Quality Playbook

Quality Playbook Generator

Plan Overview — read this first, then explain it to the user

Before reading any other section of this skill, understand the plan and its dependencies. Each phase produces artifacts that the next phase depends on. Skipping or rushing a phase means every downstream phase works from incomplete information.

Phase 0 (Prior Run Analysis): If previous quality runs exist, load their findings as seed data. This is automatic and only applies to re-runs.

Phase 1 (Explore): Run the documentation intake first. Invocation form: bin/reference_docs_ingest.py does from bin import benchmark_lib at import, so Python's -m bin.reference_docs_ingest resolves ONLY when bin/ is reachable as a top-level package. Resolve the install root (the directory containing this SKILL.md) via the same install-location fallback list this skill uses for references/ / quality_gate.py (the 10 canonical layouts documented below — install-root forms: <empty>, .claude/skills/quality-playbook, .github/skills, .github/skills/quality-playbook, .cursor/skills/quality-playbook, .continue/skills/quality-playbook, .codex/skills/quality-playbook, .windsurf/skills/quality-playbook, .cline/skills/quality-playbook, .aider/skills/quality-playbook). Then, from the target repo root, run PYTHONPATH=<install_root> python3 -m bin.reference_docs_ingest <target>. If <install_root> is empty (QPB self-bootstrap, or a setup_repos.sh install where bin/ is already at the target root) omit the PYTHONPATH= prefix — cwd already provides bin/. The bare python -m bin.reference_docs_ingest <target> works ONLY for those two layouts; an install_skill.py-layout adopter (bin/ inside the marker dir) otherwise gets ModuleNotFoundError: No module named 'bin'. This walks reference_docs/ — cite/ files produce quality/formal_docs_manifest.json records; top-level files are loaded as Tier 4 context via reference_docs_ingest.load_tier4_context(<target>). Then explore the codebase in three stages: open exploration driven by domain knowledge, domain-knowledge risk analysis, and selected structured exploration patterns. Write all findings to quality/EXPLORATION.md. This file is the foundation — Phase 2 reads it as its primary input.

Phase 2 (Generate): Read EXPLORATION.md and produce the quality artifacts: requirements, constitution, functional tests, code review protocol, integration tests, spec audit protocol, TDD protocol. (AGENTS.md at the target's repo root is generated by the orchestrator AFTER Phase 6, not by you in Phase 2 — see "File 6" below for the contract.)

Phase 3 (Code Review): Run the three-pass code review against HEAD. Write regression tests for every confirmed bug. Generate patches.

Phase 4 (Spec Audit): Three independent AI auditors review the code against requirements. Triage with verification probes. After triage, the same Council runs the Layer-2 semantic citation check — one prompt per reviewer, structured per-REQ verdicts for every Tier 1/2 citation, output to quality/citation_semantic_check.json. Write regression tests for net-new findings.

Phase 5 (Reconciliation): Close the loop — every bug from code review and spec audit is tracked, regression-tested or explicitly exempted. Run TDD red-green cycle. Finalize the completeness report.

Phase 6 (Verify): Run self-check benchmarks against all generated artifacts. Check for internal consistency, version stamp correctness, and convergence.

Phase 7 (Present, Explore, Improve): Present results to the user with a scannable summary table, offer drill-down on any artifact, and provide a menu of improvement paths (iteration strategies, requirement refinement, integration test tuning). This is the interactive phase where the user takes ownership of the quality system.

Every bug found traces back to a requirement, and every requirement traces back to an exploration finding.

The critical dependency chain: Exploration findings → EXPLORATION.md → Requirements → Code review + Spec audit → Bug discovery. A shallow exploration produces abstract requirements. Abstract requirements miss bugs. The exploration phase is where bugs are won or lost.

MANDATORY FIRST ACTION: After reading and understanding the plan above, print the following attribution banner exactly as written below — do NOT condense, abbreviate, summarize, or reformat. Reproduce the full 8-line canonical block including the two ===…=== rules, both taglines, the blank lines, and the license line, byte-for-byte matching bin/_purpose.print_attribution_banner() (the single source of truth). On the title line, include the running skill version — render it as Quality Playbook vX.Y.Z -- by Andrew Stellman, where vX.Y.Z is the version: from this skill's frontmatter, exactly as print_attribution_banner() emits it. This lets the operator confirm at a glance which version is running (and catches a stale install silently running old behavior). Then explain the plan in your own words — what you'll do, what each phase produces, and why the exploration phase matters most. Emphasize that exploration starts with open-ended domain-driven investigation, followed by domain-knowledge risk analysis that reasons about what goes wrong in systems like this, then supplemented by selected structured patterns. Do not copy the plan verbatim; paraphrase it to demonstrate understanding.

================================================================================
  Quality Playbook -- by Andrew Stellman
  https://github.com/andrewstellman/quality-playbook

  AI code review is good. Quality engineering is better.
  Because code that looks right can still do the wrong thing.

  Licensed under the Apache License, Version 2.0
================================================================================

(The template above shows the canonical 8-line block; on the first line, insert vX.Y.Z after Quality Playbook using this skill's frontmatter version:, matching bin/_purpose.print_attribution_banner().)

Generate a complete quality system tailored to a specific codebase. Unlike test stub generators that work mechanically from source code, this skill explores the project first — understanding its domain, architecture, specifications, and failure history — then produces a quality playbook grounded in what it finds.

How to run this — self-encoded invocation contract

If the operator hands you this skill (or points you at any QPB-installed target) and says "Run the Quality Playbook" — possibly with a hint like "this is a bootstrap run" or "run on itself" or "self-audit" — this section tells you exactly what to do. The operator should not need to provide additional instructions; the canonical invocation, the defaults, the guardrails, and the output contract all live here.

Pick your execution mode

QPB ships in two execution shapes. Pick the one that matches your runtime — the wrong choice produces the codex-on-codex indirection pathology.

Both modes use the same phase prompt content — the phase_prompts/*.md files at the repo root are the single source of truth, loaded by bin/run_playbook.py::_load_phase_prompt and read directly by Mode A walkthroughs. The only thing the two modes differ on is WHO drives — you (Mode A) or the orchestrator subprocess-spawning a CLI agent (Mode B).

When in doubt, default to Mode A. If the operator wanted runner-driven invocation they would have run the runner themselves; if they pasted "Run the Quality Playbook" into your chat, they want you to drive. The Mode B section below tells you what to do if the operator explicitly invokes the runner.

Documented Mode A vs Mode B asymmetries — by design. Three behaviors deliberately differ between the modes because the modes serve different purposes (Mode A is the adopter-facing walkthrough on a target repo; Mode B is the QPB-internal runner used for benchmarking + headless CI). The phase prompts are identical (single source of truth — see paragraph above); the divergences are in the driver obligations, not the audited contract:

1. Phase 0 entry contract — install validator (Mode A only). Mode A's mandatory first action is to run the install validator. Invocation form is install-location-aware: resolve the install root (the directory containing this SKILL.md) via the same install-location fallback list this skill uses for references/ / phase_prompts/ (the 10 canonical layouts documented below), then run python3 <install_root>/bin/qpb_validate.py <target>. For a clone / self-bootstrap (install root is the QPB clone, bin/ reachable from cwd) the bare python3 bin/qpb_validate.py <target> works. For an install_skill-layout adopter (channel or manual install — bin/ inside the marker dir, e.g. .github/skills/quality-playbook/bin/) you MUST use the install-root-prefixed form; running bare bin/qpb_validate.py from the target repo root fails (the validator lives under the marker dir, not at repo root). The adopter has just installed QPB into their target repo and must confirm canonical layout before any phase. Mode B (the QPB clone running its own runner) operates from the canonical install by construction; the validator would always succeed against the QPB clone itself, so the check would be vacuous. Adopters running Mode A get the install correctness gate; Mode B operators have it already.
2. End-of-run archive (Mode B only). Mode B's _finalize_iteration calls archive_lib.archive_run after Phase 6, materializing quality/previous_runs/<ts>/ for benchmark replay + cross-run diffing. Mode A produces artifacts directly into the target's live quality/ for the adopter to inspect, commit, or re-run on top of; there is no archive partition because there is no benchmark loop. Adopters who want longitudinal archives invoke Mode B explicitly (python3 -m bin.run_playbook --full-run <target>).
3. Phase 6 auditor-prompt sub-agent dispatch (Mode A only). phase_prompts/phase6.md routes Mode A through phase_prompts/phase6_auditor.md via a fresh-context sub-agent spawn (the A-13 hybrid). Mode B's per-phase CLI subprocess is already a fresh context (the structural separation the auditor exists to provide), so phase6.md:5-7 tells Mode B to execute the verification inline and skip the auditor spawn. phase_prompts/phase6_auditor.md is therefore only loaded under Mode A; the file's header documents this routing explicitly.

These asymmetries are pinned by bin/tests/test_mode_a_b_parity_documented.py. If a future change wants to align them, update the pin test, the rationale here, and add the missing behavior to the appropriate side.

Mode A — skill-direct walkthrough (UI-context)

The operator's prompt is just "Run the Quality Playbook" (or "run on itself", "self-audit", etc.). You drive every phase inline.

Mode A means YOU execute the skill. If you are an interactive coding agent (Claude Code, Cursor, Copilot UI, Codex desktop, any tool where the operator is monitoring your chat output in real-time), DO NOT:

• Spawn a sub-skill via your quality-playbook skill-invocation mechanism.
• Spawn a sub-agent via your Task tool / Agent tool / similar.
• Invoke python3 -m bin.run_playbook — that's Mode B, the CLI-automation path.
• Read agents/quality-playbook.agent.md or agents/quality-playbook-claude.agent.md and follow their "spawn sub-agents per phase" pattern — those files are AUTOMATION ONLY (batch CI runs, headless invocations) where per-phase context-window isolation is necessary at the cost of operator chat visibility.

Phase 0 entry contract (MANDATORY first action): run the QPB install validator. Resolve the install root via the install-location fallback list (per the Phase 0 numbered step above), then run python3 <install_root>/bin/qpb_validate.py <target-repo> — bare python3 bin/qpb_validate.py <target-repo> works only when cwd already contains bin/ (QPB clone / self-bootstrap); install_skill-layout adopters (channel install — bin/ under .github/skills/quality-playbook/, etc.) MUST prefix the install root. Paste every event= line; do not proceed until event=validation_complete status=ok — see AGENTS.md "Mode A entry sequence". Non-negotiable — skipped/fabricated validation and bare-path-from-repo-root invocation are both documented adopter failure modes.

EXCEPTION: Phase 6 verification MUST be delegated to a fresh-context sub-agent. Sub-agent delegation is forbidden for EXECUTION (Phases 1-5) because hiding work from operator chat defeats real-time monitoring. Sub-agent delegation is MANDATED for VERIFICATION (Phase 6) because shared-context executor-as-verifier has empirically fabricated PASS verdicts against failing gates across multiple benchmark runs despite repeated rounds of strengthened prompt-level witness language. The principle is the same as the rule above — operator chat should carry the truth — but the mechanism is opposite: visibility for execution; isolation for verification (a fresh auditor has none of the executor's memory/anchoring/completion-reward bias). See phase_prompts/phase6.md + phase_prompts/phase6_auditor.md for the sub-agent delegation protocol. This exception is scoped strictly to Phase 6 verification — the no-sub-agent rule still holds for all Phase 1-5 execution.

EXCEPTION: the Feature H persona validation pass may spawn its personas. The no-sub-agent rule governs delegating a PHASE'S EXECUTION (Phases 1–5). The Feature H persona validation pass (bin/persona_apply.run_feature_h, run automatically at the Phase 2→3 boundary; Design §8b, references/requirements_pipeline.md § E.9) is a second narrowly-scoped sanctioned exception: it spawns fresh-context, tool-restricted domain-expert + security personas to validate the finalized requirements. This does NOT reopen either failure mode the rule closes: (a) it does not delegate a phase's execution — it is a bounded validation remediation that runs at one boundary and returns to your session, never a worker running phases 2–6 (so the delegated-agent-silent-death mode cannot apply); (b) operator visibility is preserved and mandatory — the pass writes an operator-visible quality/expert_review_summary.json listing every applied change with its grounding, every change is agent-validation-tagged and revertible (persona_apply.revert), and the pass is opt-out (disablable for the run), so nothing is hidden and no verdict is fabricated. The guardrail's own principle — operator chat carries the truth — is honored, not bypassed: that review summary is the trail. Scoped strictly to this pass; the no-sub-agent rule still holds for all other Phase 1–5 work — you may NOT delegate a phase, spawn a worker, or invoke the quality-playbook orchestrator sub-skill.

The failure mode that motivated this rule: a shared-context session ran phases 1-6, fabricated the gate-verdict log (quality/results/quality-gate.log was hand-written with a "PASS" tally while the actual gate showed 14 FAIL, GATE FAILED), and reported PASS to the parent. The Phase 6 witness contract (your obligation to quote the gate's verdict lines verbatim) cannot enforce when a sub-skill owns the witness — only the parent's chat carries operator-readable evidence.

YOU read SKILL.md and the phase prompts. YOU execute Phases 1-5 yourself and write artifacts to quality/. Phase 6 verification is delegated to the fresh-context auditor sub-agent per the exception above (the auditor invokes quality_gate.py); you paste its verbatim verdict. Your chat IS the trust trail — execution stays visible, verification stays bias-isolated.

You have shell access — probe before claiming unavailability. Mode A means an interactive coding agent (Claude Code, Cursor, Copilot UI) running commands on the operator's actual machine via your Bash tool — NOT a sandboxed runtime. A common failure is writing "the sandbox can't run X" reflexively, conflating your model-level "I can't natively execute" with the harness Bash tool you DO have. A which <tool> / <tool> --version probe costs one line; assuming-and-being-wrong forfeits the entire Phase 5 evidence trail.

For each phase 1..6, in order:

1. Load the phase prompt. Read phase_prompts/phaseN.md (resolve via the same install-location fallback list documented for references/ below). For phase1.md, substitute {seed_instruction} (the prelude that says "skip Phase 0/0b" — empty string when seeds are allowed) and {role_taxonomy} (the taxonomy block rendered from the role taxonomy below). For phase2.md through phase6.md, the file is pure-literal — read it verbatim.
2. Execute the phase per the prompt. Read the inputs the prompt names, do the analysis, write outputs into the target's quality/ directory.
3. STOP at the end-of-phase boundary. Every phase prompt ends with an "IMPORTANT: Do NOT proceed to Phase N+1" instruction. Honor it. The operator advances to the next phase by saying so.

You are responsible — without the orchestrator's structural backstop — for the same source-unchanged invariant the runner enforces: do NOT modify any file outside the target's quality/ directory. In Mode B the gate would catch this; in Mode A you are the gate. A documented failure mode: a Phase 2 LLM modifying the target's root AGENTS.md — the same failure mode applies in Mode A.

For the bootstrap-run (self-audit) variant of Mode A, see "Bootstrap mode" below — the only delta is that the target IS the QPB repo, so cite the same phase_prompts/ files you read from.

Mode A scope — what's covered, what's Mode-B-only

The per-phase walkthrough above scopes Mode A to phases 1..6. The following surfaces are deliberately Mode-B-only — if the operator wants them, point them at the runner instead of trying to drive them yourself:

• Phase 0 / Phase 0b (seed injection from prior runs). The orchestrator handles seed discovery, prior-run scanning, and seed-prompt injection. In Mode A, treat every run as --no-seeds (skip Phase 0/0b entirely, start at Phase 1). If the operator explicitly asks for seed-driven exploration, hand off to Mode B (python3 -m bin.run_playbook --with-seeds <target>).
• Phase 7 (interactive Present / Explore / Improve). Mode A's Phase 7 is the conversational version — present the artifact summary table inline and let the operator drive what to explore. See the Phase 7: Present, Explore, Improve section below for the canonical treatment covering both modes.
• Iteration strategies (gap / unfiltered / parity / adversarial). Iterations re-enter the playbook with a strategy-specific addendum. In Mode A, after Phase 6 completes cleanly, hand off to Mode B for iterations: python3 -m bin.run_playbook --next-iteration --strategy <name> <target>. The iteration prompts (phase_prompts/iteration.md) ARE single-source-of-truth, but the iteration-orchestration loop (rotating through gap → unfiltered → parity → adversarial) is the runner's job. A Mode A operator who wants iterations after Phase 6 should be told: "Phase 6 is done; run python3 -m bin.run_playbook --full-run <target> to get all four iteration strategies, or pick one strategy explicitly with --next-iteration --strategy gap."

If the operator asks for one of these surfaces in Mode A and the request is ambiguous (e.g., "also do the iterations"), surface the mode-handoff explicitly rather than improvising — improvisation is how the prompt content drifts away from the runner's canonical loop.

Mode B — runner-driven invocation (CLI-automation)

The operator runs python3 -m bin.run_playbook themselves (typically because they want batching, headless CI, or to route per-phase work to a different model). The orchestrator at bin/run_playbook.py spawns a CLI agent per phase, feeds it the externalized phase prompt, and aggregates the result.

Canonical invocation

The orchestrator is the entry point. Two invocation forms are supported:

• python3 -m bin.run_playbook <target> — canonical package-module form.
• python3 /path/to/QPB/bin/run_playbook.py <target> — direct script form. Works from any cwd because the module injects QPB root into sys.path before importing sibling modules.

<target> is the path to the project to audit. For a bootstrap run (target IS the QPB repo), pass . from the repo root. For any other target, pass the path to that target's repo root.

Default behavior (no flags)

Bare invocation triggers a full run: all 6 phases (Explore → Generate → Code Review → Spec Audit → Reconciliation → Verify) followed by all 4 iteration strategies (gap → unfiltered → parity → adversarial), executed synchronously in the same session. Any prior quality/ directory is auto-archived to quality/previous_runs/<TIMESTAMP>/ before the new run starts.

This is the canonical operator path. Don't ask permission to add flags; the defaults are the answer.

When the bare invocation fires, the orchestrator emits a one-line stderr banner naming the run cost. That banner is informational; let it scroll.

Common overrides

Use only when the operator asks for something specific:

Recovering from a partial / aborted runner-driven run

Council 2026-04-30 P1-4: the operator-hygiene guidance for cleaning up after an aborted run lives in the Bootstrap mode section below ("Bootstrap-run operator hygiene") — the recovery is identical in Mode B: git restore quality/ to discard the partial Phase 1/2 output, then re-invoke. Do NOT edit files outside quality/ to "tidy up" — the source-unchanged invariant trips on the very next run. See the Bootstrap-mode hygiene paragraph for the full mechanic; it applies regardless of whether the abort happened during a self-audit run or against an external target.

Bootstrap mode (running QPB on itself)

When the operator says "this is a bootstrap run" or "we're running QPB on itself" or "self-audit":

1. Confirm the working directory is the QPB repo root (or cd there).
2. Invoke python3 -m bin.run_playbook . — same canonical form, target is ..
3. The orchestrator handles archival of the existing quality/ tree to quality/previous_runs/<TIMESTAMP>/ automatically; you don't need to clean anything manually.

The run proceeds the same way as any other target. The only difference is that the audit subject IS the playbook itself, so the produced artifacts describe QPB's own quality system.

Bootstrap-run operator hygiene — recovering from a partial / aborted run. If a prior bootstrap run aborted mid-flight (e.g., the source-unchanged invariant tripped, a phase prompt errored, the operator hit Ctrl-C), the working tree may contain a half-written quality/ directory plus a quality/previous_runs/<TIMESTAMP>/.partial sentinel marking the abandoned archive. Before re-invoking, run git restore quality/ (and, if you want a clean slate, git clean -fd quality/) to drop any uncommitted Phase 1/2 output from the aborted run. The orchestrator will re-archive the now-pristine quality/ tree and start clean. Do NOT edit files outside quality/ to "tidy up" — anything outside quality/ is QPB source; touching it for cleanup will trip the source-unchanged invariant on the very next run. The 2026-04-30 bootstrap test surfaced this exact recovery question: the operator had a half-written quality/ from an aborted Phase 2 and re-running without restoring left stale Phase 1 artifacts that confused the next run's archival.

Guardrails (machine-checkable; treat as hard constraints)

These are not suggestions; the orchestrator enforces them and a violation aborts the run:

1. Synchronous execution — no sub-agent delegation. Run every phase yourself in the same session. Do NOT use the Task tool, sub-agent dispatch, background-agent invocations, the quality-playbook skill-invocation mechanism, or any "delegate phases 2–6 to a worker" pattern. Two verified failure modes the guardrail closes: (a) Phase 1 completes, phases 2–6 silently die in a delegated agent that loses its parent session, the runner self-marks -PARTIAL, and the operator gets no signal anything was wrong. (b) An interactive coding session spawns the quality-playbook orchestrator sub-skill; sub-skill runs Mode A in its own context but fabricates quality/results/quality-gate.log and reports "Gate: PASS" against an actual failing gate. The Phase 6 witness contract cannot enforce when the witness lives in a sub-skill's chat that the parent never sees. Phase 6 verification — mandatory sub-agent delegation: the no-sub-agent rule above governs Phase 1-5 EXECUTION (operator visibility). Phase 6 VERIFICATION is the opposite: it MUST run in a fresh-context sub-agent, because shared-context executor-as-verifier has empirically fabricated PASS verdicts against failing gates despite repeated rounds of strengthened witness language. Same principle (operator chat carries the truth), opposite mechanism (visibility for execution; bias-isolation for verification). Scoped strictly to Phase 6 verification — see phase_prompts/phase6.md + phase_prompts/phase6_auditor.md. Feature H persona pass — the second sanctioned exception: the automatic persona validation pass at the Phase 2→3 boundary (bin/persona_apply.run_feature_h) MAY spawn its fresh-context, tool-restricted personas — it is a bounded, operator-visible validation remediation (mandatory quality/expert_review_summary.json, every change agent-validation-tagged + revertible, opt-out), not a delegated phase, so neither failure mode (a) nor (b) applies. Scoped strictly to that pass (see the EXCEPTION block above); all OTHER Phase 1–5 sub-agent delegation stays forbidden.
2. Don't patch QPB source mid-run. If you encounter a bug in bin/, .github/skills/, agents/, references/, SKILL.md, or AGENTS.md during the run, STOP and report: name the file:line, describe the failure, propose a fix shape — but do NOT apply the fix. The orchestrator captures a git-SHA baseline at run start and verifies the source tree unchanged at every phase boundary; an autonomous patch fails the gate with a diagnostic naming the modified files. Patches go through Council review, not mid-run improvisation.
3. Don't delete sentinel files. Files protected by .gitignore !-rules (e.g., reference_docs/.gitkeep, reference_docs/cite/.gitkeep) keep otherwise-empty tracked directories present. The pre-flight check enumerates every !-rule and aborts if any sentinel is missing. If you find such a file and don't understand its purpose, leave it alone.
4. Phase 1 file enumeration uses git ls-files. Use git ls-files as the canonical file list when the target is a git repo; this respects .gitignore automatically. Do NOT use os.walk, find, os.listdir, or any recursive directory walker — those pull in .git/, .venv/, node_modules/, build outputs, and vendored dependencies, all of which the role-map validator rejects. Disallowed path prefixes are .git/, .venv/, venv/, node_modules/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, .tox/, plus any path whose components end in .egg-info or .dist-info. The role map carries a provenance field recording which enumeration source you used ("git-ls-files" or "filesystem-walk-with-skips" for non-git targets). There is also a 2000-entry ceiling; a role map exceeding it almost certainly walked .gitignored content.
5. Cross-artifact agreement. EXPLORATION.md's "File inventory" section and the role map's summary field both render from bin.role_map.summarize_role_map(). Don't write file counts or role percentages by hand; copy from the helper. The validator cross-checks the two and rejects mismatches.

If the operator's prompt says something that conflicts with these guardrails (e.g., "delegate phases 3–6 to a sub-agent so we can run faster"), don't comply with the conflicting instruction. Surface the conflict, name the guardrail, and ask for clarification. The guardrails exist because each one corresponds to a verified historical failure mode.

What this run produces — output artifact contract

A successful run produces this canonical set under the target's quality/ directory plus an AGENTS.md at the target's repo root. Every file listed here is gate-validated:

The gate verdict in quality/INDEX.md (pass / pass-with-cleanup / partial / fail) is the operator-facing summary of how the run went. The 089c F15 three-state taxonomy maps the gate's RESULT: line to this enum: RESULT: GATE PASSED → pass; RESULT: GATE PASSED WITH CLEANUP NEEDED → pass-with-cleanup (review completed, bug findings stand, only audit record-keeping incomplete — non-blocking); RESULT: GATE FAILED → fail (a substantive issue). partial covers aborted / WARN-only runs. If the verdict is anything other than pass, surface why before considering the run done; pass-with-cleanup is a successful outcome, but the State CN emit (per references/what_just_happened.md) walks the adopter through completing the remaining audit records.

quality/INDEX.md uses schema_version: "2.0" and carries a target_role_breakdown field with the per-role counts and percentages computed from quality/exploration_role_map.json. Pipelines activate from the role map's per-file role tags (skill-prose, skill-reference, skill-tool, code, test, docs, config, fixture, formal-spec, playbook-output) rather than a project-type label — the skill-derivation pipeline runs over files tagged skill-prose/skill-reference, the code-review pipeline runs over files tagged code, the prose-to-code divergence check runs over files tagged skill-tool, and when the role map shows zero of a role that pipeline no-ops cleanly. Both pipelines run when both surfaces are present.

Locating reference files

This skill references files in a references/ directory (e.g., references/iteration.md, references/review_protocols.md). The location depends on how the skill was installed. When a reference file is mentioned, resolve it by checking these paths in order and using the first one that exists (the canonical ten install layouts):

1. references/ (relative to SKILL.md — works when running from the skill directory or self-bootstrap)
2. .claude/skills/quality-playbook/references/ (Claude Code installation)
3. .github/skills/references/ (GitHub Copilot flat installation)
4. .cursor/skills/quality-playbook/references/ (Cursor installation)
5. .continue/skills/quality-playbook/references/ (Continue installation)
6. .github/skills/quality-playbook/references/ (alternate Copilot installation, nested)
7. .codex/skills/quality-playbook/references/ (Codex installation)
8. .windsurf/skills/quality-playbook/references/ (Windsurf installation)
9. .cline/skills/quality-playbook/references/ (Cline installation)
10. .aider/skills/quality-playbook/references/ (aider installation — aider does not auto-discover; tell aider to read SKILL.md explicitly)

All reference file mentions in this skill use the short form references/filename.md. If the relative path doesn't resolve, walk the fallback list above.

Council roster + adopter override

The Phase 4 Council of Three runs against a default 3-member roster defined in bin/council_config.py::DEFAULT_COUNCIL_MEMBERS — claude-opus-4.7, gpt-5.5, claude-sonnet-4.6. Adopters override per-operator via ~/.qpb/config.json (or $XDG_CONFIG_HOME/qpb/config.json); manage with python3 -m bin.qpb_config show|set|unset <key>. Per-run override via the --council-roster <m1,m2,m3> CLI flag takes highest precedence. See references/runners_and_models.md for the full override docs (precedence chain, model-availability behavior, falling back when a member is unavailable).

Why This Exists

Most software projects have tests, but few have a quality system. Tests check whether code works. A quality system answers harder questions: what does "working correctly" mean for this specific project? What are the ways it could fail that wouldn't be caught by tests? What should every developer (human or AI) know before touching this code?

Without a quality playbook, every new contributor (and every new AI session) starts from scratch — guessing at what matters, writing tests that look good but don't catch real bugs, and rediscovering failure modes that were already found and fixed months ago. A quality playbook makes the bar explicit, persistent, and inherited.

What This Skill Produces

Nine files that together form a repeatable quality system:

Plus output directories: `quality/code_revie

…(truncated)