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.

AgentMemory Contract

This repository's stable AgentMemory identity is stored in .agentmemory-project. The same committed value must be used across clones, worktrees, Claude Code, and Codex.

Authority

Current Git, approved issues/specifications, repository documentation, and ADRs override recalled memory. The workflow_status slot is the current handoff checkpoint. Verified durable memories and raw observations follow it in that order.

Active Checkpoint

Maintain exactly one project-scoped slot named workflow_status. Replace it at approvals, phase changes, blocked states, verification milestones, commits, and session end. Record what is complete, in flight, blocked or unverified, and exactly one next step.

Durable Memory

Save approved architectural decisions, rejected alternatives, non-obvious constraints, verified recurring bug fixes, deployment or migration gotchas, important module relationships, and durable preferences. Search before saving and store one idea at a time with rationale and relevant files.

Do not explicitly save routine output, temporary progress outside the checkpoint, unverified hypotheses, generated content, credentials, personal data, or production data.

Availability

If AgentMemory preflight fails, plan-build asks the interactive user to retry, continue in explicitly degraded mode, or stop. A non-interactive failure stops. Degraded sessions must report that previous context was not restored.

Plan Build Architect Workflow

Use this workflow only when plan_build --architect launches Claude Code. Claude is the lead architect, documentation manager, task dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit is the required automated reviewer.

AgentMemory is the continuity layer for Claude and Codex. Git and approved workflow documents remain authoritative when memory conflicts with current evidence.

Non-Negotiable Role Boundary

Claude may inspect every project file but may create or modify only:

• SPEC.md
• TASKS.md
• ADR.md
• CHANGELOG.md
• README.md
• Markdown files under docs/

Claude must not write application code, test code, migrations, generated source, or executable configuration. Delegate those changes to Codex through an approved task prompt.

Codex must not commit, stage, push, reset, restore, or discard changes. All approved work remains uncommitted until the complete delivery passes final verification and the user approves one final commit.

Never push automatically.

Startup Preflight

Before discovery or project-file modification:

1. Confirm the current directory is a Git worktree.
2. Record git status --short and preserve all pre-existing work.
3. Confirm an interactive terminal is available.
4. Confirm codex, coderabbit, and git are available.
5. Confirm .agentmemory-project matches AGENTMEMORY_PROJECT_NAME and that memory tools are available unless the launcher recorded explicitly approved degraded mode.
6. Run the mandatory memory recall gate below.
7. Inspect project instructions, manifests, existing documentation, tests, CI, and nearby implementation patterns.
8. Never request or expose credential values. Use approved credential integrations when authentication is required.

If a requirement is missing, stop with exact remediation guidance.

Mandatory Memory Recall

Initialize a session-local memory mode from PLAN_BUILD_MEMORY_MODE. Accept only required or degraded; abort preflight if it is missing or invalid. Before existing-workflow detection, run this gate unless that local mode is degraded:

1. Read the project-scoped workflow_status slot. Create it with project scope if it is absent.
2. Recall the active requirement, prior architecture decisions, rejected alternatives, unresolved questions, previous task outcomes, relevant file history, and reusable lessons.
3. Reject memories from another project and verify high-impact memories before relying on them.
4. Reconcile memory with Git, SPEC.md, TASKS.md, ADR.md, CHANGELOG.md, CONTEXT.md, and the issue tracker. Those current artifacts win every conflict.
5. Present the loaded previous case: active work, completed milestone, blocker or unresolved decision, and recorded next step.

Maintain exactly one workflow_status slot containing phase, active work and source, completed milestone, in-flight work, blockers, pending decisions, relevant files, last verification, next step, and update time. Replace it after every approval gate, task transition, blocked state, final verification, and before every session end. When the session-local memory mode is degraded, skip memory calls, report that continuity is unavailable, and never claim recall succeeded. If a required memory call fails after preflight, ask whether to retry, continue this session in explicitly degraded mode, or stop. On approval, set the session-local mode to degraded; never degrade silently.

Existing Workflow Detection

If SPEC.md, TASKS.md, ADR.md, or CHANGELOG.md exists:

1. Read all existing workflow records.
2. Compare their claims with Git and the current worktree.
3. Identify the first incomplete or inconsistent task.
4. Present the detected state and ask whether to resume.

When the launch instruction says Start mode: archive-and-start-new, archive existing workflow documents in a timestamped documentation archive before creating replacements. Never overwrite them silently.

Archive-and-start-new replaces the active workflow_status only after the archive succeeds. It does not delete prior sessions or durable memories; those remain historical evidence and must not be mistaken for approval of the new requirement.

Phase 1: Discovery and Architecture

Interview the user until product, architecture, data, integration, operational, security, and handover requirements are clear.

Rules:

• Ask exactly one question at a time.
• Include a recommended default answer with every question.
• Resolve facts from the repository instead of asking the user.
• Ask the user only for decisions, priorities, business rules, and information that cannot be discovered safely.
• Probe user roles, workflows, data structures, API or component contracts, technology constraints, integrations, edge cases, failure modes, migration, rollback, testing, deployment, monitoring, security, compliance, support, and ownership.
• Collect project name, client or owner, purpose, target users, repository scope, supported environments, deployment owner, operational owner, support role, compliance constraints, and intended handover date.
• Do not implement or dispatch Codex during discovery.

Do not enter Phase 2 until the user explicitly states either:

• I am ready to generate the spec
• Phase 1 complete

Phase 2: Specification

After the explicit Phase 1 completion phrase:

1. Ask no more discovery questions.
2. Create or reconcile SPEC.md without discarding valid existing content.
3. Include executive summary and goals, architecture and technology, data models or durable state schemas, API or component contracts, edge cases, constraints, testing strategy, out-of-scope items, and definition of done.
4. Use Mermaid for applicable system context, component, deployment, and critical sequence diagrams.
5. Mark non-applicable sections with a factual rationale instead of inventing behavior.
6. Treat the approved specification as the requirements baseline.
7. Present the specification and wait for explicit approval.

Any later requirement change is a visible amendment. Pause execution, assess affected tasks and documents, record architectural changes in ADR.md, and obtain approval before continuing.

Phase 3: Codex Task Plan

After SPEC.md approval, create or reconcile TASKS.md.

Use stable task IDs such as TASK-001. Allowed states are:

• Pending
• In Progress
• Blocked
• Review
• Complete

Only one task may be In Progress.

Every task must include:

• ID, title, status, and dependencies
• Objective
• Exhaustive allowed file scope
• Context and interfaces
• Self-contained prompt for Codex
• Acceptance criteria
• Unit or integration test requirements
• Verification commands
• CodeRabbit outcome
• Completion evidence

Every Codex prompt must explicitly prohibit commits and out-of-scope edits. Tasks must be atomic, sequential, and small enough for a fresh Codex context.

Every Codex prompt must also include AGENTMEMORY_PROJECT_NAME, the active task and specification references, and a compact checkpoint summary. Require Codex to recall relevant project history independently, reconcile it with current files, and avoid saving speculative findings as durable facts. The launcher environment must be inherited unchanged by Codex.

Present TASKS.md and wait for explicit approval before execution.

Documentation Records

Maintain these root engineering records throughout execution:

• SPEC.md: approved requirements baseline and amendments
• TASKS.md: task state, prompts, reviews, and evidence
• ADR.md: append-only architecture decisions
• CHANGELOG.md: Keep a Changelog-compatible Unreleased entries referencing task IDs
• README.md: product overview, prerequisites, quick start, and configuration

Every ADR uses a stable ID and records status, date, context, decision, alternatives, consequences, and affected components. Keep superseded decisions and link their replacements.

Mandatory Client Handover Package

The following files are mandatory without exception:

• docs/USER_MANUAL.md
• docs/RUNBOOK.md
• docs/API.md
• docs/DEPLOYMENT.md
• docs/SECURITY.md
• docs/HANDOVER.md

Create missing documents and reconcile existing ones. Do not replace valid project-specific content wholesale.

When a document or section is not applicable, retain it and state Not Applicable with a short factual rationale.

Client-facing documents describe the delivered system, not Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless disclosure is contractually required.

Implementation claims must reference relevant source files, configuration, schemas, endpoints, or verified commands. Handover documents include software version or commit SHA, generation date, document owner, and last verification date.

docs/HANDOVER.md must include deliverables, access prerequisites, verified capabilities, limitations, approved deferred risks, support boundaries, warranty assumptions, ownership transfer, and dated acceptance/sign-off placeholders.

Task Execution Loop

For each approved task, in dependency order:

1. Confirm dependencies are Complete.
2. Set exactly that task to In Progress.
3. Record the current Git status and task baseline.
4. Invoke Codex non-interactively in the current worktree with workspace-write access using the exact approved prompt from TASKS.md.
5. Capture Codex's result.
6. Inspect the diff for correctness, approved scope, repository conventions, unrelated changes, and secret exposure.
7. Independently run the task's verification commands.
8. Set the task to Review and run CodeRabbit on the task diff.
9. Investigate every concrete finding.
10. Delegate valid fixes back to Codex within the same task scope.
11. Rerun focused verification and CodeRabbit after substantive fixes.
12. Record commands, results, findings, and completion evidence.
13. Replace workflow_status with the completed milestone, remaining blocker or next task, and verification evidence.
14. Save any verified bug root cause, non-obvious constraint, architecture decision, external-system gotcha, or reusable lesson that should survive this delivery.
15. Report the outcome and wait for user approval before starting the next task.

Use non-interactive Codex execution in this form, adapting only supported sandbox flags to the installed CLI:

codex exec --sandbox workspace-write "<exact approved task prompt>"

Critical, high, and medium CodeRabbit findings block completion. Low-severity findings may be deferred only with user approval and must be recorded in CHANGELOG.md and docs/HANDOVER.md.

Scope Expansion

If Codex reports that required work exceeds the allowed file scope:

1. Do not permit out-of-scope edits.
2. Assess requirement, architecture, dependency, and test impact.
3. Update SPEC.md, TASKS.md, and ADR.md when appropriate.
4. Ask the user to approve the revised scope.
5. Redispatch only after approval.

Failure and Retry Policy

Allow the initial Codex attempt plus at most two focused correction attempts.

If acceptance still fails:

1. Stop the workflow.
2. Mark the task Blocked.
3. Preserve the partial diff.
4. Record diagnostics and attempted fixes in task evidence.
5. Ask whether to revise architecture, scope, or acceptance criteria.
6. Do not start dependent tasks.

If no test framework exists, the first applicable task establishes the smallest project-appropriate validation setup. If automated testing is technically impossible, obtain user approval for explicit manual acceptance steps and record the risk in docs/HANDOVER.md.

Security Rules

• Never include credential values, tokens, private keys, personal data, or production secrets in prompts or documentation.
• Document only secret names, required environment variables, approved storage, ownership, and rotation procedures.
• Use native credential helpers and approved credential stores.
• Run available secret scanning before final completion.
• Treat suspected credentials as blocking findings.
• Never save credentials, tokens, personal data, production data, or unverified hypotheses to AgentMemory.
• Automatic hook capture does not make memory authoritative; verify recalled claims against current artifacts.

Final Review and Single Commit

After every task is Complete:

1. Finish all root engineering records and mandatory handover documents.
2. Run CodeRabbit over the complete uncommitted diff.
3. Delegate valid code or test fixes to Codex under the responsible task scope.
4. Run the complete project lint, type-check, build, and test suite.
5. Confirm the aggregate diff contains only approved changes and preserves pre-existing work.
6. Validate required documents and sections, Markdown structure, links, source references, commands, examples, and Mermaid syntax where tooling is available.
7. Ensure no unresolved TODO, placeholder, or template text remains. Approved limitations belong in docs/HANDOVER.md.
8. Run available secret scanning.
9. Present the complete diff summary, verification evidence, known limitations, and proposed commit message.
10. Wait for explicit user approval.
11. Stage only approved files and create one commit.
12. Replace workflow_status with the final commit, completed work, remaining limitations, and next operational step.
13. Do not push.

Never call the delivery complete when required verification has not run. Report environmental or unrelated failures with evidence.

Changelog

Unreleased

Added

• Standalone executable plan_build.zsh.
• Canonical standard and architect Claude skills.
• Standard Matt, prompt-enhanced Matt, and architect workflows.
• Architect safe-resume and archive-and-start-new launch modes.
• Command-level, network-free Zsh regression tests.
• Dedicated installation, integration, architecture, task, and troubleshooting documentation.
• Memory-aware Matt Pocock routing as the default workflow.
• Stable committed .agentmemory-project identity shared by Claude and Codex.
• AgentMemory server and Claude/Codex plugin preflight with explicit degraded-mode approval.
• Mandatory project recall and one canonical workflow_status checkpoint in standard and architect workflows.

Changed

• Plan-build-specific implementation and documentation now belong to the dedicated plan-build gist rather than the Zsh Setup repository.
• --yolo is translated to Claude Code's --dangerously-skip-permissions argument.
• Active workflow documentation no longer describes removed v2 or distribution modes.
• Prompt enhancement now uses valid, immediately flushed platform script invocations, including util-linux script -e for child-status propagation, and cleans up temporary state and child processes on return or interruption.
• The Zsh Setup cache contract now activates immutable three-file releases through one atomic current symlink and identifies mutable HTTPS HEAD as the update trust boundary.
• Standard planning now follows Matt Pocock's grilling, specification, tracer-ticket, TDD, diagnosis, and wayfinding flows.
• Matt implementation commits are deferred until working-tree review, validation, and explicit user approval.
• Architect mode recalls and reconciles previous state before document-based resume detection and passes the same memory identity to Codex.

Removed

• Dependence on ~/.func and ambient shell functions.
• The obsolete v2 downloader and its former workflow variants.
• The --brainstorm and --writing-plan options and Claude Superpowers dependency.

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:

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:

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:

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:

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:

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:

plan_build
Implement pagination for the audit log.
Preserve existing API compatibility.
EOF

Available modes:

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:

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 -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.

Plan-Build Memory-Aware Matt Workflow

Use this workflow when plan_build hands Claude Code a project request. Matt Pocock's skills provide discovery, specification, ticketing, TDD, and review. AgentMemory restores prior project context across Claude and Codex sessions. Codex and CodeRabbit remain independent reviewers.

Non-Negotiable Rules

• Run from the project root and preserve all pre-existing work.
• Treat Git, the approved issue or specification, CONTEXT.md, and ADRs as authoritative. Memory supplements them and never overrides contradictory current evidence.
• Use the AGENTMEMORY_PROJECT_NAME supplied by the launcher for every memory operation and child Codex process.
• Do not expose or save credentials, tokens, personal data, or production secrets.
• Matt entry skills marked disable-model-invocation require explicit user invocation. Tell the user the exact namespaced slash command and wait for it instead of simulating the skill.
• Override /implement's automatic commit instruction. Keep changes uncommitted until review and validation pass and the user explicitly approves the commit. Never push automatically.

Memory Precedence

Resolve conflicts in this order:

1. Current Git state and the approved issue or specification.
2. Current repository documentation, CONTEXT.md, and ADRs.
3. The project-scoped workflow_status slot.
4. Verified durable memories and lessons.
5. Raw historical observations.

Report conflicts and correct stale memory. Never bend current implementation or requirements to match an old observation.

Mandatory Recall Gate

Run this gate before routing the request, asking discovery questions, or modifying files. Initialize a session-local memory mode from PLAN_BUILD_MEMORY_MODE, accepting only required or degraded. Treat an unset or invalid value as required and fail closed if mandatory recall cannot run. Only a launcher-supplied degraded value or an explicit user approval after a later memory failure may set the local mode to degraded and permit skipping memory calls.

1. Confirm the current project matches AGENTMEMORY_PROJECT_NAME and read .agentmemory-project.
2. Read the project-scoped workflow_status slot with memory_slot_get. If it does not exist, create it with project scope, a 4,000-character limit, and the template below.
3. Redact the request before search. Query only sanitized issue or ticket identifiers and non-sensitive domain terms; remove or reject credentials, tokens, personal data, production data, and other sensitive payload values. Search for related prior bugs, decisions, and lessons, and reject results belonging to another project.
4. After likely files are known, use file history to recover prior changes and gotchas for those files.
5. Verify high-impact memories before relying on them. Never invent context when retrieval is empty.
6. Reconcile recalled state with Git, the tracker, CONTEXT.md, ADRs, and current documentation.
7. Tell the user what previous case was loaded: active work, last completed milestone, unresolved decision or blocker, and recorded next step.

Use this slot shape and replace it at milestones rather than appending an unlimited log:

Phase: <discovery|specification|ticketing|implementation|review|blocked|complete>
Active work: <title and stable issue/spec reference>
Completed: <latest completed milestone>
In flight: <current operation>
Blocked: <blocker or None>
Pending decisions: <decisions or None>
Relevant files: <paths or Unknown>
Last verified: <commands and result or Not run>
Next step: <one concrete action>
Updated: <ISO-8601 timestamp>

When AgentMemory is healthy but no prior state exists, say so and initialize the slot. If any required memory call fails after launcher preflight, ask the user whether to retry, continue this session in explicitly degraded mode, or stop. On approval, record the session-local mode as degraded, skip remaining memory calls, and report the loss of continuity. Do not continue memoryless without that approval and never claim previous context was loaded.

Route Through Matt

After recall, route the request using Matt's /ask-matt model:

Do not triage tickets produced by /mattpocock-skills:to-tickets; they are already agent-ready.

Feature Flow

For an ordinary idea:

1. Ask the user to invoke /mattpocock-skills:grill-with-docs with the payload.
2. Resolve repository facts locally and ask one decision at a time with a recommended answer.
3. Use /mattpocock-skills:research for external facts.
4. For a runnable design question, use /mattpocock-skills:handoff, continue in a fresh prototype session, invoke /mattpocock-skills:prototype, then hand the learned decision back. Do not confuse Matt's file handoff with /agentmemory:handoff, which resumes recorded sessions.
5. Do not implement until the user confirms shared understanding.
6. Update workflow_status after shared understanding and after every later approval gate.

If the work fits one context window, agree on public testing seams, obtain a read-only Codex review of the requirements and seams, then ask the user to invoke /mattpocock-skills:implement in the same session.

If the work needs multiple sessions:

1. Ask the user to invoke /mattpocock-skills:to-spec.
2. Confirm the proposed public testing seams before publishing.
3. Ask the user to invoke /mattpocock-skills:to-tickets.
4. Obtain approval for vertical tracer-bullet tickets and their blocking edges.
5. Run a read-only Codex review of the approved specification and tickets. Resolve valid findings and reapprove material scope changes.
6. Record the specification, ticket frontier, and first unblocked ticket in workflow_status, then stop.
7. Start each unblocked ticket in a fresh plan_build invocation so it gets a clean context plus the mandatory recall gate.

Implementation Flow

For a ready ticket or approved small task:

1. Record the baseline SHA, git status --short, and pre-existing diff.
2. Load the full ticket or specification and verify dependency completion.
3. Recall blocker outcomes, relevant file history, durable decisions, and lessons.
4. Confirm public testing seams with the user before writing tests.
5. Follow /mattpocock-skills:implement and /mattpocock-skills:tdd one red-green vertical slice at a time.
6. Run focused tests and type checking regularly; run the full project validation suite at the end.
7. Update workflow_status when a red test is established, implementation turns green, focused validation passes, full validation passes, review begins, or work becomes blocked.
8. Do not commit when the Matt implementation skill requests it. Continue through plan-build review and explicit approval instead.

Every Codex prompt must include the project ID, active ticket or specification, and checkpoint summary. Require Codex to recall the same project independently and to treat current repository evidence as authoritative. Read-only review prompts must prohibit edits and durable saves of speculative findings.

Review Stack

Review only the intended change against its captured baseline. Capture the startup patch, then use a three-way, patch-aware comparison between HEAD, that baseline, and the current staged, unstaged, and intended untracked files. Preserve and exclude unrelated baseline changes throughout review, approval, and staging. If intended and pre-existing edits overlap in a file or hunk, stop and ask the user instead of subtracting or guessing.

1. Run Matt's two axes in parallel against that filtered intended change: repository Standards and originating Spec. The stock /mattpocock-skills:code-review only compares committed HEAD history, so apply its standards and spec briefs directly to the filtered working tree before the approval commit.
2. Ask Codex for an independent review focused on bugs, regressions, unsafe assumptions, missing tests, and repository fit.
3. Run CodeRabbit on the local change. Investigate every concrete finding.
4. Fix valid findings and repeat affected reviews after substantive changes.
5. Rerun focused validation and the complete suite.
6. Reconstruct the filtered change and confirm final staging contains only approved work, preserves every baseline change, and has no secret exposure.
7. Present the diff summary, validation evidence, known limitations, and proposed commit message.
8. Wait for explicit approval, stage only intended files, create one commit, and do not push.

Durable Memory Writes

Search before saving and store one durable idea at a time with the project ID, rationale, real file paths where relevant, and specific concept tags.

Save durable memory for:

• Approved architecture decisions and rejected alternatives.
• Non-obvious constraints and important module relationships.
• Repeated bugs with verified root causes and fixes.
• Deployment, migration, integration, and external-system gotchas.
• Durable user or team preferences.

Save reusable lessons separately. Do not save routine output, temporary progress outside workflow_status, unverified hypotheses, generated content, or secrets.

Before ending any session, update workflow_status with what is done, in flight, blocked or unverified, and exactly one next step. Automatic hooks capture raw activity; this explicit checkpoint is what makes the next case resumable.

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

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:

AGENTMEMORY_PROJECT_NAME=<committed-id>
AGENTMEMORY_INJECT_CONTEXT=<true unless degraded>
PLAN_BUILD_MEMORY_MODE=<required|degraded>

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

~/.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.

Plan-Build Tasks

Completed

PB-001: Establish the dedicated project boundary

• Extract the executable from Zsh Setup into plan_build.zsh.
• Remove dependencies on ~/.func and unrelated shell helpers.
• Make the executable directly runnable and safely sourceable.

PB-002: Preserve supported workflows

• Preserve standard and prompt-enhancement behavior.
• Preserve architect safe-resume and archive-and-start-new modes.
• Preserve EOF-terminated payload input and interactive enhanced-prompt approval.
• Translate --yolo to Claude Code's real --dangerously-skip-permissions option.
• Keep --v2 rejected through the unknown-option path.

PB-003: Canonicalize skills and documentation

• Publish the standard workflow as SKILL.md.
• Publish the architect workflow as ARCHITECT.md.
• Remove obsolete v2-only and distribution workflow claims from the active standard skill.
• Document installation, prerequisites, cache integration, compatibility, testing, and troubleshooting.

PB-004: Add standalone regression coverage

• Stub external CLIs, Claude launch, Auggie enhancement, and interactive approval.
• Cover all modes, invalid combinations, preflight ordering, safe-resume/new architect prompts, and normal versus bare Git repositories.
• Keep the suite network-free.

PB-005: Replace Superpowers planning with Matt Pocock's workflow

• Make Matt routing the default standard workflow.
• Remove --brainstorm, --writing-plan, and the Superpowers dependency.
• Preserve Auggie prompt enhancement and architect modes.
• Route discovery, specifications, tracer-bullet tickets, TDD, diagnosis, and wayfinding through explicit namespaced Matt skills.
• Override automatic commits with review, validation, and explicit approval.

PB-006: Add AgentMemory continuity

• Require a committed stable .agentmemory-project identity.
• Verify the shared AgentMemory server and Claude/Codex plugins before payload input.
• Allow only an explicitly approved interactive degraded mode when memory is unavailable.
• Pass one memory scope through Claude and inherited Codex processes.
• Require project-scoped recall and one canonical workflow_status checkpoint in both standard and architect skills.
• Add network-free tests for project identity, memory preflight outcomes, recall prompts, and child environment propagation.

Completed outside this repository

ZS-001: Migrate the Zsh Setup launcher

Replace the old in-repository implementation with a thin cached launcher that downloads the canonical executable and skills from the plan-build gist. The Zsh Setup migration now uses immutable complete release directories, a serialized atomic current symlink switch, and skill links through that same release.

Required launcher contract:

zsh <selected-release>/plan_build.zsh "$@"

Required remote files:

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