# Plan-Build Specification

## Purpose

Plan-build is a self-contained Zsh launcher for Claude Code multi-agent implementation workflows. This repository is the canonical boundary for the executable, both Claude skills, command tests, and project documentation. It does not depend on the Zsh Setup repository or on functions from `~/.func`.

## Public interface

```text
plan_build [--yolo] [--prompt] [--brainstorm | --writing-plan]
plan_build --architect [--new] [--yolo]
```

The executable reads standard input until a line exactly equal to `EOF`. Empty payloads fail. Unknown and duplicate options fail with usage text. `--v2` is intentionally unknown.

### Standard modes

- No planning flag: use the normal short-plan eight-step workflow.
- `--prompt`: enhance the payload through Auggie, display the result, and require interactive approval before Claude launches.
- `--brainstorm`: require enabled Claude Superpowers, then use brainstorming and writing-plans approval gates.
- `--writing-plan`: require enabled Claude Superpowers and create the implementation plan directly.
- `--yolo`: launch Claude Code with `--dangerously-skip-permissions`.

`--brainstorm` and `--writing-plan` are mutually exclusive. `--prompt` may be combined with either.

### Architect mode

`--architect` makes Claude the documentation-first architect and dispatcher. It may combine only with `--new` and `--yolo`.

- Default: safely detect and resume existing planning state.
- `--new`: archive existing planning documents as directed by the architect skill and start fresh.
- `--yolo`: changes Claude Code permissions only; every workflow approval gate remains mandatory.

Architect preflight happens before payload input and verifies an interactive terminal, Claude Code, Codex, CodeRabbit, Git, an exact normal Git worktree, and a readable non-empty architect skill.

## Installed skills

The executable expects:

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

The canonical repository sources are `SKILL.md` and `ARCHITECT.md`.

## Standalone constraints

- Zsh on macOS, Ubuntu, and WSL.
- No sourcing of user shell configuration.
- All internal helpers use the `_plan_build_` namespace.
- External command boundaries remain replaceable for tests.
- Tests use no network and do not launch real agent CLIs.
- The program remains sourceable and runs main only when executed directly.

## Zsh Setup launcher integration

A thin Zsh Setup launcher downloads one release bundle:

```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 must stage all three files, require each to be non-empty, and require the executable to pass `zsh -n`. A validated bundle moves into a unique immutable release directory. Activation is serialized by a kernel-backed Zsh file lock and occurs by atomically replacing one `current` symlink. The installed skill paths symlink to `SKILL.md` and `ARCHITECT.md` through `current`, so executable and skills always resolve through one release boundary. Cached fallback repairs missing or stale skill links before execution.

The launcher executes the selected release with `PLAN_BUILD_SKILL_PATH` and `PLAN_BUILD_ARCHITECT_SKILL_PATH` bound to that same immutable directory:

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

It does not source the downloaded executable. Refresh failure falls back to the last complete validated release; without one, launch fails. Curl is optional only when that fallback exists. Signals stop an in-flight refresh, clean temporary state, and return the conventional signal status.

The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS authenticates the transport endpoint, but without an immutable version or pinned digest it does not provide content-integrity or provenance guarantees for updates. Because the three files are separate requests, publication during refresh can also expose different remote revisions; publishers should update the gist only from complete, tested commits.

## Acceptance criteria

- Every documented mode has command-level coverage.
- Invalid combinations, duplicate flags, empty payloads, and `--v2` rejection are covered.
- Superpowers checks precede Auggie and payload input.
- Architect preflight precedes payload input and distinguishes normal worktrees from bare repositories.
- Prompt enhancement cannot launch Claude without explicit approval.
- `--yolo` reaches the Claude binary only as `--dangerously-skip-permissions`.
- Syntax checks, command tests, and `git diff --check` pass.
- The Zsh Setup launcher activates and falls back only in complete three-file releases.