Ottonomous

Ottonomous 🚌💨

Skills for every stage of product development — spec writing, task prioritization, implementation, testing, code review, and summaries — that work in both Claude Code and OpenAI Codex.

Install

Claude Code

/plugin marketplace add brsbl/ottonomous
/plugin install ottonomous@ottonomous

Codex

codex plugin marketplace add brsbl/ottonomous

Dependencies

• Claude Code or Codex
• Node.js 18+
• Git

Philosophy

Invocation differs per provider: Claude Code uses /spec, Codex uses $spec. Throughout these docs skills are referred to by bare name (e.g. the spec skill).

Subagents for Context Isolation

Use subagents to isolate concerns and prevent context pollution:

• Context isolation: Each subagent gets only what it needs, nothing more. The orchestrator agent delegates to and manages subagents
• Specialization: Different expertise per agent (frontend-developer vs backend-architect, senior-code-reviewer vs architect-reviewer, test-writer, etc)

Skill/Subagent Separation

Skills and subagents have distinct responsibilities:

• Skills define what to hand off (file list, diff command, scope, context) and are instructions for the orchestrator agent
• Subagents define how to process what's handed off (criteria, detection rules, output format)

This keeps subagents self-contained and reusable while skills orchestrate the workflow. Skills describe delegation in tool-neutral prose so the same source runs on either provider — the runtime decides the actual model and delegation mechanics.

Swarm Orchestration

Skills coordinate multiple subagents working in parallel using background subagents — spawning concurrent work and waiting on the results:

Coordination patterns:

• Fan-out/Fan-in — Spawn N agents, wait for all, synthesize results. Used by review.
• Batches — Complete batch N before starting N+1 (for dependent work). Used by review fix.
• Pipeline — Sequential handoff between specialists. Used by otto.

Scaling: 1-4 items = 1 agent, 5-10 = 2-3 agents, 11+ = 3-5 agents. Group by directory or component type.

Iterative Review for Verification

Every phase has explicit verification:

• Planning: spec → spec review → user approval
• Implementation: code → code review → fix → commit
• Verification criteria: Each step defines "Done when..."
• Prioritized findings: P0-P2 across all skills (P0 = critical, P1 = important, P2 = minor)

Recommended Workflow

Invoke skills with /x in Claude Code or $x in Codex (e.g. /spec or $spec).

spec                      # define requirements via interview
  │
  ▼
task                      # break spec into sessions & tasks
  │
  ▼
┌───────────────────┐
│                   │
▼                   │
next batch          │     # implement sessions of tasks in parallel then stage results
│                   │
▼                   │
test write staged   │     # generate tests, then lint/typecheck/run all
│                   │
▼                   │
review staged       │     # multi-agent code review
│                   │
▼                   │
review fix staged   │     # fix P0-P2 issues
│                   │
▼                   │
commit ─────────────┘     # loop if more sessions/tasks
  │
  ▼
summary                   # generate semantic overview of changes, opened in browser
  │
  ▼
 PR

Reset context between steps (e.g. /clear in Claude Code).

Skills

The 8 skills: spec, task, next, test, review, summary, otto, reset.

Specification & Planning

Skill	Description
spec [idea]	Researches best practices, interviews you to define requirements and design. technical-product-manager validates completeness, consistency, feasibility, and technical correctness.
spec revise {spec}	Saves a comprehensive spec and goes straight to review with codebase exploration, skipping the interview.
spec list	Lists all specs with id, name, status, and created date.
task <spec-id>	Creates atomic tasks grouped into agent sessions. principal-engineer reviews work breakdown, dependencies, and completeness.
task list	Lists all tasks and their spec, sessions, status etc.

Implementation

Skill	Description
next	Returns next task id.
next session	Returns next session id.
next <id>	Launches a subagent to implement a task or session. Plans first, then implements.
next batch	Implements all highest-priority unblocked sessions in parallel.

Testing