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

## Zsh Setup cache launcher

When curl is available, the Zsh Setup integration attempts to download this complete release bundle on every invocation:

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

It stages all three non-empty files, requires `plan_build.zsh` to pass `zsh -n`, moves the bundle into a unique immutable release directory, and atomically switches a single `current` symlink. Activation is serialized with a kernel-backed Zsh file lock. Failed refreshes leave the prior validated release active and repair its skill links before execution.

The launcher invokes the executable from the selected immutable release and binds both internal skill paths to that same release:

```zsh
PLAN_BUILD_SKILL_PATH=<selected-release>/SKILL.md \
PLAN_BUILD_ARCHITECT_SKILL_PATH=<selected-release>/ARCHITECT.md \
zsh <selected-release>/plan_build.zsh "$@"
```

It never sources remote code into the caller shell. The 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. Complete-release activation and syntax validation prevent partial or syntactically invalid active releases; they do not establish provenance or guarantee that three independent downloads observed the same remote revision if publication occurs during refresh.

The installed Claude skill files are symlinks through the same `current` release:

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

The launcher defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/plan-build`; Zsh Setup exposes `PLAN_BUILD_CACHE_DIR` and `PLAN_BUILD_BASE_URL` overrides. Skill paths stay fixed at `~/.claude/skills` to match the canonical executable.

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