@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/references/spec-driven/validate.md

@@ -0,0 +1,397 @@
+# Spec-Driven Validate
+
+Use this reference for the mandatory final Execute validation gate. This is not a separate phase — verification is part of every task's completion within Execute and runs automatically after the final task or inline step is complete.
+
+<!-- validator anchors: reject shallow assertions | payload/conjunction rule | per-task test adequacy review summary | fix-loop iteration count | 3 verification iterations -->
+
+**Goal**: Verify implementation meets spec AND coding principles.
+
+## Three Levels of Verification
+
+1. **Per-task verification (always, author self-check):** After implementing each task, verify its "Done when" criteria before committing. This is mandatory and automatic. The implementer runs it.
+
+2. **Feature-level validation (independent Verifier sub-agent, always-on, never prompted):** After all tasks for a feature (or priority group) are done, validation runs automatically — the orchestrator dispatches a **fresh Verifier sub-agent** (see [references/spec-driven/sub-agents.md](sub-agents.md)). Do NOT ask the user whether to run it; it is the safety net, not an opt-in. User interaction is limited to interactive UAT (for user-facing features) and acting on a FAIL verdict ("fix these gaps now?"). The Verifier:
+   - Runs **read-only** over the real implementation and tests — mutations run in a scratch/throwaway state only (see Discrimination Sensor section), and must be reverted or discarded before verdict
+   - Scopes coverage to the feature's **git diff surface** (not the full repository)
+   - Re-derives coverage independently using **evidence-or-zero**: every AC must be traced to a `file:line` + assertion expression; a criterion with no `file:line` citation counts as NOT covered
+   - Runs the **spec-anchored outcome check** and the **discrimination sensor** (both described below)
+   - Writes `.specs/features/<slug>/validation.md` with the full evidence report
+   - Returns a compact verdict + ranked gap list to the orchestrator in chat
+   - Gaps become **fix tasks** routed back to an implementer; re-verification follows with a maximum of **3 fix→re-verify iterations** before escalating to the user
+
+3. **Interactive UAT (for user-facing features only):** The feature has complex user-facing behavior where human judgment matters (UI flows, interaction patterns, visual design). For backend-only, harness-only, or infrastructure work, automated checks are sufficient — record `UAT: not applicable` with reason.
+
+**Trigger for explicit validation:** "Validate", "verify work", "UAT", "test with me", "walk me through it"
+
+## Independence Rule
+
+Prefer a fresh read-only verifier agent or tool. The author must not verify their own work when independent verification tooling is available. When subagents are unavailable, run the standalone fresh-eyes fallback: re-read `spec.md`, changed files, tests, and diff from scratch before making a verdict.
+
+The verifier is read-only against the real worktree. Discrimination sensor mutations run only in scratch state such as a temporary worktree, stash-protected copy, or temp file copy, and must be reverted or discarded before verdict.
+
+## Inputs
+
+- Approved `spec.md`.
+- `context.md`, `design.md`, and `tasks.md` when present.
+- Implementation diff and changed files.
+- Execute evidence: commands, gate results, test counts, skipped checks, per-task test adequacy reviews, and accepted assumptions.
+- Current tests, fixtures, snapshots, schemas, and validation assets.
+- Artifact-store evidence: active artifact key, version, and checksum after write (where specify/tasks/design produced artifacts).
+
+---
+
+## Process
+
+### 1. Check Completed Tasks
+
+Go through `.specs/features/<slug>/tasks.md`:
+
+- [ ] All tasks marked done?
+- [ ] Any blocked or partial?
+
+### 2. Spec-Anchored Acceptance Criteria Check
+
+For each acceptance criterion in `.specs/features/<slug>/spec.md`, the Verifier re-derives the **spec-defined expected outcome** and confirms the test's actual assertion matches it:
+
+```markdown
+### P1: [Story Title]
+
+**Acceptance Criteria**:
+
+| Criterion (WHEN X THEN Y) | Spec-defined outcome | `file:line` + assertion expression | Result |
+| ------------------------- | -------------------- | ---------------------------------- | ------ |
+| WHEN [X] THEN [Y]         | [precise value/state from spec] | `path/to/test.ts:42` — `expect(result.field).toBe(expected)` | ✅ PASS / ❌ GAP / ⚠️ Spec-precision gap |
+```
+
+**Rules:**
+
+- Where the spec defines a precise outcome (specific status code, field value, error message, state), the test assertion MUST target that exact outcome — not just that an assertion exists.
+- Where the spec does NOT define a precise outcome, mark as **⚠️ Spec-precision gap** and flag it in the report. Do NOT silently pass a vague assertion.
+- Evidence-or-zero: a criterion with no `file:line` citation counts as NOT covered.
+
+### 3. Check Edge Cases
+
+From `.specs/features/<slug>/spec.md` edge cases:
+
+- [ ] [Edge case 1] handled correctly
+- [ ] [Edge case 2] handled correctly
+
+### 4. Run Build-Level Gate Check (MANDATORY)
+
+Run the Build-level gate check from the **Gate Check Commands** section in tasks.md. This is NOT optional.
+
+1. Run: `[Build gate command from the Gate Check Commands section in .specs/features/<slug>/tasks.md]`
+2. Non-zero exit code = STOP. Do not proceed to Code Quality Check.
+3. Record results:
+   - Total test count: [N]
+   - Passed: [N]
+   - Failed: [list]
+   - Skipped: [list — each skip must be justified]
+
+**Test Integrity Check:**
+
+- Compare current test count against the count before this feature was implemented
+- If test count DECREASED: investigate why. Tests should only be deleted with explicit justification.
+- If assertions were weakened (less specific than before): flag as potential regression
+
+### 5. Discrimination Sensor (MANDATORY — always runs after gate check passes)
+
+The sensor provides the empirical guarantee that the tests can actually detect regressions. It runs in a scratch/throwaway state — the real working tree is never modified.
+
+**How it works:**
+
+1. **Prepare a scratch state.** Use one of (choose the safest available for the environment):
+   - `git stash` the current state, apply a mutation, run tests, then `git stash pop`; OR
+   - A temporary worktree (`git worktree add`); OR
+   - A temp copy of the affected file(s).
+2. **Inject a behavior-level fault** into the new code introduced by this feature. Choose a mutation proportional to the code's risk:
+   - Flip a boolean condition (`if (x)` → `if (!x)`, `>` → `>=`)
+   - Change a return value (return a wrong status code, wrong field, zero instead of a computed value)
+   - Off-by-one (shift a loop bound, change a slice index)
+   - Remove a required side effect (delete a method call that the spec requires)
+3. **Run the tests** that cover the mutated code. Use the Quick or Full gate command from tasks.md.
+4. **Confirm the mutant is killed** (tests FAIL). Then discard the mutation (restore the scratch state).
+5. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior — add a fix task to strengthen the assertion.
+
+**Tiering (proportional, not optional):**
+
+| Context | Sensor depth |
+| ------- | ------------ |
+| Default (all features) | Lightweight fault-injection: 1–3 targeted behavior-level mutations per feature, focused on the highest-risk new code |
+| P0 / critical paths (payment, auth, data integrity) | Full mutation run: use language-appropriate mutation tooling if available (e.g., Stryker, mutmut, cargo-mutants, pitest); otherwise increase the number of manual fault-injection mutations to ≥5 covering all branches |
+
+**Stack-agnostic:** The sensor targets behavior-level semantics (what the code does), not a specific tool. Any language, any framework.
+
+**Report:** Record killed/survived for each mutation attempt. Surviving mutants → create fix tasks before marking the feature done.
+
+If a safe reversible mutant cannot be made, record why and mark `Blocked` unless equivalent existing mutation evidence proves discrimination.
+
+### 6. Code Quality Check (MANDATORY)
+
+For each changed file, verify against [references/spec-driven/coding-principles.md](coding-principles.md) and the [references/naming-standards.md](../naming-standards.md) conventions:
+
+| Check                                | Pass? |
+| ------------------------------------ | ----- |
+| No features beyond what was asked    |       |
+| No abstractions for single-use code  |       |
+| No unnecessary "flexibility" added   |       |
+| Only touched files required for task |       |
+| Didn't "improve" unrelated code      |       |
+| Matches existing patterns/style      |       |
+| Would senior engineer approve?       |       |
+| Tests map to acceptance criteria and are non-shallow (spot-check one story) | |
+| Spec-anchored outcome check: each test's asserted value matches the spec-defined outcome (or gap flagged) | |
+| Per-layer Coverage Expectation met: domain logic has 1:1 AC mapping; routes/e2e cover happy + edge + error paths for every route in scope | |
+| Every test in scope maps to a spec AC, listed edge case, or Done-when criterion (no unclaimed tests) | |
+| Documented project quality/testing guidelines followed (cite guideline file, or "none — strong defaults applied") | |
+
+❌ Any "No"? → Fix before marking complete.
+
+### 7. Interactive UAT (if user-facing feature)
+
+For each testable deliverable, present one test at a time:
+
+```
+Test [N]: [Test Name]
+
+Expected: [What should happen — specific and observable]
+
+→ Does this work? Describe what you see.
+```
+
+Wait for user response:
+
+| User says                      | Interpret as            |
+| ------------------------------ | ----------------------- |
+| "yes", "pass", "works", "next" | ✅ Pass                 |
+| "skip", "can't test", "n/a"    | ⏭️ Skip                 |
+| Anything else                  | ❌ Issue — log verbatim |
+
+**Severity inference (never ask the user for severity):**
+
+| User description contains               | Inferred severity |
+| --------------------------------------- | ----------------- |
+| crash, error, exception, fails, broken  | Blocker           |
+| doesn't work, wrong, missing, can't     | Major             |
+| slow, weird, off, minor, small          | Minor             |
+| color, font, spacing, alignment, visual | Cosmetic          |
+| (unclear)                               | Major (default)   |
+
+For mobile or UI features, follow the [references/mobile-context.md](../mobile-context.md) gate before driving an emulator/simulator. When instrumentation applies, prefer the Maestro MCP tooling (`list_devices` → `inspect_screen` → `run`) over manual steps.
+
+### 8. Generate Fix Plans (if issues found)
+
+For each issue found during UAT or from the Verifier:
+
+1. **Diagnose** — Analyze the codebase to find root cause. Prefer massa-ai code-analysis tools first (search, optimized_context) for symbol and dependency location; fall back to ast-grep/rg/grep when the index is stale or unavailable. Current source overrides stale index/memory.
+2. **Create fix task** — Write a task definition with:
+   - What: The specific fix
+   - Where: File paths
+   - Verify: How to prove the fix works
+   - Done when: Acceptance criteria for the fix
+3. **Present fix plan** — Show all fix tasks to user for approval
+
+Fix tasks follow the same format as regular tasks and can be executed with the implement phase (see [references/spec-driven/execute.md](execute.md)).
+
+**Guardrail:** Maximum 3 diagnostic iterations per issue. If root cause isn't found after 3 attempts, flag for human investigation. The same 3-iteration bound applies to the Verifier's fix→re-verify cycle: if gaps persist after 3 rounds, escalate to the user rather than continuing to loop.
+
+### 9. Write Validation Report File + Return Chat Summary (MANDATORY)
+
+After all checks complete, the Verifier MUST:
+
+1. **Write the persisted report** to `.specs/features/<slug>/validation.md` (see template below). This file is the evidence artifact — it survives the session and can be referenced by CI, reviewers, or future agents. Record in `.specs/project/STATE.md` (Decisions) that validation evidence is available at that path.
+2. **Return a compact summary in chat** to the orchestrator (see Compact Chat Summary section below). The orchestrator surfaces it to the user and routes any ranked gaps to fix tasks.
+
+### 10. Distill Lessons (MANDATORY when validation.md has signal)
+
+This is the closing action of validation — not a separate phase. Immediately after the report is written, turn its grounded failures into reusable, project-local guidance by following [references/lessons.md](../lessons.md) and the stub at [references/spec-driven/lessons.md](lessons.md). In short: for each surviving mutant, spec-precision gap, failed/uncovered AC, or `// SPEC_DEVIATION`, record one terse general lesson via:
+
+```bash
+python3 skills/massa-ai/scripts/lessons.py --root . add --feature <slug> --signal "<signal>" --source "<source>" --text "<lesson>" --scope "<scope>"
+```
+
+The script enforces grounding (mandatory `--source`) and owns all bookkeeping. A clean PASS with no signal → record nothing. Run the self-check: if there was signal but no lesson was recorded, say so in chat. See [references/lessons.md](../lessons.md) for the exact commands, phrasing rules, scope discipline, and the no-script fallback.
+
+Persist durable memory for verified outcomes worth reusing via `remember` with tags `workflow:spec-driven`, `entity:<slug>`, and `memory:episodic|procedural` as appropriate.
+
+---
+
+## Verdicts
+
+- `Pass`: delivered behavior matches the spec, checks pass, UAT is passed or not applicable, and the discrimination sensor proves validation can fail for wrong behavior.
+- `Needs Fix`: implementation diverges from the spec or validation is insufficient, and the fix path is clear.
+- `Blocked`: verification cannot produce a trustworthy verdict because tooling, environment, safe mutation, requirements, UAT, or evidence is missing.
+
+## Fix Loop
+
+- Return `Needs Fix` findings to Execute as fix tasks.
+- Cap the loop at 3 verification iterations.
+- After 3 unsuccessful iterations, mark `Blocked` with remaining findings and exact next step.
+
+---
+
+## Compact Chat Summary (returned in chat after validation)
+
+The Verifier returns this block to the orchestrator after completing all checks:
+
+```markdown
+## Validation: [Feature] — [PASS ✅ | FAIL ❌]
+
+**Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps flagged]
+**Gate**: [X passed, 0 failed]
+**Sensor**: [N mutations injected, N killed, N survived]
+**Report**: `.specs/features/<slug>/validation.md`
+
+**Ranked gaps** (if FAIL):
+1. [Gap description] — [AC or criterion] — [file:line or "no evidence"]
+2. ...
+```
+
+---
+
+## Validation Report Template (`.specs/features/<slug>/validation.md`)
+
+```markdown
+# [Feature] Validation
+
+**Date**: [YYYY-MM-DD]
+**Spec**: `.specs/features/<slug>/spec.md`
+**Diff range**: [commit range or branch..HEAD]
+**Verifier**: independent sub-agent (author ≠ verifier)
+
+---
+
+## Task Completion
+
+| Task | Status     | Notes   |
+| ---- | ---------- | ------- |
+| T1   | ✅ Done    | -       |
+| T2   | ✅ Done    | -       |
+| T3   | ⚠️ Partial | [Issue] |
+
+---
+
+## Spec-Anchored Acceptance Criteria
+
+| Criterion (WHEN X THEN Y) | Spec-defined outcome | `file:line` + assertion | Result |
+| ------------------------- | -------------------- | ----------------------- | ------ |
+| WHEN X THEN Y             | [precise value/state from spec] | `path/to/test.ts:42` — `expect(result.field).toBe(expected)` | ✅ PASS |
+| WHEN A THEN B             | [expected value]     | `path/to/test.ts:88` — `expect(res.status).toBe(400)` | ✅ PASS |
+| WHEN C THEN D             | not precisely defined in spec | — | ⚠️ Spec-precision gap |
+
+**Status**: ✅ All ACs covered / ❌ Gaps present / ⚠️ Spec-precision gaps flagged
+
+---
+
+## Discrimination Sensor
+
+| Mutation | File:line | Description | Killed? |
+| -------- | --------- | ----------- | ------- |
+| 1        | `src/service.ts:42` | Flipped condition `x > 0` → `x >= 0` | ✅ Killed |
+| 2        | `src/service.ts:88` | Changed return value `status: 'active'` → `status: 'inactive'` | ✅ Killed |
+| 3        | `src/handler.ts:15` | Removed side-effect call to `notify()` | ❌ Survived → fix task created |
+
+**Sensor depth**: [lightweight / P0-full]
+**Result**: [N/N killed] — [PASS ✅ | FAIL ❌]
+
+---
+
+## Interactive UAT Results (if performed)
+
+| #   | Test        | Result   | Details                                         |
+| --- | ----------- | -------- | ----------------------------------------------- |
+| 1   | [Test name] | ✅ Pass  | -                                               |
+| 2   | [Test name] | ❌ Issue | [Verbatim user response] — Severity: [inferred] |
+| 3   | [Test name] | ⏭️ Skip  | [Reason]                                        |
+
+---
+
+## Code Quality
+
+| Principle        | Status |
+| ---------------- | ------ |
+| Minimum code     | ✅     |
+| Surgical changes | ✅     |
+| No scope creep   | ✅     |
+| Matches patterns | ✅     |
+| Spec-anchored outcome check (asserted values match spec) | ✅ |
+| Per-layer Coverage Expectation met (domain 1:1 ACs; routes happy+edge+error) | ✅ |
+| Every test maps to a spec requirement — no unclaimed tests | ✅ |
+| Documented guidelines followed: [file(s) or "none — strong defaults applied"] | ✅ |
+
+---
+
+## Edge Cases
+
+- [x] Edge case 1: Handled correctly
+- [ ] Edge case 2: NOT handled - needs fix
+
+---
+
+## Gate Check
+
+- **Gate command**: [Build gate command from the Gate Check Commands section in tasks.md]
+- **Result**: [X] passed, [Y] failed, [Z] skipped
+- **Test count before feature**: [N]
+- **Test count after feature**: [M]
+- **Delta**: [+(M - N) new tests]
+- **Skipped tests**: [list with justification for each]
+- **Failures**: [list with details]
+
+---
+
+## Fix Plans (if issues found)
+
+### Fix 1: [Issue description]
+
+- **Root cause**: [What's actually wrong]
+- **Fix task**: [Task definition]
+- **Priority**: [Blocker/Major/Minor/Cosmetic]
+
+---
+
+## Requirement Traceability Update
+
+Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verified state in `.specs/project/FEATURES.json`:
+
+| Requirement | Previous Status | New Status   |
+| ----------- | --------------- | ------------ |
+| [FEAT]-01   | Implementing    | ✅ Verified  |
+| [FEAT]-02   | Implementing    | ❌ Needs Fix |
+
+---
+
+## Summary
+
+**Overall**: ✅ Ready | ⚠️ Issues | ❌ Not Ready
+
+**Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps]
+**Sensor**: [N/N mutations killed]
+**Gate**: [X passed]
+
+**What works**: [List]
+
+**Issues found**: [Issue 1: How to fix]
+
+**Next steps**: [Action]
+```
+
+---
+
+## Tips
+
+- **Validation is never prompted** — it always runs after the last task; do not ask the user whether to run it
+- **Spec-anchored, not just covered** — "there is an assertion" is not enough; the assertion must target the spec-defined outcome
+- **Sensor in scratch only** — never mutate the real tree; stash/worktree/temp copy, run, discard
+- **Surviving mutants are fix tasks** — do not mark the feature done if the sensor found weak tests
+- **P1 first** — MVP must work before P2/P3
+- **WHEN/THEN = Test** — Each criterion is a test case
+- **Be specific** — "Doesn't work" isn't helpful
+- **Recommend fixes** — Don't just report problems, create fix tasks
+- **Quality check is mandatory** — Not optional
+- **Infer severity** — Never ask the user "how bad is this?"
+- **Max 3 diagnostic iterations** — Prevents infinite investigation loops
+- **Update traceability** — Every verified requirement updates spec.md status and the FEATURES.json registry
+- **Always write the report file** — `.specs/features/<slug>/validation.md` is the persisted evidence artifact
+- **Distill after writing** — turn grounded failures into lessons via `python3 skills/massa-ai/scripts/lessons.py` ([references/lessons.md](../lessons.md)); clean PASS → no lesson
+- **Independence first** — prefer a fresh read-only verifier; the author never verifies their own work when tooling allows

package/skills/massa-ai/references/subagent-design.md

@@ -0,0 +1,132 @@
+# Subagent Design
+
+Use this reference only when designing or revising a reusable subagent role, adding a new role to `references/agent-orchestration.md`, or turning repeated delegated work into a stable role charter.
+
+Do not load this reference for ordinary one-off delegation. For runtime delegation, use `references/agent-orchestration.md`.
+
+## Principle
+
+Subagents are execution units inside a harness, not independent workflow owners. In massa-ai:
+
+- the main agent owns workflow routing, memory recall and persistence, user-facing synthesis, and the final Evidence Gate
+- reusable subagents own one bounded capability with explicit context inputs, permission limits, deterministic sensors, and a compact output contract
+- prompt quality matters, but completion gates and concrete evidence matter more
+
+## Local Task vs Skill vs Subagent
+
+Use this decision tree before creating or revising a reusable subagent:
+
+```text
+Is the work immediate, small, and tightly coupled to the main thread?
+  -> Keep it local.
+
+Is the work reusable guidance that does not need isolated context?
+  -> Use or create a skill/reference.
+
+Is the work a one-off bounded delegation with an existing role?
+  -> Use references/agent-orchestration.md with a task-specific prompt contract.
+
+Is the work recurring, specialized, context-heavy, independently verifiable, and useful across workflows?
+  -> Design a reusable subagent role with this reference.
+```
+
+Prefer a skill/reference when the value is procedure or domain knowledge. Prefer a subagent when the value is isolated context, parallel work, or independent verification.
+
+Reusable role threshold:
+
+- Create or revise a reusable subagent role only when the work recurs across workflows, needs isolated context or independent verification, has deterministic sensors, and usually meets at least one dispatch trigger from `references/agent-orchestration.md`: explicit delegation request, >=2 independent slices, >10 files, high/critical findings, or context-firewall overflow.
+- Do not create a role for one-off local tasks, overlapping write sets, unresolved user intent, or tasks that need full conversation history.
+
+## Role Charter Template
+
+Use this shape when adding a reusable role or writing a subagent definition. Keep the charter short enough that the main agent can pass it without dragging unrelated workflow history.
+
+```markdown
+## Role: [kebab-case-name]
+
+Purpose: [one responsibility]
+
+Trigger description:
+- Use when [specific workflow condition or user phrase].
+- Do not use when [local task, unresolved intent, overlapping role, or unsafe write scope].
+
+Permissions:
+- Default: read-only.
+- Write access only when the task has a disjoint write set and concrete verification.
+- Model: inherit by default; use a cheaper/faster model only for low-risk mechanical checks.
+
+Context inputs:
+- exact projectId
+- exact parent `workflowSessionId` and child session tag; repeated-search roles
+  receive their own ephemeral Synapse session
+- workflow name and role name
+- scope and file/module ownership
+- relevant recalled facts and source pointers
+- exclusions and what to avoid redoing
+- allowed tools and mutation level
+- deterministic validation expected
+- context-firewall limits
+
+Process:
+1. Confirm the scope and refusal conditions.
+2. Inspect only the supplied scope plus minimal source needed to verify claims.
+3. Run or recommend deterministic sensors when available.
+4. Return compact findings, evidence, risks, and next step.
+
+Output contract:
+- Status: Complete, Partial, or Blocked
+- Scope checked or files changed
+- Evidence with commands, source locations, or artifacts
+- Findings or implementation summary
+- Risks and skipped checks
+- Exact next step
+
+Validation sensors:
+- [tests, build, typecheck, lint, static search, artifact inspection, or source-location proof]
+
+Memory boundary:
+- Suggest durable memories only when useful.
+- Do not persist broad project memory unless explicitly assigned by the main agent.
+```
+
+## Capability Packet
+
+When a workflow dispatches a reusable role, send a capability packet rather than a loose instruction. The packet should include:
+
+- `role`: the role name from `agent-orchestration.md`
+- `purpose`: one sentence tied to this workflow
+- `trigger`: why delegation is justified now
+- `scope`: exact files, modules, diff, report finding, or task IDs
+- `permissions`: read-only or write with disjoint write set
+- `inputs`: recalled facts, source pointers, task/report IDs, constraints, and exclusions
+- `sensors`: commands or concrete checks expected
+- `output`: the exact output contract
+- `firewall`: raw logs, diffs, snapshots, or research that must be summarized
+- `memory`: whether the subagent may suggest memory and who persists it
+
+## Quality Checklist
+
+Before adding or revising a reusable role:
+
+- One responsibility; no generic "helper" roles.
+- Trigger description names when to use it and when not to use it.
+- Scope can be represented as a bounded capability packet.
+- Read-only by default; write permissions require disjoint ownership and verification.
+- Output contract includes evidence, skipped checks, risk, and exact next step.
+- Success depends on deterministic sensors or concrete source evidence, not self-evaluation.
+- Context-firewall rule is explicit for verbose logs, diffs, snapshots, generated reports, and research.
+- Main agent remains responsible for synthesis, memory persistence, and final Evidence Gate.
+- Role count stays small; add a role only when repeated work justifies the overhead.
+
+## Anti-Patterns
+
+- Vague descriptions such as "use for general tasks" or "help with code".
+- Creating a subagent for a task that should be a local step or a skill.
+- Letting a subagent decide user intent, workflow routing, or final acceptance.
+- Broad write permissions without a disjoint write set.
+- Parallel write agents sharing files or working tree state without isolation.
+- Prompt-only success claims such as "be thorough" without sensors.
+- Returning raw logs, diffs, screenshots, CSVs, or research dumps to the main context.
+- Creating many narrow roles before repeated need is proven.
+- Persisting one-off subagent chatter as durable memory.
+- Missing lifecycle closure: no status, no skipped checks, no next step.