codeaholicguy/ai-devkit

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

# 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

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

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

# 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

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

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

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

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

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

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

# 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

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

# Refactor

Use for structural refactors. Use `dev-simplify` 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.

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

# Retro

Turn what went wrong into fixes that stop it recurring. Not a status summary: use `session-compact` for handoff state.

## Rules

- When suggested by another skill, ask the user before running; skip silently if declined.
- Every item needs evidence: a failed command, hook or test output, a user correction, a revert, or rework in the diff. No generic lessons.
- Cap at the 3-5 highest-cost items. Note what worked in one line only if it should be kept on purpose.
- Blameless: describe the gap in the system, not the person or agent.
- Never copy secrets, credentials, or personal data from transcripts into fixes or memory.

## Fix Ladder

# 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. Run `dev-smoke` when the change touches user-facing flows.
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

# 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

# Smoke

Exercise the flows a change touches the way a user would, then throw the script away. Report with `verify`; use `dev-testing` for permanent tests.

## Rules

- Drive the real entry point: built binary, running server, CLI, UI, or job. Imported functions and mocks are not smoke checks.
- Sandbox everything: temp dir, isolated `HOME` and config, empty git hooks, seeded test data, test accounts and tokens.
- Never use production, shared environments, real accounts or credentials, or paid APIs. Ask before outward-facing side effects: messages, emails, webhooks, deploys, pushes.
- Start servers on a dedicated port, wait until they respond, and stop the whole process tree on exit. Never reuse or kill the user's own servers.
- Keep secrets out of the script and its output.
- Write the script outside the repo; commit it only if the user asks to promote it.
- Timebox setup. If the app cannot run locally, say what was not checked instead of faking a pass.

# 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

# 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

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

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

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

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

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

# Session Compact

Use AI DevKit's Jev-backed CLI to create a structured continuation artifact from a historical session. Prefer this command over a hand-written compact when it is available.

## When to Use

- Context is getting long and useful state needs to survive compaction.
- Work is being handed to another agent or resumed after becoming stale.
- A complex implementation or debugging session is closing.
- Durable memory candidates or task-progress facts need to be identified after a long run.

## Workflow

1. Find the session ID when it is not already known:

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

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

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

# 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.
- A change that alters anything a user or caller sees requires a `dev-smoke` run, whatever the claim is called.

## Gate Function

Every completion claim must pass all steps in order: