Journey 1 — Setting Up the Swifter Project

Purpose: The team's first hour inside the Swifter platform — from "Setup is complete" to "the first Work Item is ready to start". A narrative walkthrough on a worked example: a small CRM with one screen and one endpoint.

Reading time: ~8 minutes · Audience: anyone running through the first session on a new engagement · You should not start any Work Item until you've reached the end of this journey.

The worked example

We will use a deliberately small example throughout this journey: a CRM project with two modules and one early screen.

Aspect	Value
Project name	acme-crm
Modules	crm-fe (Frontend, React) · crm-be (Backend, Spring Boot)
First screen	Customers list — a table of customer rows with name / status / last-payment columns
First endpoint	GET /api/customers returning the list
Engagement shape	Customer-Led — client team being onboarded

The screens, names, and frameworks will of course differ on your engagement. The shape of the journey is what stays constant.

What "Setup complete" means

Before you start this journey, the following are already in place from the Setup section:

• The Swifter organisation exists; the team is provisioned with SSO.
• The deployment variant is decided and recorded (SaaS or Self-Hosted).
• The Git provider, issue tracker, and Figma integrations are wired at the organisation level.
• The development-process working agreements (FE-BE contract discipline, SCRUM cadence) are written down.
• A seed backlog of work items exists in the issue tracker.

You do not run this journey if any of those is missing. The Setup section's environment readiness checklist is the gate.

The journey at a glance

Each step is 5–15 minutes for a small project. The whole journey is one session, end to end.

Step 1 — Open Home, create the project

Sign in to the Swifter platform. You land on Home, which lists projects in your current organisation. The header carries the organisation switcher (only visible if you belong to more than one organisation) and the gear icon for Settings.

If your engagement is new, the projects list is empty. Click Create new project.

The dialog has three logical groups. Fill them in:

1. Identity and integrations. Project name: acme-crm. Pick the version-control integration (your Git host), the issue-tracker integration (Azure DevOps / Jira), and the design-system integration (Figma). All three are required, all three were configured at the organisation level during Setup, so you are just selecting from a list.
2. Modules. You will add two modules — see step 2.
3. Advanced options. Leave the work-item-query predicate empty for now; sync will use the tracker's default.

Common mistake. If any of the three integrations is missing in its dropdown, an organisation admin has not configured it. Stop here and ask them to add it under Settings → Integrations. Do not press Create — the project would not start cleanly.

Step 2 — Add modules — crm-fe and crm-be

Inside the Create-new-project dialog, click Create new module. The sub-dialog asks for:

Field	crm-fe value	crm-be value
Module name	crm-fe	crm-be
Module type	Frontend	Backend
Framework	React (or your team's choice)	Spring Boot (or your team's choice)
Package manager	Yarn	Maven
Use existing repository	Off (greenfield) — or on, if brownfield	Off — or on, if brownfield
Monorepo	Off (separate repos for FE and BE)	Off

Add both modules before submitting. Module type is the field that decides which tabs (App / Dev / Test) appear after Start on any work item assigned to that module — getting it right here saves rework later.

Brownfield case. If a module points at an existing repository, turn on Use existing repository and enter the URL. The Backend Architect scan in step 5 will then run against your actual codebase.

Click Create new project. Swifter takes you to the Workspace.

Step 3 — Connect repositories and the design system

If your modules are greenfield (the default), Swifter has just cloned its built-in templates into your Git host. Open the Reqs tab, then the project Settings → General, and confirm the repository URLs were assigned. For brownfield modules, confirm the repository URL is the one you supplied.

For Figma — open Settings → Integrations and verify the Figma integration is connected. A team member with Figma edit access must authorise it. Test by pasting a Figma frame URL into agent chat later; for now, just confirm the workspace and file key are recorded.

Branch policies. Swifter creates a dedicated branch per work-item session (e.g. swifter/wi-1234-customer-list). Your Git host's branch policies must allow branch creation by the integration user and PR creation from swifter/* into main. If the team has not adjusted policies yet, do that now — branch creation failures are the most common Day-3 blocker.

Step 4 — Sync the backlog from the issue tracker

Open the Reqs tab and click Sync with issue tracker. Work items appear from your tracker (Azure DevOps Boards or Jira) into the project's backlog.

Sync is one-way — tracker into Swifter. Edits made in the tracker after sync need another Sync click; Swifter never writes back to the tracker.

For acme-crm, the synced items might include:

• WI-1001 Customers list — read-only table (FE)
• WI-1002 GET /api/customers endpoint (BE)
• WI-1003 Customer detail screen (FE)

The team picked WI-1001 as the demo work item — small, well-defined, real backlog item with a clean Figma frame and an explicit scope-out.

Filter the sync. If the tracker has hundreds of items, set the work-item-query predicate in project Settings → General (WIQL WHERE for Azure DevOps, JQL for Jira) to limit which items come across. Otherwise the Reqs tab becomes noisy.

Step 5 — Generate backend guidelines

If you have a backend module — and the worked example does — generate the per-module guidelines before any backend implementation Work Item opens. Skipping this is the empirically-documented quality cliff: production engagement data shows zero implementation WIs completing until the backend guidelines exist.

Open a session against any work item in the backend module, switch the agent picker to Backend Architect, and run /swifter-backend-architect:create-guidelines.

The agent runs a 6-step user gate via AskUserQuestion:

1. Architecture approach (confirm or suggest alternative).
2. Codebase locations (confirm where domain / data / services / repositories / controllers / shared modules live).
3. Suggestions or adjustments.
4. Pitfall mitigations.
5. NFR scope confirmation (which of the 7 non-functional categories are in scope).
6. Mandatory principles confirmation.

Answer each thoughtfully — this is the primary moment the team shapes content. The architect then writes 16 files under .swifter/specs/crm-be/overview/:

• 8 core files: STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, TESTING.md, INTEGRATIONS.md, CONCERNS.md, PITFALLS.md.
• 1 capstone: CODING_GUIDELINES.md.
• 7 NFR files at overview/nfr/.

Open the Dev tab; you should see the new files on the session branch. Read STACK.md and CONVENTIONS.md end-to-end before approving the PR — the eight core files are easy to amend, but mistakes here propagate into every subsequent backend Work Item.

Merge the architect's PR to main. The guidelines are now in the project repository and every future backend session will read them.

For frontend modules — no architect run needed. Frontend agents do not read the 16-file set. They only need framework_knowledge.md and storybook_knowledge.md, both auto-generated on the first frontend analyst session (step 7 below).

Step 6 — Open the first work item — press Start

Back in the Reqs tab, click WI-1001. Confirm the work item:

• Has a clear title (Customers list — read-only table) and a Type set to Page.
• Has a user story and any conditional logic (IF <condition> THEN <element / state>) written out — the analyst will derive acceptance criteria from these in a later step, so AC drafts are not authored here.
• Has a Figma link pointing at a specific frame, not the whole file.
• Has explicit scope-out: "API integration is out of scope. Use mocked data." (the FE-BE Integration is a separate WI you will create later).
• Has the module set to crm-fe.

If anything is missing, fix it before pressing Start. (Authoring discipline is in Work-Item Composition.)

Press Start. Swifter creates a work session, opens a session branch (swifter/wi-1001-customers-list), and enables the App, Dev, and Test tabs for the crm-fe module. The agent chat opens with a prompt to pick the team member who should work the item next.

The recommendation will be Frontend Analyst — accept it. Analysis comes before implementation in the platform's SDLC.

Step 7 — Refresh frontend knowledge caches

The first run of swifter-frontend-analyst:define-page-spec (or any first frontend command) automatically invokes refresh-framework-knowledge and refresh-storybook-knowledge. These read your project's package.json and Storybook configuration and produce two cache files at .swifter/specs/crm-fe/overview/:

• framework_knowledge.md — the canonical reference for your project's framework, libraries, conventions, and forbidden idioms.
• storybook_knowledge.md — your project's Storybook conventions (story file layout, MDX usage, addons).

The cache files are long (often 2000+ lines on a real project) and are prerequisites for every subsequent frontend generation: if either is missing, the developer agent's generate-component STOPs with an error.

Both files are hand-editable. Auto-generation gets you a head start; the cache then becomes a living guideline the team shapes as conventions emerge. The first analyst run is when the team reviews what was inferred and overrides anything wrong.

What framework_knowledge.md typically captures

Eight canonical categories, project-agnostic. Concrete library names below are examples — yours will differ by stack.

Category	What it captures	Example values
Metadata	Framework + version, key dependency versions, package manager, generation date	React 19 + Next.js 15 + pnpm · Angular 21 + Tailwind 4 + yarn · Vue 3 + Vite 6 + pnpm
Project conventions	Build / test / lint / format / Storybook commands; path aliases; module system	pnpm build, pnpm test; alias @/* → src/*; ES modules
Forbidden technologies	Libraries the project has migrated away from, with allow/deny tables and boundary-case exceptions	RxJS forbidden in app code; allowed only at the HTTP service boundary via lastValueFrom() · Redux Toolkit forbidden; use Zustand instead · any forbidden; use unknown + narrowing
File structure & naming	Directory layout, file-name conventions, component selector prefixes	pages/[page]/, components/, file names in kebab-case, component selector prefix app-
Component patterns	Standalone vs module-based, signal/hook-based I/O, container/presentational separation, lifecycle hooks	Standalone components with signal-based input() / output(); or React function components with useState / useEffect
Imports & path aliases	Barrel exports, alias mappings, no-deep-relative-imports rule	import { Foo } from '@components/foo'; never ../../../
Styling	CSS framework, design-token namespace, layer hierarchy, where library overrides live	Tailwind layers + --token-* namespace; or CSS Modules + a theme provider
TypeScript & state	Strict typing, DTOs vs domain models with mapper pattern, null / undefined handling, chosen state primitive	Signals + a custom BaseStateService; or Zustand + TanStack Query

The Forbidden technologies section is the highest-leverage block to hand-edit. Most projects inherit a package.json whose dependency tree still allows libraries the team has migrated away from (a legacy state library kept only for one boundary, a date library replaced by a newer one). The cache's auto-inference picks up the dependency and assumes it's fair game; only an explicit forbidden entry tells the agent otherwise. Add forbidden entries before the first developer run, then again whenever a migration completes.

Future framework changes (a major version upgrade, a new addon, a library migration) call for a re-run of the refresh skills, after which the team re-reviews and re-adds any hand-edited entries.

You can stop here. The page-spec generation will produce the actual deliverable for WI-1001. From this point you are on Journey 2 — the frontend-screen happy path.

Step 8 — Verify Preview works on the session branch

Before you let the analyst finish writing the spec, do a quick health check: switch back to the work-item header, open the ⋮ menu, and click Rebuild Preview. The platform builds the frontend on the session branch and serves it. Open the Preview URL; you should see the project shell (header, navigation, an empty area for the customer list).

Preview-build failures at this point typically mean one of:

• Branch creation didn't work — check Git-host branch policies.
• The frontend module's framework string is wrong — confirm it's REACT (or your team's value) in Settings → General.
• Code Server domain not allowlisted — see the diagnostic in Runbook — Troubleshooting.

If Preview works on a near-empty session branch, your environment is healthy and you're ready to run real work.

Ready for the next journey

At this point:

• The project exists in Swifter with both modules wired to their repositories.
• The backend guidelines are written and reviewed.
• The frontend knowledge caches are generated and reviewed.
• The backlog is synced; the first Work Item is open with a session running; Preview works.

The team is set up. Journey 2 — Frontend Screen Happy Path — walks you through finishing the WI-1001 Customers list end-to-end. After that, Journey 3 — FE-BE Integration Happy Path — wires the page to the real GET /api/customers endpoint through a separate Integration WI.

If something goes wrong at any step of this journey, do not delete the project and start over. Open Troubleshooting and find the symptom; almost every Day-1 issue has a known cause.