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

#	Phase	Reference	When
1	New Requirement	references/new-requirement.md	User wants to add a feature
2	Review Requirements	references/review-requirements.md	Requirements doc needs validation
3	Review Design	references/review-design.md	Design doc needs validation against requirements
4	Execute Plan	references/execute-plan.md	Ready to implement tasks from planning doc
5	Update Planning	references/update-planning.md	Auto-trigger after completing any task in Phase 4
6	Check Implementation	references/check-implementation.md	Verify code matches design
7	Write Tests	references/writing-test.md	Add test coverage (100% target)
8	Code Review	references/code-review.md	Final pre-push review

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

Rationalization	Why It's Wrong	Do Instead
"Skip to coding, requirements are clear"	Ambiguity hides in assumptions	Run Phase 1-3 first
"Design hasn't changed, skip Phase 6"	Code drifts from design during implementation	Check implementation against design
"Tests slow us down, ship first"	Bugs in production are slower	Write tests in Phase 4 and 7
"Just a small change, no review needed"	Small changes cause big outages	Phase 8 applies to all changes

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.