Tool-neutral, simple workflow layer for spec-driven software development. Gives coding agents a durable project constitution, system specs, structured increments, and verifiable delivery rules.

Works with Claude Code and Codex.

npm install -g esperkit
esperkit install

Then initialize through the agent:

esper:init

This interviews you, creates the .esper/ directory with a constitution, spec scaffolding, and workflow config.

EsperKit supports two complementary development styles.

Spec-to-Code — define or revise the system spec first, then derive implementation from it.

esper:spec    →  open or create the spec working file, revise with the agent
esper:go      →  approve specs, derive increment plan
esper:go      →  approve plan, implement
esper:review  →  verify implementation

Plan-to-Spec — start from a direct request, implement in bounded increments, then sync back into specs.

esper:atom    →  single bounded task (or esper:batch for a queue)
esper:go      →  approve plan, implement
esper:review  →  verify implementation
esper:sync    →  force spec sync if needed (usually automatic)

Both workflows use esper:go as the shared approval gate and esper:continue to resume interrupted sessions.

Use the same esper:* command names across hosts, including Claude Code and Codex.

Constitution — durable project-level document describing what the project is and is not, key technical decisions, testing strategy, and principles.

Specs — long-lived system description for agents and humans. Architecture, behavior, interfaces, constraints. Not temporary task notes.

Increments — bounded units of delivery. Each stores what will change, why, how to verify it, and which specs it touches. Atomic (single task) or systematic (batch queue).

Working file — the Markdown file that serves as the shared review surface between you and the agent. Chat, edit directly, or leave comments inside it.

.esper/
├── esper.json              # project config and workflow preferences
├── context.json            # machine-readable runtime state
├── CONSTITUTION.md         # project vision and constraints
├── WORKFLOW.md             # agent bootstrap instructions
└── increments/
    ├── pending/            # queued work
    ├── active/             # current working increment (max 1)
    ├── done/               # completed, not yet archived
    └── archived/           # closed historical increments

<spec_root>/                # default: specs/
├── index.md                # spec tree entrypoint
├── _work/                  # temporary spec coordination files
└── ...                     # organized by domain

• Tool-neutral — project state is readable without depending on one vendor's runtime
• Specs are durable — the spec tree lives in files, stays revisable, and remains aligned with shipped work
• Progressive structure — small work stays light; large work gets more rigor
• AI-native by default — simple intent-level commands; the agent handles the responsible next steps
• Zero dependencies — installs instantly with no dependency tree
• Fail loudly — verification steps that are advertised as blocking must block

• User Manual — day-to-day usage guide covering both workflows, all commands, and best practices
• Product Spec — full specification defining artifacts, requirements, and the workflow model

MIT