End-to-end process

ReSpex is a small state machine around a Markdown spec. The goal is to keep the spec as the durable source of truth and use an agent CLI to converge the code toward it.

        ┌─────────────┐
        │  working    │
        │    spec     │
        └──────┬──────┘
               │
      ┌────────┼────────┐
      ▼        ▼        ▼
   edit     refine    baseline
      │        │        │
      └────────┴────────┘
               │
               ▼
        ┌─────────────┐
        │   commit    │  ← snapshot approved version
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │    apply    │  ← agent implements the snapshot
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │   verify    │  ← optional conformance checks ([verify] config)
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │  code + git │
        │   commit    │
        └─────────────┘

New project

1. Initialize and draft the spec

respex init "a CLI that converts CSV to JSON"

If an agent is configured, init writes a first SPEC.md for you. Otherwise it writes a skeleton and you should edit by hand or run respex refine after configuring an agent.

2. Review and commit

Read the spec, fix anything that is wrong, then snapshot it:

respex view
respex edit
respex commit -m "initial spec"

commit is the “approve” step. Until you commit, apply will refuse to run.

3. Optionally refine

Use refine when you want the agent to improve the spec for you:

respex commit -m "my manual edits"    # snapshot before the agent touches it
respex refine
respex diff --refine latest

refine rewrites the spec. It can remove or reword your edits. That is why you should commit first: the previous version is saved and you can restore it.

respex restore --refine latest --before

If the rewrite looks good, commit it:

respex commit -m "refined requirements"

4. Apply the spec

respex apply

Apply gives the agent an immutable copy of the committed spec. The agent edits the repository, not the spec. Review the code changes with git diff, then commit them in git.

4b. Verify conformance

When [verify] checks are configured (commands or the agent audit), apply runs them automatically after the agent finishes; you can also run them any time:

respex verify

A failed verification makes the next apply re-run the agent instead of reporting “nothing to do”, so the loop keeps pulling the codebase toward the spec. See Verification.

5. Iterate

When requirements change, update the spec and repeat:

respex edit
respex commit -m "add JSON output option"
respex apply
git diff

respex apply skips work that is already applied. When verification is configured, only a passed verification counts as applied.

Open Questions

If your spec has an ## Open Questions section, resolve the blocking ones before applying. See the Open Questions workflow page for the full pattern.

Multi-file projects

When spec_files is configured, you can work on one capability at a time:

respex view auth
respex edit auth
respex commit -m "clarify auth requirements"
respex apply auth
respex refine auth
respex check

commit always snapshots the whole bundle atomically; apply auth and refine auth use the master spec as context while touching only that feature.

Existing project

1. Initialize and baseline

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

baseline inspects the current code, tests, docs, and config, then writes a spec from observed behavior. It does not invent intent; uncertain areas go into Open Questions.

If SPEC.md already has meaningful content, add --merge:

respex baseline --merge --intent "..."

The agent prefers one spec but can propose a multi-file bundle when the repository has durable capabilities with independent requirement boundaries. When it does:

respex diff --baseline latest
respex baseline accept
respex commit -m "multi-file baseline"

2. Refine or edit, then apply

From this point the workflow is the same as a new project:

respex edit
respex commit
respex apply

When to edit, when to refine

You want to…	Use
Write exactly what you mean	`respex edit`
Ask the agent to improve the spec	`respex refine`
Derive a spec from existing code	`respex baseline`
Snapshot the working spec	`respex commit`
Make the repo match the committed spec	`respex apply`

A safe rule:

Edit when you know the change you want.
Refine when you want the agent to critique and rewrite.
Always commit before a risky refine so diff and restore work.

Recovery checkpoints

Every commit and every agent operation that changes the spec saves a before/after snapshot in .respex/state.db.

respex log
respex diff --refine latest
respex diff --baseline latest
respex restore --refine 3 --before
respex restore --baseline 2 --before

Restore is itself reversible, so experimenting is safe.

Inspection commands

respex status          # spec state, dirty flag, operation lock, agent
respex log             # versions, baselines, refinements, applies, verifications
respex verify          # run conformance checks against the working tree
respex spec validate   # required sections check
respex doctor          # config, tools, state, lock health

Typical session

respex init "CSV to JSON CLI"
respex view
respex edit
respex commit -m "initial spec"
respex apply
git diff
git commit -m "implement CSV to JSON CLI"

respex edit
respex commit -m "add streaming mode"
respex apply
git diff
git commit -m "add streaming mode"