State model

All Musketeer state lives on disk in the .musketeer/ directory as human-readable YAML files.

Core principles

State is explicit

All state is stored in named YAML files with clear purposes. There is no hidden state. You can inspect any file at any time with a text editor.

State is local

State is stored locally on disk in your project directory. State files are:

• Human-readable YAML
• Machine-parseable
• Self-contained (no external references required)
• Suitable for version control

Workspace configuration

The workspace config lives at .musketeer/musketeer.yml:

version: 1
workspace:
  state_dir: .musketeer
agents:
  originator:
    adapter: local
  cross_examiner:
    adapter: local
  executor:
    adapter: local
policy:
  executor_allowlist: []
  redaction:
    enabled: false
    patterns: []

This file defines the three agent seats (Originator, Cross-Examiner, Executor), their adapters, and workspace policy.

Run state

Each run is identified by a UUID (the replay_id) and stored in its own directory under .musketeer/runs/. A run contains five YAML files:

intent.yml

Owned by the Originator. Defines the goal:

replay_id: <uuid>
title: "Untitled"
outcome: "TBD"

constraints.yml

Owned by the Cross-Examiner. Sets boundaries:

replay_id: <uuid>
scope: []
non_goals: []
allowlist: []

plan.yml

Shared by Originator and Cross-Examiner. Defines tasks:

replay_id: <uuid>
tasks: []

Each task has an id, title, and status.

progress.yml

Owned by the Executor. Records sequenced progress entries:

replay_id: <uuid>
entries: []

Each entry has a seq (strictly increasing), ts (timestamp), role, and summary.

handoff.yml

Owned by the Executor. Records handoff notes:

replay_id: <uuid>
note: ""

State directory structure

.musketeer/
  musketeer.yml
  runs/
    <replay_id>/
      intent.yml
      constraints.yml
      plan.yml
      progress.yml
      handoff.yml

Querying state

The musketeer run status command shows run state:

musketeer run status                  # Show all runs
musketeer run status --replay <id>    # Show a specific run

When no --replay flag is given, run status lists all runs sorted lexicographically.

See run status for details.