Swifter — Intro
Purpose: Give a developer, QA, or business analyst seeing Swifter for the first time a full working mental model of what the platform is and how delivery runs on it — enough to then go read the detail in the rest of this User Guide. Watch the embedded video; the written script below is the same content for reference.
This intro is in four parts:
- Overview — what Swifter is, in one factory metaphor.
- Principles — the six ideas that make delivery on Swifter stable, repeatable, and auditable.
- Interface — four short narrated walkthroughs of the real product, from first project to a merged pull request.
- Tour — one end-to-end build of a real screen, start to finish.
You will not become an expert from this intro. You will finish it knowing where every piece lives and why it is shaped the way it is — ready to learn the rest.
1 · Overview — Swifter is a software-development factory
Think of Swifter as a software-development factory. Not a chat window where one person prompts an LLM until something compiles — a factory, with a fixed production line, specialised stations, and a record of everything that passed through.
Three things make it a factory rather than a workshop:
- Every proficiency works across the whole SDLC. Business analysts, frontend and backend developers, QA, and an architect are all on the team and all present on the platform — but they now do their work through Swifter instead of by hand. The proficiencies don't disappear; the work shifts from typing code to writing specifications, reviewing agent output, and tuning the rules the agents follow.
- They all work with agents. Each proficiency pairs with a specialised Swifter agent — a frontend analyst and a backend analyst, a frontend developer and a backend developer, a backend-architect, and a tester — plus an autonomous triage agent that routes a new work item to the right one. Each agent owns one narrow proficiency. The human directs and reviews; the agent executes. An analyst agent produces specs, never production code. A developer agent writes code from those specs, never invents requirements. The tester turns acceptance criteria into runnable Playwright scripts.
- The platform enforces one opinionated, governed process. There is exactly one way work flows: requirements → specifications → design → development → testing → pull request → merge. The same sequence runs for every work item. That single enforced shape is what makes delivery stable (the same input produces the same output), repeatable (the team learns the flow once), and auditable (every artefact traces back to the work item, the agent, and the workflow that produced it).
This is the opposite of "vibe coding." Ad-hoc LLM use gives a different result every time the prompt is rewritten, leaves no spec for the next person to read, and bypasses the conventions and integrations real delivery needs. Swifter replaces that with five hard principles: spec-driven (the spec is the contract, code is generated from it), multi-proficiency agentic SDLC (a sequence of narrow agents, not one mega-prompt), verification loops (every output is checked against a checklist; failures retry or escalate), work-item-scoped sandboxes (each work item runs on its own Git branch — experiments are cheap, rollbacks trivial), and artefact lineage (audit is a first-class data stream, not an afterthought).
That is the whole platform in one screen. The rest of this intro is the production line in detail.
2 · Principles
Six principles — the work item, the agents, the build sequence, the lifecycle, the guidelines, and monitoring. Each is one idea you need before the line makes sense, and they build on each other in that order; composing and splitting a work item (2.4) is the craft of the first principle, returned to once the build sequence shows why it matters.
2.1 · The work item is the basic building block
Everything on Swifter is a work item — the unit that flows down the production line. A work item is small on purpose: it must fit in an agent's context window and finish in one or two sessions.
Work items form a tree. A head work item carries the feature-level context — the whole-screen Figma link, the requirements-document reference, the cross-cutting scope. It is never assigned to an agent; it is a parent and a reference container. Its children are the atomic units that actually get built: one component, one page, one integration, one defect. When a reviewer needs the wider picture, they walk up to the head; when they need to execute, they stay in the child.
That is the unit of work. But a work item doesn't build itself — it is handed to a specialist. So let's meet who does the work.
2.2 · Agents — variety, and how you work with them
Swifter is not one AI. It is a set of specialised agents, each carrying one human proficiency. The point is separation: each agent has a single narrow goal, so the human reviewer always knows exactly where to look for which kind of mistake.
| Human proficiency | What the human does | What the agent does |
|---|---|---|
| 👤 Business analyst | Authors the work item; signs off on acceptance criteria | — (analyst agents read the work item) |
| 👤 Frontend / backend analyst | Reviews the generated spec; refines the work item when the spec drifts | 🤖 Produces specs — data model, logic rules, API contract, Storybook stories — no production code |
| 👤 Frontend / backend developer | Reviews the implementation against the spec; merges the PR | 🤖 Writes production code from the spec + project guidelines |
| 👤 Tech lead / architect | Shapes the project guidelines; amends conventions as patterns emerge | 🤖 Scans the codebase; produces the per-module guideline files |
| 👤 QA tester | Reviews acceptance criteria and failing scripts | 🤖 Generates test cases and Playwright scripts; runs them |
| 👤 Designer | Maintains the design in Figma | 🤖 (the frontend analyst agent reads Figma frames directly) |
Those are the proficiencies. The way you work with every one of them is the same three-beat move — so here is that loop. You don't memorise a roster. You learn the principle: a human instructs and reviews at decision points; the agent does the heavy lifting in between. The few agents you'll touch first are the frontend analyst (specs from Figma), the frontend / backend developer (code from specs), and the autonomous triage agent (start), which reads a new work item and routes it to the right specialist for you.
This separation is the first reason the factory produces predictable software where a single mega-prompt cannot: the analyst never writes code, the developer never invents requirements, the tester never writes implementation. Every step has one job.
Now you know the players and the loop. Point them at a whole application, and they run in a fixed order.
2.3 · The application build sequence
When you build a new feature that touches a screen and an API, the artefacts are created in a fixed order so dependencies resolve cleanly:
Data model first, then the API contract derived from it. Once the contract is fixed, frontend and backend build in parallel — the frontend against a mock service whose shape matches the contract, the backend against in-memory mocks — and they converge at a dedicated Integration work item that swaps the mock for the real API. E2E tests close the loop.
Each step is its own work item. The contract is the joint that lets both streams move independently; treat it as write-once, and if it must change, do it in one Contract-Change work item that fans out to both sides. Bundling two steps into one work item collapses the review checkpoint between them and is the most common cause of an abandoned session.
That sequence only stays clean if each box in it — each work item — is written so an agent can execute it on first read. Which returns us to the craft of the first principle: how you compose, and size, a single work item.
2.4 · Composing and splitting a work item
Every box in that build sequence is a single work item — so how do you write one an agent can execute on first read? A work-item description is a brief for an agent, not a story for a person, and five composition principles make it well-formed. One — agents read literally: quote anything that must appear verbatim — button labels (Button label: "Process Amortization"), enum values (Type — one of: A, B, C, D, E), tooltip text — and never write "as per design," because the agent has no interpreter to resolve a vague phrase against the Figma. Two — state scope OUT explicitly: the single highest-leverage line in a work item is X is out of scope; use mocked data, because without it Swifter helpfully builds adjacent functionality it sees mentioned anywhere in the Figma or BRD. Three — name a sibling when one exists: "use the approach and patterns of <sibling page / component / endpoint>" lets the agent inherit shape decisions from work it already has in context — for free; omit the line entirely when no suitable sibling exists rather than adding a "none" placeholder. Four — conditional logic as IF/THEN, never prose: write IF <condition> THEN <element/state> with literal quoted tooltip text, so each rule is independently parseable and checkable against acceptance criteria. Five — one scope per WI: if the description says "and also," it is two work items. A sixth, optional Implementation Hints section carries non-functional / workaround / architectural-pin nudges below the body — treat it as temporary, since the platform absorbs recurring hints over time. Work items score on Specificity, Completeness, and Clarity (1–3 each; 7–9 excellent), and a 3–4 score is acceptable only for sync items.
That fifth rule — one scope per item — raises the obvious question: when do you split? When a description starts saying "and also," split it. When a page has independent widgets at different refresh cadences, split. When work crosses frontend and backend, always split. A well-sized work item finishes in 1–2 sessions; one that runs into a third or fourth session is mis-sized — stop and split. The cautionary tale from a real pilot: a single API spread across nine attempt-2, attempt-3 work items because the input data kept changing — when a work item fails for an input reason, fix the input and rerun in place; only spawn a new work item when the scope itself is wrong.
Why this matters to you: the size and shape of a work item is the single biggest lever on whether the agent gets it right on the first run. Two small, sharp work items beat one ambiguous one every time.
Once a work item is well-composed and right-sized, it travels the same seven-step path every time, through two quality gates.
2.5 · Work-item lifecycle and a technical example
Every work item — whatever its type — moves through the same seven-step lifecycle, with two gates that catch problems while they're still cheap:
The two gates are the whole point. Step 2 — tech lead validates catches scope and dependency problems before an agent burns a session on a half-ready work item. Step 4 — the BA compares the generated spec to expectation: roughly 90% match ships to development; less sends the work item back for a refine. A wrong spec produces wrong code — catching it here costs minutes; catching it after implementation costs a session.
That is the lifecycle in the abstract. Here is what it looks like run once, end to end, on a real backend endpoint. The arc is two sessions:
generate-scoped-specifications(backend analyst) reads the endpoint description and produces a scoped spec — DTO, controller signature, service signature — no code yet. You approve.implement-scoped-changes(backend developer) reads that spec plus the project guidelines and writes the controller, service, DTO, mapper, and wires the mock data. It runs the build; red gates trigger up to three auto-fix attempts before it stops and surfaces the error.
A frontend component or page follows the same analyst-then-developer shape; a defect skips the spec pass and routes straight to the developer through triage. One rule holds across every type: when a step fails, continue in the same chat with a structured restart — never open a fresh chat. A new chat throws away the session's branch state and conversation, and produces compounding failures. The work-item type templates (paste-and-fill descriptions for Component, Page, Defect, Integration, Backend Endpoint, and more) are what make the input correct on the first read.
Notice that the developer leaned on two shared sources of truth the team owns — the project guidelines, and the design system.
2.6 · Guidelines and the design system
Two inputs shape what the agents produce, every single run.
Project guidelines are per-module files (STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, PITFALLS, and more) that pin the team's stack, conventions, forbidden patterns, and known anti-patterns. The architect agent generates them through a six-step interactive gate on the first run; after that the team hand-edits them as patterns emerge. The principle to hold onto: guidelines are inputs, not documentation. They are read by the agent on every generation — so a team that keeps them current sees convergence (the same imports, the same error-handling block in every file), and a team that treats them as a read-once doc sees drift.
The design system is Figma as the single source of truth. UI work items link to a specific frame, never the whole file, and never a prose paragraph describing the design — the analyst trusts the link and ignores the prose. The frontend analyst reads the Figma frame, matches its styles to the project's design tokens, and produces a faithful HTML/CSS preview plus a placeholder component and a spec. The developer agent then rewrites that placeholder as production code using the project's component library. Visual rules that can't live in Figma — a conditional display, a tooltip — go into the work item as explicit IF/THEN rules with literal quoted text, not as freeform prose.
And once all of this is running, you watch two things: is the team adopting it, and when do you step in by hand.
2.7 · Monitoring
Once the team is delivering real work, Swifter's analytics pipeline computes a small, stable set of efficiency metrics per work item. The Engagement Lead watches four:
automation_ratio— the adoption signal: the share of a PR's code actually authored by the agent (not by hand). Read it as a trend, not a snapshot — is the project-level average climbing as the team learns the platform?manual_intervention— how much message-by-message human nudging a work item needed beyond its initial description. In practice this stays low — a small share of the total work — and it's read as a trend, not a target.verification_pass_rate— how clean the agent's output was on the first run, before any retry.code_churn_ratio— whether the change volume was proportionate to the stated scope.
The headline use is to tell "is delivery genuinely agent-driven?" (adoption) from "is the output any good, and where is the human still steering?" (the other three). When intervention rises while description quality stays high, that's a platform/skill issue to escalate — not a reason to rewrite already-good work items. This is also where manual intervention is expected and healthy: the human stays in the loop at the decision points, and the metrics simply make that loop visible.
3 · Interface — four walkthroughs of the real product
The four short videos below walk the actual Swifter UI, in the order you'll use it: set up a project, fill the backlog, ship a backend work item to a pull request, then a frontend one. Each is preceded by a short "what you'll see here."
Chapter 3.1 · First project and work items
What you'll see here: Swifter keeps your whole delivery flow in one place — from organisation setup, to creating a project, to a ready backlog. At the organisation level you configure integrations once — issue tracking (Azure DevOps, Jira), version control, and design systems — as reusable assets every new project inherits. You'll watch a new project, DemoCRM, get created and linked to its tracker, repository, and design system; see how a frontend module's stack and repository strategy are chosen; and see that Swifter supports both greenfield and brownfield (start from a template, connect an existing repo, or map a monorepo folder). The project opens straight to its backlog, where work items can be created directly or synced from the tracker.
(▶ Interface video 1 — First project and work items)
Chapter 3.2 · Populate the backlog
What you'll see here: how the backlog fills up. Sync with Issue Tracker pulls work items from Azure DevOps or Jira by the project's query — your backlog grows without copying issues by hand. You'll also watch the Create Work Item dialog, which gathers everything Swifter needs in one place: the type (generic, component, page, defect) that sets the shape of the work; the module (frontend, backend, testing) that decides which agents and tabs apply; the parent that nests it in the tree; the title, description, and an optional Figma design URL so agents can follow the intended visuals. You'll see the new item land under its parent in the hierarchy, and see Start — the action that opens a work session and unlocks agent chat plus the app/dev/test tabs.
(▶ Interface video 2 — Populate backlog)
Chapter 3.3 · Backend — work item → specs → code → PR
What you'll see here: a full backend delivery inside a real workspace. One umbrella feature groups related work, and its children can sit at different lifecycle stages at once — that's intentional. You'll see Start create the session and its branch and connect agent chat to the item; then the backend analyst run generate specifications to translate the work item into concrete specs — behaviour, contracts, constraints. Next the backend developer runs implement changes against the repository, applying edits and running checks. You'll review the produced artefacts in-product — the DTO in app, the generated function and validation in logic, the HTTP contract in the API library, and the raw source on the session branch in dev — then create pull request, check its status against the Git host, and complete the merge. The work item moves to done.
(▶ Interface video 3 — Backend work item → specs → code → PR)
Chapter 3.4 · Frontend — work item → PR
What you'll see here: the same shape, for the frontend. A parent feature groups UI work; child component items sit at different lifecycle stages. After Start, Swifter prompts you to pick who works the item next — for a new component with no specs yet, the frontend analyst is recommended (analysis before implementation, as the SDLC guidance prescribes). The analyst defines the component specification from the work item and design inputs; you'll review the generated component stories and their states (empty, partial, full) in the embedded Storybook. Then the frontend developer generates the component implementation from those spec artefacts, applying the module's framework patterns. You'll skim the generated templates, styles, and wiring on the session branch in dev, then create pull request, check its review/CI status, and complete the merge to main. The item moves to done, and the backlog tree reflects it.
(▶ Interface video 4 — Frontend work item → PR)
4 · Tour — building one real screen, end to end
To close, watch a single feature built from nothing, in dependency order — the Frontend Screen Video Guide. It builds a real component (workitem content tabs) and then a page that composes it (workitems list), on an Angular frontend module, narrated step by step.
This Tour ties together everything above: the work item as the unit, the analyst-then-developer arc, Figma as the source of truth, the spec-before-code discipline, and the controlled pull request to close. It is the principles of this intro, executed once, on screen — so you finish with the full mental model: a factory where every proficiency works across the SDLC, all working with agents, on one enforced process.
(▶ Tour video — Frontend Screen Video Guide: create a component (workitem content tabs), then a page (workitems list). Produced by the sibling dpb-video mission — all 18 steps stitched end-to-end (~8 min), narrated throughout.)
Where to go next: the rest of this User Guide is the detail — the delivery guide (work-item composition, type templates, technical execution), the project guidelines and design-system pages, and the journey walkthroughs. You now have the map; go read the territory.