hatch3r 1.6.2 → 1.7.1

package/commands/hatch3r-project-spec.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Translate a greenfield vision into future-state design artifacts -- ADRs, domain model, API contracts, per-module technical specs, and a board-ready todo.md
 tags: [planning, greenfield]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 # Project Spec — Greenfield Project Specification from Vision to Docs
 
@@ -37,6 +41,18 @@ Take a project idea or vision and produce complete project documentation across
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. When in doubt, **ASK** — it is better to ask one question too many than to make one wrong assumption. Discovery questions are never wasted.
 
+## Step 0: Triage
+
+Classify the project-spec request before delegating:
+
+- **Tier 1 (trivial)**: small greenfield project with focused scope, single platform, no compliance burden; reduced fanout (3–4 researchers) and skip the production-blueprint sub-agent.
+- **Tier 2 (standard)**: standard greenfield with business and technical lenses; standard pipeline with all 7 parallel researchers and ADR generation.
+- **Tier 3 (deep)**: enterprise-scale, multi-platform, or regulated greenfield (HIPAA/PCI/FedRAMP); full pipeline with all researchers, deep web research for compliance, and confirm spec scope with the user before file writes.
+
+If Tier 1, run the reduced researcher set and skip Sub-Agents 6–7 unless the user opts in. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including the production-blueprint and confirm scope with the user before generating ADRs.
+
+---
+
 ### Step 1: Gather Project Vision & Business Context
 
 #### 1a. Core Vision

package/commands/hatch3r-quick-change.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-reviewer, hatch
 description: Lightweight command for small changes not worth tracking on the board. Adaptive ceremony with inline or sub-agent implementation, batch support, and soft scope guards.
 tags: [core, implementation]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -77,9 +81,21 @@ Downstream propagation: every ASK checkpoint that reports verification quality,
 
 ---
 
+## Triage
+
+Classify the change request before delegating. Detailed tier scoring runs in Step 2 (Tier Assessment); this section summarizes the routing:
+
+- **Tier 1 (trivial)**: single-file edit, config tweak, typo, or constant rename; inline implementation in Step 4a, no researcher, no review loop.
+- **Tier 2 (standard)**: multi-file change or new function with bounded scope; standard pipeline with `hatch3r-implementer` and lightweight researcher (`similar-implementation` at `quick` depth).
+- **Tier 3 (deep)**: hard-blocked here — quick-change does not provide research depth for Tier 3 work. Step 2b routes Tier 3 to `hatch3r-workflow`.
+
+If Tier 1, run inline. If Tier 2, run the implementer-only pipeline below. If Tier 3, exit and recommend `hatch3r-workflow`.
+
+---
+
 ## Workflow
 
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. For every ASK checkpoint, use the platform-native question tool per `agents/shared/user-question-protocol.md`.
 
 ### Step 1: Input and Batch Parsing
 
@@ -94,7 +110,7 @@ Parse the user's description into discrete change items.
 
 ---
 
-### Step 2: Scale Assessment (Soft Guard)
+### Step 2: Tier Assessment (Soft Guard)
 
 Evaluate whether the described changes fit the quick-change scope.
 

package/commands/hatch3r-recipe.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Execute shareable workflow recipes that compose agents, skills, and commands into guided sequences for common development scenarios
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-refactor-plan.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Plan a refactoring or migration effort -- spawn parallel researchers, produce refactoring spec, ADR(s), and phased todo.md entries for board-fill.
 tags: [planning]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -47,6 +51,18 @@ The command produces phased todo.md entries that map to the appropriate executio
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the refactor-planning request before delegating:
+
+- **Tier 1 (trivial)**: localized refactoring scoped to a single module with strong test coverage; reduced fanout (1–2 researchers) and produce a single-phase todo entry.
+- **Tier 2 (standard)**: standard refactor across 2–4 modules or a single dimension (structural or logical or visual); standard pipeline with all 5 parallel researcher modes.
+- **Tier 3 (deep)**: cross-cutting refactor (architectural shift, framework swap, or mixed-dimension); full pipeline with deep research and confirm phased plan with the user before file writes.
+
+If Tier 1, run the reduced researcher set and skip ADR generation unless decisions are obvious. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including ADR generation and confirm phasing with the user before writing files.
+
+---
+
 ### Step 1: Gather Refactoring Goal
 
 1. **ASK:** "Tell me about the refactoring or migration you want to plan. I need:

package/commands/hatch3r-release.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Cut a versioned release with changelog generation, version bumping, and GitHub release creation.
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 # Release — Cut a Versioned Release with Changelog
 

package/commands/hatch3r-report.md

@@ -0,0 +1,167 @@
+---
+id: hatch3r-report
+type: command
+orchestrator: false
+description: Generate an in-chat session report from the active or named transcript — every tool call, sub-agent delegation, and file edit, with diagnostics for missed parallelism, redundant work, and over-serialization.
+tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+---
+## Agent Pipeline
+
+This command runs inline and does not spawn sub-agents. Parsing is driven by Bash + jq over the on-disk session transcript; the LLM only sees aggregated counts and triggered-heuristic evidence, never the raw JSONL. This keeps the command efficient (P7) even on 1000+ record sessions.
+
+# Session Report — Agentic Action Replay
+
+Render an in-chat report of what happened in a Claude Code session: every tool call, every sub-agent `Agent` delegation, every file edit, every hook event. Default = current session, executive summary, in-chat. Flags extend scope and depth. Two audiences: (a) users who want to understand the session end-to-end; (b) maintainers investigating runtime shape for framework-level optimizations.
+
+---
+
+## Argument Parsing
+
+| Flag | Effect |
+|------|--------|
+| `--session <id\|path>` | Target a UUID under the project slug dir, or an absolute `.jsonl` path. Default = newest-mtime jsonl in current project slug. |
+| `--list` | Exclusive. Print the 5 most-recent sessions in this project (sessionId, mtime, first-user-message preview 60 chars). Skips all other rendering. |
+| `--verbose` | Append a chronological per-turn timeline after the executive summary. |
+| `--save` | After rendering in-chat, also write to `.hatch3r/reports/{sessionId-short8}-{YYYYMMDD-HHMMSS}.md`. |
+
+`--list` takes precedence over `--session`, `--verbose`, `--save`. All other flags compose.
+
+## Step 1 — Discover the Session
+
+Compute the project slug from the working directory: `SLUG="$(pwd | sed 's|/|-|g')"`. The transcript directory is `~/.claude/projects/${SLUG}`. List `*.jsonl` files; the active session is the newest by mtime (`ls -t *.jsonl | head -1`). When `--session <value>` is provided, resolve a 36-char UUID against the slug dir as `${value}.jsonl`, otherwise treat as an absolute path. When `--list` is set, enumerate the top-5 newest jsonl files; for each, parse the first `type=user` record and emit `<short-id>  <mtime>  <first-60-chars-of-user-text>`.
+
+## Step 2 — Aggregate via jq
+
+Run jq over the JSONL to produce a single structured JSON of counts. Persist to `$(mktemp)` so the LLM reads aggregated data only. Sample pipeline:
+
+```bash
+jq -s '
+  def tu: [.[] | select(.message.content?) | .message.content[] | select(.type=="tool_use")];
+  def tr: [.[] | select(.message.content?) | .message.content[] | select(.type=="tool_result")];
+  def asst_turns: [.[] | select(.type=="assistant" and (.message.content?))];
+  def thinks: [.[] | select(.message.content?) | .message.content[] | select(.type=="thinking") | .text];
+  {
+    sessionId: .[0].sessionId, firstTs: .[0].timestamp, lastTs: .[-1].timestamp,
+    cwd: .[0].cwd, gitBranch: .[0].gitBranch, records: length,
+    toolCounts: (tu | group_by(.name) | map({tool: .[0].name, count: length}) | sort_by(-.count)),
+    distinctReads: (tu | map(select(.name=="Read") | .input.file_path) | unique | length),
+    distinctEdits: (tu | map(select(.name=="Edit" or .name=="Write") | .input.file_path) | unique | length),
+    topReads: (tu | map(select(.name=="Read") | .input.file_path) | group_by(.) | map({path: .[0], count: length}) | sort_by(-.count) | .[0:3]),
+    agentCalls: (tu | map(select(.name=="Agent") | {sub: (.input.subagent_type // "general-purpose"), prompt: (.input.prompt[:80] // "")})),
+    bashCmds: (tu | map(select(.name=="Bash") | .input.command)),
+    turnLens: [asst_turns[] | (.message.content | map(select(.type=="tool_use")) | length)],
+    thinkingChars: ([thinks[] | length] | add // 0),
+    errorResults: (tr | map(select((.content | tostring) | test("error|failed"; "i"))) | length),
+    totalResults: (tr | length)
+  }' "$JSONL"
+```
+
+`thinkingChars` is the summed length of every `thinking` block's text — required input for D-LOOP-01 (`thinking chars ÷ (tool_use count + 1) > 1200`).
+
+The LLM reads the resulting JSON, computes derived metrics (parallel-batch count = turns with ≥2 tool_use; sequential count = turns with exactly 1), and builds the rendered tables.
+
+## Step 3 — Compute Diagnostics
+
+Apply each rule in §Diagnostic Heuristics over the aggregated structure. Each fired diagnostic produces a record `{id, severity, turns:[...], evidence, suggestion}`. Emit at most one fire per rule per session (consolidate same-rule fires across turns into one record). If zero rules fire, render `None — execution shape is clean.`
+
+## Step 4 — Render Executive Summary
+
+Always emit. Headings, order, and content per §Output Format. Mask obvious secret patterns (`sk-...`, `ghp_...`, `xoxb-...`, `AIza...`, `Bearer ...`) in any rendered tool_use input field. Truncate Bash commands and Agent prompts to ≤80 chars in tables.
+
+## Step 5 — Render Verbose Timeline (--verbose only)
+
+Append `## Timeline`. For each assistant turn containing ≥1 tool_use, emit a numbered block: turn index, ISO timestamp, elapsed-since-start, optional `thinking: N chars` summary, one line per tool_use (tool name + first 60 chars of primary input field), and a parallel/sequential marker — `→ {n} tool_use blocks ✓ parallel` when n≥2, `→ 1 tool_use ⚠ sequential` when n=1.
+
+## Step 6 — Save to Disk (--save only)
+
+Create `.hatch3r/reports/` if missing. Write the rendered markdown (executive summary + timeline if `--verbose` set) to `.hatch3r/reports/{sessionId-short8}-{YYYYMMDD-HHMMSS}.md`. Append a `## Raw Counts (machine-readable)` section containing the jq-aggregated JSON in a fenced ```json``` block — this lets future tooling grep across sessions without re-parsing the source JSONL. Print the file path back to chat. The `.hatch3r/` directory is gitignored.
+
+---
+
+## Output Format
+
+```markdown
+## Session Report — a5d750f7
+
+**Window:** 2026-05-12 09:14:03 → 09:47:21 (33m 18s, 272 records)
+**Project:** hatch3r (release/1.7.1)
+
+### Tool Activity (91 tool calls)
+
+| Tool | Calls | Notable |
+|------|------:|---------|
+| Read | 47 | 12 distinct files; validate.ts read 4x |
+| Bash | 21 | 6 parallel batches, 15 sequential |
+| Edit | 18 | 9 distinct files |
+| Task |  4 | 3 general-purpose, 1 explore — all sequential |
+| Grep |  1 | — |
+
+### Sub-Agent Delegation (4 Agent calls)
+
+| # | Subagent | Prompt (first 60) | Files touched |
+|---|----------|-------------------|---------------|
+| 1 | general-purpose | "Find references to validateCommandOrch..." | 0 |
+| 2 | Explore | "Map existing commands that overlap..." | 0 |
+| 3 | Explore | "Find conversation transcript access..." | 0 |
+| 4 | Plan | "Design hatch3r-report command..." | 0 |
+
+### File Footprint
+
+- 12 distinct files read; 9 distinct files edited
+- Top 3 most-read: src/cli/commands/validate.ts (4x), commands/hatch3r-context-health.md (2x), CHANGELOG.md (2x)
+
+### Diagnostics
+
+- WARN D-PAR-01 Missed parallelism: turns 7, 9, 11 each issued one Read on disjoint paths → batch into one assistant turn.
+- WARN D-RED-01 Redundant Read: src/cli/commands/validate.ts read at turns 4, 8, 22, 31 with no Edit between turns 4 and 31.
+- INFO D-PAR-02 Sub-agent fan-out: 4 Agent calls at turns 44, 53, 67, 78 — disjoint subsystems → eligible for parallel fan-out.
+
+### Suggested Next Action
+
+Re-run `/hatch3r-report --verbose` for the chronological timeline.
+```
+
+---
+
+## Diagnostic Heuristics
+
+| ID | Heuristic | Trigger | Severity |
+|----|-----------|---------|----------|
+| D-PAR-01 | Missed parallelism (same-tool sequential) | ≥3 consecutive assistant turns each with exactly 1 `tool_use` of the **same** tool type targeting disjoint inputs | WARN |
+| D-PAR-02 | Sub-agent fan-out missed | ≥2 `Agent` tool_use blocks within 10 turns where prompt subjects target disjoint path prefixes | WARN |
+| D-RED-01 | Redundant Read | Same `Read.file_path` in ≥3 tool_use blocks with no intervening `Edit`/`Write` on that path | WARN |
+| D-RED-02 | Re-Bash identical command | Same `Bash.command` (trimmed exact match) ≥2 times within 20 turns | INFO |
+| D-LOOP-01 | High thinking-to-action ratio | Total `thinking` chars ÷ (tool_use count + 1) > 1200 AND tool_use count < 8 | WARN |
+| D-LOOP-02 | Tool burst → stall | One turn with ≥5 tool_use blocks AND next turn with 0 AND ≥3 subsequent turns with 0 tool_use | INFO |
+| D-ERR-01 | Tool-result error rate | `tool_result.content` matches `/error\|failed/i` in >20% of results | WARN |
+| D-PATH-01 | File staleness | Path read at turn N, edited at turn M, re-read at turn P>M+15 with no intervening edit on that path | INFO |
+| D-SUB-01 | Sub-agent returning empty | `Agent` tool_result body <200 chars AND no subsequent Edit on any path the prompt referenced | WARN |
+
+Each fired record: `{id, severity, turns:[n,...], evidence, suggestion}`. Consolidate same-rule fires into one record per session.
+
+---
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| `~/.claude/projects/{slug}` does not exist | Print: "No Claude Code transcripts found for this project. Slug: {slug}". Exit. |
+| Slug dir exists but contains no `*.jsonl` | Print: "Project directory empty — no sessions to report on." Exit. |
+| `--session <id>` does not resolve to a readable file | Print: "Session {id} not found under {slug}. Use --list to see available sessions." Exit. |
+| `jq` not installed | Print: "jq is required. Install via `brew install jq` (macOS) or your distro's package manager, then retry." Exit. |
+| Malformed JSONL record encountered | Skip the record; increment a `skipped` counter; surface the count in the executive summary footer when non-zero. |
+| Read access denied to a transcript file | Print: "Cannot read {path}: permission denied." Exit. |
+
+---
+
+## Guardrails
+
+- **Never modify the JSONL.** Read-only access. All scratch files go to `$(mktemp)` and are deleted at end-of-run.
+- **Mask obvious secret patterns** (`sk-`, `ghp_`, `xoxb-`, `AIza`, `Bearer `) in any rendered tool_use input — substitute `{REDACTED-{prefix}}`. The transcript may contain ephemeral tokens from user pastes.
+- **Never write outside `.hatch3r/reports/`.** The `--save` target is fixed; do not honor flags or env vars that redirect output to other paths.
+- **Never abort on a malformed record.** Skip-and-count is the contract; aborting would hide the rest of the session from the operator (Silent Failure Contract — surface the skip count rather than swallowing it).
+- **Honor the iteration summary contract** (`rules/hatch3r-iteration-summary.md`) at the end of the parent assistant turn that invoked this command. The report content is not a substitute for the canonical Status / Outcome / Done block.

package/commands/hatch3r-revision.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-test-writer, ha
 description: User-guided revision of agent-implemented code in a fresh context window. Reconstructs what was done, interviews the user for feedback, fixes issues, cleans up leftovers, and drives toward merge readiness. Delegation, quality pipeline, modes, and board integration details are in commands/revision/.
 tags: [implementation, team]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -75,6 +79,18 @@ Initialize the run cache at the start of the workflow. See `commands/revision/re
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the revision request before delegating:
+
+- **Tier 1 (trivial)**: cleanup-only revision or 1–3 minor leftovers; reduced pipeline (Steps 1–2, 4–5, 8) with inline fixes and skip the full review loop in Step 7.
+- **Tier 2 (standard)**: standard user feedback with a mix of critical/important/cleanup findings; standard pipeline with sub-agent delegation (Step 6) and the review loop (Step 7a).
+- **Tier 3 (deep)**: deep revision with critical findings, architectural concerns, or board-deferred follow-ups; full pipeline including the parallel quality specialists in Step 7b and the merge-readiness gate in Step 9.
+
+If Tier 1, run the reduced pipeline. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including all quality specialists and confirm merge readiness with the user before commit.
+
+---
+
 ### Step 1: Context Reconstruction
 
 Rebuild full context in the fresh window. No prior implementation context is assumed.
@@ -129,7 +145,7 @@ Revision Context:
 
 **ASK:** "Is this the work you want to revise? Any additional context I should know about? (yes / provide context / wrong branch)"
 
-If the user provides additional context (e.g., a different issue number, clarifications, or scope adjustments), incorporate it before proceeding.
+When asking, use the platform-native question tool per `agents/shared/user-question-protocol.md`. If the user provides additional context (e.g., a different issue number, clarifications, or scope adjustments), incorporate it before proceeding.
 
 ---
 

package/commands/hatch3r-roadmap.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Sequence delivery phases over time into a dependency-ordered milestone plan with business and technical lenses, emitting a todo.md rollout schedule rather than design docs
 tags: [planning, greenfield]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 # Roadmap — Generate Phased Roadmap from Specs & Vision
 
@@ -35,6 +39,18 @@ Follow the **Token-Saving Directives** in `hatch3r-board-shared`.
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. When in doubt, **ASK** — it is better to ask one question too many than to make one wrong assumption. Discovery questions are never wasted.
 
+## Step 0: Triage
+
+Classify the roadmap request before delegating:
+
+- **Tier 1 (trivial)**: small project with focused scope (under 20 backlog items), single dimension (technical only); reduced fanout (1 researcher: Technical Readiness) and condensed todo.md output.
+- **Tier 2 (standard)**: standard dual-lens roadmap (business + technical) with both researchers; standard pipeline with parallel research and AGENTS.md generation.
+- **Tier 3 (deep)**: enterprise/scale company with regulatory deadlines, multi-quarter horizon, or 50+ backlog items; full pipeline with deep web research and confirm milestones with the user before writing files.
+
+If Tier 1, run the reduced researcher set and skip Step 7 (AGENTS.md) unless requested. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline with deep research, surface market-timing intelligence, and confirm phased plan with the user before file writes.
+
+---
+
 ### Step 1: Load Project Context & Business Discovery
 
 #### 1a. Load Existing Documentation

package/commands/hatch3r-rule-customize.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Edit rule scope globs, toggle always-on versus conditional activation, and adjust precedence tier via .hatch3r/rules/ YAML overrides plus markdown appends
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-security-audit.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Open an OWASP ASI security epic reviewing auth boundaries, input validation, and supply-chain risks with one hardening sub-issue per module plus trust-boundary audit
 tags: [maintenance, security]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-skill-customize.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Rewrite skill dispatch descriptions for model auto-selection, gate per-preset exposure, and control slash-command surfacing via .hatch3r/skills/ YAML overrides
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-test-plan.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Plan a comprehensive test strategy -- spawn parallel researchers, produce test plan spec with coverage targets, priority ordering, test case outlines, and structured todo.md entries for board-fill.
 tags: [core, planning]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -38,6 +42,18 @@ Take a test planning scope (feature, module, or codebase area) and produce a com
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the test-planning request before delegating:
+
+- **Tier 1 (trivial)**: tests for a single feature or single module with existing test infrastructure; reduced fanout (1–2 researchers: coverage-analysis, risk-prioritization) and produce a single-task todo entry.
+- **Tier 2 (standard)**: feature-scoped or module-coverage audit with mixed test types; standard pipeline with all 5 parallel researcher modes.
+- **Tier 3 (deep)**: full-suite restructure, mutation-testing rollout, contract testing, or coverage uplift across the whole codebase; full pipeline with deep research and confirm test plan scope with the user before writing files.
+
+If Tier 1, run the reduced researcher set and skip Step 6 (ADRs). If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including ADR generation for testing infrastructure decisions and confirm scope with the user before writing files.
+
+---
+
 ### Step 1: Gather Test Planning Scope
 
 1. **ASK:** "Tell me about the test strategy you want to plan. I need:

package/commands/hatch3r-workflow.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch
 description: Guided development lifecycle with 4 phases (Analyze, Plan, Implement, Review) and scale-adaptive Quick Mode for small tasks.
 tags: [core, implementation]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 # Development Workflow -- Guided Lifecycle for Structured Implementation
 
@@ -59,11 +63,23 @@ Downstream propagation: every ASK checkpoint that reports verification quality,
 
 ---
 
+## Triage
+
+Classify the development task before delegating. Detailed mode classification runs in Step 0 (Triage / Scale-Adaptive Mode Selection); this section summarizes the routing:
+
+- **Tier 1 (trivial)**: single-line edit, typo, or trivial config change; Quick Mode skips most ASK checkpoints and runs the streamlined 3-step path.
+- **Tier 2 (standard)**: bug fix or small feature in 1–3 files; Quick Mode with full sub-agent delegation (researcher, implementer, reviewer, fixer, test-writer, security-auditor).
+- **Tier 3 (deep)**: multi-module feature, architectural change, or cross-cutting refactor; Full Mode with all 4 phases (Analyze, Plan, Implement, Review) and deep research before mutating files.
+
+If Tier 1, take Quick Mode with reduced sub-agent prompts. If Tier 2, take Quick Mode below. If Tier 3, switch to Full Mode and confirm the plan with the user before implementation.
+
+---
+
 ## Workflow
 
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK. For every ASK checkpoint, use the platform-native question tool per `agents/shared/user-question-protocol.md`.
 
-### Step 0: Mode Selection (Scale-Adaptive)
+### Step 0: Triage (Scale-Adaptive Mode Selection)
 
 Assess the task to recommend a mode.
 

package/commands/revision/revision-board-integration.md

@@ -4,6 +4,7 @@ type: command
 description: Board integration for revision. Covers run cache schema, post-commit PR updates, dashboard refresh (Step 9a), and lightweight reconciliation (Step 9b).
 tags: [implementation, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Revision — Board Integration
 

package/commands/revision/revision-delegation.md

@@ -4,6 +4,7 @@ type: command
 description: Fix delegation protocol for revision Step 6. Covers complexity-aware grouping, blast radius context, sub-agent prompt templates, and cross-agent conflict resolution.
 tags: [implementation, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Revision — Fix Delegation (Step 6)
 

package/commands/revision/revision-modes.md

@@ -4,6 +4,7 @@ type: command
 description: Auto-advance mode, safety guardrails, error handling, and session report for revision. Covers --auto operation, never-skip rules, platform-aware error recovery, and end-of-session summary.
 tags: [implementation, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Revision — Modes, Guardrails, and Error Handling
 

package/commands/revision/revision-quality.md

@@ -4,6 +4,7 @@ type: command
 description: Quality verification pipeline for revision Step 7. Covers review loop (Stage 1), final quality with conditional specialists (Stage 2), and failure handling.
 tags: [implementation, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Revision — Quality Verification (Step 7)