# Plan Build Architect Mode Specification

## 1. Executive Summary & Goals

### Problem Statement

The existing `plan_build` command asks Claude Code to plan and implement a task through an eight-step multi-agent workflow. It does not provide a documentation-first delivery mode in which Claude acts strictly as architect and documentation manager while OpenAI Codex performs all implementation work.

This creates three handover risks:

1. Requirements and architecture decisions can remain implicit in agent conversations.
2. Implementation tasks may not have durable, atomic scopes and acceptance criteria.
3. The final repository may lack the user, operational, API, deployment, security, and acceptance documentation required for a client handover.

### Solution

Add an optional built-in `plan_build --architect` mode. In this mode, Claude Code owns discovery, specifications, task decomposition, review orchestration, progress records, and final handover documentation. Codex is the sole implementation executor. CodeRabbit reviews every completed task and the final aggregate diff.

Architect mode follows three gated phases:

1. **Discovery and Architecture:** Claude interviews the user one question at a time and recommends a default answer for each decision.
2. **Documentation Synthesis:** After an explicit phase-completion phrase, Claude writes the approved requirements into `SPEC.md` without asking additional questions.
3. **Codex Execution Plan:** After specification approval, Claude writes atomic sequential task briefs and self-contained Codex prompts into `TASKS.md`.

Codex tasks execute only after `TASKS.md` approval. Exactly one task may be active at a time. All implementation and documentation changes remain uncommitted until the complete workflow, reviews, tests, and client handover package pass final verification. The user must approve the single final commit. The workflow never pushes automatically.

### Goals

- Preserve the existing default `plan_build` behavior.
- Add `--architect` as an explicit opt-in mode.
- Remove the obsolete and broken `--v2` integration from the built-in command.
- Keep Claude from writing implementation or test code in architect mode.
- Make Codex tasks atomic, sequential, auditable, and constrained by file scope.
- Require explicit approval at every phase and execution boundary.
- Require CodeRabbit review after every task and over the final combined diff.
- Produce complete internal engineering records and client-facing handover documentation.
- Resume interrupted architect workflows safely.
- Preserve existing project documentation and user work.
- Produce one user-approved commit only after all tasks are complete.

### Non-Goals

- Replacing the existing standard, brainstorm, writing-plan, prompt-enhancement, or yolo workflows.
- Allowing unattended architect execution.
- Allowing Claude to implement application or test code.
- Automatically pushing the final commit.
- Inventing project behavior, infrastructure, controls, or APIs that do not exist.

## 2. User Stories

1. As a project owner, I want Claude to interview me one question at a time, so that architectural decisions remain understandable and deliberate.
2. As a project owner, I want each question to include a recommended default, so that discovery can proceed efficiently.
3. As a project owner, I want explicit phase gates, so that no specification or implementation begins before I approve it.
4. As a project owner, I want a cohesive `SPEC.md`, so that requirements and contracts have one approved baseline.
5. As a project owner, I want atomic Codex prompts in `TASKS.md`, so that implementation work has clear boundaries.
6. As a project owner, I want only one Codex task active at a time, so that failures and diffs remain attributable.
7. As a project owner, I want Claude to inspect but not implement code, so that architecture and execution responsibilities remain separated.
8. As a project owner, I want CodeRabbit to review every task, so that defects are found before dependent work begins.
9. As a project owner, I want one final holistic review, so that cross-task regressions are detected.
10. As a project owner, I want all work committed once at the end, so that the complete delivery appears as one coherent change.
11. As a project owner, I want interrupted sessions to resume from durable records, so that long projects do not lose state.
12. As a client, I want user and operational documentation, so that I can adopt and run the delivered system.
13. As a client, I want deployment and rollback instructions, so that releases can be managed safely.
14. As a client, I want security and ownership documentation, so that operational responsibilities are explicit.
15. As a client, I want a formal acceptance checklist, so that handover completion is objectively verifiable.
16. As an engineer, I want approved specification changes recorded, so that implementation does not silently drift from requirements.
17. As an engineer, I want file-scope enforcement, so that Codex cannot introduce unrelated changes.
18. As an engineer, I want focused tests per task and full verification at completion, so that failures are localized without sacrificing system confidence.
19. As an operator, I want documentation claims tied to source files and verified commands, so that instructions can be trusted.
20. As a security reviewer, I want secrets excluded from prompts and documents, so that the workflow does not leak credentials.

## 3. System Architecture & Tech Stack

### Existing Context

The feature extends a Zsh function-based command distributed through the Zsh Setup OpenGist. The current command launches Claude Code with an installed workflow document. Existing behavior is covered by a Zsh test script that stubs external CLIs and asserts command-level output and argument contracts.

### Runtime Components

| Component | Responsibility in architect mode |
| --- | --- |
| `plan_build` Zsh function | Parse flags, reject incompatible combinations, run preflight, collect the initial payload, and launch Claude with the architect workflow. |
| Claude Code | Lead architect, documentation manager, task dispatcher, scope verifier, review triager, and phase-gate controller. |
| OpenAI Codex CLI | Sole application and test-code executor, invoked non-interactively for one approved task at a time. |
| CodeRabbit CLI | Automated reviewer after every task and over the final aggregate diff. |
| Git | Baseline detection, diff isolation, traceability, and one final user-approved commit. |
| Markdown files | Durable workflow state, approved requirements, decisions, execution records, and client handover package. |

### Canonical Workflow Source

Architect mode must have one canonical workflow document in the Zsh Setup gist. The configuration installer and all supported platform installers distribute that same document to:

`~/.claude/skills/plan-build-architect/SKILL.md`

The active local installation and published OpenGist source must remain identical after rollout.

### Execution Topology

```mermaid
flowchart TD
    U[Project Owner] -->|Initial payload| PB[plan_build --architect]
    PB -->|Preflight and architect prompt| C[Claude Code]
    C -->|One question at a time| U
    U -->|Explicit phase approvals| C
    C -->|Writes and maintains| D[Engineering and handover Markdown]
    C -->|One approved task prompt| X[Codex CLI]
    X -->|Scoped code and tests| W[Shared Git worktree]
    C -->|Inspect diff and verify| W
    C -->|Review request| R[CodeRabbit CLI]
    R -->|Findings| C
    C -->|Valid fixes delegated| X
    C -->|Task and final approval requests| U
    U -->|Final commit approval| C
    C -->|One commit, no push| G[Git history]
```

### Responsibility Boundary

Claude may inspect every project file but may create or modify only documentation and orchestration records during architect execution:

- `SPEC.md`
- `TASKS.md`
- `ADR.md`
- `CHANGELOG.md`
- `README.md`
- Files under `docs/` that form the client handover package

Codex owns all application code, configuration code, migrations, generated source, and test-code modifications. If a required change falls outside an approved task scope, Codex stops and reports the required expansion rather than modifying the file.

### Interactive Constraint

Architect mode requires a usable interactive terminal. It must fail before modifying project files when a TTY is unavailable. This protects all mandatory approval gates.

## 4. Data Models & Schemas

Architect mode introduces no application database schema. Its durable state is represented by structured Markdown documents.

### Project Metadata

Discovery must collect:

- Project name
- Client or owning organization
- Product purpose
- Target users
- Repository scope
- Supported environments
- Deployment owner
- Operational owner
- Support contact role
- Compliance constraints
- Intended handover date

Sensitive identities may use user-approved placeholders.

### Task Record

Every `TASKS.md` task must contain:

| Field | Requirement |
| --- | --- |
| ID | Stable sequential identifier such as `TASK-001`. |
| Title | Concise implementation outcome. |
| Status | One of `Pending`, `In Progress`, `Blocked`, `Review`, or `Complete`. |
| Dependencies | IDs that must be complete first, or `None`. |
| Objective | Exact feature, behavior, or function Codex must implement. |
| Allowed File Scope | Exhaustive files or bounded path patterns Codex may create or modify. |
| Context / Interfaces | Approved schemas, contracts, imports, conventions, and relevant existing behavior. |
| Prompt for Codex | Self-contained non-interactive execution prompt. |
| Acceptance Criteria | Observable behavior and required test coverage. |
| Verification Commands | Focused lint, type-check, unit, integration, or build commands. |
| CodeRabbit Outcome | Findings, triage result, and rerun status. |
| Completion Evidence | Commands run, results, and relevant diff evidence. |

Only one task may have `In Progress` status.

### Task State Transitions

```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress: approved and dependencies complete
    InProgress --> Review: Codex reports completion
    InProgress --> Blocked: execution or scope blocker
    Review --> InProgress: valid findings require fixes
    Review --> Complete: acceptance and review pass
    Blocked --> Pending: user approves revised scope or architecture
    Complete --> [*]
```

### Architecture Decision Record

`ADR.md` is append-only. Every decision uses a stable ID such as `ADR-001` and records:

- Status
- Date
- Context
- Decision
- Alternatives considered
- Consequences
- Affected files or components
- Superseding ADR, when applicable

Superseded decisions remain visible.

### Changelog

`CHANGELOG.md` follows Keep a Changelog conventions. Work remains under `Unreleased` until the final delivery and is grouped under:

- Added
- Changed
- Fixed
- Security
- Deprecated
- Removed

Entries reference task IDs. Detailed execution evidence remains in `TASKS.md`.

### Mandatory Handover Package

The following files are mandatory without exception:

| File | Audience and purpose |
| --- | --- |
| `README.md` | Product overview, prerequisites, quick start, and configuration. |
| `SPEC.md` | Approved requirements, architecture, schemas, contracts, constraints, and acceptance baseline. |
| `TASKS.md` | Internal task execution and evidence record. |
| `ADR.md` | Internal architecture decision history. |
| `CHANGELOG.md` | Delivery and release history. |
| `docs/USER_MANUAL.md` | End-user workflows and expected outcomes. |
| `docs/RUNBOOK.md` | Operations, monitoring, backup, recovery, and troubleshooting. |
| `docs/API.md` | Authentication, endpoints or commands, examples, and errors. |
| `docs/DEPLOYMENT.md` | Environments, infrastructure, release, rollback, and validation. |
| `docs/SECURITY.md` | Access control, secret handling, data protection, rotation, and known risks. |
| `docs/HANDOVER.md` | Deliverables, ownership, support boundaries, limitations, and formal acceptance. |

Non-applicable material must be marked `Not Applicable` with a factual rationale. Files may not be omitted.

## 5. CLI & Component Contracts

### Supported Invocation

`plan_build --architect`

Optional architect flags:

- `--new`: Start a new architect workflow after archiving existing workflow documents.
- `--yolo`: Forward Claude's permissive execution mode but never bypass architect approval gates.

### Incompatible Flags

Architect mode must reject combinations with:

- `--brainstorm`
- `--writing-plan`
- `--prompt`

The `--v2` option, its downloader function, and its usage documentation must be removed entirely. After removal, passing `--v2` follows the normal unknown-argument error path. The built-in workflow does not expose the former v2-only `--grill` or `--distribute` concepts.

### Preflight Contract

Before discovery or file modification, architect mode verifies:

- Interactive TTY
- Git repository context
- `claude`
- `codex`
- `coderabbit`
- `git`
- Installed architect workflow document

A missing requirement causes a non-zero exit with exact remediation guidance. Project-specific tools are checked when their approved tasks require them.

### Phase-Gate Contract

#### Phase 1 to Phase 2

Claude may leave discovery only after the user states either:

- `I am ready to generate the spec`
- `Phase 1 complete`

Claude asks one question at a time and includes one recommended default with every question.

#### Phase 2 to Phase 3

Claude writes `SPEC.md` without asking more questions. It waits for explicit specification approval before creating `TASKS.md`.

#### Phase 3 to Execution

Claude writes `TASKS.md` and waits for explicit task-plan approval before invoking Codex.

#### Between Tasks

Claude dispatches one task, verifies scope and acceptance criteria, completes CodeRabbit triage, reports evidence, and waits for user approval before starting the next task.

#### Final Commit

Claude presents the final verification results, aggregate diff summary, and proposed commit message. It stages and commits only after explicit user approval. It never pushes.

### Codex Invocation Contract

Claude invokes Codex non-interactively in the current project worktree with workspace-write access. The exact prompt stored in the approved task record is passed to Codex. Every prompt includes:

- Objective
- Allowed File Scope
- Context / Interfaces
- Acceptance Criteria
- Unit or integration test requirements
- Verification commands
- Prohibition on commits
- Instruction to stop before touching out-of-scope files

Codex execution output is captured for verification. Claude independently inspects the diff and reruns required commands.

### CodeRabbit Contract

CodeRabbit runs after each Codex task and once over the final combined diff.

- Claude investigates every concrete finding.
- Valid findings are delegated to Codex within the same task.
- Critical, high, and medium findings block progress until resolved.
- Low-severity findings may be deferred only with user approval.
- Approved deferrals are recorded in `CHANGELOG.md` and `docs/HANDOVER.md`.
- Tests and CodeRabbit rerun after substantive fixes.

### Retry Contract

After the initial Codex attempt, Claude may dispatch at most two focused correction attempts. If acceptance criteria still fail:

1. Stop execution.
2. Mark the task `Blocked`.
3. Preserve the partial diff.
4. Record diagnostics and attempted corrections.
5. Ask the user whether to revise architecture, scope, or acceptance criteria.
6. Do not start dependent tasks.

### Resume Contract

When workflow documents already exist, Claude:

1. Reads `SPEC.md`, `TASKS.md`, `ADR.md`, and `CHANGELOG.md`.
2. Compares their recorded state with Git and the current worktree.
3. Identifies the first incomplete task.
4. Presents the detected state and asks whether to resume.

`--new` must archive existing workflow documents before creating replacements. It must never overwrite them silently.

## 6. Documentation Contracts

### Existing Documentation

Claude updates existing documents in place and preserves valid project-specific content. It creates only missing files. Wholesale replacement is prohibited unless reconciliation proves that no valid content would be lost.

### Client-Facing Content

Client documents describe the delivered system and do not expose Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless contractual or compliance requirements require AI disclosure.

### Traceability

Implementation-specific claims reference relevant source files, configurations, schemas, endpoints, or verified commands. Handover documents include:

- Software version or final commit SHA
- Generation date
- Document owner
- Last verification date

### Diagrams

Use maintainable Mermaid diagrams for system context, component interactions, deployment topology, and critical operational sequences when applicable. If a diagram is not applicable, state why.

### Handover Acceptance

`docs/HANDOVER.md` includes:

- Deliverables
- Environment and access prerequisites
- Verified capabilities
- Known limitations
- Approved deferred risks
- Support boundaries
- Warranty assumptions
- Ownership transfer
- Dated client acceptance checklist
- Sign-off placeholders

## 7. Edge Cases & Constraints

### Existing Dirty Worktree

Claude records the initial Git status and preserves pre-existing work. It may not revert, overwrite, stage, or include unrelated changes. If approved and pre-existing changes cannot be distinguished safely, execution stops for user direction.

### Scope Expansion

Codex stops when required work exceeds the task's allowed scope. Claude assesses the impact, updates `SPEC.md`, `TASKS.md`, and `ADR.md` as appropriate, and requests approval before redispatch.

### Requirement Changes

Approved `SPEC.md` is the baseline. Later requirements are explicit amendments. Execution pauses while Claude assesses affected tasks and documentation. Architectural amendments require an ADR. No changed task is dispatched without approval.

### Missing Test Framework

The first applicable task establishes the smallest project-appropriate test and validation setup. If automated testing is technically impossible, Claude obtains approval for explicit manual acceptance steps and records the risk in `docs/HANDOVER.md`.

### Secrets and Sensitive Data

Prompts and documents never contain credential values, tokens, private keys, personal data, or production secrets. They may document secret names, environment variables, storage systems, ownership, and rotation procedures. Available secret scanning runs before final commit, and suspected credentials block completion.

### Non-Applicable Documentation

Mandatory documents remain present and mark irrelevant sections as `Not Applicable` with rationale. The workflow never fabricates content to fill a template.

### Single Commit

No task-level commits are created. All approved implementation, tests, engineering records, and client documents remain in the worktree until every task is complete and final verification passes. The final commit includes only approved files.

### Interrupted Sessions

Durable task states and evidence, not chat history, determine resume position. Claude must validate recorded state against actual files and Git before continuing.

## 8. Testing & Acceptance Strategy

### Primary Test Seam

The highest existing seam is command-level testing of the sourced Zsh function with external CLI stubs. Extend this seam rather than testing private parser details independently.

### Required Workflow Tests

- `--architect` produces the expected Claude invocation and architect workflow instruction.
- `--architect --new` is accepted.
- `--architect --yolo` forwards yolo behavior while preserving the architect instruction.
- `--architect` rejects every incompatible flag combination.
- Duplicate architect flags fail with usage guidance.
- Missing TTY fails before workflow modification.
- Missing required CLI or skill fails with remediation guidance.
- Existing non-architect modes retain their current observable behavior.
- `--v2` is rejected as an unknown argument and no v2 downloader remains.
- Existing non-v2 modes retain their current observable behavior after v2 removal.

### Per-Task Verification

Every Codex task includes focused unit or integration tests and relevant lint, type-check, build, and test commands. Claude reruns them independently before CodeRabbit review is considered complete.

### Final Verification

Before requesting commit approval, Claude verifies:

- Every task is `Complete`.
- No task has unresolved blocking review findings.
- The complete project lint, type-check, build, and test suite passes.
- The aggregate diff contains only approved changes.
- Required documentation files and sections exist.
- Markdown structure and internal links are valid.
- Referenced source paths and commands exist and are accurate.
- Endpoint and command examples match implementation.
- Mermaid syntax is validated where tooling is available.
- No unresolved `TODO`, placeholder, or template text remains.
- Approved known limitations are recorded in `docs/HANDOVER.md`.
- Available secret scanning reports no suspected credentials.
- Handover documents match the final implementation.

## 9. Implementation Decisions

- Architect mode is opt-in and does not replace existing `plan_build` modes.
- Architect mode is implemented only for the built-in workflow.
- The obsolete `_plan_build_v2` downloader, `--v2` parser branch, passthrough logic, usage text, README examples, and standalone-install references are removed.
- Claude is the architect and documentation manager, not an implementation agent.
- Codex is the sole implementation and test-code executor.
- CodeRabbit is mandatory for task and final reviews.
- Execution is sequential with one active task.
- User approval is mandatory at phase, task, deferral, and commit boundaries.
- All changes are committed once after complete verification.
- The final commit is never pushed automatically.
- Existing documentation is reconciled rather than overwritten.
- Complete client handover documentation is mandatory without exception.

## 10. Out of Scope

- Repairing, replacing, or migrating the unavailable standalone v2 script or remote endpoint; only the built-in integration and references are removed.
- Parallel task execution.
- Frontend/backend distribution to different executors.
- Autonomous approval decisions.
- Multiple task commits.
- Automatic pushes, releases, or deployments.
- Replacement of project issue trackers or external documentation systems.
- Generating implementation code during specification work.

## 11. Definition of Done

Architect mode is complete when:

1. The built-in command exposes the approved CLI contract.
2. No built-in v2 downloader, flag parser, usage text, or documentation reference remains.
3. The canonical architect skill is distributed by every supported installer.
4. The current machine can refresh the active function and skill from the published source.
5. Command-level tests cover architect behavior, v2 rejection, and preservation of existing non-v2 modes.
6. The workflow enforces role boundaries, phase gates, task states, retries, reviews, and the single-commit policy.
7. The workflow mandates the complete internal and client documentation package.
8. Syntax and workflow tests pass.
9. Published OpenGist content matches the verified local source.