hatch3r 1.6.2 → 1.7.0

package/agents/modes/coverage-analysis.md

@@ -5,6 +5,9 @@ description: Map existing test coverage, identify gaps, and surface critical unt
 tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `coverage-analysis`
 

package/agents/modes/current-state.md

@@ -4,6 +4,9 @@ type: mode
 description: Map the current state of code being analyzed — complexity, coupling, cohesion, coverage.
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `current-state`
 

package/agents/modes/feature-design.md

@@ -5,6 +5,9 @@ description: Break the subject down into implementable sub-tasks with user stori
 tags: [core, planning]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `feature-design`
 

package/agents/modes/impact-analysis.md

@@ -5,6 +5,9 @@ description: Map the blast radius of an issue across flows, modules, data, and u
 tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `impact-analysis`
 

package/agents/modes/library-docs.md

@@ -4,6 +4,9 @@ type: mode
 description: Look up current API documentation for specific libraries via Context7 MCP.
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `library-docs`
 

package/agents/modes/migration-path.md

@@ -5,6 +5,9 @@ description: Design a phased execution plan with safe ordering and rollback poin
 tags: [core, planning, implementation]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `migration-path`
 

package/agents/modes/prior-art.md

@@ -4,6 +4,9 @@ type: mode
 description: Research best practices, known issues, and ecosystem trends via web search.
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `prior-art`
 

package/agents/modes/refactoring-strategy.md

@@ -5,6 +5,9 @@ description: Design the refactoring approach with transformations, invariants, a
 tags: [core, planning, implementation]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `refactoring-strategy`
 

package/agents/modes/regression.md

@@ -5,6 +5,9 @@ description: Investigate when an issue was introduced by analyzing git history a
 tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `regression`
 

package/agents/modes/requirements-elicitation.md

@@ -5,6 +5,9 @@ description: Detect ambiguities and missing requirements, generate structured qu
 tags: [core, planning]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `requirements-elicitation`
 

package/agents/modes/risk-assessment.md

@@ -5,6 +5,9 @@ description: Identify risks, security implications, performance concerns, and br
 tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `risk-assessment`
 

package/agents/modes/risk-prioritization.md

@@ -5,6 +5,9 @@ description: Risk-ranked prioritization of testing effort by business impact and
 tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `risk-prioritization`
 

package/agents/modes/root-cause.md

@@ -5,6 +5,9 @@ description: Analyze the codebase for candidate root causes using static analysi
 tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `root-cause`
 

package/agents/modes/similar-implementation.md

@@ -4,6 +4,9 @@ type: mode
 description: Search the codebase for analogous features and extract implementation conventions.
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `similar-implementation`
 

package/agents/modes/symptom-trace.md

@@ -5,6 +5,9 @@ description: Trace reported symptoms through the codebase to find divergence poi
 tags: [core, planning, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `symptom-trace`
 

package/agents/modes/test-pattern.md

@@ -5,6 +5,9 @@ description: Extract existing test conventions, framework usage, mock patterns,
 tags: [core, review]
 parent: hatch3r-researcher
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
 ---
 ### Mode: `test-pattern`
 

package/agents/shared/efficiency-patterns.md

@@ -0,0 +1,71 @@
+---
+id: shared-efficiency-patterns
+type: reference
+description: Portable, model-agnostic patterns for token efficiency and runtime speed in end-user agentic flows. Referenced by agents and orchestrators via `efficiency_patterns:` frontmatter.
+tags: [shared, efficiency, p7]
+cache_friendly: true
+---
+
+## Efficiency Patterns
+
+> Last updated: 2026-04-27
+
+### Purpose
+
+This file lists the eight P7 efficiency patterns referenced by agents, orchestrator commands, and skills. The [quality charter](./quality-charter.md) dominates on conflict — efficiency must not weaken confidence calibration, root-cause reporting, or contract preservation.
+
+### The 8 Patterns
+
+| # | Pattern | Statement | Primary applies-to |
+|---|---------|-----------|--------------------|
+| P1 | Static-first prompt structure | Stable framing first, variable inputs last | agents, orchestrator commands, prompts |
+| P2 | Parallel-tool-by-default | When >=2 tool calls are independent, dispatch in one turn | agents, orchestrator commands |
+| P3 | Triage-first orchestration | Tier 1/2/3 classification before delegation | orchestrator: true commands |
+| P4 | Plan/Act split | Plan output then act-confirm for non-trivial work | implementer/fixer/architect/creator agents |
+| P5 | Structured outputs over prose | Tables for multi-attribute lists, JSON for handoff | all artifacts where applicable |
+| P6 | Lazy loading / reference-by-pointer | Reference shared content; do not embed | all artifacts |
+| P7 | Conditional skill/rule loading | Load only what the task requires | agents that delegate, orchestrator commands |
+| P8 | Diff-only outputs | Unified diff for code edits, full content only for new files | code-producing agents and skills |
+
+### Pattern detail
+
+**P1. Static-first prompt structure.** Do this: place tool definitions, role, contracts, and examples at the top of every artifact; place variable inputs (issue body, diff, user message) at the bottom. Verification: `scripts/validate-efficiency-invariants.ts --static-first` scans the first 60 lines for volatile-token regex hits.
+
+**P2. Parallel-tool-by-default.** Do this: when two or more tool calls have no data dependency, emit them in a single assistant turn rather than serial turns. Verification: `scripts/validate-efficiency-invariants.ts --parallel-tool` warns when an artifact has >=2 tool/sub-agent mentions without a parallel-dispatch directive nearby.
+
+**P3. Triage-first orchestration.** Do this: every command with `orchestrator: true` classifies inputs into Tier 1 (trivial, single-agent), Tier 2 (standard pipeline), or Tier 3 (research-first) before delegating. Verification: `scripts/validate-efficiency-invariants.ts --triage-first` requires a `triage_tiers` array in frontmatter and a Triage/Tier/Scale Assessment heading in body.
+
+**P4. Plan/Act split.** Do this: implementer, fixer, architect, and creator agents produce a plan artifact and pause for confirmation before mutating files when scope exceeds one file or 50 lines. Verification: convention-only — audited under D06 sub-agent 6.5 (no automated check).
+
+**P5. Structured outputs over prose.** Do this: use markdown tables for any list with >=2 attributes per item; use JSON code blocks for inter-agent handoff payloads. Verification: convention-only — audited under D06 sub-agent 6.5 (no automated check).
+
+**P6. Lazy loading / reference-by-pointer.** Do this: link to `agents/shared/*`, `rules/*`, `skills/*` rather than copying their content; embed only when the artifact is invoked without filesystem access. Verification: convention-only — audited under D06 sub-agent 6.5 (no automated check).
+
+**P7. Conditional skill/rule loading.** Do this: agents and orchestrator commands load only the skills and rules required by the current invocation; `scope: always` rules apply globally, tagged rules load only when their tag matches the task. Verification: convention-only — audited under D06 sub-agent 6.5 (no automated check).
+
+**P8. Diff-only outputs.** Do this: code-producing agents emit unified diffs for edits to existing files and full content only for new files. Verification: convention-only — audited under D06 sub-agent 6.5 (no automated check).
+
+### Conservative bias clause
+
+> Patterns must never override the quality charter. If applying a pattern would weaken confidence calibration, root-cause analysis, contract preservation, or any other charter directive, do not apply it. The quality charter is the dominant contract. When in doubt, do not optimize.
+
+Error toward keeping content over removing it. Apply patterns through structural compliance only — section ordering, table form, frontmatter declarations.
+Auto-rewrite of prose to fit a pattern is forbidden; structural moves are reversible, semantic edits are not. Sub-agents that detect a conflict between a pattern and the quality charter skip the pattern, log the skip in their structured output under `efficiency_skips`, and report the conflict rather than risk semantic loss.
+A pattern skip is never a finding by itself — only a pattern conflict that the sub-agent fails to surface counts as a regression.
+
+### Cross-platform notes
+
+| Pattern | Auto-benefit on these adapters | Required everywhere? |
+|---------|--------------------------------|----------------------|
+| P1 Static-first | Anthropic prompt caching, OpenAI Responses caching, Google Gemini implicit caching | yes |
+| P2 Parallel tools | All adapters where the host LLM supports parallel tool use | yes |
+| P3-P7 | All adapters | yes |
+| P8 Diff-only | All adapters except line-by-line autocomplete (e.g. github-agents/copilot) | conditional |
+
+### References
+
+- Anthropic Prompt Caching documentation (2025)
+- OpenAI Prompt Caching guide (2025)
+- Google Gemini Caching overview (2025)
+- arXiv: SWE-Bench compression studies (2026) and Plan-and-Act (2025)
+- Anthropic effective context engineering (2025)

package/agents/shared/external-knowledge.md

@@ -2,6 +2,8 @@
 id: shared-external-knowledge
 type: reference
 description: Shared external knowledge reference for all agents — tooling hierarchy, platform CLI, Context7 MCP, and web research guidance.
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 ## External Knowledge
 

package/agents/shared/injection-patterns.md

@@ -2,6 +2,8 @@
 id: shared-injection-patterns
 type: reference
 description: Canonical prompt-injection screening patterns — single source of truth for pipeline input sanitization, learnings validation, and user-facing injection screening guidance.
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 
 ## Injection Patterns Catalog

package/agents/shared/prompt-structure.md

@@ -2,6 +2,8 @@
 id: shared-prompt-structure
 type: reference
 description: XML-tag structuring pattern for agent prompts — reduces misinterpretation of instructions vs context vs rules per Anthropic Claude 4.x 2026 guidance.
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 
 ## Prompt Structure Pattern

package/agents/shared/quality-charter.md

@@ -2,6 +2,8 @@
 id: shared-quality-charter
 type: reference
 description: Shared quality charter for all agents — behavioral standards for senior-engineer-quality output.
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 
 ## Agent Quality Charter
@@ -94,3 +96,11 @@ When modifying code that is consumed by other modules, agents, or external syste
 - Verify existing consumers before changing function signatures, type shapes, event schemas, or API responses.
 - If a contract change is necessary, document it explicitly in the structured output and flag for reviewer attention.
 - Prefer additive changes (new optional fields, overloaded signatures) over breaking changes.
+
+### 10. Standardized Iteration Summary
+
+Every user-facing iteration ends with the canonical Iteration Summary block defined in `rules/hatch3r-iteration-summary.md`.
+
+Required fields: Status (closed enum: SUCCESS | PARTIAL | FAILED | BLOCKED), Outcome (one sentence), Done, Not Done / Deferred / Unverified, Open Questions / Blockers, Confidence + basis. Optional sections (Artifacts Touched, Verifications Run, Earliest Failure Point, Suggested Next Action) are appended only when they carry information.
+
+Never substitute a prose paragraph for the block. Never silently skip Not Done — if scope was fully completed, write `None — full scope completed`. Never inflate confidence — if you did not verify, say medium and name the unknown.

package/agents/shared/user-content-templates.md

@@ -0,0 +1,257 @@
+---
+id: shared-user-content-templates
+type: shared-context
+description: Body and frontmatter skeletons for the 5 user-authored content types. Referenced by hatch3r-creator at authoring time.
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+## User-Content Skeletons
+
+Canonical reference for the body and frontmatter shapes `hatch3r-creator` produces when a user invokes `/hatch3r-create`. Five sections, one per artifact type. Each provides the minimum frontmatter (YAML), a body skeleton with `<PLACEHOLDER>` substitution slots, and notes on required versus optional fields. Placeholder convention: `<NAME>` is replaced at composition time; `[<TAG-1>, <TAG-2>]` indicates an array.
+
+### 1. Agent Skeleton
+
+**Path:** `.agents/user/agents/<NAME>.md`. **Required:** `id`, `description`, `model`, `tags`. **Optional:** `protected` (always `false` for user agents), `quality_charter` (auto-injected), `adapters` (restricts adapter propagation when present).
+
+```yaml
+---
+id: <NAME>
+type: agent
+description: <DESCRIPTION>
+model: <MODEL>
+tags: [<TAG-1>, <TAG-2>]
+quality_charter: agents/shared/quality-charter.md
+---
+```
+
+```markdown
+You are <ROLE-STATEMENT> for the project. You receive <INPUT-SUMMARY> and produce <OUTPUT-SUMMARY>.
+
+Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<context>`, `<rules>` tags wrap role, runtime state, and constraints.
+
+<task>
+## Your Role
+- <BULLET-1>
+- <BULLET-2>
+</task>
+
+<context>
+## Inputs
+- <INPUT-SLOT-1>
+- <INPUT-SLOT-2>
+</context>
+
+## Implementation Protocol
+### 1. <STEP-1-TITLE>
+<STEP-1-BODY>
+### 2. <STEP-2-TITLE>
+<STEP-2-BODY>
+### 3. Return Structured Result
+{ status: "SUCCESS" | "BLOCKED", output: <FIELDS>, notes: <FREE-TEXT> }
+
+<rules>
+## Boundaries
+- **Always:** <ALWAYS-1>
+- **Never:** <NEVER-1>
+</rules>
+```
+
+### 2. Skill Skeleton
+
+**Path:** `.agents/user/skills/<NAME>/SKILL.md` inside a new directory created via `mkdir -p`. The layout matches the canonical pattern at `skills/hatch3r-<name>/SKILL.md`. **Required:** `id`, `description`, `tags`. **Optional:** `quality_charter` (auto-injected).
+
+```yaml
+---
+id: <NAME>
+type: skill
+description: <DESCRIPTION>
+tags: [<TAG-1>, <TAG-2>]
+quality_charter: agents/shared/quality-charter.md
+---
+```
+
+```markdown
+# <TITLE>
+
+## Quick Start
+Task Progress:
+- [ ] Step 1: <STEP-1-TITLE>
+- [ ] Step 2: <STEP-2-TITLE>
+- [ ] Step 3: <STEP-3-TITLE>
+- [ ] Step 4: Verification
+
+## Step 1: <STEP-1-TITLE>
+<STEP-1-BODY>
+
+## Step 2: <STEP-2-TITLE>
+<STEP-2-BODY>
+
+## Step 3: <STEP-3-TITLE>
+<STEP-3-BODY>
+
+## Step 4: Verification
+Run `<VERIFICATION-COMMAND>`. The skill is complete when:
+1. <ACCEPTANCE-CRITERION-1>
+2. <ACCEPTANCE-CRITERION-2>
+```
+
+Recommended step count: 3-7. Skills with more than 7 steps trigger a gentle warning suggesting decomposition.
+
+### 3. Rule Skeleton
+
+**Path:** `.agents/user/rules/<NAME>.md` plus the auto-generated companion `.agents/user/rules/<NAME>.mdc`. The `.md` is canonical; `.mdc` is generated by `saveUserContent` using the `.md → .mdc` scope transform from `rules/hatch3r-content-authoring.md`. **Required:** `id`, `type`, `description`, `scope`, `tags`. **Required when scope=conditional:** `globs`. **Optional:** `precedence` (default `normal`), `quality_charter` (auto-injected).
+
+Three scope shapes (pick one):
+
+| Shape | `scope:` line | `globs:` line | When to use |
+|---|---|---|---|
+| A | `scope: always` | (omit) | Applies every session, regardless of file context. |
+| B | `scope: "<GLOB-CSV>"` | (omit) | Legacy compact form — tooling treats it as conditional. |
+| C | `scope: conditional` | `globs: "<GLOB-CSV>"` | Explicit globs plus optional `precedence:`. |
+
+```yaml
+---
+id: <NAME>
+type: rule
+description: <DESCRIPTION>
+scope: <SHAPE-A-VALUE-OR-SHAPE-B-CSV-OR-conditional>
+globs: "<GLOB-CSV>"          # required for Shape C; omit for A/B
+precedence: <PRECEDENCE>     # Shape C only; default normal
+tags: [<TAG-1>]
+quality_charter: agents/shared/quality-charter.md
+---
+```
+
+```markdown
+# <TITLE>
+
+<SHORT-PARAGRAPH-DESCRIBING-THE-RULE>
+
+## Directives
+- <DIRECTIVE-1>
+- <DIRECTIVE-2>
+
+## When This Rule Applies
+<TRIGGER-CONDITIONS>
+
+## Examples
+<POSITIVE-AND-NEGATIVE-EXAMPLES>
+```
+
+The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a strict gate). The `.mdc` companion has different frontmatter — `saveUserContent` derives it from the `.md` scope shape per the table in `rules/hatch3r-content-authoring.md`.
+
+### 4. Command Skeleton
+
+**Path:** `.agents/user/commands/<NAME>.md`. **Required:** `id`, `type`, `description`, `orchestrator`, `tags`. **Required when orchestrator=true:** `agentPipeline` (non-empty array). **Optional:** `quality_charter` (auto-injected). Two variants follow; pick by the `orchestrator` value.
+
+```yaml
+# 4a. Inline command — orchestrator: false. Modeled after commands/hatch3r-recipe.md.
+---
+id: <NAME>
+type: command
+orchestrator: false
+description: <DESCRIPTION>
+tags: [<TAG-1>]
+quality_charter: agents/shared/quality-charter.md
+---
+```
+
+```yaml
+# 4b. Orchestrator command — orchestrator: true. Modeled after commands/hatch3r-board-init.md.
+---
+id: <NAME>
+type: command
+orchestrator: true
+agentPipeline: [<AGENT-ID-1>, <AGENT-ID-2>]
+description: <DESCRIPTION>
+tags: [<TAG-1>]
+quality_charter: agents/shared/quality-charter.md
+---
+```
+
+Body skeleton — 4a inline (single-section workflow with inline validation):
+
+```markdown
+## Agent Pipeline
+This command runs as a single orchestrator without sub-agent delegation.
+# <TITLE> — <ONE-LINE-PURPOSE>
+<INTRO-PARAGRAPH>
+## Workflow
+### Step 1: <STEP-1-TITLE>
+**ASK:** "<QUESTION-1>"
+### Step 2: <STEP-2-TITLE>
+<STEP-2-BODY>
+### Step 3: Validation Gates
+<INLINE-VALIDATION-CHECKS>
+### Step 4: Summary
+<TITLE> Result: <FIELD-1>: <VALUE>
+## Guardrails
+- <GUARDRAIL-1>
+```
+
+Body skeleton — 4b orchestrator (Phase 1 collect, Phase 2 delegate, Phase 3 housekeeping):
+
+```markdown
+## Agent Pipeline
+This command runs as an orchestrator. After collecting inputs in Phase 1, it delegates to <AGENT-ID-1> via the Task tool.
+# <TITLE>
+<INTRO-PARAGRAPH>
+## Workflow
+### Phase 1 — Collect & Plan
+#### 1.1: <SLOT-1>
+**ASK:** "<QUESTION-1>"
+#### 1.N: Plan Summary & Confirmation
+**ASK:** "Confirm to proceed, or specify changes."
+### Phase 2 — Delegate
+Use the Task tool to invoke <AGENT-ID-1>. Pass collected slots as structured input. Wait for the structured return.
+### Phase 3 — Housekeeping
+<POST-DELEGATION-STEPS>
+## Guardrails
+- <GUARDRAIL-1>
+```
+
+The strict gate `validateCommandOrchestratorFrontmatter` (`src/cli/commands/validate.ts:171`) rejects `orchestrator: true` without a non-empty `agentPipeline` array.
+
+### 5. Hook Skeleton
+
+**Path:** `.agents/user/hooks/<NAME>.md`. **Required:** `id`, `type`, `event`, `agent`, `description`, `tags`. **Optional:** `globs` (file-save filtering), `condition`, `quality_charter` (auto-injected). **Event enum:** `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`, enforced by `isValidHookEvent` (`src/hooks/types.ts:30`).
+
+```yaml
+---
+id: <NAME>
+type: hook
+event: <EVENT>
+agent: <AGENT-ID>
+description: <DESCRIPTION>
+globs: "<GLOB-CSV>"
+tags: [<TAG-1>]
+quality_charter: agents/shared/quality-charter.md
+---
+```
+
+```markdown
+# Hook: <EVENT> → <AGENT-ID>
+<SHORT-PARAGRAPH-DESCRIBING-WHAT-THE-HOOK-DOES-AND-WHEN-IT-FIRES>
+## Agent Behavior
+When this hook fires, the assigned agent should:
+1. <STEP-1>
+2. <STEP-2>
+## Trigger Conditions
+- **Event:** <EVENT>
+- **Glob filter:** <GLOB-CSV-OR-NONE>
+## Output
+<DESCRIBES-WHAT-THE-AGENT-RETURNS-OR-WRITES>
+```
+
+The `agent` field must reference an existing agent — canonical (e.g., `lint-fixer` resolves to `agents/hatch3r-lint-fixer.md`) or under `.agents/user/agents/`. Missing references are rejected at strict-gate time.
+
+## Reference Implementations
+
+For each user type, mirror the canonical shape below — minus the `hatch3r-` filename prefix; the user-tier path is always under `.agents/user/{type}/`:
+
+- **Agent:** `agents/hatch3r-implementer.md` (full body) or `agents/hatch3r-fixer.md` (compact body).
+- **Skill:** `skills/hatch3r-bug-fix/SKILL.md` or `skills/hatch3r-feature/SKILL.md`.
+- **Rule:** `rules/hatch3r-deep-context.md` (`scope: always`) or `rules/hatch3r-component-conventions.md` (`scope: conditional`).
+- **Command:** `commands/hatch3r-recipe.md` (inline) or `commands/hatch3r-board-init.md` (orchestrator).
+- **Hook:** `hooks/hatch3r-pre-commit.md` (with globs) or `hooks/hatch3r-session-start.md` (always-fire).

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