Getting started

Initialize a new project

respex init "a CLI that converts CSV to JSON"

This creates:

.respex/
├── config.toml
├── state.db
├── logs/
└── tmp/
SPEC.md

If an agent is configured, respex init "..." drafts the first SPEC.md from the description. Otherwise it writes a skeleton and tells you to configure an agent and run respex refine.

Existing repository

For an existing codebase, derive an initial spec from observed code, tests, documentation, and configuration:

respex init
respex baseline --intent "what this project is meant to accomplish"
respex diff --baseline latest
respex commit -m "baseline existing implementation"

Use respex baseline --merge when SPEC.md already contains meaningful content.

The baseline agent prefers one spec and chooses a multi-file bundle only when the repository has independent capability boundaries. See Multi-file specs.

Edit and refine

respex edit              # open SPEC.md in your configured editor
respex refine            # agent improves the spec using the repository
respex diff --refine latest
respex commit -m "refined auth requirements"

Refinement is repeatable. ReSpex stores the before/after content of every refinement so you can review or restore.

Apply the spec

respex apply

Apply gives the agent an immutable copy of the committed spec, then runs the agent against the repository. Output is captured in .respex/logs/.

Run respex apply again and ReSpex reports that the version is already applied.

With [verify] checks configured in .respex/config.toml (commands, or audit = true for an agent audit), respex verify runs conformance checks against the working tree and every whole-version apply chains them after the agent finishes. See Verification.