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

Implementation

Testing

Scope: staged, branch (default)

Code Review

Scope: staged, branch (default)

Summary

Scope: staged, branch (default)

Automation

Architecture

skills/                      # Single source of truth — neutral SKILL.md + agent personas
├── spec/
│   ├── SKILL.md
│   └── agents/
│       └── technical-product-manager.md  # Spec validation (completeness, feasibility)
├── task/
│   ├── SKILL.md
│   └── agents/
│       └── principal-engineer.md         # Task decomposition review
├── next/
│   ├── SKILL.md
│   └── agents/                           # Implementation agents
│       ├── frontend-developer.md
│       └── backend-architect.md
├── test/
│   ├── SKILL.md
│   └── agents/
│       └── test-writer.md                # Test generation
├── review/
│   ├── SKILL.md
│   └── agents/                           # Code review agents
│       ├── architect-reviewer.md         # Architectural issues
│       ├── senior-code-reviewer.md       # Implementation issues
│       └── false-positive-validator.md   # Validates and filters review findings
├── summary/
│   ├── SKILL.md
│   └── scripts/md-to-html.js
├── otto/
│   └── SKILL.md
└── reset/
    └── SKILL.md

.otto/                       # Workflow artifacts (git-ignored)
├── specs/                   # Specification documents (.md)
├── tasks/                   # Sessions and tasks (.json)
├── reviews/                 # Review fix plans (.json)
├── summaries/               # Generated HTML summaries
└── otto/
    └── sessions/            # Otto session state (state.json)

Provider-agnostic layout

skills/ is the single source of truth: each SKILL.md is neutral (no model: or allowed-tools:), and agent personas describe delegation in tool-neutral prose. From this one source, both providers are wired up:

• skills/ — neutral source skills and agent personas, read directly by Claude Code.
• scripts/build-codex-plugin.mjs (npm run build) — generates the Codex app package at plugins/ottonomous/ by copying the skills and emitting a per-skill agents/openai.yaml Codex interface file.
• .claude-plugin/ — Claude Code manifests (plugin.json points skills at ./skills and lists the agent dirs; marketplace.json). Claude Code ignores the generated openai.yaml files.
• .codex-plugin/ + .agents/plugins/ — Codex manifests. The root .codex-plugin/plugin.json is a compatibility manifest, and .agents/plugins/marketplace.json points at ./plugins/ottonomous.

The Codex package under plugins/ottonomous/ is generated, never hand-edited — regenerate it with npm run build whenever skills/ changes. This one-source-regenerate-the-mirror approach (modeled on the moss-skills repo) is the anti-drift mechanism.

Feedback

Found a bug or have a feature request? Open an issue.

License

MIT