Mp Implement

Matt Pocock Implementation Pipeline (v2 — Workflow-engined)

You are running the full Matt Pocock engineering methodology against a user-provided PRD or design doc: input → canonical PRD → vertical slices → merged code. Stop ONLY at the numbered HITL checkpoints — everything else proceeds AFK.

> v2: Phase 3 now runs on the native Workflow runtime (deterministic orchestration, structured-output agents, dependency waves with parallel slices, resume). Lifecycle discipline (run manifest, register-before-dispatch, scoped cleanup) absorbed from deepseek-mp-implement. If the Workflow tool is unavailable in the current harness, Phase 3 falls back to the original /subagent-driven-development engine — everything else in this skill still applies, including the manifest and cleanup protocol.

Relationship to upstream mattpocock/skills

This pipeline is the AFK compression of Matt's human-driven chain: grill-with-docs → to-spec → to-tickets → implement → code-review. Upstream deliberately stays small, composable, and human-driven; this skill inlines those disciplines rather than invoking the user-invoked skills at runtime, and hands back to the human at the HITL checkpoints (consistent with upstream's user-invoked/model-invoked rule). The AFK orchestration here — waves, run manifest, worktrees, dual review gates, verify gate — is deliberately local; upstream intentionally does not provide it. Synced against upstream v1.1.0 (2026-07).

Input

One argument: a file path (path/to/feature.md), an issue tracker reference (#42, a GitHub/GitLab URL), or .scratch//PRD.md. If no argument, ask which PRD/design to operate on, then read it fully.

Persistence (goal-like harness)

You do NOT stop at the end of each phase. You stop only at HITL checkpoints; once a checkpoint resolves, resume without asking. The pipeline runs until all AFK slices are merged or you hit a blocker you cannot resolve. Loops are expected (diagnose → fix → re-verify). Drive forward.

HITL checkpoints at a glance (defined inline at each phase): 1 setup missing · 2 input too sparse · 3 CONTEXT.md sparse · 4 slice approval + merge policy · 5 ambiguity / ADR conflict / test red after 2 honest attempts · 6 load-bearing interface change · 7 stalled run that won't stop, or cleanup resistance · 8 architecture candidates. Between these: drive forward without asking.

Pipeline

[Phase 0]   Setup verification          ──→ HITL 1 if repo not configured
[Phase 0.5] Canonicalize input → PRD    ──→ HITL 2 only if input too sparse
[Phase 1]   Domain alignment             ──→ HITL 3 if CONTEXT.md sparse
[Phase 2]   Decomposition + merge policy ──→ HITL 4 on slice approval
[Phase 3]   Wave-based implementation    ──→ AFK loop until all slices merged
   │  engine = Workflow tool, one run per dependency wave
   │  (see ./phase3-workflow.md for script template, schemas, prompts)
   ├─ 3.0 pre-flight: baseline check, run manifest, worktrees, waves
   ├─ 3.1 dispatch wave  → per slice: implement (TDD) → spec review loop
   │                       → multi-lens quality review loop → verify gate
   ├─ 3.2 harvest results → push / PR / merge per policy; handle BLOCKED
   ├─ 3.3 per-wave cleanup → next wave
   └─ 3.F final sweep (manifest closed out, 0 orphaned worktrees)
[Phase 4]   Closing hygiene              ──→ HITL 8 on arch candidates

After Phase 0.5, every later phase operates on the canonical PRD on the issue tracker — the original input file becomes a reference, not the source of truth.

---

Phase 0 — Setup verification (one-time per repo)

Check whether /setup-matt-pocock-skills has been run — its marker is the ## Agent skills block it writes into CLAUDE.md or AGENTS.md:

grep -l "## Agent skills" CLAUDE.md AGENTS.md 2>/dev/null

If missing → HITL CHECKPOINT 1: "Setup hasn't been run in this repo. Running /setup-matt-pocock-skills first — needs your input on issue tracker / triage labels / domain doc layout. Proceed?" Wait, then invoke it.

If present → resolve doc locations via the block's ### Issue tracker / ### Triage labels / ### Domain docs pointers — they are authoritative; don't assume docs/agents/ paths. The tracker may be GitLab (glab), not just GitHub (gh). Read the tracker doc, label vocabulary, and domain layout it names. A missing triage-labels.md means triage isn't installed — fall back to the canonical default label set (ready-for-agent et al.). Proceed.

Phase 0.5 — Canonicalize input into a PRD

Read the input fully. Classify:

1. Already canonical (Problem Statement, Solution, numbered User Stories, Implementation Decisions, Testing Decisions, Out of Scope — AND lives on the tracker) → skip to Phase 1.
2. Canonical but local-only → publish to tracker as-is with ready-for-agent label. Phase 1.
3. Substantive but non-canonical (design doc, feature brief, meeting notes with clear intent) → synthesize with /to-spec discipline: explore the relevant code, sketch the test seams first — prefer existing seams, the fewest possible, the ideal one — then write the canonical PRD. Do NOT interview the user.
4. Foggy AND too big for one session (greenfield / huge feature, destination not yet statable) → HITL CHECKPOINT 2: offer /wayfinder first — a HITL planning layer on the tracker; once its decision tickets clear the fog, hand back here and continue with case 3.
5. Merely sparse (vague intent, no concrete stories) → HITL CHECKPOINT 2: offer /grill-with-docs (~10-20 min interview, also updates CONTEXT.md/ADRs) or let the user expand the doc themselves. Grilling rule: facts the agent looks up in the codebase itself; decisions go to the human one at a time — never act until the human confirms shared understanding. After grilling, fall through to case 3.

First make one quick breadth-first pass over the input — if it surfaces no fog, skip grilling and go straight to case 3.

Publish (cases 2, 3, 5): per the tracker doc from Phase 0, ready-for-agent label, title in CONTEXT.md vocabulary. If the original was a tracker issue, link it as "Supersedes" — never modify or close the original. If the original was a local file, leave it as-is but add a one-line pointer at its top to where the canonical PRD now lives. Then show the user the link + 3-line summary (title, # stories, # out-of-scope) plus the proposed test seams, and ask to proceed — a light confirmation to catch mis-synthesis and wrong seams before code gets written, not a full grilling.

Phase 1 — Domain alignment

Read CONTEXT.md (or CONTEXT-MAP.md + per-context files). If sparse for this PRD's area → HITL CHECKPOINT 3: offer /grill-with-docs to build the shared language (same rule: facts the agent looks up; decisions to the human, one at a time). If adequate → silent pass; note the terms you'll use everywhere. Read docs/adr/ for decisions constraining the approach. If the PRD's approach contradicts an ADR, surface it explicitly BEFORE Phase 2 — don't let it first collide with HITL 5 mid-execution; mark it: Contradicts ADR-0007 (event-sourced orders) — but worth reopening because….

Phase 2 — Decomposition + merge policy

Apply /to-tickets discipline: break the PRD into vertical-slice tracer-bullet issues in dependency order. Prefactor first — "Make the change easy, then make the easy change": when warranted, a prefactor slice goes first. Per slice: Title (CONTEXT.md vocabulary), Type (HITL or AFK — prefer AFK; a slice is HITL only if it can resolve exclusively through live human exchange — taste, sign-off, manual operations — and the agent never stands in for the human's side), Blocked by, User stories covered, Acceptance criteria. Avoid specific file paths or code snippets — they go stale fast (exception: a decision-encoding snippet from a prototype).

Wide-refactor exception: when one mechanical change's blast radius spans the repo so no vertical slice can land green (e.g. renaming a column used everywhere), slice by expand–contract instead — expand (new form beside old) blocks migrate batches (sized by blast radius, CI green between batches) which block contract (remove old form). If batches can't individually stay green, use a shared integration branch with a final integrate-and-verify slice (compatible with merge policy (b)).

HITL CHECKPOINT 4 (mandatory): present the numbered breakdown and ask:

• Granularity right? Blocking edges correct — does each ticket only depend on tickets that genuinely gate it (related ≠ blocking; this directly determines wave width)? HITL/AFK markings right? Merge or split any?
• Merge policy (one-time decision for Phase 3): (a) auto-merge — controller merges each PR once both reviews + verification pass; fully AFK across waves (default for solo repos), or (b) await human review — PRs stack up, issues move to "awaiting human review", dependent waves branch off predecessor branches instead of main. Say explicitly when offering (a): it means no human sees any PR before it lands — the user must waive that knowingly, not by rubber-stamping the slice list.

Iterate until approved. Publish slices as tracker issues in dependency order (so "Blocked by" references real IDs). Where the tracker supports it, use NATIVE sub-issues for slice→PRD parenting and NATIVE blocking edges for "Blocked by" (GitHub: issue dependencies via gh api; GitLab: the /blocked_by quick action — resolve via the tracker doc); ## Parent / ## Blocked by body sections are the documented fallback. Local-markdown trackers keep per-slice files in dependency order. Apply ready-for-agent to AFK slices.

Phase 3 — Wave-based implementation (AFK loop)

You are the controller; you never implement in your own context. Implementation, reviews, and verification run as Workflow agents with isolated context and structured outputs. The full script template, JSON schemas, and prompt construction live in ./phase3-workflow.md — use them; do not improvise the script from memory.

3.0 Pre-flight (controller, once)

1. Baseline gate — run the project's test/lint/typecheck on the base branch now. Never start a wave from a broken baseline; fix or HITL first.
2. Run manifest — create .claude/mp-run-.md, the authoritative registry of everything this run creates:

# MP Run Manifest
Repo:  · Base:  · PRD:  · Created: 
Merge policy: auto-merge | await-review

| Slice | Wave | Branch | Worktree | Status | PR | Cleaned |
|-------|------|--------|----------|--------|----|---------|
| #42   | 1    | feat/x | .worktrees/feat-x | ready | #51 | ✓ |

Status flow: registered → dispatched → READY|BLOCKED|…STUCK|VERIFY_FAILED → merged|deferred → cleaned.

1. Slice briefs — for each AFK slice, assemble a self-contained brief: full issue body + comments verbatim, relevant CONTEXT.md terms, constraining ADRs, test commands, scene-setting (where it fits). Workflow agents cannot reach back into this session or be asked questions mid-run — anything missing becomes a BLOCKED result, so front-load everything.
2. Waves (maximize width — this is the whole point of the engine) — topologically sort slices by "Blocked by"; every slice whose dependencies are satisfied goes into the next wave and runs in parallel. Default to the WIDEST wave: dependency-independent slices belong in the same wave even when they touch overlapping files. The bar for serializing two same-wave slices is a real edit collision at region granularity, NOT mere file overlap:

• Collision (serialize): both slices would edit the same region of a file — same function, same block, adjacent lines — such that parallel branches stomp each other's logic or produce a non-trivial merge conflict.
• No collision (keep parallel): two slices touch different regions of a shared hub file — different event types in one watcher, different fold sections in one Svelte component, different exports in a barrel, append-only additions to an allowlist/test file. These do NOT force serialization; the per-branch merge resolves as a union at harvest (3.2): merge one PR, then union-resolve the other's conflict on the shared file. That is the expected pattern, not an exception.

File-level disjointness was the old, too-strict heuristic; in mature codebases almost every slice grazes a few hub files (the live component, the watcher, the allowlist, the shared test), so file-level checking collapses every wave to one slice and wastes the parallel engine entirely. Judge at region/function granularity instead. When genuinely uncertain whether two slices collide, prefer the wider wave and let the integration review (3.F) catch cross-slice drift — a needlessly-serialized run is the more common and more expensive failure here. Only a true same-region collision, or a real "Blocked by" dependency, justifies splitting into separate waves.

1. Worktrees (register before dispatch) — for each slice in the wave: git worktree add .worktrees/ -b (ensure .worktrees/ is in .git/info/exclude; if the repo already has a worktree convention via /using-git-worktrees, follow it instead). Then run project setup inside the worktree (install dependencies — a fresh worktree has no node_modules/venv) and confirm the test suite runs green there: never hand an agent an unbuildable workspace, or its first failure surfaces as a misleading BLOCKED. Record path + branch in the manifest BEFORE the wave launches. No manifest entry, no dispatch.

3.1 Dispatch the wave

Invoke the Workflow tool with the script from ./phase3-workflow.md, passing args = { repo, baseBranch, testCommands, maxFixRounds, timestamp, slices: [...] } (timestamp is mandatory — workflow scripts cannot read the clock). Per slice the script runs: TDD implementer → spec-compliance review loop → multi-lens quality review loop → verification gate, all with structured outputs. Update manifest entries to dispatched. Note the returned runId and script path in the manifest — they are your resume handle.

Interrupted or stopped run? Re-invoke with {scriptPath, resumeFromRunId} — completed agents replay from cache; only unfinished work re-runs. Never restart a wave from scratch when a resume handle exists. Lost the handle (crash between dispatch and noting it)? Recover the runId from /workflows first; only with no recoverable handle anywhere may a wave be re-dispatched fresh. Stalled (no progress in /workflows for ~30 min)? TaskStop the explicit runId from the manifest, then resume; if it won't stop or stalls again → HITL CHECKPOINT 7. Never stop a runId that isn't in this run's manifest.

Harvest when the wave returns — not mid-run; READY inside a running wave is cached work, not lost work.

3.2 Harvest results (controller)

The workflow returns one structured outcome per slice. When a wave ran wide and two READY slices touched different regions of a shared hub file, merge them sequentially with union resolution: merge the first PR, then resolve the second's conflict on the shared file as a union (keep both regions) before merging. Resolve per resolving-merge-conflicts: read BOTH slices' commit messages and brief intents first (primary sources — the manifest has them), resolve hunk by hunk preserving both intents, never invent new behavior, never --abort. Re-run that slice's verify gate after resolution so the merged state is proven, not assumed. This is routine, not a failure; it is the price of the wider wave and is far cheaper than serializing the whole wave.

| Outcome | Action | |---------|--------| | READY | NOT auto-mergeable yet. First read implStatus + concerns: correctness/scope concerns (DONE_WITH_CONCERNS) get a fix dispatch or HITL 5 before merge — never merge concerns unread. Non-empty lensGaps → a review dimension never ran; jud

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skywalkercyt
• Source: skywalkercyt/mp-implement
• License: MIT

Install and usage instructions live in the source repository linked above.