# plan-build

`plan-build` is a standalone Zsh tool that launches Claude Code with a structured multi-agent implementation workflow. Claude orchestrates, Codex provides independent implementation review, and CodeRabbit reviews the resulting changes. Architect mode instead keeps Claude within a documentation-first architecture and task-dispatch role while Codex performs implementation.

## Prerequisites

- Zsh
- Claude Code CLI (`claude`)
- OpenAI Codex CLI (`codex`)
- CodeRabbit CLI (`coderabbit`)
- Git
- The installed plan-build skills described below

`--prompt` also requires Auggie (`auggie`), an authenticated `~/.augment/session.json`, Perl, and the platform `script` utility.

`--brainstorm` and `--writing-plan` require the enabled Claude Code plugin `superpowers@claude-plugins-official`. Claude Code safe mode must be disabled for those modes.

Architect mode additionally requires an interactive terminal and a normal Git worktree. Bare repositories are rejected.

## Installation

Install the executable somewhere on `PATH`:

```zsh
mkdir -p "$HOME/.local/bin"
curl -fsSL \
  https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh \
  -o "$HOME/.local/bin/plan_build"
chmod +x "$HOME/.local/bin/plan_build"
```

Then install both skills:

```zsh
mkdir -p \
  "$HOME/.claude/skills/plan-build" \
  "$HOME/.claude/skills/plan-build-architect"
curl -fsSL \
  https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md \
  -o "$HOME/.claude/skills/plan-build/SKILL.md"
curl -fsSL \
  https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md \
  -o "$HOME/.claude/skills/plan-build-architect/SKILL.md"
```

For production automation, download to a temporary file in the destination directory and rename it atomically after a successful transfer.

## Usage

Run the command in the project you want to change, enter the payload, then put `EOF` alone on a line:

```zsh
plan_build
Implement pagination for the audit log.
Preserve existing API compatibility.
EOF
```

Available modes:

```text
plan_build                                      Standard short-plan workflow
plan_build --prompt                             Enhance with Auggie and approve
plan_build --brainstorm                         Superpowers design and plan
plan_build --writing-plan                       Superpowers implementation plan
plan_build --prompt --brainstorm                Enhance, design, plan, and build
plan_build --yolo --writing-plan                Permissive Claude process mode
plan_build --architect                          Safely resume architect state
plan_build --architect --new                    Archive state and start fresh
plan_build --architect --yolo                   Architect with permissive process mode
```

`--brainstorm` and `--writing-plan` are mutually exclusive. `--prompt` can combine with either. `--architect` can combine only with `--new` and `--yolo`; `--new` is invalid without `--architect`. Duplicate flags and all other flags fail. `--v2` is intentionally unsupported.

The user-facing `--yolo` option is translated to Claude Code's `--dangerously-skip-permissions` argument. It never bypasses approval gates defined by either workflow.

## Cache-launcher integration contract

The future thin Zsh Setup launcher must download:

```text
https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
```

It must download into a temporary file beside the cache target, validate that the download succeeded, is non-empty, and passes `zsh -n`, then atomically rename it into place. It invokes the cached program exactly as:

```zsh
zsh <cache> "$@"
```

This mutable HTTPS `HEAD` download is the explicit update trust boundary: transport security authenticates the server, but the URL provides neither immutable-version pinning nor content-integrity verification. Atomic activation and syntax validation prevent partial or syntactically invalid cache entries; they do not establish provenance for changed remote content.

The same launcher or installer downloads `SKILL.md` and `ARCHITECT.md` from the same gist to:

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

The launcher migration in the Zsh Setup repository is not part of this extraction and is not yet complete.

## Testing

The suite is self-contained and never accesses the network or launches real agent CLIs:

```zsh
zsh -n plan_build.zsh test_plan_build.zsh
zsh test_plan_build.zsh
git diff --check
```

## Troubleshooting

- **CLI is missing:** install the named program and ensure its executable is on `PATH`.
- **Superpowers is missing:** in Claude Code run `/plugin install superpowers@claude-plugins-official`.
- **Superpowers is disabled:** run `claude plugin enable superpowers@claude-plugins-official`.
- **Safe mode blocks planning:** unset `CLAUDE_CODE_SAFE_MODE`.
- **Auggie cannot authenticate:** run `auggie login` and confirm `~/.augment/session.json` is non-empty.
- **Prompt enhancement does not continue:** `--prompt` requires an interactive terminal to approve both optional project indexing and the final enhanced prompt.
- **Architect preflight fails in Git:** change to a checked-out worktree rather than the `.git` directory or a bare repository.
- **Architect skill is missing:** install `ARCHITECT.md` at the exact skill path shown above.