akili-specs 2.4.2 → 2.5.0

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

@@ -31,7 +31,7 @@ For all three modes:
 3. Ensure `docs/specs/general-setup/` exists.
 4. Ensure root `CLAUDE.md` exists or is enhanced.
 5. Ensure root `AGENTS.md` exists or is enhanced.
-6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, and `reviewer.md` (see Step 7B).
+6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 7B).
 7. Default behavior is to enhance existing project docs in place instead of creating parallel copies.
 
 The constitutional baseline must cover these files:
@@ -48,6 +48,7 @@ The constitutional baseline must cover these files:
 - `.agents/leader.md`
 - `.agents/implementer.md`
 - `.agents/reviewer.md`
+- `.agents/tester.md`
 
 **Mode-specific drafting policy:**
 
@@ -301,9 +302,9 @@ This index is what keeps agent context inheritance working: agents load the root
 
 ---
 
-### Step 8B: Scaffold the `.agents/` Triad
+### Step 8B: Scaffold the `.agents/` Personas
 
-Establish or upgrade the project-level `.agents/` directory that powers the AKILI multi-agent execution loop (Leader → Implementer → Reviewer used by `/akili-execute`).
+Establish or upgrade the project-level `.agents/` directory that powers the AKILI multi-agent harness: the Leader → Implementer → Reviewer loop used by `/akili-execute`, and the Leader → Tester(s) harness used by `/akili-test`.
 
 Target layout:
 
@@ -312,23 +313,24 @@ Target layout:
 ├── .agents/
 │   ├── leader.md        # Orchestration playbook, task tracking, .agents references
 │   ├── implementer.md   # Coding guidelines, testing standards, design-token discipline
-│   └── reviewer.md      # Spec conformance audit, design-token compliance, structured FAIL output
+│   ├── reviewer.md      # Spec conformance audit, design-token compliance, structured FAIL output
+│   └── tester.md        # Per-suite QA authoring/execution, bounded inner loop, PASS/FAIL/PRODUCT_BUG output
 ```
 
 **Source of truth for templates:**
 
 The packaged methodology ships default personas under `akili/templates/` inside the active tool's config directory:
 
-- 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 the packaged templates are available, prefer copying them as the seed; otherwise draft equivalent personas inline using the structure documented in this command and the `/akili-execute` command.
+If the packaged templates are available, prefer copying them as the seed; otherwise draft equivalent personas inline using the structure documented in this command and the `/akili-execute` and `/akili-test` commands.
 
 **Mode-specific scaffolding policy:**
 
-- **Brand-new (Seed Setup):** copy the three default templates verbatim into `.agents/`. Tailor only the project name and detected stack if known.
-- **Legacy (Discovery Setup):** copy the three default templates, then customize them based on the codebase scan — inject detected design-token paths, the test command, the lint command, framework conventions, and any directory boundaries discovered. The Reviewer persona in particular should know which `design.md` and `trd.md` paths to cite.
+- **Brand-new (Seed Setup):** copy the four default templates verbatim into `.agents/`. Tailor only the project name and detected stack if known.
+- **Legacy (Discovery Setup):** copy the four default templates, then customize them based on the codebase scan — inject detected design-token paths, the test command, the lint command, framework conventions, and any directory boundaries discovered. The Reviewer persona should know which `design.md` and `trd.md` paths to cite; the Tester persona should know the repo's real test runner and command.
 - **Active AKILI-SPECS (Safe Update):** **do not overwrite** existing `.agents/*.md` files. For each missing file, install the default template (customized to the detected stack). For each existing file, read it, identify gaps versus the current packaged template (e.g. missing rework-loop instructions, missing PASS/FAIL output contract, missing AKILI commit standard), and append a minimal upgrade block that preserves all existing custom instructions.
 
 **Required content per persona:**
@@ -336,6 +338,7 @@ If the packaged templates are available, prefer copying them as the seed; otherw
 - **`leader.md`** — orchestration sequence, rework loop with 3-attempt ceiling, structured FAIL handoff to the next Implementer spawn, `execution.md` audit-trail format, `tasks.md` status transitions, AKILI commit standard, Pivot Protocol escalation.
 - **`implementer.md`** — strict context alignment to constitution + spec, incremental focus (no scope creep), aesthetics and design-token compliance from `docs/ux-ui/design.md`, verification rigor (must run the task's verification command before reporting), structured completion report.
 - **`reviewer.md`** — read-only role, audit checklist (requirement conformance, design-token compliance, technical compliance, stability), structured PASS/FAIL output where every FAIL item lists *Discovered Issue*, *Violated Rule*, and *Remediation Suggestion*.
+- **`tester.md`** — single-suite scope (backend unit, frontend unit, integration, or E2E), thin per-suite context, explicit coverage of negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`), bounded self-correction inner loop (max 3), distinction between a test defect (fix the test) and a product defect (keep the test red, report `PRODUCT_BUG`), and structured `PASS`/`FAIL`/`PRODUCT_BUG` output with a per-scenario coverage slice. Author ≠ tester: prefer a different model than the Implementer.
 
 **Cross-tool compatibility:**
 
@@ -367,7 +370,9 @@ project guides so the project does not depend on the package's `docs/` after ins
    T6 Multimodal) with one-line definitions.
 3. The phase→tier mapping for the real AKILI phases, with the `/akili-execute` triad split into
    Leader (T5), Implementer (T2), and Reviewer (T3), and an explicit note that the Reviewer model
-   must differ from the Implementer model.
+   must differ from the Implementer model. `/akili-test` is likewise split into its Leader (T5,
+   orchestration) and Tester(s) (T2, test authoring), with a note to prefer a Tester model different
+   from the Implementer (author ≠ tester).
 4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`.
    Fill the Claude Code column for the user's plan (e.g. PRO: Opus reserved for T1/T3, Sonnet as the
    T2/T4/T6 workhorse, Haiku for T5). Fill the OpenCode column from the user's confirmed roster; if
@@ -410,4 +415,4 @@ Ask the user whether to approve or request changes. If changes are requested, re
 
 ## Outcome
 
-At the end of `/akili-constitution`, the repository should have a project-level baseline that future `/akili-specify`, `/akili-execute`, `/akili-validate`, and `/akili-test` work can rely on without guessing the structure or conventions. The `.agents/` triad must be in place so that `/akili-execute` can run the Leader → Implementer → Reviewer rework loop without falling back to inline personas. The root guides must also carry a `## Model Routing` registry (Step 8C) so each phase runs on a model matched to its demand, with the Reviewer on a different model than the Implementer.
+At the end of `/akili-constitution`, the repository should have a project-level baseline that future `/akili-specify`, `/akili-execute`, `/akili-validate`, and `/akili-test` work can rely on without guessing the structure or conventions. The `.agents/` personas must be in place so that `/akili-execute` can run the Leader → Implementer → Reviewer rework loop and `/akili-test` can run the Leader → Tester(s) harness without falling back to inline personas. The root guides must also carry a `## Model Routing` registry (Step 8C) so each phase runs on a model matched to its demand, with the Reviewer on a different model than the Implementer.

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

@@ -67,13 +67,46 @@ Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unle
 4. Read nearby or related specs under `docs/specs/`.
 5. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
 
-### Step 1: Clarify Intent, Sources & Scope Chunking
+### Step 1: Classify Request Type & Route
 
-Before diving into the problem, ask the user about the source of the requirements and any visual designs:
+`/akili-propose` is the single entry point for change work. Before clarifying details, **classify the request** so it takes the right track. Infer the type from the user's wording; if it is ambiguous, ask **one** short question: *"Is this a bug to fix, a new feature/change, or a trivial cosmetic tweak?"*
+
+| Type | Signals | Route |
+|---|---|---|
+| **Trivial** | Cosmetic/copy-only, one-line, a color/text/label tweak using existing tokens | Recommend `/akili-quick <name>` instead of a full proposal. Stop here unless the user still wants a proposal. |
+| **Feature / Change** | An intent ("I want X", "add/support/enable Y") | Continue with the standard proposal flow below. |
+| **Bug** | A symptom ("X is broken/failing/wrong", "regression", "error", "used to work") | Continue with the proposal flow, but follow the **Bug Track** (diagnosis-first) described below. |
+
+The proposal `frontmatter`/header should record the detected type as `Type: Bug | Change | Trivial` in Document Control so `/akili-specify` and `/akili-execute` inherit it. For bugs, prefer the `bugfix/<name>` spec path taxonomy.
+
+**Bug Track (diagnosis before fix):** A bug is not a feature — you start from a symptom, not an intent, so you must understand *why* before proposing *how*. For a bug:
+
+- Load the `systematic-debugging` skill.
+- Capture the **observed symptom**, concrete **reproduction steps**, and the **confirmed root cause** (not a guess) before recommending any fix.
+- Assess **impact/scope** (what else the root cause touches).
+- Recommend a **fix strategy** and route it by size: a genuinely cosmetic one-liner → `/akili-quick`; anything with logic, data, or a behavior change → `/akili-specify` (Lite) in Bug Mode, which requires a regression test.
+- These go in the proposal's **Bug Diagnosis** section (Step 2), which replaces the Requirement Delta Preview for bugs.
+
+### Step 1.1: Clarify Intent, Sources & Scope Chunking
+
+For **Feature / Change** and **Bug** requests, clarify the details. Ask the user about the source of the requirements and any visual designs:
 
 1. **Requirement Source:** Ask if they have a **Jira ticket** (if they do, suggest using the **Jira MCP** to automatically extract the description, acceptance criteria, and comments created by the BA) or if they prefer to paste/write the context directly.
 2. **Visual Designs / Mockups:** Ask if there is a **Figma link** or any visual mockup available. If they provide a Figma URL, suggest using the **Figma MCP** to extract the design details, components, and layout information.
 
+#### Mockup Fallback (No Visual Input)
+
+If the change has any UI surface AND the user provides **no** Figma link, image, or existing design, offer to generate a mockup directly in the agent before specifying. This is **opt-in and recommended** — never mandatory. The user can always decline and continue without a visual.
+
+- Recommend generating the mockup with the `stitch-design` skill (Stitch MCP), which produces high-fidelity HTML + screenshots and can synthesize a `.stitch/DESIGN.md` source of truth.
+- If the user accepts, load `stitch-design` and generate the mockup for the primary screens/flows in scope. Persist the artifacts under the spec so `/akili-specify` can consume them:
+  - Save the generated screens under `docs/specs/$SPEC_PATH/mockup/` (or reference the `.stitch/designs` location if the skill writes there).
+  - Record the exact paths and any `.stitch/DESIGN.md` reference in the proposal's **Visual Reference** section (see Step 2).
+- If the user declines, note "no visual reference" in the proposal and continue. Do not block the proposal on a mockup.
+- If Stitch MCP is unavailable, still offer to sketch a lightweight self-contained HTML mockup saved under `docs/specs/$SPEC_PATH/mockup/` so intent stays reviewable.
+
+A generated mockup counts as **visual design context** for `/akili-specify`, exactly like a Figma link would.
+
 Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
 
 - problem being solved
@@ -95,23 +128,63 @@ Ask focused questions only when the proposal would otherwise depend on unstable
 
 Create a concise proposal with this structure:
 
-1. Document Control
+1. Document Control (include `Type: Bug | Change | Trivial`)
 2. Intent
 3. Problem / Current Behavior
 4. Proposed Outcome
 5. Scope
 6. Non-Goals
 7. Affected Users, Systems, And Specs
-8. Requirement Delta Preview
-9. Approach Options
-10. Recommended Approach
-11. Risks, Dependencies, And Open Questions
-12. Success Criteria
-13. Next Step
+8. Visual Reference
+9. **Bug Diagnosis** (Bug track) *or* **Requirement Delta Preview** (Change track)
+10. Approach Options
+11. Recommended Approach
+12. Risks, Dependencies, And Open Questions
+13. Success Criteria
+14. Next Step
+
+### Visual Reference
+
+Capture whatever visual source backs this change so `/akili-specify` can convert it into requirements, design, and tasks. Use the state that applies:
+
+```markdown
+## Visual Reference
 
-### Requirement Delta Preview
+- Source: [Figma | Generated mockup (stitch-design) | Self-contained HTML mockup | None]
+- Location: <e.g. Figma URL, docs/specs/<spec-path>/mockup/, .stitch/designs, or .stitch/DESIGN.md>
+- Notes: screens/flows covered, or why no visual is needed (e.g. backend-only change).
+```
+
+When a mockup was generated during Step 1, list the concrete artifact paths here so downstream commands treat it as approved visual design context.
 
-When the change affects existing behavior, include a lightweight preview using these sections where relevant:
+### Bug Diagnosis (Bug track only)
+
+For a **Bug** request, replace the Requirement Delta Preview with a diagnosis produced using the `systematic-debugging` skill. Do not propose a fix until the root cause is confirmed — a fix built on a guessed cause is the top source of non-fixes and regressions.
+
+```markdown
+## Bug Diagnosis
+
+### Observed Symptom
+- What is broken, from the user's perspective (error, wrong output, crash, regression).
+
+### Reproduction Steps
+- Deterministic steps to reproduce (environment, inputs, expected vs actual).
+
+### Root Cause (confirmed)
+- The actual underlying cause, confirmed by investigation — not a hypothesis. Cite the code path / commit / condition responsible.
+
+### Impact & Scope
+- What else the same root cause affects; blast radius; data integrity or security implications.
+
+### Fix Strategy
+- The smallest safe correction, and the route: `/akili-quick` only if the fix is genuinely cosmetic with no logic; otherwise `/akili-specify` (Lite) in Bug Mode, which requires a regression test (red before the fix, green after).
+```
+
+If the root cause cannot be confirmed yet, say so explicitly and keep the proposal open for further investigation rather than proposing a speculative fix.
+
+### Requirement Delta Preview (Change track only)
+
+When a **Feature / Change** affects existing behavior, include a lightweight preview using these sections where relevant:
 
 ```markdown
 ## Requirement Delta Preview
@@ -137,22 +210,29 @@ For non-trivial work, include 2 or 3 options with trade-offs. Recommend one opti
 
 ### Next Step
 
-End the proposal with the exact next command:
+End the proposal with the exact next command, matched to the detected type:
 
 ```text
 /akili-specify $SPEC_PATH
 ```
 
+- **Change track:** `/akili-specify $SPEC_PATH` (standard depth for the work).
+- **Bug track:** `/akili-specify $SPEC_PATH` in **Bug Mode** — specify converts the confirmed root cause into a fix plan and a mandatory regression test. If the diagnosis showed the fix is genuinely cosmetic with no logic, recommend `/akili-quick <name>` instead.
+- **Trivial track:** the request should not have reached a full proposal — recommend `/akili-quick <name>`.
+
 ## Review Checklist
 
 Before presenting the proposal, verify:
 
 - [ ] The problem is clear.
+- [ ] The request type (Bug / Change / Trivial) is detected and recorded in Document Control.
+- [ ] For a bug: reproduction steps and a **confirmed** root cause are documented (not a guess).
 - [ ] Scope and non-goals are explicit.
 - [ ] The proposed outcome is behavior-focused.
 - [ ] Affected specs or code areas are listed.
+- [ ] The Visual Reference records the design source (Figma, generated mockup, or none) with its location.
 - [ ] Risks and open questions are visible.
-- [ ] The next command uses the resolved spec path.
+- [ ] The next command matches the detected type (specify, specify Bug Mode, or quick).
 
 ## Report To User
 
@@ -160,8 +240,10 @@ Generate a short, easy-to-understand summary (summary facil de entender de lo qu
 
 1. proposal path
 2. resolved spec path
-3. recommended approach
-4. main risks or open questions
-5. next command to run after approval
+3. detected request type (Bug / Change / Trivial)
+4. recommended approach (for a bug: the confirmed root cause and fix strategy)
+5. visual reference status (Figma, generated mockup with its path, or none)
+6. main risks or open questions
+7. next command to run after approval (matched to the type)
 
 Ask whether to approve the proposal, revise it, or stop.

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

@@ -0,0 +1,125 @@
+---
+description: Fast-track a trivial, low-risk change (copy edit, color tweak, small style/text change) with minimal traceability and automatic escalation when it is not actually trivial.
+---
+
+# Fast-Track a Trivial AKILI-SPECS Change
+
+Make a small, low-risk change in a single step — without generating the full `requirements.md` / `design.md` / `tasks.md` / `execution.md` / `test-report.md` / `validation-report.md` set — while still preserving AKILI's spec-to-code traceability through a `[SPEC:quick/<name>]` commit and a one-line log entry.
+
+This command exists for changes that are genuinely trivial: change a button color, fix a title's text, add a paragraph, adjust a label, tweak spacing. It is **not** a shortcut for real features, bugfixes with logic changes, or anything touching data, API, auth, or shared contracts. When a change turns out to be bigger than it looked, this command **stops and escalates** to the proper flow.
+
+> **Recommended model tier:** T2 Coder (a small, direct edit + verification). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. No deep-reasoning tier is required for a trivial change.
+
+## Usage
+
+```
+/akili-quick <short-change-name> [free-text description of the change]
+```
+
+**Examples:**
+
+- `/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 explaining the annual discount`
+
+## Arguments
+
+- `$ARGUMENTS` — a short kebab-case change name, optionally followed by a free-text description.
+  - The first token is the change name → the traceability slug is `quick/<change-name>`.
+  - The rest is the change description. If no description is given, ask the user for one before touching code.
+
+---
+
+## Triviality Gate (run FIRST)
+
+Before making any edit, confirm the change qualifies as trivial. A change is eligible ONLY if **all** of these hold:
+
+- **Cosmetic or copy-only:** text/label/content edits, color/spacing/style-token tweaks, static markup additions.
+- **No behavior change:** no new or modified logic, control flow, conditionals, state, or side effects.
+- **No data / API / auth / contract change:** no schema, endpoint, request/response shape, permission, or shared-package surface change.
+- **Small and local:** roughly **≤ ~20 LOC** and confined to **one component/file** (or a couple of tightly related files).
+- **Design-token safe:** any color/spacing/typography change uses an existing approved token from `docs/ux-ui/design.md` — not a new hardcoded value.
+
+### Automatic Escalation
+
+If the change fails **any** gate criterion, do **not** fast-track it. Stop and recommend the right entry point:
+
+- Small but with logic, or a real bugfix → `/akili-specify <spec-path>` in **Lite** depth.
+- A **bug** (something is broken, not just a cosmetic edit) whose fix touches logic or behavior → `/akili-propose <name>` so the root cause is diagnosed first (Bug Track), 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 scope → `/akili-propose <change-name>` first.
+- Introduces a **new** design token or visual pattern not in `docs/ux-ui/design.md` → route through `/akili-propose` (Visual Reference) or `/akili-specify` so the token is designed, not improvised.
+
+State clearly which criterion failed and which command to run instead. Never silently downgrade a real change into a quick edit.
+
+---
+
+## Behavior
+
+### Step 0: Load Minimal Context
+
+Keep context small — this is a trivial change, not a full spec run.
+
+1. Read only what the change needs:
+   - the target file(s) for the change
+   - `docs/ux-ui/design.md` **only if** the change involves a color, spacing, typography, or other design token (to use the approved token)
+   - root `CLAUDE.md` / `AGENTS.md` only if repo conventions are unclear for the edit
+2. **CodeGraph over full reads:** if `.codegraph/` exists, use `codegraph_search` to locate the exact symbol/component instead of scanning files.
+3. Do **not** read the full constitution set, `docs/prd.md`, or `docs/trd/trd.md` for a trivial edit.
+
+### Step 1: Confirm & Make the Change
+
+1. Restate the change in one sentence and confirm the target file(s) and the exact before/after (e.g. old hex/token → new token, old text → new text). If the description is ambiguous, ask one focused question — do not guess.
+2. Apply the smallest possible edit that satisfies the request. No refactors, no adjacent "while I'm here" cleanups, no scope creep.
+3. Preserve all unrelated code, comments, and formatting.
+
+### Step 2: Verify
+
+1. Run the lightest applicable check for the change:
+   - a lint / type-check / build for the touched file(s), or
+   - the component's existing test if one already covers the surface, or
+   - a clear manual verification note when no automated check is practical (e.g. "renders the hero title as 'X'").
+2. Do **not** author a new test suite here. If the change genuinely needs new test coverage, that is a signal it is not trivial → escalate per the gate.
+
+### Step 3: Record Traceability & Commit
+
+Preserve spec-to-code traceability with the minimum footprint:
+
+1. Append a **one-line entry** to `docs/specs/quick/quick-log.md` (create the file with a header if it does not exist):
+
+   ```markdown
+   # Quick Changes Log
+
+   One-line record of trivial, fast-tracked changes made with `/akili-quick`.
+
+   | Date | Change | Files | Verification | Commit |
+   |---|---|---|---|---|
+   | 2026-07-19 | quick/login-button-color — use brand accent token on primary login button | src/components/LoginButton.tsx | `npm run lint` pass | [SPEC:quick/login-button-color] |
+   ```
+
+2. Commit with the AKILI spec-reference standard, using the quick slug:
+
+   ```bash
+   git commit -m "[SPEC:quick/<change-name>] <concise description>"
+   ```
+
+Do **not** create `requirements.md`, `design.md`, `tasks.md`, `execution.md`, `test-report.md`, or `validation-report.md` for a quick change.
+
+### Step 4: Report to User
+
+Generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) including:
+
+1. what changed (before → after) and the file(s) touched
+2. which design token was used, if applicable
+3. the verification performed and its result
+4. the traceability slug and commit prefix used
+5. a reminder that if follow-up work grows beyond a trivial tweak, it should move to `/akili-propose` or `/akili-specify`
+
+---
+
+## Rules
+
+- Traceability is not optional: every quick change gets a `[SPEC:quick/<name>]` commit and a one-line log entry.
+- Respect design tokens: never hardcode a new color/size to "just make it match"; use the approved token or escalate.
+- One change per invocation. Batch unrelated tweaks into separate `/akili-quick` runs or a proper spec.
+- When in doubt about triviality, escalate. A wrongly fast-tracked change costs more than a Lite spec.
+- Keep the edit and the context minimal — this command's whole value is speed and low token cost.

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

@@ -45,6 +45,15 @@ Use the lightest useful depth:
 
 Lite mode still requires testable requirements, scenarios, and done criteria.
 
+### Bug Mode
+
+When the spec is a **bug** — the proposal's Document Control says `Type: Bug`, the spec path is `bugfix/*`, or the user frames it as a defect — specify runs in **Bug Mode** on top of the chosen depth (usually Lite):
+
+- Treat the proposal's **Bug Diagnosis** (confirmed root cause + reproduction) as the source of truth. If no proposal exists, first confirm the root cause with the `systematic-debugging` skill before writing the fix plan — do not specify a fix for a guessed cause.
+- Frame requirements around the **corrected behavior**, with a scenario that encodes the exact failing case from the reproduction steps.
+- **A regression test is mandatory.** At least one task must add a test that reproduces the bug — **red before the fix, green after** — and the requirement's scenario must map to it. This is non-negotiable evidence that the bug is actually fixed and stays fixed.
+- Keep the fix scoped to the root cause; do not fold unrelated cleanup into a bugfix.
+
 ## Behavior
 
 ### Step 0: Setup
@@ -60,7 +69,10 @@ Lite mode still requires testable requirements, scenarios, and done criteria.
    - `docs/trd/trd.md` (legacy fallback: `docs/detailed-design/detailed-design.md`)
    - The constitutional templates in `docs/specs/general-setup/` (`requirements.md`, `design.md`, `task.md`)
    - Package-level `CLAUDE.md` files if they exist
-3. Read `docs/specs/$ARGUMENTS/proposal.md` if it exists.
+3. Read `docs/specs/$ARGUMENTS/proposal.md` if it exists. If it has a **Visual Reference** section, treat the referenced source as approved visual design context and load it:
+   - A Figma URL → use the Figma MCP when available.
+   - A generated mockup under `docs/specs/$ARGUMENTS/mockup/`, `.stitch/designs`, or a `.stitch/DESIGN.md` reference → read those artifacts (screens, HTML, design tokens) and use `stitch-design` to interpret them.
+   - Any mockup produced during `/akili-propose` counts as visual design context for the `Design Impact` steps below, exactly like a Figma link.
 4. Read nearby or dependent specs under `docs/specs/` that overlap with the requested path.
 5. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
 6. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
@@ -108,7 +120,7 @@ Guidelines:
 - use measurable, testable language
 - separate goals from requirements
 - write behavior contracts, not implementation plans
-- **Design Impact:** IF the proposal includes Figma or visual design context, ensure UI states (loading, error, empty, success) and responsive behaviors are captured as explicit requirements.
+- **Design Impact:** IF the proposal includes any visual design context (Figma, an agent-generated mockup, or a `.stitch/DESIGN.md` reference), ensure UI states (loading, error, empty, success) and responsive behaviors are captured as explicit requirements.
 - include concrete scenarios for key requirements using `GIVEN`, `WHEN`, `THEN`, and optional `AND`
 - make requirement strength explicit with `SHALL`, `MUST`, `SHOULD`, or `MAY` where useful
 
@@ -197,7 +209,7 @@ Guidelines:
 - extend existing architecture rather than replacing it
 - use current repo paths and package names
 - include UI/UX decisions when the feature affects screens, flows, or components
-- **Design Impact:** IF the proposal includes Figma or visual design context, break down the visual design into a clear Frontend Component Architecture (e.g., atomic components) and define the necessary Design Tokens (colors, typography).
+- **Design Impact:** IF the proposal includes any visual design context (Figma, an agent-generated mockup, or a `.stitch/DESIGN.md` reference), break down the visual design into a clear Frontend Component Architecture (e.g., atomic components) and define the necessary Design Tokens (colors, typography). When the source is a generated mockup, derive the tokens from its artifacts (HTML/screens or `.stitch/DESIGN.md`).
 - tie design sections back to requirements explicitly
 - record meaningful trade-offs and rejected alternatives for non-trivial decisions
 - call out data, API, security, error-handling, observability, and rollback concerns when relevant
@@ -260,7 +272,8 @@ Task quality rules:
 - every task must reference the requirements it satisfies
 - every task must include a concrete verification command or manual check
 - tasks should explicitly address the negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`) defined in their respective requirement scenarios
-- **Design Impact:** IF the proposal includes Figma or visual design context, ensure frontend tasks are atomic, focusing on specific UI components, layouts, styling, and states extracted from the design.
+- **Bug Mode:** IF this is a bug, one task MUST add a regression test that reproduces the defect (red before the fix, green after) and reference the corrected-behavior requirement. Its verification is that the test fails on current code and passes after the fix.
+- **Design Impact:** IF the proposal includes any visual design context (Figma, an agent-generated mockup, or a `.stitch/DESIGN.md` reference), ensure frontend tasks are atomic, focusing on specific UI components, layouts, styling, and states extracted from the design or mockup artifacts.
 - tasks should avoid broad instructions like "implement feature" without scoped subtasks
 - tasks may be grouped by phase, but dependencies must remain explicit
 
@@ -300,6 +313,7 @@ After all three documents are approved, verify:
 - [ ] Every task references requirements and design sections
 - [ ] Every task has clear done criteria and verification guidance that accounts for the negative scenarios
 - [ ] The task dependency graph has no circular dependencies
+- [ ] For a bug (Bug Mode): the root cause is reflected in the requirements and at least one task adds a regression test (red before, green after)
 - [ ] The spec path matches the repo's chosen taxonomy under `docs/specs/`
 - [ ] Only real, available skills are referenced in tasks
 

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

@@ -4,9 +4,11 @@ description: Write and execute comprehensive automated unit/integration tests fo
 
 # Test AKILI-SPECS Implementation
 
-Run automated and, when needed, manual tests against a spec path's implementation. Produce `test-report.md` with results, requirement coverage, scenario traceability, and failures.
+Run automated and, when needed, manual tests against a spec path's implementation using the AKILI **Leader → Tester(s)** multi-agent harness. Produce `test-report.md` with results, requirement coverage, scenario traceability, and failures.
 
-Testing should prove the behavior promised in `requirements.md`, not only increase test count.
+In this command you act as the **Leader** (Orchestrator). You partition testing into per-suite units, delegate each unit to a focused **Tester** subagent, aggregate their structured reports, and assemble the final `test-report.md`. Testing should prove the behavior promised in `requirements.md`, not only increase test count.
+
+> **Recommended model tier:** Leader on T5 Fast-Cheap (orchestration — writes no tests), each Tester on T2 Coder (test authoring + verification). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. Prefer a Tester model that differs from the Implementer that wrote the code (author ≠ tester reduces confirmation bias).
 
 ## Usage
 
@@ -35,9 +37,41 @@ Create or update `docs/specs/$ARGUMENTS/test-report.md` with:
 
 ---
 
+## Multi-Agent Harness
+
+The Leader delegates concrete test authoring to the **Tester** persona defined in the project's `.agents/` directory:
+
+- `.agents/tester.md` — the persona used when delegating a single test suite (backend unit, frontend unit, integration, or E2E).
+
+If `.agents/tester.md` is missing, run `/akili-constitution` first to scaffold it. Do not invent the persona inline — the constitution is the source of truth.
+
+**Delegation mechanism by tool:**
+
+- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md`.
+
+**Token discipline — thin context per Tester (this is the core saving):**
+
+- Give each Tester **only its slice**: its assigned suite, the specific requirements + Given/When/Then scenarios that suite must prove, and the project's test command. Never hand a Tester the full `requirements.md`/`design.md`/`tasks.md` unless a scenario genuinely needs it.
+- Each Tester's context is discarded when it finishes, so per-suite contexts never accumulate in one growing window.
+- The Leader writes no tests itself unless the Deployment Rule below says to run inline, or a Tester exhausts its inner loop and the user approves a Leader fallback.
+
+**Deployment Rule (how many Testers to spawn):**
+
+| Situation | Action |
+|---|---|
+| Lite depth, or a single trivial suite (e.g. one bugfix test) | **Run inline** — the Leader authors it directly. Spawning a subagent would cost more tokens than the work saves. |
+| Standard / Full depth with one substantial suite | Spawn **one** Tester for that suite. |
+| Multiple suites that are **independent** (touch different domains/files — e.g. backend unit vs frontend unit vs E2E) | Spawn **one Tester per suite, in parallel**. |
+| Multiple suites that **share files or fixtures** | Spawn Testers **sequentially** (or a single Tester covering them) to avoid conflicting writes. |
+
+The Leader decides the count from the spec's depth and the independence of the suites — favor the fewest spawns that still keep each context small and each suite independent.
+
+---
+
 ## Behavior
 
-### Phase 0: Load Context
+### Phase 0: Load Context (Leader)
 
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
@@ -52,47 +86,44 @@ Create or update `docs/specs/$ARGUMENTS/test-report.md` with:
    - `docs/specs/$ARGUMENTS/requirements.md`
    - `docs/specs/$ARGUMENTS/design.md`
    - `docs/specs/$ARGUMENTS/tasks.md`
-3. Identify backend, frontend, and end-to-end scope from the design and tasks.
-4. Extract key requirements, Given/When/Then scenarios, negative constraints (`BUT it must NOT`), and strict validations (`AND IT MUST`) from `requirements.md`.
-
-### Phase 1: Unit Tests
+3. Read the Tester persona `.agents/tester.md` (stop and direct the user to `/akili-constitution` if it is missing).
+4. Identify backend, frontend, and end-to-end scope from the design and tasks.
+5. Extract key requirements, Given/When/Then scenarios, negative constraints (`BUT it must NOT`), and strict validations (`AND IT MUST`) from `requirements.md`.
 
-- Create or improve backend unit tests where needed.
-- Create or improve frontend unit tests where needed.
-- Explicitly test negative constraints (`BUT it must NOT`) and strict boundary validations (`AND IT MUST`).
-- Map tests back to requirements and scenarios.
-- Prefer focused tests that prove one behavior clearly over broad tests with unclear intent.
+### Phase 1: Plan Suites & Delegation (Leader)
 
-Use skills as needed:
+1. Partition the work into concrete **suites**: backend unit, frontend unit, integration, E2E — only those the spec actually needs.
+2. For each suite, assemble a **context slice**: the target requirements + scenarios, the negative/strict rules to assert, the repo test command, and the relevant skills.
+3. Apply the **Deployment Rule** to decide inline vs delegated, and parallel vs sequential.
+4. Assign skills per suite as needed:
+   - `nestjs-expert`, `systematic-debugging` — backend
+   - `vercel-react-best-practices`, `react-doctor` — frontend
+   - `ui-ux-pro-max` (fallback `frontend-design`) — UI-heavy E2E
 
-- `nestjs-expert`
-- `systematic-debugging`
-- `vercel-react-best-practices`
-- `react-doctor`
+### Phase 2: Execute Suites (Tester per suite)
 
-### Phase 2: Integration Tests
+For each suite, the assigned Tester (or the Leader inline) must:
 
-- Create or improve API integration tests where relevant.
-- Validate auth, request/response shape, and major flows.
-- Cover cross-module behavior that cannot be proven by unit tests alone.
+- Author focused tests that prove one behavior clearly.
+- **Explicitly** cover negative constraints (`BUT it must NOT`) and strict boundary validations (`AND IT MUST`).
+- Map every test back to its requirement and scenario.
+- Run the suite and apply the **bounded self-correction inner loop** (max 3 attempts):
+  - fix genuine **test defects** and re-run;
+  - keep a failing test that reveals a genuine **product defect** red, and report it as `STATUS: PRODUCT_BUG` instead of rewriting it to pass.
+- Prefer unit tests for internal logic, integration tests for cross-module/API behavior, and E2E only for critical user journeys — not every small component state.
 
-### Phase 3: End-to-End Tests
+Each Tester concludes with exactly one status — `PASS`, `FAIL`, or `PRODUCT_BUG` — plus a per-scenario coverage slice, per `.agents/tester.md`.
 
-- Create or improve E2E tests for user-visible workflows.
-- If the work is UI-heavy, prefer `ui-ux-pro-max` when available.
-- Otherwise use `frontend-design` and the UX/UI design doc as the UX reference.
-- Use E2E tests for critical user journeys, not every small component state.
+### Phase 3: Aggregate & Traceability (Leader)
 
-### Phase 4: Coverage & Traceability
-
-Create a requirement-to-test matrix so every key requirement has test evidence or an explicit gap. Ensure negative constraints and strict validations are mapped.
+Collect every Tester's coverage slice into one requirement-to-test matrix so every key requirement has test evidence or an explicit gap. Ensure negative constraints and strict validations are mapped. Carry through any `PRODUCT_BUG` findings as failures with remediation.
 
 Recommended matrix columns:
 
 | Requirement | Scenario | Test Type | Test File or Command | Result | Gap or Notes |
 |---|---|---|---|---|---|
 
-### Phase 5: Generate Test Report
+### Phase 4: Generate Test Report (Leader)
 
 Create `docs/specs/$ARGUMENTS/test-report.md`.
 
@@ -112,9 +143,11 @@ The report must include:
 8. Remediation
 9. Accepted Gaps, if any
 
-### Phase 6: Report to User
+When Testers were delegated, record in the Summary how many suites ran, how many Testers were spawned (and whether in parallel), and any suite run inline.
+
+### Phase 5: Report to User (Leader)
 
-Generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) of the overall test status, test counts, requirement coverage, scenario gaps, and top failures. If failures exist, ask whether to fix failures, add missing tests, fix all, or keep only the report.
+Generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) of the overall test status, test counts, requirement coverage, scenario gaps, product bugs found, and top failures. If failures exist, ask whether to fix failures, add missing tests, fix all, or keep only the report.
 
 ---
 
@@ -139,3 +172,5 @@ If `ui-ux-pro-max` is unavailable, use `frontend-design` plus the UX/UI design d
 - Prefer repository-specific test commands over hardcoded framework assumptions.
 - If a test is flaky, record the flake and avoid treating it as passing evidence until stabilized.
 - If no automated test is practical, document the manual verification steps and why automation was deferred.
+- A Tester must never rewrite a test to hide a genuine product defect; a real failure is reported as `PRODUCT_BUG`, not silenced.
+- Do not delegate trivial single-test work to a subagent when running it inline is cheaper (see the Deployment Rule).