# Architecture Decision Records

## ADR-001: Documentation-First Architect Mode

**Status:** Accepted

**Date:** 2026-07-28

### Context

The existing `plan_build` workflow makes Claude Code the implementation orchestrator but does not enforce durable specifications, atomic Codex task prompts, client handover documentation, or a strict separation between documentation and code execution.

### Decision

Add an opt-in built-in `--architect` mode. Claude Code owns discovery, architecture, documentation, dispatch, and verification. Codex is the sole code and test-code executor. CodeRabbit reviews every task and the final aggregate diff. Tasks execute sequentially, and all approved work is committed once after final verification and explicit user approval.

### Alternatives Considered

- Replace the default workflow: rejected because direct implementation remains useful.
- Keep Claude as an implementation fallback: rejected because it weakens the requested role boundary.
- Execute tasks in parallel: rejected because sequential execution provides clearer scope, review, and failure attribution.

### Consequences

- Architect mode requires an interactive terminal and additional workflow state documents.
- Long-running work can resume from repository records rather than chat history.
- Delivery takes more approval steps but produces a complete auditable handover package.

### Affected Components

- `func`
- `test_plan_build.zsh`
- `architect-workflow.md`
- Installer scripts addressed by `TASK-003`

## ADR-002: Remove the Standalone v2 Integration

**Status:** Accepted

**Date:** 2026-07-28

### Context

The built-in `--v2` path downloads a standalone script from an unavailable endpoint. Retaining the path exposes a broken user interface and creates a second workflow source that can drift.

### Decision

Remove the v2 downloader, parser branch, passthrough behavior, usage text, and documentation. `--v2` now follows the normal unknown-argument path.

### Alternatives Considered

- Repair or recreate the standalone gist: rejected because v2 is no longer required.
- Preserve the broken option as undocumented behavior: rejected because it would remain a misleading public contract.

### Consequences

- `--grill` and `--distribute` are no longer reachable through `plan_build`.
- The built-in command has one maintained implementation path.

### Affected Components

- `func`
- `test_plan_build.zsh`
- `README.md`