hatch3r 1.8.0 → 1.9.0

package/{agents → dist/content/agents}/shared/quality-charter.md

@@ -6,6 +6,8 @@ efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 ---
 
+> Last updated: 2026-05-26
+
 ## Agent Quality Charter
 
 All agents operating under hatch3r should embody these behavioral standards. This charter is the single source of truth for agent conduct — referenced by content artifacts and verified by the weekly audit cycle.
@@ -60,6 +62,8 @@ Every recommendation should account for its impact on:
 
 When stakeholder interests conflict, note the tradeoff explicitly and recommend based on the project's stated priorities.
 
+Apply the subset of stakeholders relevant to the project's declared maturity tier (solo / team / scaleup / enterprise per `hatch3r config maturity`). **Solo:** end user + maintaining developer (you). **Team:** + team lead. **Scaleup:** + ops team. **Enterprise:** + compliance + security review. When the tier is unknown, default to solo and ask via `agents/shared/user-question-protocol.md`.
+
 ### 6. Fail Gracefully
 
 When prerequisites are missing, inputs are invalid, or unexpected conditions arise:
@@ -98,7 +102,11 @@ When modifying code that is consumed by other modules, agents, or external syste
 - 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
+### 10. Consult Prior Learnings
+
+Before answering project-specific questions about prior work, decisions, or resolved issues, read `.hatch3r/learnings/INDEX.md` (when present) and any topic-applies index entries matched against the current task. Cite the consulted entry IDs in the structured output. Implementer + Reviewer + Researcher agents are bound; other roles consult when context applies.
+
+### 11. Standardized Iteration Summary
 
 Every user-facing iteration ends with the canonical Iteration Summary block defined in `rules/hatch3r-iteration-summary.md`.
 
@@ -106,6 +114,26 @@ Required fields: Status (closed enum: SUCCESS | PARTIAL | FAILED | BLOCKED), Out
 
 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.
 
+### 12. Anti-Duplication Procedure
+
+Before writing implementation code: run a codebase pattern search (grep for similar function names, similar type shapes, similar comment headers); report findings in the structured output. After writing: run a duplication scan (jscpd or equivalent) against the affected directories; flag any block matching ≥30 lines or ≥80% similarity with existing code. Refactor or justify before merge; silent duplication is a P4 violation.
+
+### 13. Adversarial Thinking
+
+For any non-trivial design choice, hold an internal adversarial review: what is the strongest case AGAINST this approach? What edge case breaks it? What stakeholder loses under this choice? Surface the counter-argument in the structured output alongside the chosen approach.
+
+### 14. Severity Discipline
+
+When classifying issues (bugs, code smells, design concerns), apply the severity taxonomy from `governance/AUDIT.md` §Severity Taxonomy (Critical / High / Medium / Low / Info). Calibrate against blast radius + reversibility + user impact. Critical reserved for production-blocking; Low/Info for cosmetic-only.
+
+### 15. Currency Verification
+
+Every external claim (library version, API behavior, platform feature) is verified against current official documentation (≤180 days). When sources conflict, prefer the publication with the most recent access date. CLI tools (`gh`, `curl`, `jq`) preferred over training-data recall.
+
+### 16. Senior-Engineer Outside-In Posture
+
+Approach every task from the perspective of a senior engineer with an outside-in user-facing perspective: the user judges by user-visible quality (UI/UX, performance, error recovery), not internal cleverness. Solve for user-visible quality first; refactor for maintainability second. When trade-offs surface between internal elegance and user-facing correctness, choose user-facing correctness.
+
 ### UI/UX quality (for agent-produced output in end-user projects)
 
 When an agent produces UI for an end-user project, the charter binds it to these criteria. Each is measurable; each is a regression if missed.
@@ -123,8 +151,8 @@ Cross-reference: this section is audited under D10 SA10.9 (`governance/audit/dom
 
 When an agent produces a service that handles a request, the charter binds it to these criteria. Each is measurable.
 
-- **OpenTelemetry spans on request path:** every inbound request and every outbound call (DB, HTTP, queue, RPC) emits an OTel span with `trace_id` and `span_id` propagated end-to-end; instrumented-route ratio = 100% (no silent paths). Reference `rules/hatch3r-observability.md`.
-- **Structured logs with trace correlation:** every log line is JSON, carries `trace_id`, includes service name + version + environment, and uses log levels mapped to severity. Stack traces emitted on `error`. Reference `rules/hatch3r-observability.md`.
+- **OpenTelemetry spans on request path:** every inbound request and every outbound call (DB, HTTP, queue, RPC) emits an OTel span with `trace_id` and `span_id` propagated end-to-end; instrumented-route ratio = 100% (no silent paths). Reference `rules/hatch3r-observability-tracing.md` and `rules/hatch3r-observability-logging.md`.
+- **Structured logs with trace correlation:** every log line is JSON, carries `trace_id`, includes service name + version + environment, and uses log levels mapped to severity. Stack traces emitted on `error`. Reference `rules/hatch3r-observability-tracing.md` and `rules/hatch3r-observability-logging.md`.
 - **RED + USE metrics on user-facing services:** Rate, Errors, Duration per route plus Utilization, Saturation, Errors per resource. Histograms over averages on latency.
 - **SLO with multi-window multi-burn-rate alerts:** every user-facing service declares an availability + latency SLO; alerts use the 2%/5%/10% multi-window multi-burn-rate pattern (Google SRE workbook), not raw threshold alerts.
 - **Error tracker with PII scrubbing:** Sentry-class tooling with source-map upload, release tag, environment tag, and an allowlist scrubber for known PII fields before egress.

package/{agents → dist/content/agents}/shared/user-content-templates.md

@@ -12,7 +12,7 @@ Canonical reference for the body and frontmatter shapes `hatch3r-creator` produc
 
 ### 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).
+**Path:** `.hatch3r/overrides/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
 ---
@@ -84,7 +84,7 @@ The three sections above (Confidence Expression, Failure Modes, Quality Charter)
 
 ### 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).
+**Path:** `.hatch3r/overrides/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
 ---
@@ -125,7 +125,7 @@ Recommended step count: 3-7. Skills with more than 7 steps trigger a gentle warn
 
 ### 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).
+**Path:** `.hatch3r/overrides/rules/<NAME>.md` plus the auto-generated companion `.hatch3r/overrides/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):
 
@@ -168,10 +168,10 @@ The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a s
 
 ### 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.
+**Path:** `.hatch3r/overrides/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.
+# 4a. Inline command — orchestrator: false. Modeled after commands/hatch3r-debug.md.
 ---
 id: <NAME>
 type: command
@@ -183,7 +183,7 @@ quality_charter: agents/shared/quality-charter.md
 ```
 
 ```yaml
-# 4b. Orchestrator command — orchestrator: true. Modeled after commands/hatch3r-board-init.md.
+# 4b. Orchestrator command — orchestrator: true. Modeled after commands/hatch3r-board-fill.md.
 ---
 id: <NAME>
 type: command
@@ -245,7 +245,7 @@ The strict gate `validateCommandOrchestratorFrontmatter` (`src/cli/commands/vali
 
 ### 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`).
+**Path:** `.hatch3r/overrides/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
 ---
@@ -274,14 +274,14 @@ When this hook fires, the assigned agent should:
 <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.
+The `agent` field must reference an existing agent — canonical (e.g., `lint-fixer` resolves to `agents/hatch3r-lint-fixer.md`) or under `.hatch3r/overrides/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}/`:
+For each user type, mirror the canonical shape below — minus the `hatch3r-` filename prefix; the user-tier path is always under `.hatch3r/overrides/{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).
+- **Command:** `commands/hatch3r-debug.md` (inline) or `commands/hatch3r-board-fill.md` (orchestrator).
 - **Hook:** `hooks/hatch3r-pre-commit.md` (with globs) or `hooks/hatch3r-session-start.md` (always-fire).

package/{agents → dist/content/agents}/shared/user-question-protocol.md

@@ -6,6 +6,8 @@ tags: [shared, ux, p1, p4]
 cache_friendly: true
 ---
 
+> Last updated: 2026-05-26
+
 ## Purpose
 
 This protocol defines how hatch3r agents and commands surface clarifying or triage questions to the user across the 15 supported AI coding platforms. It is the single source of truth for the *how* of asking; the *whether* is governed by [quality-charter §3 "Question Unclear Requirements"](./quality-charter.md) and §8 "Escalate Ambiguity Early". Files that reference this protocol: the requirements-elicitation mode (`agents/modes/requirements-elicitation.md`), the five ASK-checkpoint commands, and the four ask-prone agents — researcher, fixer, architect, implementer.

package/{commands → dist/content/commands}/board/pickup-azure-devops.md

@@ -56,7 +56,7 @@ Follow the **Azure Boards Work Item State Sync** from `commands/board/shared-azu
 **Create PR:**
 `az repos pr create --org https://dev.azure.com/{namespace} --project {project} --source-branch {branch} --target-branch {base} --title "..." --description "..."` (fall back to `create_pull_request` MCP).
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link PR to epic:**
 `az boards work-item relation add --id {epic_id} --relation-type "ArtifactLink" --target-id {pr_id}` or link via PR description.

package/{commands → dist/content/commands}/board/pickup-delegation-multi.md

@@ -78,8 +78,8 @@ For each dependency level, starting at Level 1:
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
    - Documentation references relevant to this sub-issue.
    - Instruction to follow the hatch3r-implementer agent protocol.
-   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
    - Instruction to use GitHub MCP for issue reads, and follow the project's tooling hierarchy for external knowledge augmentation.
    - Explicit instruction: do NOT create branches, commits, or PRs.
    - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
@@ -147,8 +147,8 @@ For each dependency level, starting at Level 1:
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3).
    - Documentation references relevant to this issue.
    - Instruction to follow the **hatch3r-implementer agent protocol**.
-   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
    - Explicit instruction: do NOT create branches, commits, or PRs.
    - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 

package/{commands → dist/content/commands}/board/pickup-delegation.md

@@ -57,8 +57,8 @@ The implementer sub-agent prompt MUST include:
 - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
 - Documentation references relevant to this issue.
 - Instruction to follow the **hatch3r-implementer agent protocol**.
-- All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-- Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+- All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+- Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
 - Explicit instruction: do NOT create branches, commits, or PRs.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
@@ -97,7 +97,7 @@ Launch as many independent sub-agents in parallel as the platform supports.
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow (e.g., "Follow the hatch3r-reviewer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` (subagents do not inherit rules automatically).
+- All `scope: always` rule directives from `rules/` (subagents do not inherit rules automatically).
 - The diff or file changes to review.
 - The issue's acceptance criteria.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.

package/{commands → dist/content/commands}/board/pickup-github.md

@@ -56,7 +56,7 @@ Follow the **GitHub Projects V2 Sync** from `commands/board/shared-github.md` fo
 **Create PR:**
 `gh pr create -R {owner}/{repo} --head {branch} --base {base} --title "..." --body "..."` (fall back to `create_pull_request` MCP).
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link PR to epic:**
 `gh issue comment {epic} -R {owner}/{repo} --body "PR: #{pr_number}"` (fall back to `add_issue_comment` MCP).

package/{commands → dist/content/commands}/board/pickup-gitlab.md

@@ -56,7 +56,7 @@ Follow the **GitLab Board Label-Based Sync** from `commands/board/shared-gitlab.
 **Create MR:**
 `glab mr create -R {namespace}/{project} --source-branch {branch} --target-branch {base} --title "..." --description "..."`. Use `Closes #N` syntax in the description for auto-close on merge.
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link MR to epic:**
 Reference the epic issue number in the MR description. GitLab auto-links MRs to issues mentioned with `Closes #N`.

package/{commands → dist/content/commands}/board/pickup-post-impl.md

@@ -118,7 +118,7 @@ After the PR merges and `Closes #N` auto-closes the referenced issue(s), confirm
    ```
    Record the mutation in the run cache under `updated_issues`.
 
-2. **Board state check.** Read `board.workflows.itemClosedEnabled` from `.agents/hatch.json`:
+2. **Board state check.** Read `board.workflows.itemClosedEnabled` from `.hatch3r/hatch.json`:
    - **If true:** The V2 built-in "Item closed" workflow has already set the board status to Done. Skip to step 3.
    - **If false or absent:** The workflow is not enabled (board-init should have halted, but this is a defensive fallback). Apply the full **Board Sync Procedure** from `hatch3r-board-shared` for each issue, target status = Done.
 
@@ -142,7 +142,7 @@ After PR creation, capture learnings from this development session.
    - Were any pitfalls discovered that should be avoided next time?
 
 2. If learnings are identified:
-   - Create learning files in `.agents/learnings/` following the learning file format (see `hatch3r-learn` command).
+   - Create learning files in `.hatch3r/learnings/` following the learning file format (see `hatch3r-learn` command).
    - Include the issue number as `source-issue`.
    - Tag with relevant area labels from the issue.
    - **ASK:** "Learnings captured: {list}. Anything else to note? (add more / done)"

package/{commands → dist/content/commands}/board/shared-azure-devops.md

@@ -56,7 +56,7 @@ Use `az devops` / `az boards` / `az repos` CLI. Issues = Work Items. PRs = Pull
 
 ## Azure DevOps Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Organization:** top-level `owner` (maps to Azure DevOps organization name)
 - **Project:** top-level `repo` (maps to Azure DevOps project name)

package/{commands → dist/content/commands}/board/shared-github.md

@@ -56,7 +56,7 @@ Use `gh` CLI and GitHub MCP tools. Issues = GitHub Issues. PRs = Pull Requests.
 
 ## GitHub Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Owner:** top-level `owner` (fallback: `board.owner`)
 - **Repository:** top-level `repo` (fallback: `board.repo`)
@@ -89,7 +89,7 @@ If `board.projectNumber` is not null, verify via `gh project view {board.project
 
 **Status label → Projects v2 option mapping:**
 
-Read the mapping from `board.statusOptions` in `.agents/hatch.json`:
+Read the mapping from `board.statusOptions` in `.hatch3r/hatch.json`:
 
 | Label                | Option ID from hatch.json          |
 | -------------------- | ---------------------------------- |

package/{commands → dist/content/commands}/board/shared-gitlab.md

@@ -49,7 +49,7 @@ GitLab MCP tools are not currently available. All operations use the `glab` CLI.
 
 ## GitLab Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Namespace:** top-level `owner` (GitLab group or user namespace)
 - **Project:** top-level `repo` (GitLab project name)

package/{commands → dist/content/commands}/hatch3r-api-spec.md

@@ -36,7 +36,7 @@ Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 sp
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
 
 **Read the `hatch3r-api-design` rule** if it exists. This rule contains the project's API design conventions (naming, versioning, error shapes, pagination patterns) that the generated spec must conform to.
 

package/{commands → dist/content/commands}/hatch3r-benchmark.md

@@ -36,7 +36,7 @@ Run performance benchmarks against a target (file, function, endpoint, or full s
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that may be useful for regression issue creation. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that may be useful for regression issue creation. Cache any values found.
 
 ## Token-Saving Directives
 

package/{commands → dist/content/commands}/hatch3r-board-fill.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 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]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -31,7 +31,7 @@ All issue operations MUST follow the Board Sync Enforcement rules defined in `ha
 
 # Board Fill -- Create Epics & Issues from todo.md + Board Reorganization
 
-Create epics (with sub-issues) or standalone issues/work items from items in `todo.md`, using the platform's CLI and MCP tools against **{owner}/{repo}** (read from `.agents/hatch.json` board config). The `platform` field determines whether to use GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Before creating anything, board-fill **triages each item through interactive questioning** to extract scope, intent, unknowns, and acceptance criteria from the user -- ensuring issues are genuinely ready for implementation, not just structurally complete. On every run, board-fill also performs a **full board reorganization**: grouping standalone issues into epics, decomposing oversized items, analyzing dependencies, setting implementation order, identifying parallel work, and marking issues as `status:ready` when all readiness criteria (structural + substantive) are met. AI proposes groupings, dependencies, and ordering; user confirms before anything is created or updated. Duplicate topics are detected and skipped.
+Create epics (with sub-issues) or standalone issues/work items from items in `todo.md`, using the platform's CLI and MCP tools against **{owner}/{repo}** (read from `.hatch3r/hatch.json` board config). The `platform` field determines whether to use GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Before creating anything, board-fill **triages each item through interactive questioning** to extract scope, intent, unknowns, and acceptance criteria from the user -- ensuring issues are genuinely ready for implementation, not just structurally complete. On every run, board-fill also performs a **full board reorganization**: grouping standalone issues into epics, decomposing oversized items, analyzing dependencies, setting implementation order, identifying parallel work, and marking issues as `status:ready` when all readiness criteria (structural + substantive) are met. AI proposes groupings, dependencies, and ordering; user confirms before anything is created or updated. Duplicate topics are detected and skipped.
 
 ---
 
@@ -52,7 +52,7 @@ GitHub Agentic Workflows and hatch3r are complementary: use agentic workflows fo
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 
@@ -86,7 +86,7 @@ If Tier 1, run only Steps 1–3, 5–6, and 7 (skip the heavy production-readine
 
 #### 1a. Product Vision Input (Optional)
 
-1. Check if a product vision document exists at `.agents/product-vision.md`.
+1. Check if a product vision document exists at `.hatch3r/product-vision.md`.
 2. If found, read and cache the vision document for use in Steps 2.5 and 4.
 3. If not found, check whether the user provided a vision statement inline with the board-fill invocation (e.g., as a quoted string or file path argument).
 4. If a vision is available from either source, note: "Product vision loaded — will use for triage context and issue scoping."
@@ -276,7 +276,7 @@ If the user flagged unresolved unknowns or research needs in triage, consider wh
 
 **Priority:** `priority:p0` (critical/security) / `priority:p1` (broken, no workaround) / `priority:p2` (degraded, default) / `priority:p3` (cosmetic, nice-to-have). Use the user's stated urgency and impact from triage (Value/Why answers) to override keyword defaults. Default `p2` only when both the todo text AND triage answers are ambiguous; security defaults to `p1`+.
 
-**Area:** Read area labels from `board.areas` in `.agents/hatch.json`. If the list is empty, infer areas from the repository's directory structure. Assign all relevant area labels.
+**Area:** Read area labels from `board.areas` in `.hatch3r/hatch.json`. If the list is empty, infer areas from the repository's directory structure. Assign all relevant area labels.
 
 **Risk:** `risk:low` (isolated, easy rollback) / `risk:med` (shared modules, moderate scope) / `risk:high` (architectural, security-critical). Incorporate triage context: if the user surfaced unknowns, external dependencies, or broad blast radius, escalate risk accordingly. Items with unresolved spikes default to `risk:med`+.
 
@@ -300,7 +300,7 @@ Use explore subagents or direct file reads to understand the current state of so
 
 #### 4b.5. Consult Project Learnings
 
-1. If `.agents/learnings/` exists, scan for learnings relevant to the areas touched by the todo items.
+1. If `.hatch3r/learnings/` exists, scan for learnings relevant to the areas touched by the todo items.
 2. Match by `area` and `tags` in learning frontmatter against the area labels assigned in Step 3.
 3. Surface relevant learnings in the Context Summary output:
    - **Pitfalls** for areas being touched (highest priority -- include specific warnings)
@@ -785,7 +785,7 @@ If yes, edit `todo.md` to remove lines for created issues. Preserve skipped/excl
 
 - **Never create issues for topics already covered** without explicit user approval.
 - **Never skip ASK checkpoints.**
-- **Use correct labels** from the label taxonomy defined in `.agents/hatch.json` (type, priority, area, risk, executor, status, has-dependencies, meta labels).
+- **Use correct labels** from the label taxonomy defined in `.hatch3r/hatch.json` (type, priority, area, risk, executor, status, has-dependencies, meta labels).
 - **Keep issue bodies concise.** Acceptance criteria must be grounded in user-stated requirements from triage, not fabricated from the todo text alone.
 - **No dependency cycles.** Flag and resolve before proceeding.
 - **Never downgrade issue status.** Only upgrade `status:triage` → `status:ready`.

package/{commands → dist/content/commands}/hatch3r-board-pickup.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-lint-fixer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
 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]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -21,7 +21,7 @@ Before any action, scan the user's request and provided context for unresolved q
 
 # Board Pickup -- Develop Issues from the Project Board
 
-Pick up an epic (with all sub-issues), a single sub-issue, a standalone issue, or **a batch of independent issues** from **{owner}/{repo}** (read from `.agents/hatch.json` board config) for development. The `platform` field determines whether to interact with GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Supports single-issue and multi-issue batch modes. When no specific issue is referenced, auto-picks the next best candidate(s). Respects dependency order and readiness status. Performs collision detection, creates a branch, then delegates implementation via one sub-agent per issue running in parallel.
+Pick up an epic (with all sub-issues), a single sub-issue, a standalone issue, or **a batch of independent issues** from **{owner}/{repo}** (read from `.hatch3r/hatch.json` board config) for development. The `platform` field determines whether to interact with GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Supports single-issue and multi-issue batch modes. When no specific issue is referenced, auto-picks the next best candidate(s). Respects dependency order and readiness status. Performs collision detection, creates a branch, then delegates implementation via one sub-agent per issue running in parallel.
 
 ---
 
@@ -57,7 +57,7 @@ hatch3r board commands orchestrate the **implementation delivery pipeline** (ini
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
 
 All issue operations in this command MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared`. Every status change, issue creation, and update must be synced to the board immediately.
 
@@ -267,7 +267,7 @@ Follow the **Board Sync Procedure** from `hatch3r-board-shared` for each issue m
 
 **If branch exists:** **ASK** reuse / delete+recreate / rename with `-v2`.
 
-**Normal path:** Use `{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+**Normal path:** Use `{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 ```bash
 git checkout {base} && git pull origin {base} && git checkout -b {branch-name}
@@ -293,7 +293,7 @@ Use the issue type to select the appropriate hatch3r skill: `type:bug` → the h
 
 #### 6.pre: Consult Learnings
 
-Before delegating: scan `.agents/learnings/` for matching `area`/`tags`, include relevant learnings (especially `pitfall` category) in sub-agent context. Skip silently if no learnings directory exists.
+Before delegating: scan `.hatch3r/learnings/` for matching `area`/`tags`, include relevant learnings (especially `pitfall` category) in sub-agent context. Skip silently if no learnings directory exists.
 
 > **Audit epics:** Audit epics produce findings (issues) rather than code changes — adjust delegation and skip Steps 7-8a if no code changes.
 
@@ -318,7 +318,7 @@ Execute Steps 7-10 in order after all implementation completes:
 - **Step 8:** Create PR/MR with proper `Closes #N` references. See platform sub-files for CLI commands.
 - **Step 8a:** Transition labels to `status:in-review` and sync board. See platform sub-files.
 - **Step 9:** Post-PR housekeeping: epic link verification, board dashboard refresh (9a, mandatory), end-of-run reconciliation (9b, mandatory).
-- **Step 10:** Capture learnings in `.agents/learnings/` if any were identified.
+- **Step 10:** Capture learnings in `.hatch3r/learnings/` if any were identified.
 
 ---
 

package/{commands → dist/content/commands}/hatch3r-bug-plan.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 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]
+tags: [planning, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -40,7 +40,7 @@ Take a complex or ambiguous bug report and produce a structured investigation re
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -102,10 +102,10 @@ Bug Brief:
    - `docs/adr/` — architectural decision records (scan for decisions relevant to the affected area)
    - `docs/investigations/` — prior investigation reports (check for related or recurring bugs)
    - `README.md` — project overview
-   - `.agents/hatch.json` — board configuration
+   - `.hatch3r/hatch.json` — board configuration
    - Existing `todo.md` — current backlog (check for overlap or related items)
 2. Scan GitHub issues via `search_issues` for existing work related to the bug. Note duplicates, related bugs, or prior investigations.
-3. If `.agents/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug brief.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug brief.
 4. Present a context summary:
 
 ```
@@ -428,7 +428,7 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
 - **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
 - **File write failure:** Report the error and provide the full file content so the user can create the file manually.
-- **Missing project context:** If no `hatch3r-board-shared` or `.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **Missing project context:** If no `hatch3r-board-shared` or `.hatch3r/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **No existing specs or docs:** Proceed without spec references. Warn that the investigation will be less contextualized without existing project documentation. Recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` first for best results.
 - **Duplicate detection:** If the bug overlaps significantly with existing todo.md items, GitHub issues, or prior investigation reports found in Step 2, present the overlap and ASK whether to proceed (augment existing / replace / abort).
 - **No clear root cause:** If all hypotheses are low-confidence, state this clearly. Recommend a focused debugging session (using `hatch3r-bug-fix` skill with the top hypothesis) rather than generating speculative fix items. ASK the user how to proceed.

package/{commands → dist/content/commands}/hatch3r-codebase-map.md

@@ -4,7 +4,7 @@ type: command
 orchestrator: true
 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]
+tags: [planning, ctx:brownfield-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -105,7 +105,7 @@ From config files and top-level imports, identify:
 - Check for `docs/specs/` — if exists, note contents (including `business/` and `technical/` subdirectories)
 - Check for `docs/adr/` — if exists, note contents
 - Check for `README.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`, or similar
-- Check for `.agents/hatch.json` — if exists, this project already has hatch3r configuration
+- Check for `.hatch3r/hatch.json` — if exists, this project already has hatch3r configuration
 - Check for root `AGENTS.md` — if exists, note its contents
 
 If `docs/specs/` or `docs/adr/` already exist:

package/{commands → dist/content/commands}/hatch3r-create.md

@@ -3,8 +3,8 @@ 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]
+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 .hatch3r/overrides/{type}/, and offers to sync to all enabled adapters.
+tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -25,7 +25,7 @@ This command runs as an orchestrator. After collecting inputs in Phase 1, it del
 
 # `/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).
+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 `.hatch3r/overrides/{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).
 
@@ -75,7 +75,7 @@ Cache the selection as `type`.
 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."
+- 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 `.hatch3r/overrides/{type}/` automatically."
 
 Cache the validated name as `name`.
 
@@ -124,9 +124,9 @@ Cache as `adapters` (array, or `null` for full parity).
 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`. Then ask for a structured `tools` declaration (see §1.6a below) and cache as `tools`.
-- **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.
+- **skill:** Confirm the subdirectory layout. Show: "Skill files are stored as `.hatch3r/overrides/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`.
+- **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 `.hatch3r/overrides/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.6a: Structured Tool Declaration (C9-H81, D20-F20.1.3)
@@ -222,14 +222,14 @@ 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)
+  /abs/path/.hatch3r/overrides/{type}/{name}.md
+  /abs/path/.hatch3r/overrides/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
+Edit your artifact directly anytime — `.hatch3r/overrides/` is preserved across
 `hatch3r update` and `hatch3r clean`.
 ```
 
@@ -237,8 +237,8 @@ Edit your artifact directly anytime — `.agents/user/` is preserved across
 
 ## 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 overwrite an existing user file.** Collision with an existing path under `.hatch3r/overrides/{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 `.hatch3r/overrides/`. 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, quality_charter reference, pillar declaration, structured `tools` field shape + category membership) block the save.
 - **Structured tool allowlist required (strict shape).** When `tools` is supplied for an `agent` artifact, every entry in `tools.allowed` and `tools.denied` must resolve to a canonical category from `ALL_TOOL_CATEGORIES` in `src/pipeline/agentToolAllowlist.ts` (`read | search | write | execute | web | mcp | git | board`). Overlap between the two lists is rejected. Strict-gate enforced at `saveUserContent` (C9-H81, D20-F20.1.3; depends on C9-H49 Hybrid allowlist).
 - **Pillar coverage required (strict).** Every user artifact must declare at least one of P1–P8 — via `pillars: [...]` in frontmatter (collected at Step 1.4a) or a `**Pillars:** ...` line in the body. The strict gate at `saveUserContent` blocks the save when neither is present (C9-H80, D20-F20.1.2).