# Maestro

> Use at the start of every task — master orchestrator that classifies work, routes it to the right domain pack (engineering, documents, brand, marketing, social, finance, small business, legal, leadership) and the right model tier (Opus by default, Fable reserved for adjudication), fetches live docs via Context7, gates frontend work behind an anti-template design mockup, enforces layered security (OWASP + edit scanning + supply-chain skill vetting), verifies visually via Playwright, reviews deeply before and after the PR, and orchestrates superpowers skills in the correct order

- Skill: `impravin22/maestro` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add impravin22/maestro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impravin22/maestro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: impravin22 (https://skillmd.com/u/impravin22)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/impravin22/maestro

---


# Maestro — Master Orchestrator

A single unified workflow for every task. Classify, gather context, plan, implement, verify, ship.

<HARD-GATE>
You MUST run through this orchestration flow at the start of every task. No exceptions. No shortcuts. Speed is never an excuse to skip discipline.
</HARD-GATE>

## Ecosystem

**Required:** superpowers (workflow skills), Context7 MCP (live docs).

Everything else is optional and degrades gracefully — a missing pack never blocks a task. Install commands, per-pack caveats, and degradation rules live in `references/ecosystem.md`. **Read that file only when a pack you need is missing, or the user asks how to install one** — never routinely.

| Consumed at | Packs |
| --- | --- |
| Step 1 CLASSIFY | claude-mem (prior observations) |
| Step 2 CONTEXT7 | Context7 MCP; LightRAG (very large repos) |
| Step 5 UI/UX | frontend-design, ui-ux-pro-max, taste-skill, transitions-dev |
| Step 6 SECURITY | security-guidance (edit-time hook) |
| Step 7 IMPLEMENT | example-skills (mcp-builder, skill-creator), Everything Claude Code, karpathy-skills |
| Step 8 VERIFY | playwright MCP, example-skills (webapp-testing) |
| Step 8.5 REVIEW | pr-review-toolkit, skillspector |
| Domain deliverables | see Domain Routing below |

## Domain Routing

Engineering is the default domain and runs the full flow below. When the task is a **non-code deliverable**, CLASSIFY names the domain and routes to its pack:

| Task is about | Domain | Pack |
| --- | --- | --- |
| Copy, SEO, CRO, launches, ads, email, pricing pages | marketing | `marketing-skills` (50) |
| Posts, threads, reels, thumbnails, content calendars | social | `social-media-skills` (17) |
| Statements, reconciliation, close, audit, variance | finance | `finance` (8) |
| Cash flow, payroll, invoicing, CRM and customer ops | small-business | `small-business` (31) |
| Contracts, NDAs, compliance, legal risk | legal | `legal` (9) |
| Jira tickets, status roll-ups, exec updates, impact write-ups, 1:1s, performance reviews, opportunity scans | leadership | `atlassian` + `pm-*` (installed) + `leadership-skills`, `pm-product-discovery`, `c-level-skills`, `pm-claude-skills` (pinned) |
| Artefacts, long-form docs, office files | documents | `example-skills`, `document-skills` |
| Brand compliance, internal announcements | brand | `example-skills` |
| Code, tests, infra, MCP servers, skill authoring | engineering | superpowers + the flow below |

Routing to a non-engineering domain? **Read `references/skill-pack-registry.md`** — it carries the shortened Deliverable flow, each pack's gates, and its caveats. Engineering tasks skip it entirely. **Mixed tasks split:** the engineering flow owns the repo diff, the Deliverable flow owns the non-code half, and each half passes its own gates.

## Model Routing

**`opus` by default; `fable` for security adjudication, review arbitration, and high-stakes domain judgement.** Tier aliases, not pinned versions.

A blind head-to-head (2026-07-29) could not separate the two on architecture, planning, or root-cause analysis, so those run on `opus`. `fable` is reserved for the three rows that experiment did not measure and whose failure cost is asymmetric: security adjudication, final review arbitration, and high-stakes domain judgement.

Pass `model:` per dispatch (Agent tool, workflow `agent()`, agent frontmatter); N generators on `opus`, the single adjudicator on `fable`. The main-conversation model is user-selected — recommend a tier at CLASSIFY, then proceed regardless.

Full table, escalation rules, fallback, and cost discipline: `references/model-routing.md`.

## Unified Flow

Every task follows this flow. Steps are skipped only when explicitly not applicable.

```
 1. CLASSIFY     → Determine task type, scope, domain pack, and model tier
 2. CONTEXT7     → Detect libraries → fetch current docs
 3. BRAINSTORM   → Invoke superpowers:brainstorming
 4. PLAN         → Invoke superpowers:writing-plans
 5. UI/UX GATE   → Generate design mockup → run design system checklist
 6. SECURITY     → Run OWASP + LLM security checklist
 7. IMPLEMENT    → Invoke superpowers:test-driven-development
 8. VERIFY       → Invoke superpowers:verification-before-completion
 8.5 LOCAL REVIEW → Run code-reviewer (and security-reviewer if sensitive) on local diff
 9. FINISH       → Invoke superpowers:finishing-a-development-branch
10. REVIEW       → PR review loop until clean approval
```

---

## Step 1: CLASSIFY

Determine the task type and scope before doing anything else.

**Ask yourself:**
- What type of task is this? (feature, bug fix, refactor, config change, documentation, UI-only)
- What parts of the codebase are affected? (frontend, backend, full-stack, infrastructure)
- Is this trivial (one-line config, comment fix) or non-trivial?
- Are there libraries/frameworks involved that I need current docs for?
- Which **domain** does this belong to? (engineering by default; documents, brand, marketing, social media, finance, small business, legal, or leadership when a domain pack from the Skill Pack Registry applies — non-code deliverables take the Deliverable flow)
- Which **model tier** fits each phase? (consult Model Routing: `opus` unless the step is security adjudication, review arbitration, or high-stakes domain judgement)

**Output:** A one-line classification statement, e.g.:
> "Feature: full-stack — adding OKR alignment suggestions. Involves: Next.js (frontend), FastAPI + DSPy (backend). Non-trivial. Domain: engineering. Model: opus throughout; fable only if Step 8.5 turns up a security verdict to adjudicate."

**Ledger:** for non-trivial engineering tasks, create `.maestro/evidence-<date>-<task-slug>.md` now, recording the classification, skip row, supply-chain flag, and model tier — later steps re-read these from the file, never from memory. Format, the stable-key rule, and read-back points: `references/evidence-ledger.md`. Skipped on the trivial row and the Deliverable flow.

**Memory-assisted classification (if claude-mem is available):**

Before locking in the classification, query prior observations to avoid re-deriving context that already exists:

1. Call the `search` MCP tool with keywords from the user's request (feature name, affected file paths, library names)
2. Call `timeline` for the affected project path if recent activity may be relevant
3. Weave any high-signal prior observations into the classification statement — surfacing the **raw observation text** (no paraphrasing) so the user can eyeball relevance. Example: "Feature: full-stack OKR alignment suggestions. Prior observation (2026-03-20): user rejected a DSPy-based retriever due to 4× latency — favour cached retrieval."

If claude-mem is unavailable, skip this substep and proceed with the classification from the user's current request alone.

**Skip logic determined here:**

| Classification | Steps to Skip |
|---------------|---------------|
| Trivial config/docs change (see Supply-chain trigger below — a `SKILL.md`, plugin-manifest, or MCP-config edit is never trivial) | Skip 3–6 and 8.5, go straight to 7 (implement without TDD ceremony) |
| No frontend touched | Skip 5 (UI/UX gate + design mockup), skip visual verification in 8 |
| Component-level frontend tweak (className change, copy edit, prop rename) | Skip 5a–5c (mockup) and 5d (UI UX Pro Max refinement), still run 5e (checklist) |
| Bug fix | Step 3 becomes `superpowers:systematic-debugging` instead of brainstorming |
| No libraries detected | Skip 2 (no Context7 calls) |
| Independent subtasks identified | Step 7 can use `superpowers:dispatching-parallel-agents` |
| No dev server running | Skip visual verification (Playwright) in step 8 |
| No new types introduced | Skip `type-design-analyzer` in step 10 |
| No comments added/modified | Skip `comment-analyzer` in step 10 |
| Non-code deliverable (marketing, social, finance, small-business, legal, or leadership content/analysis with no repo diff) | Run the **Deliverable flow** (see Skill Pack Registry): skip 5, 7 (TDD), 8.5, 9, 10; Step 6 only if credentials/customer data/PII are handled; Step 7 becomes DRAFT with the domain pack's skills; Step 8 Evidence Gate + domain gate still run |

**Supply-chain trigger:** if the task is *authoring, installing, or updating a skill, plugin, or MCP server* — i.e. the diff will touch a `SKILL.md`, a plugin manifest, or an MCP server config — flag it here. **Step 8.5** then runs the SkillSpector supply-chain scan on the changed artefact before the PR. This is orthogonal to the code-review agents: it vets the *skill supply chain* (malicious instructions, prompt injection, agent-config snooping, MCP rug-pull, excessive agency), a surface ordinary code review does not cover. It does **not** fire on normal app-code diffs. It **overrides** the "Trivial config/docs change" row above for every gate that row skips, Step 6 included: a `SKILL.md`, plugin-manifest, or MCP-config edit is never "trivial" for gate purposes, however small the diff. The security checklist's prompt-injection, excessive-agency and supply-chain rows apply to exactly these diffs, so Step 6 runs too.

---

## Step 2: CONTEXT7 — Fetch Live Documentation

**Purpose:** Ensure you plan and code against *current* API documentation, not stale training data.

**Process:**

1. From the classification, identify all libraries/frameworks involved in this task
2. For each library, resolve its Context7 ID:
   - Use Context7's `resolve-library-id` tool (or `ctx7 library <name>`)
3. For each resolved library, fetch relevant documentation:
   - Use Context7's `query-docs` tool with a query specific to the current task
   - Focus the query on the APIs/features you'll actually use, not the entire library
4. Hold the fetched docs in context — they inform brainstorming, planning, and implementation

**Example:**
```
Task: "Add server-side pagination to the OKR list endpoint"
Libraries detected: FastAPI, SQLAlchemy, TanStack Query
→ resolve-library-id("fastapi") → fetch docs for "pagination query parameters"
→ resolve-library-id("sqlalchemy") → fetch docs for "limit offset pagination"
→ resolve-library-id("tanstack-query") → fetch docs for "useInfiniteQuery pagination"
```

**If Context7 is unavailable:** Note it and proceed — do not block the workflow. Use your training knowledge but flag that docs were not verified against the latest version.

**Optional supplement for very large codebases — LightRAG (if installed and wired via an MCP bridge):** For repos where Context7's scope is too narrow (e.g., proprietary frameworks, niche internal APIs), a running `lightrag-server` instance can provide a graph+vector RAG layer. No off-the-shelf MCP bridge ships with maestro: the user must run `lightrag-server` and either query its REST API directly (via a scratch MCP shim) or use it outside the Claude Code loop. Treat LightRAG as an optional *external* service, not as a drop-in Context7 replacement.

---

## Step 3: BRAINSTORM

Invoke `superpowers:brainstorming` to explore the idea before committing to an approach.

**Maestro additions on top of brainstorming:**
- Reference the Context7 docs fetched in step 2 when evaluating approaches
- Ensure every proposed approach includes a **solution justification**:
  1. Why this approach is best
  2. At least 2 alternatives considered
  3. Why each alternative was rejected (concrete downsides)
  4. Trade-offs of the chosen approach acknowledged upfront
- Apply **self-critique**: after designing a solution, find at least 2 weaknesses before presenting
- Perform **impact analysis**: what WILL this change? What WON'T? What could break?
- **Memory lookup (if claude-mem available)** — before proposing approaches, call `get_observations` scoped to similar prior work (same library, same feature area). Surface any rejected approaches and their concrete failure reasons. Do not re-propose a previously rejected approach unless the rejection reason no longer applies (state why explicitly).

**For bug fixes:** Replace this step with `superpowers:systematic-debugging` — diagnose the root cause before proposing any fix.

---

## Step 4: PLAN

Invoke `superpowers:writing-plans` to create a detailed implementation plan.

**Maestro additions on top of planning:**
- The plan must reference specific APIs from the Context7 docs (not guessed signatures)
- If frontend work is included, the plan must note which UI/UX checklist items apply
- If security-sensitive (auth, input handling, LLM calls), the plan must note which security checklist items apply
- Every plan must include a testing strategy section
- Every plan task names its verification command and expected success marker; copy these into the evidence ledger as pre-registered gates before Step 7 starts — the oracle is fixed before implementation, not chosen after to fit the result
- **Plan reuse (if claude-mem available)** — call `search` for prior plans with similar scope (e.g., "pagination endpoint", "OKR checkin migration"). If a close structural match exists, reuse the proven plan skeleton and cite the prior plan in the justification — do not duplicate planning work the user has already approved.

---

## Step 5: UI/UX GATE & DESIGN MOCKUP

**Skip if:** No frontend files are touched.

**Trigger taxonomy** (see `references/frontend-design-trigger.md` for the full decision matrix):

| Frontend change type | 5a–5c Mockup? | 5e Checklist? |
|---|---|---|
| New surface (page, route, major component) | **Yes** | Yes |
| Significant redesign (layout shift, new states, new interaction model) | **Yes** | Yes |
| Style refresh of existing surface (palette, typography, spacing) | **Yes** | Yes |
| New variant of existing component (new size/intent of an existing button, card, modal) | **Yes** (light — sketch is enough) | Yes |
| Component-level tweak (className change, copy edit, prop rename, prop drilling fix) | No | Yes |
| Bug fix without visual change | No | Yes |
| A11y-only fix (add aria-label, fix focus order, fix contrast) | No | Yes |
| Test-only change (Vitest, Playwright, or Storybook coverage with no UI change) | No | No |

If the table says "Yes" in column **5a–5c Mockup**, you MUST run substeps 5a–5c **before** Step 6. Do not proceed to SECURITY or IMPLEMENT until the user has approved the mockup.

If the change type is not in the table or is ambiguous, default to **Yes** (run the mockup gate). The user can override with "skip the mockup, just code it" — but the default must be safe.

---

### 5a. Generate design direction

Invoke the `frontend-design` skill (a light sketch suffices for **new variants of existing components**) to produce a concrete design direction. Output **must** include all of:

- **Style direction** — pick exactly one from a worthwhile list and justify it. Worthwhile: editorial / magazine, neo-brutalism, glassmorphism with real depth, light or dark luxury, bento, scrollytelling, 3D integration, Swiss / international, retro-futurism. **Banned as a "direction":** "clean minimal", "modern", "professional", "simple", "elegant". These are non-directions and produce template output.
- **Palette** — concrete tokens (oklch / hex), not vague colour names. Reference the project's existing tokens before introducing new ones.
- **Typography pairing** — specific families, weights, and the type scale.
- **Layout strategy** — grid, bento, sidebar+canvas, scrollytelling, magazine, asymmetric. **Banned default:** centred single-column max-w-md card with icon → headline → body → CTA → secondary link. That is the canonical generic template; if the proposed layout looks like that, reject and re-pick.
- **Motion language** — what motion clarifies (hierarchy, state change, focus) vs. what it distracts from. Respect `prefers-reduced-motion: reduce`.

**Optional direction voices (if installed):** Taste can contribute direction candidates, Transitions the motion language. Both are **additive only** — their output still faces the anti-template ban below, the required-qualities check, and the 5c gate. Neither replaces `frontend-design` as the direction generator.

**Anti-template ban — these are forbidden in the output:**

- Default card grids with uniform spacing and no hierarchy
- Stock hero section: centred headline, gradient blob, generic CTA
- Unmodified Tailwind / shadcn / Material / Bootstrap defaults passed off as finished design
- Flat layouts with no layering, depth, or motion
- Uniform radius, spacing, and shadows across every component
- Safe gray-on-white styling with one decorative accent colour
- Dashboard-by-numbers: sidebar + uniform cards + generic charts with no point of view
- Default font stacks used without a deliberate reason

**Required qualities — output must demonstrate at least four:**

1. Clear hierarchy through scale contrast
2. Intentional rhythm in spacing, not uniform padding everywhere
3. Depth or layering through overlap, shadows, surfaces, or motion
4. Typography with character and a real pairing strategy
5. Colour used semantically, not just decoratively
6. Hover, focus, and active states that feel designed
7. Grid-breaking editorial or bento composition where appropriate
8. Texture, grain, or atmosphere when it fits the visual direction
9. Motion that clarifies flow instead of distracting from it
10. Data visualisation treated as part of the design system, not an afterthought

Reference at least 2 real precedents (existing pages in the same product, or external products like Linear, Vercel, Stripe, Apple Newsroom, NYT Cooking, Things 3, etc.) and explain **what specifically** you are borrowing from each — not just "Linear" but "Linear's command-bar density and keyboard hint chips".

Before moving to 5b, **self-audit**: open the design direction and ask "could a 2018 admin template ship this?" If yes, re-pick. If no, proceed.

### 5b. Generate mockup artefact

Produce a tangible artefact the user can eyeball **before** any production code is written. Pick the lightest form that conveys the design:

| Artefact | When to use | Where it lives |
|---|---|---|
| HTML prototype (single file, Tailwind via CDN) | New surfaces, redesigns, exploration | `proposed-*.html` in repo root or `docs/mockups/` |
| Annotated component sketch in markdown | Small new components | Inline in the plan |
| Existing-page screenshot + redline overlay | Refreshes of existing pages | Attached to the plan |
| Storybook story (if Storybook is configured) | Component-level work | Storybook's tree |

The mockup must show: hero state, loading state, empty state, error state, and at least one responsive breakpoint. **No placeholder lorem ipsum** — use realistic copy from the actual product domain.

**Pre-approval self-check (run before presenting to user):**

- [ ] Does the mockup avoid looking like a default Tailwind / shadcn / Material template?
- [ ] Are hover, focus, and active states drawn or specified — not implicit defaults?
- [ ] Is hierarchy expressed through scale contrast rather than uniform emphasis?
- [ ] Would this look believable in a real product screenshot, side-by-side with Linear, Vercel, Stripe?
- [ ] If the artefact supports both themes, do both light and dark feel deliberate?
- [ ] Does at least one element break the predictable grid (asymmetry, overlap, sidecar, marquee, etc.)?

If any of the first four checkboxes is "no", **regenerate the mockup before going to 5c**. Do not present a mockup that fails these checks.

### 5c. Mockup approval gate

Present the mockup to the user. Wait for explicit approval (`yes` / `go on` / `approved`). Iterate on feedback **without** writing production code.

**Do not skip this gate** even if the design feels obvious. If the user is in caveman mode and replies "yes", that is sufficient — but the gate must still be hit.

### 5d. UI UX Pro Max refinement (if installed)

If UI UX Pro Max is installed, invoke it to refine palette and typography against the direction approved in 5c. Treat its suggestions as **additive** — the user has already approved the direction in 5c, so UI UX Pro Max can suggest refinements (different palette token, better font pairing, tweaked spacing scale) but **cannot override the approved direction**. If UI UX Pro Max recommends a fundamental direction change, surface it to the user explicitly ("UI UX Pro Max suggests switching from editorial to brutalist because X. Stick with editorial, or pivot?") and wait for an answer.

The maestro checklist in 5e remains the canonical gate (accessibility, responsive, loading/error states, etc.). Do not let UI UX Pro Max override checklist-level accessibility or state-coverage requirements.

### 5e. Run UI/UX checklist against the approved mockup

Read and run through `references/uiux-checklist.md` against the approved mockup (not against your imagination of the final UI).

**This is not optional for frontend work.** Every frontend change that alters rendered output, even "just a small tweak", gets checked against the design system; test-only changes are exempt per the trigger matrix.

**Key enforcement areas:**
- **Visual Design** — Tailwind tokens, spacing scale, typography, colour palette, dark mode
- **Accessibility (WCAG 2.1 AA)** — keyboard nav, focus, contrast, ARIA, semantic HTML, motion, touch targets
- **Component Patterns** — shadcn/ui, composition, loading/error/empty states, responsive
- **Performance** — CLS, image optimisation, client component boundaries, bundle impact

Flag any checklist violations against the mockup, fix the mockup, re-confirm with the user, then proceed to Step 6.

---

## Step 6: SECURITY

Read and run through `references/security-checklist.md` against the planned changes.

**This applies to every task that touches:**
- API endpoints or middleware
- User input handling
- Database queries
- LLM calls (input sanitisation, output scanning)
- Authentication or authorisation
- File uploads or external data processing

Flag any checklist violations in the plan and resolve them before proceeding to implementation.

### Layered Defence with Security Guidance

Maestro provides **two layers** of security enforcement:

1. **Planning-time** (this step) — the security checklist catches architectural and design-level security issues *before* code is written
2. **Edit-time** (Security Guidance plugin) — a post-edit hook that automatically scans every code change for common vulnerability patterns as it lands

**If the Security Guidance plugin is installed**, it runs automatically on every file edit. It detects:
- Command injection (`os.system()`, `subprocess` with shell=True, `child_process.exec()`)
- Code injection (`eval()`, `Function()` constructor, `vm.runInNewContext()`)
- XSS vectors (`dangerouslySetInnerHTML`, unsanitised template literals)
- Insecure deserialisation (`pickle.loads()`, `yaml.load()` without SafeLoader)
- Hardcoded secrets (API keys, tokens, passwords in source code)

When a vulnerability is detected, the hook shows a warning with remediation advice after the edit lands: re-read the flagged file and remediate before continuing the TDD loop. This catches issues that pass checklist review but appear during implementation.

**If the Security Guidance plugin is not installed:** This step still functions via the checklist alone. Note the missing plugin in your response so the user can install it for automated post-edit protection.

---

## Step 7: IMPLEMENT

Invoke `superpowers:test-driven-development` to write tests first, then implementation.

**Maestro additions on top of TDD:**
- **Decision ladder — run before implementing anything non-trivial**: does this need to exist at all (YAGNI) → is it already in this codebase (where existing candidates conflict, the pattern-conflict rule below decides) → does the stdlib do it → does a native platform feature cover it → does an installed dependency solve it → can it be one line → only then write the minimum that works. Question complexity instead of building it by default ("do you actually need X, or does Y cover it?"); no unrequested abstractions, no avoidable dependencies, fewest files. **The ladder governs how much implementation code gets written — it never relaxes a maestro gate**: Step 5's approved design (states, accessibility), Step 6 security (all input hostile, validate at every boundary), the mandatory pytest/Vitest suite with its security-focused tests, and type annotations all stand. If the ladder says a user-approved plan item should not exist, surface it and ask — never silently drop it. A `yagni:` comment marks an intentional ceiling and must name it (e.g. global lock, O(n²) scan, naive heuristic) plus the upgrade path; it is never cover for leaving TODO-quality gaps.
- Use the Context7 docs from step 2 when writing code — do not guess API signatures
- Follow **Google style guides** strictly (Python and TypeScript)
- **British English** in all prose, comments, commit messages, and documentation
- Type annotations everywhere (Python type hints, TypeScript types)
- No `any` types in TypeScript — use specific types
- `snake_case` for API interface fields (match backend FastAPI)
- **Surface pattern conflicts, don't blend them** — if two existing patterns in the codebase contradict (e.g. mixed error-handling, mixed state management, mixed naming conventions in adjacent modules), pick the more recent or more tested one, justify the choice in the PR description, and flag the other for cleanup in a follow-up. Blended code that satisfies both patterns is the worst outcome: it doubles the surface area to maintain and obscures the canonical pattern for future readers
- Every test file must include security-focused tests where applicable

**For independent subtasks:** Use `superpowers:dispatching-parallel-agents` or `superpowers:subagent-driven-development` to parallelise work. Dispatch implementation subagents on `opus` per Model Routing — the plan already carries the judgement, and it was written on `opus` too. Escalate a subagent to `fable` only after two failed attempts on the same task.

---

## Step 8: VERIFY

### Step 8.0: Evidence Gate (run before ANY completion language)

Before writing "done/fixed/passing/works/verified" or any synonym:
1. Name the command or artefact that proves it.
2. Run it FRESH this message — no cached or prior runs.
3. Paste the actual output (or line/byte count, response, figures) inline.
4. No evidence ⇒ state UNVERIFIED + the missing check. Do not claim.
5. Update the evidence ledger: fill each gate's EVIDENCE from this message's fresh output; demote any gate that no longer passes; the final report names every unmet or abandoned gate with its reason, not only the ones that passed.

Deliberately duplicates `superpowers:verification-before-completion` — the gate must be visible in the workflow, because the sub-skill only fires if invoked.

Invoke `superpowers:verification-before-completion`.

**Then run through `references/quality-gates.md`:**

- [ ] Tests written and passing (pytest for Python, Vitest for TypeScript)
- [ ] Lint clean: `ruff check --fix .` (Python) / `npm run lint` (TypeScript)
- [ ] Format clean: `ruff format --check .` (Python) / `npx prettier --check .` (TypeScript)
- [ ] TypeScript clean: `npx tsc --noEmit` (zero errors)
- [ ] Solution justification documented (why, alternatives, trade-offs)
- [ ] British English verified in all new prose
- [ ] Imports verified — all exist, signatures match
- [ ] No regressions — read changed code once more before committing

### Visual Verification with Playwright

**Skip if:** No frontend files are touched, or no dev server is running.

When frontend changes are involved and Playwright MCP is available, perform visual verification:

1. **Ensure a dev server is running** — if not, suggest the user starts one (`npm run dev` or equivalent). Do not start one silently.
2. **Navigate to affected routes** — use Playwright to open each route that was changed or added
3. **Verify visual rendering** — check that the page renders without errors, layout is correct, and no elements are broken
4. **Test interactive elements** — click buttons, fill forms, toggle states that were changed
5. **Check responsive behaviour** — verify at key breakpoints (375px mobile, 768px tablet, 1280px desktop) if layout changes were made
6. **Verify accessibility** — use Playwright's accessibility tree to check for missing labels, broken focus order, or missing ARIA attributes
7. **Take screenshots** — capture before/after screenshots for the PR description if the change is visually significant

**If Playwright MCP is not available:** Skip visual verification. Note the missing tool in your response so the user can install it. The remaining quality gates (tests, lint, types) still apply.

**Do NOT claim work is done until every applicable gate passes.**

---

## Step 8.5: PRE-PR CODE REVIEW (Local Diff)

**Skip if:** Classification = trivial config/docs change (e.g., one-line config tweak, comment fix, README typo).

**Run for every other task — bug fixes included.** This step closes the gap between local correctness gates (Step 8) and the external PR review loop (Step 10). It is the user's "code review BEFORE PR creation" rule, made explicit and enforceable in the workflow. Catching maintainability and security issues here saves a full claude-review bot cycle on every PR.

### Why a separate step

Step 8 VERIFY enforces *correctness* (tests pass, types compile, lint clean). Step 10 REVIEW happens *after* the PR is open and runs against the merged-base diff. Neither covers the local pre-push window where a focused diff review prevents predictable bot rework. Step 8.5 owns that window.

### What to dispatch

Run as **parallel Agent calls** against the local diff (`git diff main...HEAD`, or `git diff` if work is uncommitted):

| Agent | When to Dispatch | What It Checks |
|-------|------------------|----------------|
| `code-reviewer` | **Always** (non-trivial changes) | Project-convention adherence, design quality, dead code, naming, structure, error handling, test coverage gaps |
| `security-reviewer` | When the diff touches authentication, authorisation, user input, database queries, file uploads, LLM calls, secrets, or PII handling | OWASP Top 10, injection, XSS, CSRF, broken access control, sensitive data exposure, insecure deserialisation, audit logging gaps |
| Language-specific reviewer (`typescript-reviewer`, `python-reviewer`, `go-reviewer`, `rust-reviewer`, etc.) | When the diff is concentrated in one language and the corresponding agent is installed | Language-idiomatic issues, type safety, async correctness, language-specific footguns |

For mixed-language diffs, dispatch the relevant per-language reviewers in parallel alongside `code-reviewer`. Do **not** serialise — run them in a single message with multiple Agent tool uses. Bare names here resolve per the agent precedence rule below; Step 10's `pr-review-toolkit:`-prefixed dispatches are a separate, namespaced set.

**Model routing here:** dispatch the reviewer agents on `opus`; when their findings conflict, or a security-reviewer/SkillSpector verdict needs adjudication, the final judgement call runs on `fable` (generator/judge asymmetry — see Model Routing).

### Severity thresholds

After collecting findings:

| Severity | Action |
|----------|--------|
| CRITICAL | **Block** — fix before Step 9. No exceptions. |
| HIGH | **Block** — fix before Step 9. No exceptions. |
| MEDIUM | **Fix where practical** in this step. If deferred, document why in the PR description. |
| LOW / nit | **Fix opportunistically.** Do not block on these — Step 10 will catch any that genuinely matter. |

### Loop until clean

1. Dispatch reviewers in parallel
2. Collect all findings
3. Fix CRITICAL + HIGH
4. Fix MEDIUM where practical
5. Re-run only the agents whose scope was affected by the fixes
6. Repeat until CRITICAL + HIGH are clear

**Then proceed to Step 9 FINISH.** Do not commit-and-push without this step passing on non-trivial changes — it is the cheapest place to catch issues before they cost a bot review cycle.

### Supply-chain scan — SkillSpector (conditional)

**Run only if** the diff adds or modifies an *agent artefact* — a skill (`SKILL.md`), a plugin manifest, or an MCP server config. **Skip entirely** for ordinary feature/bug-fix diffs (React, Python, app code): SkillSpector is not a code scanner and will only add noise.

**Why it is separate from the agents above:** the code-review agents check *your* code. SkillSpector checks the *skill supply chain* — prompt injection, agent-config snooping, MCP rug-pull, excessive agency, malicious or vulnerable skill instructions — a surface the code reviewers do not cover.

**Process:**

1. Call `scan_skill(<path-to-changed-artefact>, use_llm=false)` on each changed skill/plugin/MCP artefact — static-only, no API key required.
2. SkillSpector returns candidate findings. **It over-flags:** teaching-skills, session observers, and security skills routinely trip its regex on benign guideline text and defensive code — e.g. a PID-validation guard, a mobile UX guideline about gesture conflicts, or a React XSS anti-pattern shown as a "don't do this" example.
3. **Claude adjudicates every HIGH/CRITICAL finding** — read the flagged `file:line` and rule real-vs-false-positive. Do **not** accept the raw `DO_NOT_INSTALL` verdict; it is a static heuristic that cannot judge intent.
4. **Gate:** a Claude-**confirmed** CRITICAL/HIGH (not a raw-static flag) → block, surface the real issue, fix or reject before Step 9. Findings Claude clears as false positives → note and proceed. **MEDIUM/LOW** findings → note in the PR description if plausibly real; otherwise disregard (static-only MEDIUM/LOW on a trusted artefact is almost always guideline-text or defensive-code noise).

Do **not** rely on SkillSpector's own LLM pass (it needs a provider key). Claude is the semantic judge — keyless, no recurring cost, fuller repo context.

### When the reviewer agents are unavailable

If `code-reviewer` and language-specific reviewers are not available in the current environment:
- Perform a **manual self-review** — read every changed file end-to-end against the user's CLAUDE.md, the project's coding-style rules, and the security checklist from Step 6
- Note the missing agents in your response so the user can install the corresponding source (`pr-review-toolkit` ships the `code-reviewer` class; `security-reviewer` and the language reviewers come from user-scope agent packs such as Everything Claude Code)
- Do **not** skip the step entirely — manual review is the fallback, not skipping

---

## Step 9: FINISH

Invoke `superpowers:finishing-a-development-branch`.

**Maestro rules:**
- **Never push directly to main.** Always create a branch and PR.
- Commit messages use conventional format: `fix:`, `feat:`, `refactor:`, `docs:`, `style:`, `test:`
- Git operations are auto-approved — do not ask for confirmation to commit, push, or create PRs.

---

## Step 10: REVIEW

After creating the PR, run a **two-phase review process**: specialist agent analysis followed by the PR review polling loop.

### Phase 1: Specialist Agent Analysis (PR Review Toolkit)

Dispatch the relevant specialist agents from the PR Review Toolkit in parallel. Select agents based on what the PR contains:

| Agent | When to Dispatch | What It Checks |
|-------|-----------------|----------------|
| `pr-review-toolkit:code-reviewer` | **Always** | Adherence to project guidelines, style, patterns |
| `pr-review-toolkit:silent-failure-hunter` | **Always** — any PR can introduce silent failures | Swallowed errors, empty catch blocks, inappropriate fallbacks, missing error propagation |
| `pr-review-toolkit:pr-test-analyzer` | **Always** | Test coverage gaps, missing edge cases, critical untested paths |
| `pr-review-toolkit:code-simplifier` | When implementation is complex or touches multiple files | Unnecessary complexity, redundant code, simplification opportunities |
| `pr-review-toolkit:type-design-analyzer` | When new types/interfaces are introduced | Type encapsulation, invariant expression, design quality |
| `pr-review-toolkit:comment-analyzer` | When docstrings or documentation comments are added/modified | Comment accuracy, staleness risk, maintainability |

**Process:**
1. Determine which agents are relevant based on the PR diff
2. Dispatch all relevant agents **in parallel** using the Agent tool (on `opus` per Model Routing)
3. Collect findings from all agents — when specialists disagree, arbitrate the conflict on `fable`
4. Fix any issues flagged by the agents — commit and push
5. Re-run any agents whose scope was affected by the fixes (if needed)

### Phase 2: PR Review Polling Loop

After specialist analysis is clean, enter the external review loop:

1. Poll GitHub every 4 minutes using `gh pr checks` and `gh api` to read review comments
2. If the review has **any** issues (suggestions, warnings, nits, dead code findings, errors):
   - Fix them
   - Commit and push
   - Continue polling
3. Only stop when the review is **fully clean** — approved with zero outstanding comments
4. Report the final clean status to the user

**Precondition:** first check whether an external reviewer or review bot is configured (`gh pr checks`, a prior PR's timeline). If none exists, Phase 2's terminal state is **CI green**: say no reviewer is configured, stop polling once checks pass, and record that as the clean status. Never poll for an approval that cannot arrive.

### When PR Review Toolkit Is Unavailable

If the PR Review Toolkit agents are not available, skip Phase 1 and proceed directly to Phase 2 (the polling loop). Note the missing toolkit in your response.

---

## Orchestration Rules

### Always Enforce (Every Task)

1. **Plan first** — never write code without a plan (exception: trivial one-liners)
2. **Tests are mandatory** — every code change ships with tests, no exceptions
3. **Solution justification** — every approach must explain why, alternatives, and trade-offs
4. **British English** — in all responses, comments, commits, and documentation
5. **Security-first** — assume all input is hostile, validate at every boundary
6. **Never push to main** — always branch + PR

### Self-Critique Protocol

After designing any solution, before presenting it:
1. Ask "what's wrong with this?" — find at least 2 weaknesses
2. State the impact of each weakness
3. Explain why the approach is still the best option despite them (or revise)

### Progress Protocol (responses inside a multi-step flow)

Applies once CLASSIFY names a step set with more than one step left, and stops when the final step closes — never on trivial single-step tasks or conversational turns. The reader cannot hold flow position between messages, so each response carries it:

1. **Open with flow position** — name the step and its state: "Step 5 (UI/UX gate) — blocked on your mockup approval." No total and no percentage: the step set varies by classification, and Step 8.5 makes any fixed denominator wrong. Name the stage instead on the Deliverable flow. Response order is position, then evidence, then prose.
2. **Leave at most one open ask** — 5c is the usual case. If two gates come due together, present both and rank them; **never drop one to satisfy this rule.** A question may be deferred, never suppressed. Most steps need nothing from the user and git operations are auto-approved, so when no action is due, close by naming the step you are moving to.
3. **Evidence above justification** — Step 8.0 already forces a fresh command run; put its output above the justification prose, not below. The justification still ships in full.
4. **No wall-clock estimates** — a duration is a guess dressed as a figure, and nothing here can check it. State steps or gates remaining. A fixed cadence, like Step 10's four-minute poll, is a schedule and fine to quote.

Governs **reporting order and ask count only.** Never truncates a checklist, drops a justification, or suppresses a gate's question.

…(truncated)