A lightweight spec workflow for coding with agents

Why OneSpec

If one of these sounds familiar:

• Your spec tool wrote more markdown than code.

  OneSpec keeps one prose file per change. A bug fix is a single patch, with no spec file at all.

• The plan turned out to be wrong halfway through implementation.

  Only the immediate building horizon is planned in detail. Everything after it stays a one-line backlog item, and each plan starts with a review of the last build.

• The agent said “done”, and it wasn’t.

  Each patch needs a test that fails before the change and passes after, with the whole suite green. The build records what was run and what came back.

• Old notes went stale, and the agent believed them.

  When a change is finished, its lasting rules fold into your specs as a diff you approve. The working plan is retired, not left for the agent to read.

How it works

1. Fix something now.

   Run /onepatch with a small change, a bug or a red CI job. It finds the cause, writes a failing test, fixes it and runs the suite. No spec needed.

2. Build a planned change.

   Write the goal and a backlog in one file. /oneplan plans the next build and stops for your approval. /onebuild carries it out, one verified commit per patch. Repeat.

3. Close it.

   /onewrap folds the change’s lasting rules into your specs and retires the change file.

Start with onepatch. Grow into the rest when you need it.