Maestro

Maestro — Master Orchestrator

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

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.

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:

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:

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

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:

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

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:

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:

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)