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

Changelog

All notable changes to this project are documented in this file.

Unreleased

Added

• TASK-002: Added built-in plan_build --architect with safe-resume, new-workflow, yolo, preflight, and command-level regression coverage.
• Added the canonical documentation-first architect workflow source.

Changed

• Documented architect mode prerequisites and supported flag combinations.

Removed

• TASK-001: Removed the obsolete standalone v2 downloader, forwarding behavior, and public usage contract.

Fixed

• TASK-002: Reject bare Git repositories during architect preflight while accepting normal worktrees.

Bash Script Installer for Zsh

The "Bash Script Installer" simplifies the setup of Zsh.

Zsh

Ubuntu

bash -c "$(curl -fsSL https://tinyurl.com/y6fhb594)"

WSL

bash -c "$(curl -fsSL https://tinyurl.com/ycyct6wp)"

MacOS

bash -c "$(curl -fsSL https://tinyurl.com/yptybtpa)"

Configuration

bash -c "$(curl -fsSL https://tinyurl.com/y8vf753j)"

Shell framework and prompt

The installers use Oh My Zsh for framework features and plugins, with the OMZ theme disabled:

ZSH_THEME=""
source "$ZSH/oh-my-zsh.sh"
eval "$(starship init zsh)"

Starship owns the prompt and loads after Oh My Zsh. The managed Starship config is installed at ~/.config/starship.toml. A Nerd Font is required for the Powerline symbols.

Plan-build workflow

plan_build launches Claude Code as the implementation orchestrator, with Codex and CodeRabbit as independent reviewers. The configuration installer also installs its workflow at ~/.claude/skills/plan-build/SKILL.md.

Architect mode keeps Claude focused on architecture and documentation while Codex implements one approved task at a time and CodeRabbit reviews each task. It uses ~/.claude/skills/plan-build-architect/SKILL.md.

plan_build                                      # Standard plan and build
plan_build --prompt                             # Enhance the payload with Auggie first
plan_build --writing-plan                       # Superpowers implementation plan, Codex review, then build
plan_build --prompt --brainstorm                # Auggie, Superpowers design and plan, Codex review, then build
plan_build --yolo --writing-plan                # Pass --yolo through to Claude Code
plan_build --architect                          # Documentation-first architecture workflow
plan_build --architect --new                    # Archive existing planning state and start a new workflow
plan_build --architect --yolo                   # Forward --yolo without bypassing workflow approval gates

--brainstorm and --writing-plan are mutually exclusive. They require the enabled superpowers@claude-plugins-official Claude Code plugin; plan_build reports the install or enable command and exits before Auggie when the requirement is not met.

--architect may combine only with --new and --yolo. It requires an interactive terminal, a Git worktree, Claude Code, Codex, CodeRabbit, Git, and the installed architect skill. The obsolete --v2 integration has been removed.

On a machine without this full setup (config.sh normally installs the skill), install just the plan-build skill with:

mkdir -p ~/.claude/skills/plan-build ~/.claude/skills/plan-build-architect
curl -fsSL https://opengist.resetrix.work/weehong/f0d940c3c1214bf5b7996195199fdc09/raw/HEAD/orchestrate-loop.md -o ~/.claude/skills/plan-build/SKILL.md
curl -fsSL https://opengist.resetrix.work/weehong/f0d940c3c1214bf5b7996195199fdc09/raw/HEAD/architect-workflow.md -o ~/.claude/skills/plan-build-architect/SKILL.md

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

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

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:

Only one task may have In Progress status.

Task State Transitions

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:

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.

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

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

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: <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

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

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 -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

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

Plan Build Architect Workflow

Use this workflow only when plan_build --architect launches Claude Code. Claude is the lead architect, documentation manager, task dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit is the required automated reviewer.

Non-Negotiable Role Boundary

Claude may inspect every project file but may create or modify only:

• SPEC.md
• TASKS.md
• ADR.md
• CHANGELOG.md
• README.md
• Markdown files under docs/

Claude must not write application code, test code, migrations, generated source, or executable configuration. Delegate those changes to Codex through an approved task prompt.

Codex must not commit, stage, push, reset, restore, or discard changes. All approved work remains uncommitted until the complete delivery passes final verification and the user approves one final commit.

Never push automatically.

Startup Preflight

Before discovery or project-file modification:

1. Confirm the current directory is a Git worktree.
2. Record git status --short and preserve all pre-existing work.
3. Confirm an interactive terminal is available.
4. Confirm codex, coderabbit, and git are available.
5. Inspect project instructions, manifests, existing documentation, tests, CI, and nearby implementation patterns.
6. Never request or expose credential values. Use approved credential integrations when authentication is required.

If a requirement is missing, stop with exact remediation guidance.

Existing Workflow Detection

If SPEC.md, TASKS.md, ADR.md, or CHANGELOG.md exists:

1. Read all existing workflow records.
2. Compare their claims with Git and the current worktree.
3. Identify the first incomplete or inconsistent task.
4. Present the detected state and ask whether to resume.

When the launch instruction says Start mode: archive-and-start-new, archive existing workflow documents in a timestamped documentation archive before creating replacements. Never overwrite them silently.

Phase 1: Discovery and Architecture

Interview the user until product, architecture, data, integration, operational, security, and handover requirements are clear.

Rules:

• Ask exactly one question at a time.
• Include a recommended default answer with every question.
• Resolve facts from the repository instead of asking the user.
• Ask the user only for decisions, priorities, business rules, and information that cannot be discovered safely.
• Probe user roles, workflows, data structures, API or component contracts, technology constraints, integrations, edge cases, failure modes, migration, rollback, testing, deployment, monitoring, security, compliance, support, and ownership.
• Collect project name, client or owner, purpose, target users, repository scope, supported environments, deployment owner, operational owner, support role, compliance constraints, and intended handover date.
• Do not implement or dispatch Codex during discovery.

Do not enter Phase 2 until the user explicitly states either:

• I am ready to generate the spec
• Phase 1 complete

Phase 2: Specification

After the explicit Phase 1 completion phrase:

1. Ask no more discovery questions.
2. Create or reconcile SPEC.md without discarding valid existing content.
3. Include executive summary and goals, architecture and technology, data models or durable state schemas, API or component contracts, edge cases, constraints, testing strategy, out-of-scope items, and definition of done.
4. Use Mermaid for applicable system context, component, deployment, and critical sequence diagrams.
5. Mark non-applicable sections with a factual rationale instead of inventing behavior.
6. Treat the approved specification as the requirements baseline.
7. Present the specification and wait for explicit approval.

Any later requirement change is a visible amendment. Pause execution, assess affected tasks and documents, record architectural changes in ADR.md, and obtain approval before continuing.

Phase 3: Codex Task Plan

After SPEC.md approval, create or reconcile TASKS.md.

Use stable task IDs such as TASK-001. Allowed states are:

• Pending
• In Progress
• Blocked
• Review
• Complete

Only one task may be In Progress.

Every task must include:

• ID, title, status, and dependencies
• Objective
• Exhaustive allowed file scope
• Context and interfaces
• Self-contained prompt for Codex
• Acceptance criteria
• Unit or integration test requirements
• Verification commands
• CodeRabbit outcome
• Completion evidence

Every Codex prompt must explicitly prohibit commits and out-of-scope edits. Tasks must be atomic, sequential, and small enough for a fresh Codex context.

Present TASKS.md and wait for explicit approval before execution.

Documentation Records

Maintain these root engineering records throughout execution:

• SPEC.md: approved requirements baseline and amendments
• TASKS.md: task state, prompts, reviews, and evidence
• ADR.md: append-only architecture decisions
• CHANGELOG.md: Keep a Changelog-compatible Unreleased entries referencing task IDs
• README.md: product overview, prerequisites, quick start, and configuration

Every ADR uses a stable ID and records status, date, context, decision, alternatives, consequences, and affected components. Keep superseded decisions and link their replacements.

Mandatory Client Handover Package

The following files are mandatory without exception:

• docs/USER_MANUAL.md
• docs/RUNBOOK.md
• docs/API.md
• docs/DEPLOYMENT.md
• docs/SECURITY.md
• docs/HANDOVER.md

Create missing documents and reconcile existing ones. Do not replace valid project-specific content wholesale.

When a document or section is not applicable, retain it and state Not Applicable with a short factual rationale.

Client-facing documents describe the delivered system, not Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless disclosure is contractually required.

Implementation claims must reference relevant source files, configuration, schemas, endpoints, or verified commands. Handover documents include software version or commit SHA, generation date, document owner, and last verification date.

docs/HANDOVER.md must include deliverables, access prerequisites, verified capabilities, limitations, approved deferred risks, support boundaries, warranty assumptions, ownership transfer, and dated acceptance/sign-off placeholders.

Task Execution Loop

For each approved task, in dependency order:

1. Confirm dependencies are Complete.
2. Set exactly that task to In Progress.
3. Record the current Git status and task baseline.
4. Invoke Codex non-interactively in the current worktree with workspace-write access using the exact approved prompt from TASKS.md.
5. Capture Codex's result.
6. Inspect the diff for correctness, approved scope, repository conventions, unrelated changes, and secret exposure.
7. Independently run the task's verification commands.
8. Set the task to Review and run CodeRabbit on the task diff.
9. Investigate every concrete finding.
10. Delegate valid fixes back to Codex within the same task scope.
11. Rerun focused verification and CodeRabbit after substantive fixes.
12. Record commands, results, findings, and completion evidence.
13. Report the outcome and wait for user approval before starting the next task.

Use non-interactive Codex execution in this form, adapting only supported sandbox flags to the installed CLI:

codex exec --sandbox workspace-write "<exact approved task prompt>"

Critical, high, and medium CodeRabbit findings block completion. Low-severity findings may be deferred only with user approval and must be recorded in CHANGELOG.md and docs/HANDOVER.md.

Scope Expansion

If Codex reports that required work exceeds the allowed file scope:

1. Do not permit out-of-scope edits.
2. Assess requirement, architecture, dependency, and test impact.
3. Update SPEC.md, TASKS.md, and ADR.md when appropriate.
4. Ask the user to approve the revised scope.
5. Redispatch only after approval.

Failure and Retry Policy

Allow the initial Codex attempt plus at most two focused correction attempts.

If acceptance still fails:

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

If no test framework exists, the first applicable task establishes the smallest project-appropriate validation setup. If automated testing is technically impossible, obtain user approval for explicit manual acceptance steps and record the risk in docs/HANDOVER.md.

Security Rules

• Never include credential values, tokens, private keys, personal data, or production secrets in prompts or documentation.
• Document only secret names, required environment variables, approved storage, ownership, and rotation procedures.
• Use native credential helpers and approved credential stores.
• Run available secret scanning before final completion.
• Treat suspected credentials as blocking findings.

Final Review and Single Commit

After every task is Complete:

1. Finish all root engineering records and mandatory handover documents.
2. Run CodeRabbit over the complete uncommitted diff.
3. Delegate valid code or test fixes to Codex under the responsible task scope.
4. Run the complete project lint, type-check, build, and test suite.
5. Confirm the aggregate diff contains only approved changes and preserves pre-existing work.
6. Validate required documents and sections, Markdown structure, links, source references, commands, examples, and Mermaid syntax where tooling is available.
7. Ensure no unresolved TODO, placeholder, or template text remains. Approved limitations belong in docs/HANDOVER.md.
8. Run available secret scanning.
9. Present the complete diff summary, verification evidence, known limitations, and proposed commit message.
10. Wait for explicit user approval.
11. Stage only approved files and create one commit.
12. Do not push.

Never call the delivery complete when required verification has not run. Report environmental or unrelated failures with evidence.

Plan-Build Orchestrate Loop

Use this workflow when plan_build hands Claude Code an implementation task. The goal is to keep Claude as the orchestrator while using Codex and CodeRabbit as independent review and validation agents. When plan_build supplies "Distribution mode: on", Codex and Kimi Code also become the implementers (backend and frontend respectively) via the Distributed Implementation variant of step 5.

Operating Rules

• Run from the project root. Treat the current working directory as the project to modify.
• Preserve user work. Check git status before edits and do not revert unrelated changes.
• Keep implementation scoped to the payload unless repository context proves a wider change is required.
• Prefer existing project conventions, scripts, test commands, and dependency managers.
• Do not call the task complete until validation has run or the reason it cannot run is documented.
• If any agent reports a plausible correctness, security, data-loss, migration, or test risk, resolve it or explicitly document why it is not applicable.

The 8-Step Workflow

1. Intake

Read the user payload fully. Identify:

• Objective and expected user-visible behavior.
• Files, modules, commands, and frameworks likely involved.
• Constraints from repository docs, package scripts, CI config, and existing patterns.
• Any ambiguity that blocks safe execution.

Only ask the user a question when no reasonable project-local assumption is safe.

2. Baseline

Inspect the repository before changing files:

git status --short
rg --files

Then read the smallest useful set of files. Prefer rg, package manifests, tests, routing files, and nearby implementations over broad file dumps.

3. Plan

Follow the planning mode supplied by plan_build:

• standard: Create a short implementation plan with concrete steps and validation commands.
• brainstorm: Invoke superpowers:brainstorming, honor its design and written-spec approval gates, and let it transition to superpowers:writing-plans after approval.
• writing-plan: Invoke superpowers:writing-plans directly, treating the payload as the requirements or specification.
• grill: Invoke mattpocock-skills:grilling to relentlessly stress-test the payload and your intended approach with the user. After grilling concludes, write the workflow's normal short implementation plan incorporating what survived.

For either Superpowers mode, save the artifacts at the paths selected by the skills. In grill mode, the short implementation plan is the planning artifact. When writing-plans reaches its execution handoff, return to this workflow instead of starting implementation: Codex must review the plan first. If the user rejects or cancels a required approval, stop cleanly without modifying implementation files.

If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note.

4. Codex Plan Review

Run this step only for brainstorm, writing-plan, and grill modes. Ask Codex for an independent, read-only review of the approved spec, when present, and the implementation plan before touching implementation files. Provide the original payload and artifact paths. Ask it to focus on requirement coverage, incorrect assumptions, unsafe migrations, missing edge cases, inadequate tests, and steps that are too vague to execute.

Recommended prompt shape:

Review these planning artifacts before implementation. Check requirement coverage, technical correctness, repository fit, edge cases, migration or rollback risk, test coverage, and whether every step is executable. Report concrete findings only; do not modify files.

Task:
<payload>

Spec:
<spec path, if present>

Implementation plan:
<plan path>

Use a read-only, ephemeral Codex invocation. Resolve every valid finding in the artifacts and repeat the review if revisions are substantial. If an artifact is missing or empty, or Codex cannot complete the review, stop before implementation and report the failure.

In standard mode, skip this step and continue directly to implementation.

5. Implement

If plan_build supplied "Distribution mode: on", skip this step and step 6 and follow the Distributed Implementation variant (steps 5a–5c) below instead, then continue at step 7.

Make the change in small, reviewable edits:

• Follow existing style and abstractions.
• Add or update tests when behavior changes.
• Update docs only when user-facing usage changes.
• Avoid unrelated refactors and formatting churn.

After each meaningful edit group, re-check the diff for accidental changes.

Distributed Implementation (distribution mode: on)

In this variant you orchestrate and review only — you never implement, not even leftovers. Codex implements backend items; Kimi Code implements frontend items.

5a. Split And Confirm

Tag every work item in the plan as BE, FE, or unclear. Present the full table to the user (AskUserQuestion) and have them confirm or reassign each item; unclear items must be assigned by the user to BE or FE. Dispatch nothing until every item is confirmed.

5b. Backend Phase (Codex)

Check git status first so pre-existing work is never mixed in or reverted. Compose a self-contained brief: the task, constraints, the exact confirmed BE item list with file paths, project conventions, and validation commands. Dispatch:

codex exec --full-auto "<brief>"

Then review the phase diff (git diff) yourself for correctness, scope, and convention fit. Send findings back to Codex as a new brief (findings plus the original context) — do not fix them yourself. Maximum 2 retry rounds; if valid findings remain after that, stop and report with the partial diff intact.

An empty diff from a delegate counts as a failure: retry once with a sharpened brief, within the same 2-round bound. If the delegate CLI crashes or hangs, stop and report, preserving the partial diff.

5c. Frontend Phase (Kimi Code)

Check git status again, then compose the FE brief the same way, and additionally include the now-implemented backend API surface (routes, types, request/response contracts) so the frontend builds against the real backend. Dispatch:

kimi -p "<brief>"

(-p runs one prompt non-interactively and manages permissions itself; it cannot be combined with --auto or --yolo.)

Review the phase diff and route findings back to Kimi under the same 2-round retry bound and failure rules as the backend phase.

After both phases pass review, skip step 6 (the per-phase reviews above replace it — Codex cannot impartially review the half it wrote) and continue at step 7 with the combined diff.

6. Codex Code Review Pass

Skip this step in distribution mode; the per-phase reviews in steps 5b–5c replace it.

Ask Codex for an independent review of the local diff before finalizing. Provide the task, constraints, and current diff. Ask it to focus on bugs, edge cases, missing tests, regressions, and simpler project-native alternatives.

Recommended prompt shape:

Review this change for correctness and risk. Prioritize bugs, regressions, missing tests, and mismatches with existing project patterns. Do not rewrite the whole solution unless a specific issue requires it.

Task:
<payload>

Diff:
<git diff>

Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial.

7. CodeRabbit Review Pass

Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding.

If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely.

8. Validate And Close

Run the planned validation commands, such as:

npm test
npm run lint
pytest
cargo test
go test ./...

Use the commands that actually exist in the project. If validation fails, fix the issue and rerun the relevant command. If a failure is unrelated or environmental, capture the evidence.

Before final response:

• Confirm git diff contains only intended changes.
• Summarize what changed.
• Report validation run and result.
• Note any remaining risks or commands that could not run.