# plan-build `plan-build` is a standalone Zsh launcher for a memory-aware multi-agent engineering workflow. Claude Code follows Matt Pocock's discovery, specification, ticketing, TDD, and review flows. AgentMemory restores the active project case and related history across fresh Claude and Codex sessions. Codex and CodeRabbit provide independent review. Architect mode keeps Claude documentation-only while Codex performs approved implementation tasks. ## Prerequisites - Zsh - Git and a checked-out Git worktree - Claude Code CLI (`claude`) - OpenAI Codex CLI (`codex`) - CodeRabbit CLI (`coderabbit`) - AgentMemory CLI and a running AgentMemory server - Enabled Claude Code plugins `mattpocock-skills@mattpocock` and `agentmemory@agentmemory` - Enabled Codex plugin `agentmemory@agentmemory` - The installed plan-build skills described below Claude Code safe mode must be disabled because it disables both required plugins. All modes require an interactive terminal. `--prompt` additionally requires Auggie (`auggie`), an authenticated `~/.augment/session.json`, Perl, and the platform `script` utility. ## Agent Setup Start and connect AgentMemory according to its current installation guide. The core wiring is: ```zsh agentmemory agentmemory connect claude-code codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` Install and enable the AgentMemory and Matt Pocock plugins in Claude Code. Verify the shared server before using plan-build: ```zsh agentmemory status claude plugin list codex plugin list ``` No LLM provider is required for continuity. AgentMemory's local embeddings, keyword retrieval, automatic hooks, explicit recall gate, and project-scoped status slot work without LLM compression. ## Plan-Build Installation Install the executable somewhere on `PATH`: ```zsh mkdir -p "$HOME/.local/bin" curl -fsSL \ https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh \ -o "$HOME/.local/bin/plan_build" chmod +x "$HOME/.local/bin/plan_build" ``` Install both plan-build skills: ```zsh mkdir -p \ "$HOME/.claude/skills/plan-build" \ "$HOME/.claude/skills/plan-build-architect" curl -fsSL \ https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md \ -o "$HOME/.claude/skills/plan-build/SKILL.md" curl -fsSL \ https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md \ -o "$HOME/.claude/skills/plan-build-architect/SKILL.md" ``` For production automation, download to a temporary file in the destination directory and rename it atomically after successful validation. ## Project Identity Every target repository must commit a `.agentmemory-project` file containing one stable identifier. The exact grammar is `[A-Za-z0-9][A-Za-z0-9._:/-]{1,127}`: 2-128 characters with no whitespace. Use the normalized remote repository identity when possible: ```text github.com/owner/repository ``` For a repository without a durable remote, use a stable UUID-based value such as `local/550e8400-e29b-41d4-a716-446655440000`. On the first interactive run, plan-build proposes the normalized `origin` URL and creates `.agentmemory-project` after approval. That setup run then stops: commit the file and rerun plan-build. Directory names are deliberately not used because unrelated repositories can share the same basename. A working-tree identity that differs from `HEAD` is rejected. The launcher exports the ID as `AGENTMEMORY_PROJECT_NAME` and enables context injection for Claude except in explicitly degraded mode. Codex inherits the same environment, so both agents use one memory scope across clones and worktrees. ## Usage Run the command in the project to change, enter the payload, then put `EOF` alone on a line: ```zsh plan_build Implement pagination for the audit log. Preserve existing API compatibility. EOF ``` Available modes: ```text plan_build Memory-aware Matt workflow plan_build --prompt Auggie enhancement, approval, then Matt workflow plan_build --yolo Permissive Claude process mode; gates remain active plan_build --architect Memory-aware architect safe resume plan_build --architect --new Archive active documents and start new state plan_build --architect --yolo Architect with permissive Claude process mode ``` `--architect` may combine only with `--new` and `--yolo`; `--new` is invalid without `--architect`. Duplicate and unknown flags fail. Removed `--brainstorm`, `--writing-plan`, and `--v2` options are intentionally unknown. The user-facing `--yolo` option translates to Claude Code's `--dangerously-skip-permissions`. It never bypasses memory, planning, review, or commit approval gates. ## Workflow Except in explicitly degraded mode, every session starts by loading the project-scoped `workflow_status` slot and retrieving related decisions, bugs, lessons, and file history. Claude reconciles this memory with Git, the current issue or specification, `CONTEXT.md`, and ADRs before acting. The default Matt route is: 1. Ordinary ideas enter `/mattpocock-skills:grill-with-docs`. 2. Small approved work continues through `/mattpocock-skills:implement` and TDD in the same context. 3. Multi-session work uses `/mattpocock-skills:to-spec`, then `/mattpocock-skills:to-tickets`. 4. Each unblocked ticket starts in a fresh `plan_build` session and recovers its case through AgentMemory. 5. Hard bugs use `/mattpocock-skills:diagnosing-bugs`; huge foggy efforts use `/mattpocock-skills:wayfinder`. 6. Matt two-axis review, Codex review, CodeRabbit, and complete validation run before an approval-gated commit. Matt's workflow entry skills require explicit invocation. Claude tells the user the exact namespaced command and waits rather than silently approximating it. The standard workflow overrides Matt `/implement`'s automatic commit instruction: plan-build commits only after explicit approval and never pushes automatically. ## Memory Availability AgentMemory captures prompts, tool activity, session boundaries, subagents, compaction, and commits automatically. Plan-build adds an explicit recall and checkpoint protocol because hooks alone fail silently when the server is unavailable. If AgentMemory, its Claude plugin, or its Codex plugin fails preflight, plan-build asks whether to retry, continue in explicitly degraded memoryless mode, or stop. A non-interactive failure stops. Degraded mode is always reported and must never claim previous context was restored. Memory supplements the repository; it does not replace specs, tickets, `CONTEXT.md`, ADRs, tests, or Git. Current approved artifacts win conflicts with old memory. Secrets, personal data, production data, and unverified hypotheses must not be explicitly saved. ## Architect Mode Architect mode recalls the previous case before detecting `SPEC.md`, `TASKS.md`, ADRs, or changelog state. Claude remains documentation-only and passes the same AgentMemory project ID and checkpoint summary to every Codex task. `--architect --new` archives the active workflow documents and replaces the active status slot only after successful archival. Historical sessions and durable memories remain available but do not count as approval for the new requirement. ## Zsh Setup Cache Launcher The Zsh Setup integration downloads this complete release bundle: ```text https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md ``` It stages all three non-empty files, requires `plan_build.zsh` to pass `zsh -n`, moves them into one immutable release directory, and atomically switches a serialized `current` symlink. Failed refreshes leave the previous validated release active. Both internal skill paths are bound to the selected release, so concurrent refreshes cannot mix generations. The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS protects transport but does not pin content, establish provenance, or guarantee that separate requests observed one remote revision. ## Testing The suite is self-contained and never accesses the network or launches real agent CLIs: ```zsh zsh -n plan_build.zsh test_plan_build.zsh zsh test_plan_build.zsh git diff --check ``` ## Troubleshooting - **AgentMemory unavailable:** run `agentmemory status`, start the server, and retry. - **AgentMemory tools missing:** confirm the Claude and Codex plugins are enabled and connected to the same server. - **Matt skills missing:** install or enable `mattpocock-skills@mattpocock` in Claude Code. - **Safe mode blocks plugins:** unset `CLAUDE_CODE_SAFE_MODE`. - **Project ID rejected:** keep `.agentmemory-project` to one valid 2-128 character identifier with no whitespace. - **Auggie cannot authenticate:** run `auggie login` and confirm `~/.augment/session.json` is non-empty. - **Prompt enhancement does not continue:** `--prompt` requires approval for optional indexing and the enhanced prompt. - **Git preflight fails:** run from a checked-out worktree, not a bare repository or `.git` directory. - **Workflow skill missing:** install `SKILL.md` and `ARCHITECT.md` at the exact paths above.