# monday.com Item Creation

## Objective

Create monday.com items from app records with board columns populated correctly.

A connected monday.com account, a per-board column mapping, and a background job that creates items from selected app records.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Identify the app records that correspond to work someone tracks on a board, and let an administrator choose the source records and the destination board rather than mirroring the whole database.
2. Hold the connection at the workspace level with tokens stored server-side only, refresh them ahead of expiry, and put the integration into a clearly labelled re-authorisation state when refresh fails rather than failing each item silently.
3. Read the destination board's columns at configuration time and store the mapping against each column's stable identifier and declared type. Do not match columns by their visible titles, which are renamed constantly and are not unique.
4. Build each column's value according to its type before sending: people, status, date, relation, and file columns each expect their own shape, and a plain string in any of them is rejected or silently ignored.
5. This entry owns creation only. If the app also has a brief for syncing status back from the board, that brief owns the inbound direction and the change-detection loop, and neither side should write a field the other side also writes.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Column identifiers are stable and column titles are not. A mapping stored against a title breaks the first time someone renames a column, usually without any error, so resolve and persist identifiers instead.
- A board or a mapped column can be deleted or archived between configuration and send. Detect the missing target, pause the mapping, and tell an administrator which column disappeared rather than dropping the value.
- People columns need account members, status columns need one of that board's defined labels, date columns need an unambiguous date, relation columns need an existing item, and file columns need an upload step. Any of these sent as loose text will fail or land empty.
- A retry after a timeout will create a second item unless creation is guarded. Derive a stable key from the source record, store the created item identifier, and reconcile before sending.
- Item creation must stay inside the connected account and the chosen board. A misconfigured mapping must never be able to write into a board the connection was not granted, and the destination picker should only ever list what the connection can reach.
- Bursts of records will hit the provider's rate limit and its query complexity ceilings. Queue sends, back off on the provider's signal, and spread a bulk import over time rather than firing it in one pass.
- When monday.com is down the user's action in the app must still complete. Show the item as pending, retry in the background, and make a permanently failed send visible on the source record.
- Long text, formatting, and attachments do not survive intact. Decide what is truncated and what is linked back to the app, rather than assuming the full record fits in a column.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Column mappings are stored by column identifier and type, and survive a column being renamed.
- [ ] Each column type receives a correctly shaped value, verified against people, status, date, relation, and file columns.
- [ ] A deleted or archived board or column pauses the mapping and notifies an administrator instead of failing silently.
- [ ] Repeated or retried sends produce exactly one item per source record.
- [ ] Creation is scoped to the connected account and the selected board and cannot write elsewhere.
- [ ] Rate limits and outages degrade to a queued pending state with visible failures, not lost records.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.