Standardize architect capabilities and strict validation

[mohidmakhdoomi]

Problem

Architect-shell support is currently inferred indirectly from builder harnesses and command-name auto-detection, producing inconsistent behavior:

• shell.architect: "opencode" fails immediately with the useful error OpenCode is only supported as a builder shell, not as an architect shell.
• shell.architect: "gemini" does not fail because GEMINI_HARNESS is still a valid built-in builder provider whose architect injection method does not throw, even though Gemini is now builder-only.
• shell.architect: "agy" does not fail because detectHarnessFromCommand() does not recognize agy; resolveHarness() silently falls back to CLAUDE_HARNESS, so Codev can launch an unsupported command with Claude-only arguments.
• More generally, any explicit but unrecognized architect command can silently inherit Claude capabilities, including role injection and resume behavior. This is the broader form of Harden harness resolution: unrecognized override command defaults to claude harness (residual --resume crash-loop) #1062.

Doctor warnings are insufficient: unsupported architect configurations must fail before Tower starts workspace processes. Builder support and architect support are different capabilities and should be represented explicitly.

Goal

Standardize architect selection around one authoritative capability model:

1. Supported architects launch with the correct harness.
2. Recognized builder-only harnesses fail fast when selected as architects.
3. Explicit, unrecognized architect commands fail fast rather than defaulting to Claude.

Scope

1. Explicit harness capabilities

• Introduce a single source of truth for which built-in harnesses support architect and/or builder use (capability metadata, role-specific registries, or an equivalent typed design).
• Initially, architect support is limited to the currently approved architect harnesses (claude and codex).
• A known harness without architect capability must throw a clear, provider-specific error similar to the existing OpenCode error. This includes gemini, opencode, and agy until/unless Support agy (Antigravity CLI) as an architect #1063 explicitly graduates agy to supported-architect status.
• Keep those providers usable in their supported non-architect roles; rejecting architect use must not regress builder or consultation behavior.
• Make doctor consume the same capability source rather than maintaining a separate allow/deny chain.

2. Strict architect resolution

• Preserve the normal no-config default (claude).
• If the user explicitly configures shell.architect and its command cannot be recognized, throw an actionable error instead of falling back to CLAUDE_HARNESS.
• Continue to support valid custom harnesses declared under harness and selected explicitly via shell.architectHarness; a configured custom harness is recognized, not an unknown command.
• Reject an explicit unknown shell.architectHarness with the existing available-harness guidance.
• Apply validation consistently to every architect launch/relaunch path:
  • afx workspace start
  • no-Tower afx architect
  • sibling architect creation
  • reconnect / shellper restart
• Validate before creating a restart loop or partially starting workspace processes.

3. Actionable errors

Errors should identify:

• the configured command/harness;
• whether it is unknown or builder-only;
• the supported architect choices;
• how to fix .codev/config.json / ~/.codev/config.json;
• for custom CLIs, how to declare and select a custom harness.

The OpenCode error is the UX baseline. gemini and agy must no longer appear to start successfully when they are not supported architects.

Acceptance criteria

• With no explicit architect config, Codev still defaults to Claude.
• shell.architect: "claude" and shell.architect: "codex" launch successfully with their correct role injection.
• shell.architect: "opencode" fails before workspace startup with a builder-only error.
• shell.architect: "gemini" fails before workspace startup with a builder-only error.
• shell.architect: "agy" fails before workspace startup as unsupported unless Support agy (Antigravity CLI) as an architect #1063 has added full architect capability by implementation time.
• An explicit unrecognized command (for example shell.architect: "my-ai") fails and never receives Claude args or Claude resume behavior.
• A valid explicitly configured custom architect harness continues to work.
• The same decisions and messages are enforced across workspace start, no-Tower launch, sibling launch, and reconnect/restart.
• Builder launches for supported builder harnesses remain unchanged.
• doctor reports architect support from the same source of truth as runtime validation.
• Unit/integration coverage includes all supported, builder-only, unknown-command, and custom-harness cases.

Related work

• Ship Codex skills in the skeleton and scaffold lifecycle #1196 — Codex skills in the shipped skeleton and scaffold lifecycle, split from this issue.
• Support codex as an architect #929 / PR Support codex as an architect (PIR #929) #1059 — codex architect support; leave its current scope unchanged.
• Harden harness resolution: unrecognized override command defaults to claude harness (residual --resume crash-loop) #1062 — narrower unknown-command → Claude fallback issue; this issue subsumes the broader design and acceptance criteria.
• Support agy (Antigravity CLI) as an architect #1063 — possible future agy architect support. If completed, it should add architect capability through the same standardized mechanism rather than bypassing validation.
• Gemini CLI > Antigravity CLI - June 18, 2026 DEADLINE #778 — Gemini CLI retirement / agy consultation migration.

Recommended protocol

PIR: the capability design needs plan review, and the end-to-end error UX should be exercised before PR creation.