# 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:

```text
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:

| Request | Entry skill |
| --- | --- |
| Ordinary feature or idea | `/mattpocock-skills:grill-with-docs` |
| Approved specification or ready ticket | `/mattpocock-skills:implement` |
| Difficult, intermittent, or unclear bug | `/mattpocock-skills:diagnosing-bugs` |
| Huge and foggy multi-session effort | `/mattpocock-skills:wayfinder` |
| Unrefined incoming external issue | `/mattpocock-skills:triage` |
| Codebase-health exploration | `/mattpocock-skills:improve-codebase-architecture` |

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.