akili-specs 2.4.2 → 2.5.0

package/.claude/commands/akili-validate.md

@@ -57,11 +57,12 @@ Use these result levels consistently:
    - `docs/specs/general-setup/`
    - package-level `CLAUDE.md` files if they exist
 2. Read spec context:
-   - `docs/specs/$ARGUMENTS/proposal.md` if present
+   - `docs/specs/$ARGUMENTS/proposal.md` if present. If it has a **Visual Reference** section, note the design source (Figma, an agent-generated mockup under `docs/specs/$ARGUMENTS/mockup/`, or a `.stitch/DESIGN.md` reference) so UI conformance can be audited against it, not only `docs/ux-ui/design.md`.
    - `docs/specs/$ARGUMENTS/requirements.md`
    - `docs/specs/$ARGUMENTS/design.md`
    - `docs/specs/$ARGUMENTS/tasks.md`
-   - `docs/specs/$ARGUMENTS/execution.md` if present
+   - `docs/specs/$ARGUMENTS/execution.md` if present (including any `## Constitution Impact` notes)
+   - `docs/specs/$ARGUMENTS/test-report.md` if present. **Reuse its evidence** — the requirement-to-test matrix and each suite's `PASS` / `FAIL` / `PRODUCT_BUG` status — instead of re-deriving coverage from scratch. This is a deliberate token saving: validate audits and cross-checks the recorded evidence rather than re-running the whole test analysis.
 
 ### Phase 1: Task Completion Check
 
@@ -92,6 +93,12 @@ For every requirement in `requirements.md`, verify:
 5. negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`) have been explicitly implemented and verified
 6. behavior matches the requirement intent, not only the task wording
 
+**Reuse `test-report.md` as the primary coverage evidence** when it exists. Cross-check its requirement-to-test matrix against `requirements.md` rather than re-deriving coverage, and carry its verdicts through:
+
+- A recorded `PRODUCT_BUG` (a correct test kept red on a real defect) is an unresolved failure → mark the affected requirement **FAIL**.
+- A `FAIL`, `GAP`, flaky, or `AUTOMATION_DEFERRED` entry without an accepted remediation → mark **WARN** (or FAIL if it covers a negative constraint or strict validation).
+- If `test-report.md` is missing or stale relative to the current code, note it and fall back to verifying coverage directly.
+
 ### Phase 5: Quality Audit
 
 Use skills as needed:
@@ -110,7 +117,7 @@ Check for:
 - API quality
 - frontend quality
 - design-system compliance
-- UX consistency with the UX/UI design document
+- UX consistency with the UX/UI design document, and with the proposal's **Visual Reference** (a Figma design or an agent-generated mockup) when the spec was designed against one
 - error handling and observability where relevant
 - accessibility and responsive behavior for UI work
 - security and authorization boundaries for protected flows
@@ -121,7 +128,9 @@ Compare the implementation against the module design and the constitutional docs
 
 If the implementation intentionally differs from the design, verify that the design or execution notes explain the change. Otherwise mark the drift as WARN or FAIL depending on risk.
 
-If `proposal.md` exists, also verify that final behavior remains aligned with the approved intent, scope, non-goals, and success criteria.
+If `proposal.md` exists, also verify that final behavior remains aligned with the approved intent, scope, non-goals, and success criteria. When the proposal has a **Visual Reference** (Figma or a generated mockup), confirm the delivered UI is consistent with it.
+
+**Agent Guide / Constitution Impact check (lightweight):** If `execution.md` contains `## Constitution Impact` notes (a task created or reshaped a module, moved a boundary, or changed a public surface), verify that the referenced child `CLAUDE.md`/`AGENTS.md` and the parent `## Module Guides` index are present and not stale. Do not perform a full guide-drift sweep here — that is `/akili-audit`'s job — but flag any unsynced guide as **WARN** and note it as pending work for `/akili-archive` (Constitution & Graph Sync).
 
 ### Phase 7: Generate Validation Report
 
@@ -138,8 +147,9 @@ The report must include:
 7. Linting & Code Quality
 8. Design Conformance
 9. Test Evidence Summary
-10. Remediation
-11. Archive Readiness Recommendation
+10. Agent Guide / Constitution Impact
+11. Remediation
+12. Archive Readiness Recommendation
 
 The report title must be `# Validation Report — {Spec Name}`.
 

package/.claude/templates/tester.md

@@ -0,0 +1,74 @@
+# Role: AKILI QA Tester
+
+You are the specialized **QA Tester** agentic team member in the AKILI-SPECS process.
+
+Your sole responsibility is to author and execute the **one test suite** assigned to you by the **Leader** (backend unit, frontend unit, integration, or E2E) for the active spec path, prove the behavior promised in `requirements.md`, and report structured results. You do **not** audit design-token conformance or architecture — that belongs to the Reviewer (`/akili-execute`) and the Validator (`/akili-validate`). Stay strictly inside your assigned suite and scope.
+
+> **Recommended model tier:** T2 Coder (maximum test-authoring throughput). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. When multiple models are available, prefer running on a **different model than the Implementer** that wrote the production code (author ≠ tester reduces confirmation bias).
+
+---
+
+## 🎯 Primary Instructions
+
+1.  **Strict Context Alignment (Prompt Caching & Skills):**
+    *   To maximize prompt caching, **FIRST** consult the project constitution (`CLAUDE.md`, `AGENTS.md`, `docs/trd/trd.md`, `docs/ux-ui/design.md`) in a consistent order before reading task-specific files.
+    *   Work only from the **slice** the Leader hands you: your assigned suite, its target requirements, and the Given/When/Then scenarios in scope. Do **not** pull the full spec set or unrelated source files unless strictly required to write a valid test.
+    *   **Skill Loading:** If the Leader assigns skills (e.g. `nestjs-expert`, `react-doctor`, `vercel-react-best-practices`, `systematic-debugging`, `ui-ux-pro-max`), load them with the `skill` tool **before** writing tests.
+2.  **Prove Behavior, Not Count (No Coverage Theater):**
+    *   Write focused tests that prove one behavior clearly over broad tests with unclear intent.
+    *   You **MUST** explicitly test the negative constraints (`BUT it must NOT`) and strict boundary validations (`AND IT MUST`) of every scenario in your slice.
+    *   Never mark a requirement covered just because related code exists. Cover it with an assertion or record it as an explicit gap.
+3.  **Incremental Focus (No Scope Creep):**
+    *   Author only your assigned suite. Do not refactor production code, redesign structure, or write tests for another suite's scope.
+    *   Prefer repository-specific test commands over hardcoded framework assumptions.
+4.  **Execution & Bounded Self-Correction Inner Loop:**
+    *   Run your suite with the project's real test command after writing.
+    *   If a test fails, decide the cause before retrying:
+        *   **Test defect** (bad assertion, wrong setup, flaky wiring) → fix the test and re-run. Bounded to **3 inner attempts**.
+        *   **Product defect** (the code genuinely violates the requirement) → do **NOT** rewrite the test to make it pass. Keep the failing test and report it as a `PRODUCT_BUG` finding to the Leader.
+    *   If a test is flaky, record the flake and do not treat it as passing evidence until stabilized.
+    *   If no automated test is practical for a scenario, document the manual verification steps and why automation was deferred — do not silently skip it.
+
+---
+
+## 📝 Structured Test Report Output
+
+Your report back to the Leader **must** conclude with exactly one status, plus a per-scenario coverage slice the Leader can drop into the requirement-to-test matrix.
+
+### Option A: PASS
+All assigned scenarios are covered and green.
+```text
+STATUS: PASS
+SUITE: (backend-unit | frontend-unit | integration | e2e)
+COMMAND: (the exact test command run, e.g. `npx vitest run src/loan`)
+EVIDENCE: (passing test output / counts)
+COVERAGE:
+- REQ-ID / Scenario → test file::test name → PASS
+```
+
+### Option B: FAIL
+Some assigned scenarios could not be proven green after the bounded inner loop, or coverage gaps remain.
+```text
+STATUS: FAIL
+SUITE: (...)
+COMMAND: (...)
+FINDINGS:
+1.  **Type:** TEST_GAP | FLAKY | AUTOMATION_DEFERRED
+    *   **Scenario:** (REQ-ID / scenario not proven)
+    *   **Detail:** (what is missing or unstable)
+    *   **Remediation:** (what is needed to close it)
+COVERAGE:
+- REQ-ID / Scenario → test file::test name → PASS | FAIL | GAP
+```
+
+### Option C: PRODUCT_BUG (Fail-Fast to Leader)
+A test correctly asserts the required behavior and the **production code fails it** — a real defect, not a test problem. Do not consume more inner attempts trying to "fix" the test.
+```text
+STATUS: PRODUCT_BUG
+SUITE: (...)
+COMMAND: (...)
+BUG:
+- **Violated Requirement:** (REQ-ID + scenario, cite requirements.md section)
+- **Failing Test:** (test file::test name — kept red on purpose)
+- **Observed vs Expected:** (actual behavior vs the required behavior)
+```

package/CHANGELOG.md

@@ -10,6 +10,21 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.5.0] - 2026-07-19
+
+### Added
+- **Request classification & Bug Track in `/akili-propose`:** `/akili-propose` is now the single entry point that classifies each request as **Bug**, **Change**, or **Trivial** (inferring from the request, asking one question when ambiguous) and routes it — no new per-type command. Bugs follow a diagnosis-first **Bug Track**: the proposal captures the observed symptom, reproduction steps, and a **confirmed root cause** (via `systematic-debugging`) in a new **Bug Diagnosis** section instead of the Requirement Delta Preview, and records `Type:` in Document Control.
+- **`/akili-specify` Bug Mode:** when a spec is a bug, specify frames requirements around the corrected behavior and **requires a regression test** as a mandatory task — red before the fix, green after — so a bug is provably fixed and stays fixed.
+- **`/akili-quick` trivial fast-track command:** A new single-step command for genuinely trivial, low-risk changes (button color, title text, small paragraph). It makes the edit directly, runs a light verification, records a one-line entry in `docs/specs/quick/quick-log.md`, and commits with a `[SPEC:quick/<name>]` prefix — skipping the full `requirements` → `design` → `tasks` → `execution` → `test-report` → `validation-report` set while preserving spec-to-code traceability. A strict triviality gate (cosmetic/copy-only, no behavior/data/API/auth/contract change, ≤ ~20 LOC in one component, design-token safe) **auto-escalates** anything larger to `/akili-specify` (Lite) or `/akili-propose`.
+- **`/akili-test` Leader → Tester(s) multi-agent harness:** `/akili-test` is no longer a single-agent script. The main session acts as a Leader that partitions testing into suites (backend unit, frontend unit, integration, E2E) and delegates each to a focused **Tester** subagent. A new `.agents/tester.md` persona (packaged under `.claude/templates/tester.md` and deployed by `/akili-constitution`) authors one suite from a thin per-suite context, explicitly covers negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`), runs a bounded 3-attempt self-correction inner loop, and emits a `PASS` / `FAIL` / `PRODUCT_BUG` contract — keeping a correct test red on a genuine product defect instead of rewriting it to pass.
+- **Token-aware Deployment Rule:** the Leader spawns the fewest Testers needed — inline (no spawn) for Lite/trivial single-suite work, one Tester per **independent** suite (in parallel when they touch different files), and sequential Testers when suites share files. Each Tester's context is discarded on completion so per-suite contexts never accumulate.
+- **Mockup fallback in `/akili-propose`:** When a UI change arrives with no Figma link, image, or existing design, the proposal step now offers an opt-in, recommended path to generate a mockup directly in the agent via the `stitch-design` skill. Accepted mockups are saved under `docs/specs/<spec-path>/mockup/` (or `.stitch/designs` / `.stitch/DESIGN.md`) and recorded in a new **Visual Reference** proposal section.
+
+### Changed
+- **`/akili-specify` consumes generated mockups:** The specify step now reads the proposal's **Visual Reference** and treats an agent-generated mockup (or `.stitch/DESIGN.md`) as approved visual design context — the same as a Figma link — driving the `Design Impact` guidance across requirements, design, and tasks.
+- **`/akili-validate` reuses test evidence and new context:** Validation now reads `test-report.md` and **reuses its requirement-to-test matrix and `PASS`/`FAIL`/`PRODUCT_BUG` verdicts** as primary coverage evidence instead of re-deriving it (a token saving that closes the test→validate loop); an unresolved `PRODUCT_BUG` forces a FAIL. Validation also audits UI against the proposal's **Visual Reference** (Figma or generated mockup) and adds a lightweight **Agent Guide / Constitution Impact** check that flags stale child guides / `## Module Guides` index as WARN for `/akili-archive`.
+- **Model routing for `/akili-test` split into Leader (T5) and Tester(s) (T2)**, with a note to prefer a Tester model different from the Implementer (author ≠ tester). Updated `docs/model-routing.md`, `/akili-constitution` scaffolding, and the docs hub accordingly.
+- **`/akili-constitution` now scaffolds four `.agents/` personas** (`leader`, `implementer`, `reviewer`, `tester`) and the installer deploys `tester.md` alongside the existing templates.
 ## [2.4.2] - 2026-07-19
 
 ### Changed

package/README.md

@@ -55,7 +55,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
 
 - `.claude/commands/` — custom AKILI-SPECS command prompts
 - `.claude/skills/` — required and preferred skills used by the methodology
-- `.claude/templates/` — default Leader, Implementer, and Reviewer personas used by the multi-agent harness (deployed into project `.agents/`)
+- `.claude/templates/` — default Leader, Implementer, Reviewer, and Tester personas used by the multi-agent harness (deployed into project `.agents/`)
 - `docs/` — human-facing documentation for the flow, CLI, commands, skills, and release process
 - `scripts/` — helper scripts referenced by commands (e.g. `gsc_verify.py`)
 - `.mcp.json.example` — reference MCP server configuration (e.g. `gsc`)
@@ -104,6 +104,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `leader.md`
   - `implementer.md`
   - `reviewer.md`
+  - `tester.md`
 - `docs/`
   - `flow.md`
   - `cli.md`
@@ -261,7 +262,7 @@ For Claude, the installer writes:
 ~/.claude/commands/
 ~/.claude/skills/
 ~/.claude/akili/scripts/
-~/.claude/akili/templates/      (leader, implementer, reviewer personas used by /akili-constitution)
+~/.claude/akili/templates/      (leader, implementer, reviewer, tester personas used by /akili-constitution)
 ~/.claude/akili/.mcp.json.example
 ```
 
@@ -501,6 +502,7 @@ See the full [Command Reference](docs/commands/README.md) for detailed pages per
 |---|---|---|
 | `/akili-constitution` | Starting a repo or repairing weak project context | `docs/prd.md`, UX/UI design, TRD, `docs/infrastructure.md`, general spec templates, `CLAUDE.md`, `AGENTS.md` guidance |
 | `/akili-propose <change-name-or-spec-path>` | Aligning on intent before full specification (supports Figma/Jira MCP context) | `proposal.md` under `docs/specs/<spec-path>/` |
+| `/akili-quick <change-name>` | Making a genuinely trivial, low-risk change (button color, title text, small paragraph) fast | The edit + a one-line entry in `docs/specs/quick/quick-log.md` and a `[SPEC:quick/<name>]` commit |
 | `/akili-specify <spec-path>` | Planning one bounded change before code | `requirements.md`, `design.md`, `tasks.md` under `docs/specs/<spec-path>/` (includes Design Impact injection, LOC estimation and HITL menus) |
 | `/akili-execute <spec-path>` | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
 | `/akili-test <spec-path>` | Adding or running test evidence | `test-report.md` with requirement-to-test traceability |
@@ -516,12 +518,13 @@ Use the lightest documentation that still makes the work clear and verifiable.
 
 | Work Type | Recommended Depth | What To Capture |
 |---|---|---|
+| Trivial cosmetic / copy tweak (button color, title text, small paragraph) | `/akili-quick` (no spec docs) | One-line log entry + `[SPEC:quick/<name>]` commit; auto-escalates if not actually trivial |
 | Small bugfix or UI tweak | Lite | Problem, affected requirement, scenario, focused task, verification command |
 | Normal feature | Standard | Requirements, scenarios, design decisions, task breakdown, tests |
 | High-risk change | Full | Business context, alternatives, data/API contracts, rollout, risks, observability, rollback |
 | Cross-cutting architecture | Full plus constitution review | Updates to project baseline docs and affected specs |
 
-Lite mode does not skip rigor. It keeps the documents short, but every requirement still needs a testable scenario and every task still needs a done criterion.
+Lite mode does not skip rigor. It keeps the documents short, but every requirement still needs a testable scenario and every task still needs a done criterion. `/akili-quick` is the one path that skips the spec documents entirely — reserved for genuinely trivial changes, with a strict gate that escalates anything bigger.
 
 ## Core Concepts
 
@@ -720,18 +723,18 @@ Fallback rule:
 ## Methodology Contract
 
 - **User-Facing Summaries:** All major commands (`/akili-propose`, `/akili-specify`, `/akili-execute`, `/akili-validate`, `/akili-test`, `/akili-constitution`) generate a short, digestible summary on the screen before proceeding to the next step, ensuring developers always understand what the agent just did.
-- `/akili-constitution` establishes the project baseline docs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`, `docs/infrastructure.md`) and `docs/specs/general-setup/` templates, and scaffolds the project `.agents/` harness (Leader, Implementer, Reviewer).
+- `/akili-constitution` establishes the project baseline docs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`, `docs/infrastructure.md`) and `docs/specs/general-setup/` templates, and scaffolds the project `.agents/` harness (Leader, Implementer, Reviewer, Tester).
 - `/akili-propose` creates a lightweight proposal before full specification. Evaluates massive instructions for **Scope Chunking** to split work into manageable modules. Integrates with **Figma MCP** and **Jira MCP** to extract visual context, requirements, and user stories.
 - `/akili-specify` must follow those templates when generating module specs. Enforces **Human-in-the-loop (HITL)** approval pauses after Requirements, Design, and Tasks. Promotes rigorous BDD scenarios (`BUT it must NOT`, `AND IT MUST`), allows blind adversarial design reviews via the `judgment-day` skill, outputs a final **Lines of Code (LOC) estimate** to recommend a safe Pull Request strategy, and explicitly injects **Design Impact** rules (from Figma contexts) into UI tasks and components.
 - `/akili-execute` orchestrates a Leader → Implementer → Reviewer rework loop (max 3 retries) to implement tasks from an approved spec path.
-- `/akili-test` validates requirement-to-test traceability, explicitly checking for negative constraints and strict boundaries.
+- `/akili-test` runs a Leader → Tester(s) harness: the Leader partitions testing into suites and delegates each to a Tester subagent (inline for trivial/Lite work; one Tester per independent suite, in parallel, otherwise). It validates requirement-to-test traceability, explicitly checking for negative constraints and strict boundaries.
 - `/akili-validate` audits implementation conformance against the spec (including rigorous boundary validations) and constitutional baseline.
 - `/akili-archive` preserves completed specs under `docs/specs/archive/` after validation, syncs agent guides (child `CLAUDE.md`/`AGENTS.md` + the parent `## Module Guides` index) from the spec's `## Constitution Impact` notes, and recommends a CodeGraph re-index.
 - `/akili-seo` operates outside the main spec lifecycle: it provisions Google Search Console ownership for a domain and produces a standalone SEO audit under `docs/specs/seo/<domain>/`. Run it any time after deployment; rerun after major content or schema changes.
 
 ## Multi-Agent Harness Engineering
 
-`/akili-execute` is not a single-agent script. It is a coordinated triad of specialized roles that share the same spec, the same constitution, and the same audit trail. The harness exists to remove confirmation bias from review (an independent auditor instead of the same agent that wrote the code), to keep each role's context window small and focused, and to enforce design-token and constitutional discipline through a hard PASS/FAIL gate.
+`/akili-execute` and `/akili-test` are not single-agent scripts. Each is a coordinated set of specialized roles that share the same spec, the same constitution, and the same audit trail. The harness exists to remove confirmation bias from review and testing (an independent auditor/tester instead of the same agent that wrote the code), to keep each role's context window small and focused, and to enforce design-token and constitutional discipline through a hard PASS/FAIL gate.
 
 Roles live in the project's `.agents/` directory (scaffolded by `/akili-constitution`):
 
@@ -740,6 +743,7 @@ Roles live in the project's `.agents/` directory (scaffolded by `/akili-constitu
 | Leader | `.agents/leader.md` | Orchestration. Picks the next eligible task, delegates, enforces the rework loop, updates `tasks.md` and `execution.md`, commits with `[SPEC:<spec-path>]`. |
 | Implementer | `.agents/implementer.md` | Writes and tests the code. Strictly task-scoped, must follow design tokens from `docs/ux-ui/design.md`, must run the verification command before reporting. |
 | Reviewer | `.agents/reviewer.md` | Read-only spec audit. Compares the diff against requirements, design tokens, the TRD, and stability. Outputs a structured PASS or FAIL with *Discovered Issue*, *Violated Rule*, and *Remediation Suggestion* for each finding. |
+| Tester | `.agents/tester.md` | Authors and runs **one** test suite (backend unit, frontend unit, integration, or E2E) from a thin per-suite context. Explicitly covers negative constraints and strict validations, runs a bounded 3-attempt self-correction inner loop, and emits `PASS`/`FAIL`/`PRODUCT_BUG` — keeping a correct test red on a real product defect instead of rewriting it. |
 
 The Leader runs each task through this loop:
 
@@ -761,11 +765,13 @@ if 3 consecutive FAILs → HALT, mark task [~], present full audit trail for hum
 - **Pivot protocol.** If discovery proves the spec itself is wrong (not the implementation), the loop stops immediately and a `## Pivot Record` is opened in `execution.md` for user sign-off — rework retries are not consumed on a broken spec.
 - **Cross-tool.** `.agents/` is pure Markdown + YAML frontmatter and is resolved relative to the active workspace, so the same harness runs under Claude Code, OpenCode, and Google Antigravity (the latter invokes `invoke_subagent` using the same persona files).
 
+**`/akili-test` — Leader → Tester(s):** The same Leader pattern drives testing, but delegation is token-aware. The Leader partitions the work into suites and applies a **Deployment Rule**: Lite depth or a single trivial suite runs **inline** (no subagent spawn — spawning would cost more tokens than it saves); Standard/Full depth or multiple **independent** suites get **one Tester per suite**, spawned **in parallel** when they touch different files, and sequentially when they share files/fixtures. Each Tester receives only its suite's requirements, scenarios, and test command — never the full spec set — and its context is discarded on completion, so per-suite contexts never accumulate. A Tester runs a bounded 3-attempt inner loop and distinguishes a **test defect** (fix the test) from a **product defect** (keep the test red, report `PRODUCT_BUG`). Ideally a Tester runs on a different model than the Implementer that wrote the code (author ≠ tester).
+
 `/akili-constitution` classifies the repository into one of three modes and seeds `.agents/` accordingly:
 
 | Mode | When | `.agents/` Behavior |
 |---|---|---|
-| Brand-new | No code, no docs | Copies the default Leader/Implementer/Reviewer templates verbatim |
+| Brand-new | No code, no docs | Copies the default Leader/Implementer/Reviewer/Tester templates verbatim |
 | Legacy | Real code, no AKILI-SPECS baseline | Copies defaults and customizes them with detected stack, design tokens, lint and test commands |
 | Active AKILI-SPECS | Baseline already exists | Preserves customized `.agents/` files in place and only upgrades or fills gaps non-destructively |
 

package/bin/akili.js

@@ -12,7 +12,7 @@ const SOURCE_CLAUDE = path.join(PACKAGE_ROOT, ".claude");
 const SOURCE_COMMANDS = path.join(SOURCE_CLAUDE, "commands");
 const SOURCE_SKILLS = path.join(SOURCE_CLAUDE, "skills");
 const SOURCE_TEMPLATES = path.join(SOURCE_CLAUDE, "templates");
-const AGENT_TEMPLATES = ["leader.md", "implementer.md", "reviewer.md"];
+const AGENT_TEMPLATES = ["leader.md", "implementer.md", "reviewer.md", "tester.md"];
 const RESOURCE_SCRIPTS = ["gsc_verify.py", "parse_tests.js"];
 const SOURCE_SCRIPTS = path.join(PACKAGE_ROOT, "scripts");
 const SOURCE_MCP_EXAMPLE = path.join(PACKAGE_ROOT, ".mcp.json.example");

package/docs/README.md

@@ -47,6 +47,6 @@ Use `/akili-seo <site-domain>` independently when you need Google Search Console
 
 - Command implementation prompts: `.claude/commands/*.md`
 - Skill implementation prompts: `.claude/skills/*/SKILL.md`
-- Multi-agent harness templates: `.claude/templates/{leader,implementer,reviewer}.md` (deployed into each project's `.agents/` by `/akili-constitution`)
+- Multi-agent harness templates: `.claude/templates/{leader,implementer,reviewer,tester}.md` (deployed into each project's `.agents/` by `/akili-constitution`)
 - CLI implementation: `bin/akili.js`
 - Release automation: `scripts/release.js` and `scripts/release-status.js`

package/docs/cli.md

@@ -94,7 +94,7 @@ Claude install layout:
 ~/.claude/commands/
 ~/.claude/skills/
 ~/.claude/akili/scripts/
-~/.claude/akili/templates/      (leader.md, implementer.md, reviewer.md — used by /akili-constitution to scaffold project .agents/)
+~/.claude/akili/templates/      (leader.md, implementer.md, reviewer.md, tester.md — used by /akili-constitution to scaffold project .agents/)
 ~/.claude/akili/.mcp.json.example
 ```
 
@@ -114,7 +114,7 @@ Antigravity install layout:
 ~/.gemini/antigravity/global_workflows/  (custom commands mapped as global workflows)
 ~/.gemini/config/skills/                 (skills mapped as global skills)
 ~/.gemini/config/akili/scripts/         (scripts mapped as config resources)
-~/.gemini/config/akili/templates/       (multi-agent harness templates: leader, implementer, reviewer)
+~/.gemini/config/akili/templates/       (multi-agent harness templates: leader, implementer, reviewer, tester)
 ~/.gemini/config/akili/.mcp.json.example
 ```
 
@@ -170,6 +170,7 @@ The CLI installs helper resources under the target `akili/` directory:
 | `templates/leader.md` | Default Leader (Orchestrator) persona for the multi-agent harness — copied into project `.agents/` by `/akili-constitution` |
 | `templates/implementer.md` | Default Implementer persona for the multi-agent harness |
 | `templates/reviewer.md` | Default Reviewer persona for the multi-agent harness |
+| `templates/tester.md` | Default Tester persona for the `/akili-test` Leader → Tester(s) harness — copied into project `.agents/` by `/akili-constitution` |
 | `.mcp.json.example` | Example MCP config for the Google Search Console MCP server |
 
 ## Troubleshooting

package/docs/commands/README.md

@@ -8,9 +8,10 @@ AKILI commands are installed as slash-command prompts for Claude Code and OpenCo
 |---|---|---|
 | [`/akili-constitution`](akili-constitution.md) | Starting a repo or repairing weak project context | Project baseline docs, `CLAUDE.md`, `AGENTS.md`, general spec templates, and the `.agents/` multi-agent harness |
 | [`/akili-propose <change-name-or-spec-path>`](akili-propose.md) | Aligning on intent before full specification | `proposal.md` under `docs/specs/<spec-path>/` |
+| [`/akili-quick <change-name>`](akili-quick.md) | Making a genuinely trivial, low-risk change (copy edit, color/text tweak) fast | The edit + a one-line entry in `docs/specs/quick/quick-log.md` and a `[SPEC:quick/<name>]` commit |
 | [`/akili-specify <spec-path>`](akili-specify.md) | Planning one bounded change before code | `requirements.md`, `design.md`, `tasks.md` |
 | [`/akili-execute <spec-path>`](akili-execute.md) | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code/docs changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
-| [`/akili-test <spec-path>`](akili-test.md) | Proving behavior with test evidence | `test-report.md` |
+| [`/akili-test <spec-path>`](akili-test.md) | Proving behavior with test evidence via the Leader → Tester(s) harness | `test-report.md` |
 | [`/akili-validate <spec-path>`](akili-validate.md) | Auditing conformance before completion | `validation-report.md` |
 | [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` |
 | [`/akili-audit`](akili-audit.md) | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
@@ -29,7 +30,7 @@ AKILI commands are installed as slash-command prompts for Claude Code and OpenCo
 /akili-archive <spec-path>
 ```
 
-You can skip `/akili-propose` for very small, obvious work. You should not skip validation before archiving unless the user explicitly accepts the risk.
+You can skip `/akili-propose` for very small, obvious work. For a genuinely trivial, low-risk change (a button color, a title's text, a small paragraph) use `/akili-quick <change-name>`, which makes the edit in one step with minimal traceability and auto-escalates to `/akili-specify` (Lite) or `/akili-propose` if the change turns out to be bigger than trivial. You should not skip validation before archiving unless the user explicitly accepts the risk.
 
 Run `/akili-audit` independently to detect drift between specs and codebase reality at any time.
 
@@ -39,6 +40,7 @@ Run `/akili-audit` independently to detect drift between specs and codebase real
 |---|---|
 | `/akili-constitution` | `.claude/commands/akili-constitution.md` |
 | `/akili-propose` | `.claude/commands/akili-propose.md` |
+| `/akili-quick` | `.claude/commands/akili-quick.md` |
 | `/akili-specify` | `.claude/commands/akili-specify.md` |
 | `/akili-execute` | `.claude/commands/akili-execute.md` |
 | `/akili-test` | `.claude/commands/akili-test.md` |

package/docs/commands/akili-constitution.md

@@ -43,6 +43,7 @@ Creates or enhances:
 - `.agents/leader.md`
 - `.agents/implementer.md`
 - `.agents/reviewer.md`
+- `.agents/tester.md`
 
 Projects created before the TRD naming may still have `docs/system-design/design.md` (UX/UI blueprint) and `docs/detailed-design/detailed-design.md` (technical blueprint). The constitution treats those as the existing UX/UI Design document and TRD, and in Active-AKILI-SPECS mode offers to migrate them to `docs/ux-ui/design.md` and `docs/trd/trd.md`.
 
@@ -50,11 +51,11 @@ The root guides also carry a `## Module Guides` index: modules whose conventions
 
 ## Multi-Agent Harness Scaffolding
 
-`.agents/` is the source of truth for the multi-agent loop that `/akili-execute` runs (Leader → Implementer → Reviewer). The constitution seeds it from the packaged defaults shipped by the installer:
+`.agents/` is the source of truth for the multi-agent harness: the loop that `/akili-execute` runs (Leader → Implementer → Reviewer) and the Leader → Tester(s) harness that `/akili-test` runs. The constitution seeds it from the packaged defaults shipped by the installer:
 
-- Claude Code: `~/.claude/akili/templates/{leader,implementer,reviewer}.md`
-- OpenCode: `~/.config/opencode/akili/templates/{leader,implementer,reviewer}.md`
-- Antigravity: `~/.gemini/config/akili/templates/{leader,implementer,reviewer}.md`
+- Claude Code: `~/.claude/akili/templates/{leader,implementer,reviewer,tester}.md`
+- OpenCode: `~/.config/opencode/akili/templates/{leader,implementer,reviewer,tester}.md`
+- Antigravity: `~/.gemini/config/akili/templates/{leader,implementer,reviewer,tester}.md`
 
 If packaged templates are not available, the constitution drafts equivalent personas inline using the structure documented in `/akili-execute` (rework loop, PASS/FAIL output contract, AKILI commit standard, Pivot Protocol).
 

package/docs/commands/akili-propose.md

@@ -31,6 +31,19 @@ Bare names default to `changes/<name>`. Paths containing `/` are used as provide
 - Scope, non-goals, risks, or affected systems are uncertain.
 - Multiple implementation approaches are possible.
 - Existing behavior may need added, modified, or removed requirements.
+- A **bug** needs its root cause diagnosed before a fix is planned.
+
+## Request Classification & Routing
+
+`/akili-propose` is the single entry point that classifies the request and routes it — so the methodology does not need a separate command per work type. It infers the type from the request (and asks one short question if ambiguous):
+
+| Type | Route |
+|---|---|
+| **Trivial** (cosmetic/copy tweak) | Recommends `/akili-quick <name>` instead of a full proposal |
+| **Feature / Change** | Standard proposal → `/akili-specify` |
+| **Bug** | **Bug Track**: diagnose first (reproduction + confirmed root cause via `systematic-debugging`) in the proposal, then `/akili-specify` in **Bug Mode** with a mandatory regression test |
+
+The detected type is recorded as `Type: Bug | Change | Trivial` in the proposal's Document Control so `/akili-specify` inherits it.
 
 ## Output
 
@@ -42,20 +55,31 @@ docs/specs/<spec-path>/proposal.md
 
 ## Proposal Sections
 
-- Document Control
+- Document Control (records `Type: Bug | Change | Trivial`)
 - Intent
 - Problem / Current Behavior
 - Proposed Outcome
 - Scope
 - Non-Goals
 - Affected Users, Systems, And Specs
-- Requirement Delta Preview
+- Visual Reference
+- Bug Diagnosis (Bug track) *or* Requirement Delta Preview (Change track)
 - Approach Options
 - Recommended Approach
 - Risks, Dependencies, And Open Questions
 - Success Criteria
 - Next Step
 
+## Bug Track
+
+For a bug, the proposal replaces the Requirement Delta Preview with a **Bug Diagnosis** produced with the `systematic-debugging` skill: observed symptom, reproduction steps, **confirmed** root cause (not a guess), impact/scope, and a fix strategy. No fix is proposed until the root cause is confirmed. The fix then routes by size — a purely cosmetic one-liner to `/akili-quick`, anything with logic to `/akili-specify` (Lite) in Bug Mode, which requires a regression test (red before the fix, green after).
+
+## Visual Input & Mockup Fallback
+
+During intent clarification the command asks for the requirement source (e.g. Jira MCP) and any visual design (Figma MCP).
+
+When the change has a UI surface and **no** Figma link, image, or existing design is provided, the command offers an **opt-in, recommended** fallback: generate a mockup directly in the agent using the `stitch-design` skill (Stitch MCP). Accepted mockups are saved under `docs/specs/<spec-path>/mockup/` (or the `.stitch/designs` / `.stitch/DESIGN.md` location) and recorded in the proposal's **Visual Reference** section. This mockup then counts as approved visual design context for `/akili-specify`, exactly like a Figma link. The user can always decline and continue without a visual.
+
 ## Next Step
 
 After approval:

package/docs/commands/akili-quick.md

@@ -0,0 +1,54 @@
+# `/akili-quick`
+
+Fast-track a genuinely trivial, low-risk change in one step, with minimal traceability and automatic escalation when the change is not actually trivial.
+
+## Usage
+
+```text
+/akili-quick <short-change-name> [free-text description]
+```
+
+Examples:
+
+```text
+/akili-quick login-button-color make the primary login button use the brand accent token
+/akili-quick hero-title fix the typo in the homepage hero title
+/akili-quick pricing-paragraph add a short paragraph under the pricing table
+```
+
+## Use When
+
+- The change is cosmetic or copy-only: text/label edits, color/spacing/style-token tweaks, small static markup additions.
+- It changes no behavior, data, API, auth, or shared contract.
+- It is small and local (~≤ 20 LOC, one component/file).
+- Any visual change uses an existing approved token from `docs/ux-ui/design.md`.
+
+Do **not** use it for real features, logic changes, bugfixes with behavior impact, or anything that introduces a new design token or pattern.
+
+## Triviality Gate & Escalation
+
+Before editing, the command checks all gate criteria. If any fails, it **stops and escalates**:
+
+- Small but with logic, or a real bugfix → `/akili-specify <spec-path>` (Lite).
+- A **bug** whose fix touches logic/behavior → `/akili-propose <name>` (Bug Track: diagnose the root cause first), then `/akili-specify` (Lite) in Bug Mode with a mandatory regression test. A purely cosmetic bug (e.g. a visible typo) may stay in `/akili-quick`.
+- Non-trivial, risky, cross-cutting, or uncertain → `/akili-propose <change-name>`.
+- Needs a new design token/pattern → `/akili-propose` or `/akili-specify` so the token is designed, not improvised.
+
+## Output
+
+- The edit applied to the target file(s).
+- A one-line entry appended to `docs/specs/quick/quick-log.md` (date, change, files, verification, commit).
+- A commit prefixed `[SPEC:quick/<change-name>]`.
+
+It does **not** create `requirements.md`, `design.md`, `tasks.md`, `execution.md`, `test-report.md`, or `validation-report.md`.
+
+## Key Rules
+
+- Traceability is not optional: every quick change gets a `[SPEC:quick/<name>]` commit and a log line.
+- Respect design tokens — never hardcode a new value to "just make it match"; use the token or escalate.
+- One change per invocation.
+- When in doubt about triviality, escalate.
+
+## Next Step
+
+None required — the change is committed. If follow-up work grows beyond a trivial tweak, move it to `/akili-propose` or `/akili-specify`.

package/docs/commands/akili-specify.md

@@ -58,6 +58,8 @@ docs/specs/<spec-path>/tasks.md
 - Key requirements include Given/When/Then scenarios.
 - Design extends the current architecture instead of replacing it.
 - Tasks reference requirements, design sections, dependencies, done criteria, verification, and relevant skills.
+- Any visual design context in the proposal — a Figma link, an agent-generated mockup under `docs/specs/<spec-path>/mockup/`, or a `.stitch/DESIGN.md` reference — is treated as approved input and drives the `Design Impact` guidance across requirements, design, and tasks.
+- **Bug Mode:** when the spec is a bug (`Type: Bug`, a `bugfix/*` path, or framed as a defect), specify frames requirements around the corrected behavior from the confirmed root cause and **requires a regression test** — at least one task adds a test that is red before the fix and green after. The root cause is confirmed with `systematic-debugging` if no proposal diagnosis exists.
 - The user approves requirements, design, and tasks before implementation begins.
 
 ## Next Step

package/docs/commands/akili-test.md

@@ -1,6 +1,6 @@
 # `/akili-test`
 
-Run or create tests for a spec path and produce requirement-level evidence.
+Run or create tests for a spec path and produce requirement-level evidence, using the AKILI **Leader → Tester(s)** multi-agent harness.
 
 ## Usage
 
@@ -14,6 +14,17 @@ Run or create tests for a spec path and produce requirement-level evidence.
 - You need a requirement-to-test matrix.
 - Manual gaps must be documented explicitly.
 
+## Multi-Agent Harness
+
+The main session acts as the **Leader** (orchestrator). It partitions testing into suites (backend unit, frontend unit, integration, E2E) and delegates each to a focused **Tester** subagent defined in `.agents/tester.md`, then aggregates the structured reports.
+
+- **Deployment Rule (token-aware):** Lite depth or a single trivial suite runs **inline** (no spawn); Standard/Full or multiple independent suites get **one Tester per suite**, spawned **in parallel** when they touch different files. Suites that share files run sequentially. The Leader picks the fewest spawns that keep each context small.
+- **Thin context per Tester:** each Tester gets only its suite's requirements, scenarios, and test command — never the full spec set — and its context is discarded on completion, so per-suite contexts never accumulate.
+- **Author ≠ tester:** Testers prefer a different model than the Implementer that wrote the code, reducing confirmation bias.
+- Each Tester reports one status — `PASS`, `FAIL`, or `PRODUCT_BUG` — plus a per-scenario coverage slice. A `PRODUCT_BUG` keeps a correct test red instead of rewriting it to pass.
+
+If `.agents/tester.md` is missing, run `/akili-constitution` first to scaffold it.
+
 ## Inputs
 
 Reads:
@@ -21,6 +32,7 @@ Reads:
 - `docs/specs/<spec-path>/requirements.md`
 - `docs/specs/<spec-path>/design.md`
 - `docs/specs/<spec-path>/tasks.md`
+- `.agents/tester.md`
 - project-level constitution docs and agent guidance
 
 ## Outputs

package/docs/commands/akili-validate.md

@@ -48,9 +48,10 @@ docs/specs/<spec-path>/validation-report.md
 - task completion and execution notes
 - expected file existence
 - build, lint, and type-check integrity
-- requirement coverage
+- requirement coverage — **reuses `test-report.md`** as the primary evidence (its requirement-to-test matrix and `PASS`/`FAIL`/`PRODUCT_BUG` verdicts) instead of re-deriving coverage; an unresolved `PRODUCT_BUG` forces a FAIL
 - test evidence summary
-- architecture and design conformance
+- architecture and design conformance, including UI consistency with the proposal's **Visual Reference** (Figma or a generated mockup) when the spec was designed against one
+- a lightweight **Agent Guide / Constitution Impact** check: if `execution.md` records module-boundary changes, confirm the child guides and the parent `## Module Guides` index are not stale (flagged WARN and left for `/akili-archive`)
 - UI/UX, API, security, accessibility, error handling, and observability as relevant
 
 ## Next Step