CLI Reference Specification

Formal specification of every aidokit command, flag, exit code, and output format.

Table of contents

1. Document scope
2. Conventions
3. Global flags
4. Environment variables
5. Configuration files
6. Top-level invocation
7. Commands
8. 7.1 aidokit init
9. 7.2 aidokit doctor
10. 7.3 aidokit sync
11. 7.4 aidokit validate
12. 7.5 aidokit migrate
13. 7.6 aidokit mcp
14. 7.7 aido skills
15. 7.8 aidokit new
16. 7.9 aidokit manifest
17. 7.10 aido add adapter
18. 7.11 aidokit remove adapter
19. 7.12 aidokit search
20. 7.13 aidokit list
21. 7.14 aidokit verify
22. 7.15 aidokit eval
23. 7.16 aidokit task score
24. 7.17 aidokit goal
25. Exit codes
26. Output formats
27. Error envelope
28. Command availability by release
29. Open questions

1. Document scope

1.1 What this spec defines

• Every user-facing command, sub-command, flag, and argument
• The exit code taxonomy
• The human and JSON output formats
• Environment variables the CLI reads
• Configuration files the CLI reads or writes

1.2 What this spec does NOT define

• Internal implementation (lives in packages/cli/src/)
• Per-adapter behavior (lives in adapter packages)
• Per-stack-pack behavior (lives in stack-pack packages)
• Workflow semantics inside Claude Code / Codex (lives in the emitted files)

1.3 Stability promise

• Pre-v0.1: This spec may change without notice
• v0.1 → v1.0: Breaking changes allowed at minor version bumps, documented in CHANGELOG
• Post-v1.0: Commands and flags follow semver; removals require a major version bump

2. Conventions

2.1 RFC 2119 keywords

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and REQUIRED are to be interpreted as described in RFC 2119.

2.2 Synopsis syntax

aido <command> [<subcommand>] [<args>] [--flag] [--flag=value]

• <word> — required argument
• [<word>] — optional argument
• --flag — boolean flag
• --flag=value — flag with value (equivalent: --flag value)
• -f — short form (single letter)
• --no-flag — explicit negation of a boolean flag
• <a|b|c> — choice among fixed values

2.3 Flag conventions

• Long flags use kebab-case: --dry-run, --no-color
• Short flags are single letters: -y, -v, -h
• Flags MUST be parseable in any order after the command/subcommand
• -- terminates flag parsing; subsequent tokens are positional arguments

2.4 Interactivity rules

• The CLI MUST detect TTY status on stdin
• When stdin is a TTY: interactive prompts are allowed
• When stdin is NOT a TTY: the CLI MUST NOT prompt; it MUST either use defaults (with --yes) or fail with exit code 2
• --no-prompts MUST behave identically to non-TTY: never prompt, fail if input is required

2.5 Color and output

• The CLI MUST detect TTY on stdout
• Color output MUST be enabled only when stdout is a TTY AND the NO_COLOR environment variable is unset AND --no-color is not passed
• ASCII spinners and progress indicators MUST degrade to plain text when stdout is not a TTY

3. Global flags

These flags work with every command (including the top-level invocation).

Rules:

• --verbose and --quiet are mutually exclusive; the CLI MUST reject if both are passed (exit 2)
• --json implies --no-color and --no-prompts
• --dry-run MUST NOT modify any files or call any external commands except read-only probes
• --yes MUST NOT override safety confirmations explicitly marked as requiring user input (e.g., destructive operations in aidokit sync)

4. Environment variables

Rules:

• Environment variables MUST NOT override explicit command-line flags
• CI detection MUST be on by default in environments where common CI variables are set (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, etc.)

5. Configuration files

5.1 Project-level

5.2 User-level

AIDO_HOME overrides ~/.aido/.

5.3 Format

All aidokit-managed files MUST be:

• UTF-8 encoded
• LF line endings (even on Windows; the CLI handles platform conversion at read time)
• Stable JSON serialization (sorted keys, 2-space indent) for .json files

6. Top-level invocation

6.1 aidokit

Synopsis: aidokit [--help] [--version]

Behavior:

• With no arguments and no flags: print short help and exit 0
• With --help: print full help and exit 0
• With --version: print version (semver) and exit 0
• With an unknown command: print "Unknown command" error and exit 2

Example output (aidokit with no args):

aidokit — AI Dev Orchestrator CLI

Usage:  aido <command> [options]

Commands:
  init             Bootstrap a project
  doctor           Verify project conformance
  sync             Re-emit files from adapter templates
  validate         Validate an artifact against its schema
  migrate          Run version migration scripts
  mcp              Manage MCP servers
  skills           Manage skills
  new              Scaffold task/ADR/skill/capability
  manifest         Print adapter manifest
  add adapter      Add an adapter to an existing project
  remove adapter   Remove an adapter
  search           Search for adapters or stack packs
  list             List installed adapters or stack packs

Run `aidokit <command> --help` for command-specific help.

7. Commands

Each command spec includes: Synopsis, Description, Arguments, Flags, Interactive prompts (if any), Behavior, Examples, Exit codes, Related commands, Release.

7.1 aidokit init

Synopsis:

aidokit init [--adapter <name>] [--conformance <level>] [--brownfield]
          [--stack <ids>] [--no-beads] [--no-mcp] [--dry-run] [--yes]

Description: Bootstrap a project with the AI Dev Orchestrator workflow. Detects environment, gathers user selections, emits the engine directory, installs MCPs, runs postinstall.

Arguments: none.

Flags:

Interactive prompts (when adapter/conformance/stacks not provided):

1. Adapter selection (from installed adapter packages — no default; user MUST pick one of claude-code, codex, copilot. In non-interactive mode (--yes or no TTY) --adapter is REQUIRED; see ADR-0016.)
2. Conformance level (default: standard)
3. Stack confirmation (default: all detected with high confidence)
4. Beads opt-in (default: yes)
5. MCP selection (default: all suggested for selected stacks)

Behavior:

1. Probe host: Node version, Git, OS, prereqs
2. Scan project root for existing files
3. Detect brownfield state (with --brownfield)
4. Run stack detection across installed stack packs
5. Prompt for missing selections (or fail if --no-prompts)
6. Build ProjectContext
7. Compute file plan
8. If --dry-run: print plan, exit 0
9. Confirm plan (unless --yes)
10. Stage and write files
11. Install MCPs via adapter
12. Run postInstall shell commands
13. Write .aido/adapter.md
14. Print summary and next steps

Examples:

Non-interactive (adapter explicit, required with --yes):

$ aidokit init --adapter codex --conformance standard --yes

✔ Detected: macOS, Node.js 20.11, Node + TypeScript stack
✔ Adapter:    Codex
✔ Conformance: standard
✔ Wrote 47 files
✔ Installed 3 MCP servers
✔ Initialized Beads

Next: codex  →  /intake "describe your project"

Interactive (adapter prompted — no default; see ADR-0016):

$ aidokit init

? Pick an adapter (use arrows):
  > claude-code
    codex
    copilot
✔ Adapter:    Copilot
…

Exit codes: 0, 1, 2, 10 (prereq missing), 11 (adapter not found), 12 (stack pack not found), 13 (conformance check), 20 (write failed), 21 (MCP install), 40 (user cancelled).

Emitted root files: aidokit init also writes a default .aidoignore at the project root. The file uses a conservative subset of gitignore syntax and lists paths that AI agents and aidokit verify MUST NOT read or transmit (env files, credential bundles, private keys, cloud-CI secrets). It is cross-adapter and byte-identical across the claude-code, codex, and copilot fixtures — multi-adapter init emits it exactly once. Edit the file to fit your project's sensitivity profile; see @aidokit/core's aidoignore namespace (loadAidoignore(projectRoot)) for programmatic consumers.

Related: add adapter, doctor, sync.

Release: v0.1 (greenfield, claude-code adapter, Standard, Node-TS). v0.5 adds --brownfield, all conformance levels, more stacks. v1.0 adds codex and copilot adapters (alphabetical; equal first-party siblings), multi-adapter projects, and removes the implicit default — --adapter is required in non-interactive mode (ADR-0016).

7.2 aidokit doctor

Synopsis:

aidokit doctor [--fix-hints] [--strict] [--drift] [--no-semantic-drift] [--max-adr-age-days <n>] [--rules] [--conflicts] [--budget-map] [--model-policy] [--all]

Description: Read-only health check. Verifies prerequisites, adapter installation, file presence, MCP scoping, manifest consistency. Never writes.

Flags:

Semantic doc-drift (SP10): With --drift (default behaviour), every markdown file under .docs/** and docs/** is scanned for two kinds of references:

• File links ([label](./path.md)) — flagged with id drift:doc-file-missing when the target does not resolve relative to the document's directory.
• Code-symbol backticks (e.g. `SomeSymbol`) — flagged with id drift:doc-symbol-missing when the identifier is not exported anywhere under packages/*/src/**. To keep the warn rate sane, only spans with length ≥ 4 containing at least one uppercase character are considered.

URLs are never validated (aidokit performs no network IO). All findings are warn severity; the existing --strict flag will still escalate them.

Behavior:

1. Read <project>/.aido/adapter.md
2. Verify declared adapter package is installed and loadable
3. Run @aidokit/prereq-check for required prerequisites
4. Invoke adapter.doctor(ctx)
5. Verify all required skill files are present
6. Verify MCP scoping in role frontmatter matches state.json
7. Run conformance harness subset against the installed adapter
8. Print summary; exit 0 if all pass, 1 if any check fails (or warns with --strict)

Example (adapter-agnostic; the adapter-CLI row and the Adapter: line vary with which adapter is installed — <adapter> and <x.y.z> are placeholders):

$ aidokit doctor

✔ Node.js 20.11.0
✔ <Adapter CLI> <x.y.z>
✔ Beads CLI 0.9.2
✔ Adapter: <adapter>@<x.y.z> (Standard conformance)
✔ All 18 skills present
✘ MCP scoping mismatch: 'context7' missing from researcher role
   Fix:  aido mcp scope context7 --add-role researcher

1 failure, 0 warnings

Exit codes: 0 (all pass), 1 (any check failed), 13 (conformance fail).

Related: sync, manifest, mcp list.

Release: v0.5.

7.3 aidokit sync

Synopsis:

aidokit sync [--scripts] [--skills] [--agents] [--dry-run] [--yes]

Description: Re-emit adapter-owned files from the current adapter package version. Shows a diff before writing; never overwrites user-owned files without confirmation.

Flags:

Behavior:

1. Read <project>/.aido/adapter.md
2. Load matching adapter version (warn if newer available)
3. Compute fresh file plan
4. Call adapter.preSync(ctx) → SyncPlan
5. Filter by --scripts/--skills/--agents if specified
6. Display the plan (counts + paths; --verbose shows full diffs)
7. If --dry-run: exit 0
8. Prompt for confirmation (unless --yes)
9. Apply approved changes via staged write
10. Update state.json with sync timestamp

Example:

$ aidokit sync --dry-run

Adapter: claude-code@0.1.0 → 0.1.2 (newer available; will use installed 0.1.0)

Plan:
  3 files to update:
    .claude/skills/digest/SKILL.md            (template updated)
    .claude/scripts/track-test-failures.mjs   (template updated)
    .claude/agents/builder.md                 (template updated)
  0 files to create
  0 files to delete
  44 files identical (skipped)

Run without --dry-run to apply.

Exit codes: 0, 1, 11, 20, 40.

Related: doctor, manifest.

Release: v0.5.

7.4 aidokit validate

Synopsis:

aidokit validate <artifact-path> [--schema <name>]

Description: Validate an artifact file (task brief, change summary, test report, etc.) against its JSON schema from @aidokit/core.

Arguments:

Flags:

Behavior:

1. Detect schema from file path or frontmatter (or use --schema)
2. Parse the file (YAML frontmatter + Markdown body)
3. Run AJV validation against the schema
4. Print pass or error details with line numbers
5. Exit 0 if valid, 1 otherwise

Example:

$ aidokit validate agent-artifacts/task-briefs/bd-a1b2-add-zod.md

✘ Invalid: agent-artifacts/task-briefs/bd-a1b2-add-zod.md
  Missing required field: 'validation-commands'
  See:  docs/specs/adapter-contract.md §6.3 SkillTemplate

Exit codes: 0 (valid), 1 (invalid), 2 (file not found or schema unknown).

Related: doctor.

Release: v0.5.

7.5 aidokit migrate

Synopsis:

aidokit migrate <from>-to-<to> [--backup-dir <path>] [--yes]

Description: Run a registered migration script that converts project structure between major versions of the kit.

Arguments:

Flags:

Behavior:

1. Look up the migration script in @aidokit/core/migrations
2. Check preconditions (files exist, no in-progress workflow state)
3. Back up affected files to --backup-dir
4. Prompt for confirmation (unless --yes)
5. Run the migration in stages
6. Write a migration-review.md summarizing changes that need manual review
7. Exit 0 on success, 30 on migration failure (with --backup-dir location printed)

Example:

$ aidokit migrate v3-to-v4

✔ Backed up 12 files to .aido-backup-2026-05-12-1430/
✔ Converted docs/01-prd.md → docs/specs/<capability>/spec.md (3 capabilities)
✔ Converted docs/04-task-index.md → Beads issues (8 issues)
✔ Renamed 8 task briefs to <bd-id>-<slug>.md convention

Review: scripts/migration-review.md

Exit codes: 0, 1, 2, 30.

Related: doctor, sync.

Release: v0.5.

7.6 aidokit mcp

Top-level MCP management. All subcommands modify per-project MCP state via the adapter.

7.6.1 aido mcp list

Synopsis: aido mcp list [--scoped-to <role>]

Behavior: Call adapter.listInstalledMCPs(ctx); print table of installed MCPs with roles scoped to.

Flags:

Example:

$ aido mcp list

ID            NAME             SCOPED TO                           INSTALLED
context7      Context7         researcher, architect               2026-05-10
beads-mcp     Beads MCP        planner, maintainer                 2026-05-10
playwright    Playwright       tester-reviewer                     2026-05-10

Exit codes: 0, 1, 11.

Release: v0.5.

7.6.2 aido mcp add <id>

Synopsis: aido mcp add <id> [--roles <role1,role2,…>] [--custom-url <url>]

Behavior:

1. Look up <id> in @aidokit/mcp-catalog (or fail if --custom-url not provided)
2. If securitySensitive, require explicit --yes confirmation
3. Determine roles (from --roles or mcp.suggestedFor)
4. Call adapter.installMCP(mcp, roles, ctx)
5. Execute returned shell commands
6. Update agent frontmatter
7. Persist to state.json

Flags:

Example: aido mcp add github --roles researcher,planner

Exit codes: 0, 1, 11, 21.

Release: v0.5.

7.6.3 aido mcp remove <id>

Synopsis: aido mcp remove <id>

Behavior: Call adapter.removeMCP(id, ctx); execute returned commands; remove from state.json and role frontmatter.

Exit codes: 0, 1, 21.

Release: v0.5.

7.6.4 aido mcp scope <id>

Synopsis: aido mcp scope <id> [--add-role <name>] [--remove-role <name>] [--set-roles <list>]

Behavior: Modify which roles see an installed MCP. Updates role frontmatter; does not reinstall.

Flags:

--add-role and --remove-role MAY be repeated; --set-roles MUST NOT be combined with the others.

Exit codes: 0, 1, 2.

Release: v0.5.

7.6.5 aido mcp suggest

Synopsis: aido mcp suggest

Behavior: Re-run the trigger evaluator against the current ProjectContext; print MCPs that would be suggested but are not installed.

Exit codes: 0, 1.

Release: v0.5.

7.6.6 aido mcp risk

Synopsis: aido mcp risk [--json]

Behavior: Read-only. Reads selectedMCPs from .aidokit/state.json and looks each id up in @aidokit/mcp-catalog. For each installed MCP, render a row with only the risk signals the catalog (MCPDef) actually declares: id, securitySensitive, untrustedOutput, and suggestedFor roles. These signals are reported verbatim — no shell/network/writes capabilities are derived or inferred, since the catalog does not declare them. An installed id not present in the catalog renders as unlisted (unknown risk). No network calls. --json emits the raw row array.

Exit codes: 0, 1.

Release: v1.0.

7.7 aido skills

Skill management at project and personal levels.

7.7.1 aido skills list

Synopsis: aido skills list [--source <core|stack-pack|personal>]

Behavior: List skills present in the project's engine directory, grouped by source.

Exit codes: 0, 1.

Release: v0.5.

7.7.2 aido skills add <id>

Synopsis: aido skills add <id> [--from <source>]

Behavior: Add a skill from the core base set or a stack pack to the project's engine directory.

Exit codes: 0, 1, 2.

Release: v0.5.

7.7.3 aido skills personal init

Synopsis: aido skills personal init

Behavior: Create $AIDO_HOME/personal-skills/ if it does not exist.

Exit codes: 0, 1.

Release: v0.5.

7.7.4 aido skills personal add <name>

Synopsis: aido skills personal add <name>

Behavior: Scaffold a new personal skill template at $AIDO_HOME/personal-skills/<name>/SKILL.md.

Exit codes: 0, 1, 2.

Release: v0.5.

7.7.5 aido skills personal list

Synopsis: aido skills personal list

Behavior: List skills in $AIDO_HOME/personal-skills/.

Exit codes: 0, 1.

Release: v0.5.

7.8 aidokit new

Scaffold artifact templates.

7.8.1 aido new task <slug>

Synopsis: aido new task <slug> [--phase <n>] [--scope <files>]

Behavior: Create a task brief from the template at agent-artifacts/task-briefs/<id>-<slug>.md. If Beads is enabled, run bd create and use the returned bd-id.

Exit codes: 0, 1, 2.

Release: v0.5.

7.8.2 aido new adr <slug>

Synopsis: aido new adr <slug>

Behavior: Create the next-numbered ADR at docs/architecture/decisions/NNNN-<slug>.md from the template.

Exit codes: 0, 1.

Release: v0.5.

7.8.3 aido new skill <name>

Synopsis: aido new skill <name> [--triggers <globs>] [--roles <roles>]

Behavior: Scaffold .claude/skills/<name>/SKILL.md (or adapter equivalent) with frontmatter populated from flags.

Exit codes: 0, 1, 2.

Release: v0.5.

7.8.4 aido new capability <slug>

Synopsis: aido new capability <slug>

Behavior: Create docs/specs/<slug>/spec.md and spec-summary.md from templates.

Exit codes: 0, 1.

Release: v0.5.

7.9 aidokit manifest

Synopsis: aido manifest [--json]

Description: Print the project's adapter.md manifest in human or JSON form.

Behavior: Read <project>/.aido/adapter.md; print contents formatted.

Exit codes: 0, 1, 2 (no manifest found).

Related: doctor.

Release: v0.5.

7.10 aido add adapter

Synopsis:

aido add adapter <name> [--conformance <level>]

Description: Add an additional adapter to a project that already has at least one installed. Shared docs and agent-artifacts are preserved; only the new adapter's engine directory and rules file are added.

Arguments: <name> — adapter package name (with or without scope)

Flags: --conformance <level> — default standard

Behavior:

1. Verify at least one adapter is already installed (read .aido/adapter.md)
2. Resolve the new adapter package; verify compatibility
3. Confirm with user (this adds files to the project)
4. Run the same steps as init, but only for the new adapter's emissions
5. Append the new adapter to a multi-adapter section in .aido/adapter.md

Exit codes: 0, 1, 11, 20.

Release: v1.0.

7.11 aidokit remove adapter

Synopsis: aidokit remove adapter <name> [--keep-shared]

Description: Remove an adapter's engine directory and rules file. Shared docs and Beads remain by default.

Flags:

Behavior:

1. Confirm with user (deletion operation)
2. Remove <engine-directory>/ and the adapter's rules file
3. Update .aido/adapter.md

Exit codes: 0, 1, 11, 40.

Release: v1.0.

7.12 aidokit search

7.12.1 aido search adapter [<query>]

Synopsis: aido search adapter [<query>] [--verified-only]

Behavior: Search npm for packages matching aidokit-adapter-* or @scope/aidokit-adapter-*. Display name, version, weekly downloads, trust tier (Official / Verified / Community / Unverified).

Exit codes: 0, 1.

Release: v1.0.

7.12.2 aido search stack-pack [<query>]

Synopsis: aido search stack-pack [<query>] [--verified-only]

Behavior: Same as adapter search, for stack packs.

Exit codes: 0, 1.

Release: v1.0.

7.13 aidokit list

7.13.1 aidokit list adapters

Synopsis: aidokit list adapters

Behavior: List adapter packages installed in the project's node_modules.

Exit codes: 0, 1.

Release: v0.5.

7.13.2 aidokit list stack-packs

Synopsis: aidokit list stack-packs

Behavior: List stack-pack packages installed in the project's node_modules.

Exit codes: 0, 1.

Release: v0.5.

7.14 aidokit verify

Synopsis:

aidokit verify [--secrets] [--budget] [--deps] [--license] [--loop-cap]
               [--all-facets] [--all] [--sarif] [--json]

Description: Run verification facets against the staged diff (default) or the working tree (--all). Facets are pluggable checks that close specific AI-assisted-development pain points (secret leakage, token cost, dependency bloat, license contamination, agent runaway).

Facet flags

Additional flags:

• --all — scan working tree instead of staged diff.
• --sarif — output SARIF 2.1.0 (pipes into GitHub code-scanning).
• --json — machine-readable findings.

Exit codes:

• 0 — no error-severity findings (warnings allowed).
• 1 — at least one error-severity finding.

Policy lives in .aidokit/policy.json (emitted at init). See @aidokit/core verify/policy-schema.ts for the schema.

7.15 aidokit eval

Synopsis: aidokit eval [--task <id>] [--brief <path>] [--json]

Behavior: Locate a task brief, parse its ## Acceptance criteria section, and run each checkbox. A checkbox whose text begins with > is runnable: the remainder of the line is argv-split on whitespace and invoked via execFile (no shell, no quoting — to use shell features make the first token bash or sh explicitly). Any other checkbox is manual and is reported as MANUAL without execution.

Brief resolution order:

1. --brief <path> — explicit override (absolute or project-relative).
2. --task <id> — agent-artifacts/task-briefs/<id>.md.
3. If neither flag is set and agent-artifacts/task-briefs/ contains exactly one *.md file (excluding README.md), that file is used.

Per-criterion status:

• PASS — runnable, exit code 0.
• FAIL — runnable, non-zero exit (exit code captured).
• MANUAL — text-only criterion; not executed.

Exit codes:

• 0 — every runnable criterion passed (manual criteria do not fail the run).
• 1 — at least one runnable criterion failed.
• 2 — brief file missing, or no ## Acceptance criteria section in the brief.

Release: v1.0.

7.16 aidokit task score

Synopsis: aidokit task score [id|path] [--brief <path>] [--json]

Behavior: Resolve a task brief, then score it against the deterministic quality rubric (ADR-0021). Returns a 0–100 score, an A–F grade, and a per-dimension breakdown. Zero LLM calls — the rubric is a structural, keyword-driven check. The command is advisory: it always exits 0.

Rubric (total 100): scope/objective section (20); acceptance criteria present with ≥1 runnable >-prefixed checkbox (30); risks section (15); rollback/back-out section (15); test-plan or validation-commands section (20). Grades: A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, F < 40.

Brief resolution order:

1. --brief <path> — explicit override (absolute or project-relative).
2. A positional argument containing a path separator or ending in .md — treated as a brief path (absolute or project-relative).
3. A bare positional id — agent-artifacts/task-briefs/<id>.md.

Exit codes: 0 always (advisory). A missing brief is reported in the output (and reason: "brief-missing" under --json) without failing.

Release: v1.0.

7.16.1 aidokit task run

Synopsis: aidokit task run [id|path] [--brief <path>] [--json]

Behavior: The Tier-2 pre-flight orchestrator (ADR-0027). Runs aidokit's own deterministic steps in order — task score → goal draft → goal plan — then stops before the model step. Writes the goal contract (agent-artifacts/goals/<id>-goal.md) and run-plan (agent-artifacts/goals/<id>-plan.sh), and prints the score plus the ordered next steps (review contract → run YOUR adapter → aidokit eval → aidokit verify --all-facets → aidokit pr packet). Composition only — zero LLM calls, no auto-progression past the model boundary. Brief resolution matches task score.

Exit codes: 0 on success; 2 (BAD_INVOCATION) when no brief resolves.

Release: v1.0.

7.17 aidokit goal

Static goal-contract + run-plan emitter (ADR-0023). Two subcommands, both resolving the brief like aidokit eval / aidokit task score (--brief <path> override; a path-looking positional; else a bare id → agent-artifacts/task-briefs/<id>.md). Zero LLM calls.

7.17.1 aidokit goal draft [id|path]

Synopsis: aidokit goal draft [id|path] [--brief <path>] [--json]

Behavior: Statically extract a goal contract from the brief and write it to agent-artifacts/goals/<id>-goal.md. The contract contains: the objective (first heading, else first paragraph); the allowed files (bullets under a Scope / In-scope files / Allowed files heading, preferring inline-code spans); the validation commands (the - [ ] > <cmd> acceptance-criteria lines aidokit eval runs); and a fixed set of stop rules (stop on first red validation, no scope expansion, human approves the merge). Missing sections render guidance placeholders.

Exit codes: 0 on success; 2 (BAD_INVOCATION) when the brief is missing or no selector is given.

7.17.2 aidokit goal plan [id|path]

Synopsis: aidokit goal plan [id|path] [--brief <path>] [--json]

Behavior: Write a commented run-plan shell script to agent-artifacts/goals/<id>-plan.sh. The script is documentation only — it enumerates the workflow steps (draft goal → run YOUR adapter manually → aidokit eval → aidokit verify → human review) as comments and never invokes a model itself.

Exit codes: 0 on success; 2 (BAD_INVOCATION) when the brief is missing or no selector is given.

Release: v1.0.

7.18 aidokit handoff

Compress available artifacts into a resume packet. Zero LLM calls.

7.18.1 aidokit handoff pack

Synopsis: aidokit handoff pack [--task <id>] [--brief <path>] [--json]

Behavior: Statically assemble a markdown handoff packet at agent-artifacts/handoff/<id-or-timestamp>.md from whatever already exists: the task brief (when --task <id> resolves to agent-artifacts/task-briefs/<id>.md, or --brief <path>), the most recent change summaries under agent-artifacts/change-summaries/, and the recent git log --oneline (read-only). When no --task is given, the packet is keyed by an ISO timestamp. No model is invoked, no network access.

Exit codes: 0 on success.

7.19 aidokit intent

Compile a static intent doc from existing project docs. Zero LLM calls.

7.19.1 aidokit intent build

Synopsis: aidokit intent build [--json]

Behavior: Assemble .aidokit/intent.md statically from documents already in the project: the ## section headings of .docs/ARCHITECTURE.md (falling back to a root ARCHITECTURE.md), the workspace package names under packages/, and the titles of the ADRs under .docs/docs/architecture/decisions/ (the 0000 template is excluded). Missing sources render placeholders. No model is invoked.

Exit codes: 0 on success.

Release: v1.0.

7.20 aidokit index

Build a local-only deterministic project index. Zero LLM calls. Zero network.

7.20.1 aidokit index build

Synopsis: aidokit index build [--json]

Behavior: Perform a read-only scan and write .aidokit/index.json. The index has four sorted arrays: files (.ts/.js under packages/<pkg>/src, skipping node_modules/dist/.git), exports ({ file, name } pairs from export (const|function|class|interface|type|enum) <Name> and export { ... }, excluding test files), tests (*.test.ts), and docs (*.md under docs/ and .docs/). Paths are project-root-relative with forward slashes. Output is written with stable sorted keys and 2-space indentation and is byte-identical across repeated runs. See ADR-0024.

Exit codes: 0 on success.

Release: v1.0.

7.21 aidokit baseline

Deterministic known-broken baseline and failure classifier. Zero LLM calls. Zero network. aidokit never runs the project's test suite — it only parses a test-output file the caller produced. See ADR-0025.

The parser recognises two line shapes: TAP-ish not ok <n?> - <name> (a leading numeric index, an optional - separator, and a trailing # directive comment are stripped) and plain FAIL <name> / FAILED <name> (case-insensitive). The resulting failing-identifier set is sorted and de-duplicated.

7.21.1 aidokit baseline capture --from <file>

Synopsis: aidokit baseline capture --from <file> [--json]

Behavior: Parse <file> and write the sorted failing set to .aidokit/baseline.json ({ "failures": [...] }). A missing <file> raises BAD_INVOCATION.

Exit codes: 0 on success.

7.21.2 aidokit baseline diff --from <file>

Synopsis: aidokit baseline diff --from <file> [--json]

Behavior: Load .aidokit/baseline.json, parse <file>, and classify each failure as pre-existing (in the baseline), new (not in the baseline — the classifier), or fixed (in the baseline but no longer failing). A missing baseline or missing <file> raises BAD_INVOCATION.

Exit codes: 0 when there are no new failures; 1 when new failures exist.

Release: v1.0.

7.22 aidokit pr

7.22.1 aidokit pr packet

Synopsis: aidokit pr packet [--task <id>] [--brief <path>] [--base <ref>] [--output <file>] [--force] [--json]

Behavior: Assemble a markdown PR review packet (ADR-0026). The packet contains: a Summary lifted from the linked task brief's ## Goal; the Changed files from git diff --name-only <base>...HEAD (--base, default main); Validation commands from the brief (falling back to pnpm -r build / pnpm -r test); and a Risks & rollback section lifted from the brief's ## Risks / ## Rollback headings when present. Brief resolution matches aidokit eval. Output goes to stdout, or to --output. Following read-before-write (AGENTS.md §6 principle 8), --output refuses to overwrite an existing file unless --force is given. Zero model calls, zero network.

Release: v1.0.

7.23 aidokit ci

7.23.1 aidokit ci init

Synopsis: aidokit ci init --provider <github|gitlab|bitbucket> [--force] [--json]

Behavior: Emit a provider CI config (ADR-0026) that runs pnpm -r build, pnpm -r test, and aidokit verify --all-facets. Targets: .github/workflows/aidokit.yml (github), .gitlab-ci.yml (gitlab), or bitbucket-pipelines.yml (bitbucket). Read-before-write: an existing target raises BAD_INVOCATION unless --force is passed.

Release: v1.0.

8. Exit codes

The CLI uses a grouped exit-code taxonomy. All commands MUST map their failures into this taxonomy.

Rules:

• Commands MUST NOT use exit codes outside this taxonomy
• Commands MUST set the most specific code that applies; fall back to 1 only for truly unclassified failures
• Exit codes MUST be consistent across --json and human output

9. Output formats

9.1 Human format (default)

• Status lines use ✔ for success, ✘ for failure, ⚠ for warning, ℹ for info
• Spinners (ora) for in-progress operations
• Color: green = success, red = failure, yellow = warning, cyan = info, gray = secondary
• Tables for list outputs (boxed in interactive mode, plain TSV when piped)

9.2 --json format

When --json is passed, ALL output MUST be a single JSON object on stdout. Logging and progress indicators MUST go to stderr.

Success shape:

{
  "ok": true,
  "command": "init",
  "result": {
    "adapter": "copilot",
    "conformance": "standard",
    "filesWritten": 47,
    "mcpsInstalled": 3,
    "nextSteps": ["claude", "/intake \"describe your project\""]
  }
}

Error shape:

{
  "ok": false,
  "command": "init",
  "error": {
    "code": "PREREQ_MISSING",
    "exitCode": 10,
    "message": "Prerequisite missing: Claude Code",
    "details": { "prereq": "claude-code", "minVersion": "2.1.32" },
    "hint": "Install Claude Code via: curl -fsSL claude.ai/install.sh | bash"
  }
}

Rules:

• The CLI MUST emit exactly one JSON object on stdout in --json mode (no streaming JSON, no NDJSON)
• All error fields except details and hint are required
• exitCode in the JSON MUST match the process exit code

9.3 --verbose format

Adds a steps array with timestamped step transitions:

{
  "ok": true,
  "command": "init",
  "result": {
    /* … */
  },
  "steps": [
    { "step": "detect", "duration_ms": 142, "status": "ok" },
    { "step": "prompt", "duration_ms": 0, "status": "skipped (--yes)" },
    { "step": "write-files", "duration_ms": 312, "status": "ok" },
    { "step": "install-mcps", "duration_ms": 8420, "status": "ok" }
  ]
}

10. Error envelope

All errors thrown by the CLI MUST conform to this shape:

interface AidoErrorEnvelope {
  code: string; // e.g., 'PREREQ_MISSING', 'ADAPTER_NOT_FOUND'
  exitCode: number; // mapped to §8 taxonomy
  message: string; // human-readable summary
  details?: Record<string, unknown>;
  hint?: string; // suggested fix
}

10.1 Error code naming

• SCREAMING_SNAKE_CASE
• Prefix indicates category: PREREQ_*, ADAPTER_*, MCP_*, FS_*, MIGRATE_*
• Stable across releases (new codes added; existing codes never renamed)

10.2 Reserved error codes

This table is the documentation mirror of the canonical ErrorCode taxonomy defined in @aidokit/core (packages/core/src/error.ts). The shipped enum is the single source of truth (ADR-0012); this table MUST list exactly its members. Exit codes are produced by exitCodeFor in packages/cli/src/exit-codes.ts and follow the §8 taxonomy. Codes without a dedicated exit group (state and internal failures) intentionally map to 1 (generic). Adapters MAY introduce additional codes; unrecognised codes fall back by prefix (PREREQ_*, ADAPTER_*, MCP_*, FS_*), then to 1.

11. Command availability by release

12. Open questions

See also

• ../../ARCHITECTURE.md — system design context
• adapter-contract.md — Adapter interface this CLI invokes
• stack-pack-contract.md — Stack pack interface this CLI invokes
• mcp-catalog.md — MCP catalog format and v0.1 contents
• conformance-levels.md — per-level requirement checklists
• ../../ROADMAP.md — release plan