# 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, workflow-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:** Superseded by ADR-006

The former supported surface was standard, prompt enhancement, brainstorm, writing-plan, architect, new architect state, and permissive Claude execution. The removed v2 entry point remained rejected as an unknown option, and stale v2-only distribution concepts were excluded from 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.

## ADR-006: Make Matt Pocock's workflow the default

**Status:** Accepted

The Superpowers brainstorm and writing-plan flags created parallel planning surfaces and required Claude to transition between plugin workflows inside one launcher mode. Matt Pocock's flow already distinguishes discovery, specifications, tracer-bullet tickets, TDD, diagnosis, and large wayfinding efforts while defining where fresh contexts are required.

The standard invocation now routes through Matt's workflow by default. `--brainstorm` and `--writing-plan` are removed without compatibility aliases. Matt entry skills that disable model invocation remain explicit user gates. Multi-session planning stops after approved tickets, and each ticket starts in a fresh plan-build session. The standard workflow overrides Matt `/implement`'s automatic commit step so uncommitted changes receive two-axis, Codex, and CodeRabbit review before user approval.

## ADR-007: Scope continuity with a committed AgentMemory identity

**Status:** Accepted

AgentMemory's default project fallback uses a directory basename, which can collide across unrelated repositories and vary across worktrees. Every target repository therefore commits `.agentmemory-project`, and the launcher exports that stable value as `AGENTMEMORY_PROJECT_NAME` to Claude and inherited Codex processes.

Hooks provide automatic capture and context injection, but they tolerate server failure and cannot guarantee that the active case was restored. Both workflow skills therefore require an explicit recall gate and exactly one project-scoped `workflow_status` slot. Current Git and approved artifacts outrank recalled state. Durable memories store only verified decisions, fixes, constraints, gotchas, relationships, and preferences; the status slot carries temporary handoff state.

When the server or either agent plugin is unavailable, an interactive user may retry, approve clearly reported degraded mode, or stop. Non-interactive failure stops. This preserves user control without silently claiming continuity.