Making AI Coders Write Things Down First

What it does

OSpec scaffolds a lightweight workflow layer inside your repository so AI coding agents can’t treat requirements as ephemeral chat filler. It creates a .ospec/ directory that holds active changes, archived history, skill manifests, and baseline knowledge docs, then pushes agents through a three-phase loop: propose a change, execute against the written spec, and verify before archiving. The framework integrates with Claude Code, Codex, Gemini, and OpenCode, or works as a plain CLI fallback, keeping the repository—not the conversation—as the source of truth.

The interesting bit

Rather than trusting a model’s memory across prompts, OSpec treats the repository itself as the agent’s state machine. Controller state lives in repo artifacts—active change directories, launch plans, and archived histories—so the agent must read and write its own context to proceed. This forces the model to document its intent before it writes code, making the repo a durable audit trail rather than a scratchpad.

Key highlights

• Durable specs over chat history: requirements, design, and verification live as files in .ospec/, not as ephemeral prompts.
• Multi-agent support: built for Claude Code, Codex/GPT, Gemini, OpenCode, and direct CLI fallback workflows.
• One-change-at-a-time discipline: the default path moves a single requirement through an active change to prevent scope creep.
• Nested project layout: initializes under .ospec/ with .skillrc persistence for document language and project metadata.
• Verification gate: changes must pass explicit verification and finalization before they are archived.

Caveats

• The README is dense with legacy migration paths, nested vs. flat layouts, and language resolution orders, suggesting the project is still settling its own file structure.
• Agent execution relies heavily on each assistant’s native sub-agent capabilities (Claude Tasks, Codex spawn_agent, etc.), and the framework does not start workers itself; it only writes launch plans, so your mileage varies by which AI tool you pair it with.

Verdict

Teams already using Claude Code or Codex who are tired of debugging “what did the agent think it was doing?” will find OSpec a useful accountability layer. If you prefer to iterate alone in a single chat window without file overhead, this will feel like unnecessary paperwork.