Feature Lifecycle: Stage by Stage

Walk through every stage of a feature — from creation to close — with what you do, what the agent does, and what gates check.

This is the definitive walkthrough of a feature's journey in Fabriq. Each stage has a clear purpose, deliverables, and a gate that ensures you don't skip critical steps.

Create → Analysis → Solution Design → Technical Design → Implementation → Validation → Review → Close

Stage 1: Create

What you do: Open the Workspace Browser, click + New Feature, enter a name and description.

Field	Example
Name	`add-dark-mode-toggle`
Description	Add a dark mode toggle to Settings page. Use existing Button component. Store preference in localStorage. Must work on desktop and mobile.

What Fabriq does:

Creates an isolated git worktree from your base repo
Generates the feature directory with docs stubs
Opens the Feature Workbench

What the agent does: Nothing yet — it hasn't been attached.

Gate check: None (creation always succeeds).

Stage 2: Analysis (Current State)

What the agent does: Reads your project structure, analyzes relevant files, and writes docs/01-current-state.md — a document describing the current codebase context for this feature.

The agent identifies:

Which components and files are relevant
Existing patterns it should follow
Potential risks or conflicts

What you do: Optionally review the current-state document. If the agent missed important context, you can inject it now.

Sample output:

# Current State: Dark Mode Toggle

## Relevant Files
- `/pages/Settings.tsx` — Settings page, contains the settings form
- `/components/Button.tsx` — Reusable button component
- `/styles/theme.css` — CSS variables for theming

## Existing Patterns
- Components use CSS modules
- Theme uses CSS custom properties defined in `:root`

Stage 3: Solution Design

What the agent does: Writes docs/03-business-design.md — the business/UX design of the solution. How the feature works from the user's perspective.

What you do: Review the design. Does it solve the right problem? Does the UX make sense? This is your last chance to redirect before code is written.

Gate check: 03-business-design.md must exist. If missing, advancing to Implementation is blocked with a message like:

GATE_BLOCKED: Feature "add-dark-mode-toggle" cannot advance from Design to Implementation.
Missing required document: docs/03-business-design.md

Stage 4: Technical Design

What the agent does: Writes docs/04-technical-design.md — the technical approach. Component architecture, data flow, file changes needed, API changes, test strategy.

What you do: Review for technical soundness. Is the architecture right? Are there security concerns? Performance implications?

Gate check: 04-technical-design.md must exist. This is a hard gate — the agent cannot start coding without an approved technical design.

Stage 5: Implementation

What the agent does: Writes code in the worktree. Every write, edit, or command surfaces as a confirmation prompt.

What you do: Monitor progress in the Workbench activity log. Review and approve/reject confirmation prompts as they appear. Intervene with guidance if the agent goes off track.

┌─ Activity Log ─────────────────────────────────────┐
│ ✓ Created worktree from main                       │
│ ✓ Read project structure (48 files)                │
│ ✓ Found existing Button component                  │
│ ⏳ Writing src/components/DarkModeToggle.tsx        │
│ ! Confirm: Write 65 lines to DarkModeToggle.tsx?  │
└────────────────────────────────────────────────────┘

Gate check: None during Implementation. Gates only apply at stage transitions.

Stage 6: Validation

What you do (required): Fill in tests/testability.md — a document that describes how to test the feature:

Entrypoints: Where to start testing (e.g., "Settings page at /settings")
Scenarios: What to test (e.g., "Toggle on → dark mode applies", "Toggle off → light mode restores")
Scope constraints: What NOT to test

What Fabriq does:

Reads testability.md and deterministically generates test cases — no LLM involved, predictable and repeatable
Runs validation through one or more executors:
- API executor — tests backend endpoints
- Browser executor — runs Playwright tests against the UI
- Repo-test executor — runs your existing test suite
Writes results to tests/runs/<id>.json and generates reports/validation-report.md

What you do: Review the validation report. If tests fail, the agent receives feedback, fixes the issues, and you re-run validation.

Gate check: testability.md must be filled in and validation must have been run at least once before advancing to Review.

Stage 7: Review

What you do: Enter the Review stage. The review screen shows:

File diff — side-by-side comparison of every changed file
Validation badges — green/yellow/red for lint, types, and test results
Acceptance checklist — did the agent meet your original requirements?

Step by step:

Check validation badges first — if tests are failing, the agent needs to fix them
Read through each changed file — focus on business logic, not formatting
Compare against your original description — did the agent build what you asked for?

If something needs fixing, leave a comment on the diff and click Request Changes. The agent revises and you repeat.

If everything looks good, click Approve.

Gate check: Validation must have passed (or warnings accepted) before approval is available.

Stage 8: Close

What Fabriq does: Runs the 5-step close pipeline — idempotent and resumable:

Step	What happens
1. Promote	Key docs copied from feature to workspace knowledge
2. Link	Feature-history entry created with decision records
3. Index	Cognitive assets indexed into workspace knowledge graph
4. Summary	`reports/close-summary.md` written with deliverables, test results, must-fix items
5. Audit	Full audit log entry written

What you do: Review the close summary. Optionally browse the feature-history entry. The worktree is cleaned up (but can be recovered).

A closed feature isn't gone — it's woven back into the workspace knowledge fabric.

Stage gate quick reference

Transition	Gate check	Can bypass?
Create → Analysis	None	-
Design → Implementation	Business + Technical design docs exist	With `confirmed=true` (logged)
Implement → Validation	testability.md not empty	With `confirmed=true` (logged)
Validation → Review	Validation run completed	No
Review → Close	Approved	No

Next steps

Stage Gates — detailed guide to gate errors and resolution
Creating Features — write effective descriptions
Working with the Agent — inject context, intervene, guide
Validation — from testability to test report
Closing a Feature — the 5-step pipeline explained