hatch3r 1.6.2 → 1.7.1

package/agents/shared/user-question-protocol.md

@@ -0,0 +1,95 @@
+---
+id: shared-user-question-protocol
+type: reference
+description: Protocol for how hatch3r agents and commands ask the user clarifying questions — when to ask, native-tool preference, and a plain-text fallback shape.
+tags: [shared, ux, p1, p4]
+cache_friendly: true
+---
+
+## Purpose
+
+This protocol defines how hatch3r agents and commands surface clarifying or triage questions to the user across the 15 supported AI coding platforms. It is the single source of truth for the *how* of asking; the *whether* is governed by [quality-charter §3 "Question Unclear Requirements"](./quality-charter.md) and §8 "Escalate Ambiguity Early". Files that reference this protocol: the requirements-elicitation mode (`agents/modes/requirements-elicitation.md`), the five ASK-checkpoint commands, and the four ask-prone agents — researcher, fixer, architect, implementer.
+
+## When To Ask
+
+- **Ambiguous requirement** — the request maps to two or more reasonable interpretations that produce different code.
+- **Irreversible decision** — deleting data, renaming a public API, dropping a column, force-pushing a branch.
+- **Branching path** — two or more viable approaches with materially different cost, scope, or risk.
+- **Conflicting constraints** — requirements that cannot all hold (e.g., "no new dependencies" and "use library X").
+- **Missing acceptance criteria** — no testable definition of done for the requested change.
+
+## When NOT To Ask
+
+- The user already decided scope in this turn or an earlier turn of the same session.
+- You are in free-text discussion, planning, or a status update — questions belong inside actionable workflows.
+- The answer is verifiable by reading code, running a test, or grepping the repo — verify first, ask only if verification fails.
+- The choice is reversible, low-stakes, and the safer default is obvious — pick the default and note it.
+
+## How To Ask
+
+1. Check whether your target platform exposes a native question or triage tool (see Platform-Native Tool below).
+2. If yes, use the native tool — it produces better UX than free-text replies and is structured for the host runtime.
+3. If no native tool exists on this platform, use the Plain-Text Fallback Template.
+4. Ask at most one question per turn. Bundle related sub-questions into a single multiple-choice prompt rather than firing multiple turns.
+
+## Platform-Native Tool
+
+The marker below is replaced at canonical-write time with the enumeration table generated from `src/pipeline/adapterToolTranslator.ts::ASK_USER_TOOLS`. Look up your runtime platform and follow its row. If your platform's row reads "No documented native tool", use the Plain-Text Fallback Template defined in the next section.
+
+<!-- HATCH3R:PLATFORM-TOOL -->
+
+When viewing this file in the source repo (pre-generation), the marker is unsubstituted — refer to the adapter map in `src/pipeline/adapterToolTranslator.ts` for the same mappings.
+
+## Plain-Text Fallback Template
+
+Use this exact shape when no native tool is available:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules for the template:
+
+- Two to four numbered options. One option is too few; five or more signals you have not narrowed the design.
+- Each option carries a one-line trade-off so the user can pick without re-deriving the problem.
+- The default-if-no-response line is mandatory — it removes the deadlock when the user is away or replies "you decide".
+- The default option is the safest reversible choice, not the most ambitious one.
+
+## Examples
+
+**Example 1 — Ambiguous requirement.** Request: "Add caching to the user profile endpoint."
+
+```
+**Question:** Which cache scope matches your needs for the profile endpoint?
+
+1. Per-user, 60s TTL — fastest response, stale data tolerated up to 60s.
+2. Per-user, write-through invalidation — fresh data, +1 cache write per profile update.
+3. Edge cache only — no app changes, but TTL is fixed by the CDN config.
+
+Default if no response: 2
+```
+
+**Example 2 — Branching path.** Request: "Migrate the build to Vite."
+
+```
+**Question:** Should the Vite migration land in one PR or staged behind a feature flag?
+
+1. Single PR — shorter total time, larger blast radius if a regression ships.
+2. Staged with VITE_BUILD flag — two PRs, lets you A/B locally before flipping.
+
+Default if no response: 2
+```
+
+## Anti-Patterns
+
+- **Multi-question barrage** — asking five questions in one turn. Ask the highest-leverage one first; the answer often collapses the rest.
+- **Options-free questions** — "What should I do?" forces the user to design the prompt. Always supply 2–4 candidate options with trade-offs.
+- **Silent assumption** — proceeding when ambiguity is real. Apply quality-charter §8: log the ambiguity in structured output even if you decide to proceed under a default.
+- **Echo-as-question** — restating the user's request back as a question ("So you want me to add caching?"). Confirm only when you have a specific decision point with options to offer.
+- **Inflated default** — choosing the most disruptive option as the no-response default. Defaults must be the reversible, lowest-blast-radius choice.

package/checks/accessibility.md

@@ -2,6 +2,7 @@
 id: accessibility
 type: check
 description: Accessibility review criteria covering WCAG compliance, semantic HTML, keyboard navigation, screen reader support, and inclusive design patterns
+cache_friendly: true
 ---
 # Accessibility Check
 

package/checks/code-quality.md

@@ -2,6 +2,7 @@
 id: code-quality
 type: check
 description: Code quality review criteria covering standards compliance, complexity, maintainability, and architectural patterns
+cache_friendly: true
 ---
 # Code Quality Check
 

package/checks/performance.md

@@ -2,6 +2,7 @@
 id: performance
 type: check
 description: Performance review criteria covering bundle size, render performance, memory usage, network optimization, database queries, and runtime efficiency
+cache_friendly: true
 ---
 # Performance Check
 

package/checks/security.md

@@ -2,6 +2,7 @@
 id: security
 type: check
 description: Security review criteria covering vulnerability patterns, input validation, authentication, secrets handling, and dependency safety
+cache_friendly: true
 ---
 # Security Check
 

package/checks/testing.md

@@ -2,6 +2,7 @@
 id: testing
 type: check
 description: Test coverage review criteria covering test quality, regression testing, test isolation, and coverage requirements
+cache_friendly: true
 ---
 # Testing Check
 

package/commands/board/pickup-azure-devops.md

@@ -4,6 +4,7 @@ type: command
 description: Azure DevOps-specific platform procedures for board-pickup. Covers az CLI commands for work item listing, status updates, collision detection, PR creation, and state transitions.
 tags: [board, team, azure-devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — Azure DevOps Platform Details
 

package/commands/board/pickup-delegation-multi.md

@@ -4,6 +4,7 @@ type: command
 description: Multi-issue sub-agent delegation protocols for board-pickup Steps 6b (epics) and 6c (batch). Covers level-by-level parallel execution, shared context, and quality pipelines.
 tags: [board, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — Multi-Issue Delegation (Steps 6b, 6c)
 

package/commands/board/pickup-delegation.md

@@ -4,6 +4,7 @@ type: command
 description: Single-issue sub-agent delegation protocol for board-pickup Step 6a. Covers research, implementation, and quality pipeline for standalone issues.
 tags: [board, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — Single-Issue Delegation (Step 6a)
 

package/commands/board/pickup-github.md

@@ -4,6 +4,7 @@ type: command
 description: GitHub-specific platform procedures for board-pickup. Covers gh CLI commands for issue listing, status updates, collision detection, PR creation, and label transitions.
 tags: [board, team, github]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — GitHub Platform Details
 

package/commands/board/pickup-gitlab.md

@@ -4,6 +4,7 @@ type: command
 description: GitLab-specific platform procedures for board-pickup. Covers glab CLI commands for issue listing, status updates, collision detection, MR creation, and label transitions.
 tags: [board, team, gitlab]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — GitLab Platform Details
 

package/commands/board/pickup-modes.md

@@ -4,6 +4,7 @@ type: command
 description: Auto-advance mode, error handling, and guardrails for board-pickup. Covers --auto/--unattended operation, safety guardrails, and specification generation.
 tags: [board, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — Modes, Guardrails, and Error Handling
 

package/commands/board/pickup-post-impl.md

@@ -4,6 +4,7 @@ type: command
 description: Post-implementation steps for board-pickup (Steps 7-10). Covers quality verification, commit/push, PR/MR creation, label transitions, board sync, dashboard refresh, reconciliation, and learnings capture.
 tags: [board, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Pickup — Post-Implementation Steps (7-10)
 

package/commands/board/shared-azure-devops.md

@@ -4,6 +4,7 @@ type: shared-context
 description: Azure DevOps-specific platform details for board shared context. Covers Work Items, Azure Boards, az CLI, and MCP tools.
 tags: [board, team, azure-devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Shared Reference — Azure DevOps Platform Details
 
@@ -155,6 +156,8 @@ After linking, verify via `az boards work-item relation list --id {epic}` and ch
 | Add comments         | `az boards work-item update --id N --discussion "..."`                                         | N/A                    |
 | Create PRs           | `az repos pr create --title "..." --source-branch "..." --target-branch "..."`                 | `create_pull_request`  |
 | Read PR details      | `az repos pr show --id N`                                                                      | N/A                    |
+| Read PR comment threads | `az rest -m GET --url 'https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/pullRequests/{N}/threads?api-version=7.1-preview.1'` | N/A |
+| Reply to PR thread   | `az rest -m POST --url '.../pullRequests/{N}/threads/{threadId}/comments?api-version=7.1-preview.1' --body '{"parentCommentId":1,"content":"...","commentType":"text"}'` | N/A |
 | Manage tags          | `az boards work-item update --id N --fields "System.Tags=tag1; tag2"`                          | N/A                    |
 | Board sync           | Work Item State updates (automatic board placement)                                             | N/A                    |
 | CI/Pipelines         | `az pipelines run list` / `az pipelines run show`                                              | N/A                    |

package/commands/board/shared-board-overview.md

@@ -4,6 +4,7 @@ type: shared-context
 description: Board overview dashboard template, model pool, model selection heuristic, and lane computation algorithm. Referenced from hatch3r-board-shared.
 tags: [board, team]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Overview Reference
 

package/commands/board/shared-github.md

@@ -4,6 +4,7 @@ type: shared-context
 description: GitHub-specific platform details for board shared context. Covers GitHub Issues, Projects V2, gh CLI, and MCP tools.
 tags: [board, team, github]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Shared Reference — GitHub Platform Details
 
@@ -165,9 +166,26 @@ After linking, verify via `issue_read` with `method: get_sub_issues` on the pare
 | Add comments         | `gh issue comment`                                                                                          | `add_issue_comment`                                 |
 | Create PRs           | `gh pr create`                                                                                              | `create_pull_request`                               |
 | Read PR details      | `gh pr view`                                                                                                | `pull_request_read`                                 |
+| Read PR inline comments | `gh api repos/{owner}/{repo}/pulls/{N}/comments --paginate`                                              | `pull_request_read`                                 |
+| Read PR review summaries | `gh api repos/{owner}/{repo}/pulls/{N}/reviews --paginate`                                              | `pull_request_read`                                 |
+| Read PR discussion   | `gh api repos/{owner}/{repo}/issues/{N}/comments --paginate`                                                | `pull_request_read`                                 |
+| Read PR thread resolution | `gh api graphql -f query='{repository(owner:"o",name:"r"){pullRequest(number:N){reviewThreads(first:100){nodes{id,isResolved}}}}}'` | N/A                                |
+| Reply to inline comment | `gh api repos/{owner}/{repo}/pulls/{N}/comments -X POST -F in_reply_to={comment_id} -f body=@{file}`     | N/A                                                 |
+| Comment on PR thread | `gh api repos/{owner}/{repo}/issues/{N}/comments -X POST -f body=@{file}`                                   | `add_issue_comment`                                 |
 | Manage labels        | `gh label create` / `gh label list`                                                                         | `issue_write` (with labels)                         |
 | Projects v2          | `gh project item-add`, `gh project item-edit`, `gh project item-list`, `gh project field-list`, `gh project view` | `projects_write` / `projects_get` / `projects_list` |
 | CI/Actions           | `gh run list` / `gh run view`                                                                               | N/A                                                 |
 | Releases             | `gh release create`                                                                                         | N/A                                                 |
 
 Fallback to MCP only for operations the `gh` CLI cannot handle: sub-issue management (`sub_issue_write`).
+
+### GitHub CLI Field-Typing Notes
+
+`gh api` field flags differ by type. Pass the wrong one and the GitHub REST API returns `HTTP 422: not of type {integer|boolean}`.
+
+| Flag | Type sent | Use for |
+|------|-----------|---------|
+| `-f key=value` | string (URL-encoded form) | `body`, `title`, `commit_message`, `query`, `state`, `event` |
+| `-F key=value` | integer / boolean (auto-typed) — also `@file` for file contents | numeric IDs: `sub_issue_id`, `in_reply_to`, `parent_issue_id`, `issue_number`, `pull_number`, `team_id`, `user_id`, `milestone_number`; booleans: `draft`, `merged`, `auto_merge` |
+
+Sub-issue linking via `POST /repos/{owner}/{repo}/issues/{N}/sub_issues` requires `-F sub_issue_id={child_numeric_id}` — `-f` returns 422. When the `sub_issue_write` MCP is unavailable, write the hand-rolled `gh api` call with `-F`, never `-f`. The same rule applies to PR review-reply (`in_reply_to`), milestone assignment (`milestone_number`), and team membership (`team_id` / `user_id`).

package/commands/board/shared-gitlab.md

@@ -4,6 +4,7 @@ type: shared-context
 description: GitLab-specific platform details for board shared context. Covers GitLab Issues, Issue Boards, glab CLI, and label-based sync.
 tags: [board, team, gitlab]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Board Shared Reference — GitLab Platform Details
 
@@ -145,6 +146,10 @@ After linking, verify via `glab api projects/{project_id}/issues/{epic_iid}/link
 | Add comments         | `glab issue note N -R {namespace}/{project}`                  | N/A            |
 | Create MRs           | `glab mr create -R {namespace}/{project}`                     | N/A            |
 | Read MR details      | `glab mr view N -R {namespace}/{project}`                     | N/A            |
+| Read MR discussions  | `glab api '/projects/{project_id}/merge_requests/{iid}/discussions?per_page=100' --paginate` | N/A |
+| Read MR notes        | `glab api '/projects/{project_id}/merge_requests/{iid}/notes?per_page=100' --paginate`       | N/A |
+| Reply to discussion  | `glab api '/projects/{project_id}/merge_requests/{iid}/discussions/{discussion_id}/notes' -X POST -f body=@{file}` | N/A |
+| Add MR note          | `glab api '/projects/{project_id}/merge_requests/{iid}/notes' -X POST -f body=@{file}`       | N/A |
 | Manage labels        | `glab label create` / `glab label list`                       | N/A            |
 | Board sync           | Label updates (automatic board list placement)                | N/A            |
 | CI/Pipelines         | `glab ci list` / `glab ci view`                               | N/A            |

package/commands/hatch3r-agent-customize.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Override agent persona, model selection, preset enablement, and repo-file apply-scope via YAML plus markdown injection under .hatch3r/agents/
 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
@@ -92,8 +95,10 @@ PostgreSQL for persistence, Redis for caching.
 
 ### Resulting Adapter Output
 
+The adapter wraps the result in hatch3r-managed block comments (literal markers omitted here so this file itself stays valid):
+
 ```markdown
-<!-- HATCH3R:BEGIN -->
+[managed-block-start]
 {canonical agent content}
 
 ---
@@ -101,9 +106,11 @@ PostgreSQL for persistence, Redis for caching.
 ## Project Customizations
 
 {content from .customize.md}
-<!-- HATCH3R:END -->
+[managed-block-end]
 ```
 
+Replace `[managed-block-start]` / `[managed-block-end]` with the actual `<!-- HATCH3R\:BEGIN -->` / `<!-- HATCH3R\:END -->` markers in real adapter output.
+
 Content placed **outside** the managed block markers by directly editing adapter output files is always preserved.
 
 ## Per-Agent Customization Examples

package/commands/hatch3r-api-spec.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer, hatch3r-reviewer]
 description: Generate or validate an OpenAPI specification from the codebase. Scans route definitions, extracts schemas, and produces a complete API spec.
 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
@@ -42,6 +46,18 @@ Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 sp
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the request before delegating:
+
+- **Tier 1 (trivial)**: single-endpoint documentation update or schema tweak; inline execution, no sub-agent fanout.
+- **Tier 2 (standard)**: feature-scoped spec generation or validate mode for an existing API; standard pipeline including review loop.
+- **Tier 3 (deep)**: full codebase scan, multi-framework detection, or breaking-change drift; full pipeline with research and confirm with the user before mutating files.
+
+If Tier 1, complete inline and skip the parallel researcher fanout. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline with research and confirm scope with the user before writing the spec.
+
+---
+
 ### Step 1: Gather API Context
 
 1. **ASK:** "I'll generate or validate an OpenAPI specification from your codebase. I need:

package/commands/hatch3r-benchmark.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-perf-profiler, hatch3r-docs-writer]
 description: Run and analyze performance benchmarks. Compare results against baselines, identify regressions, and produce performance reports.
 tags: [review, performance]
 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
@@ -40,6 +44,18 @@ Run performance benchmarks against a target (file, function, endpoint, or full s
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the benchmark request before delegating:
+
+- **Tier 1 (trivial)**: single benchmark with `none` baseline or quick re-run of an existing suite; inline execution, no `hatch3r-perf-profiler` fanout.
+- **Tier 2 (standard)**: standard suite with `previous-run` or git-ref baseline; standard pipeline including statistical analysis and reporting.
+- **Tier 3 (deep)**: full-suite cross-environment benchmark with regression triage and root-cause tracing; full pipeline with research and confirm scope with the user before saving results.
+
+If Tier 1, complete inline and skip the analysis fanout. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline with research and confirm scope with the user before saving results.
+
+---
+
 ### Step 1: Gather Benchmark Context
 
 1. **ASK:** "Tell me about the benchmarks you want to run. I need:

package/commands/hatch3r-board-fill.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-reviewer, hatch3r-fixer]
 description: Create epics and issues/work items from todo.md, reorganize the board with dependency analysis, readiness assessment, and implementation ordering. Supports GitHub, Azure DevOps, and GitLab.
 tags: [board, 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
@@ -51,7 +55,19 @@ Follow the **Token-Saving Directives** in `hatch3r-board-shared`.
 
 ## 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: Triage
+
+Classify the board-fill request before delegating:
+
+- **Tier 1 (trivial)**: 1–3 todo items, all clear scope, no decomposition needed; inline issue creation with minimal triage questioning.
+- **Tier 2 (standard)**: standard batch (4–15 items) with mixed clarity and grouping decisions; standard pipeline with item-level triage (Step 2.5) and full readiness assessment.
+- **Tier 3 (deep)**: large board reorganization, vision-driven greenfield batching, or 15+ items with decomposition; full pipeline with deep triage and confirm scope with the user before any GitHub mutations.
+
+If Tier 1, run only Steps 1–3, 5–6, and 7 (skip the heavy production-readiness review). If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including Steps 5.5, 5.6, and 7.9, and confirm batch composition with the user before executing.
+
+---
 
 ### Step 1: Read and Parse todo.md
 

package/commands/hatch3r-board-groom.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Ongoing backlog refinement for existing board items. Re-prioritize, reclassify, re-scope, archive stale items, decompose oversized issues, merge duplicates, refresh dependencies, and remediate board health findings.
 tags: [board, team]
 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-board-init.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Initialize a project board (GitHub Projects V2, Azure Boards, or GitLab Issue Boards) with hatch3r's label taxonomy, status fields, and board structure. Platform detected from hatch.json.
 tags: [board, team]
 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-board-pickup.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch
 description: Pick up one or more epics/issues from the project board for development. Handles dependency-aware selection, collision detection, branching, parallel sub-agent delegation, and batch execution. Supports GitHub, Azure DevOps, and GitLab. Platform-specific details are in commands/board/pickup-{platform}.md.
 tags: [board, 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]
 ---
 # Board Pickup -- Develop Issues from the Project Board
 
@@ -69,7 +73,19 @@ Downstream propagation: every ASK checkpoint that reports verification quality,
 
 ## 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. When asking the user how to proceed, use the platform-native question tool per `agents/shared/user-question-protocol.md`.
+
+## Step 0: Triage
+
+Classify the pickup request before delegating:
+
+- **Tier 1 (trivial)**: single sub-issue, isolated change, clear acceptance criteria; standard pipeline but with `quick` researcher depth and no parallel batch.
+- **Tier 2 (standard)**: single epic with sub-issues, or 2–3 independent issues in a batch; standard pipeline with researcher per issue and parallel implementer fanout.
+- **Tier 3 (deep)**: cross-cutting epic, contract change, multi-module batch, or audit epic; full pipeline with deep research, confirm sub-issue selection with the user, and serialize work that touches overlapping files.
+
+If Tier 1, run the standard delegation path (Step 6a) with reduced research depth. If Tier 2, run the standard pipeline below with parallel fanout where dependencies allow. If Tier 3, run the full pipeline with deep research and confirm batch composition with the user before branching.
+
+---
 
 ### Step 1: List Available Work (Dependency-Aware)
 

package/commands/hatch3r-board-refresh.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Regenerate the living board overview dashboard from current board state. Scans all open issues, computes health metrics, and updates the meta:board-overview issue.
 tags: [board, team]
 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-board-shared.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Shared context and procedures for all board commands. Provides platform-agnostic board config, label taxonomy, branch conventions, sync enforcement, and tooling directives. Platform-specific details are in commands/board/shared-{platform}.md.
 tags: [board, team]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 # Board Shared Reference
 
@@ -270,6 +273,27 @@ During **board-fill Step 4c** (external research) and **board-pickup Step 6** (i
 2. Use **web research** for novel technical challenges, current best practices, security advisories, or breaking changes not covered by Context7 or local docs.
 3. Follow the project's tooling hierarchy for knowledge augmentation priority.
 
+### Agent-Synthesized Wrapper Scripts
+
+Board commands instruct the agent to invoke individual CLI / MCP calls; the agent harness already batches them. If the agent synthesises a wrapper shell script anyway, the script MUST be portable across the user's installed shells. macOS ships `bash 3.2` as `/bin/bash` and many users default to `zsh` — bash-4-only features fail loudly on both.
+
+1. **Default to individual tool calls.** Do not wrap `gh issue create`, `gh issue edit`, `gh project item-add`, `az boards work-item create`, or `glab issue create` loops in a synthesised bash script unless the user explicitly asks for a script artifact. The harness's parallel tool dispatch is cheaper than spawning a sub-shell and avoids the portability problem entirely.
+2. **If a wrapper is required, target `bash 3.2` (macOS system default).** Banned constructs: `declare -A` (associative arrays), `${!ARR[@]}` (associative-array key expansion), `mapfile`, `readarray`. Use parallel indexed arrays (`KEYS=()`, `VALUES=()`) with integer indices, or rewrite the batching logic in Python / Node. `zsh` is not a drop-in substitute — `${!ARR[@]}` semantics differ; `bad substitution` is the symptom.
+3. **Pin the shell explicitly.** Start every synthesised script with `#!/usr/bin/env bash` and guard any bash-4+ feature behind `[[ ${BASH_VERSINFO[0]} -ge 4 ]] || { echo "bash 4+ required, found ${BASH_VERSION}"; exit 64; }` so the failure mode is loud, not silent.
+
+### Pager-Bypass Directive
+
+Every `gh api`, `gh pr view`, `gh issue view`, `gh project item-list`, `az pipelines run`, and `glab api` invocation from an agent-driven terminal MUST run with `GH_PAGER=cat` and `PAGER=cat` set. The default GitHub CLI pager (`less`) opens the alternate screen buffer, which returns empty captured output in non-TTY contexts — the call appears to succeed but its `--jq` output is lost. Piping to `| cat` does not bypass the alternate-buffer behaviour; the environment variables are the only reliable workaround.
+
+Set once at the start of every board / PR command run, before the first CLI invocation:
+
+```bash
+export GH_PAGER=cat
+export PAGER=cat
+```
+
+The export is idempotent and safe to re-set. `GH_PAGER` is scoped to `gh`; `PAGER` covers downstream `git`, `az`, or `glab` invocations. This directive applies to every command in this directory tree.
+
 ---
 
 ## Formatting Rules

package/commands/hatch3r-bug-plan.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Diagnose a complex incident -- reproduce the symptom, rank root-cause hypotheses, design the fix path, and emit regression coverage items as a board-ready investigation
 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
@@ -43,6 +47,18 @@ Take a complex or ambiguous bug report and produce a structured investigation 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 bug investigation before delegating:
+
+- **Tier 1 (trivial)**: clear root cause, single module, reproduction known; route to `hatch3r-bug-fix` skill instead of running this full investigation.
+- **Tier 2 (standard)**: ambiguous symptoms across one subsystem with 2–3 plausible hypotheses; standard pipeline with the 5 parallel researcher modes.
+- **Tier 3 (deep)**: multi-module, intermittent, lingering bug requiring ADRs and phased fixes; full pipeline with deep research and confirm scope with the user before generating fix items.
+
+If Tier 1, recommend the `hatch3r-bug-fix` skill and exit. If Tier 2, run the standard parallel-researcher pipeline below. If Tier 3, run the full pipeline including ADR generation in Step 6 and confirm fix phases with the user before writing files.
+
+---
+
 ### Step 1: Gather Bug Report
 
 1. **ASK:** "Tell me about the bug you want to investigate. I need:

package/commands/hatch3r-codebase-map.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Reverse-engineer a brownfield codebase into current-state module boundaries, integration-point inventory, tech-debt register, and dependency graph via static analysis
 tags: [planning, brownfield]
 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]
 ---
 # Codebase Map — Brownfield Codebase Analysis & Spec Generation
 
@@ -38,6 +42,18 @@ Analyze an existing codebase to reverse-engineer 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 codebase analysis request before delegating:
+
+- **Tier 1 (trivial)**: single-module spec or scoped reverse-engineering of one subsystem; reduced fanout (1–2 analyzers), no AGENTS.md regeneration unless requested.
+- **Tier 2 (standard)**: standard scope (full repo, < 5K files) with both technical and business specs; standard pipeline with all 6 parallel analyzers and AGENTS.md generation.
+- **Tier 3 (deep)**: monorepo, very large codebase (>10K files), or full production-readiness audit; full pipeline with all analyzers and confirm scope with the user before writing files.
+
+If Tier 1, run the reduced analyzer set and skip Step 5 (ADRs) unless decisions are obvious. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including the production-readiness scorecard and confirm scope with the user before file writes.
+
+---
+
 ### Step 1: Initial Scan, Scope & Discovery
 
 Perform a lightweight scan of the project root to build a project fingerprint, then gather business context.

package/commands/hatch3r-command-customize.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Tune slash-command display text, orchestrator sub-agent dispatch pipeline, and invocation arguments via .hatch3r/commands/ YAML and markdown 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-context-health.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Monitor conversation context health, detect degradation, and auto-suggest fresh context or sub-agent delegation
 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
 

package/commands/hatch3r-cost-tracking.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Track and report token usage and estimated costs across agent workflows and board operations
 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