# Plan-Build Specification ## Purpose Plan-build is a self-contained Zsh launcher for memory-aware Claude Code engineering workflows. Matt Pocock's skills define discovery through delivery, AgentMemory provides project continuity across Claude and Codex sessions, Codex performs independent review or architect-dispatched implementation, and CodeRabbit reviews local changes. This repository is canonical for the executable, both plan-build skills, command tests, and documentation. ## Public Interface ```text plan_build [--yolo] [--prompt] plan_build --architect [--new] [--yolo] ``` The executable reads standard input until a line exactly equal to `EOF`. Empty payloads, duplicate flags, and unknown flags fail. `--brainstorm`, `--writing-plan`, and `--v2` are intentionally unknown. - Default mode uses the memory-aware Matt workflow. - `--prompt` enhances the payload through Auggie and requires interactive approval before Claude launches. - `--yolo` translates to `--dangerously-skip-permissions` without bypassing workflow gates. - `--architect` keeps Claude documentation-only and makes Codex the implementation executor. - `--architect --new` archives active workflow documents before starting new state. `--architect` may combine only with `--new` and `--yolo`. ## Common Preflight All modes require an interactive terminal, a normal Git worktree, Claude, Codex, CodeRabbit, Git, AgentMemory, and a readable non-empty selected workflow skill. Claude safe mode is rejected. Default mode additionally requires the enabled Claude plugin `mattpocock-skills@mattpocock`. Every mode checks the AgentMemory server and enabled `agentmemory@agentmemory` plugins for Claude and Codex. When memory preflight fails, an interactive user may retry, explicitly approve degraded memoryless mode, or stop. Non-interactive memory failure stops. Other preflight failures are not degradable. ## Stable Memory Identity Every target worktree uses a committed `.agentmemory-project` containing one stable 2-128 character identifier. Its exact grammar is `[A-Za-z0-9][A-Za-z0-9._:/-]{1,127}`; whitespace is forbidden. On first interactive use, the launcher proposes a normalized `origin` identity or asks for an explicit ID, writes the file after approval, and stops. A later invocation proceeds only when the file exists in `HEAD` and its working-tree value matches the committed value. The launcher exports: ```text AGENTMEMORY_PROJECT_NAME= AGENTMEMORY_INJECT_CONTEXT= PLAN_BUILD_MEMORY_MODE= ``` Claude and inherited Codex processes therefore share one scope across worktrees, clones, and machines. ## Mandatory Recall And Checkpoint When memory is available, before routing, discovery, workflow detection, or modification, each skill reads or creates one project-scoped `workflow_status` slot, retrieves related decisions, bugs, lessons, and file history, and reconciles them with current Git and approved artifacts. In explicitly approved degraded mode, the skill skips memory calls, reports that recall and checkpoint persistence are unavailable, proceeds only from current repository evidence, and never claims previous context was restored. A later memory failure requires the same retry, explicitly degrade, or stop choice. The slot records phase, active work and source, completed milestone, in-flight work, blockers, pending decisions, relevant files, last verification, one next step, and update time. It is replaced at meaningful milestones and before session end. Durable decisions and verified fixes are saved separately; routine output, secrets, personal data, generated content, and unverified hypotheses are not. Authority order is current Git and approved issue/spec, repository documentation and ADRs, active status slot, verified durable memory, then raw observations. ## Matt Workflow The standard skill routes ordinary ideas to grilling, approved tickets to implementation, hard bugs to diagnosis, huge foggy efforts to wayfinding, incoming external issues to triage, and codebase health requests to architecture improvement. Matt entry skills requiring explicit user invocation are never silently simulated. Small approved work remains in the discovery context. Multi-session work creates an approved spec and tracer-bullet tickets, then stops; every unblocked ticket starts in a fresh plan-build invocation. Implementation uses pre-agreed public test seams and red-green vertical slices. Matt's automatic commit instruction is overridden. The uncommitted working tree receives Matt-equivalent Standards and Spec review, Codex review, CodeRabbit review, and complete validation before the user approves one commit. Plan-build never pushes automatically. ## Architect Mode Architect mode runs memory recall before existing-state detection. Claude may modify only its documented Markdown scope. Codex receives the project ID, task/spec references, and compact checkpoint, recalls relevant history independently, and remains prohibited from commits or out-of-scope edits. Archive-and-start-new preserves historical memories but replaces the active slot after successful document archival. Historical memory is context, not approval for the new requirement. ## Installed Skills ```text ~/.claude/skills/plan-build/SKILL.md ~/.claude/skills/plan-build-architect/SKILL.md ``` Canonical sources are `SKILL.md` and `ARCHITECT.md`. ## Standalone Constraints - Support Zsh on macOS, Ubuntu, and WSL. - Do not source user shell configuration. - Keep helpers in the `_plan_build_` namespace. - Keep external command and interaction boundaries replaceable. - Keep tests network-free and prevent real agent launches. - Remain safely sourceable and run main only when executed directly. - Preserve the three-file immutable cache release contract. ## Acceptance Criteria - Default, prompt-enhanced, permissive, architect resume, and architect-new modes have command coverage. - Removed options, invalid combinations, duplicates, and empty payloads are covered. - Stable project IDs are validated and reach Claude's environment. - AgentMemory success, degraded approval, and rejection paths are covered without network access. - Recall requirements appear in standard and architect launch prompts. - Common preflight happens before payload input. - Prompt enhancement cannot launch Claude without approval. - `--yolo` reaches Claude only as `--dangerously-skip-permissions`. - Syntax checks, command tests, and `git diff --check` pass.