Skip to content

refactor(run-mode): collapse the run-mode vocabulary and rewrite the mode docs #120

Description

@slowdini

Part of #113 ("Instant magic"). The user-facing tail of the in-session removal (#B). Doc-heavy.

Closes/supersedes #31 (run-mode tracking ticket): once one dispatch path remains, the multi-mode vocabulary collapses.

Why

After the in-session mechanism is removed (#B), the three-mode story (interactive / hybrid / headless) collapses to a single Cli dispatch path. "Headless" and "hybrid" were always the same mechanism differing only in who drives the loop, so we reframe headless as tacitly supported — the same runbook a human or an agent can drive — rather than a first-class mode carrying its own support claims. The --run-mode flag and RunMode enum become vestigial and the docs that narrate multiple modes need a rewrite.

Scope

  • Retire --run-mode: remove the flag, or keep it as a hidden deprecated no-op for one release. Collapse the RunMode enum now that one path remains.
  • Drop capabilities_for fields that existed only to gate mechanism choice.
  • conditions.json: stop recording run_mode (or pin a constant). Minor back-compat change to a version-controlled artifact — add a migration note and bump the version. (Schemas in schema/ are harness-agnostic and don't validate run_mode, so no schema break.)
  • README rewrite — these sections all assume the multi-mode world:
    • Quickstart (Mode A / Mode B walkthroughs reference switch-condition and "start a fresh interactive session").
    • The run loop.
    • Run modes (collapse the three-mode table → one Cli dispatch flow; reframe headless as tacit).
    • Cost and billing (the interactive-vs-claude -p billing split is moot).
    • Per-harness mode paragraphs (Claude Code "fully wired" / Codex / OpenCode).
  • docs/harness-parity.md: remove the "two parity axes / dispatch-mechanism" framing (the mechanism axis is gone). (The full minimal-interface rewrite is #D.)

Files

src/cli/args.rs (--run-mode), src/core/run_mode.rs, the conditions.json writer + src/core/context.rs, README.md (large surface), docs/harness-parity.md, and affected tests.

Acceptance criteria

  • No --run-mode surface (or a clearly deprecated no-op).
  • README tells one coherent single-mode story; no dangling references to switch-condition / interactive sessions.
  • conditions.json change documented + version bumped.
  • cargo test, cargo fmt --check, cargo clippy --all-targets -- -D warnings green.

Dependencies

Depends on #B.


Filed from the #113 feasibility/breakdown plan.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions