Commands Spec: Slash Commands Like Claude Code
Status: specification; implementation to do (roadmap M13); it replaces §14 of the agent specification.
Instructions for Claude Code: This spec extends
AGENT_SPEC.md(§14 is superseded by this file), and refers toPROCESS_SPEC.mdandGIT_SPEC.mdfor the behavior of process- and git-related commands. Read them all before starting.The reference is the Claude Code commands page (https://code.claude.com/docs/en/commands, as of Nov 2026). Commands tied to Anthropic accounts, billing or cloud services are either adapted to a local equivalent or skipped. See the status column in §3.
Rule #1: audit before you build. Same rule as
AGENT_SPEC.md§0A.
Phase 0: search the repo for any command handling. Look for:
- input lines starting with
/, a command registry, argument parsing, autocomplete, help output- existing commands, prompt templates, skills
For every command in §3, record ✅/🟡/❌/⚠️ with file:line evidence in
docs/gap-analysis.mdunder "Commands".Write
docs/commands-design.md, mapping the framework (§1–§2) to existing code or new modules.Stop and show me both. Ask only what you can't infer.
Implement milestone by milestone (§8), only ❌ and 🟡 items. Re-search at the start of each milestone. Test everything. Show evidence and wait for my go-ahead between milestones.
Fill in before starting:
- Binary name / config dir / memory file:
oklm agent/.oklm/(user:~/.config/oklm/;.agent/read as a fallback) /AGENTS.md(alsoOKLM.md,AGENT.md,CLAUDE.md; agent-design.md). - Commands to skip entirely beyond the ones marked Skip: none decided; to settle at C0 from its audit table.
- Second local model available (for
/advisor,/btw, titles): yes: OKLM can open a second, smaller model in the same process (Qwen3-0.6B, SmolLM2 and others are in the public corpus); the agent's--small-modelis planned in agent-design.md (§2.5). - Speech-to-text available (for
/voice): yes, OKLM's own Whisper (oklm transcribe,include/oklm/mm/audio.h, multimodal.md); no whisper.cpp. Recording from the microphone is the missing part (Allegro 5's audio addon, or a recorder command).
Before starting (OKLM)
What this spec needs settled or built before its C0 can start, and how its names map onto OKLM's.
Names.
| The spec says | OKLM |
|---|---|
AGENT_SPEC.md |
agent_skill_chat_spec.md (roadmap M10) |
PROCESS_SPEC.md |
process_spec.md (M11) |
GIT_SPEC.md |
git_spec.md (M12) |
COMMANDS_SPEC.md |
commands_spec.md (M13) |
the agent binary, agent |
oklm agent |
.agent/, ~/.agent/ |
.oklm/ and ~/.config/oklm/
($XDG_CONFIG_HOME, %APPDATA% on Windows) |
AGENT.md, AGENT.local.md |
AGENTS.md (also OKLM.md,
AGENT.md, CLAUDE.md; agent-design.md) |
| the ProcessManager | the job manager, src/harness/jobs.c (adr/0012-jobs.md) |
.agent/commands/**/*.md,
.agent/skills/ |
.oklm/commands/, .oklm/skills/ (skills
already load from there) |
~/.agent/themes/,
~/.agent/feedback-bundles/ |
~/.config/oklm/themes/,
~/.local/state/oklm/feedback/ |
.agent/loop.md |
.oklm/loop.md |
What exists. oklm agent's REPL handles
/reset, /mode MODE, /jobs,
/thinking and /exit with string comparisons in
cmd_agent (apps/oklm.c);
oklm chat has its own (/system,
/reset, /tool, /exit). Skills
(.oklm/skills/*/SKILL.md, src/harness/tools.c)
are the format prompt commands share (§1.7). The prompt has a line
editor with history (include/oklm/harness/line_edit.h),
where the command menu and completion (§1.6) go. The C0 audit records
every command of §3 against this in gap-analysis.md under "Commands".
Owned elsewhere, not built twice. This spec replaces
the agent specification's §14 and owns the framework, the menu (its
/ input mode), custom commands as skills and the catalog;
the full map is agent-specs.md. Each
command's behavior lives in the spec named in its row: this spec builds
the registry, parser, menu and shared UI, and calls into them.
/tasks (alias /bashes, and today's
/jobs) shows the job manager's list (process specification
§13); /compact, /rewind, /resume,
/memory, /agents, /mcp are the
agent specification's §10, §11, §8, §12, §16; the git commands are the
git specification's.
Prerequisites. C1 to C3 (framework, menu, prompt commands as skills) need only the agent specification's M0 and its skills (present); they can be its M10 milestone (slash commands), since this spec replaces its §14. C4 to C9 follow the milestones that give each command its behavior.
Decisions to take at C0: whether
oklm chat shares the registry (proposed: yes, with its own
set); the place of the command menu in the terminal (below the prompt,
the line editor drawing it).
1. Command framework
1.1 Command types
| Type | What it does | Example |
|---|---|---|
| builtin-action | Code runs immediately and prints a result; the model isn't involved | /clear, /model, /rename |
| builtin-dialog | Opens an interactive TUI panel; prints text in -p
mode |
/config, /permissions,
/resume |
| prompt (skill) | Expands to a prompt handed to the model, optionally with tool pre-approvals | /commit, /init, /code-review,
user skills |
| workflow | A scripted multi-agent run in the background with a progress view | /batch, /deep-research |
| mcp-prompt | An MCP server prompt exposed as a command | /mcp__github__review |
1.2 Command definition (one registry for all types)
Command {
name: "code-review"
aliases: ["review"]
type: builtin-action | builtin-dialog | prompt | workflow | mcp-prompt
description: string // shown in menu and /help
argumentHint: "[low|medium|high] [--fix] [pr#|branch|path]"
argsSchema?: parser spec // for builtins: enums, flags, positional, key=value
source: builtin | bundled-skill | project | user | plugin:<name> | mcp:<server>
availability(): ok | hidden | unavailable(reason) // platform, config, feature presence
hiddenFromMenu: bool // listed only after full name typed (e.g. /heapdump)
runsWhileBusy: "immediate" | "queue" | "immediate-dialog"
headless: "supported" | "text-only" | "unsupported"
execute(args, ctx) -> CommandResult
}
CommandResult = { output?: text (shown to user, not to model unless flagged), injectPrompt?: text,
addToContext?: bool, openDialog?: id, error?: text }
1.3 Parsing rules
- A command is recognized only at the start of a message. The text after the name is its arguments.
- Stacking:
/skill-a /skill-b do XYZloads up to 6 prompt-type commands and passes the trailing text to each as arguments. Builtins can't be stacked. - Names are case-insensitive.
:separates namespaces (/frontend:component,plugin:skill). - Arguments for builtins come from
argsSchema, with friendly errors such asUsage: /rename <name>. - For prompt commands, the raw argument string is available as
$ARGUMENTS, and as$0,$1… (shell-like splitting, quotes respected). //textor a leading space escapes, so a message can start with a literal/.- Unknown commands:
Unknown command: /foo, plus up to 3 close suggestions (edit distance). The text is not sent to the model.
1.4 Precedence and conflicts
- Builtin > project > user > plugin > MCP.
- On a name clash, the shadowed command stays reachable by its
namespaced name (
/plugin-name:cmd,/mcp__server__prompt). /helpand/skillsshow shadowing warnings.
1.5 Running while the agent is busy
queue(the default): run after the current turn ends. The input box shows "queued: /compact".immediate: runs now without interrupting. For read-only and status commands:/status,/tasks,/usage,/context,/btw,/copy,/help.immediate-dialog: opens now, and changes apply from the agent's next tool call in the same turn:/permissions,/add-dir,/model,/effort,/theme.- Settings changed mid-turn that would invalidate the KV/prompt cache
(
/model,/effort) show a short warning and ask for confirmation.
1.6 Command menu (TUI)
- Typing
/opens the menu. Further letters filter it. - Matching: prefix, or word-start within the name or
an alias, ignoring the
:,_and-separators. Typing/adddirmatches/add-dir, and/newmatches/clearthrough its alias. - Highlight the top suggestion only on a real match. Enter runs the highlighted entry.
- On a typo, close matches stay listed but nothing is highlighted. Enter submits the text as typed, which gives "Unknown command".
- Hidden commands appear only once the full name is
typed. Unavailable commands are left out. When nothing matches:
No commands match "/name". - Each row shows the name, argument hint, description and a source
badge (
skill,project,plugin:x,mcp). - Argument completion: enum values
(
/effort low|…), paths (/add-dir,/cd), session names (/resume), server names (/mcp reconnect), model names (/model).
1.7 Prompt commands and skills share one format
Custom commands are skills. Load them from:
.agent/skills/<name>/SKILL.mdand~/.agent/skills/<name>/SKILL.md(AGENT_SPEC §13)- legacy single files:
.agent/commands/**/*.mdand~/.agent/commands/**/*.md(subfolders become namespaces)
Frontmatter (superset):
---
name: commit # default: folder/file name
description: Create a git commit following repo conventions
argument-hint: "[message hint]"
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*), Bash(git diff:*)
model: main | small | <name>
disable-model-invocation: true # user-only (command), not auto-invoked by the model
user-invocable: true # false = model-only skill, hidden from / menu
context: fork # optional: run in a forked subagent, result returns here
---
Body with $ARGUMENTS, $1, @path/to/file (inlined), and !`git status --short` (runs Bash
under normal permissions, output inlined before the model sees the prompt).
- Expansion order: frontmatter, then
!commands run (with a timeout and output cap), then@files are inlined, then the argument placeholders are substituted. - If the body uses no placeholder, the arguments are appended as
ARGUMENTS: ….
1.8 Visibility overrides
- A
skillOverridessetting can hide a command from the menu, hide it from the model, or disable it. /skillslets the user cycle visibility (§3). Managed settings can lock overrides.
1.9 Headless (-p)
agent -p "/compact"and other commands work whenheadlessisn'tunsupported.- Dialog commands print a text summary instead (
/mcp→ a server status table,/config key=valuesets values).
2. Shared UI building blocks (build once, reuse in many commands)
- Picker: a filterable list with preview,
multi-select, and key hints. Used by
/resume,/rewind,/model,/theme,/mcp,/skills,/copy,/tasks. - Settings panel: tabbed (Settings, Status, Usage,
Stats). Used by
/config,/status,/usage. - Confirm dialog with a "don't ask again" option.
- Diff viewer: GIT_SPEC §8.1.
- Progress view for workflows and background tasks: PROCESS_SPEC §13.
- Text-mode fallback for each of the above, for
-pand non-TTY sessions.
3. Command catalog
Status column:
- Implement: same behavior as Claude Code.
- Local: adapted to a local equivalent.
- Skip: depends on Anthropic accounts, billing or cloud; not implemented. Typing it shows "not available in this agent" instead of "Unknown command".
3.1 Session and conversation
| Command | Aliases | Status | Behavior |
|---|---|---|---|
/clear [name] |
/reset, /new |
Implement | New empty conversation; memory kept; optional name labels the old
one in /resume; old one still reachable from the rewind
menu in this process |
/compact [instructions] |
Implement | AGENT_SPEC §10, focus instructions passed to the summarizer | |
/autocompact [auto|<tokens>] |
Implement | Set the auto-compact threshold (e.g. 24k,
auto = tuned for model); saved to user settings; dialog
without args |
|
/context [all] |
Implement | Colored grid of context use (system, tools, memory, skills, MCP,
messages, free) plus optimization tips and an over-limit warning;
all expands the breakdown |
|
/resume [session] |
/continue |
Implement | Picker or by id/name; background sessions marked
bg |
/rename [name] |
Implement | Rename the session (auto-name from history if empty); strip control/invisible chars; cap 200 chars; reject if empty | |
/branch [name] |
Implement | Branch the conversation at this point and switch into the branch;
original kept for /resume |
|
/fork [prompt] |
Implement | Copy the conversation into a new background session (§3.6) and keep working here; the copy is told to use its own worktree | |
/subtask <task> |
Implement | Forked background subagent that inherits the full conversation; its result returns here | |
/btw [question] |
Implement | Side question answered with current context but not added to history; no arg shows past side questions | |
/rewind |
/checkpoint, /undo |
Implement | AGENT_SPEC §11: restore code, conversation or both, or "summarize from here" |
/export [filename] |
Implement | Plain text or markdown; dialog (clipboard or file) without arg | |
/copy [N] |
Implement | Copy the Nth-latest response; picker for code blocks; w
writes to a file (useful over SSH, OSC 52 fallback) |
|
/todos |
Implement | Show the current task list (AGENT_SPEC §5.12); runs while busy | |
/recap |
Implement | One-line summary of the session (small model); also shown automatically after the user returns from being idle | |
/goal [condition|clear] |
Implement | Keep working across turns until the condition is met (evaluated by a
judge model call after each turn);
clear/stop/off/reset/none/cancel removes it; max-iterations
guard |
|
/exit |
/quit |
Implement | Exit (PROCESS_SPEC §13 exit prompt); in an attached background session, detach instead |
/stop |
Implement | Stop the attached background session; keep transcript and worktree | |
/background [prompt] |
/bg |
Local | Detach this session to run as a local background agent (§3.6); optional last instruction |
/teleport |
/tp |
Skip | Cloud sessions |
/remote-control |
/rc |
Skip (optional later: local web UI) | claude.ai remote control |
/desktop |
/app |
Skip | Desktop app handoff |
3.2 Model and behavior
| Command | Aliases | Status | Behavior |
|---|---|---|---|
/model [model] |
Implement | Picker of configured local models with context size; saves the
default; s = this session only; ←/→ adjusts effort;
cache-invalidation warning |
|
/effort [level|auto|status] |
Implement | Maps to reasoning budget / thinking tokens / sampling settings for
the local model; max session-only; status
prints the level |
|
/fast [on|off] |
Local | Switch to the configured fast/small model or a lower-precision quant for speed | |
/advisor [model|off] |
Local | Second local model consulted at key moments (before plans, after
failures) via an Advisor tool |
|
/plan [description] |
Implement | Enter plan mode; with a description, start planning immediately | |
/output-style [style] |
Implement | AGENT_SPEC §18; list or switch | |
/config [key=value …] |
/settings |
Implement | Settings panel; key=value sets directly (also in
-p); --help lists keys; can turn off but not
turn on settings that need confirmation |
/update-config [request] |
Implement (skill) | Describe a settings change; the model edits the right
settings.json (permissions, env, hooks) |
|
/permissions |
/allowed-tools |
Implement | Rules by scope, add/remove, working directories, recent denials; applies from the next tool call |
/fewer-permission-prompts |
Implement (skill) | Scan transcripts for common read-only Bash/MCP calls and propose an allowlist for project settings | |
/sandbox |
Implement | Toggle the OS sandbox (AGENT_SPEC §6.5) where supported | |
/auto-mode-setup |
Local (later) | Only if an auto-approval classifier mode is built: draft environment entries for it |
3.3 Project setup and context
| Command | Status | Behavior |
|---|---|---|
/init |
Implement | AGENT_SPEC §8.6, plus a proposal for services.json
(PROCESS_SPEC §9); if config from other agents is found, offer
/import |
/memory |
Implement | Edit memory files; view and toggle auto-memory entries if auto-memory exists |
/add-dir <path> |
Implement | Add a working directory; path completion; most config isn't loaded
from added dirs; reject network paths; runs DirectoryAdded
hooks; when busy, confirm now and allow from the next tool call |
/cd <path> |
Implement | Move the session to a new cwd, keeping the conversation; re-detect
git, memory and project settings (with trust prompt); differs from
/add-dir |
/import [codex|gemini|cursor|claude] [--dry-run] [--yes] |
Local | Import instruction files, MCP servers, commands, agents and skills
from other agents' config dirs (including .claude/ and
CLAUDE.md) |
/agents |
Implement | List, create and edit subagent definitions (AGENT_SPEC §12) |
/list-agents |
/peers · Local (later) |
List subagents and sessions this session can message |
/skills |
Implement | List with name, scope, description, token cost, validity and
shadowing (AGENT_SPEC §13.6); filter; t sorts by tokens;
Space/Enter cycles visibility (model, menu, both, off); Esc saves; shows
or opens one |
/reload-skills |
Implement | Re-scan skill and command dirs; report added and removed |
/skill-doctor |
Implement | Per-skill context cost and usage counts from local transcripts; suggest ones to disable |
/hooks |
Implement | View hook configs by event, source and matcher; warn on changes since session start |
/mcp [reconnect|enable|disable <server|all>] |
Implement | AGENT_SPEC §16.9; text summary in -p |
/plugin [subcommand] |
Implement (with plugins milestone) | list, install, enable, disable, update, marketplace |
/reload-plugins [--force] |
Implement (with plugins) | Reload; warn and skip if MCP tool changes would invalidate the cache
unless --force |
/plugin-authoring |
Local (optional skill) | Reference for writing plugins for this agent |
/keybindings |
Implement | Open the keybindings file in $EDITOR (create with
defaults if missing) |
/statusline |
Implement | Configure the status line from a description, or auto-derive from the shell prompt (PS1) |
/terminal-setup |
Implement | Install Shift+Enter newline bindings for common terminals and editors; macOS Terminal Option+Enter |
/theme |
Implement | auto, light/dark, daltonized, ANSI, custom themes from
~/.agent/themes/ |
/color [color|default] |
Implement | Prompt bar color for this session; random without arg; works in
-p |
/tui [default|fullscreen] |
Local (later) | Switch renderer if an alt-screen renderer exists |
/focus |
Local (with fullscreen) | Show only the last prompt, a tool summary and the final response |
/scroll-speed |
Local (with fullscreen) | Mouse wheel speed |
/voice [hold|tap|off] |
Local (optional) | Dictation via local speech-to-text (e.g. whisper.cpp) |
/ide |
Local (later) | IDE integration status, if an editor extension or LSP bridge exists |
/chrome, /claude-in-chrome |
Skip (or Local via a Playwright skill, PROCESS_SPEC §10.8) | Browser extension |
3.4 Code, git and review (behavior in GIT_SPEC)
| Command | Aliases | Status | Behavior |
|---|---|---|---|
/diff |
Implement | GIT_SPEC §8.1 | |
/code-review [level] [--fix] [--comment] [--max-findings n] [pr#|branch|path] |
/review |
Implement (skill) | GIT_SPEC §8.2; remembers the last level; ultra maps to
max with more local agents |
/ultrareview [PR|branch] |
Local | Alias of /code-review max (no cloud) |
|
/security-review |
Implement (skill) | GIT_SPEC §8.3 | |
/simplify [target] |
Implement (skill) | GIT_SPEC §8.4 | |
/batch <instruction> |
Implement (workflow) | GIT_SPEC §9 | |
/autofix-pr [prompt] |
Local | GIT_SPEC §5.2 local loop | |
/commit, /pr, /bisect |
Implement (extra, not in Claude Code's list) | GIT_SPEC §3, §5.1, §6 | |
/install-github-app |
Local (optional) | Generate a GitHub Actions workflow for a self-hosted runner (GIT_SPEC §13) | |
/run |
Implement (skill) | Build, launch and drive the project's app to see a change working;
uses services.json and integrations (PROCESS_SPEC) |
|
/verify |
Implement (skill, user-invoked only) | Confirm a change by running the app and observing the result, not just tests | |
/run-skill-generator |
Implement (skill) | Write a per-project skill that teaches /run and
/verify to build, launch and drive the app from clean |
3.5 Background work, scheduling and workflows
| Command | Aliases | Status | Behavior |
|---|---|---|---|
/tasks |
/bashes |
Implement | PROCESS_SPEC §13; includes finished subagents |
/loop [interval] [prompt] |
/proactive |
Implement (skill) | Repeat a prompt while the session is open; no interval = model
self-paces with ScheduleWakeup; no prompt = built-in maintenance prompt
or .agent/loop.md |
/schedule [description] |
/routines |
Local | Recurring tasks via local cron or systemd timers / launchd / Task
Scheduler running agent -p; list, update, run now, recent
runs |
/workflows |
Implement (with workflows) | Progress view: watch, pause, resume, save running and completed workflows | |
/workflow-authoring |
Local (with workflows) | Reference for writing workflow scripts | |
/deep-research <question> |
Local (workflow) | Fan out web searches if a search provider is configured; otherwise research local docs/repo; cited report |
3.6
Background sessions (needed by /background,
/fork, /stop, /resume)
- A local daemon or supervisor (on top of the ProcessManager) runs
detached agent sessions.
agent agentslists them, andagent attach <id>attaches. - A session's state is in its transcript, so attaching streams the live transcript and lets the user type.
- Peek replies: send one message to a background session without attaching.
3.7 Diagnostics, info and help
| Command | Aliases | Status | Behavior |
|---|---|---|---|
/help |
Implement | All commands grouped by type and source, plus key shortcuts | |
/status |
Implement | Version, model and endpoint, interpreter connectivity, settings sources, MCP, memory files, session kind (interactive/background attached/unattended); runs while busy | |
/usage |
/cost, /stats |
Local | Session tokens (input/output/cached), tokens/s, wall time, optional cost from a price table; Stats tab: sessions, tokens per day, top tools |
/doctor [prompt-audit [path]] |
/checkup |
Implement (skill) | Install, settings, extensions, memory file problems, interpreter
reachability, ripgrep/git/gh, orphan processes/worktrees; proposes fixes
applied after confirmation; prompt-audit reviews
memory/skill text for conflicts and bloat |
/debug [description] |
Implement (skill) | Turn on debug logging from now; read the session debug log and diagnose | |
/bug [report] |
/share |
Local | Write a local feedback bundle (sanitized transcript + diagnostics)
to ~/.agent/feedback-bundles/ after a consent screen
choosing how much history |
/feedback [report] |
Local | Same dialog, plus the queue of drafts the model wrote, if a feedback tool exists | |
/release-notes |
Implement | Version picker over the local CHANGELOG; shown in transcript, not to the model | |
/insights |
Local | HTML report from local transcripts: projects, usage patterns, frequent failures, features to try | |
/team-onboarding |
Local | Markdown onboarding guide from the last 30 days of local usage (commands, MCP servers, skills) | |
/heapdump |
Local (hidden) | Memory diagnostics for the agent process (language-specific) | |
/powerup |
Local (optional) | Interactive feature lessons |
3.8 Skipped (Anthropic account, billing or cloud only)
/login, /logout, /upgrade,
/usage-credits, /rate-limit-options,
/privacy-settings, /passes,
/stickers, /radio, /mobile
(/ios, /android),
/install-slack-app, /web-setup,
/remote-env, /setup-bedrock,
/setup-vertex, /design,
/design-login, /design-sync,
/slides, /artifacts,
/artifact-capabilities, /artifact-diagramming,
/claude-api, /dataviz (could become a
local skill), /teleport, /remote-control,
/desktop. Already removed upstream, so don't implement:
/pr-comments, /ultraplan, /vim
(editor mode lives in /config).
3.9 MCP prompts
- Server prompts are registered as
type: mcp-promptcommands (AGENT_SPEC §16.6), with arguments mapped in order and autocomplete hints.
4. Bundled skills shipped with the agent
These are prompt commands written as SKILL.md folders under
src/bundled-skills/, so users can read and override
them:
commit, pr, code-review,
security-review, simplify, batch,
bisect, init, update-config,
fewer-permission-prompts, doctor,
debug, loop, run,
verify, run-skill-generator,
skill-creator, autofix-pr,
deep-research.
Each one:
- declares
allowed-toolsnarrowly - has a test with the mock model asserting the expanded prompt and tool calls
- has a real-model eval
5. Settings (additions to AGENT_SPEC §7)
commands.legacyDirs (bool),
commands.maxStack (default 6), skillOverrides
({name: "on"|"menu-only"|"model-only"|"off"}),
review.defaultLevel, goal.maxIterations,
loop.defaultPrompt, schedule.backend
(cron|systemd|launchd|taskscheduler), ui.viewMode,
ui.promptColor, feedback.bundleDir.
6. Hooks (additions to AGENT_SPEC §15)
UserPromptSubmitreceives commands after parsing, withcommandandargsfields. It can block or rewrite them.- New events:
CommandRun(name, args, source, result status) andDirectoryAdded(from/add-dir).
7. Testing
- Parser:
- start-of-message rule, escapes, stacking limit, quotes in
$1… - unknown-command suggestions, namespaced names, precedence and shadowing
- start-of-message rule, escapes, stacking limit, quotes in
- Menu matching:
- a table of inputs mapped to the expected highlight or no highlight
(
/adddir,/new, typos, hidden commands, unavailable commands)
- a table of inputs mapped to the expected highlight or no highlight
(
- Busy behavior: queue vs immediate vs
immediate-dialog, using a mock turn in progress. Assert that
/permissionschanges apply from the next tool call. - Expansion:
!command with a permission prompt,@fileinlining, placeholder substitution, appending args when there's no placeholder, output caps. - Every builtin:
- at least one test (action result or dialog state)
- a
-ptest for every command marked headless-capable
- Every bundled skill: mock-model test plus an eval.
- Snapshot tests of
/help,/context,/statusand/usageoutput.
8. Milestones
Every milestone follows the same steps:
- Re-search the code.
- Update the gap analysis.
- Implement only ❌/🟡 items.
- Test.
- Show evidence.
- Report what was reused, extended and new.
| # | Milestone | Done when |
|---|---|---|
| C0 | Audit of every command in §3 +
docs/commands-design.md |
Gap table complete with evidence |
| C1 | Framework: registry, types, parser, stacking, precedence, unknown handling, busy modes, headless | Parser and busy-mode tests green |
| C2 | Command menu matching + argument completion + shared UI blocks (§2) | Matching table tests green; picker reused by ≥ 3 commands |
| C3 | Prompt commands = skills: loaders, frontmatter, expansion, legacy
dirs, overrides, /skills, /reload-skills |
Expansion tests green; custom command with ! and
@ works end to end |
| C4 | Session commands (§3.1) except background ones | Each has a test; /btw doesn't enter history;
/branch and /rewind verified |
| C5 | Model and behavior commands (§3.2) | Cache warning shown; /config key=value works in
-p |
| C6 | Project and context commands (§3.3) | /cd re-detects git and memory; /add-dir
mid-turn applies to the next tool call |
| C7 | Git and review commands (§3.4) | Depends on GIT_SPEC G3–G9 |
| C8 | Background work and scheduling (§3.5) + background sessions (§3.6) | /fork and /background sessions listed and
attachable; /schedule creates a working local timer |
| C9 | Diagnostics and info (§3.7) | /doctor finds and fixes a seeded misconfiguration;
/usage numbers match the transcript |
| C10 | Skip stubs (§3.8), MCP prompts, hooks additions, docs
(docs/commands.md generated from the registry) |
Every command in the reference list is accounted for |
Priority if time is short:
- C1–C4 give the essentials.
- C5–C7 cover daily use.
- C8–C10 give full parity.