EsperKit

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

Works with Claude Code and Codex. Supports single-agent interactive work and multi-agent autonomous runs across providers.

Install

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.

Workflows

EsperKit supports two complementary development styles. Spec-to-Code supports both interactive (single-agent) and autonomous (multi-agent) execution.

flowchart LR
    D{Starting point?}

    D -->|Spec-first| E[Revise spec]
    D -->|Direct request| P[Plan increment]

    E --> G[Approve]
    P --> G

    G --> M{Execution mode?}

    M -->|Interactive| H[Agent implements] --> O

    M -->|Autonomous| I[Orchestrator splits tasks]
    I --> J[Workers implement in parallel]
    J --> K{Reviewer evaluates}
    K -->|Fail| J
    K -->|Pass| O

    O[Review & sync] -->|More work| D

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 spec and begin execution (no second approval gate)
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.

Commands

| Command | What it does | |---|---| | esper:init | Interview, scaffold project, write constitution | | esper:spec | Open or create the spec working file for authoring and revision | | esper:atom | Create a single bounded increment from a direct request | | esper:batch | Create a queued series of related increments | | esper:go | Cross the active approval boundary and advance the workflow | | esper:continue | Resume interrupted work from current project state | | esper:review | Verify implementation against the approved plan and specs | | esper:sync | Force or retry post-implementation code-to-spec sync | | esper:context | Show current project state and next safe action |

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

CLI

| Command | What it does | |---|---| | esperkit install | Install or update host-specific skills | | esperkit init | Create deterministic project scaffolding | | esperkit config | Read or write project config | | esperkit context get | Print runtime context as JSON | | esperkit spec | Manage the spec tree (index, get, create, set-root, archive) | | esperkit increment | Manage increments (list, get, create, activate, finish, set, group) | | esperkit run | Manage autonomous runs (create, get, list, stop) | | esperkit doctor | Run project health checks | | esperkit migrate | Migrate project state to the latest schema |

Core Concepts

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. Single-job mode (one atomic increment) or queued mode (a series of increments processed sequentially).

Runs — machine-readable autonomous execution records derived from an approved scope contract and its corresponding parent increment.

Task packets — bounded work items inside a run, subordinate to the parent increment.

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.

Project Structure

.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
└── runs/                   # autonomous execution records
    └── <run-id>/
        ├── run.json
        ├── tasks/
        └── reviews/

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

Choosing the Right Entry

| Situation | Command | |---|---| | Architecture or behavior needs design before coding (approved spec goes directly to execution) | esper:spec | | Small, bounded task with a known outcome | esper:atom | | Multiple related changes that should be queued | esper:batch | | Returning after a break or state is unclear | esper:context |

Design Principles

• Tool-neutral first — project state must remain readable without dependence on one vendor runtime
• Specs are durable — the spec tree must live in files, be revisable, and stay aligned with shipped behavior
• One contract at a time — in Spec-to-Code, the approved spec is authoritative; in Plan-to-Spec, one parent increment is authoritative
• Frozen inputs for autonomy — autonomous runs review against persisted artifacts, not conversation history
• Bounded autonomy — automated loops require explicit stop conditions and escalation rules
• Human-readable behavior — the spec tree must make intended and current behavior easy for a user to inspect quickly

Docs

• User Manual — day-to-day usage guide covering both workflows, all commands, and best practices
• Spec Index — entrypoint to the split spec tree covering core, workflow, state, CLI, skills, and patterns

License

MIT