Feature delivery workflow
For ANY new functionality — endpoint, component, AI agent, feature flag, pipeline, etc.
1. SPEC.md first (NO code yet)
- Run
/start-tz <name>slash command — createsspecs/<SERIES>/<TZ_N>/SPEC.mdfrom template - Fill: goal (≤3 sentences), explicit IN scope, explicit OUT scope, definition of done, deadline
- Owner reviews and approves SPEC before code
2. Architecture check
- If feature touches architecture (new module, new external dep, new pattern) → ADR REQUIRED before code
- Use
/adrslash command to create one-line ADR fast - Read related ADRs first (UserPromptSubmit hook auto-injects matching ADRs)
3. ROADMAP.md — staged plan
- Run
/start-tzalready created it. Fill stages with task checklists. - Each stage independently validatable: code → mypy/ruff per task (R12) → pytest per stage (R13)
- Each stage ends with manual smoke test from owner before next stage starts
4. External tech check (R2)
- Pydantic AI? FastAPI? React component lib? — Context7 MCP
resolve-library-id→get-library-docs - Quote the relevant API clause + URL in SPEC.md
- Do NOT write code from training memory
5. Implement stage by stage
- Stage 1: write code → mypy clean per task → write tests → pytest passes → request manual smoke
- WAIT for owner OK
- Stage 2: only after stage 1 OK
- ...
6. NO drive-by improvements (R3)
- See a bug while building? → log to
docs/agent/06_known_issues.md(FINDINGS.md inside TZ dir) - See a refactor opportunity? → log to backlog
- Stop hook will block scope creep at end of turn — heed it
7. One commit per ТЗ (R5)
- Stage validation does NOT mean commit. Code accumulates.
- Single commit at /close-tz:
feat(tz-XX): <one-sentence summary> - Commit body 3-5 lines, no exhaustive file list
8. Close ТЗ
- Run
/close-tzslash command:- SQL/data sanity check if DB touched
- Manual smoke OK from owner
- FINDINGS.md → backlog (significant findings become follow-up TZ)
- docs/agent/04_changelog.md updated
- docs/agent/00_current_state.md updated (only durable facts)
- ADR for architectural decisions
- Single commit
- Folder moved to
_archive/when series closes
Anti-patterns
- ✗ Code before SPEC
- ✗ Code before reading docs (R2)
- ✗ Skip ADR for architectural decision
- ✗ Combine 3 ТЗ into one commit
- ✗ Mark ТЗ done without owner smoke test