feat(config): extend .retortconfig schema with cli-routing, mcp-servers, and worktree settings

[JustAGhosT]

Summary

Extend .retortconfig with three new top-level blocks that support the multi-CLI dispatch (#487), MCP server observation (retort-plugins), and worktree conventions. Update retort-config.mjs validation, the init wizard (Phase B GUI + TTY), and the schema docs.

---

New schema blocks

cli: — AI CLI routing (prerequisite for #487)

cli:
  preferred: claude          # claude | cursor | codex | aider | opencode | windsurf
  fallback: opencode
  auto-detect: true          # scan PATH on startup (default: true)
  team-overrides:
    devops: codex
    frontend: cursor
    data: aider

mcp: — MCP server visibility hints

Retort doesn't manage MCP servers, but the plugin's MCPPanel needs to know which servers are relevant to this project. This block provides hints for the state-watcher.

mcp:
  watch: true                      # enable MCP observation in plugin (default: true)
  servers:                         # override/augment auto-detected servers
    - id: context7
      label: "Context7 Docs"
      expected: true               # alert if not connected
    - id: filesystem
      expected: true
  probe-interval: 30               # health check interval in seconds (default: 30)

worktrees: — worktree conventions

worktrees:
  branch-prefix: feat              # default prefix for agent worktree branches
  auto-cleanup: true               # remove worktree on successful merge
  base-branch: dev                 # default base branch for new worktrees
  max-concurrent: 5                # warn if more than N worktrees active

---

Validation changes (retort-config.mjs)

Add validation for each new block:

• cli.preferred must be one of the known CLI IDs
• cli.team-overrides keys must match team IDs in teams.yaml (warn, not error, for unknown teams)
• mcp.probe-interval must be a positive integer
• worktrees.branch-prefix must be a valid git branch prefix (no spaces, no ..)

---

Init wizard changes

TTY wizard (retort-config-wizard.mjs) — Phase B extension

Add optional prompts after the existing agent management phase:

? Configure CLI routing? (Y/n)
  Preferred CLI: › claude ▾
  Team overrides (optional, press Enter to skip each):
    devops: ›
    frontend: › cursor
    ...

? Configure MCP observation? (Y/n)
  [shows detected MCP servers from .claude/settings.json]
  Mark as expected (health alerts if disconnected):
  ◉ context7   ◉ filesystem   ○ playwright   ○ memory

Plugin GUI (retort-plugins OnboardingPanel) — follow-on

The same prompts should appear in the OnboardingPanel's setup wizard. Covered by retort-plugins#1 scope.

---

Files

File	Change
retort-config.mjs	Add cli, mcp, worktrees to schema + validation
retort-config-wizard.mjs	Extend Phase B with CLI routing + MCP prompts
init.mjs	Pass new config blocks through Phase 8
.retortconfig (repo self-hosted)	Update with cli: preferred: claude
docs/reference/retortconfig.md	Document all blocks (create if missing)

---

Acceptance criteria

• retort init wizard offers CLI routing and MCP prompts (skippable)
• Unknown cli.preferred value produces a validation error with suggestions
• Team override references non-existent team → warning (not error), continues
• mcp.servers[].expected: true entries appear in plugin MCPPanel with alert badge if disconnected
• worktrees.branch-prefix is respected by retort worktree create
• .retortconfig in this repo updated to reflect the new schema
• Existing .retortconfig files without the new blocks continue to work (all fields optional)
• Unit tests for new validation paths

---

Related

• feat(cli): add retort run — multi-CLI team dispatch with .retortconfig routing #487 — retort run consumes cli: block
• retort-plugins#1 — router + MCPPanel consume mcp: block
• PR feat(config): add .retortconfig — agent remapping and opt-in feature flags v1 #479 — .retortconfig v1 schema (base)
• worktree.mjs — worktrees.branch-prefix replaces hardcoded feat/

🤖 Generated with Claude Code

[blocksorg]

Mention Blocks like a regular teammate with your question or request:

@blocks can you add technical details to this issue?
@blocks make the following changes ...
@blocks create an issue from what was mentioned in the following comment ...
@blocks explain the following code ...
@blocks are there any security or performance concerns?

Run @blocks /help for more information.

Workspace settings | Disable this message