devspecs

DevSpecs for Codex

Give Codex a durable thread outside the chat

DevSpecs adds repo-local context, bounded task state, and checkpointed handoffs to Codex without replacing Codex or storing its private session history.

Direct answer

Codex does the coding; DevSpecs keeps the work legible

Codex can inspect Git and the filesystem, plan a change, edit code, and run tests. DevSpecs gives that work an addressable local thread: the current goal, one permitted slice, relevant repo evidence, an explicit decision, and the next handoff.

Run the CLI directly when you want deterministic output to inspect. Use the generated Codex skills when you want Codex to create or continue one bounded slice through the same CLI primitives.

Mechanism

Two thin skills over one local CLI

`ds init --tool codex` writes repo-local skill instructions. They teach Codex how to use DevSpecs; they do not create a second task system.

Initialize
Run `ds init --tool codex`. The CLI writes `.agents/skills/ds-task/SKILL.md` and `.agents/skills/ds-apply/SKILL.md`.
$ds-task
Ask Codex to create or continue a bounded task, use diagnostic commands only when the target is unclear, and finish at one decision gate.
$ds-apply
Ask Codex to resolve and implement exactly one current slice, then stop after checkpointing promote, improve, rework, rollback, or block.
Re-enter
Run `ds recent` yourself or ask Codex to run it before planning when you return to work that has gone cold.

Product proof

What a clean Codex setup creates

Verified with DevSpecs v1.3.0 in a fresh Git repository. Explicit Codex setup works even when the empty repository has no Codex files to auto-detect.

ds init --yes --tool codex --index manual
  • .agents/skills/ds-task/SKILL.md · created · $ds-task
  • .agents/skills/ds-apply/SKILL.md · created · $ds-apply
  • Indexing not started automatically · run ds scan when ready
  • Next: $ds-task "goal"

Boundaries

What the Codex adapter does not do

  • The skills are local instructions, not an MCP server, agent runner, or background observer.
  • DevSpecs does not store Codex prompts, tool calls, hidden state, or the complete session transcript.
  • If an open Codex task does not discover newly generated skills, start a new task so it reloads the repository instructions.

Continue

See the workflow, then use the exact docs.

Persistent context for coding agentsUnderstand the local records that remain useful across agent sessions.Build a durable coding-agent handoffSee what should cross human-to-agent and agent-to-agent transitions.Follow one bounded FastAPI sliceInspect the real task, apply, test, and checkpoint receipts.

Try DevSpecs

Keep the thread in your repository.

Install the local CLI. Use the command docs when you need exact flags and lifecycle details.

Install CLIRead the task flow