# 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 retains only a cached launcher that refreshes the canonical bundle.

The Zsh Setup migration is maintained separately from the canonical executable so shell installation concerns do not leak back into this 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: Activate immutable complete releases through one symlink

**Status:** Accepted

The thin launcher stages `plan_build.zsh`, `SKILL.md`, and `ARCHITECT.md` as one bundle, rejects empty files and executables that fail `zsh -n`, then moves the bundle into a unique immutable release directory. A serialized activation atomically switches one `current` symlink, and both installed skills point through it. Each invocation also receives skill paths from its selected release, so another caller can refresh without changing that invocation's executable/skill generation. The mutable HTTPS `HEAD` URL remains the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content, establish update provenance, or make the three separate requests one remote snapshot.