AI DevKit

View saved version →

---
name: agent-communication
description: AI DevKit · Exchange information with active Codex, Claude Code, and other AI agents using ai-devkit agent list, detail, and send. Use when an agent needs to find another active agent, read its recent context, send it information, or request information back.
---

# 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

```bash
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.

Referenced files: 1

View saved version →

---
name: agent-management
description: AI DevKit · Manage running AI agents with ai-devkit agent commands. Use when an agent needs to identify itself, list agents, start workers, inspect agent detail, assign work, group agents, resume sessions, stop agents, or delegate work to other agents.
---

# 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

```bash
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:

```bash
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."
```

Referenced files: 1

View saved version →

---
name: agent-orchestration
description: "AI DevKit · Supervise multi-agent workflows over repeated passes: poll progress, unblock waiting agents, coordinate dependencies, relay outputs, resolve conflicts, and verify completion. Use only for ongoing multi-agent coordination, not one-off list/detail/send/start/kill actions."
---

# Agent Orchestration

Use only for multi-agent supervision: coordinating dependencies, polling progress, unblocking waiting agents, relaying outputs, resolving conflicts, and verifying completion across agents. For one-off list/detail/send/start/kill work, use `$agent-management` or `$agent-communication`.

Use `$agent-management` for safe agent selection and lifecycle actions. Use `$agent-communication` for list/detail/send mechanics. Use `$verify` before accepting any agent's completion claim.

## Rules

- Own the loop until assigned work is complete, blocked, or stopped.
- Run `agent list --json` before each pass; never assume names/statuses.
- Inspect waiting, idle, unknown, missing, or stale agents before acting.
- Send self-contained instructions and avoid duplicate follow-ups.
- Sequence agents that touch the same files; relay only relevant upstream output.
- Escalate only for repeated failures, unresolved conflicts, product/business decisions, or destructive/shared/production/security-sensitive actions.

## Loop

If the goal or agent ownership is unclear, run one scan/detail pass. Ask the user once only if context is still insufficient.

1. Scan agents.
2. Assess agents needing attention with `detail --tail 10`.
3. Act: approve, clarify, correct, delegate, relay, verify, or escalate.
4. Report one brief status line.
5. Sleep 10-60s and repeat.

## Completion

Finish when all assigned work is verified, blocked with a clear reason, or stopped by the user. Summarize per-agent outcomes, verification, unresolved issues, and next step.

Referenced files: 1

View saved version →

---
name: ai-devkit-setup
description: AI DevKit · Check local AI DevKit readiness and run setup only when status shows onboarding or harness integration gaps.
---

# AI DevKit Setup

Use this skill when a user wants to onboard AI DevKit, prepare a harness, repair local AI DevKit integration, or check whether setup is needed.

Keep the workflow status-driven and simple. Prefer the installed `ai-devkit` binary; if it is unavailable, use `npx ai-devkit@latest`.

## Execution Notes

- Under filesystem sandboxing, run `ai-devkit status --json` and any `ai-devkit setup` command outside the sandbox. These commands inspect and modify host-level agent configuration; sandboxed runs can produce false failures or block setup writes, especially for integrations that execute harness commands and access paths like `~/.pi/agent`.

## Workflow

1. Run readiness first:

   ```bash
   ai-devkit status --json
   ```

2. Identify failed or warning checks that setup can fix. Setup covers local integrations like hooks, built-in skills, and session tracking for `codex`, `pi`, and `claude`; it does not fix auth, missing package managers, or host tools requiring user installation.

3. Run the narrowest setup command, for example:

   ```bash
   ai-devkit setup --agent codex,pi,claude
   ```

   If the user asked for broad onboarding and several supported harnesses need setup, `ai-devkit setup` is acceptable.

4. Re-run `ai-devkit status --json` and report what changed plus any remaining manual actions.

## Boundaries

- Do not run setup before checking status unless the user explicitly asks to force setup.
- Do not claim setup is complete without a fresh status check from this session.
- Do not modify secrets, auth tokens, or unrelated harness config manually. Point the user to the failing status item instead.
- Ask before destructive cleanup or replacing existing user-managed configuration.
- Keep output concise: status command, setup command if run, final readiness, and remaining user actions.

Referenced files: 1

View saved version →

---
name: brainstorm
description: AI DevKit · Use when the user asks to brainstorm, ideate, generate ideas, expand options, challenge ideas, pressure-test ideas, compare concepts, narrow choices, name something, plan content angles, explore strategy, evaluate product ideas, technical approaches, experiments, or decisions.
---

# Brainstorm

Run a compact diverge-to-converge loop.

## Workflow

1. Frame: goal, constraints, audience, success criteria, assumptions.
2. Baseline: state the simplest honest solution first. Every option must beat it; the baseline stays a candidate.
3. Diverge: distinct options across practical, high-leverage, and unusual angles.
4. Challenge: weak assumptions, failure modes, tradeoffs, rejections. Always: reject speculative generality (each abstraction, layer, flag, and data copy needs a current caller) and verify load-bearing "needed" claims in the consuming code, not doc assertions.
5. Compare: only relevant criteria, plus deletion cost (how easily the option can be removed later). Ties go to the smaller option.
6. Converge: strongest 3 picks with rationale and a next step. Self-review first: for each new constant, object, layer, and flag ask "why do we need this?" Cut answers that are only messaging or future-proofing.

## Formats

Use Quick by default. Use Deep only for ambiguous or high-stakes decisions. Ask at most one clarifying question only if missing context would materially change the brainstorm; otherwise state assumptions and proceed.

- Quick: clusters, challenges, 3 picks.
- Deep: assumptions, clusters, evaluation table, recommendation.
- Naming: tone groups, fit, ambiguity, pronunciation.
- Technical: approaches, tradeoffs, risks, validation.
- Content: angles, hooks, audiences, outlines.

Avoid filler, near-duplicates, generic best practices, premature recommendations, and scope without a current caller. If asked for more ideas, explore a new axis before listing variants.

View saved version →

---
name: changelog
description: AI DevKit · Update CHANGELOG.md Unreleased items from git commits since the latest release. Use when users ask to update changelog/release notes from recent commits, with one concise line per commit and commit/PR links.
---

# 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.

Referenced files: 1

View saved version →

---
name: dev-commit
description: AI DevKit · Safe git commit workflow for AI coding agents. Use when the user asks to commit, prepare a commit, stage changes, create a PR-ready checkpoint, or finish work with a conventional commit while avoiding unrelated user changes.
---

# 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. In workspaces whose packages resolve against built artifacts, ensure install and build have run in that worktree (`npm ci`, `npm run build`) before full validation or commit hooks; a fresh worktree with stale artifacts fails hooks for environmental reasons.
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. If a hook fails, first rule out environmental causes (missing install, stale workspace build artifacts, concurrent test runs sharing resources) by re-running the failing package in isolation; do not treat an environmental failure as a code regression or "stop" condition until isolated runs still fail.

## 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.

Referenced files: 1

View saved version →

---
name: dev-design
description: AI DevKit · Design phase guidance for reviewing feature design against requirements. Use when the user wants to validate architecture, review design docs, resolve design trade-offs, or run dev-lifecycle phase 3.
---

# 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. Check usage-first design: APIs, CLI flows, UI flows, and docs should optimize for their caller/user, not implementation convenience.
6. Screen design red flags: shallow modules, pass-through layers, temporal decomposition, leaked transport/storage/framework types, scattered validation, synchronized flags, and repeated conditionals where a domain model would fit.
7. Resolve every gap, misalignment, open question, hidden assumption, or unresolved trade-off between requirements and design.
8. Brainstorm alternatives for key architecture decisions and trade-offs before accepting the first approach.
9. Prefer subtract-before-add sequencing: delete obsolete paths, consolidate redundant concepts, and narrow scope before adding new structure.
10. Update the design doc with clarified decisions and chosen options.
11. Store reusable architecture decisions in memory.
12. If task tracing is available, record design coverage progress, next step, or blockers per `task`.
13. 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.

Referenced files: 1

View saved version →

---
name: dev-implementation
description: AI DevKit · Implementation phase guidance for executing feature plans and checking implementation against design. Use when the user wants to implement planned tasks, update implementation docs, verify code matches design, or run dev-lifecycle phases 5 and 7.
---

# 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. Subtract before adding: delete dead paths, redundant guards, stale tests, and one-caller wrappers when they are in task scope.
9. Handle breaking changes carefully: update all in-repo callers atomically and delete the old internal API; for external/public/cross-service callers, add a new function and deprecate the old one.
10. Model the domain when implementation friction repeats: replace synchronized flags, branch growth, or duplicated shape assumptions with the smallest domain structure that removes them.
11. Generate a markdown tracking snippet after each status change.
12. 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.
13. After each section, ask if new tasks were discovered.
14. 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. Treat repeated implementation friction as a redesign signal, not another patch, and return to design when the model no longer fits.
6. Finalize the implementation doc. Verify it captures what shipped, fill gaps, and record follow-ups.
7. 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.

Referenced files: 1

View saved version →

---
name: dev-lifecycle
description: AI DevKit · Orchestrator for structured SDLC phase skills. Use when the user wants to run the full lifecycle or choose the next phase across requirements, design, planning, implementation, testing, and review.
---

# 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

| Phase | Route to | When |
|---|---|---|
| Setup. Workspace | `dev-worktree` | Starting or resuming feature work |
| 1. New Requirement | `dev-requirements` | User wants to add a feature or start `/new-requirement` |
| 2. Review Requirements | `dev-requirements` | Requirements doc needs validation |
| 3. Review Design | `dev-design` | Design doc needs validation against requirements |
| 4. Create Initial Plan | `dev-planning` | Requirements, design, and testing docs are ready for task breakdown |
| 5. Execute Plan | `dev-implementation` | Ready to implement tasks from planning doc |
| 6. Update Planning | `dev-planning` | Auto-trigger after completing any implementation task |
| 7. Check Implementation | `dev-implementation` | Verify code matches design and docs |
| 8. Write Tests | `dev-testing` | Add or verify test coverage |
| 9. Code Review | `dev-review` | Final pre-push review |

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.

Referenced files: 2

View saved version →

---
name: dev-planning
description: AI DevKit · Planning phase guidance for creating and reconciling feature task plans. Use when the user wants to create an implementation plan, update planning docs, mark task progress, capture blockers or new tasks, or run dev-lifecycle planning work.
---

# 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.

Referenced files: 1

View saved version →

---
name: dev-pr
description: AI DevKit · Publish a ready feature branch for review. Use when the user wants to sync, push, and open or update a code review request on GitHub, GitLab, or another Git host.
---

# 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

Referenced files: 1

View saved version →

---
name: dev-requirements
description: AI DevKit · Requirements phase guidance for starting features and reviewing requirements. Use when the user wants to capture a new requirement, clarify product scope, initialize feature docs, review requirements, or run dev-lifecycle phases 1-2.
---

# 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.

Referenced files: 1

View saved version →

---
name: dev-review
description: AI DevKit · Final code review phase guidance for holistic pre-push review. Use when the user wants code review, final lifecycle review, design alignment checks, integration risk review, or dev-lifecycle phase 9.
---

# 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 boundary discipline: external data is validated at edges, internal code is not littered with redundant guards, and transport/storage/framework types do not leak through domain APIs.
8. Check reader load: needless layers, pass-through methods, broad shallow interfaces, mutable state scope, and unclear value ownership.
9. Check domain fit: branch growth, synchronized flags, repeated shape assumptions, temporal decomposition, and missing state models.
10. Check dependency health, including circular dependencies or version conflicts from new imports.
11. Check breaking changes. For public/external APIs, recommend parallel change and deprecation over in-place mutation. For in-repo-only callers, all callers should be migrated and legacy APIs deleted.
12. Check rollback safety, especially irreversible migrations or one-way data/state changes.
13. Review file by file for correctness, logic, edge cases, redundancy, security, performance, error handling, and test coverage.
14. Check cross-cutting concerns: naming conventions, documentation updates, missing tests, config/migration changes.
15. Summarize blocking issues, important follow-ups, and nice-to-haves. Per finding include file, issue, impact severity, and recommendation.
16. If task tracing is available, add blockers and set `blocked` for blocking findings; if review passes with final evidence, close the task per `task`.
17. 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`.

Referenced files: 1

View saved version →

---
name: dev-testing
description: AI DevKit · Testing phase guidance for adding and validating feature test coverage. Use when the user wants to write tests, update testing docs, run coverage, close coverage gaps, or run dev-lifecycle phase 8.
---

# 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`.

Referenced files: 1

View saved version →

---
name: dev-worktree
description: AI DevKit · Worktree setup and resume guidance for isolated feature work. Use when starting, resuming, switching, or verifying a feature branch/worktree for lifecycle, debugging, implementation, review, or multi-agent workflows.
---

# 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. For workspaces whose packages resolve against built artifacts (for example `dist/` output consumed via workspace aliases), run the repository build (for example `npm run build`) after install. Full-suite validation and commit hooks fail on stale or missing artifacts with errors that look like code regressions. State when the build was skipped and why.
5. 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.
- Workspace build command run (when applicable), or why it was skipped.
- Any workspace risks or blockers.

Referenced files: 1

View saved version →

---
name: document-code
description: AI DevKit · Document a code entry point with structured analysis, dependency mapping, and saved knowledge docs. Use when users ask to document, understand, or map code for a module, file, folder, function, or API.
---

# 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

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "I already understand this code" | Understanding ≠ documented understanding | Write it down, then verify |
| "The code is self-documenting" | Future readers lack your current context | Capture the why, not just the what |
| "Dependencies are obvious" | Implicit dependencies cause surprises | Map them explicitly to depth 3 |

## 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

Referenced files: 1

View saved version →

---
name: memory
description: AI DevKit · Use the memory CLI as a durable knowledge layer. Search before non-trivial work, store verified reusable knowledge, update stale entries, and avoid saving transcripts, secrets, or one-off task progress.
---

# 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:
   ```bash
   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:
   ```bash
   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

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

Use `--table` to get IDs for updates:

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

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

### Store

```bash
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:

```text
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:

```bash
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.

Referenced files: 1

View saved version →

---
name: refactor
description: AI DevKit · Systematic structural or multi-file refactors across any stack while preserving behavior and public contracts. Use for reorganizing modules, boundaries, naming, APIs/contracts, staged refactor plans, or refactor risk review.
---

# Refactor

Use for structural refactors. Use `simplify-implementation` for local readability, dead code, or small logic cleanup.

## Rules

- Preserve behavior and public contracts unless changes are explicit.
- Classify first: small = local/no public movement; medium = multi-file/extraction/boundary/export touch; large = package/cross-package/staged migration/broad consumers.
- For medium/large refactors, write a brief before editing: evidence, pressure, remaining delta, do/defer/avoid ranking, non-goals, contracts, target shape, validation, compatibility.
- Do not propose target trees without current-code evidence: tree, file size/mixed concerns, imports/exports, consumers, validation commands.
- Separate moves/renames from logic changes and design/API behavior questions.
- Prefer existing conventions, provider locality, and the smallest structure that solves observed pressure.
- Subtract before adding: remove dead wrappers, redundant validators, stale exports, and unused paths before introducing new structure.
- Avoid taste refactors, premature abstractions, and thin one-file directories unless staged or conventional.
- Validate with fresh command output.

## Workflow

1. Discover stack, configs, entry points, exact validation commands, and prior decisions when available.
2. Map contracts: exports, APIs, routes, CLI, config, schemas, events, files, docs, examples, consumers.
3. Map structure: directories, naming, boundaries, dependency direction, cycles, mixed concerns, duplication.
4. Check reader load: can a new reader find where key state comes from and what can change it quickly? Collapse pass-through layers that do not hide policy, adaptation, or real complexity.
5. If continuing work, compare current state and list only remaining delta.
6. Choose refactor type and shape:
   - extraction, reorganization, or design refactor
   - flat/internal, feature-first, domain-first, layer-first, core/adapters/entrypoints, service/repository
   - adapter-heavy: provider-specific stays provider-local; shared pure logic -> shared/core/formatting; SDK/client code -> adapter/entrypoint/delivery
7. Check boundary discipline: validate at CLI/config/network/external API edges; keep internal logic typed, domain-shaped, and pure where practical.
8. Prefer domain structure over repeated conditionals: state machine, typed model, registry/map, reducer, or ownership-focused module when it deletes branches or invalid states.
9. Rank moves as do now, defer, or avoid.
10. Stage: baseline -> delete dead paths -> move/rename -> imports/call sites -> split/merge -> simplify -> exports/docs/tests.
11. For internal API changes, inventory callers, migrate them, and delete the legacy API in the same wave when no external contract requires compatibility.
12. Preserve or explain compatibility re-exports/wrappers/barrels like `types.ts` plus `types/`.
13. Validate: tests, compile/typecheck, lint, build, public/downstream smoke checks, diff review.

## Stop

Pause when contracts are unclear, baseline cannot be checked and no narrower validation exists, breaking changes need migration decisions, ownership/product decisions are required, or the work is becoming a rewrite.

Referenced files: 1

View saved version →

---
name: remote-from-slack
description: AI DevKit · Connect the current agent session to an available Slack channel bridge.
---

# Remote From Slack

Use this skill when the user wants to control or chat with the current session from Slack.

Prefer the installed `ai-devkit` binary; if unavailable, use `npx ai-devkit@latest`. Run AI DevKit commands outside filesystem sandboxes because they inspect host-level agent and channel state.

## Workflow

1. Check readiness:

   ```bash
   ai-devkit status --json
   ```

   If AI DevKit is not ready, use `ai-devkit-setup` skill first. Stop if setup leaves manual actions.

2. Inspect channels and agents:

   ```bash
   ai-devkit channel list
   ai-devkit agent list --json
   ```

3. Identify the current agent by matching this session to an `agent list --json` entry. If unclear, ask for the agent name.

4. Find configured Slack channels. If none exist, tell the user to run:

   ```bash
   ai-devkit channel connect slack
   ```

   Stop after giving that action.

5. Choose a channel. Use the requested channel or the only available Slack channel. If multiple Slack channels are available, ask the user which one to use. Available means Slack, enabled, credentials present, and not already running.

6. If no Slack channel is available because bridges are already running, ask before stopping one. After confirmation:

   ```bash
   ai-devkit channel stop <channel>
   ```

7. Start the bridge in the background:

   ```bash
   ai-devkit channel start <channel> --agent <agent-name> --daemon
   ```

8. Report the connected channel, agent name, and how to stop it: `ai-devkit channel stop <channel>`.

## Boundaries

- Do not create or connect a Slack channel for the user; only point them to `channel connect`.
- Do not stop a running bridge without explicit confirmation.
- Do not guess when both agent or channel selection are ambiguous.

Referenced files: 1

View saved version →

---
name: remote-from-telegram
description: AI DevKit · Connect the current agent session to an available Telegram channel bridge.
---

# Remote From Telegram

Use this skill when the user wants to control or chat with the current session from Telegram.

Prefer the installed `ai-devkit` binary; if unavailable, use `npx ai-devkit@latest`. Run AI DevKit commands outside filesystem sandboxes because they inspect host-level agent and channel state.

## Workflow

1. Check readiness:

   ```bash
   ai-devkit status --json
   ```

   If AI DevKit is not ready, use `ai-devkit-setup` skill first. Stop if setup leaves manual actions.

2. Inspect channels and agents:

   ```bash
   ai-devkit channel list
   ai-devkit agent list --json
   ```

3. Identify the current agent by matching this session to an `agent list --json` entry. If unclear, ask for the agent name.

4. Find configured Telegram channels. If none exist, tell the user to run:

   ```bash
   ai-devkit channel connect telegram
   ```

   Stop after giving that action.

5. Choose a channel. Use the requested channel or the only available Telegram channel. If multiple Telegram channels are available, ask the user which one to use. Available means Telegram, enabled, configured with bot credentials, and not already running. Do not reject a Telegram channel only because it is not authorized yet; Telegram authorization cannot complete until after the bridge is started and the user sends a message to the bot.

6. If no Telegram channel is available because bridges are already running, ask before stopping one. After confirmation:

   ```bash
   ai-devkit channel stop <channel>
   ```

7. Start the bridge in the background:

   ```bash
   ai-devkit channel start <channel> --agent <agent-name> --daemon
   ```

8. Report the connected channel, agent name, and how to stop it: `ai-devkit channel stop <channel>`. If the channel was not authorized before start, explicitly tell the user the bridge is running and they must now send any message to the Telegram bot to authorize that chat before using it.

## Boundaries

- Do not create or connect a Telegram channel for the user; only point them to `channel connect`.
- Do not stop a running bridge without explicit confirmation.
- Do not guess when both agent or channel selection are ambiguous.

Referenced files: 1

View saved version →

---
name: security-review
description: AI DevKit · Review code, skills, and prompts for security vulnerabilities — OWASP Top 10, prompt injection, business logic flaws, and insecure defaults. Use when reviewing PRs, auditing modules, reviewing AI skills/prompts, or preparing for release.
---

# 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](references/checklist.md) (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

| Rationalization | Do Instead |
|---|---|
| "It's internal / behind a VPN / only admins" | Zero-trust: validate at every boundary regardless of network position or user role |
| "We'll add auth later" | Add auth before merge — unauthenticated endpoints get discovered fast |
| "It's just a dev credential" | Use env vars / secrets manager — dev secrets leak to prod constantly |
| "The framework handles that" | Verify the config — frameworks have defaults, not guarantees |
| "We sanitize on the frontend" | Always validate server-side — client validation is bypassable |
| "The LLM won't follow injected instructions" | Treat all tool results and external content as untrusted data |
| "It's just a prompt, not code" | Prompts control tool execution — review with the same rigor as code |

## 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"

Referenced files: 2

View saved version →

---
name: simplify-implementation
description: AI DevKit · Analyze and simplify existing implementations to reduce complexity, improve maintainability, and enhance scalability. Use when users ask to simplify code, reduce complexity, refactor for readability, clean up implementations, improve maintainability, reduce technical debt, or make code easier to understand.
---

# 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).
- Delete or inline before adding: remove dead code, one-caller wrappers, redundant guards, stale tests, and unused configuration first.

## 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?
- Apply the existence check to tests and scaffolding: remove stale, duplicate, implementation-detail-only, unused, or no-longer-relevant tests, assertions, and fixtures without unique behavioral coverage.
- Apply the reader-load test: can a new reader answer where key values come from and what can change them quickly? Count needless layers and hidden mutable state.
- Assess impact (LOC, dependencies, cognitive load, boundary leakage, scalability blockers).

3. Apply Readability Principles
- Apply the [readability guide](references/readability-guide.md) and its "Reading Test".
- Prefer domain-shaped structures over scattered conditionals when they remove branches, duplicated rules, or invalid states. Do not add an abstraction that only moves code around.

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.
- **Redesign**: Repeated implementation friction, patched branches, or synchronized flags → revisit the model before another local cleanup.

5. Prioritize and Plan
- Rank by impact/risk. Present plan with before/after snippets. Request approval.

## Red Flags and Rationalizations

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "While I'm here, let me refactor this too" | Scope creep breaks things | Only simplify what was requested |
| "This abstraction will help later" | Predicted reuse rarely materializes | Remove it unless used twice today |
| "Shorter is simpler" | Brevity can hide complexity | Optimize for readability, not line count |
| "I'll add a v2 instead of updating callers" | Accumulates dead code and forks the API | Modify in place when callers are in-repo; parallel-change only for external/public APIs |
| "Existing fn is close enough — I'll bend it to fit" | Wrong abstraction is costlier than duplication | Reuse only on clean fit; otherwise keep the small duplicate |

## Validation
- Preserve meaningful regression, public-contract, and interaction coverage. Update stale tests to intentional behavior; never delete tests merely to make failures pass.
- 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

Referenced files: 2

View saved version →

---
name: structured-debug
description: AI DevKit · Guide structured debugging before code changes by clarifying expected behavior, reproducing issues, identifying likely root causes, and agreeing on a fix plan with validation steps. Use when users ask to debug bugs, investigate regressions, triage incidents, diagnose failing behavior, handle failing tests, analyze production incidents, investigate error spikes, or run root cause analysis (RCA).
---

# 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

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "I already know the cause" | Assumptions skip evidence | Reproduce and prove it first |
| "This is urgent, just fix it" | A wrong fix wastes more time | 10 minutes of diagnosis saves hours |
| "The fix is obvious from the stack trace" | Stack traces show symptoms, not causes | Trace backward to the root cause |

## Output Template
Use this response structure:
- Observed vs Expected
- Repro and Environment
- Hypotheses and Tests
- Options and Recommendation
- Validation Plan and Results
- Open Questions

Referenced files: 1

View saved version →

---
name: task
description: AI DevKit · Track dev-lifecycle / structured-debug progress on a durable task with the ai-devkit task CLI. Use to record phase, progress, next step, blockers, and validation evidence.
---

# 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:

```bash
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>`.

```bash
# 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.

Referenced files: 1

View saved version →

---
name: tdd
description: AI DevKit · Test-driven development — write a failing test before writing production code. Use when implementing new functionality, adding behavior, or fixing bugs during active development.
---

# 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

| Pattern | Problem | Fix |
|---|---|---|
| Test-after | Code shapes the test instead of the other way around | Delete the code, write the test first |
| Testing internals | Tests break on refactor, not on behavior change | Test public behavior only |
| Giant red step | Multiple behaviors in one test | One assertion per behavior |
| Gold-plating green | Adding code no test requires | Remove untested code |
| Skipping refactor | Tech debt accumulates immediately | Refactor before the next red |
| Mock-heavy tests | Tests pass but real code fails | Prefer real dependencies, mock at boundaries only |

## Red Flags and Rationalizations

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "This is too simple to test first" | Simple code still needs a spec | Write the test — it'll be fast |
| "I'll add the test right after" | You won't, and the code will shape the test | Test first, always |
| "I need to see the design first" | The test IS the design | Let the test drive the interface |
| "Mocking is too hard for this" | Difficulty mocking signals tight coupling | Fix the design, then test |
| "The test would be identical to the implementation" | Then you're testing internals | Test the behavior from the outside |

## 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"`

Referenced files: 1

View saved version →

---
name: technical-writer
description: AI DevKit · Review and improve documentation for novice users. Use when users ask to review docs, improve documentation, audit README files, evaluate API docs, review guides, or improve technical writing.
---

# 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

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "Developers will figure it out" | Novice users won't | Write for the least experienced reader |
| "The code example speaks for itself" | Examples without context confuse | Add what it does and when to use it |
| "Too much detail clutters the doc" | Missing detail blocks users | Include prerequisites and edge cases |

## 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
```

Referenced files: 1

View saved version →

---
name: verify
description: AI DevKit · Enforce evidence-based completion claims — require fresh command output before reporting success. Use when completing any task, fixing a bug, finishing a phase, running tests, building, deploying, or making any "it works" claim.
---

# 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

| Claim | Required Evidence | Not Sufficient |
|---|---|---|
| Tests pass | Test output: 0 failures, exit 0 | Previous run, "should pass now" |
| Build succeeds | Build output: exit 0 | Linter passing, partial build |
| Bug is fixed | Reproduce symptom → now passes | "Changed code, should be fixed" |
| Linter clean | Linter output: 0 errors | Single file check |
| Phase complete | Each criterion verified individually | "Tests pass, so done" |
| Feature works | E2E test or manual walkthrough | Unit tests alone |

## 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

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "This change is trivial" | Trivial changes break things constantly | Run the check |
| "I ran it earlier" | Code changed since then | Run it again now |
| "The test is flaky" | Flaky ≠ ignorable | Fix the flake first |
| "It compiles, so it works" | Compilation ≠ correctness | Run the tests |
| "The CI will catch it" | CI is a safety net, not a substitute | Verify locally first |
| "The agent said it's done" | Agent claims need verification too | Check diff and run tests |

## 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.

Referenced files: 1