Workflows

New project

respex init "a CLI that converts CSV to JSON"
respex refine
respex diff --refine latest
respex commit -m "initial spec"
respex apply
respex apply          # already applied

Existing project

Automatic baseline structure

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

The agent prefers a single SPEC.md. When independent capability boundaries warrant multiple files, it instead leaves a bundle proposal; accept it after review:

respex baseline accept

Then commit and apply either structure:

respex commit -m "baseline existing implementation"
respex apply

Use respex baseline --merge if SPEC.md already has meaningful content.

See Multi-file specs for details.

Refine loop

respex refine
respex diff --refine latest
respex commit -m "clarify auth requirements"
respex apply

Refinement is repeatable. ReSpex rejects a refine that would be a no-op:

• The spec is still the generated skeleton.
• The exact same spec, prompt, and agent configuration was last refined unchanged.

Use respex refine --force to override either guard.

Review before applying

respex diff          # working vs last commit
respex commit        # snapshot if acceptable
respex apply

apply refuses to run if the working spec differs from the last committed version; commit first.

Verification loop

respex verify              # run the configured [verify] checks
respex apply               # re-runs the agent while verification fails

With [verify] configured, apply chains the checks after the agent and treats a failed verification as drift: the next apply re-runs the agent rather than reporting “nothing to do”. Fix the code (or the checks) and the next apply passes. See Verification.

Rollback

respex diff --refine latest
respex restore --refine latest --before
respex diff --refine latest

Restore creates a reversible history entry, so you can change your mind.

Cancel an agent run

On Linux and macOS, Ctrl-C first interrupts the agent process group and force-kills it after a grace period. On Windows, ReSpex uses taskkill /T to terminate the agent process tree. The live spec is not modified on failure, timeout, or interruption.