# Architecture Decision Records

## ADR-001: Make plan-build a dedicated standalone gist

**Status:** Accepted

The implementation previously lived inside the broad Zsh Setup `func` file while its workflows and history were spread across that repository. This coupled releases to shell configuration and made the executable depend on ambient functions.

The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, Superpowers, Git-worktree, architect-preflight, payload, and Claude-launch helpers. Zsh Setup will eventually retain only an atomic cache launcher and skill downloader.

The old launcher migration is a separate, still-pending change because this extraction must not modify the source repository.

## ADR-002: Keep one supported workflow surface

**Status:** Accepted

The supported surface is standard, prompt enhancement, brainstorm, writing-plan, architect, new architect state, and permissive Claude execution. The removed v2 entry point remains rejected as an unknown option, and stale v2-only distribution concepts are not part of the canonical skills.

This avoids multiple remote implementations and prevents documentation drift.

## ADR-003: Translate convenience flags at the process boundary

**Status:** Accepted

`--yolo` remains the plan-build user interface for continuity, but `_plan_build_launch_claude` translates it to Claude Code's actual `--dangerously-skip-permissions` argument. Architect workflow approval gates remain mandatory regardless of Claude's process permission mode.

## ADR-004: Test through replaceable command seams

**Status:** Accepted

The executable is sourceable and its `_plan_build_` helpers form test seams. Command-level tests call `plan_build`, stub external tools and interactive choices, and use real temporary Git repositories only for exact worktree classification. Tests never use the network.

## ADR-005: Validate mutable cache updates before atomic activation

**Status:** Accepted

The thin launcher must stage `plan_build.zsh` beside its cache target, reject empty downloads and files that fail `zsh -n`, and only then atomically rename the candidate into place. The mutable HTTPS `HEAD` URL is the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content or establish update provenance.