spec-orbit

Most spec-driven tools are a one-way pipeline — write a spec, generate a plan, implement it, done. The spec is scaffolding that gets discarded.

spec-orbit is different. The spec is the fixed center. Everything orbits it — planning, implementation, and verification — and the orbit is closed: /spec-check can audit a PR against the spec, or read the actual codebase and check whether the intent still holds. When it doesn't, you update the spec and the next cycle begins. The spec stays alive for the lifetime of the feature.

/spec       → think through a feature, capture decisions, save a spec
/spec-plan  → analyze a spec and identify what can be a self-contained plan
/implement  → execute the plan step by step, verify before calling it done
/spec-check → check whether a PR or the codebase still honours the spec

Built for Claude Code. The developer controls every handoff — nothing executes without approval.

Why spec-orbit

AI coding sessions are stateless. You close the session, the context is gone — and the next time you open it, you're reconstructing intent from git history, half-remembered decisions, and code that no longer looks like what you planned.

spec-orbit was built to solve this. The spec is your persistent context. Every decision made, every tradeoff considered, every open question — captured in a markdown file that lives in your repo. Start a new session and load the spec. Full context restored, instantly.

But a spec only works as persistent context if it stays accurate. That's the problem every other spec-driven tool ignores — they treat the spec as input to a pipeline, not as a living document. Once the code is written the spec is abandoned, and it starts drifting from reality immediately.

spec-orbit keeps the spec alive. /spec-check audits the codebase against the spec and flags where they've diverged — whether that's code that didn't follow the plan, or a spec that no longer reflects what was actually built. You update the spec, and it remains trustworthy for the next session.

The second reason spec-orbit exists: updating markdown files is painfully slow for an LLM. Loading a whole file into context just to change one section wastes tokens and time. spec-edit operates on individual sections — targeted reads and writes, no whole-file loads. The loop stays fast enough to actually use.

The orbit

        ┌─────────────────────────────────┐
        │                                 ▼
     /spec                          /spec-check
   capture intent              verify intent survived
        │                                 │
        ▼                                 │
    /spec-plan                            │
  plan a chunk                  spec outdated? update it
        │                                 │
        ▼                                 │
   /implement ───── code is written ──────┘
  execute the plan

The spec is never discarded. It is the reference point the loop returns to.

How it works

.specs/
└── auth/
    ├── spec.md                  ← intent, decisions, open questions
    ├── token-rotation.md        ← optional detail doc
    └── plans/
        └── token-rotation-backend.md  ← scoped checklist, ready for /implement

/spec is a thinking partner, not a transcription tool. It asks questions, challenges assumptions, and surfaces tradeoffs. Nothing is written until you ask.

/spec-plan reads the spec and figures out what can be broken into a coherent, independently shippable chunk. It proposes the split, you pick, it drafts the plan in chat and only saves once you approve.

/implement works through the plan one task at a time, tracking progress in the plan file's todo list. It never commits. When all tasks are done it runs whatever validation the project requires before declaring the work complete.

/spec-check closes the loop. Two modes: diff mode checks a PR or branch against the spec's key decisions; audit mode reads the actual source files and checks whether the intent described in the spec is still reflected in the code. If the spec is outdated, update it — and the next orbit begins.

All four skills use the spec-edit CLI tool to read and write spec files by section — fast, targeted, no whole-file reads.

Requirements

• Claude Code
• Bun — used to run the spec-edit tool
  • macOS / Linux: curl -fsSL https://bun.sh/install | bash
  • Windows: powershell -c "irm bun.sh/install.ps1 | iex"

Optional: Atlassian MCP configured in your environment (enables ticket context lookup when a Jira link is present in a spec).

Installation

Copy the skills/ and tools/ directories into Claude Code's config directory:

cp -r skills/* ~/.claude/skills/
mkdir -p ~/.claude/tools/spec-edit
cp tools/spec-edit/index.ts ~/.claude/tools/spec-edit/

Skills

/spec [topic]

Discuss and shape a spec. The AI asks questions rather than jumping to answers — the goal is to surface tradeoffs and decisions before writing anything down.

/spec                        → list existing specs, pick one or start new
/spec auth                   → open the auth spec

Specs are stored as markdown under .specs/ at the project root — the skill will offer to create it if it doesn't exist.

/spec-plan [spec-name] [hint]

Reads a spec and identifies what can be broken into self-contained, independently reviewable chunks of work. Proposes the split, lets you pick a chunk, then drafts scope and checklist in chat — only writing to disk once you approve.

/spec-plan                          → list specs, pick one
/spec-plan auth                     → plan a chunk of the auth spec
/spec-plan auth token-rotation      → plan a specific chunk

/implement [hint]

Execute a plan produced by /spec-plan. Reads the plan, confirms scope, seeds a todo list, and works through it one task at a time — updating checkboxes as it goes.

/implement                          → list available plans, pick one
/implement auth token-rotation      → find and run the matching plan

When all tasks are checked off, a code-verifier agent runs whatever validation the project requires — tests, static analysis, builds. Nothing is reported complete until it passes.

/spec-check [topic or PR]

Closes the orbit. Verify that code matches the spec — or that the spec still matches the code.

/spec-check                  → list specs, choose what to check
/spec-check auth             → audit the auth spec against current code
/spec-check auth 42          → check PR #42 against the auth spec

Reports one of: Aligned, Gaps, Deviations, Out of scope, or Spec outdated.

The spec-edit tool

tools/spec-edit/index.ts is a small Bun CLI for reading and writing spec markdown files by section. The skills use it internally, but you can also run it directly.

spec-edit status <specs-dir>                     list all specs and plans
spec-edit list <file>                            list sections with line counts
spec-edit read <file> [heading]                  print a section (or whole file)
spec-edit init <file> <title>                    create a new spec
spec-edit init-plan <file> <title>               create a new plan
spec-edit replace <file> <heading>               replace a section (stdin)
spec-edit append <file> <heading>                append to a section (stdin)
spec-edit insert <file> <after> <heading>        insert a new section (stdin)
spec-edit set-meta <file> <key> <value>          set a header metadata field

Handles CRLF line endings, backtick and tilde fenced code blocks, and trailing whitespace in headings.

Spec file format

# Feature Title

**Last updated:** 2026-06-01
**Jira:** PROJ-123

## Context

Why this exists and what problem it solves.

## Key Decisions

- Decision one
- Decision two

## Current Approach

How it works now.

## Open Questions

- Anything unresolved.

Plan files follow the same format with Scope, Checklist, Todo, and Open Questions sections. /implement owns only the Todo section — everything else is read-only during execution.