hatch3r 1.6.0 → 1.7.0

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
 

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
 

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
 

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
@@ -53,6 +57,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.
 
+## 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
 
 1. Read `todo.md` at the project root.

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
 
@@ -71,6 +75,18 @@ Downstream propagation: every ASK checkpoint that reports verification quality,
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## 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)
 
 #### 1a. Fetch and Parse Board State

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
 

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
 

package/commands/hatch3r-create.md

@@ -0,0 +1,197 @@
+---
+id: hatch3r-create
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-creator]
+description: Author a custom user-tier artifact (agent, skill, rule, command, or hook) for this project. Generates frontmatter and body skeleton, applies strict + gentle quality gates, writes to .agents/user/{type}/, and offers to sync to all enabled adapters.
+tags: [core, customize]
+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
+
+This command runs as an orchestrator. After collecting inputs in Phase 1, it delegates artifact composition and the strict + gentle gate funnel to `hatch3r-creator` via the Task tool. Phase 3 runs `hatch3r validate` and surfaces results inline.
+
+# `/hatch3r-create` — Author a User-Tier Artifact
+
+Use this command when you need a project-specific agent, skill, rule, command, or hook that does not exist in the canonical hatch3r corpus. The command writes one new artifact under `.agents/user/{type}/` per invocation, runs the same frontmatter/security/structural gates the framework uses on canonical content (strict — block on failure), and runs style/lean checks as warnings (gentle — save proceeds, warnings reported).
+
+The 5 supported types: **agent** (sub-agent invokable from orchestrators), **skill** (workflow recipe), **rule** (always or glob-scoped guidance), **command** (slash command, inline or orchestrator), **hook** (event-triggered agent invocation).
+
+---
+
+## Workflow
+
+The command runs in three phases. Phase 1 collects every input upfront. Phase 2 delegates to `hatch3r-creator`. Phase 3 verifies and reports. No file is written until the user confirms the plan in Step 1.7.
+
+## Step 0: Triage
+
+Classify the artifact-authoring request before delegating:
+
+- **Tier 1 (trivial)**: small rule, snippet command, or single-event hook with clear scope; inline frontmatter assembly with minimal type-specific prompts.
+- **Tier 2 (standard)**: standard agent, skill, or orchestrator command with frontmatter and body skeleton; standard pipeline with `hatch3r-creator` delegation and full strict-gate funnel.
+- **Tier 3 (deep)**: artifact with cross-cutting tool allowlists, custom adapters, or pipeline integration; full pipeline with `hatch3r-creator` and confirm the plan with the user before writing.
+
+If Tier 1, run Phase 1 with reduced prompts (skip optional dimensions). If Tier 2, run the standard pipeline below. If Tier 3, expand Phase 1 dimension probing and confirm the plan summary explicitly with the user before delegating.
+
+**Parallel-dispatch directive:** When two or more steps below are independent (no shared files, no data dependency), issue all tool calls or sub-agent spawns in a single turn. Sequential dispatch of independent work is a finding under P7 (efficiency charter §P2).
+
+---
+
+### Phase 1 — Collect & Plan
+
+#### 1.1: Choose Artifact Type
+
+Present the 5 types with one-sentence descriptions and ask the user to select one.
+
+```
+Which type of artifact?
+  1) agent    — A sub-agent invoked by orchestrators via the Task tool
+  2) skill    — A reusable workflow recipe followed by an agent
+  3) rule     — Coding/process guidance applied always or by glob match
+  4) command  — A slash-command entry point (inline or orchestrator)
+  5) hook     — An event-triggered agent invocation (pre-commit, file-save, etc.)
+```
+
+**ASK:** "Select artifact type (1-5)."
+
+Cache the selection as `type`.
+
+#### 1.2: Choose Name
+
+**ASK:** "Provide a kebab-case name for the artifact (lowercase, hyphens only, no spaces). Example: `pr-summarizer`."
+
+Validate the name against the regex `^[a-z][a-z0-9-]*$`. Reject and re-ask if:
+
+- The name fails the regex (uppercase, underscores, leading digit, etc.).
+- The name starts with `hatch3r-` — this prefix is reserved for canonical framework content. Show: "Names starting with `hatch3r-` are reserved for canonical framework artifacts. Choose a different prefix or omit the prefix entirely. The framework will namespace the file path under `.agents/user/{type}/` automatically."
+
+Cache the validated name as `name`.
+
+#### 1.3: Description
+
+**ASK:** "Provide a one-paragraph description (minimum 60 characters). This appears in the AI tool's artifact picker — make it specific enough that the right artifact is selected when the user asks."
+
+Reject and re-ask if the description is shorter than 60 characters. Cache as `description`.
+
+#### 1.4: Tags
+
+Present the known tag set: `core, customization, planning, implementation, review, performance, a11y, security, board`.
+
+**ASK:** "Select one or more tags (comma-separated). You may add custom project tags after the known set, e.g., `implementation, my-team`."
+
+Cache as `tags` (array).
+
+#### 1.5: Adapter Scope (Optional)
+
+**ASK:** "Restrict this artifact to specific adapters? Press Enter to default to ALL enabled adapters (full parity), or list adapter names like `claude, cursor`."
+
+Cache as `adapters` (array, or `null` for full parity).
+
+#### 1.6: Type-Specific Prompts
+
+Branch on the cached `type`:
+
+- **agent:** Ask for `model` preference (default: `standard`; options: `fast | standard | reasoning`). Ask for an optional tool-allowlist hint (free-text). Cache as `model` and `toolHint`.
+- **skill:** Confirm the subdirectory layout. Show: "Skill files are stored as `.agents/user/skills/{name}/SKILL.md` (a new directory will be created). Continue?" — ASK Y/n.
+- **rule:** Ask for scope: `always` (loaded every session) or `conditional` (loaded by glob match). If `conditional`, ASK for a comma-separated glob list (e.g., `src/**/*.ts, src/**/*.tsx`). Then ASK for `precedence` (one of `critical | high | normal | low`, default `normal`). Cache as `ruleScope`, `ruleGlobs`, `rulePrecedence`.
+- **command:** ASK whether this is an orchestrator command. If yes, ASK for the agent pipeline as a comma-separated list of agent IDs (each ID must reference an existing agent — canonical or under `.agents/user/agents/`). Cache as `isOrchestrator` and `agentPipeline`.
+- **hook:** ASK for the hook event from the enum: `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`. Reject any value outside this enum and re-ask. Cache as `hookEvent`.
+
+#### 1.7: Plan Summary & Confirmation
+
+Render the proposed file path, full frontmatter block, and body-skeleton outline. For an agent plan, the summary lists `Path`, `Type`, `Name`, `Description` (first 80 chars), `Tags`, `Adapters` (or "all enabled"), `Model`; then the frontmatter block; then the body-skeleton outline (`<task>`, `<context>`, Implementation Protocol numbered steps, `<rules>`). For other types, swap the type-specific slots from Step 1.6.
+
+**ASK:** "Confirm to delegate authoring to `hatch3r-creator`, or specify changes (e.g., 'change model to fast', 'add tag: review')."
+
+Loop until the user confirms.
+
+---
+
+### Phase 2 — Delegate to `hatch3r-creator`
+
+Use the Task tool to invoke the `hatch3r-creator` sub-agent. If `hatch3r-creator` is not registered in the current session, fall back to `general-purpose` and pass the same input contract — the agent file is part of this release and lives at `agents/hatch3r-creator.md`.
+
+Pass the collected slots as a structured input:
+
+```
+{
+  type:          "{type}",
+  name:          "{name}",
+  description:   "{description}",
+  tags:          [{tags}],
+  adapters:      [{adapters}] | null,
+  model:         "{model}",        // agent only
+  toolHint:      "{toolHint}",     // agent only (optional)
+  ruleScope:     "{ruleScope}",    // rule only
+  ruleGlobs:     [{ruleGlobs}],    // rule only (when scope=conditional)
+  rulePrecedence:"{rulePrecedence}", // rule only
+  isOrchestrator: {bool},          // command only
+  agentPipeline: [{agentPipeline}],// command only (when isOrchestrator=true)
+  hookEvent:     "{hookEvent}"     // hook only
+}
+```
+
+The sub-agent composes frontmatter + body, calls `saveUserContent` from `src/content/userContent.ts` (the canonical strict + gentle gate funnel), and atomic-writes the file via `src/merge/safeWrite.ts`. For rule artifacts, `saveUserContent` also generates the paired `.mdc` companion using the `.md → .mdc` scope transform documented in `rules/hatch3r-content-authoring.md`. For skill artifacts, it creates the `{name}/` subdirectory and writes `SKILL.md` inside.
+
+Wait for the sub-agent's structured return:
+
+```
+{
+  status:       "WRITTEN" | "STRICT_GATE_FAILED" | "BLOCKED",
+  paths:        ["{absolute path}"],
+  strictErrors: [{message, gate, line?}],
+  gentleWarnings: [{message, gate, line?}]
+}
+```
+
+If `status: "STRICT_GATE_FAILED"`, surface every entry in `strictErrors` to the user verbatim and offer to retry Phase 1 with corrections. Do not proceed to Phase 3.
+
+If `status: "BLOCKED"`, surface the blocker (e.g., user file collision) and stop.
+
+---
+
+### Phase 3 — Post-Create Housekeeping
+
+Only run this phase when Phase 2 returns `status: "WRITTEN"`.
+
+#### 3.1: Validate
+
+Run `hatch3r validate --verbose` and capture stdout + exit code. Surface every error and warning related to the new artifact verbatim, plus a summary line: "Validate completed with N errors, M warnings (X relate to the new artifact)." If validate reports errors that block the artifact, instruct the user to edit the file directly at the printed absolute path or re-run `/hatch3r-create` after deleting the file.
+
+#### 3.2: Print Path & Sync Offer
+
+Print the absolute path(s) and the next-step pointer:
+
+```
+Created:
+  /abs/path/.agents/user/{type}/{name}.md
+  /abs/path/.agents/user/rules/{name}.mdc   (rule only — paired companion)
+
+Next step:
+  Run `hatch3r sync` to propagate this artifact to all enabled adapter outputs
+  (.cursor/, .claude/, .github/copilot-instructions.md, etc.).
+
+Edit your artifact directly anytime — `.agents/user/` is preserved across
+`hatch3r update` and `hatch3r clean`.
+```
+
+---
+
+## Constraints / Anti-Patterns
+
+- **Never overwrite an existing user file.** Collision with an existing path under `.agents/user/{type}/` is a strict-gate failure raised by `hatch3r-creator` (status `BLOCKED` with the conflicting path).
+- **Never write to canonical content directories.** All output goes under `.agents/user/`. Writes to `agents/`, `skills/`, `rules/`, `commands/`, or `hooks/` are rejected.
+- **Never bypass strict gates.** Strict failures (frontmatter, ID collision, deny patterns, paired-file parity, orchestrator contract, hook event enum, ≤10KB size) block the save.
+- **Pillar coverage required.** Every user artifact must declare at least one of P1–P6 in tags or body. Authors that do not select a pillar-aligned tag are warned by the gentle gate; the artifact still saves but the warning surfaces in Phase 3.
+- **One artifact per invocation.** Re-run `/hatch3r-create` for additional artifacts.
+
+---
+
+## Quality Charter
+
+This command and the `hatch3r-creator` sub-agent both inherit the standards in `agents/shared/quality-charter.md` — confidence levels, root-cause orientation, measurable acceptance criteria, and graceful failure with corrective messages.

package/commands/hatch3r-debug.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch
 description: Standalone debug-and-fix workflow — add strategic debug logging, collect runtime logs from the user, perform root cause analysis, implement the fix, and clean up all debug artifacts.
 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]
 ---
 # Debug — Instrument, Diagnose, and Fix from Runtime Evidence
 
@@ -83,6 +87,18 @@ If the user declines, skip all browser steps. Do not ask again during the sessio
 
 Execute these stages in order. **Do not skip any stage.** Ask the user at every checkpoint marked with ASK.
 
+## Triage
+
+Classify the debug request before delegating:
+
+- **Tier 1 (trivial)**: single-file bug with one obvious instrumentation point and known reproduction; reduced researcher depth (`quick`) and minimal logging.
+- **Tier 2 (standard)**: bug spanning 2–4 files with multiple instrumentation points; standard pipeline with researcher (`symptom-trace`) and implementer for logging and fix.
+- **Tier 3 (deep)**: cross-module or intermittent bug requiring deep root-cause analysis; full pipeline with `deep` researcher depth and confirm fix approach with the user before mutating files.
+
+If Tier 1, run the standard stages with reduced researcher depth. If Tier 2, run the full pipeline below. If Tier 3, expand researcher modes (add `regression` if relevant) and confirm the diagnosis with the user before Stage 5.
+
+---
+
 ### Stage 1: Gather Bug Context
 
 **Goal:** Understand the bug, its symptoms, affected area, and reproduction path before instrumenting anything.

package/commands/hatch3r-dep-audit.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Scan, assess, and upgrade npm dependencies. Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
 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-feature-plan.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Design a new capability -- draft user stories, acceptance criteria, data model, API surface, and sub-issue breakdown as an epic-shaped todo.md for greenfield features
 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 single feature idea and produce a complete feature specification (`docs/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 feature-planning request before delegating:
+
+- **Tier 1 (trivial)**: small feature scoped to one module with clear AC; reduced fanout (1–2 researchers), produce a single standalone todo entry instead of an epic.
+- **Tier 2 (standard)**: standard feature touching 2–5 modules with sub-tasks; standard pipeline with all 5 parallel researcher modes and ADR generation if architectural decisions arise.
+- **Tier 3 (deep)**: cross-cutting feature with new architecture, multiple integrations, or breaking changes; full pipeline with deep research and confirm spec 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 and confirm spec scope explicitly before writing files.
+
+---
+
 ### Step 1: Gather Feature Description
 
 1. **ASK:** "Tell me about the feature you want to plan. I need:

package/commands/hatch3r-healthcheck.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Open a QA and reliability epic surveying coverage gaps, flaky tests, and regression blind spots with one testing sub-issue per module plus cross-module wiring audit
 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-hooks.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Define and manage event-driven hooks that activate agents on project events
 tags: [core, devops]
 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-learn.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Capture learnings from development sessions into reusable knowledge files for future consultation.
 tags: [core, maintenance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline