Dev Lifecycle

Sequential phases producing docs in docs/ai/. Flow: 1→2→3→4→(5 after each task)→6→7→8.

Prerequisite

Before starting any phase, run npx ai-devkit@latest lint to verify the base docs/ai/ structure exists and is valid.

If working on a specific feature, also run npx ai-devkit@latest lint --feature <name> to validate feature-scoped docs.

If lint fails because project docs are not initialized, run npx ai-devkit@latest init, then rerun lint. Do not proceed until checks pass.

For a new feature start (Phase 1 or /new-requirement), apply the shared worktree setup in references/worktree-setup.md before phase work. This setup is worktree-first by default and includes explicit no-worktree fallback, context verification, and dependency bootstrap.

Phases

Load only the reference file for the current phase. For Phase 1, also load references/worktree-setup.md.

Resuming Work

If the user wants to continue work on an existing feature:

1. Check branch and worktree state before phase work:
   • Branch check: git branch --show-current
   • Worktree check: git worktree list
2. Determine target context for <feature-name> (all .worktrees/ paths are relative to the project root — the directory containing .git):
   • Prefer worktree <project-root>/.worktrees/feature-<name> when it exists.
   • Otherwise use branch feature-<name> in the current repository.
3. Before switching, explicitly confirm target with the user (branch or worktree path).
4. After user confirmation, switch to the confirmed context first:
   • Worktree: run phase commands with workdir=<project-root>/.worktrees/feature-<name>.
   • Branch: checkout feature-<name> in current repo.
5. After switching, run npx ai-devkit@latest lint --feature <feature-name> in the active branch/worktree context.
6. Then run the phase detector using the installed skill directory (same resolution rule as reference docs), not a workspace-relative skills/... path:
   • Resolve <skill-dir> as the directory containing this SKILL.md.
   • Run <skill-dir>/scripts/check-status.sh <feature-name> (or cd <skill-dir> && scripts/check-status.sh <feature-name>). Use the suggested phase from this script based on doc state and planning progress.

Backward Transitions

Not every phase moves forward. When a phase reveals problems, loop back:

• Phase 2 finds fundamental gaps → back to Phase 1 to revise requirements
• Phase 3 finds requirements gaps → back to Phase 2; design doesn't fit → revise design in place
• Phase 6 finds major deviations → back to Phase 3 (design wrong) or Phase 4 (implementation wrong)
• Phase 7 tests reveal design flaws → back to Phase 3
• Phase 8 finds blocking issues → back to Phase 4 (fix code) or Phase 7 (add tests)

Doc Convention

Feature docs: docs/ai/{phase}/feature-{name}.md (copy from README.md template in each directory, preserve frontmatter). Keep <name> aligned with the worktree/branch name feature-<name>.

Phases: requirements/, design/, planning/, implementation/, testing/.

Memory Integration

In phases with clarification questions (typically 1-3), run these CLI commands (see the memory skill for full options):

1. Before asking — search first, only ask about uncovered gaps: npx ai-devkit@latest memory search --query "<topic>"
2. After clarification — store for future sessions: npx ai-devkit@latest memory store --title "<title>" --content "<insight>" --tags "<tags>"

Red Flags and Rationalizations

Rules

• Read existing docs/ai/ before changes. Keep diffs minimal.
• Use mermaid diagrams for architecture visuals.
• After each phase, summarize output and suggest next phase.
• Apply the verify skill before completing Phase 4 tasks, Phase 6 checks, Phase 7 coverage claims, and Phase 8 review items. No phase transition without fresh evidence.