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

## Thin-launcher integration

A future Zsh Setup launcher will download:

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

It must write to a temporary file in the cache directory, require the download to be non-empty and pass `zsh -n`, make the validated file atomically visible, then execute:

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

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.

It will download `SKILL.md` and `ARCHITECT.md` from the same gist into the installed skill paths above. Migration of that old launcher is deliberately outside this repository and is not yet complete.

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