Agent Communication

Use ai-devkit agent ... to discover and communicate with active agents. If ai-devkit is not on PATH, use npx ai-devkit@latest agent ....

Commands

ai-devkit agent list --json
ai-devkit agent detail --id <agent-name> --json --tail 20
ai-devkit agent send --id <agent-name> "<message>"
ai-devkit agent send --id <agent-name> --wait --timeout 120000 --json "<message>"
<command> 2>&1 | ai-devkit agent send --id <agent-name> --stdin

Notes

• list --json returns active agents with fields such as name, type, status, summary, projectPath, and lastActive.
• Use the name from list --json as --id. Partial matches are supported, but exact names are safer.
• Use detail --json --tail <n> to read recent context from an agent before deciding what to send.
• send --wait waits for a reply; add --json when the response should be machine-readable.
• send --stdin forwards piped command output or larger text.

Agent Management

Use ai-devkit agent ...; if unavailable, use npx ai-devkit@latest agent ....

Workflow

1. List agents: ai-devkit agent list --json.
2. Identify self: compare your current session id to sessionId from list --json
3. Inspect before acting: ai-devkit agent detail --id <name> --json --tail 20.
4. Reuse idle agents when suitable; otherwise start one with agent start.
5. Send self-contained assignments. Track each agent's task and last instruction.
6. Verify completed work before reporting it done. Use $agent-communication for agent-to-agent updates.

Commands

ai-devkit agent list --json
ai-devkit agent detail --id <name> --json --tail 20
ai-devkit agent start --type codex --name <name> --cwd <path>
ai-devkit agent send --id <name> "<single-line instruction>"
ai-devkit agent send --id <name> --wait --timeout 120000 --json "<single-line instruction>"
ai-devkit agent send --group <group> "<single-line instruction>"
ai-devkit agent sessions --cwd <path> --type codex --json --limit 20
ai-devkit agent rename <old-name> <new-name>
ai-devkit agent kill <name>

Use exact names from list --json. Partial matches are convenient but risk sending work to the wrong agent.

Assignment Rules

• Do not send instructions to yourself unless intentional.
• Prefer task names like auth-review, ui-tests, or docs-pass.
• Include objective, scope/files, constraints, validation command, expected output, and whether to stop or continue.
• Assign non-overlapping files or sequence dependent work.
• Use groups only for broadcasts that truly apply to every member.
• Ask before killing agents you did not start, destructive actions, production/shared-system actions, or product decisions.

Example:

ai-devkit agent send --id auth-review "Review auth middleware in /repo. Do not edit files. Report security findings with file/line references, ranked by severity."

Changelog

Update the top Unreleased list in CHANGELOG.md from commits after the latest release.

Workflow

1. Find the latest release base:
   • Prefer the latest reachable tag: git describe --tags --abbrev=0.
   • If there are no tags, search recent history for a release commit and use that hash.
2. Get commits: git log <base>..HEAD --reverse --format='%H%x09%s'.
3. Derive the GitHub repo URL from git remote get-url origin.
4. For each commit, add one concise changelog line:
   • Format: - [<short-hash>](<url>) <one-line summary>
   • If the commit clearly relates to a PR, link the hash to the PR URL instead of the commit URL.
   • Detect PRs from subjects like (#123), merge commits, or gh pr list --search <hash> --state all --json number,url.
5. Insert the new lines into the top Unreleased section/list in CHANGELOG.md.
   • If no Unreleased section exists, create one at the top.
   • Do not create a dated release heading unless the user asks for a release.

Rules

• Keep one line per commit.
• Preserve the existing changelog style when obvious.
• Always add entries to the top Unreleased list.
• Skip noisy commits only when clearly non-user-facing and explain what was skipped.
• Do not invent PR links; use commit links when PR evidence is missing.

Dev Commit

Make one intentional, verified commit without sweeping in unrelated work.

Commit Contract

1. Check repository state with git status --short --branch, git diff --stat, and git diff.
2. Identify the files that belong to the requested change. Treat pre-existing user edits, local config, generated artifacts, dependency caches, build outputs, and unrelated formatting churn as out of scope unless the user explicitly includes them.
3. Run appropriate validation before committing. Prefer the repo's targeted tests, lint, typecheck, build, or documented verification commands. Record skipped validation with the reason.
4. Stage only intended paths. Prefer explicit pathspecs such as git add path/to/file over git add ..
5. Re-check with git diff --cached --stat, git diff --cached, and git status --short.
6. Write a concise conventional commit message: <type>(optional-scope): <summary>.
7. Commit, then report the commit SHA, final status, validation commands, and any unstaged/untracked files left behind.

Guardrails

• Do not commit secrets, credentials, .env files, local machine config, caches, coverage, logs, screenshots, or generated files unless the change explicitly requires them.
• Do not stage another person's unrelated edits. If intended and unrelated changes are mixed in one file, use an interactive or patch-based staging flow and review the staged diff carefully.
• Do not amend, rebase, force-push, reset, or delete branches unless the user explicitly asks for that operation.
• If validation fails, stop before committing unless the user explicitly instructs you to commit with failing validation. Report the failing command and key output.
• If the repo has commit hooks, let them run. If a hook changes files, inspect and stage only intended hook outputs before retrying.

Message Style

Use semantic or conventional commit types that match the change:

• feat: user-facing feature or capability
• fix: bug fix
• docs: documentation-only change
• test: test-only change
• refactor: behavior-preserving code restructuring
• chore: maintenance, build, tooling, metadata, or generated index updates

Keep the subject under about 72 characters when practical, imperative, and specific. Add a body only when it explains non-obvious validation, risk, migration, or follow-up context.

Dev Design

Run the design review phase for configured AI docs features. Before changing docs or code, propose the concrete plan for this phase and wait for user approval unless the user already approved the exact phase plan.

Phase Contract

1. Run npx ai-devkit@latest lint before phase work.
2. If working on a named feature, run npx ai-devkit@latest lint --feature <name>.
3. Read existing requirements and design docs before changes.
4. Ask until every material architecture, scope, validation, rollout, contradiction, trade-off, or open question is answered, explicitly deferred, or accepted as a named assumption.
5. Ask one decision at a time, with why it matters, 2-3 viable options when useful, and a recommended answer.
6. Do not approve or transition past design while material open questions remain.
7. Use mermaid diagrams for architecture visuals where a diagram clarifies the design.
8. If parent dev-lifecycle established usable task tracing, emit design phase, progress, blocker/open-question, and next-step events per task.

Review Design

Use for Phase 3.

1. Run npx ai-devkit@latest lint --feature <name> and review the design doc path it validates. If manual path resolution is unavoidable, first resolve .ai-devkit.json paths.docs, falling back to docs/ai.
2. Search memory for relevant architecture patterns or past decisions.
3. Cross-check against the latest matching requirements doc. Verify every goal, user story, and constraint has corresponding design coverage. Flag uncovered requirements.
4. Review completeness: architecture, components, technology choices, data models, API contracts, design trade-offs, and non-functional requirements.
5. Resolve every gap, misalignment, open question, hidden assumption, or unresolved trade-off between requirements and design.
6. Brainstorm alternatives for key architecture decisions and trade-offs before accepting the first approach.
7. Update the design doc with clarified decisions and chosen options.
8. Store reusable architecture decisions in memory.
9. If task tracing is available, record design coverage progress, next step, or blockers per task.
10. Summarize requirements coverage, completeness assessment, updates made, and remaining gaps.

Next: dev-implementation. If requirements gaps are found, return to dev-requirements. If design is fundamentally wrong, revise design and re-review.

Dev Implementation

Run implementation work for configured AI docs features. Before changing docs or code, propose the concrete plan for this phase and wait for user approval unless the user already approved the exact phase plan.

Phase Contract

1. Run npx ai-devkit@latest lint before phase work.
2. If working on a named feature, run npx ai-devkit@latest lint --feature <name>.
3. Read requirements, design, planning, implementation, and testing docs before changes.
4. Use the tdd skill while executing implementation tasks: write a failing test before production code, then make it pass.
5. Apply the verify skill before completing tasks or making implementation alignment claims.
6. Keep testing and implementation docs in lockstep with code. Do not defer all doc updates to final verification.
7. If parent dev-lifecycle established usable task tracing, emit phase, progress, next-step, blocker, and evidence events per task.

Execute Plan

Use for Phase 5.

1. Run npx ai-devkit@latest lint --feature <name> and work through the planning doc path it validates. If manual path resolution is unavoidable, first resolve .ai-devkit.json paths.docs, falling back to docs/ai.
2. Gather context: feature name, planning doc path, supporting docs, current branch, and current diff.
3. Parse task lists and build an ordered queue by section.
4. Present the task queue with status: todo, in-progress, done, blocked.
5. For each task, show context, suggest relevant docs, and outline sub-steps from the design doc when useful.
6. If task tracing is available, record current task progress and immediate next action per task.
7. Reuse before writing: grep for existing utilities/functions before adding new ones. Reuse only if it fits cleanly.
8. Handle breaking changes carefully: update all in-repo callers atomically; for external/public/cross-service callers, add a new function and deprecate the old one.
9. Generate a markdown tracking snippet after each status change.
10. After each task, update the testing doc with completed scenarios, newly discovered scenarios, and invalidated scenarios. Update the implementation doc with changed files, decisions, design deviations, and edge cases handled.
11. After each section, ask if new tasks were discovered.
12. Summarize completed, in-progress, blocked, skipped, new tasks, task-tracing events emitted or why tracing was unavailable, and doc deltas.

Next: after completing any task, run dev-planning Phase 6. When all tasks are done, run Check Implementation, then dev-testing and dev-review.

Check Implementation

Use for Phase 7.

1. Compare implementation against the configured design and requirements docs validated by npx ai-devkit@latest lint --feature <name>.
2. Gather context: feature description, modified files, relevant design/requirements docs, constraints.
3. Summarize design: key decisions, components, interfaces, data flows.
4. Review file by file: verify design intent, note deviations, flag logic gaps, edge cases, security issues, and missing tests or doc updates.
5. Finalize the implementation doc. Verify it captures what shipped, fill gaps, and record follow-ups.
6. Summarize alignment status, deviations with severity, missing pieces, concerns, and next steps.

Next: dev-testing, then dev-review. If major deviations exist, return to dev-design if design is wrong or Execute Plan if implementation is wrong.

Dev Lifecycle

Coordinate the phase-specific AI DevKit skills instead of running phase details directly.

Required phase skills:

• dev-worktree for feature workspace setup and resume.
• dev-requirements for phases 1-2: new requirement and requirements review.
• dev-design for phase 3: design review.
• dev-planning for phases 4 and 6: initial task planning and updates after implementation tasks.
• dev-implementation for phases 5 and 7: execute plan and check implementation.
• dev-testing for phase 8: write tests and verify coverage.
• dev-review for phase 9: final code review.

Supporting skills:

• memory for reusable project knowledge during clarification.
• tdd for implementation tasks.
• verify before completing implementation, implementation checks, testing claims, and review readiness.
• task for optional progress tracing when the task command is usable.

Startup Validation

At the beginning of every dev-lifecycle run:

1. Run npx ai-devkit@latest skill list to inspect currently installed project skills.
2. Confirm the listed skills include all required phase skills and supporting skills.
3. If any required skill is missing, run npx ai-devkit@latest skill add --built-in to install all AI DevKit built-in skills. Then rerun npx ai-devkit@latest skill list.
4. If installation fails or a required skill is still missing, stop and report the missing skill names and command output summary. Do not run a phase without its skill.
5. Run npx ai-devkit@latest lint to verify the configured AI docs structure.
6. If working on a specific feature, run npx ai-devkit@latest lint --feature <name>.
7. If lint fails because project docs are not initialized, run npx ai-devkit@latest init -a -e claude --built-in --yes, then rerun lint.
8. Probe optional task tracing availability:
   • With a feature: npx ai-devkit@latest task list --name <feature-name> --json
   • Without a feature: npx ai-devkit@latest task list --json
   • Treat task tracing as available only if the read probe exits 0. If it fails, record task tracing as unavailable with the failed command and reason, then continue without task logging.
   • Never block lifecycle work only because the task command is missing or unusable.
9. When working on a specific feature and task tracing is available:
   • Load and follow task before executing a phase.
   • Initialize or show the task named after the feature, mark active work, and emit phase/progress/next/blocker/evidence events per task.
   • Sequence task mutations; do not batch or parallelize mutations for the same feature.

Plan Before Execution

Before executing any phase:

1. Identify the target feature, current docs state, branch/worktree context, and likely next phase.
2. Propose a concise plan that names the phase skill to use, the docs/files to read, commands to run, expected edits, task tracing status and planned task events if tracing is available, and verification evidence.
3. Wait for user approval before executing the plan unless the user already gave explicit approval for that exact phase execution.
4. After approval, load and follow only the selected phase skill plus any explicitly required supporting skills. If tracing is available, the task skill is explicitly required.

Phase Routing

Sequential flow: setup -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 after each completed task -> 7 -> 8 -> 9.

Resuming Work

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

1. Use dev-worktree to identify and confirm the target branch/worktree.
2. Run npx ai-devkit@latest lint --feature <feature-name> in the active context.
3. Run the phase detector from the installed dev-lifecycle skill directory:
   • Resolve <skill-dir> as the directory containing this SKILL.md.
   • Run <skill-dir>/scripts/check-status.sh <feature-name>.
   • Use the suggested phase when proposing the execution plan.

Backward Transitions

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

• Requirements review finds fundamental gaps: return to dev-requirements Phase 1.
• Design review finds requirements gaps: return to dev-requirements Phase 2.
• Design review finds design flaws: stay in dev-design and revise design.
• Implementation check finds major deviations: return to dev-design if design is wrong, or dev-implementation if code is wrong.
• Testing reveals design flaws: return to dev-design.
• Review finds blocking issues: return to dev-implementation or dev-testing.

Rules

• Use npx ai-devkit@latest lint and npx ai-devkit@latest lint --feature <name> to discover and validate the configured docs directory. Do not assume docs/ai; it is only the default.
• Read existing configured AI docs before changes. Keep diffs minimal.
• Keep feature names aligned with branch/worktree feature-<name>.
• New feature docs come from npx ai-devkit@latest docs init-feature <name>. Use the paths returned by the command as authoritative.
• Existing feature docs are the paths reported or validated by npx ai-devkit@latest lint --feature <name>. If you must infer manually, first resolve the configured docs directory from .ai-devkit.json paths.docs, falling back to docs/ai.
• After each phase, summarize output and suggest the next phase.
• Do not claim completion without fresh verification evidence.
• When task tracing is available, follow task: create once, assign actor when known, mark active/blocked, set phase, record progress/next/evidence, and close only after final verification/review. If tracing is unavailable, include failed probe commands in the phase summary without blocking the lifecycle.

Dev Planning

Run planning creation and reconciliation for configured AI docs features. Before changing docs, propose the concrete plan for this phase and wait for user approval unless the user already approved the exact phase plan.

Phase Contract

1. Run npx ai-devkit@latest lint before phase work.
2. If working on a named feature, run npx ai-devkit@latest lint --feature <name>.
3. Read existing configured planning, implementation, and testing docs before changes. Resolve paths through lint --feature instead of assuming docs/ai.
4. Keep task creation and updates traceable to requirements, design, testing scenarios, completed work, blockers, or newly discovered scope.
5. If parent dev-lifecycle established usable task tracing, emit planning phase, progress, blocker/scope, and next-step events per task.

Create Initial Plan

Use for Phase 4 after requirements, design, and initial testing docs exist.

1. Run npx ai-devkit@latest lint --feature <name> and identify the planning doc path it validates. If docs init-feature just ran, use the returned planning path as authoritative.
2. Read requirements, design, and testing docs for the feature.
3. Convert goals, user stories, design components, API/data changes, migration needs, and testing scenarios into implementation tasks.
4. Group tasks by milestone or logical sequence.
5. For each task, include outcome, dependencies, validation evidence, and related testing scenarios.
6. Verify every test-plan scenario has at least one implementation task.
7. Add risks, blockers, sequencing notes, and likely follow-up checks.
8. Update the planning doc with the initial ordered task list.
9. If task tracing is available, record plan progress and next implementation step per task.

Next: dev-implementation.

Update Planning

Use for Phase 6. Auto-trigger this phase after completing any task in dev-implementation.

1. Run npx ai-devkit@latest lint --feature <name> and reconcile the planning doc path it validates. If manual path resolution is unavoidable, first resolve .ai-devkit.json paths.docs, falling back to docs/ai.
2. If continuing from implementation, carry forward existing context. Otherwise ask for feature name, completed tasks, new tasks, blockers, and planning doc path.
3. Review existing milestones, sequencing, dependencies, and outstanding tasks.
4. Reconcile each task: mark status as done, in-progress, blocked, or not started; note scope changes; record blockers; capture skipped or added tasks.
5. Update the planning doc with the current status checklist.
6. Suggest the next 2-3 actionable tasks, risky areas, and coordination needed.
7. If task tracing is available, record completed/blocked/new tasks, blockers, and next action per task.
8. Write a summary paragraph for the planning doc covering progress, risks, upcoming focus, and scope changes.

Next: if tasks remain, return to dev-implementation. If all done, run implementation verification before testing and review.

Dev PR

Publish an already-reviewed branch for code review. Keep this separate from commit creation: if the branch has uncommitted changes, stop and ask the user to run the commit workflow first.

Contract

1. Verify repository context with git status -sb, git branch --show-current, and git remote -v.
2. Confirm the branch is not the base branch and has committed changes to publish.
3. Fetch the remote before comparing or rebasing.
4. Rebase the feature branch onto the latest remote base branch before push/review.
5. Resolve conflicts carefully, preserving intended behavior, then rerun relevant validation.
6. Push safely. Use --force-with-lease only when a rebase rewrote an already-pushed branch.
7. Open or update the host's review request: PR, merge request, or equivalent.
8. Report review URL, branch, HEAD SHA, validation results, push mode, and risks.

Publish Workflow

1. Inspect local context:
   • git status -sb
   • git branch --show-current
   • git remote -v
2. If uncommitted changes exist, stop. Do not stage, amend, squash, or commit in this skill.
3. Identify the remote and base branch from repo conventions, upstream config, or user instruction; default to origin/main only when that matches the repo.
4. Fetch the remote, inspect the delta, and rebase onto the remote base branch.
5. If conflicts occur, inspect conflicted files and git diff, resolve minimally, validate when useful, git add, then continue the rebase. Stop if the correct resolution is unclear.
6. Run relevant validation for the changed surface.
7. Push:
   • First push: set upstream.
   • Normal update: plain push.
   • Rebased already-pushed branch: --force-with-lease.
8. Open or update the review request using the host's tool/API/UI (gh, glab, forge CLI, web UI, or project-specific workflow).
9. Write a concise review description. Include enough for reviewers to understand:
   • Summary: what changed, why, and how.
   • Validation: how it was verified.
   • Risks: notable risks or "none known".
10. Report:

• Review URL and state
• Branch and HEAD SHA
• Validation commands and exit codes
• Push mode, including whether --force-with-lease was used
• Risks, follow-ups, or blockers

Dev Requirements

Run the requirements phases for configured AI docs features. Before making docs or code changes, propose the concrete plan for this phase and wait for user approval unless the user already approved the exact phase plan.

Phase Contract

1. Run npx ai-devkit@latest lint before phase work.
2. If working on a named feature, run npx ai-devkit@latest lint --feature <name>.
3. If lint fails because project docs are not initialized, run npx ai-devkit@latest init -a -e claude --built-in --yes, then rerun lint.
4. Read existing configured AI docs and keep diffs minimal. Do not assume docs/ai; it is only the default docs directory.
5. Ask until every material product, UX, architecture, scope, validation, rollout, contradiction, trade-off, or open question is answered, explicitly deferred, or accepted as a named assumption.
6. Ask one decision at a time, with why it matters, 2-3 viable options when useful, and a recommended answer.
7. Do not create, update, approve, or transition past requirements while material open questions remain.
8. Restate the shared understanding before updating docs or suggesting the next phase.
9. If parent dev-lifecycle established usable task tracing, emit requirements phase, clarification/progress, blocker/open-question, and next-step events per task.

New Requirement

Use for Phase 1 or /new-requirement.

1. Search AI DevKit memory for relevant past features or conventions with npx ai-devkit@latest memory search --query "<feature/topic>". If unfamiliar, check the memory skill first.
2. Clarify feature name in kebab-case, problem, target users, key user stories, scope, non-goals, success criteria, UX, constraints, rollout, and validation.
3. Brainstorm alternatives to confirm this is the right thing to build. Present 2-3 approaches with one-line trade-offs and a recommendation.
4. Store reusable answers after clarification.
5. Use dev-worktree to create or resume the active feature workspace with normalized <name>.
6. Initialize docs with npx ai-devkit@latest docs init-feature <name> from the active worktree/repository and fill the returned paths. Treat those returned paths as authoritative because paths.docs may customize the docs directory.
7. Fill requirements doc: problem statement, goals/non-goals, user stories, success criteria, constraints, open questions.
8. Fill design doc: architecture with mermaid diagram, data models, APIs, components, design decisions, security/performance.
9. Fill testing doc: derive scenarios from requirements success criteria and design components/edge cases as - [ ] checkboxes, plus mocks/fixtures and coverage target.
10. If task tracing is available, record draft progress and next review step per task.
11. Use dev-planning to create the initial task plan from the requirements, design, and testing docs.

Next: dev-requirements review, then dev-design.

Review Requirements

Use for Phase 2.

1. Run npx ai-devkit@latest lint --feature <name> and review the requirements doc path it validates. If manual path resolution is unavoidable, first resolve .ai-devkit.json paths.docs, falling back to docs/ai.
2. Check it against the README.md template.
3. Search memory for relevant conventions or past patterns.
4. Review each section: problem statement, goals/non-goals, success criteria, user stories, constraints, open questions, template compliance.
5. Resolve every gap, contradiction, ambiguity, open question, or implicit assumption.
6. Brainstorm alternatives for key decisions and trade-offs before accepting the first approach.
7. Update the requirements doc with clarified answers and chosen options.
8. Store reusable clarifications in memory.
9. If task tracing is available, record validation progress, next step, or blockers per task.
10. Summarize what was validated, what was updated, and remaining open items.

Next: dev-design. If fundamental gaps remain unresolvable, return to New Requirement.

Dev Review

Run final pre-push review for configured AI docs features. Before changing docs or code, propose the concrete review plan and wait for user approval unless the user already approved the exact phase plan.

Phase Contract

1. Run npx ai-devkit@latest lint before phase work.
2. If working on a named feature, run npx ai-devkit@latest lint --feature <name>.
3. Check git status -sb and git diff --stat.
4. Read feature docs and relevant changed files before findings.
5. Apply the verify skill before claiming readiness.
6. If parent dev-lifecycle established usable task tracing, emit review phase, progress, blocker/finding, next-step, and final evidence/readiness events per task.

Code Review

Use for Phase 9. Take a holistic review stance: findings first, ordered by severity, grounded in file/line references.

1. Gather context: feature description, modified files, design docs, risky areas, tests already run.
2. Verify design alignment by summarizing architectural intent and checking implementation matches.
3. For each modified file, grep exported names to trace callers and dependents. Read relevant signatures, call sites, and type definitions.
4. Check consistency against 1-2 similar modules.
5. Search for existing utilities the new code could reuse or now duplicates. Flag near-matches honestly; do not force a wrong abstraction.
6. Verify contract integrity at API, type, config, and schema boundaries.
7. Check dependency health, including circular dependencies or version conflicts from new imports.
8. Check breaking changes. For public/external APIs, recommend parallel change and deprecation over in-place mutation. For in-repo-only callers, in-place modification with all callers updated is acceptable.
9. Check rollback safety, especially irreversible migrations or one-way data/state changes.
10. Review file by file for correctness, logic, edge cases, redundancy, security, performance, error handling, and test coverage.
11. Check cross-cutting concerns: naming conventions, documentation updates, missing tests, config/migration changes.
12. Summarize blocking issues, important follow-ups, and nice-to-haves. Per finding include file, issue, impact severity, and recommendation.
13. If task tracing is available, add blockers and set blocked for blocking findings; if review passes with final evidence, close the task per task.
14. Complete final checklist: design match, no logic gaps, security addressed, integration points verified, tests cover changes, docs updated.

Done: if the checklist passes, the feature is ready to push and create a PR. If blocking issues remain, return to dev-implementation or dev-testing.

Dev Testing

Run testing work for configured AI docs features. Before changing docs or code, propose the concrete plan for this phase and wait for user approval unless the user already approved the exact phase plan.

Phase Contract

1. Run npx ai-devkit@latest lint before phase work.
2. If working on a named feature, run npx ai-devkit@latest lint --feature <name>.
3. Read the testing doc, requirements, design, implementation notes, and current diff before changes.
4. Apply the verify skill before making coverage or test-pass claims.
5. If parent dev-lifecycle established usable task tracing, emit testing phase, next-action, and evidence events per task.

Write Tests

Use for Phase 8.

1. Run npx ai-devkit@latest lint --feature <name> and reference the testing doc path it validates. If manual path resolution is unavoidable, first resolve .ai-devkit.json paths.docs, falling back to docs/ai.
2. Gather context: feature name, changes summary, environment, existing test suites, flaky tests to avoid.
3. Analyze the testing template, success criteria, edge cases, available mocks, and fixtures.
4. Add unit tests for happy paths, edge cases, and error handling for each module. Highlight missing branches.
5. Add integration tests for critical cross-component flows, setup/teardown, and boundary/failure cases.
6. Run coverage tooling, identify gaps, and suggest additional tests if below the target.
7. If task tracing is available, record evidence for each fresh test/coverage command per task.
8. Update the selected testing doc with test file links and results.

Next: dev-review. If tests reveal design flaws, return to dev-design.

Dev Worktree

Set up or resume the correct workspace before feature work. Keep this skill focused on repository context, worktree isolation, and dependency bootstrap. Do not perform requirements, design, planning, implementation, testing, or review work here.

Phase Contract

1. Propose the exact workspace plan before changing branch or worktree state.
2. Confirm the target branch/worktree with the user before switching contexts.
3. Use feature-<name> for branch and worktree names, where <name> is normalized kebab-case without the prefix.
4. Prefer a project-local worktree at <project-root>/.worktrees/feature-<name>.
5. Use no-worktree mode only when the user explicitly requests it.
6. Run all follow-up commands in the verified target context.

Start Feature Workspace

Use for a new feature start.

1. Normalize feature name to kebab-case <name>.
2. Determine the project root, the directory containing .git.
3. If the user explicitly requests no worktree:
   • Continue in the current repository and branch.
   • Call out that branch/workspace isolation is reduced.
   • Skip to dependency bootstrap.
4. Otherwise use branch/worktree name feature-<name>.
5. Ensure .worktrees is listed in the project .gitignore; if not, add it.
6. If branch does not exist, run git worktree add -b feature-<name> .worktrees/feature-<name>.
7. If branch exists and the target worktree does not, run git worktree add .worktrees/feature-<name> feature-<name>.
8. If the target worktree already exists, reuse it after verifying it is clean enough for the requested work.
9. Verify worktree context with git -C .worktrees/feature-<name> branch --show-current; it must equal feature-<name>.
10. Return the active workdir path for the next phase.

Resume Feature Workspace

Use when continuing an existing feature.

1. Check current branch with git branch --show-current.
2. Check available worktrees with git worktree list.
3. Prefer <project-root>/.worktrees/feature-<name> when it exists.
4. Otherwise use branch feature-<name> in the current repository.
5. Include the selected target in the plan and wait for approval before switching.
6. After approval, run future phase commands in the selected context.

Dependency Bootstrap

After selecting the target context:

1. Detect ecosystem from lockfiles, manifests, and tooling configs.
2. Prefer deterministic lockfile-based installs.
3. Use the repository-native command:
   • JavaScript/TypeScript: npm ci, pnpm install --frozen-lockfile, yarn install --frozen-lockfile, or bun install --frozen-lockfile.
   • Python: uv sync, poetry install --no-interaction, pipenv sync, or pip install -r requirements.txt.
   • Ruby: bundle install.
   • Rust: cargo fetch, or cargo build when fetch-only is insufficient.
   • Go: go mod download.
   • Java/Kotlin: ./gradlew dependencies, ./gradlew build, or Maven equivalent.
4. If no dependency manager is clearly detectable, continue and state what was checked.

Output

End with:

• Active workdir.
• Branch name.
• Whether worktree or no-worktree mode is active.
• Dependency bootstrap command run, or why it was skipped.
• Any workspace risks or blockers.

Code Documentation Assistant

Build structured understanding of code entry points with an analysis-first workflow.

Hard Rule

• Do not create documentation until the entry point is validated and analysis is complete.

Workflow

1. Gather & Validate

• Confirm entry point (file, folder, function, API), purpose, and desired depth.
• Verify it exists; resolve ambiguity or suggest alternatives if not found.
• Search for existing knowledge before analyzing: npx ai-devkit@latest memory search --query "<entry point name or purpose>"

2. Collect Source Context

• Summarize purpose, exports, key patterns.
• Folders: list structure, highlight key modules.
• Functions/APIs: capture signature, parameters, return values, error handling.

3. Analyze Dependencies

• Build dependency view up to depth 3, track visited nodes to avoid loops.
• Categorize: imports, function calls, services, external packages.
• Exclude external systems or generated code.

4. Synthesize

• Overview (purpose, language, high-level behavior).
• Core logic, execution flow, patterns.
• Error handling, performance, security considerations.
• Improvements or risks discovered during analysis.

5. Create Documentation

• Normalize name to kebab-case (calculateTotalPrice → calculate-total-price).
• Create docs/ai/implementation/knowledge-{name}.md using the Output Template — this is the source of truth.
• Include mermaid diagrams when they clarify flows or relationships.

6. Offer HTML Artifact

• After the markdown is written, ask the user once: "Also generate an HTML artifact for easier scanning? (y/N)".
• If yes, generate sibling docs/ai/implementation/knowledge-{name}.html per the HTML Artifact spec. Regenerate from the markdown on subsequent runs; never hand-edit.
• If no or no response, stop here — markdown alone is a complete result.

HTML Artifact

Generated only when the user opts in at step 6. A self-contained HTML file optimized for scanning, not reference reading. Complements the markdown — does not replace it.

Constraints:

• Single file. Inline CSS. No build step. Only external asset allowed is mermaid via CDN (https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js).
• Card-based grid layout, not a long scroll. The reader should capture structure at a glance.
• Responsive down to laptop width. Print-friendly.
• No interactivity beyond collapsible deep-dives and mermaid pan/zoom.

Section mapping (from the Output Template):

• Overview → hero card: title, one-line purpose, language/type badges.
• Implementation Details → grid of sectioned cards with short bullets, not prose.
• Dependencies → graph card (mermaid) plus a categorized list (imports, calls, services, external).
• Visual Diagrams → full-width rendered mermaid blocks.
• Additional Insights → callout boxes, color-coded by kind (info, warning, risk).
• Next Steps → checklist card.
• Metadata → compact footer (date, depth, files touched).

Red Flags and Rationalizations

Validation

• Documentation covers all Output Template sections.
• If an HTML artifact was generated, it opens standalone in a browser, renders mermaid, and reflects the markdown content (no drift).
• Summarize key insights, open questions, and related areas for deeper dives.
• Confirm file path(s) and remind to commit.

Output Template

• Overview
• Implementation Details
• Dependencies
• Visual Diagrams (mermaid)
• Additional Insights
• Metadata (date, depth, files touched)
• Next Steps

AI DevKit Memory CLI

Use npx ai-devkit@latest memory ... as the durable knowledge layer.

Workflow

1. For implementation, debugging, review, planning, or documentation tasks, search before deep work unless the task is trivial:

   npx ai-devkit@latest memory search --query "<task, subsystem, error, or convention>" --limit 5
   

   For broad or risky tasks, search multiple angles: subsystem, error text, framework, command, and task intent.

2. Use results as context:

   • Trust repo files, tests, fresh command output, and explicit user instructions over memory.
   • If memory conflicts with verified evidence, use the evidence and update the stale memory.
   • Mention memory only when it changes the plan or avoids asking the user again.

3. Search before storing:

   npx ai-devkit@latest memory search --query "<knowledge to store>" --table
   

4. Store or update only after the quality gate passes.

Quality Gate

Before storing, all must be true:

• Future sessions are likely to reuse it.
• It is verified by code, docs, tests, command output, or explicit user instruction.
• It is not merely a restatement of obvious nearby files unless it prevents repeated agent mistakes.
• It is scoped narrowly enough.
• Existing memory does not already cover it.
• It contains no secrets, credentials, private customer data, personal data, raw logs, or temporary paths.

Store:

• Project conventions, user preferences, durable decisions.
• Reusable fixes, testing patterns, commands, setup gotchas.
• Non-obvious constraints, architecture rules, failure patterns.

Do not store:

• Task progress, transcripts, speculation, generic programming facts.
• Raw errors without diagnosis.
• Anything the user did not intend to persist.

Commands

Search

npx ai-devkit@latest memory search \
  --query "<query>" \
  --tags "<tags>" \
  --scope "<scope>" \
  --limit 5

Use --table to get IDs for updates:

npx ai-devkit@latest memory search --query "<query>" --table

Options: --query/-q required; --tags; --scope/-s; --limit/-l from 1-20; --table.

Store

npx ai-devkit@latest memory store \
  --title "<actionable title, 10-100 chars>" \
  --content "<context, guidance, evidence, exceptions>" \
  --tags "<lowercase,tags>" \
  --scope "<global|project:name|repo:org/repo>"

Use this content shape when helpful:

Context: Where this applies.
Guidance: What to do.
Evidence: File, command, test, or user instruction.
Exceptions: When not to apply it.

Update

Find the ID with search --table, then update only changed fields:

npx ai-devkit@latest memory update \
  --id "<memory-id>" \
  --title "<updated title>" \
  --content "<updated content>" \
  --tags "<replacement,tags>" \
  --scope "<updated scope>"

--tags replaces all existing tags.

Scoping

Use the narrowest useful scope:

• repo:<org/repo> for one repository.
• project:<name> for one app, product, or workspace.
• global only for knowledge that applies across unrelated projects.

If unsure, use a narrower scope.

Troubleshooting

• CLI missing: run npx ai-devkit@latest --version.
• Duplicate title: search, then update the existing item if it is the same knowledge.
• Empty results: broaden terms, remove filters, or search symptoms and subsystem names separately.
• Validation error: check title/content lengths, query length, and --limit range.
• DB path: default is ~/.ai-devkit/memory.db; project config can override it automatically.

Security Review

Find vulnerabilities before they ship.

Hard Rules

• Do not dismiss a finding without evidence it is unexploitable.
• Do not commit, log, or surface secrets discovered during review — flag and recommend rotation.
• Do not modify code until the user approves a remediation plan.

Workflow

1. Scope

   • Confirm target: diff, file set, module, full repo, or skill/prompt. A target can be both code and prompt.
   • Identify stack/framework — adapt the checklist (skip what the framework handles, add its pitfalls).
   • Trace data flow: request → middleware → handler → service → datastore → response. For prompts: input → template → LLM → tools → output.
   • Map trust boundaries, privilege levels, and threat actors.
   • Search prior findings: npx ai-devkit@latest memory search --query "<target>" --tags "security"

2. Scan

   • Only check relevant categories. Skip sections and items that don't apply. Do not report skipped items.
   • For diffs/PRs: also check whether the change weakens existing controls — removed middleware, bypassed validation, new unprotected routes.
   • Categories in priority order: a. Secrets — hardcoded tokens, keys, connection strings. b. Injection — SQL, NoSQL, command, template, SSRF, path traversal, XSS. c. Auth — missing checks, privilege escalation, OAuth/OIDC, IDOR. d. Business Logic — race conditions, TOCTOU, workflow bypass, mass assignment, parameter tampering. e. Data Exposure — PII in logs, verbose errors, overly broad responses. f. Resource Exhaustion — unbounded queries, missing pagination, upload size, decompression bombs. g. Dependencies — critical CVEs only (RCE, auth bypass, data breach); ignore low/medium. h. Cryptography — weak algorithms, hardcoded IVs/keys, disabled certificate validation. i. Configuration — debug mode, permissive CORS, missing security headers. j. Logging — security events unlogged, no tamper protection, no alerting. k. Prompt Injection — instruction override, tool abuse, data exfiltration, indirect injection via tool results.
   • For each finding: file, line, evidence.

3. Classify

   Severity	Criteria
   Critical	Exploitable now, data loss or RCE possible
   High	Exploitable with moderate effort or insider access
   Medium	Requires chained conditions or limited impact
   Low	Defense-in-depth, no direct exploit path

   • Adjust severity by exposure (internet-facing vs internal) and data sensitivity.
   • Check for attack chains — multiple Medium findings that combine into High/Critical.
   • Mark false positives with reasoning.

4. Remediate

   • For each finding: root cause, minimal fix (prefer stdlib/framework over custom), verification step.
   • For Critical/High: also recommend a detection control (log, alert, or WAF rule).
   • Present plan and request approval before changing code.

5. Verify

   • Use the verify skill to confirm each remediation.
   • Re-scan fixed files for regressions.
   • Store findings: npx ai-devkit@latest memory store --title "<pattern>" --content "<finding and fix>" --tags "security,<category>"

Red Flags

Output Template

• Scope: Target, stack, data flow, trust boundaries, threat actors
• Findings (by severity): ID, severity, category, file:line, exploit scenario, fix
• Attack Chains: Findings that escalate when combined
• False Positives: Dismissed items with reasoning
• Remediation Plan: Ordered fixes with verification steps
• Residual Risk: Scope limitations, unverifiable items
• Zero findings: state what was checked and scope boundaries — "no findings" ≠ "fully secure"

Simplify Implementation Assistant

Reduce complexity with an analysis-first approach before changing code.

Hard Rules

• Do not modify code until the user approves a simplification plan.
• Readability over brevity. Some duplication beats the wrong abstraction.
• Prefer reusing an existing function over introducing a new one — but only if it fits cleanly. Do not force-fit a near-match.
• Before improving code, ask whether the function, abstraction, dependency, or custom logic needs to exist at all.
• Prefer platform and standard-library features over custom code or dependencies. Use already-installed dependencies when they cleanly solve the problem; do not add a dependency for logic that is only a few clear lines.
• For breaking changes: modify in place only when all callers are in-repo and updated in the same change. For public/external APIs, add a new function and deprecate the old one (parallel change).

Workflow

1. Gather Context

• Confirm targets, pain points, and constraints (compatibility, API stability, deadlines).
• Search for past simplification decisions or known constraints: npx ai-devkit@latest memory search --query "<target area>" --tags "simplify"

2. Analyze Complexity

• Identify sources (nesting, duplication, coupling, over-engineering, magic values).
• Run an existence check: can this code be deleted, delegated to the standard library, handled by a native platform feature, enforced by the database, or covered by an existing dependency?
• Assess impact (LOC, dependencies, cognitive load, scalability blockers).

3. Apply Readability Principles

• Apply the readability guide and its "Reading Test".

4. Propose Simplifications For each issue, apply a pattern:

• Extract: Long functions → smaller, focused functions.
• Consolidate: Duplicate code → shared utilities.
• Flatten: Deep nesting → early returns, guard clauses.
• Decouple: Tight coupling → dependency injection, interfaces.
• Remove: Dead code, unused features, excessive abstractions.
• Replace: Custom logic → standard-library, native platform, database, or already-installed dependency features.
• Defer: Premature optimization → measure-first approach.

5. Prioritize and Plan

• Rank by impact/risk. Present plan with before/after snippets. Request approval.

Red Flags and Rationalizations

Validation

• Verify no regressions, add tests for new helpers, update docs if interfaces changed.

Output Template

• Target and Context
• Complexity Analysis
• Simplification Proposals (prioritized)
• Recommended Order and Plan
• Scalability Recommendations
• Validation Checklist

Local Debugging Assistant

Debug with an evidence-first workflow before changing code.

Hard Rule

• Do not modify code until the user approves a selected fix plan.

Workflow

1. Clarify

• Restate observed vs expected behavior in one concise diff.
• Confirm scope and measurable success criteria.
• Before investigating, search for similar past incidents: npx ai-devkit@latest memory search --query "<observed behavior>" --tags "debug,root-cause"

2. Reproduce

• Capture minimal reproduction steps.
• Capture environment fingerprint: runtime, versions, config flags, data sample, and platform.

3. Hypothesize and Test For each hypothesis, include:

• Predicted evidence if true.
• Disconfirming evidence if false.
• Exact test command or check.
• Prefer one-variable-at-a-time tests.

4. Plan

• Present fix options with risks and verification steps.
• Recommend one option and request approval.

Validation

• Confirm a pre-fix failing signal exists.
• Confirm post-fix success using the verify skill — including regression verification for bug fixes.
• Summarize remaining risks and follow-ups.
• Store root cause and fix for future sessions: npx ai-devkit@latest memory store --title "<root cause>" --content "<diagnosis and fix>" --tags "debug,root-cause"

Task Tracing

If task tracing is usable, choose a short kebab-case debug task name when no task name exists, then use task optionally: record repro/final results as evidence, the current hypothesis as next, and blockers only when they materially affect progress. Never block debugging because task tracing is unavailable.

Red Flags and Rationalizations

Output Template

Use this response structure:

• Observed vs Expected
• Repro and Environment
• Hypotheses and Tests
• Options and Recommendation
• Validation Plan and Results
• Open Questions

Task Progress Tracking

Record development progress on a durable task: phase, progress, next step, blockers, and validation evidence.

Requires the optional task command. Use npx ai-devkit@latest for task and agent commands. Before recording task events, run a real read probe:

npx ai-devkit@latest task list --json
# or, when a task name is known:
npx ai-devkit@latest task list --name <task-name> --json

Only treat task tracing as available when the read probe exits 0. If it fails, continue without task logging and include the failed command plus stderr/stdout summary in the final report. Do not block the user's work just because optional task tracing is unavailable or unusable.

Core idea

• One task per work item. Create it once; advance its phase field as work moves through the lifecycle or debug workflow.
• <id> can be a task name. Every command below accepts the task name in place of a task id, resolving to the latest non-terminal task. Prefer <task-name> so agents do not track task ids.
• Choose stable names. For lifecycle work, use the feature key as the task name. For debugging or review work, choose a short kebab-case task name.
• Emit at checkpoints, not streaming. Phase transitions, task toggles, immediate next-step changes, fresh evidence, blockers discovered/resolved. A handful of calls per session.
• Sequence mutations. Never run task mutation commands in parallel for the same task. Each mutation reads the current task snapshot and writes it back; parallel writes can clobber snapshot fields even though events append. Run create/assign/phase/next/progress/evidence/blocker/artifact/close commands one at a time, then read back with show --events --json when the final state matters.
• Attribution is explicit. Identify self once, then pass actor flags on mutation commands.

Identify self

Use agent-management when attribution is needed:

1. Run the agent-management self-identification workflow with npx ai-devkit@latest agent list --json.
2. Match the current agent entry from that list. Prefer an exact session match when available; otherwise use the unambiguous entry for the current project/worktree.
3. Build actor flags from the matched entry: --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId>. Map JSON fields directly: name -> --agent, type -> --agent-type, pid -> --pid, and sessionId -> --session.
4. If identity is ambiguous, do not guess. Continue task logging without actor flags rather than fabricating attribution.
5. Add --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> to every mutation command once known. If a task already exists, run npx ai-devkit@latest task assign <task-name> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json once so the task snapshot has current ownership.
6. If actor identity is unknown, run the same mutation commands without the four actor flags.

Canonical commands

When self identity is known, add all four actor flags to every mutation command: --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId>.

# Create the task once (capture taskId from --json if needed)
npx ai-devkit@latest task create --title "<title>" --name <task-name> --phase requirements --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# If the task already exists, assign current ownership once when known
npx ai-devkit@latest task assign <task-name> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Mark real work as active after create/resume
npx ai-devkit@latest task status <task-name> active --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Advance phase as the lifecycle moves on
npx ai-devkit@latest task phase <task-name> implementation --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Progress (use --text; positional text is ignored)
npx ai-devkit@latest task progress <task-name> --text "Implementing task CLI" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Next step
npx ai-devkit@latest task next <task-name> "Run validation" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Blockers
npx ai-devkit@latest task status <task-name> blocked --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task blocker <task-name> add "Waiting for review" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task blocker <task-name> resolve <blocker-id> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task status <task-name> active --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Validation evidence - record after a fresh verify/tdd/test run
npx ai-devkit@latest task evidence <task-name> --passed --command "npm test" --exit-code 0 --summary "tests passed" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Reference an artifact (never copies the file)
npx ai-devkit@latest task artifact <task-name> docs/ai/testing/foo.md --kind test-report --description "Testing notes" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Read current status / list
npx ai-devkit@latest task show <task-name> --json
npx ai-devkit@latest task list --name <task-name> --json

# Close at lifecycle end
npx ai-devkit@latest task close <task-name> completed --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

When to emit (by workflow)

• dev-lifecycle - real read probe first; create at start when no non-terminal task exists for the feature; assign once when actor is known; set status active when real work starts or resumes; phase on every phase transition; next after phase planning; progress after planning/implementation task toggles; show at resume; close completed only after final verification/review is done.
• verify / tdd / dev-testing - evidence after fresh proof (this is what makes "last validation" trustworthy). Use --failed when it fails.
• structured-debug - reuse the same commands: evidence for repro results, next for the next hypothesis, blocker add/resolve, progress.
• Any phase - blocker add when blocked, resolve when clear; next to state the immediate next step. Set status blocked when an open blocker stops progress, and set status active again after the blocker is resolved.

Tips

• Add --json when an agent must parse output (create/show/list). Omit for human-readable checks.
• Don't restate obvious nearby files or transient state; keep summaries short.
• Good task records let a later reader answer: who worked on it, which phase it reached, what changed, what is next, what verified the claim, and what blocked or changed scope. Do not log every command; do log those checkpoints.

TDD

Red. Green. Refactor. In that order, every time.

Hard Rules

• No production code without a failing test first.
• If production code was written before its test, delete it and start over with a failing test.
• Never skip the red step. A test that has never failed proves nothing.

Cycle

For each unit of behavior:

1. Red — Write a test for the next behavior. Run it. It must fail. Read the failure message — it should describe the missing behavior.
2. Green — Write the minimum production code to make the test pass. Nothing more. Run the test. Apply the verify skill.
3. Refactor — Clean up both test and production code. Run the test again. Still green? Done. Apply the verify skill.

Then pick the next behavior and repeat.

Rules for Each Step

Red:

• Test one behavior, not one function. Name the test after what the system should do, not what the function is called.
• The test must fail for the right reason — a missing method, wrong return value, unmet condition. Not a syntax error or import failure.
• If the test passes immediately, it's not testing new behavior. Delete it or pick a different behavior.

Green:

• Write the simplest code that passes. Hardcode if needed — the next test will force generalization.
• Do not add code "while you're in there." If it's not required by a failing test, it doesn't exist yet.
• Do not refactor during green. Pass first, clean second.

Refactor:

• Remove duplication between test and production code.
• Extract only when you see real duplication, not predicted duplication.
• Tests must still pass after every refactor move. Run them after each change.

Anti-Patterns

Red Flags and Rationalizations

Memory Integration

After completing a TDD session, store reusable test patterns (setup, assertions, fixtures): npx ai-devkit@latest memory store --title "<pattern>" --content "<details>" --tags "tdd,testing"

Technical Writer Review

Review documentation as a novice would experience it. Suggest concrete improvements.

Hard Rules

• Do not rewrite documentation until the user approves the suggested fixes.
• Suggest concrete fix text, not vague advice.

Review Dimensions (rate 1-5)

• Clarity: Can a novice understand it without outside help?
• Completeness: Are prerequisites, examples, and edge cases covered?
• Actionability: Can users copy-paste commands and follow along?
• Structure: Does it flow logically from simple to complex?

Priority

• High: Blocks novice users from succeeding.
• Medium: Causes confusion but workaround exists.
• Low: Polish and nice-to-have.

Red Flags and Rationalizations

Output Template

## [Document Name]

| Aspect | Rating | Notes |
|--------|--------|-------|
| Clarity | X/5 | ... |
| Completeness | X/5 | ... |
| Actionability | X/5 | ... |
| Structure | X/5 | ... |

**Issues:**
1. [High] Description (line X)
2. [Medium] Description (line X)

**Suggested Fixes:**
- Concrete fix with example text

Verify

Prove it works before saying it works.

Hard Rules

• Do not claim completion without fresh terminal evidence from this session.
• Forbidden words in completion claims: "should", "probably", "seems to", "likely", "I believe", "I think it works". These signal unverified assertions.
• Cached, remembered, or previous-session output is not evidence. Run it again.

Gate Function

Every completion claim must pass all 5 steps in order:

1. Identify — What command proves this claim? If multiple commands are needed, run the gate once per command.
2. Run — Execute the full command now. No partial runs, no skipping.
3. Read — Read complete output. Check exit code. Count pass/fail.
4. Confirm — Does the output prove the exact claim?
5. Report — State the result, cite command, exit code, and key output.

If any step fails, stop. Fix the issue and restart from step 1.

If no verification command exists (e.g., no test suite), tell the user and ask them how to verify before claiming done.

Verification Patterns

Regression Verification

For bug fixes, a single pass is not enough:

1. Write a test covering the bug.
2. Run → must pass (fix in place).
3. Revert the fix.
4. Run → must fail (proves test catches the bug).
5. Restore the fix.
6. Run → must pass.

If step 4 passes, the test is wrong. Rewrite it.

Red Flags and Rationalizations

Memory Integration

After a failed verification, store the failure pattern: npx ai-devkit@latest memory store --title "<failure pattern>" --content "<what failed and how to avoid>" --tags "verify,failure-pattern"

Task Tracing

If a task name is known and tracing is usable, record task evidence after the verification report per task. If tracing was not probed, run the real read probe first. If probe or evidence recording fails, report the failed task command and continue verification; never block verification on optional task logging.