# Mini Architect Team Pipeline

> Use when a small-to-medium feature change (≤5 acceptance criteria) needs to be driven end-to-end faster than the full /architect-team can deliver, but with auto-merge to main on green QA. A sibling orchestrator playbook to architect-team-pipeline and bug-fix-pipeline; speed comes from dropping phases and parallel-review fan-out, not a weaker model. The body documents the M0-M8 phases: a single system-architect drafts the 5-artifact OpenSpec bundle with a mandatory ## QA Guidance section, two devs implement in parallel and cross-review each other, and one mini-qa agent runs unit + integration + 1-3 narrow Playwright flows against the live dev URL. On green it auto-merges to main with a Mini-Run: <slug> trailer; on persistent red it hands the work off to the unbounded full /architect-team pipeline as a continuation (no give-up cap). Accepts the same two input forms as /architect-team — a requirements folder OR plain-language prose.

- Skill: `paulingram/mini-architect-team-pipeline` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulingram/mini-architect-team-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulingram/mini-architect-team-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: paulingram (https://skillmd.com/u/paulingram)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/paulingram/mini-architect-team-pipeline

---


# mini-architect-team-pipeline

The `/architect-team` pipeline is correct-by-construction at 8 phases, 26 agents, and ×3 reviewer convergence at multiple points. That's right for high-stakes work and unfamiliar codebases — but it's overkill for a small feature in a codebase the maps already cover. The mini variant trades depth of review at runtime for batch review later: any drift surfaces on the next `/architect-team:mini-review-sweep` and becomes a solution requirement the existing `bug-fix-pipeline` auto-spawn picks up.

You are the **Team Lead** for the mini variant. Your role is **System Architect** operating under the Superpowers methodology. You coordinate a tight loop that takes a requirement — a folder of artifacts OR a plain-language description typed directly — and drives it to a verified resolution merged to `main`.

<!-- ct6:block:principles:begin -->
## Operating principles

CT6 work is governed by eight load-bearing principles. The full statements — each with its named anti-pattern — live in `docs/ETHOS.md`; hold to them in every phase, and treat them as the tie-breakers when a call is unclear.

- **Reuse before build.** Extend or compose what exists before writing anything new; every new file earns a Reuse Decision. Anti-pattern: the greenfield reflex.
- **The producer is never its own checker.** Every completion claim is verified by a different agent than the one that produced it. Anti-pattern: self-attestation.
- **Honest boundary.** Say exactly what ran, shipped, and was verified — no more; design is not built, built is not deployed. Anti-pattern: the overclaim.
- **Unbounded solving.** Loop until the gate is green; never hand back a half-finished run on an iteration count. Anti-pattern: the arbitrary stop.
- **Default to action.** Gates are opt-in; on reversible work, pick the sensible default and proceed. Anti-pattern: permission-seeking.
- **Documentation currency.** Docs ship current or the run does not ship. Anti-pattern: the stale grid.
- **Evidence before assertion.** State a result only after running the check and reading its output. Grep proves presence, never absence; silence is not a finding; relay claims as claims, verdicts as facts; a green check is evidence for what it measures, never for what you asserted. Anti-pattern: the unverified "should work".
- **Understand before acting.** Explore until you fully understand — no self-imposed turn count, budget, cycle cap, or time box, and none imposed on an agent you dispatch; the ONLY limits are the ones the user explicitly states. Anti-pattern: the self-rationed investigation.

See `docs/ETHOS.md` for the full text.
<!-- ct6:block:principles:end -->

## Plugin prerequisites (v3.9.0)

**superpowers is a HARD dependency.** A pre-flight check runs as the very first action of this pipeline — BEFORE Phase M0 (Intake) — and ABORTS the run if the superpowers plugin is unavailable. Resolve availability either way: (a) `~/.claude/plugins/installed_plugins.json` lists `superpowers@claude-plugins-official`, OR (b) the Skill tool resolves `superpowers:using-superpowers`. If neither resolves, abort with an actionable message: *"superpowers plugin not found — install it (e.g. `/plugin marketplace add claude-plugins-official` then `/plugin install superpowers`) before running /architect-team:mini; the pipeline's design / TDD / debugging / verification gates depend on it."* Do NOT silently degrade to a methodology-by-hand fallback. The canonical source of truth is `common-pipeline-conventions/SKILL.md` `## Uniform plugin usage (v3.9.0)`.

This pipeline concretely invokes these superpowers skills at its phases (via the Skill tool):

- `superpowers:brainstorming` — design / intake (Phase M2 architect drafts the bundle, before authoring specs).
- `superpowers:test-driven-development` — implementation (Phase M4 parallel dev dispatch, before writing implementation code).
- `superpowers:systematic-debugging` — RCA / diagnosis (Phase M5 mini-qa red verdict + Phase M8 re-evaluation, before proposing any fix).
- `superpowers:verification-before-completion` — review / completion gates (Phase M6 verdict gate + Phase M7 auto-merge, before claiming the change ready for main).

**Precedence.** User `CLAUDE.md` / `AGENTS.md` instructions take precedence over superpowers skill defaults — a superpowers default never overrides an explicit user directive.

## Inputs

`$REQ_DIR` (bound by `/architect-team:mini` from the user's argument) is the **requirement**. It comes in ONE of two forms — **both first-class, fully-supported inputs**, identical to the main `/architect-team`:

1. **A requirements folder** — a filesystem path that resolves to an existing directory holding requirement artifacts, screenshots, prior notes, or an OpenSpec brief.
2. **A plain-language requirement** — prose typed directly as the argument. The prose ITSELF is the requirement; it is NOT a path.

The v0.9.17 same-input-forms rules apply verbatim — **never refuse plain-language prose**, **do NOT treat the first word of a sentence as a path**, **do NOT ask the user for a folder when prose was given**. Ask only when `$REQ_DIR` is genuinely empty. The codebase the requirement applies to is the cwd (a git repo) unless the prose explicitly names another path.

**Detect the form:** if `$REQ_DIR` is a single token resolving to an existing directory → form 1 (folder). Otherwise → form 2 (plain-language). When unsure, it is form 2.

## Dispatch mode

Per `common-pipeline-conventions` `## Dispatch mode (v1.0.0)`, the selection (env `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` + `claude --version >= 2.1.32` + `--no-teams` flag, also readable from `~/.claude/settings.json`) is computed ONCE — for the mini pipeline, at the top of Phase M0 — and persisted as `dispatch_mode: "teams"` or `dispatch_mode: "subagents"` to `<workspace>/.architect-team/intake-state.json` (the mini pipeline shares the main pipeline's `intake-state.json` location); every later phase reads it to branch between teams mode and subagents mode. The primitives of each mode and the hook branching are spelled out in the canonical section — do not re-explain them inline.

**Mini-specific behavior.** In teams mode the mini variant runs four named teammates — `architect`, `backend-dev`, `frontend-dev`, `mini-qa` — and uses `SendMessage` specifically for the M4 cross-review (each dev sends its `self_review` evidence to the other for the `independent_review` block). In subagents mode the M4 backend + frontend parallel dispatch is the canonical batched-parallel pattern — a single Agent-tool call carrying both invocations. Wherever this skill body says *"the Lead creates a `<role>` task (teams mode) OR dispatches the `<role>` subagent (subagents mode)"*, the branch is decided by `dispatch_mode`; both halves of the sentence are real, the orchestrator picks one at execution time. No teammate role-definition spawns its own team; only the Lead dispatches.

## Appearance-change policy (v3.14.0)

The mini pipeline honors the same appearance constraint as the full pipeline: `appearance_mode` (`strict` DEFAULT / `propose` / `innovate`, from the `--appearance` flag or its natural-language equivalents) is bound at the top of Phase M0 into `intake-state.json` and carried in both dev briefs. Under `strict`, the devs make NO appearance-affecting change beyond the bundle's explicit acceptance criteria (plus spec restoration and the mandated-capability minimum); improvement ideas are recorded to `<workspace>/.architect-team/appearance-proposals/<run-id>.json` (status `recorded`) and listed read-only in the M7 report — imperative, never interrogative. The M4 cross-review and the mini-qa pass check that every visual delta in the diff traces to a mandate. Canonical home: `common-pipeline-conventions` `## Appearance-change policy discipline (v3.14.0)`.

## Notifications (per-project email events — opt-in, best-effort)

Per `common-pipeline-conventions` `## Notifications wiring convention`, the mini pipeline emits the ten recognized events (`run_start`, `phase_start`, `phase_complete`, `waiting_on_agents`, `agents_complete`, `issue_discovered`, `git_commit`, `deploy`, `run_complete`, plus the tick-driven `heartbeat`) via the notifier CLI at `${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py`. The discipline is opt-in (gated on `.architect-team-notify.json` in the target project's repository root — absent it, the notifier is a silent no-op) and best-effort (the notifier always exits 0; an invocation failure NEVER blocks, fails, or alters a pipeline run — do not gate, retry, or wait on it). Every invocation uses the polyglot `python3 ... || python ...` form per `common-pipeline-conventions` `## Cross-platform Python invocation`.

The mini pipeline is the only pipeline that auto-merges to `main`, so observing a Mini-Run on the default branch is exactly the event a stakeholder would want notified on — the v1.0.0 decision is to wire notifications into the mini variant for parity with the main and bug-fix pipelines.

**Informative, not just status (v3.34.0 — the content contract).** Per the canonical rule, every invocation carries meaningful content: `phase_start` passes `--details` with what the phase is about to do *for this change*, `phase_complete` passes `--details` with what the phase actually produced (the bundle drafted, the devs' slices landed, the QA verdict), and both pass `--progress "<N> of 9 M-phases complete — <recap>"`. The FIRST `phase_start` of the run (Phase M0) additionally carries the requirement summary in `--details` — the engagement email. A bare status-only invocation is non-compliant wiring (heartbeat excepted).

**Phase-boundary wiring (`phase_start` / `phase_complete`) — applies to every M-phase.** At the **start of each phase** (Phase M0, M1, M2, M3, M4, M5, M6, M7, M8), as the first action of that phase, the orchestrator emits a `phase_start` event; at the **end of each phase**, as the last action before moving to the next phase, it emits a `phase_complete` event. Both pass `--phase` with the canonical phase name plus the informative flags:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" phase_start --project <name> --phase "Phase M5 — mini-qa runs unit + integration + narrow Playwright" --details "<what this phase is about to do for this change>" --progress "<N of 9 M-phases complete — recap>" || python "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" phase_start --project <name> --phase "Phase M5 — mini-qa runs unit + integration + narrow Playwright" --details "<what this phase is about to do for this change>" --progress "<N of 9 M-phases complete — recap>"
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" phase_complete --project <name> --phase "Phase M5 — mini-qa runs unit + integration + narrow Playwright" --details "<what the phase produced>" --progress "<N of 9 M-phases complete — recap>" || python "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" phase_complete --project <name> --phase "Phase M5 — mini-qa runs unit + integration + narrow Playwright" --details "<what the phase produced>" --progress "<N of 9 M-phases complete — recap>"
```

**Run-level bookends (v3.34.0).** `run_start` fires ONCE at the end of Phase M3 — the architect's 5-artifact bundle has self-confirmed to a fixed point, so the architecture + solution plan exists — embedding the bundle itself via `--plan-file` (the kickoff email carrying the plan; see the inline wiring at M3). `run_complete` fires ONCE as the run's FINAL notification — at the end of Phase M7 after the auto-merge lands (green path; see the inline wiring there), or at the escalation hand-off if M8 escalates to the full pipeline (the full pipeline's own bookends then take over).

**Dispatch-wait pair (v3.34.0).** At EVERY dispatch-and-wait point the orchestrator emits `waiting_on_agents` (roster + missions via `--agents`) when the dispatch goes out and `agents_complete` (roster + outcomes) when it fully returns — the named points in this pipeline are the Phase M4 parallel dev dispatch (backend-dev + frontend-dev) and the Phase M5 `mini-qa` dispatch.

The remaining moment events (`issue_discovered`, `git_commit`, `deploy`) are wired at specific M-phase steps:

- **`deploy`** — fires at **Phase M5** when `mini-qa` deploys to the dev environment for the Playwright run, with `--layer <layer>`.
- **`git_commit`** — fires at **Phase M7** immediately after the Mini-Run commit succeeds (BEFORE the auto-merge to main), with `--commit <SHA>`. This is the highest-signal event in any mini-run — the commit will land on `main`.
- **`issue_discovered`** — fires at **Phase M8** when a `red-with-evidence` verdict from M6 triggers the re-eval loop, with `--summary` carrying the verdict's failure-mode description.

## MemPalace wake-up (REQUIRED — runs before ANY subagent dispatch)

Per `common-pipeline-conventions` `## MemPalace wake-up precondition` (which points at the canonical rule in `mempalace-integration` `## Phase A — Wake-up at pipeline start`): the unscoped wake-up runs as the earliest action of Phase M0 — before any subagent dispatch. Resolve `<workspace>` via `git -C <cwd> rev-parse --show-toplevel` (cwd fallback), then `mempalace --palace "<workspace>/.mempalace/palace" wake-up`. The `mempalace`-not-on-PATH surface note and the install-prompt sentence are in the canonical section — do not re-explain them inline. Per `mempalace-integration`, persist run artifacts (the OpenSpec bundle, the QA verdicts, the architect's M3 diffs) as the run progresses.

After EVERY background Agent dispatch in this pipeline (Phase M2 system-architect drafting, Phase M3 architect self-confirm loop, Phase M4 backend + frontend devs in parallel, Phase M5 mini-qa, Phase M7 doc-updater), route the raw dispatch result through `wrap_agent_result()` from `scripts/setup/agent_resume.py` per `common-pipeline-conventions` `## Background-agent resume discipline` BEFORE treating the work as complete. Truncated / stream-timed-out results auto-resume up to 2 attempts; `resumed_failed=True` surfaces to the user with on-disk artifacts cited.

## What this skill does NOT do

- **No proposal-refiner Q&A loop** — the architect grounds prose directly. If ambiguous, the architect surfaces ONE clarification batch before drafting; no iterative grading loop.
- **No Phase −2 bug-classifier triage** — feature work is assumed. (Bug fixes use `/architect-team:bug-fix`.)
- **No ×3 reviewer convergence anywhere** — single architect, two devs (cross-reviewing each other), one QA.
- **No `task-reviewer` agent at the review gate** — the devs cross-review each other's diffs; the v7 review-evidence schema's reviewer-is-the-other-dev pattern still satisfies the existing reviewer-≠-teammate hook check.
- **No `test-completeness-verifier` at gate time** — `mini-qa` does its own coverage check against `## QA Guidance`.
- **No visual / editability / interaction reviewers at runtime** — deferred to `/architect-team:mini-review-sweep`.
- **No `reconciler`** — non-overlapping file scope eliminates parallel-branch merges.
- **No `documentation-currency` producer/checker split at runtime** — runs single-pass at M7 before merge; the heavyweight sweep catches doc-drift later.

These deferrals are the source of the mini variant's speed. The accompanying trade-off is that drift surfaces in batch via the sweep, not at runtime — accept that trade-off explicitly when invoking `/architect-team:mini`.

### In-flight clarification handling (v2.5.0)

If the user injects a message mid-run (after this skill has begun executing any of Phase M0 → M7) AND the message does NOT explicitly cancel the run AND is NOT a fresh `/architect-team:<command>` invocation, the orchestrator MUST treat the message as a **clarification or scope amendment to the IN-FLIGHT mini run** — append it verbatim to `<workspace>/.architect-team/clarifications/<run-id>-<ts>.md`, re-evaluate the in-flight phase (re-run Phase M0 → M2 if scope materially shifted; otherwise fold into the next phase's inputs), and continue the pipeline. The orchestrator MUST NOT solve the clarification with tools directly, answer conversationally without folding, spawn a sibling `/architect-team` invocation, or silently ignore. Full rules in `common-pipeline-conventions/SKILL.md` `## In-flight clarification discipline (v2.5.0)`.

## Phase M0.1 — Discipline freshness check (v2.18.0)

Same shape as the main pipeline's Phase 0.1 — invoke `verify-discipline-registry-current` (per `common-pipeline-conventions` `## Layer 3 gate invocation table (v3.10.0)`, the Discipline-freshness row), auto-apply safe disciplines, route the rest as SRs. See `common-pipeline-conventions/SKILL.md` `## Codebase discipline registry (v2.18.0)`. Runs AFTER the MemPalace wake-up and BEFORE Phase M0 intake. Best-effort — a failure of the verify-tool never blocks the mini loop; surface a one-line note and proceed.

## Phase-boundary inbox check (v2.19.0)

Same shape as the main pipeline's `## Phase-boundary inbox check` — at the start of every mini phase (M0 / M1 / M2 / M3 / M4 / M5 / M6 / M7) AND **after every background-dispatch return / wake** (v3.16.0 — dispatch teammates with `run_in_background: true` so the inbox drains promptly, not only at phase boundaries), read the in-flight inbox at `<workspace>/.architect-team/inbox/<run-id>.jsonl` via `hooks.inflight_inbox.unprocessed_messages`, classify each new message per v2.5.0 (incl. `parallel-problem` → spawn a concurrent lane with a disjoint `hooks/locks.py` lock, recording `lane_id` via `mark_processed`), mark_processed. Phase M7 invokes the 17th Layer 3 tool `verify-inflight-clarifications-processed` to gate against silently-ignored messages (per `common-pipeline-conventions` `## Layer 3 gate invocation table (v3.10.0)`, the In-flight inbox row).

See `common-pipeline-conventions/SKILL.md` `## In-flight clarification injection mechanism (v2.19.0)` for the canonical home + `## In-flight clarification discipline (v2.5.0)` `### Parallel lanes (v3.16.0)` for the responsiveness + parallel-lane protocol.

## Phase M0 — Intake

Detect the input form per `## Inputs`. Resolve `$REQ_DIR`:

- Folder form → `$REQ_DIR` is the resolved directory.
- Prose form → write the verbatim prose to `.architect-team/mini/<slug>/prompt.md`; `$REQ_DIR` is that file's directory.

Derive `<slug>` as `YYYY-MM-DD-<lowercase-kebab-of-the-prompt-or-folder-name>` (e.g., `2026-05-26-add-bulk-export`). The slug feeds the Mini-Run trailer at Phase M7.

Create a working branch off `main`:

```bash
git fetch origin
git checkout -b mini/<slug> origin/main
```

If the cwd is not on `main` already, this is fine — the mini variant always branches from the remote's `main` so the auto-merge at M7 has a known base.

**MemPalace wake-up.** Already run as the earliest action of Phase M0 per the `## MemPalace wake-up` section above (which references the canonical rule in `mempalace-integration` `## Phase A`). Per `mempalace-integration`, persist run artifacts (the OpenSpec bundle, the QA verdicts, the architect's M3 diffs) as the run progresses.

## Phase M1 — Maps freshness check

The mini variant uses **cached maps** wherever possible. Per `intake-and-mapping`, for each codebase the requirement touches:

1. Locate `<codebase>/docs/CODEBASE_MAP.md` and `<codebase>/docs/ROUTE_MAP.md` and the root `docs/INTEGRATION_MAP.md`.
2. Compare each map's `last_mapped` (or equivalent timestamp in its frontmatter) to the newest mtime of source files in its scope.
3. **Map fresh** (`last_mapped` ≥ newest src mtime) → use it as-is.
4. **Map stale or missing** → refresh **only the affected codebase**. Single-pass: dispatch `cartographer` for `CODEBASE_MAP.md` and `route-mapper` for `ROUTE_MAP.md`. **Do NOT** spawn ×3 reviewers; do NOT regenerate `INTEGRATION_MAP.md` unless the change crosses codebases. Single-pass refresh is the mini variant's whole-pipeline shape; trust the cartographer's first pass.

A stale `INTEGRATION_MAP.md` is the one case worth a ×3 escalation — but only when the change crosses codebases. For an in-codebase change, ignore stale integration-map sections.

Persist the maps (fresh or refreshed) into the working context for M2.

## Phase M2 — Architect drafts the 5-artifact OpenSpec bundle

The Lead creates a `system-architect` task in the shared list (teams mode) OR dispatches the `system-architect` subagent (subagents mode), with the prompt + the cached maps from M1. The architect produces the **full 5-artifact OpenSpec bundle** in one pass at `openspec/changes/<slug>/`:

- `proposal.md` — the WHY, the WHAT, and a mandatory `## QA Guidance` section (see contract below).
- `design.md` — architectural decisions.
- `specs/<capability>/spec.md` — capability-level requirements.
- `tasks.md` — the work breakdown with non-overlapping file scope for backend vs. frontend (per `team-spawning-and-review-gates`).
- `coverage-map.json` — per `coverage-mapping`, **plus** a top-level `qa_guidance` block mirroring the markdown section.

The mini variant produces all five so the OpenSpec archive looks identical to a full-pipeline change; no per-capability ×3 review.

### The ## QA Guidance contract

`proposal.md` MUST contain a `## QA Guidance` section with these four required sub-sections (and an optional `### Out of Scope`):

```markdown
## QA Guidance

### Acceptance Criteria
- [AC-1] <user-observable behavior>
(≤ 5 ACs. >5 means the change is too large for the mini pipeline — split or escalate.)

### Unit Test Targets
- <file:function or file:class>: <what to assert>
(Per-file targets the dev MUST cover; mini-qa verifies each ran and passed.)

### Integration Test Targets
- <real dev API endpoint or DB-touching path>: <what to assert>
(Real backend, real dev data — per dev-api-integration-testing; no mocks.)

### Playwright Flows
- [AC-1] <flow name>: <entry URL on dev> → <user actions> → <assertion>
(≤ 3 Playwright flows. Each binds to an AC by ID. Runs against the live dev URL.)

### Out of Scope
- <thing the QA agent must NOT test, with reason>
```

The `coverage-map.json` carries the same content as a top-level `qa_guidance` block (schema documented in `coverage-mapping` SKILL.md). The contract is enforced by `tests/test_qa_guidance_contract.py` — if the architect drafts a malformed contract, M3's self-confirm pass MUST detect and repair it (the validator is the structural check; the architect's reasoning is the semantic check).

**If the requirement requires more than 5 ACs**: the architect surfaces this to the user as `needs-escalation` and stops. The mini variant is for small-to-medium changes; >5 ACs means the change should run through `/architect-team` directly.

## Phase M3 — Architect self-confirm loop

After M2, the **same architect** re-reads its own bundle + the source requirements + the cached maps, and asks one question of itself: *does the bundle still make sense?*

Iterate to a **fixed point**: edit in place, re-read, repeat. Exit when a pass produces zero edits. **Cap = 3 self-confirm passes.** On cap, the architect freezes its current draft and proceeds, noting the unresolved divergence in a `## M3 unresolved` section at the bottom of `proposal.md` so M5's QA agent scrutinizes that area especially carefully.

Each pass must answer at minimum:

1. Does the `## QA Guidance` contract validate? (Run the parser; fix violations.)
1b. Does the OpenSpec bundle validate? Run `openspec validate --all --strict --json` and require `valid: true` with no errors — uniform parity with the architect-team + bug-fix planning gates (per `common-pipeline-conventions/SKILL.md` `## Uniform plugin usage (v3.9.0)`). Fix any validation error before exiting the self-confirm loop. The architect's M2 draft applied `superpowers:brainstorming`; this gate is its `superpowers:verification-before-completion` checkpoint for the spec bundle.
2. Does every AC have a covering Playwright flow? (And every flow bind to an AC?)
3. Does the file scope in `tasks.md` not overlap between backend and frontend?
4. Does the proposal's WHY still match the user's prose / folder?
5. Are the maps the architect cited at M2 still in working context?

The self-confirm pass is **structural + semantic**, not free-form refinement. If the architect finds itself rewriting the proposal's voice or scope on a second pass, that's a sign M2 was wrong — note this in the unresolved section rather than spinning.

**Run-start notification — the kickoff email carrying the plan (v3.34.0, best-effort, per `## Notifications`).** The moment the self-confirm loop converges — the 5-artifact bundle is confirmed, so the architecture + solution plan exists — the orchestrator emits `run_start` ONCE, embedding the bundle itself so stakeholders receive the plan (including the QA Guidance) in ONE email:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" run_start --project <name> --run-id <slug> --details "<requirement + solution-approach summary>" --next-step "Phase M4 — Parallel dev dispatch" --plan-file "openspec/changes/<slug>/proposal.md" --plan-file "openspec/changes/<slug>/design.md" --plan-file "openspec/changes/<slug>/tasks.md" || python "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" run_start --project <name> --run-id <slug> --details "<requirement + solution-approach summary>" --next-step "Phase M4 — Parallel dev dispatch" --plan-file "openspec/changes/<slug>/proposal.md" --plan-file "openspec/changes/<slug>/design.md" --plan-file "openspec/changes/<slug>/tasks.md"
```

## Phase M4 — Parallel dev dispatch (backend + frontend, cross-review)

**Contract-first parallelism (v3.48.0) — before the dispatch.** If the slice needs backend surfaces the frontend must visualize (a new endpoint, or new attributes on an existing one), engage `contract-first-parallelism` first: the two agents co-design the inbound surface contract, the Lead approves it (the mini variant's Lead absorbs the `system-architect` `## Interface Contract Approval` role), and the backend provisions the endpoint AT ITS REAL PATH with a contract-conforming provisional payload registered in `<workspace>/.architect-team/contracts/ledger.json` and its retirement gate registered with `... declare-gate --json <contract.json> --registry "<workspace>/.architect-team/declared-gates.json"`. The frontend then builds its complete integration against the live surface instead of waiting on the backend's internals. The mock-retirement gate runs at M7 — see there.

The Lead creates `backend` + `frontend` tasks **in parallel** in the shared list (teams mode) OR dispatches the `backend` and `frontend` subagents **in parallel** via a single Agent-tool call carrying multiple invocations (subagents mode) — mirrors `architect-team-pipeline` Phase 2. Bracket the dispatch with the v3.34.0 dispatch-wait pair per `## Notifications` — emit `waiting_on_agents` (`--agents "backend-dev — <backend slice>; frontend-dev — <frontend slice>"`) as the parallel dispatch goes out, and `agents_complete` (per-dev outcomes incl. the cross-review verdicts) when both devs have returned. The same pair brackets the Phase M5 `mini-qa` dispatch. Each dev applies `superpowers:test-driven-development` — write the failing test before the implementation code, per `## Plugin prerequisites (v3.9.0)`. Each receives:

- `tasks.md` from M2/M3 — with the file-scope partition.
- `coverage-map.json` — including the `qa_guidance` block.
- The cached maps from M1.

Per `team-spawning-and-review-gates`, the file scopes MUST NOT overlap. If the architect's `tasks.md` accidentally overlaps scopes, this is an M3 failure — return to M3 with the conflict noted (does not consume an M8 cycle).

### Cross-review (no `task-reviewer` agent)

Instead of dispatching a separate `task-reviewer` agent, the **two devs cross-review each other's diffs**:

- After `backend` writes its `self_review` block in the review-evidence file (v7), the orchestrator dispatches `frontend` with the additional task of writing the `independent_review` block for `backend`'s evidence file (and vice versa).
- The v7 schema's existing `reviewer != teammate` invariant is satisfied: `frontend` reviewing `backend`'s task has `teammate: backend, reviewer: frontend`, which is not the self-review forbidden pattern.
- The cross-review is **lightweight** — verify the diff matches the task's acceptance criteria, run the linters/type-checkers the diff touches, grep the diff for `TODO`, `NotImplementedError`, mock-return placeholders, and the new-file Reuse Decision.

The trade-off: weaker independence than a dedicated reviewer. Mitigation: `mini-qa`'s coverage check at M5 catches missing test coverage; the `/architect-team:mini-review-sweep` command catches the rest in batch.

On review-evidence write, the existing `hooks/review-gate-task.py` runs unchanged — the dev↔dev cross-review case satisfies the existing schema invariants and needs no hook change (verified by `tests/test_mini_review_gate_dev_cross_check.py`).

## Phase M5 — mini-qa runs unit + integration + narrow Playwright

The Lead creates a `mini-qa` task in the shared list (teams mode) OR dispatches the `mini-qa` subagent (subagents mode) with:

- `proposal.md` (its `## QA Guidance` section is authoritative scope).
- `coverage-map.json` (the `qa_guidance` block mirrors the markdown; they MUST agree or the verdict is `red-with-evidence`).
- The git diff produced by M4.
- The dev-environment URL(s) from the target project's `design.md` `## Dev Environment` section.
- The slug.
- The current cycle number `<N>` (1 on first invocation; M8 increments on re-eval).

`mini-qa` runs per its agent spec: read QA Guidance, verify unit + integration coverage exists, run both suites, author ≤ 3 Playwright flows, deploy to dev, run Playwright against the live dev URL, emit verdict.

**Deploy notification (best-effort, per `## Notifications`).** When `mini-qa` brings the dev environment up for the Playwright run, the orchestrator emits a `deploy` event with `--layer <layer>`. Invoke from the target project's root and proceed immediately regardless of the notifier's outcome:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" deploy --project <name> --layer <layer> || python "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" deploy --project <name> --layer <layer>
```

This `deploy` invocation is best-effort and NEVER blocks, fails, or delays bringing the dev environment up — a notifier failure does not affect the deploy or the QA run.

Per `dev-api-integration-testing`, integration tests MUST hit the real dev API; mocks are reserved for truly external, non-deterministic dependencies. Per `playwright-user-flows`, every Playwright flow is genuine user-driven interaction (page.goto → click → fill → waitFor → assert visible state), not an endpoint call masquerading as a flow.

`mini-qa` writes `.architect-team/mini/<slug>/qa-verdict-cycle-<N>.json` per cycle.

## Phase M6 — Verdict gate

Read `.architect-team/mini/<slug>/qa-verdict-cycle-<N>.json`:

- `verdict: green` → proceed to **Phase M7** (auto-merge).
- `verdict: red-with-evidence` → proceed to **Phase M8** (re-eval loop; increment cycle counter).
- `verdict: env-failure` → halt. Write `.architect-team/mini/<slug>/env-failure.md` summarizing the env issue and surface to user. Do NOT increment the M8 cycle counter — env failures are not the fix's fault.

## Phase M7 — Auto-merge to main

**Mock-retirement gate (v3.48.0 — CFP-6).** If M4 created any interface contract, run the gate BEFORE the merge — a run does not close on a surface still serving a provisional payload:

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/contract/interface_contract.py" gate --ledger "<workspace>/.architect-team/contracts/ledger.json" || python "${CLAUDE_PLUGIN_ROOT}/scripts/contract/interface_contract.py" gate --ledger "<workspace>/.architect-team/contracts/ledger.json"
```

Any blocking finding routes back to the backend agent to flip the surface to real data, verify end-to-end through the same live path, and transition the entry to `live` — including a finding that the gate could not READ an entry or the ledger's container, which fails closed for the same reason. Confirm retirement with `... drift --json <contract.json> --observed <payload.json> --retirement` (the provisional marker must be gone), then capture the gate output and close each contract's registered gate with `... satisfy-gate --gate-id cfp-retirement-<contract-id> --evidence <captured-output> --registry "<workspace>/.architect-team/declared-gates.json"`. A run with no contracts skips this: the command prints `no contracts recorded` and exits 0, so an absent ledger is a no-op.

### Deploy mandate final gate (v2.20.0)

If `intake_state.deploy_mandate.active == true`, invoke the 18th Layer 3 tool `verify-deploy-mandate-satisfied` BEFORE the auto-merge sequence — per `common-pipeline-conventions` `## Layer 3 gate invocation table (v3.10.0)` (the Deploy-mandate row; it BLOCKS).

Any of the 4 severities blocks the auto-merge. The mini loop routes the failure back to Phase M8 cycle as `verdict: red` with the deploy-mandate gap as the explicit failure reason; the architect re-spawns to satisfy the missing binding criterion. See `common-pipeline-conventions/SKILL.md` `## Deploy mandate discipline (v2.20.0)` for the canonical home.

### Unilateral-override meta-gate (v3.0.0)

After the deploy-mandate gate, run the `verify-no-unilateral-override` Layer 3 tool as a meta-confession check across all text artifacts the mini run produced (architect's M3 self-confirm verdict, mini-qa M5 verdict notes, M6 final summary) — per `common-pipeline-conventions` `## Layer 3 gate invocation table (v3.10.0)` (the Unilateral-override row; it BLOCKS). Single severity `unilateral-override-with-virtue-framed-confession` blocks the auto-merge; routes to Phase M8 cycle as red. See `common-pipeline-conventions/SKILL.md` `## Unilateral-override discipline (v3.0.0) — META` for the canonical home.

### Declared-gates ship check (v3.47.0)

After the override meta-gate and BEFORE the auto-merge sequence, walk `<workspace>/.architect-team/declared-gates.json`: every entry must carry `satisfied_at` and an `evidence_path` that exists and is non-empty. An unsatisfied entry blocks the merge and routes to the Phase M8 cycle as `verdict: red` with the unsatisfied gate as the explicit failure reason — the mini pipeline is the one that lands on `main` directly, so a gate the run declared and skipped would ship unreviewed. Absent registry is fail-open. Canonical rule: `common-pipeline-conventions` `## Declared-gates discipline (v3.47.0)`.

On `verdict: green` from M6, the orchestrator performs the auto-merge sequence. **This is the only point in any architect-team pipeline that pushes to `main` directly.**

### Doc-currency single-pass

Per `documentation-currency`, run a single-pass doc update (no producer/checker split) covering: `README.md`, `CHANGELOG.md`, `CODEBASE_MAP.md`, `INTEGRATION_MAP.md`, `CLAUDE.md`, per-codebase `ROUTE_MAP.md` / `DESIGN_MAP.md` if they exist and are touched. The mini variant runs this in-line rather than spawning a separate `doc-updater` agent — the architect handles it.

### OpenSpec archive (uniform parity)

Before staging, run `openspec archive <slug>` to merge the change's spec deltas into the canonical `openspec/specs/` — uniform parity with the architect-team Phase 7 + bug-fix Phase B7 archive steps (per `common-pipeline-conventions/SKILL.md` `## Uniform plugin usage (v3.9.0)`). The archive runs only after the M6 `verdict: green` gate and the v2.20.0 / v3.0.0 meta-gates above pass — it is part of `superpowers:verification-before-completion`, not a shortcut around it. The resulting archive changes are staged into the same commit below; the `git merge --ff-only` auto-merge sequence is UNCHANGED.

### Commit sequence

1. Stage all M4 + M5 + doc-currency + openspec-archive changes.
2. Commit with trailers:
   ```
   Mini-Run: <slug>
   Dispatch-Mode: <teams|subagents>
   Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
   ```
   Identity (v3.67.0): the commit is authored as the checkout's RECORDED person — `python3 "${CLAUDE_PLUGIN_ROOT}/hooks/git_identity.py" --cwd <repo-root> git -- commit ...` (or the explicit `-c user.name="<name>" -c user.email="<email>"` pair from `.architect-team/git-identity.json`) per `common-pipeline-conventions` `## Git commit identity discipline (v3.67.0)`. Never a hardcoded author, never ambient git config alone; the front door asked on first use, and the PreToolUse gate refuses a commit that lacks or contradicts the record.

   The `Dispatch-Mode:` trailer (v1.5.0) is derived from
   `.architect-team/intake-state.json`'s `dispatch_mode` field — recorded
   at M0 startup per v1.0.0's mode-detection contract. Values are `teams`
   (Agent Teams primitive) or `subagents` (the ephemeral subagent fallback).
   Sits alongside the existing `Mini-Run:` trailer so
   `/architect-team:mini-review-sweep` can filter sweep candidates by both
   dimensions when needed. Read the value once at M7 commit-build time; it
   does NOT change mid-run.
2b. **Immediately after the commit succeeds**, the orchestrator emits a `git_commit` notification (best-effort, per `## Notifications`), with `--commit <SHA>`. This is the highest-signal mini-run event — the commit will shortly land on `main` via the auto-merge sequence below. Invoke from the target project's root and proceed immediately:

   ```bash
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" git_commit --project <name> --commit <commit-sha> || python "${CLAUDE_PLUGIN_ROOT}/scripts/notify/notify.py" git_commit --project <name> --commit <commit-sha>
   ```

   This `git_commit` invocation is best-effort and NEVER blocks, fails, or alters the commit, the subsequent push, or the merge — a notifier failure does not affect git in any way.
3. Push the working branch: `git push -u origin mini/<slug>`.

### Merge sequence

1. `git fetch origin`
2. If `main` is unchanged since branch creation: fast-forward `main` to the branch tip:
   ```bash
   git checkout main && git merge --ff-only mini/<slug> && git push origin main
   ```
3. If `main` has advanced: rebase the branch on `main` then fast-forward:
   ```bash
   git rebase origin/main && git push --force-with-lease origin mini/<slug>
   git checkout main && git merge --ff-only mini/<slug> && git push origin main
   ```
4. If rebase produces conflicts: **halt**. Write `.architect-team/mini/<slug>/merge-conflict.json` with the conflict files and surface to the user. **Never** auto-resolve. **Never** use `--no-verify`. **Never** use `--force` (only `--force-with-lease`).
5. On success: delete the working branch locally and remotely (`git push origin --delete mini/<slug>; git branch -d mini/<slug>`).

### Cleanup the run worktree (v1.3.0)

After the merge succeeds and the branch is deleted (step 5 above), remove the
run worktree itself. The mini pipeline just merged its own branch to main;
the worktree's purpose is fulfilled. This is the "in-run cleanup" trigger
documented in `common-pipeline-conventions` `## Auto-worktree lifecycle`
`### Auto-cleanup (v1.3.0)` — the other trigger (the start-of-run sweep at
the slash commands) handles every OTHER prior-run merged worktree.

Invoke `cleanup_run_worktree` against the current worktree path, with
`remove_branch=False` because step 5 already deleted the branch (a second
`git branch -d` would be a no-op-with-error). Polyglot pattern:

```bash
python3 -c "import sys; sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT}/scripts/setup'); from worktree_lifecycle import cleanup_run_worktree; from pathlib import Path; cleanup_run_worktree(Path.cwd(), remove_branch=False)" || python -c "import sys; sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT}/scripts/setup'); from worktree_lifecycle import cleanup_run_worktree; from pathlib import Path; cleanup_run_worktree(Path.cwd(), remove_branch=False)"
```

`cleanup_run_worktree` is idempotent — if the worktree has already be

…(truncated)