Execution Modes

Modes control how many human checkpoints exist while spexso works on one issue. The mode is chosen on /spexso-start (via flag or prompt). The mode can be switched mid-session by saying "switch to copilot".

For autonomous runs across the whole backlog, see /spexso-marathon — it executes each issue in yolo mode and chains them via dependency-graph + priority + age ordering.

/spexso-start --yolo — Autonomous within one issue

Zero human gates during this issue's build. Claude reads the spec, plans, TDD-implements every task, self-reviews, commits, and finishes. After each task, runs /compact to keep context lean.

Best for: Greenfield features with solid specs. Boilerplate-heavy services. Long unattended sessions on a single well-specified issue.

Safety rails: Tests must pass per task. Auto-review rewrites critical/high issues. If tests fail 3x on a task, pauses and asks for human input. Each task also has a wall-clock ceiling (budgets.perTaskMinutes in .spexso/config.json, default 30) — once exceeded, the orchestrator must pause and escalate with the latency report (npx spexso observe report) instead of grinding on (see TDD flow).

One command, end to end. Each stage invokes the next in the same turn — start → plan → build → review → finish — so /spexso-start <id> --yolo needs no further input. Only the 3-strike rail, the full-suite gate in /spexso-finish and a rebase conflict halt it; low-severity review findings never do. Under an orchestrator (spexso-issue-runner in a marathon, a journey layer) the chaining is off: the orchestrator calls each step itself (ending with finish --train).

Note: --yolo controls how this one issue is executed. It does not chain to the next issue. Use /spexso-marathon for backlog-wide autonomous runs.

/spexso-start --pilot — Guided cruise

Two checkpoints per task: (1) plan approval, (2) test results review. Implementation between checkpoints runs autonomously. This is the recommended default for most work. When a wave runs parallel RED, the checkpoint granularity is the wave: one summary with per-task lines, instead of an interruption mid-wave.

Best for: Standard feature development. Enhancements. Integration work. When the developer wants oversight without micro-managing.

Checkpoint behavior: Claude presents the plan → developer approves/adjusts → Claude implements + tests → Claude shows "3 tests pass, 1 new file, 47 lines" → developer approves or requests changes.

/spexso-start --copilot — Pair programming

Every step requires explicit approval. Claude proposes, human decides, Claude executes one step, human reviews, repeat. Maximum control at the cost of speed.

Best for: Bug investigation. Production hotfixes. Sensitive code (auth, payments, data migration). When the spec is fuzzy and you're discovering requirements interactively.

Behavior: Claude functions as a thinking partner, not an executor. It suggests approaches, explains tradeoffs, and only writes code when told to.

Marathon vs mode — two different axes

Axis	Question it answers	Surface
Mode	How is this one issue executed?	/spexso-start --yolo | --pilot | --copilot
Marathon	Which issues do we work on, and in what order?	/spexso-marathon (each issue runs in yolo)

Marathon does the queue selection (dependency-aware, priority, age). Mode does the per-issue execution style. They're orthogonal — combining them is implicit: marathon always runs each issue in yolo. There is no "marathon-pilot".

Unattended marathon: /spexso-marathon --autopick is the same loop started by the online runner instead of a person — only auto-pick issues, sequential, an atomic branch claim at start, and each MR queued for GitLab auto-merge instead of merged. See Auto-pick.

Stop the line: before each wave the marathon runs npx spexso train guard. While an issue sits at stage::review with a needs::* label (needs::conflict-resolution, needs::attention) and an open MR, it exits with stop reason line_stopped and names the MR: the next issue would otherwise branch from a base without that work, and the conflicts pile up. Land or close the MR, then restart.

Queue transparency: Before starting the loop, marathon prints a pre-flight summary: how many issues are Ready (no open blockers), how many are Blocked (waiting on a blocker that is neither merged nor closed), and which issues are Not queued (wrong stage, type::tracking, assigned to others, a needs::* label). Nothing disappears silently.

Plan Behavior Per Mode

Mode	Plan behavior	Plan posted to GitLab?
yolo (incl. marathon)	Auto-plans silently. No human checkpoint. Plan is generated and immediately executed.	Yes — posted as issue comment for audit trail
pilot	Plan is generated and presented to developer. Developer approves, adjusts, or rejects. Then execution begins.	Yes — posted after approval
copilot	Plan is generated and presented. Developer can modify each task interactively before any execution starts.	Yes — posted after finalization

In all modes, the plan is always generated — skipping it is not possible. The difference is only whether the human sees and approves it before execution starts. This ensures that even yolo sessions have a traceable plan posted to GitLab for the tech lead to review.