orchestration (Playbook)

Quality-gated pipeline from idea to shipped code. Each phase produces a validated artifact that feeds the next. Context is scoped per phase; no phase inherits prior conversation history. Choose one configuration from the user prompt.

When to use (triggers)

• Fuzzy idea, requirements, brief → arm
• First-principles design, constraints, research → design
• Multi-perspective critique, adversarial review → adversarial-review
• Execution plan, task groups, atomic planning → plan
• Drift detection, plan-vs-design, claim verification → pmatch
• Parallel build, agent coordination, implementation → build
• Static quality gate (lint/format/type) → quality-static
• Test quality gate (verification commands) → quality-tests
• Dead code, noise, cleanup → denoise
• Frontend style audit → quality-frontend
• Backend style audit → quality-backend
• Documentation freshness → quality-docs
• OWASP, vulnerability scan, security → security-review
• Final release decision gate → release-readiness
• Full pipeline, end-to-end orchestration → pipeline

Choosing configuration from user prompt

Prompt / theme	Configuration
idea, requirements, brief, arm, crystallize	arm
design, first-principles, constraints, approach, research	design
adversarial review, multi-perspective, critique, ar	adversarial-review
execution plan, task groups, atomic planning, deterministic	plan
drift, pmatch, plan-vs-design, claim verification	pmatch
build, parallel, coordinate, implement, agent teams	build
static checks, lint, format, typecheck	quality-static
test gate, verification tests, quality tests	quality-tests
denoise, dead code, unused, cleanup	denoise
frontend quality, frontend style, qf	quality-frontend
backend quality, backend style, qb	quality-backend
docs freshness, documentation quality, qd	quality-docs
security review, OWASP, vulnerabilities	security-review
release readiness, ship gate, go/no-go	release-readiness
full pipeline, end-to-end, orchestrate all phases	pipeline

Cognitive tiering

Tier	Role	Phases
Lead (high-reasoning)	Strategy, design, coordination	arm, design, adversarial-review (lead), plan, build (lead), release-readiness
Worker (fast)	Implementation, audit, review	build (workers), adversarial-review (reviewers), quality-static, quality-tests, denoise, quality-*, security-review, pmatch

Artifact contracts

All artifacts validate against schemas in

contracts/artifacts/

(including

execution-trace

and

evaluation-report

). Quality gates validate against

contracts/quality-gate.schema.json

. Pipeline state lives in

.pipeline/

(gitignored).

Adapter mapping (source of truth)

Canonical stage adapters are defined under

adapters/<runner>/skills/

.

• Codex:

  adapters/codex/skills/orchestration-*/SKILL.md

• Cursor:

  adapters/cursor/skills/orchestration-*/SKILL.md

• Claude:

  adapters/claude/skills/orchestration-*/SKILL.md

• Gemini:

  adapters/gemini/skills/orchestration-*/SKILL.md

• Kilo:

  adapters/kilo/skills/orchestration-*/SKILL.md

Semantic anchors

Use these terms consistently. Each term carries specific operational meaning:

• Context minimization: excessive context degrades signal quality; scope context tightly per phase.
• Capability allocation: reserve deep reasoning for strategy and use fast models for execution/audit throughput.
• Separation of duties: producers do not self-certify; validation must run from independent context.
• Parallel challenge: independent reviewers pressure-test assumptions to surface blind spots.
• Evidence-first guidance: recommendations must trace to verifiable sources and repository facts.
• Predeclared verification: tests and acceptance checks are defined before implementation begins.
• Human control points: automation assists execution, but critical gate progression requires explicit approval.
• Fix-first security closure: critical/high security findings are fixed and re-verified before progression; risk acceptance is explicit and owned.
• Traceable intent preservation: requirements and constraints keep stable trace IDs through plan, tests, drift, and gate evidence.

Configurations

arm

Requirements crystallization. Input: fuzzy idea (user prompt). Model: lead (high-reasoning). Steps: Extract requirements, constraints, non-goals, style, key concepts via conversational Q&A → Force remaining decisions in single structured checkpoint → Validate against

contracts/artifacts/brief.schema.json

→ Write to

.pipeline/runs/<run-id>/brief.json

. Gate:

open_questions

array is empty; all constraints have explicit type and source. Output: Brief artifact. Hard rules: never guess a requirement; if ambiguous, ask; checkpoint is one round, not iterative.

design

First-principles design. Input: Brief artifact. Model: lead (high-reasoning). Steps: Classify every constraint (hard/soft, flag misclassifications) → Reconstruct approach from validated truths only (no assumptions from training data) → Research via MCP-backed live docs (e.g. Context7) + web search → Align with codebase patterns (grep for conventions) → Iterate with user until alignment → Validate against

contracts/artifacts/design-document.schema.json

→ Write to

.pipeline/runs/<run-id>/design.json

. Gate: user approves alignment; all research citations have verified_at timestamps; no unclassified constraints remain. Tools: filesystem, MCP docs, web search. Semantic intent: evidence-first guidance.

adversarial-review

Multi-perspective critique. Input: Design Document artifact. Model: 3 independent reviewer subagents with different expert perspectives — architect-reviewer (architecture, scalability, coupling), security-engineer (OWASP, auth, trust boundaries), performance-engineer (bottlenecks, resource usage, caching). Lead (high-reasoning) orchestrates. Steps: Fan out design to 3 reviewer subagents in parallel (each gets filesystem + MCP docs access, each returns findings in Finding[] format) → Collect findings and pipe through

multi-model-review

skill for deduplication and cost/benefit analysis → Lead fact-checks each finding against actual codebase → Structured report for human review → Loop until no findings warrant mitigation per cost/benefit → Validate against

contracts/artifacts/review-report.schema.json

→ Write to

.pipeline/runs/<run-id>/review.json

. Gate: all critical/high findings mitigated or accepted with justification;

remaining_unmitigated

contains only low/info items. Hard rules: the lead never dismisses a finding without evidence; each reviewer works independently (no shared context between reviewers). Semantic intent: parallel challenge + separation of duties.

plan

Atomic execution planning. Input: Design Document + Review Report artifacts. Model: lead (high-reasoning). Steps: Transform design into task groups (target 3-6 tasks per builder, hard max 8) → Assign file ownership (no file appears in more than one group) → Include exact file paths, complete code patterns showing the approach, named test cases with setup and assertions → Define non-negotiable acceptance criteria per task → Link every task and test to covered requirement IDs (

covers_requirement_ids

) → If a group intentionally falls outside the 3-6 target, include

scope_override.reason

in that group → Validate against

contracts/artifacts/execution-plan.schema.json

→ Write to

.pipeline/runs/<run-id>/plan.json

. Gate: every task has at least one test case;

file_ownership

has no conflicts; all code patterns are complete (no TODOs or placeholders); verification commands are executable; MUST requirements are covered by >=1 test link (

coverage-min

gate criterion); groups outside 3-6 have explicit

scope_override.reason

. Hard rules: if the builder would have to guess, the plan failed. Semantic intent: predeclared verification.

pmatch

Drift detection. Input: source artifact (design or plan) + target artifact (plan or implementation). Model: two independent Task subagents (e.g. refactoring-specialist + architect-reviewer) working in parallel. Steps: Each agent independently extracts claims from source document → Verifies each claim against target → Feed both claim sets to

multi-model-review

with

action.type="drift-detect"

and

drift_config.mode="dual-extractor"

for adjudication (heuristic mode remains fallback-only) → Emit drift claim taxonomy classes (

interface

,

invariant

,

security

,

performance

,

docs

) for quality measurement → Lead validates conflicts and mitigations → Validate against

contracts/artifacts/drift-report.schema.json

→ Write to

.pipeline/runs/<run-id>/drift-reports/pmatch.json

. Gate: no unmitigated structural drift (severity critical or high); all violated claims have mitigation or justification; adjudication metadata present (

mode

,

extractors

,

conflicts_resolved

,

resolution_policy

). Hard rules: extractors work independently (no shared context); lead must verify before accepting a finding.

build

Coordinated parallel build. Input: Execution Plan artifact. Model: lead (high-reasoning) + workers (fast). Steps: Lead distributes task groups to builder agents (each gets own terminal/context scoped to its task group only) → Builders implement independently → Lead coordinates, unblocks, monitors progress → After all builders finish, lead runs pmatch (plan vs implementation) → Gate: all acceptance criteria pass; pmatch clean; verification commands succeed. Hard rules: lead never writes code; builders see only their task group and file paths; no builder context leaks to another builder. Semantic intent: context minimization + separation of duties.

quality-static

Static quality gate. Input: implementation (changed files) + verification commands. Model: worker (fast). Steps: Execute lint, format-check, and typecheck/build commands (no auto-fix) → Capture command evidence and failures → Validate report against

contracts/artifacts/quality-report.schema.json

(

audit_type: static

) → Write

.pipeline/runs/<run-id>/quality-reports/static.json

. Gate: all static commands exit 0; report schema-valid.

quality-tests

Test quality gate. Input: implementation + execution plan verification commands. Model: worker (fast). Steps: Execute required test commands independently of build coordination → Capture failures with reproduction commands → Validate report against

contracts/artifacts/quality-report.schema.json

(

audit_type: tests

) → Write

.pipeline/runs/<run-id>/quality-reports/tests.json

. Gate: all required tests pass; no unresolved critical/high test violations.

denoise

Dead code and noise removal. Input: implementation (changed files). Model: worker (fast). Steps: Identify dead imports, unused variables, debug artifacts (console.log, TODO comments from build), orphaned code → Remove with evidence for each removal → Run tests to confirm no regressions → Validate against

contracts/artifacts/quality-report.schema.json

(audit_type: denoise). Gate: tests still pass after cleanup; no functional changes.

quality-frontend

Frontend style audit. Input: implementation (frontend files). Model: worker (fast). Steps: Audit against project-specific frontend style guide (component patterns, naming, accessibility, performance) → Report violations with file, line, evidence, remediation → Validate against

contracts/artifacts/quality-report.schema.json

(audit_type: frontend). Gate: no critical/high violations.

quality-backend

Backend style audit. Input: implementation (backend files). Model: worker (fast). Steps: Audit against project-specific backend style guide (API patterns, error handling, security, logging) → Report violations with file, line, evidence, remediation → Validate against

contracts/artifacts/quality-report.schema.json

(audit_type: backend). Gate: no critical/high violations.

quality-docs

Documentation freshness audit. Input: implementation. Model: worker (fast). Steps: Cross-reference docs (README, API docs, inline docs) with changed code → Flag stale documentation (functions renamed, parameters changed, behavior altered without doc update) → Validate against

contracts/artifacts/quality-report.schema.json

(audit_type: docs). Gate: all changed public APIs have matching documentation.

security-review

Comprehensive security audit and remediation loop. Input: implementation + runtime/deploy config. Model: worker (fast) for scanning, lead verification for closure.

Mandatory coverage checklist:

1. Access control and tenancy isolation (IDOR, horizontal/vertical privilege escalation, mass assignment).
2. Client-side injection defenses (XSS sources/sinks, output encoding, CSP effectiveness).
3. CSRF defenses on every state-changing endpoint (token enforcement + SameSite strategy).
4. Secret exposure and sensitive-data leakage (hardcoded keys, tokens, credentials, signing secrets, client bundle leaks).
5. HTTP security hardening (CSP, HSTS, X-Frame-Options/frame-ancestors, X-Content-Type-Options, Referrer-Policy, cache policy for sensitive pages).
6. Session and cookie hardening (

   Secure

   ,

   HttpOnly

   ,

   SameSite

   , auth token storage policy).
7. Production information exposure (server banners/versions, debug mode, stack traces, verbose errors).
8. Dependency vulnerabilities and patching (lockfile-aware updates + rescan).
9. Server-side injection and input abuse (SQL/NoSQL injection, command injection, SSRF).
10. File and path handling (insecure upload validation, path traversal, archive extraction safety).
11. Redirect and token issues (open redirects, JWT algorithm/expiry/storage validation).

Execution steps:

1. Run all checklist categories and capture evidence per finding.
2. Fix every critical/high finding.
3. Rerun the same checks and confirm closures.
4. Repeat until

   critical/high open = 0

   .
5. For any accepted risk, record owner, justification, expiry, and follow-up ticket.

Validate against

contracts/artifacts/quality-report.schema.json

(audit_type: security). Gate: no open critical/high findings; mandatory checklist fully executed; accepted risks explicitly signed off.

release-readiness

Final ship gate. Input: completed gate artifacts + quality reports + release docs. Model: lead (high-reasoning). Steps: Determine release decision (

go

,

no-go

,

conditional

) → Assess semver impact, changelog updates, migration readiness, rollback readiness, open risks, and approvals → Validate against

contracts/artifacts/release-readiness.schema.json

→ Write

.pipeline/runs/<run-id>/release-readiness.json

. Gate: schema-valid artifact; changelog updated; major version impacts include validated migration docs; rollback tested with owner; open risks have owner and due date; conditional decisions include explicit conditions.

pipeline

Full pipeline orchestrator. Meta-configuration that runs phases in sequence: arm → design → adversarial-review → plan → pmatch → build → quality-static → quality-tests → post-build → release-readiness. Steps: Initialize

.pipeline/runs/<run-id>/

→ Run each phase, write artifacts, validate gates between phases → Enforce per-phase context budgets using

context_manifest

+ quality-gate criteria (

count-max

,

number-max

) → Apply

config.orchestration_policy

to choose reviewer/builder fan-out only when marginal gain clears threshold → Emit append-only trace events to

.pipeline/runs/<run-id>/trace.jsonl

and summarize with

trace-collector

→ Block on gate failure (human must resolve before proceeding) → Post-build: run denoise, then quality-frontend + quality-backend + quality-docs + security-review (parallel or sequential depending on file independence) → For security-review specifically, run mandatory remediation loop (fix + rescan) with coverage of all required categories before final post-build gate close → Run release-readiness gate and block closure on

no-go

or unfulfilled

conditional

requirements → Write pipeline-state.json after each phase transition → Optional matrix evaluation writes

.pipeline/evaluations/<eval-id>/evaluation-report.json

. Hard rules: never auto-advance past a failed gate; human approval required at arm checkpoint, design alignment, adversarial review report, conditional/no-go release decisions, and any accepted security risk exception. Semantic intent: human control points + capability allocation.