OKLMdocumentation v1.0.3
On this page

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.

  1. 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.
  2. 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).
  3. 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.
  4. 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).
  5. 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).
  6. Full parity: agent M16 to M20, process P10 to P12, git G10 and G11, commands C10.