Otto is a recipe-driven AI-development workflow assembled from three open-source projects — spec-kit, agent-skills, and Matt Pocock's skills — without forking, copying, or modifying any of them. Where they overlap, Otto routes instead of merging: a thin capability registry + router + workflow graph that picks the right unit from the right source at the right moment.
spec-kit = SKELETON durable state, governance, the autonomous engine
agent-skills = MUSCLE the SDLC practices — esp. review, security, ship
pocock skills = MUSCLE alignment, domain language, diagnosis, architecture
Otto = NERVOUS SYSTEM selection, sequencing, project memory, the install recipe
This repository is published as a design artifact. The primary intended use is reading DESIGN.md — the decision-of-record, and the best thing in the repo — and taking whatever ideas are useful. Installing and running Otto is possible (USAGE.md) but unsupported: it was built for one person's machines, hosts, and working habits.
Assemble a serious AI-assisted development practice today and you end up with several skill libraries installed at once — and they overlap. Three plausible responses: pick one and lose the others' strengths; merge them into a fourth library and inherit three maintenance burdens; or keep all three read-only and put the intelligence in a routing layer that knows which library answers which moment. Otto is the third option, taken seriously: every capability maps to exactly one primary unit, documented alternates, and explicit swap criteria. The full argument is in ESSAY.md; the decisions and their rejected alternatives are in DESIGN.md.
Five thin layers, all Markdown + one YAML + shell scripts — no build, no runtime, no dependency tree:
sources (read-only clones, pinned) sources/sources.md
└─ capability registry registry/capabilities.yaml ← canonical
└─ router router/ (/flow, routing policy)
└─ lifecycle spine + gates workflows/spine.md
└─ 11 recipe presets workflows/recipes/
Two co-equal modes drive it.
Manual — /flow. Describe intent; Otto reads repo state and returns a routing card:
recipe → stage → next capability → exact invocation → the gate to clear.
/flow add CSV export to the reports page
Otto ▸ feature · stage 2 · SPEC
Next: author-spec — /speckit.specify
Why: feature in an existing repo; no specs/<branch>/spec.md yet.
Layer: spec-driven-development (pull its template depth into the spec)
Gate: spec.md with user stories + success criteria; no open [NEEDS CLARIFICATION].
After: PLAN (/speckit.plan → /speckit.tasks → /speckit.analyze)
Hands-off — /otto-conductor. Runs a whole recipe unattended — stage → gate → advance —
pausing only at human-gated decision points (constitution, spec acceptance, go/no-go,
irreversible ops, and all git). Every run carries a declared ceiling and three stop
conditions (budget exhausted · a stage entered a 4th time · no progress on a repeated failure
signature), review steps run with no write tools, and judgment gates are checked by a
fresh-context evaluator that never saw the build.
/otto-conductor bugfix: login returns 500 on empty password
Worked scenarios A–F (bugfix, feature, multi-repo migration, dependency assessment, doc extraction, hardening fan-out): USAGE.md §9.
Three pieces of the design stand alone and are written up to be readable with no knowledge of Otto:
- Footprint manifest & private mode — a per-repo inventory of everything your dev tooling touched, plus a git-disposition choice that can keep the tooling entirely out of a repo's history.
- Gate classes — a mechanical | judgment | human taxonomy for workflow gates, with per-class enforcement and independent verification.
- Run budgets & stop conditions — declared ceilings for autonomous runs, including a no-progress rule based on repeated failure signatures.
install/claude-code.md is the full wire-up (Claude Code-first;
install/portable.md sketches other hosts). Read
KNOWN-DRIFT.md first: the upstream pins are snapshots and all three
upstreams move fast — re-audit before installing. bash install/verify-otto.sh audits an
install against itself.
- Build complete (steps 1–7). Autonomous capabilities validated 13/13 (2026-07-15, full dry-run on a throwaway project — results and caveats in VALIDATION.md; the dry run's raw log lives outside this repo).
- That validation is Otto grading Otto with Otto's own gates; the repo records the circularity as an open item (BACKLOG.md F-07). One independent external check is recorded in VALIDATION.md Part 3.
- The pinned refs were captured 2026-06-08 and re-verified 2026-07-21 (KNOWN-DRIFT.md).
- Personally maintained, no support promise. Issues are welcome; a response is not
guaranteed. The
learnings/wisdom store the design describes is part of the live system but not included here (it accrues machine- and project-specific lessons); its template ships in memory/templates/learnings.md.
| Path | Layer | What |
|---|---|---|
| registry/capabilities.yaml | 1 | every capability → its best-of-breed source unit (+ compute: and tools: pins) |
| registry/compute.md · registry/tool-scope.md | 1 | pin policy: model/effort tiers · least-privilege tool profiles |
| workflows/spine.md | 3 | the lifecycle graph: stages, gates, entry points, modules, recipes |
| sources/sources.md | 0 | the three sources: pinned refs, licenses, install commands |
| USAGE.md | — | how-to guide: modes, capabilities, recipes, worked scenarios |
| VALIDATION.md | — | static-audit results + the executed dry-run (13/13 PASS, 2026-07-15) |
| BACKLOG.md | — | the deferred-work index — every row carries an act-on trigger |
| CLAUDE.md | — | agent operating rules for this repo (auto-loaded each session) |
| assessments/ | — | dated read-only assess records feeding the backlog (two included; the rest withheld for privacy) |
| ROADMAP.md | — | deferred layers reference: Portfolio layer, domain profiles |
| router/ · workflows/ · memory/ | 2–4 | /flow, 11 recipes, scope, autonomous conductor + Workflow backend, memory stack |
| install/ · EXTENDING.md | 6 | Claude Code + portable wire-up, extension guide, /otto-sync, /otto-distill |
| extracts/ | — | standalone write-ups of the portable ideas above |
| ESSAY.md | — | essay: layering three skill libraries without forking them |
| KNOWN-DRIFT.md | — | pinned-ref snapshot dates and what to re-audit before installing |
Best-of-breed + layer · hybrid tooling (conventions adopted, CLI optional) · spine + recipe presets · Claude Code-first, portable-ready · manual and hands-off co-equal. Each with rejected alternatives and swap criteria: DESIGN.md.
MIT — see LICENSE. Otto orchestrates its three upstreams and vendors none of their files; all three are MIT-licensed at the refs pinned in sources/sources.md, as recorded there.