Technical execution of Work-item (agents sequence)

Purpose: For each work-item type, give the agent + command sequence the operator runs inside the chat, the post-command check to confirm the result, the resume command when something fails, and the file locations where the artefacts land. This is the reference for what happens once a session is opened.

Reading time: ~12 minutes · Audience: developer / analyst operating the chat; tech lead reviewing · Authoring rules are in Work-Item Description Composition; templates are in Templates for Work-items of different types; the per-WI lifecycle from author to close is in The Lifecycle of one Work-item.

Every section below follows the same shape:

1. The arc — chat_origin → chat_development → … with the agent + command in each chat.
2. The checks per step — the verification questions the operator answers before approving.
3. What lands on disk — the artefacts and source files written by the step.
4. When something fails — the resume command and what to keep in the same chat.

Component (UI)

Arc

A simple cosmetic component can finish in one session — the analyst's placeholder is good enough to ship. The default arc is two sessions.

Sequence per step

Step 1 — Acceptance criteria. Run /swifter-frontend-analyst:generate-acceptance-criteria. The command reads the work item directly. Check that acceptance-criteria.json has 4–10 entries, each user-observable (no framework / class / endpoint references); IDs append; at least one criterion per major variant or behaviour.

Step 2 — Component spec (10 sub-steps). Run /swifter-frontend-analyst:define-component-spec. The command runs fetch-figma-data → match-figma-styles (interactive — confirm low-confidence matches) → generate-figma-html-css → refresh-framework-knowledge → placeholder component → refresh-storybook-knowledge → onboard-component (is_project_specific: true) → verify Storybook builds → report. Check that definition.md, template.html, styles.css, preview.html, mapping-used.json, component-implementation.md all exist under .swifter/specs/{module}/components/{component}/; mapping-used.json has zero pending matches; Storybook build is green.

Step 3 — Component data model. Run /swifter-frontend-analyst:work-on-component-data-model. Wait for the Approve gate. Read data_model.yaml via the work-with-data-model-toolset skill (not by raw Read on the file). Check that no entity duplicates one owned by another component in the same module; no fabricated values; the activity log captures any empty fields.

Step 4 — Component logic. Run /swifter-frontend-analyst:work-on-component-logic. Wait for the Approve gate. The command produces validation rules, display rules, and functions under the component folder. Read via the toolset skills, not raw Read. Empty categories are recorded explicitly so the developer agent knows they were considered.

Step 5 — Figma compliance review (manual). Walk the Figma node tree against the placeholder side-by-side. Flag structure / layout / sizing / typography / colour / effects / borders / icons / variants. Bring the findings to the user as a table with severity counts. Auto-fix after approval via Edit on template.html, styles.css, and mapping-used.json; never raw-edit a spec YAML.

Step 6 — Standalone logic modules. Move to a new chat (chat_development). Run /swifter-frontend-developer:work-on-component-logic <component-name> all. Wait for the Approve gate. The command writes {component}.types.{ext}, {component}.validation.{ext}, {component}.display-rules.{ext}, {component}.logic.{ext}, plus a barrel index.{ext} under the project's logic-modules directory.

Step 7 — Component implementation. Run /swifter-frontend-developer:generate-component <component-name>. Wait for the Approve gate on the HTML → onboarded-component mapping. The command writes the production component, strips redundant CSS, applies the specs, and builds Storybook. The placeholder header from Step 2 is replaced; the prop interface imports from the types file produced in Step 6.

File locations

Artefact	Path
Acceptance criteria	.swifter/specs/{module}/work-item-artefacts/{wi}/acceptance-criteria.json
Component spec	.swifter/specs/{module}/components/{component}/definition.md
Stories + MDX	.swifter/specs/{module}/components/{component}/*.stories.{ext} + *.mdx
Metadata	.swifter/specs/{module}/components/{component}/metadata.yaml
Data model	.swifter/specs/{module}/components/{component}/data_model.yaml
Logic specs	.swifter/specs/{module}/components/{component}/{validation,display,functions}_rules/
Figma cache	.swifter/cache/figma/{cache_name}.json (+ .meta.json, .style-mapping.json)
Placeholder (Step 2) and production component (Step 7)	<source-tree>/{component-source-dir}/{component-name}/
Logic modules (Step 6)	<source-tree>/{logic-modules-dir}/{component-name}/{component}.types.{ext} etc.

When something fails

Stay in the same chat. The failing command emits a resume command — paste it back verbatim. Do not open a new chat_development_02. The <source-tree> paths above are inferred from framework_knowledge.md's path aliases; if a step writes to the wrong place, the alias is the bug.

Page (UI)

Arc

The optional chat_wiring step is required when the page has multiple state slices, multiple route segments, lazy-loaded children, or paramMap-based bindings.

Sequence per step

Step 1 — Acceptance criteria. Same as the Component arc — /swifter-frontend-analyst:generate-acceptance-criteria. Page-level acceptance criteria reference page outcomes (navigation, list states, error states), not component-internal behaviour.

Step 2 — Page spec. Run /swifter-frontend-analyst:define-page-spec. The command imports the components named in the WI (it does not re-onboard them), composes them into a page, derives state bindings from the components' data models, builds Storybook stories at page level, and writes route.md describing the routing entry.

Step 3 — Page data model + logic. Same toolset commands as for components but scoped to the page — page-level entities, page-level display rules (loading / empty / error states), navigation functions.

Step 4 — Page implementation. Run /swifter-frontend-developer:generate-page <page-name>. Wait for the Approve gate. The command imports the existing component implementations, wires state, applies the page-level logic, and builds Storybook. Storybook page stories should render each declared state (empty / partial / full / error) without errors.

Step 5 — Wiring (when needed). Re-invoke /swifter-frontend-developer in a third chat named chat_wiring. The same developer agent reads the page it already built and adds the state-service wiring and the route guards / params. Do not regenerate the page in this step.

File locations

Artefact	Path
Page spec + routing	.swifter/specs/{module}/pages/{page}/page.md + route.md
Page-level Storybook	.swifter/specs/{module}/pages/{page}/*.stories.{ext}
Production page	<source-tree>/pages/{page-name}/
Routing module	<source-tree>/app.routes.{ext} (or framework-equivalent)

When something fails

Same rule as components — same chat, structured restart. If the wiring step is skipped on a page that needs it, the page renders but state across components is not wired; this surfaces as the page working on Storybook but blank under Preview. Re-invoke the developer agent in a chat_wiring chat against the existing implementation; do not regenerate the page.

Defect (UI)

Arc

Sequence per step

Step 1 — Triage. Run /swifter-default:start. The autonomous-triage agent reads the WI's Observed / Expected pair plus the Original WI link, picks the correct downstream agent (almost always the frontend developer for UI defects), and proceeds without a separate spec pass.

Step 2 — Fix. The frontend developer agent reads the page or component the defect references, reproduces it in its head, and writes the fix. The fix lives in the same component / page directory the original WI produced.

Step 3 — Storybook re-build. The developer agent rebuilds Storybook. A fix that breaks Storybook is rolled back; the developer is re-invoked with the build output.

When something fails

Do not route a defect through the analyst — the analyst writes a spec for a one-line fix, the WI inflates to 2+ sessions for no benefit. If autonomous triage routed wrong (rare), close the chat without saving artefacts and re-Start with the frontend developer explicitly selected.

FE ↔ BE Integration

Arc

Swifter has no dedicated /integrate-api command. The integration is mechanical because the same work-on-component-logic + generate-page commands are re-invoked against an existing page after the function spec is rewired to reference an API library operation.

Precondition — API library entry

Before any command runs, the consumed API must be present at .swifter/specs/{module}/api_library/{library-name}/ with _library.yaml (type: consumed, active: true configuration with baseUrl), _schemas.yaml, and one *.yaml file per operation. The library entry is imported upstream — typically as part of the backend endpoint WI's deliverables, or manually from the BE's published Swagger document. No agent command creates an API library entry.

Sequence per step

Step 1 — Inputs check. The Integration WI must carry: endpoint path, HTTP method, Swagger / OpenAPI reference, example response JSON, UI ↔ API mapping table, computed-field rules, and the name of the page-side function that switches from mock to real. If any input is missing, fix the WI before pressing Start.

Step 2 — Analyst rewires the function spec. Run /swifter-frontend-analyst:work-on-component-logic. The analyst invokes the discover-and-read-api-libraries skill, lists libraries under api_library/, asks which one to use, and updates the page's functions/functions.yaml so the target function (e.g. fetchCustomers) declares an api_dependencies block (apiLibraryName, operationId, method, path) and any response-unwrap or transformation. The page's data_model.yaml stays unchanged unless the API contract diverges from the existing domain shape. Wait for the Approve gate.

Step 3 — Developer regenerates the function module. Move to a new chat (chat_development). Run /swifter-frontend-developer:work-on-component-logic <page-name> functions (narrow scope — only the functions module is regenerated). The function's source replaces its mock-fetch with a call to the API library client and applies the unwrap.

Step 4 — Developer regenerates the page. Run /swifter-frontend-developer:generate-page <page-name>. Step 6 of the command applies the externalize-consumed-api-config skill — it scans api_library/*/ for type: consumed entries and writes a framework-appropriate example config file (.env.example for Vite, src/environments/environment.ts.example for Angular) using {{apilibrary:<name>:baseUrl}} placeholders, plus a centralized config module (src/config.ts or framework-equivalent) with fail-fast requireEnv validation. The agent never writes the real .env; the operator (or deploy pipeline) supplies the URL.

Step 5 — Operator sets the real base URL. Create the real config file (.env for Vite, src/environments/environment.ts for Angular) — both are in .gitignore — and resolve the {{apilibrary:...}} placeholder to the live BE's URL. Without this, the page fails fast at startup with the configured error message.

Step 6 — Verify under Preview. The page consumes the live endpoint. Walk every value in the mapping table (including empty / null / error states); the network panel should show requests hitting the configured base URL rather than a mock.

Step 7 — Decommission the mock. Either delete the old mock service file or relocate it to __fixtures__/ per project guidelines. The page's dependency graph must no longer reference it.

File locations

Artefact	Path
API library entry (precondition)	.swifter/specs/{module}/api_library/{library-name}/{_library.yaml, _schemas.yaml, *.yaml}
Updated function spec	.swifter/specs/{module}/components/{page-name}/functions/functions.yaml
Regenerated function module	<source-tree>/{logic-modules-dir}/{page-name}/{page-name}.logic.{ext}
Regenerated page wrapper	<source-tree>/<framework-pages-dir>/{page-name}/
Centralized config module	<source-tree>/src/config.{ext} (or framework-equivalent) — fail-fast requireEnv
Example config (committed)	.env.example (Vite) or src/environments/environment.ts.example (Angular)
Real config (gitignored, operator-owned)	.env or src/environments/environment.{ts,development.ts}
Old mock service	Relocated to <source-tree>/__fixtures__/ or deleted, per project guidelines

When something fails

Common causes:

• API library missing or operation not found — Step 2's discover-and-read-api-libraries will stop and report. Import the library entry from the BE's Swagger document, then re-run the analyst command.
• Field listed on the page but absent from the mapping table — Swifter mocks the field or skips it. Add the formula to the mapping table (e.g. Remaining = principal − paid) and re-run Step 2 in the same chat.
• Live endpoint shape disagrees with the API library schema — fix the BE WI first; do not patch functions.yaml or the mapper to absorb shape drift silently.
• Preview throws Required environment variable … is not set — Step 5 was skipped or the variable name in .env does not match the centralized config module. Match them exactly.

Backend Endpoint (new endpoint with mocked data)

Arc

The two-session arc is the default; if the developer pass fails, continue in the same chat with a structured restart. Do not open developer_run_02.

Sequence per step

Step 1 — Scoped specifications. Run /swifter-backend-analyst:generate-scoped-specifications. The agent reads the WI's endpoint description, the domain model (Entity block in the WI), the enum definitions, and the source-file mapping. It produces a scoped specification (DTO + controller signature + service signature + repository signature) under .swifter/specs/{module}/endpoints/{endpoint}/. Approve before proceeding.

Step 2 — Implementation. Run /swifter-backend-developer:implement-scoped-changes. The agent reads the scoped specifications and the overview/ guidelines (STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, CODING_GUIDELINES, all 7 NFRs, PITFALLS) — every "How" entry in CODING_GUIDELINES.md is a binding rule. The developer writes the controller, service, DTO, mapper, and wires the mock-data file from the source-file mapping.

Step 3 — Build + verify. The developer runs the project build. Red gates trigger up to three auto-fix attempts. If still red after the third, the agent stops and surfaces the error.

File locations

Artefact	Path
Scoped specification	.swifter/specs/{module}/endpoints/{endpoint}/specification.yaml
Controller	<source-tree>/{controller-package}/{Endpoint}Controller.{ext}
Service	<source-tree>/{service-package}/{Endpoint}Service.{ext}
DTO + mapper	<source-tree>/{dto-package}/{Endpoint}DTO.{ext} + {Endpoint}Mapper.{ext}
Mock-data files	<source-tree>/{mocks-package}/{entity}.json (per the WI's source-file mapping)

When something fails

Stay in chat_developer_run_01. A structured restart message includes: what was attempted, what specifically failed (file + gate + error message), what changed (refined WI? updated spec?), and the explicit ask ("continue from current branch state, fix the failing test in XService.spec.ts, do not regenerate the controller"). Opening chat_developer_run_02 resets the agent's branch state and produces compounding failures.

Backend Architecture Guidelines

Arc

Sequence per step

Step 1 — Scan + analysis. The architect scans the codebase, reads any existing overview/ files, classifies NFR coverage (detected / partial / not detected), and scans for the 8 mandatory principles (followed / violated / not detected). No files are written yet.

Step 2 — 6-step user gate (AskUserQuestion). The architect presents the analysis and asks: architecture approach, codebase locations, suggestions, pitfall mitigations, NFR scope, mandatory principles. This is the primary place the team shapes content. Answer thoughtfully; the gate's output goes into every file the architect writes.

Step 3 — Write 16 files. The architect writes STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS, PITFALLS, CODING_GUIDELINES, plus 7 NFR files at overview/nfr/ — to strict line budgets and prescribed structures. The 8 core files are then hand-editable between runs; the others are best amended via the gate.

File locations

Artefact	Path
8 core overview files	.swifter/specs/{module}/overview/{STACK,STRUCTURE,ARCHITECTURE,CONVENTIONS,TESTING,INTEGRATIONS,CONCERNS,PITFALLS}.md
Coding rules	.swifter/specs/{module}/overview/CODING_GUIDELINES.md
NFR files	.swifter/specs/{module}/overview/nfr/NFR_*.md (7 files)

When something fails

Re-running /swifter-backend-architect:create-guidelines is safe — it reads existing files, runs the gate again, then rewrites. User edits inside loose-table formats survive; edits to rigid files (CODING_GUIDELINES, NFRs) may not — re-shape those via the gate.

Sync / Maintenance (UI)

Arc

Sequence per step

Step 1 — Choose the right command. sync-component-specs is for drift detection — source has changed since the last spec write. import-component-specs is for onboarding existing source code into Swifter spec coverage for the first time; it takes a glob argument (src/**/*.tsx) or a directory.

Step 2 — Run + review. The agent walks the source tree, diffs against existing specs, and updates the specs in place. For import-component-specs, it generates new specs for components it finds that have all required props with types.

Step 3 — Verify. Check that metadata.yaml for each affected component has been written via the toolset; the source tree (<source-tree>/) was not touched (sync writes only to .swifter/).

File locations

Artefact	Path
Updated component specs	.swifter/specs/{module}/components/{component}/*
Sync head pointer	.swifter/specs/{module}/components/SYNC_HEAD (records the last-synced commit)

When something fails

Sync is the canonical no-touch pattern — the WI description is title-only. Adding hints creates extra surface for misinterpretation and is the most common cause of a sync session abandoning. If the description has hints, strip them and re-run.

QA Acceptance Criteria + Test cases + Test scripts

Arc

Sequence per step

Step 1 — Acceptance criteria. Run /swifter-frontend-analyst:generate-acceptance-criteria. Numbered, user-observable assertions. Each AC has a unique ID; the file appends to existing IDs on re-run.

Step 2 — Test cases. Switch to swifter-tester. Run /swifter-tester:generate-test-cases. The agent reads the acceptance criteria, the module's overview/ (STACK / STRUCTURE / ARCHITECTURE / CONVENTIONS / TESTING / INTEGRATIONS / CONCERNS), the page or component specs, and every file in .swifter/knowledgebase/ if any exist. It plans 2–4 cases per AC at a 2:1–3:1 positive:negative ratio and writes them as YAML.

Step 3 — Test scripts. Run /swifter-tester:generate-test-scripts. The agent reads the test cases, runs live DOM exploration against a running preview (or staging URL), and writes Playwright scripts. Selector priority: generated locator from browser_generate_locator → data-testid → role-based → text → CSS. App-specific testing patterns from the knowledgebase are applied throughout.

Step 4 — Run. Execute the scripts against the preview URL. Iterate on failures — fix the script or fix the prompt that produced it. If the underlying WI changes, regenerate cases and scripts.

File locations

Artefact	Path
Acceptance criteria	.swifter/specs/{module}/work-item-artefacts/{wi}/acceptance-criteria.json
Test cases (YAML)	.swifter/tests/{module}/test-cases/test-cases-{wi}.yaml
Playwright scripts	.swifter/tests/{module}/test-scripts/{wi}/*.spec.{ext}
Knowledgebase (input, user-curated)	.swifter/knowledgebase/*.md
Test runs (per run output)	.swifter/tests/{module}/test-runs/{run-id}/

When something fails

If the tester generates wrong selectors repeatedly for the same control, add the convention to .swifter/knowledgebase/{topic}.md — the next run will read it and apply it. If the test cases are wrong, fix the acceptance criteria; the test cases are downstream.

Routing — same-chat continuation rule

Across every arc above, the rule is the same: when a step fails, continue in the same chat with a structured restart. Opening a new chat (developer_run_02, wiring_02, etc.) loses the prior session's branch state and conversation context, and produces compounding failures. The strongest contraindication observed in production engagement data was a backend WI that accumulated developer_run_02 through developer_run_05 chats and never reached Done; the same WI was salvaged by reopening the original chat with a structured restart.

A structured restart message has four lines:

What was attempted: <one sentence>.
What failed: <file name + gate name + error message>. Paste the error verbatim.
What changed: <refined WI? updated spec? new contract?>.
Ask: <"continue from current branch state, fix the failing test in XService.spec.ts, do not regenerate the controller">.