Skip to main content

Application Build Sequence

BE Preparations (once per Project)​

  1. Backend Guidelines WI — runs once per project before any implementation WI; swifter-backend-architect:create-guidelines. Without it, the backend stream stalls.
  2. Data Model WI — define the entity and its attributes in Swifter. The data-model toolset is the only sanctioned way to mutate the artefact. If the Database is present in the Project — the implementation includes the Database and Entities setup as well.

No frontend counterpart is needed: frontend modules do not consume architect-generated guidelines — the two FE knowledge caches (framework_knowledge.md, storybook_knowledge.md) are auto-refreshed by the analyst's refresh-framework-knowledge / refresh-storybook-knowledge skills on the first frontend command (see Project Guidelines).

Purpose: Specify the order in which frontend and backend artefacts are created for a new application so dependencies resolve cleanly and parallelism is safe.

End-to-End Order​

API contract first, then the validation contract; the BE implementation then proceeds in parallel with the frontend stream (components, page, FE implementation on mocked data); integration is its own work item; E2E tests close the loop. The nine-step canonical order for a new feature that touches a page and an API:

  1. API Contract WI — derive OpenAPI / Swagger from the data model.
    • Include examples of JSON request/response.
    • Define the specific response-code handling where an endpoint deviates from the defaults; the default response-code handling is defined once in the Backend Guidelines.
  2. Reusable validation Contract WI — define commonly used validation rules.
  3. External API's integration WI — define the external API's integrations if present (see Backend Stream for the minimum payload).
  4. BE implementation WI — BE implementation.
  5. Component WI (×N) — one per reusable block, sourced from Figma.
  6. Page WI — the page specification: compose the components, wire breadcrumbs and routing, define the UI ↔ endpoint mapping table.
  7. FE implementation WI — the full page implementation on mocked data: state binding, the endpoint response → UI mappings, the validations. Everything except the real endpoint API call — the returned data is mocked, sourced from the contract's JSON request/response examples.
  8. Integration WI — replace the mocked data with the real endpoint API call plus a DTO ↔ domain mapper.
  9. E2E Test WI — Playwright suite mapped to the acceptance criteria. A closing phase rather than a single work item — it expands into the work items listed in E2E Test as the Closing Step.

Each step is a separate work item. Bundling two of them collapses the spec-review checkpoint between them and is the most common cause of the Origin → ABANDONED pattern — the agent's spec addresses only part of the bundled description, the reviewer abandons the session, and the cycle repeats (see Work Item Composition).

Backend Stream​

Backend stream is API contract → Reusable validation Contract → External API's integration → BE implementation. The detailed sub-order:

  • API Contract WI — produces the OpenAPI document attached to the project, including the JSON request/response examples and any endpoint-specific response-code handling (defaults come from the Backend Guidelines).
  • Reusable validation Contract WI — produces the BE validation schema for the given contract.
  • External API's integration WI — produces the external API's integrations. The work item's minimum payload:
    • The external contract (the external OpenAPI document).
    • Base URL, path, HTTP method, and the path / query / header parameters.
    • Request/response parameter and attribute log-masking definitions.
    • Response-code processing.
  • BE implementation WI — swifter-backend-analyst:generate-scoped-specifications followed by swifter-backend-developer:implement-scoped-changes in the same chat.
    • In case of Database based Project the Mock data can be introduced for the DEV or Preview environments.
    • In case of External API proxy Project the Mock data should be retrieved from the DEV External API's or the internal Mock Server setup can be considered.

If the Database is present in the project, the connection parameters are defined in the initial project setup scope and then only changed per environment via environment variables — no dedicated work item is needed.

Frontend Stream​

Frontend stream is component work items from Figma → page work item composing components → FE implementation on mocked data matching the contract; component before page is a hard rule. The Reusable validation Contract WI (step 2) is a shared input to this stream — a single work item producing both the FE and BE validation schemas, not a separate FE-side step. The detailed sub-order:

  • Component WI (per component) — swifter-frontend-analyst:define-component-spec followed by swifter-frontend-developer:generate-component. The component is published to Storybook as a placeholder and then rewritten in production code.
  • Page WI — swifter-frontend-analyst:define-page-spec followed by swifter-frontend-developer:generate-page. The page composes the components, sets breadcrumbs and routing.
    • Includes a mapping table — UI element → endpoint → response field → transformation — that covers every visible value on the page, including computed columns.
  • FE implementation WI — the full page implementation: state binding, the endpoint response → UI mappings from the mapping table, and the validations from the validation contract. The returned data is mocked and matches the contract (the JSON request/response examples from the API Contract WI); the implementation does not include the real endpoint API call — that is delivered in the dedicated Integration WI.

Building a page before its components exist is an anti-pattern: the analyst has no sibling references to lean on, and the spec drifts.

Parallelism Window​

Once both the API and validation contracts are fixed, FE and BE proceed in parallel — FE on mocked data matching the contract, BE on the real implementation; they meet at the Integration WI. The parallelism is not a side effect of the structure; it is the structure's reason for existing. The contract is the joint of which both streams are independently moveable parts. They converge at the Integration WI, where the mocked data is swapped for the real API client.

The window closes if either stream changes the contract without amending the other side's input. Treat the contract as a write-once artefact; if it must change, do it in a dedicated Contract Change WI that fans out to both streams.

Integration as a Separate WI​

Integration is its own work item — never bundled into the FE implementation work item — with the FE implementation WI link, Swagger reference, and UI-to-API mapping table as inputs. The integration work item's minimum payload:

  • A link to the FE implementation WI that produced the mock-based page.
  • The endpoint path and HTTP method.
  • The Swagger / OpenAPI reference for the endpoint.
  • An example JSON response.
  • The UI-to-API mapping table from the Page WI.

The developer agent reads existing state and service code on the frontend, generates the API client from Swagger, creates the DTO ↔ domain mapper, and replaces the mocked data with the real endpoint call.

E2E Test as the Closing Step​

E2E test work items run Playwright against acceptance criteria as the closing step of a feature; QA-WI authoring is excellent on the pilot but the QA-generation skill remains the bottleneck. The closing-step order:

  1. Acceptance Criteria WI — swifter-frontend-analyst:generate-acceptance-criteria produces numbered, testable assertions tied to the page spec.
  2. Test Cases WI — swifter-tester:generate-test-cases expands the criteria into named test cases.
  3. Test Scripts WI — swifter-tester:generate-test-scripts produces Playwright scripts that exercise the page through its preview.
  4. Test Run — execute the scripts against the preview (or the deployed environment) and iterate on the failures.

The tester agent is newer than the frontend / backend agents and its capabilities are still ramping; expect intervention to be higher in early test work items even when the criteria are excellent. Invest in the tester skill, not in rewriting the criteria — the criteria are already the most polished artefacts in the pilot dataset.