# Plan Build Architect Mode Execution Plan ## Execution Policy This plan implements the approved `SPEC.md`. Claude Code is the architect, documentation manager, dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit reviews every task and the final aggregate diff. The following rules apply to every task: 1. Execute tasks sequentially in ID order. 2. Only one task may be `In Progress` at a time. 3. Do not start a task until its dependencies are `Complete` and the user approves dispatch. 4. Codex may modify only the task's Allowed File Scope. 5. Codex must stop and report when required work exceeds that scope. 6. Codex must not commit, stage, push, reset, restore, or discard changes. 7. Claude independently checks the diff and reruns verification commands. 8. CodeRabbit reviews each task. Valid critical, high, and medium findings must be fixed before completion. 9. Codex receives at most two focused correction attempts after its initial execution. 10. All changes remain uncommitted until every task, final review, full verification, and handover document passes. 11. Claude updates `SPEC.md`, `ADR.md`, `CHANGELOG.md`, `README.md`, and the mandatory `docs/` handover package. Codex does not edit those documents unless a later approved scope amendment explicitly says otherwise. ## Claude Documentation Workstream This workstream runs alongside Codex execution and is not delegated: - Preserve and reconcile existing documentation rather than replacing it blindly. - Maintain `SPEC.md` as the approved baseline and record approved amendments. - Create and maintain append-only `ADR.md` decisions. - Maintain Keep a Changelog-compatible `CHANGELOG.md` entries referencing task IDs. - Remove obsolete v2 usage and standalone-install references from `README.md` after `TASK-001` passes. - Document `plan_build --architect`, `--new`, compatibility rules, prerequisites, and examples after `TASK-002` passes. - Document installer distribution and local refresh behavior after `TASK-003` passes. - Create or update `docs/USER_MANUAL.md`, `docs/RUNBOOK.md`, `docs/API.md`, `docs/DEPLOYMENT.md`, `docs/SECURITY.md`, and `docs/HANDOVER.md` before final review. - Mark non-applicable sections explicitly with a factual rationale rather than omitting files or inventing behavior. - Add final commit SHA placeholders only until the final commit exists; replace or explain the self-reference limitation during finalization. --- ## TASK-001: Remove the obsolete v2 integration **Status:** Complete **Dependencies:** None ### Objective Remove the broken standalone v2 downloader and all `--v2` parsing and forwarding behavior from the built-in `plan_build` function. Preserve every existing non-v2 mode. Make `--v2` use the normal unknown-argument failure path. ### Allowed File Scope - `func` - `test_plan_build.zsh` No other file may be created, modified, renamed, or deleted by Codex. ### Context / Interfaces - `func` currently defines `_plan_build_v2()`, which downloads a now-unavailable standalone script. - `plan_build()` currently performs a preliminary argument pass to strip `--v2` and forward all remaining arguments. - The normal parser already rejects unknown arguments with a non-zero status and usage output. - Existing supported behavior includes `--yolo`, `--prompt`, `--brainstorm`, and `--writing-plan`. - `test_plan_build.zsh` is the highest command-level test seam. It sources `func`, stubs external commands, invokes `plan_build`, and asserts status and output. - Do not redesign the existing parser beyond the smallest change required to remove v2. ### Acceptance Criteria - `_plan_build_v2()` no longer exists. - The v2 URL, temporary-file logic, Bash forwarding, and v2 status handling no longer exist. - `plan_build()` no longer performs a v2 pre-parse or maintains v2 passthrough arguments. - Usage output contains no `--v2`, `--grill`, or `--distribute` text. - `plan_build --v2` returns non-zero through the standard unknown-argument path and identifies `--v2` as unknown. - Existing standard, yolo, prompt, brainstorm, and writing-plan behavior remains unchanged. - Tests cover v2 rejection and continue covering existing modes. - Zsh syntax validation and the complete existing plan-build test suite pass. ### Verification Commands ```bash zsh -n func zsh -n test_plan_build.zsh zsh test_plan_build.zsh git diff --check -- func test_plan_build.zsh git diff -- func test_plan_build.zsh ``` ### Prompt for Codex ```text Objective: Remove the obsolete standalone v2 integration from the built-in plan_build Zsh function. Delete the _plan_build_v2 downloader and remove all --v2 pre-parsing, passthrough, forwarding, and usage text. After the change, --v2 must be handled by the existing normal unknown-argument branch. Preserve all non-v2 behavior. Allowed File Scope: - func - test_plan_build.zsh Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. Context / Interfaces: - func defines _plan_build_v2() immediately before plan_build(). It downloads a missing remote plan_build.sh and executes it with Bash. - plan_build() currently strips --v2 in a preliminary argument loop, then either forwards to _plan_build_v2 or enters the normal parser. - The normal parser already prints "Error: Unknown argument: ", prints usage, and returns 1. - Supported non-v2 flags are --yolo, --prompt, --brainstorm, and --writing-plan. - test_plan_build.zsh is a command-level Zsh test that sources func, stubs external CLI checks and Claude, and asserts output/status. - Make the smallest correct parser change. Do not refactor unrelated shell functions or reformat unrelated content. Acceptance Criteria: 1. _plan_build_v2 and all of its URL/download/temporary-file/forwarding code are removed. 2. plan_build has no use_v2 or passthrough state and no preliminary v2 argument pass. 3. Usage text has no v2, grill, or distribute reference. 4. plan_build --v2 returns status 1 and includes "Unknown argument: --v2". 5. Standard, --yolo, --prompt, --brainstorm, and --writing-plan behavior remains unchanged. 6. Add a command-level regression assertion for --v2 rejection. 7. All existing tests pass. Required Verification: - zsh -n func - zsh -n test_plan_build.zsh - zsh test_plan_build.zsh - git diff --check -- func test_plan_build.zsh Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. ``` ### CodeRabbit Outcome Passed with zero findings. ### Completion Evidence - Codex removed the v2 downloader and parser forwarding only within the approved files. - `plan_build --v2` now returns the normal unknown-argument error. - `zsh -n func` passed. - `zsh -n test_plan_build.zsh` passed. - `zsh test_plan_build.zsh` passed. - `git diff --check -- func test_plan_build.zsh` passed. --- ## TASK-002: Add the built-in architect command contract **Status:** Complete **Dependencies:** TASK-001 ### Objective Add `--architect` to the built-in `plan_build` function. Support `--new` and `--yolo`, enforce incompatible and duplicate flag rules, run fail-fast architect preflight, collect the initial payload through the existing input contract, and launch Claude with the canonical installed architect skill. Preserve existing non-architect modes. ### Allowed File Scope - `func` - `test_plan_build.zsh` No other file may be created, modified, renamed, or deleted by Codex. ### Context / Interfaces - Claude will create the canonical repository workflow document `architect-workflow.md` before this task is dispatched. - Installers will later distribute it to `~/.claude/skills/plan-build-architect/SKILL.md` in `TASK-003`. - Architect mode is interactive and requires `claude`, `codex`, `coderabbit`, `git`, a Git worktree, a usable TTY, and a readable non-empty installed skill. - Preflight must run before payload collection or any project-file modification. - `--new` is valid only with `--architect`. - `--architect` may combine only with `--new` and `--yolo`. - Architect mode must reject `--prompt`, `--brainstorm`, and `--writing-plan` combinations. - `--yolo` is forwarded to Claude but the architect workflow itself retains mandatory human gates. - The initial payload continues using the existing `EOF`-terminated stdin behavior. - Existing command-level tests stub helpers and Claude. Architect tests must not launch real external CLIs or require a real TTY. ### Acceptance Criteria - Usage documents built-in architect syntax and no v2 syntax. - Duplicate `--architect` and duplicate `--new` fail with usage guidance. - `--new` without `--architect` fails. - Architect combinations with prompt, brainstorm, or writing-plan fail before external tools launch. - A dedicated architect preflight checks all required tools, Git context, TTY, and installed skill with actionable errors. - Architect preflight occurs before payload reading. - Empty payload remains an error. - The Claude invocation explicitly directs Claude to read `~/.claude/skills/plan-build-architect/SKILL.md`, obey the architect role boundary, and treat the payload as the initial high-level requirement. - `--new` is represented unambiguously in the Claude instruction. - `--yolo` is forwarded to Claude. - Existing non-architect modes retain current observable behavior. - Command-level tests cover success, compatibility failures, duplicates, new/resume instruction, yolo forwarding, and preflight failure without invoking real tools. ### Verification Commands ```bash zsh -n func zsh -n test_plan_build.zsh zsh test_plan_build.zsh git diff --check -- func test_plan_build.zsh git diff -- func test_plan_build.zsh ``` ### Prompt for Codex ```text Objective: Implement the built-in plan_build --architect command contract in Zsh. Architect mode launches Claude as a documentation-first architect/orchestrator using ~/.claude/skills/plan-build-architect/SKILL.md. It must support --new and --yolo, reject incompatible or duplicate flags, run a fail-fast preflight, preserve the existing EOF-terminated payload input, and leave every existing non-architect mode unchanged. Allowed File Scope: - func - test_plan_build.zsh Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. Context / Interfaces: - TASK-001 has already removed --v2. - Existing plan_build supports --yolo, --prompt, --brainstorm, and --writing-plan. - --architect may combine only with --new and --yolo. - --new without --architect is invalid. - --architect combined with --prompt, --brainstorm, or --writing-plan is invalid. - Duplicate --architect and duplicate --new must fail with usage output. - Architect preflight must verify, before payload reading: an interactive TTY; a Git worktree; claude, codex, coderabbit, and git availability; and a readable non-empty ~/.claude/skills/plan-build-architect/SKILL.md. - Error output must identify the missing requirement and provide practical remediation. - The current input contract reads lines until EOF appears on its own line and rejects an empty payload. - The Claude prompt must explicitly tell Claude to read ~/.claude/skills/plan-build-architect/SKILL.md, follow it strictly, remain within its documentation/orchestration boundary, and use the payload as the initial high-level requirement. - When --new is present, the prompt must explicitly request the skill's archive-and-start-new behavior. Otherwise it must permit safe resume detection. - --yolo forwards the existing Claude yolo argument but does not weaken workflow approval gates. - test_plan_build.zsh uses function stubs. Add or stub a dedicated architect preflight seam so tests never invoke actual CLIs or depend on the test runner's TTY. - Prefer the existing command-level test seam. Do not add another test framework. - Make minimal localized changes and do not refactor unrelated functions. Acceptance Criteria: 1. Usage includes plan_build --architect [--new] [--yolo]. 2. Duplicate architect/new flags and invalid combinations return status 1 with clear errors and usage. 3. Architect preflight executes before payload collection and checks every stated dependency. 4. Empty payload returns status 1. 5. A successful architect invocation directs Claude to the canonical installed skill and includes the initial payload. 6. --new changes the instruction to start a new archived workflow; default behavior permits resume detection. 7. --yolo is forwarded to Claude. 8. Existing standard, prompt, brainstorm, writing-plan, and yolo tests remain green. 9. Tests cover architect success and every parser/preflight edge without launching real external processes. Required Verification: - zsh -n func - zsh -n test_plan_build.zsh - zsh test_plan_build.zsh - git diff --check -- func test_plan_build.zsh Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. ``` ### CodeRabbit Outcome CodeRabbit reported one major finding: checking only the exit status of `git rev-parse --is-inside-work-tree` could accept a bare repository. Codex added an exact `true` check and regression fixtures for normal and bare repositories. The follow-up CodeRabbit review passed with zero findings. ### Completion Evidence - Codex added the built-in architect parser, preflight, launch prompt, and command-level tests only within the approved files. - Architect tests cover success, new workflow, safe resume, yolo forwarding, invalid combinations, duplicates, empty payload, preflight ordering, normal worktrees, and bare repository rejection. - `zsh -n func` passed. - `zsh -n test_plan_build.zsh` passed. - `zsh test_plan_build.zsh` passed. - `git diff --check -- func test_plan_build.zsh` passed. - Final CodeRabbit review passed with zero findings. --- ## TASK-003: Distribute and verify the canonical architect skill **Status:** Pending **Dependencies:** TASK-002 ### Objective Extend the configuration and platform installers to atomically install the canonical `architect-workflow.md` source as `~/.claude/skills/plan-build-architect/SKILL.md`. Add repository-level tests that verify every supported installer uses the same source and destination while preserving the existing plan-build skill installation. ### Allowed File Scope - `config.sh` - `zsh_macos.sh` - `zsh_ubuntu.sh` - `zsh_wsl.sh` - `test_plan_build_installers.zsh` (new) Codex must not modify `architect-workflow.md`; Claude owns its approved content. No other file may be created, modified, renamed, or deleted by Codex. ### Context / Interfaces - `config.sh` currently downloads `orchestrate-loop.md` to `~/.claude/skills/plan-build/SKILL.md` through a temporary file and atomic move. - Each platform installer has equivalent existing plan-build skill installation logic. - The new canonical repository source is `architect-workflow.md`. - The new installed destination is `~/.claude/skills/plan-build-architect/SKILL.md`. - Existing plan-build skill distribution must continue unchanged. - All four installers must use their existing gist raw base rather than introducing a new remote endpoint. - Failure to download or install the architect skill must be visible and must not leave a partial destination file. - The new test should validate repository contracts without network access, elevated privileges, home-directory changes, or execution of full platform installers. ### Acceptance Criteria - `config.sh` installs both the existing plan-build skill and the architect skill. - macOS, Ubuntu, and WSL installers install both skills. - Every installer downloads `architect-workflow.md` from its existing gist raw base. - Every installer targets `~/.claude/skills/plan-build-architect/SKILL.md`. - Parent directories are created safely. - Downloads use temporary files and atomic moves. - Failed downloads remove temporary files and emit clear errors or warnings consistent with each installer's existing behavior. - Existing plan-build skill installation remains intact. - A new Zsh test validates all four installer contracts statically and runs without external services. - Bash and Zsh syntax checks pass. ### Verification Commands ```bash bash -n config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh zsh -n test_plan_build_installers.zsh zsh test_plan_build_installers.zsh zsh test_plan_build.zsh git diff --check -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh git diff -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh ``` ### Prompt for Codex ```text Objective: Distribute the canonical architect workflow through every supported Zsh Setup installer. Install repository file architect-workflow.md from the existing gist raw base as ~/.claude/skills/plan-build-architect/SKILL.md, using the same safe temporary-file and atomic-move pattern as the existing plan-build skill. Add a network-free repository test for the installer contracts. Allowed File Scope: - config.sh - zsh_macos.sh - zsh_ubuntu.sh - zsh_wsl.sh - test_plan_build_installers.zsh (new) Do not modify architect-workflow.md. Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. Context / Interfaces: - config.sh and all three platform installers already install orchestrate-loop.md at ~/.claude/skills/plan-build/SKILL.md. - Preserve that existing installation exactly. - Add architect-workflow.md as a second canonical source. - Install it at ~/.claude/skills/plan-build-architect/SKILL.md. - Use each script's existing GIST_RAW_BASE. Do not add or depend on another gist or endpoint. - Follow each script's current logging and failure conventions. - Create destination directories safely. - Download to a temporary sibling file and move only after successful curl completion. - Remove temporary files on failure so partial skills cannot become active. - test_plan_build_installers.zsh must inspect repository files and assert the source filename, installed destination, existing-skill preservation, and safe download pattern for config.sh plus macOS, Ubuntu, and WSL scripts. - The test must not access the network, invoke sudo, execute the installers, or write to the real home directory. - Keep changes localized to existing skill-install blocks. Acceptance Criteria: 1. All four installers install the existing plan-build skill and new architect skill. 2. All use architect-workflow.md and ~/.claude/skills/plan-build-architect/SKILL.md. 3. All use temporary download files and atomic moves, with cleanup on failure. 4. Existing installation behavior remains intact. 5. The new static contract test passes without external services. 6. Existing plan_build tests remain green. Required Verification: - bash -n config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh - zsh -n test_plan_build_installers.zsh - zsh test_plan_build_installers.zsh - zsh test_plan_build.zsh - git diff --check -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. ``` ### CodeRabbit Outcome Pending. ### Completion Evidence Pending. --- ## Final Review and Handover Gate This gate begins only after `TASK-001`, `TASK-002`, and `TASK-003` are `Complete`. Claude must: 1. Complete all root engineering records and mandatory `docs/` handover files. 2. Run CodeRabbit over the complete uncommitted diff. 3. Delegate valid code or test fixes to Codex under the responsible task's original scope and retry limit. 4. Run all focused commands plus the complete repository verification suite. 5. Validate required documents, links, source references, examples, Mermaid syntax where tooling exists, and absence of unresolved placeholders. 6. Run available secret scanning and block suspected credentials. 7. Confirm Git contains only approved changes and preserves pre-existing user work. 8. Present the final diff summary, verification evidence, known limitations, and proposed single commit message. 9. Wait for explicit user approval before staging and creating one commit. 10. Never push automatically. ## Final Commit **Status:** Pending user approval after final gate. **Proposed message:** `feat: add plan_build architect workflow`