Projects and Work Items
Purpose: Create a project, populate the backlog, and manage individual work items inside the Reqs tab.
Creating a Project
The Create new project button on Home opens a dialog that gathers everything Swifter needs in one place. The dialog has three logical groups — identity and integrations, modules, and advanced options — and you submit the whole thing in one click.
| Field group | Fields | Notes |
|---|---|---|
| Identity and integrations | Project name; Version control system; Issue tracking; Design system | All four required. The integration pickers list whatever the org admin has configured under Settings → Integrations. |
| Modules | At least one module, each with name, type (Frontend / Backend / Testing), framework, package manager | Click Create new module to open the per-module sub-dialog. You can add more than one before submitting. |
| Advanced options | Work item query predicate | Optional. Filters which items are pulled from the tracker on Sync — WIQL WHERE clause for Azure DevOps, JQL for Jira. Leave empty to use the tracker default. |
Once the form is submitted the project is created and you are taken straight into its Workspace, with the Reqs tab open and the backlog empty until you sync or add items.
Modules and Tab Surface
Modules tie work items to a slice of the repository — typically frontend, backend, testing, sometimes a shared library — and each module has a single type. The work item's module is what drives which tabs become available after Start, so getting the module right at creation time matters more than it might look.
| Module type | App tab | Dev tab | Test tab |
|---|---|---|---|
| Frontend | Pages, Data model, Logic, API Library, Components, Styles | Always | Available |
| Backend | Data model, Logic, API Library | Always | Not available |
| Testing | Not available | Always | Available |
You can add more modules later from project Settings → General, but existing modules cannot be edited or removed from there — design the initial module set with that constraint in mind.
Greenfield vs Brownfield
The per-module sub-dialog has one toggle that decides the project's delivery shape — Use existing repository. With the toggle off (the default) the platform creates the module from its built-in template and you get a greenfield codebase wired to your version-control integration. Turn it on and a Repository URL field appears, letting you point the module at an existing repo so agents work against your real source.
For monorepos enable the Monorepo toggle and supply a Monorepo folder — the path inside the repo where this module lives. A single repository can host multiple modules this way, each in its own subfolder, with the platform respecting the boundary when it generates code and opens pull requests.
Sync with Issue Tracker
Sync with issue tracker sits on the Reqs tab toolbar and pulls work items from the connected tracker into the project. Sync is one-way — tracker into Swifter — so edits made in the tracker after sync require another press to land, and Swifter never writes back. The work item query set in advanced options decides which items come across; without a query the tracker's own defaults apply.
In practice teams run Sync once on project creation to load the initial backlog and then re-run it periodically as the tracker grows. Items synced this way keep their tracker IDs and a read-only marker — title, type, parent, and description cannot be edited inside the platform for synced items, only for items created natively in Swifter.
Creating Work Items Manually
The Create work item button on the Reqs tab opens a dialog that captures the same fields you would see in any tracker, plus a couple of Swifter-specific ones. Title is the short name everyone sees; Type sets the shape of the work (generic, component, page, defect); Module ties the item to a frontend / backend / testing slice; Parent picks an existing item above this one in the backlog; Assignee is optional; Description holds the detail in Markdown; Design URL is an optional Figma link.
Two practical notes. First, if you paste one or more Figma URLs into the Description Markdown they are picked up by agents as well, so you do not have to choose between the Design URL field and inline references. Second, Module is the field people most often forget — without it, Start is disabled, so the item cannot reach a session.
Editing After Start
The moment you press Start on a work item its session and branch are created, and certain fields lock to keep the session aligned with what is on disk. Type, module, and status lock for everyone; title, description, and parent stay editable only for items created natively in Swifter (synced items keep those fields read-only end-to-end); assignee and the Figma link remain editable but you can no longer revert assignee back to unassigned. Acceptance criteria and child items remain editable for as long as the work item is not Done and the session is not Done or Abandoned.
Plan accordingly — if you might restructure the backlog or move a piece of work between modules, do it before Start. Once a session exists, the cheapest way to change module is usually a fresh work item rather than a fight with the lock.
Hierarchy and Children
The Reqs tab shows the backlog as a tree — children sit under their parent, and when you open a parent its Children section lists everything nested beneath it. This works for both synced and Swifter-native items, and the tree reflects parent / child links from the source tracker faithfully.
A common pattern is one umbrella feature with several child work items at different lifecycle stages — one in Reqs, one with a session in progress, one already merged. The tree makes that obvious from the parent card, which is useful both during planning (what is left to start?) and during review (what has shipped under this feature?).