theseus-protocol

Theseus Protocol

Theseus is a Thoughtbox-owned refactoring protocol.

The server-side Theseus implementation behind tb.theseus(...) owns scope, visa state, audit state, and terminal status. Codex hooks only ask Thoughtbox whether a write should be blocked.

Do not use .theseus/ files or scripts/theseus.sh as authoritative state. Do not rely on implicit git reset --hard recovery in the active workflow. Do not use legacy direct handles like thoughtbox_gateway or thoughtbox_theseus as the interaction surface when Code Mode is available.

API Surface

The current public Thoughtbox MCP surface is Code Mode:

• Discovery: thoughtbox_search
• Execution: thoughtbox_execute
• Theseus operations: tb.theseus({ ... })

Each thoughtbox_execute call should contain at most one state-mutating Theseus operation. Read-only confirmation calls such as tb.theseus({ operation: "status" }) are safe to use for state checks.

Runtime Contract

1. Protocol entry is explicit-only in v1.
2. If you need schema or example confirmation, call thoughtbox_search before executing.
3. Use thoughtbox_execute and call tb.theseus({ operation: ... }) for every protocol transition.
4. Hooks consult Thoughtbox before mutating file operations.
5. Hooks do not spawn agents or mutate protocol state.
6. Helper agents may audit or gather evidence, but only the coordinator calls tb.theseus.

Commands

init

Required inputs:

• Declared scope
• Optional refactor description

Call:

async () => {
  return await tb.theseus({
    operation: "init",
    scope: ["src/module-a.ts", "src/module-b/"],
    description: "<refactor goal>",
  });
}

After init, test files are write-locked and out-of-scope writes require a visa.

visa

Required inputs:

• Out-of-scope file path
• Justification

Call:

async () => {
  return await tb.theseus({
    operation: "visa",
    filePath: "src/dependency.ts",
    justification: "<why the scope must expand>",
    antiPatternAcknowledged: true,
  });
}