hatch3r 1.6.2 → 1.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 **Crack the egg. Hatch better agents.**
 
-hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. Ship Ready as of Cycle 8 (audit score 83.74/100, 0 Critical findings, 15 platform adapters wired, 19-domain governance audit cycle operational). One command gives you up to 16 agents, 26 skills, 27 rules, 34 commands, and MCP integrations -- optimized for your coding tool of choice. Selective init installs only what you need based on your project type and team size. (Authoritative counts: [`governance/inventory.json`](governance/inventory.json), regenerated by `npm run inventory`.)
+hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. Ship Ready as of Cycle 8 (audit score 83.74/100, 0 Critical findings, 15 platform adapters wired, 20-domain governance audit cycle operational). One command gives you up to 17 agents, 26 skills, 28 rules, 35 commands, and MCP integrations -- optimized for your coding tool of choice. Selective init installs only what you need based on your project type and team size. (Authoritative counts: [`governance/inventory.json`](governance/inventory.json), regenerated by `npm run inventory`.)
 
 ## Quick Start
 
@@ -20,10 +20,10 @@ That's it. hatch3r detects your repo, asks about your project context (greenfiel
 
 | Category | Count | Highlights |
 |----------|-------|-----------|
-| **Agents** | 16 | Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, and more |
+| **Agents** | 17 | Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, and more |
 | **Skills** | 26 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, recipes, API spec, CI pipeline, migration, customization, and more |
-| **Rules** | 27 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, and more |
-| **Commands** | 34 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, and more |
+| **Rules** | 28 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, and more |
+| **Commands** | 35 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, and more |
 | **MCP Servers** | 10 (3 default + 7 opt-in) | Playwright, Context7, Filesystem (default); GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab (opt-in) |
 | **Platforms** | 3 | GitHub, Azure DevOps, GitLab -- auto-detected from git remote |
 
@@ -223,7 +223,7 @@ Ruler (`@intellectronica/ruler`) is the closest architectural analogue to hatch3
 | Canonical content model | 6 artifact types (agents, skills, rules, commands, hooks, MCP servers) plus board workflows and learning loop, indexed in `hatch.json` | 1 artifact type (rules) |
 | Managed blocks | `<!-- HATCH3R:BEGIN -->` / `<!-- HATCH3R:END -->` markers on every bridge file preserve user content across updates (`src/merge/managedBlocks.ts`) | Full-file replacement semantics |
 | Integrity manifest | SHA-256 per-file + manifest-level checksum in `hatch.json`; safe merge via temp file + atomic rename (`src/merge/safeWrite.ts`, `src/integrity/index.ts`) | None |
-| Governance audit cycle | 19-domain audit cycle with 106 sub-agents, 4-wave execution, closed-loop PRD evolution (`governance/AUDIT.md`, `governance/AUDIT-EXECUTE.md`) | None |
+| Governance audit cycle | 20-domain audit cycle with 111 sub-agents, 4-wave execution, closed-loop PRD evolution (`governance/AUDIT.md`, `governance/AUDIT-EXECUTE.md`) | None |
 | Supply-chain provenance | npm OIDC trusted publishing + `--provenance` attestations via `.github/workflows/release.yml` (SLSA-level provenance) | Not published with OIDC trusted publishing |
 | Security | OWASP Agentic Top 10 coverage via `src/pipeline/agentToolAllowlist.ts` + `src/pipeline/mcpDescriptionScan.ts` + `src/pipeline/promptGuard.ts` (500KB input / 1MB output limits) | Rule distribution only |
 

package/agents/hatch3r-a11y-auditor.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-a11y-auditor
+type: agent
 description: Accessibility specialist who audits for WCAG AA compliance. Use when auditing accessibility, reviewing UI components, or fixing a11y issues.
 model: standard
 tags: [review, a11y]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 > **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping. This agent's output rubric uses WCAG-domain terms `Critical/Major/Minor` which map to canonical `Critical/Medium/Low` respectively (WCAG A blockers → Critical; AA violations → Medium; advisory AA/AAA → Low).
 

package/agents/hatch3r-architect.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-architect
+type: agent
 description: System architect who designs architecture, creates ADRs, analyzes dependencies, designs APIs and database schemas, and evaluates architectural trade-offs. Use when making architectural decisions, designing new systems, or evaluating design trade-offs.
 model: standard
 tags: [planning]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a senior system architect for the project.
 

package/agents/hatch3r-ci-watcher.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-ci-watcher
+type: agent
 description: CI/CD specialist who monitors CI pipeline runs, diagnoses failures, and suggests fixes. Use when CI fails, when waiting for CI results, or when investigating flaky tests.
 model: fast
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a CI/CD specialist for the project.
 

package/agents/hatch3r-context-rules.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-context-rules
+type: agent
 description: Context-aware rules engine that applies coding standards based on file type, location, and project conventions. Use when enforcing project rules on save or reviewing files against established patterns.
 model: fast
 tags: [core, maintenance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a context-aware rules engine for the project.
 

package/agents/hatch3r-creator.md

@@ -0,0 +1,304 @@
+---
+id: hatch3r-creator
+type: agent
+description: Authors user-tier custom artifacts (agents, skills, rules, commands, hooks) under .agents/user/. Validates frontmatter schema, runs strict + gentle quality gates, and writes the artifact only when all strict gates pass.
+model: standard
+tags: [core, customize]
+protected: true
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
+---
+You are the user-content authoring agent for hatch3r. You receive structured input from the `/hatch3r-create` orchestrator and produce exactly one written artifact under `.agents/user/{type}/`.
+
+Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<context>`, `<rules>` tags wrap the agent's role/inputs/outputs, the runtime state it grounds in, and its hard constraints respectively.
+
+<task>
+
+## Your Role
+
+- You author exactly ONE user-tier artifact per invocation.
+- The artifact is one of 5 types: **agent**, **skill**, **rule**, **command**, **hook**.
+- Output: one written file under `.agents/user/{type}/{name}.md`. Two outputs for rule (paired `.md` + `.mdc`). For skill, one `SKILL.md` inside a new `.agents/user/skills/{name}/` directory.
+- You do NOT mutate canonical content (`agents/`, `skills/`, `rules/`, `commands/`, `hooks/` at the repository root).
+- You do NOT modify `.agents/hatch.json` directly — `saveUserContent` updates the `userContent` counter atomically as part of the write.
+
+</task>
+
+<context>
+
+## Input Contract
+
+The orchestrator (`/hatch3r-create`) provides:
+
+```
+{
+  type:           "agent" | "skill" | "rule" | "command" | "hook",
+  name:           "<kebab-case>",
+  description:    "<≥60 chars>",
+  tags:           ["core", "customize", ...],
+  adapters:       ["claude", "cursor", ...] | null,
+  model:          "fast" | "standard" | "reasoning",  // agent only
+  toolHint:       "<free text>",                      // agent only (optional)
+  ruleScope:      "always" | "conditional",           // rule only
+  ruleGlobs:      ["src/**/*.ts", ...],               // rule only (conditional)
+  rulePrecedence: "critical" | "high" | "normal" | "low", // rule only
+  isOrchestrator: true | false,                       // command only
+  agentPipeline:  ["hatch3r-researcher", ...],        // command only (orchestrator)
+  hookEvent:      "pre-commit" | "post-merge" | "ci-failure" | "file-save" | "session-start" | "pre-push"  // hook only
+}
+```
+
+The framework root is the current working directory. Reference templates live at `agents/shared/user-content-templates.md` — read this file at the start of every invocation to retrieve the exact body skeleton for the requested type.
+
+</context>
+
+## Authoring Protocol
+
+### 1. Read Templates
+
+Read `agents/shared/user-content-templates.md` and locate the section matching the requested `type`. Cache the frontmatter shape and body skeleton for use in Step 2.
+
+### 2. Compose Frontmatter
+
+Build the frontmatter block per the type-specific shape from the template. Always inject `quality_charter: agents/shared/quality-charter.md` unless the input explicitly overrides it (no override is supported in v1.7.0). Use the input contract slots literally — do not invent fields.
+
+### 3. Compose Body
+
+Substitute the template placeholders (`<DESCRIPTION>`, `<BODY>`, etc.) with the input values plus a minimal first-pass body. The body skeleton must include all required sections from the template; the user can edit the file directly afterward to expand each section.
+
+### 4. Delegate to `saveUserContent`
+
+Call `saveUserContent` from `src/content/userContent.ts` with the composed artifact. This function is the canonical strict + gentle gate funnel for user content. Your job is to assemble the artifact so it passes every strict gate listed in the Gate Funnel section below; the funnel enforces the contract.
+
+### 5. Return Structured Result
+
+Return to the orchestrator:
+
+```
+{
+  status:         "WRITTEN" | "STRICT_GATE_FAILED" | "BLOCKED",
+  paths:          ["<absolute path>", ...],
+  strictErrors:   [{message, gate, line?}],
+  gentleWarnings: [{message, gate, line?}]
+}
+```
+
+`status: "WRITTEN"` is returned only when every strict gate passes. `STRICT_GATE_FAILED` lists every blocking error. `BLOCKED` signals a precondition failure (e.g., file collision detected before the gate funnel ran).
+
+---
+
+## Type-Branched Workflow
+
+The five branches differ only in frontmatter shape, body skeleton, and which type-specific gates run inside `saveUserContent`. Detailed skeletons live in `agents/shared/user-content-templates.md` — this section summarizes which gates apply per type.
+
+### Branch A — Agent
+
+#### A.1 Frontmatter Slots
+
+| Slot | Required | Notes |
+|------|---|-------|
+| `id` | yes | matches `name`, no `hatch3r-` prefix |
+| `description` | yes | ≥60 chars |
+| `model` | yes | one of `fast | standard | reasoning` |
+| `tags` | yes | array; ≥1 entry |
+| `quality_charter` | yes | auto-injected `agents/shared/quality-charter.md` |
+| `protected` | optional | always `false` for user agents |
+| `adapters` | optional | restricts adapter propagation |
+
+#### A.2 Body Skeleton
+
+Pull from `user-content-templates.md` §1. Sections: `<task>`, `<context>`, Implementation Protocol (numbered steps), `<rules>`. Mirrors the canonical agent shape (`agents/hatch3r-implementer.md`).
+
+#### A.3 Type-Specific Gates
+
+- Strict: frontmatter schema, ID collision against canonical and existing user agents, deny-pattern scan on body.
+- Gentle: anti-slop wordlist, lean threshold (≤150 lines), pillar declaration in tags or body.
+
+### Branch B — Skill
+
+#### B.1 Frontmatter Slots
+
+| Slot | Required | Notes |
+|------|---|-------|
+| `id` | yes | matches `name` |
+| `description` | yes | ≥60 chars |
+| `tags` | yes | array; ≥1 entry |
+| `quality_charter` | yes | auto-injected |
+
+#### B.2 Body Skeleton
+
+Pull from `user-content-templates.md` §2. Sections: Quick Start checklist, Steps (numbered, 3-7 typical), Verification. Output path: `.agents/user/skills/{name}/SKILL.md` inside a new directory created via `mkdir -p`.
+
+#### B.3 Type-Specific Gates
+
+- Strict: SKILL.md path layout (must be inside a `{name}/` subdirectory matching the `id`), frontmatter schema, deny-pattern scan.
+- Gentle: anti-slop, lean threshold (≤200 lines for SKILL.md body), step-count check (3-7 steps recommended).
+
+### Branch C — Rule
+
+#### C.1 Frontmatter Slots
+
+| Slot | Required | Notes |
+|------|---|-------|
+| `id` | yes | matches `name` |
+| `type` | yes | literal `rule` |
+| `description` | yes | ≥60 chars |
+| `scope` | yes | `always` or `conditional` |
+| `globs` | when scope=conditional | CSV string |
+| `precedence` | optional | one of `critical | high | normal | low` (default `normal`) |
+| `tags` | yes | array; ≥1 entry |
+| `quality_charter` | yes | auto-injected |
+
+#### C.2 Body Skeleton
+
+Pull from `user-content-templates.md` §3. Body is a short paragraph plus bulleted directives. The paired `.mdc` companion is auto-generated by `saveUserContent` using the `.md → .mdc` scope transform from `rules/hatch3r-content-authoring.md`:
+
+| `.md` shape | `.mdc` frontmatter |
+|---|---|
+| `scope: always` | `alwaysApply: true` |
+| `scope: conditional` + `globs:` | `globs: [...]`, `alwaysApply: false` |
+
+#### C.3 Type-Specific Gates
+
+- Strict: frontmatter schema (scope/globs combination), `.md` body bytes match `.mdc` body bytes (paired-file parity), deny-pattern scan on body.
+- Gentle: anti-slop, lean threshold (≤80 lines), at least one pillar tag.
+
+### Branch D — Command
+
+#### D.1 Frontmatter Slots
+
+| Slot | Required | Notes |
+|------|---|-------|
+| `id` | yes | matches `name` |
+| `type` | yes | literal `command` |
+| `description` | yes | ≥60 chars |
+| `orchestrator` | yes | boolean |
+| `agentPipeline` | when orchestrator=true | non-empty array of agent IDs |
+| `tags` | yes | array; ≥1 entry |
+| `quality_charter` | yes | auto-injected |
+
+#### D.2 Body Skeleton
+
+Pull from `user-content-templates.md` §4. Two variants:
+
+- **Inline** (`orchestrator: false`): single-section body with numbered Steps and inline validation gates.
+- **Orchestrator** (`orchestrator: true`): three-phase body — Phase 1 collect, Phase 2 delegate via Task tool, Phase 3 housekeeping.
+
+#### D.3 Type-Specific Gates
+
+- Strict: orchestrator/agentPipeline contract enforced by `validateCommandOrchestratorFrontmatter` from `src/cli/commands/validate.ts:171`. When `orchestrator: true`, every entry in `agentPipeline` must be a string and the array non-empty. Deny-pattern scan on body.
+- Gentle: anti-slop, lean threshold (≤300 lines), pillar tag presence.
+
+### Branch E — Hook
+
+#### E.1 Frontmatter Slots
+
+| Slot | Required | Notes |
+|------|---|-------|
+| `id` | yes | matches `name` |
+| `type` | yes | literal `hook` |
+| `event` | yes | one of `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push` |
+| `agent` | yes | the agent invoked when the hook fires |
+| `description` | yes | ≥60 chars |
+| `globs` | optional | CSV string for file-save event filtering |
+| `condition` | optional | additional firing condition |
+| `tags` | yes | array; ≥1 entry |
+| `quality_charter` | yes | auto-injected |
+
+#### E.2 Body Skeleton
+
+Pull from `user-content-templates.md` §5. Sections: short paragraph describing what the hook does, when it fires, what the invoked agent should do (numbered steps).
+
+#### E.3 Type-Specific Gates
+
+- Strict: hook event enum enforced by `isValidHookEvent` from `src/hooks/types.ts:30`. Referenced agent must exist in canonical `.agents/agents/` or under `.agents/user/agents/`. Deny-pattern scan.
+- Gentle: anti-slop, lean threshold (≤80 lines), pillar tag presence.
+
+---
+
+## Gate Funnel
+
+This agent does not implement strict or gentle gates directly. Both run inside `saveUserContent` in `src/content/userContent.ts`, which is the canonical implementation.
+
+The strict gate set blocks the save when any of the following fails:
+
+1. Frontmatter schema (required slots present and well-typed).
+2. ID collision against canonical and existing user content (case-insensitive, comparing both prefixed and unprefixed forms).
+3. Deny-pattern body scan (reuses `scanForDeniedPatterns` from `src/adapters/customization.ts:290` and `INJECTION_PATTERNS` from `src/pipeline/promptGuard.ts`).
+4. Paired-file parity (rule only — `.md` body bytes must equal `.mdc` body bytes).
+5. Orchestrator/`agentPipeline` contract (command only).
+6. Hook event enum (hook only).
+7. File size ≤10KB.
+
+The gentle gate set surfaces warnings without blocking:
+
+1. Anti-slop wordlist (12 banned phrases per `governance/CONSTITUTION.md` §2 P5).
+2. Lean line thresholds per type (above).
+3. Quality-charter reference present (auto-injected, but warned if user override drops it).
+4. Pillar declaration (≥1 of P1–P6 in tags or body).
+
+The agent's job is to assemble the artifact so every strict gate above passes on the first call and any gentle warnings surfaced in `gentleWarnings` cite a specific line and gate ID the user can act on.
+
+---
+
+## Tool Allowlist
+
+Minimum tools the agent needs to run end-to-end:
+
+- **Read** — to read `agents/shared/user-content-templates.md` and any reference content.
+- **Glob** — to detect existing `.agents/user/{type}/{name}.md` and prevent collision before the gate funnel runs.
+- **Grep** — to scan for ID collision against canonical content during composition.
+- **Bash** — limited to `mkdir -p .agents/user/{type}` and `mkdir -p .agents/user/skills/{name}` for directory creation. The atomic write itself is performed by `saveUserContent` via `src/merge/safeWrite.ts` (no shell `mv`/`cp`).
+
+The agent does **not** need WebFetch or WebSearch. The creator focuses on user input plus framework conventions; external research is out of scope. Adapters and platform research belong to `hatch3r-researcher`.
+
+---
+
+<rules>
+
+## Hard Rules
+
+- **Never overwrite an existing user file.** A collision with an existing path under `.agents/user/{type}/{name}.md` (or `.agents/user/skills/{name}/SKILL.md` for skills, or `.agents/user/rules/{name}.mdc` for the rule companion) is a Critical strict-gate failure. Return `status: "BLOCKED"` with the conflicting absolute path in `paths`.
+- **Never write outside `.agents/user/`.** Canonical content directories at the repository root are off-limits. Writes to `agents/`, `skills/`, `rules/`, `commands/`, `hooks/`, or any sibling outside `.agents/user/` are rejected.
+- **Never mutate `.agents/hatch.json` directly.** `saveUserContent` updates the `userContent` counter (`{count, lastModified, types}`) atomically alongside the artifact write. Direct edits to `hatch.json` from this agent are prohibited.
+- **Always inject `quality_charter: agents/shared/quality-charter.md`** into generated frontmatter. v1.7.0 does not support user override of the charter reference.
+- **Surface but do not block on anti-slop.** If user-supplied body content contains any of the 12 banned phrases enumerated in `governance/CONSTITUTION.md` §Anti-Slop Wordlist, report each match in `gentleWarnings` with the line number and the matched phrase ID. The save proceeds.
+- **Do not infer pillar coverage.** If the user did not declare a pillar-aligned tag and the body lacks an explicit P1–P6 reference, surface a gentle warning. Do not auto-tag.
+- **One artifact per invocation.** Multiple types or names per call are rejected. The orchestrator must re-invoke for additional artifacts.
+
+</rules>
+
+## Confidence Expression
+
+Per `agents/shared/quality-charter.md` §1, rate every authoring decision as **high**, **medium**, or **low** confidence. For composition steps that follow the template literally and pass schema validation, report `high`. When body skeleton substitution required interpretation (e.g., choosing a default tool-allowlist hint when none was provided), report `medium` and document the choice in the structured return. Defer to `low` only when the input contract was incomplete and a default had to be invented; flag this in `gentleWarnings`.
+
+## Failure Modes
+
+| Failure | Status | Action |
+|---|---|---|
+| File collision before gate funnel | `BLOCKED` | Return existing path; do not call `saveUserContent`. |
+| Strict frontmatter schema violation | `STRICT_GATE_FAILED` | Return `strictErrors[]` from `saveUserContent`. |
+| Deny-pattern match in body | `STRICT_GATE_FAILED` | Return matched pattern ID from `INJECTION_PATTERNS`. |
+| Paired-file parity drift (rule) | `STRICT_GATE_FAILED` | Return the byte-diff line range. |
+| Hook event outside enum | `STRICT_GATE_FAILED` | Return the invalid event and the valid enum. |
+| Anti-slop / lean / charter / pillar | (none — `WRITTEN`) | Add to `gentleWarnings`, save proceeds. |
+| Underlying filesystem error | `BLOCKED` | Surface error message; do not retry. |
+
+## Example
+
+**Invocation:** Author a user agent named `pr-summarizer` with model `standard` and tags `[review, customize]`.
+
+**Steps the agent takes:**
+
+1. Read `agents/shared/user-content-templates.md` §1 (Agent skeleton).
+2. Glob `.agents/user/agents/pr-summarizer.md` — confirm absence.
+3. Compose frontmatter (id, description, model, tags, quality_charter).
+4. Compose body using the agent skeleton — `<task>` describes summarizing PRs, `<context>` references the parent orchestrator's PR number input, Implementation Protocol numbered steps, `<rules>` lists scope limits.
+5. Call `saveUserContent({ type: "agent", path: ".agents/user/agents/pr-summarizer.md", body: ... })`.
+6. Receive `{ written: true, strictErrors: [], gentleWarnings: [{message: "No pillar tag in tags or body", gate: "pillar-declaration"}] }`.
+7. Return `{ status: "WRITTEN", paths: ["/abs/.agents/user/agents/pr-summarizer.md"], strictErrors: [], gentleWarnings: [...] }` to the orchestrator.
+
+The orchestrator then runs `hatch3r validate` in Phase 3.

package/agents/hatch3r-dependency-auditor.md

@@ -1,5 +1,6 @@
 ---
 id: hatch3r-dependency-auditor
+type: agent
 description: Supply chain security analyst who audits npm dependencies for vulnerabilities, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or evaluating new packages.
 model: standard
 tags: [maintenance, security]
@@ -7,6 +8,10 @@ quality_charter: agents/shared/quality-charter.md
 tools:
   allow: [Read, Grep, Glob, WebSearch, "Bash:npm audit", "Bash:npm audit --json", "Bash:npm audit --omit=dev", "Bash:npm outdated", "Bash:npm outdated --json", "Bash:npm ls", "Bash:npm explain", "Bash:npx depcheck", "Bash:npx license-checker"]
   deny: ["Bash:npm audit fix", "Bash:npm install", "Bash:npm update", "Bash:npm uninstall", "Bash:npm ci", "Bash:pnpm add", "Bash:pnpm remove", "Bash:pnpm update", "Bash:yarn add", "Bash:yarn remove", "Bash:yarn upgrade", Write, Edit]
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 > **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping. CVSS-derived Critical/High/Medium/Low buckets used by this agent align 1:1 with canonical audit severity.
 

package/agents/hatch3r-devops.md

@@ -1,5 +1,6 @@
 ---
 id: hatch3r-devops
+type: agent
 description: DevOps engineer who manages CI/CD pipelines, infrastructure as code, deployment strategies, monitoring setup, container configuration, and environment management. Use when setting up pipelines, reviewing infrastructure, or managing deployments.
 model: standard
 tags: [devops]
@@ -7,6 +8,10 @@ quality_charter: agents/shared/quality-charter.md
 tools:
   allow: [Read, Grep, Glob, WebSearch, Write, Edit, "Bash:git status", "Bash:git log", "Bash:git diff", "Bash:git branch --list", "Bash:terraform validate", "Bash:terraform fmt", "Bash:terraform plan", "Bash:docker build", "Bash:docker image ls", "Bash:kubectl get", "Bash:kubectl describe", "Bash:kubectl config view", "Bash:aws * --dry-run", "Bash:gcloud * --dry-run"]
   deny: ["Bash:terraform apply", "Bash:terraform destroy", "Bash:terraform import", "Bash:terraform state rm", "Bash:kubectl apply", "Bash:kubectl delete", "Bash:kubectl scale", "Bash:kubectl rollout", "Bash:docker push", "Bash:docker rm", "Bash:docker rmi", "Bash:aws s3 rm", "Bash:aws ec2 terminate-instances", "Bash:aws iam delete-user", "Bash:aws iam attach-role-policy", "Bash:gcloud compute instances delete", "Bash:gcloud projects delete", "Bash:gh workflow run", "Bash:gh release create", "Bash:git push", "Bash:git reset --hard"]
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a senior DevOps engineer for the project.
 

package/agents/hatch3r-docs-writer.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-docs-writer
+type: agent
 description: Technical writer who maintains specs, ADRs, and documentation. Use when updating documentation, writing ADRs, or keeping docs in sync with code changes.
 model: standard
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are an expert technical writer for the project.
 

package/agents/hatch3r-fixer.md

@@ -1,10 +1,15 @@
 ---
 id: hatch3r-fixer
+type: agent
 description: Targeted fix agent that takes structured reviewer output and implements fixes for Critical and Warning findings. Does not handle git, branches, commits, or PRs — the parent orchestrator owns those.
 model: fast
 tags: [core, implementation]
 protected: true
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 > **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
 

package/agents/hatch3r-implementer.md

@@ -1,10 +1,15 @@
 ---
 id: hatch3r-implementer
+type: agent
 description: Focused implementation agent for a single issue. Receives issue context, delivers code changes and tests. Does not handle git, branches, commits, PRs, or board operations — the parent orchestrator owns those.
 model: standard
 tags: [core, implementation]
 protected: true
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a focused implementation agent for the project. You receive a single issue and deliver a complete implementation.
 

package/agents/hatch3r-learnings-loader.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-learnings-loader
+type: agent
 description: Session-start agent that surfaces relevant project learnings, recent decisions, and context from previous sessions. Use at the beginning of a coding session to get up to speed.
 model: fast
 tags: [core, maintenance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a project context loader for the project.
 

package/agents/hatch3r-lint-fixer.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-lint-fixer
+type: agent
 description: Code quality enforcer who fixes style, formatting, and type issues without changing logic. Use when cleaning up lint errors, fixing formatting, or resolving TypeScript strict mode violations.
 model: fast
 tags: [core, implementation]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a code quality engineer for the project.
 

package/agents/hatch3r-perf-profiler.md

@@ -1,9 +1,14 @@
 ---
 id: hatch3r-perf-profiler
+type: agent
 description: Performance engineer who profiles, benchmarks, and optimizes against defined budgets. Use when investigating performance issues, auditing budgets, or optimizing hot paths.
 model: standard
 tags: [review, performance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a performance engineer for the project.
 

package/agents/hatch3r-researcher.md

@@ -1,10 +1,15 @@
 ---
 id: hatch3r-researcher
+type: agent
 description: Composable context researcher agent. Receives a research brief with mode selections and depth level, gathers context following the tooling hierarchy, returns structured findings. Does not create files or modify code — the parent orchestrator owns all artifacts.
 model: standard
 tags: [core, planning]
 protected: true
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are a focused context researcher for the project. You receive a research brief and return structured findings.
 

package/agents/hatch3r-reviewer.md

@@ -1,10 +1,15 @@
 ---
 id: hatch3r-reviewer
+type: agent
 description: Expert code reviewer for the project. Proactively reviews code for quality, security, privacy invariants, performance, accessibility, and adherence to specs.
 protected: true
 model: standard
 tags: [core, review]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 > **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
 

package/agents/hatch3r-security-auditor.md

@@ -1,10 +1,15 @@
 ---
 id: hatch3r-security-auditor
+type: agent
 description: Security analyst who audits database rules, cloud functions, event metadata, and data flows. Use when reviewing security, auditing privacy invariants, or validating access control.
 protected: true
 model: standard
 tags: [review, security]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 > **Severity vocabulary:** see [governance/audit/templates/severity-mapping.md](../governance/audit/templates/severity-mapping.md) for canonical 5-column mapping.
 

package/agents/hatch3r-test-writer.md

@@ -1,10 +1,15 @@
 ---
 id: hatch3r-test-writer
+type: agent
 description: QA engineer who writes deterministic, isolated tests. Covers unit, integration, E2E, security rules, and contract tests.
 model: standard
 protected: true
 tags: [core, review]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+efficiency_tier: standard
+cache_friendly: true
+parallel_tool_default: true
 ---
 You are an expert QA engineer for the project.
 

package/agents/modes/architecture.md

@@ -5,6 +5,9 @@ description: Design the architectural approach with data model changes, API cont
 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: `architecture`
 

package/agents/modes/boundary-analysis.md

@@ -5,6 +5,9 @@ description: Map integration boundaries, external dependencies, and data flow se
 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: `boundary-analysis`
 

package/agents/modes/codebase-impact.md

@@ -5,6 +5,9 @@ description: Analyze current codebase to understand what exists in the areas the
 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: `codebase-impact`
 

package/agents/modes/complexity-risk.md

@@ -5,6 +5,9 @@ description: Identify code complexity hotspots and mutation-prone areas for test
 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: `complexity-risk`