Development Lifecycle (Docs-First)
One flow, enforced. Every non-trivial change moves through the same six phases, in order, each producing one artifact in one canonical home. Documentation is written before code and corrected during implementation if reality diverges — never skipped, never freestyle.
1. Principles
| Principle | Meaning |
|---|---|
| Docs-first | Requirements and intent are written before implementation. You start in docs/wiki, not in code. |
| One home per artifact | Each artifact type has exactly one location (table below). No freestyle specs/plans scattered across the repo. |
| Traceable | Every artifact carries IDs and links forward/back along the spine, so one feature is followable roadmap → URD → PRD → ADR → Plan → code → test. |
| Code-as-truth | Once built, docs describe actual verified behaviour. If implementation reveals the doc is wrong, fix the doc in the same change — docs and code never drift. |
| Gated | Each phase has a definition-of-done that must hold before the next begins. |
2. The Flow
| # | Phase | Artifact | Canonical home | Owner | Gate to next phase |
|---|---|---|---|---|---|
| 1 | Requirements | URD | content/{en,vi}/modules/<tier>/<module>/urd.md | PM/PO/BA | Functional requirements have URD-<AREA>-NNN IDs + MoSCoW + acceptance criteria |
| 2 | Increment scope | PRD | …/<module>/prds/YYYY-MM-DD-<slug>.md | PM/PO | Cites the URD IDs it delivers; goals/non-goals, UX/flows, rollout defined |
| 3 | Architecture (non-trivial only) | ADR | content/{en,vi}/developer/packages/<pkg>/decisions/NNNN-<slug>.md | Eng | Decision + alternatives + consequences recorded; linked from PRD |
| 4 | Implementation plan | Plan | .agents/plans/YYYY-MM-DD-<module>-<slug>.md | Eng | Step-by-step; each step cites URD IDs / ADR; verification per step |
| 5 | Code | source | packages/*, apps/*, third-parties/* | Eng | Builds green (bun run rebuild), lint 0 (quality gate) |
Brainstorm output has no separate home. Design exploration resolves into the PRD (product intent) and ADR (architecture decisions). There is no standalone "spec" file — see §5.
3. When does a phase apply?
| Change type | URD | PRD | ADR | Plan | Test cases |
|---|---|---|---|---|---|
| New module / major feature | ✅ | ✅ | if non-trivial | ✅ | ✅ |
| Feature increment in an existing module | update | ✅ | if non-trivial | ✅ | update |
| Architecture-only change (no user-visible behaviour) | — | — | ✅ | ✅ | if testable |
| Bugfix / small mechanical change | — | — | — | optional | update if behaviour changed |
"Non-trivial" = anything that introduces a pattern, a cross-package contract, a data migration, or a decision a future engineer would ask "why?" about. When in doubt, write the ADR.
4. Traceability spine
The chain is anchored by the traceability block at the top of every module index.md (see Module convention §6.1). That block now carries a Plan link so the engineering step is part of the spine:
> | Chain | Link |
> |-------|------|
> | Roadmap | [Phase 1](/en/delivery/roadmap#phase-1) |
> | URD | [URD](./urd) |
> | PRD | [PRD-XXX-001](./prds/2026-06-04-...) |
> | Decisions (ADR) | [ADR-0001](/en/developer/packages/<pkg>/decisions/0001-...) |
> | Plan | [.agents/plans/2026-06-04-<module>-...](…) |
> | Dev docs | [@nx/<pkg>](/en/developer/packages/<pkg>/) |
> | Runbook | [<module> ops](/en/runbook/operations/) |
> | Delivery log | [Traceability matrix](/en/delivery/traceability-matrix) |IDs line up across artifacts by <AREA> code: URD-STK-001 ↔ TC-STK-001 ↔ PRD-STK-001. See Module convention §6.
5. One home per artifact (no freestyle)
| Artifact | The ONE home | Retired / never use |
|---|---|---|
| Requirements | module urd.md | ad-hoc requirement notes |
| Product intent / increment | module prds/ | docs/superpowers/specs/, scratch "design.md" |
| Architecture decision | developer/packages/<pkg>/decisions/ (ADR) | inline design notes in code/PR |
| Implementation plan | .agents/plans/ | docs/superpowers/plans/, docs/plans/ |
docs/superpowers/is retired. Brainstorming produces a PRD (+ ADR); plan-writing produces a.agents/plans/file. Both link into the module spine.
6. Working the flow with agents
- Start every feature in
docs/wiki— write/extend the URD, then the PRD. Only after the PRD is agreed do you write the plan; only after the plan do you write code. - Brainstorming (the design dialogue) ends by writing the PRD (and an ADR if architecture is involved), not a standalone spec.
- Plan-writing ends by writing the
.agents/plans/file, which the PRD links to. - During implementation, if the code reveals a doc is wrong, edit the doc in the same change before continuing. Docs are corrected, not abandoned.
7. Related
- Developer Docs Structure — package docs + ADR shape
- Delivery — Roadmap · Traceability Matrix
_template/— copy-from skeleton for a new module