Agent specifications
The four specifications of the coding agent, which one owns each part they share, and the order to build them in. Each part is specified once, in its owner; the others point there.
Status: maintained (2026-11-02); the audits and designs are listed below.
The specifications
| Specification | Roadmap | Audit | Design |
|---|---|---|---|
| agent_skill_chat_spec.md: the agent (model, loop, tools, permissions, settings, memory, context, sessions, sub-agents, skills, hooks, MCP, terminal, headless) | M10 | gap-analysis.md | agent-design.md |
| process_spec.md: background processes, Monitor, events, language servers, services, integrations | M11 | gap-analysis.md | process-design.md |
| git_spec.md: repository context, safe commits, branches, pull requests, reviews, worktrees | M12 | gap-analysis.md | git-design.md |
| commands_spec.md: the slash-command framework and catalog | M13 | gap-analysis.md | commands-design.md |
Each starts with an audit of the existing code and searches again at every milestone, building only what is missing or partial.
Who owns what
Parts more than one specification described, and where each now lives. "Adds" means the other specification contributes entries or fields to the owner's mechanism, not a second mechanism.
| Part | Owner | Others |
|---|---|---|
| Slash-command framework, menu, custom commands, the catalog | commands §1–§3 | agent §14 (superseded), §13.5 (/skill-name), §19
(/ input mode) point there; each command's behavior stays
with its own section |
Background processes, their tools, /tasks
(/bashes) |
process §2, §3, §13 | agent §5.8 (background), §5.9, §22 point there |
| Monitor, event bus, scheduled wakeups | process §4 | agent §22; commands /loop, /schedule use
them |
| Ctrl+B (move to background) | process §3 | agent §19, process §13 point there |
| The command environment (editor, pager, prompt variables, markers) | process §2.2 | agent §5.8, git §2.4 point there |
| Processes of MCP servers | process §6 | agent §16.3 keeps the protocol |
| Processes and listing of background sub-agents | process §7 | agent §12 keeps the sub-agents themselves |
| Dangerous-pattern list (allow turned back into ask) | agent §6.4 | git §2.3, process §11 add entries |
| Notifications | agent §19 | process §13 adds triggers |
| Status line | agent §19 | git §1.3, process §13 add fields; commands /statusline
configures it |
| System reminders (injection into the conversation) | agent §4 | process §4.2 (events), git §1.2 (branch changes) use them |
| Trust question for a folder | agent §19, §24 | agent §13.7, §16.2, process §9, commands /cd use
it |
| Hooks (mechanism, events) | agent §15 | process §8, git §9, commands §6 add events |
| Settings (hierarchy, loader) | agent §7 | the other three add keys |
| Headless and stream-json | agent §20 | process §14 adds events, commands §1.9 runs commands |
| Git snapshot in the prompt | git §1.2 | agent §9 keeps its place in the prompt |
| Git workflows (commits, PRs, review, CI) | git §3, §5, §8, §13 | agent §21 points there |
Worktrees (session, sub-agent isolation, /batch) |
git §9 | agent §12, §21, commands /fork use them |
| Checkpoints and rewind | agent §11 | git §10 (relationship), git §2.5 and §8.1 (the agent's edited files) use them |
/doctor, /usage, /status,
/bug |
commands §3.7 | agent §23 keeps the usage tracking; each specification adds its checks |
| Small model | agent §2.5 | commands /fast, /advisor,
/recap use it |
| JSON-RPC module | process §5 (with agent §16) | two framings: Content-Length (language servers), newline-delimited (MCP) |
Order
Milestones of all four, in waves; within a wave they can go in parallel. A milestone never starts before the ones it depends on.
- Agent core: agent M1 to M3 (backend and stream events, cancel, messages, loop, tools). In parallel, process P1 and P2 (the job manager's data model, output, stopping, readiness probes, ports), which need nothing else.
- Control and context: agent M4 (permissions and the dangerous-pattern mechanism), M5 (prompt assembly, reminders), M5b (memory), M6 (settings). Then commands C1 to C3 (registry, menu, prompt commands; the agent's M10) and git G1 to G3 (detection, snapshot, classifier, safe commits).
- Long sessions: agent M7 (compaction) and M8 (sessions, resume, checkpoints). Then process P3 to P5 (background tools, orphans and resume, the event bus and Monitor) and commands C4 to C6.
- Daily use: agent M9 (terminal), M11 (hooks), M12
(sub-agents), M13 (skills, ToolSearch), M14 (headless); process P6
(language servers); git G4 to G6 (branches, conflicts,
/diff); commands C7 to C9 (git, background and diagnostic commands, once their owners are done). - Integrations: agent M15 (MCP), then process P7 (MCP and sub-agent processes, hook events); git G7 to G9 (hosts, review, worktrees); process P8 to P9 (services, first integrations).
- Full parity: agent M16 to M20, process P10 to P12, git G10 and G11, commands C10.