feature-delivery

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 — creates specs/<SERIES>/<TZ_N>/SPEC.md from 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 /adr slash command to create one-line ADR fast
• Read related ADRs first (UserPromptSubmit hook auto-injects matching ADRs)

3. ROADMAP.md — staged plan

• Run /start-tz already 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-tz slash 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