hatch3r 1.8.0 → 1.9.0

package/{rules → dist/content/rules}/hatch3r-tooling-hierarchy.md

@@ -2,8 +2,8 @@
 id: hatch3r-tooling-hierarchy
 type: rule
 description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
-scope: "**/.agents/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/.windsurf/**,**/hatch.json,**/.claude/**"
-tags: [core]
+scope: "**/.hatch3r/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/hatch.json,**/.claude/**"
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -13,7 +13,7 @@ cache_friendly: true
 
 **Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations.
 
-Read `platform` from `.agents/hatch.json` to determine which platform tools to use.
+Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
 
 ### Prerequisites
 
@@ -82,7 +82,7 @@ Use web search to retrieve current, real-world information not available in proj
 - Internal project decisions (use project ADRs).
 
 **Fallback when web search is unavailable:**
-If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.agents/hatch.json`), web research cannot be performed. In this case:
+If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.hatch3r/hatch.json`), web research cannot be performed. In this case:
 - Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available").
 - Rely more heavily on Context7 documentation MCP and codebase exploration.
 - Flag security-sensitive decisions that would benefit from current advisory data.

package/{rules → dist/content/rules}/hatch3r-tooling-hierarchy.mdc

@@ -1,6 +1,6 @@
 ---
 description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
-globs: ["**/.agents/**", "**/mcp/**", "**/mcp.json", "**/.cursor/**", "**/.github/copilot*", "**/.windsurf/**", "**/hatch.json", "**/.claude/**"]
+globs: ["**/.hatch3r/**", "**/mcp/**", "**/mcp.json", "**/.cursor/**", "**/.github/copilot*", "**/hatch.json", "**/.claude/**"]
 alwaysApply: false
 ---
 # Tooling Hierarchy
@@ -9,7 +9,7 @@ alwaysApply: false
 
 **Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations.
 
-Read `platform` from `.agents/hatch.json` to determine which platform tools to use.
+Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
 
 ### Prerequisites
 
@@ -78,7 +78,7 @@ Use web search to retrieve current, real-world information not available in proj
 - Internal project decisions (use project ADRs).
 
 **Fallback when web search is unavailable:**
-If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.agents/hatch.json`), web research cannot be performed. In this case:
+If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.hatch3r/hatch.json`), web research cannot be performed. In this case:
 - Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available").
 - Rely more heavily on Context7 documentation MCP and codebase exploration.
 - Flag security-sensitive decisions that would benefit from current advisory data.

package/{rules → dist/content/rules}/hatch3r-ux-states-and-flows.md

@@ -3,7 +3,8 @@ id: hatch3r-ux-states-and-flows
 type: rule
 description: Four-state surface contract (loading/empty/error/partial), user-flow decomposition before implementation, and microcopy + tone discipline for end-user UIs
 scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/messages/**,**/locales/**,**/copy/**"
-tags: [ux, ui, frontend]
+tags: [implementation, floor:ui-ux, ux, ui, frontend]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-ux-states-and-flows.mdc

@@ -2,6 +2,7 @@
 description: Four-state surface contract (loading/empty/error/partial), user-flow decomposition before implementation, and microcopy + tone discipline for end-user UIs
 globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/messages/**", "**/locales/**", "**/copy/**"]
 alwaysApply: false
+precedence: high
 ---
 # UX States and Flows
 

package/{skills → dist/content/skills}/hatch3r-a11y-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-a11y-audit
 description: Run a WCAG AA accessibility audit with findings and fixes across 7 scan categories (keyboard, contrast, ARIA, reduced motion, screen reader, high contrast, automated axe). Use when auditing accessibility or verifying WCAG compliance.
-tags: [review, a11y]
+tags: [review, floor:ui-ux, a11y]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-architecture-review/SKILL.md

@@ -72,7 +72,7 @@ Reference:
 ## Step 4: External Research
 
 - For external library docs and current best practices, follow the project's tooling hierarchy.
-- **Issue/PR search** (check `platform` in `.agents/hatch.json`): Search for related issues, prior discussions, or similar decisions in the repo:
+- **Issue/PR search** (check `platform` in `.hatch3r/hatch.json`): Search for related issues, prior discussions, or similar decisions in the repo:
   - **GitHub:** Use **GitHub MCP** or `gh issue list --search "..."` / `gh pr list --search "..."`
   - **Azure DevOps:** `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] CONTAINS '...'"` or `az repos pr list`
   - **GitLab:** `glab issue list --search "..."` / `glab mr list --search "..."`

package/{commands/hatch3r-board-groom.md → dist/content/skills/hatch3r-board-groom/SKILL.md}

@@ -1,9 +1,7 @@
 ---
 id: hatch3r-board-groom
-type: command
-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]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -14,17 +12,6 @@ parallel_tool_default: true
 
 Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
 
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation.
-
-All board operations MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared`.
-
-# Board Groom -- Backlog Refinement for Existing Issues
-
-Perform ongoing backlog grooming on **{owner}/{repo}** (read from `.agents/hatch.json` board config). Scans all open issues, surfaces health-driven refinement suggestions, and lets the user selectively apply grooming actions: re-prioritize, reclassify, re-scope, demote, archive, decompose, merge duplicates, refresh dependencies, and remediate board health gaps. Unlike `board-fill` (which ingests new work from `todo.md`), board-groom operates exclusively on existing board items. Unlike `board-refresh` (which is read-only), board-groom mutates issues based on user-confirmed decisions.
-
----
 
 ## Integration with GitHub Agentic Workflows
 
@@ -42,7 +29,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
 
@@ -56,10 +43,10 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 ### Step 1: Read Configuration
 
-1. Read `.agents/hatch.json` and cache the full config (top-level `owner`/`repo`, `platform`, and `board` section).
-2. Read `platform` from `.agents/hatch.json`. Default to `github` if missing.
+1. Read `.hatch3r/hatch.json` and cache the full config (top-level `owner`/`repo`, `platform`, and `board` section).
+2. Read `platform` from `.hatch3r/hatch.json`. Default to `github` if missing.
 3. Resolve owner/repo per `hatch3r-board-shared`: use top-level `owner`/`repo` first, fall back to `board.owner`/`board.repo` if top-level values are empty.
-4. If both are missing, abort with: "Cannot groom board -- owner and repo are not configured in `.agents/hatch.json`. Run `board-init` first."
+4. If both are missing, abort with: "Cannot groom board -- owner and repo are not configured in `.hatch3r/hatch.json`. Run `board-init` first."
 5. Note `board.projectNumber` -- if null, board sync will be skipped later.
 
 ---

package/{commands/hatch3r-board-init.md → dist/content/skills/hatch3r-board-init/SKILL.md}

@@ -1,9 +1,7 @@
 ---
 id: hatch3r-board-init
-type: command
-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]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -14,17 +12,6 @@ parallel_tool_default: true
 
 Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
 
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation.
-
-All board operations MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared`.
-
-# Board Init -- Bootstrap a Project Board
-
-Initialize a new or existing project board for **{owner}/{repo}** (read from `.agents/hatch.json` board config). The `platform` field in `hatch.json` determines whether to set up GitHub Projects V2, Azure Boards, or GitLab Issue Boards. Sets up status fields/states, creates the full hatch3r label/tag taxonomy, optionally migrates issues from another project, and writes all IDs back to `.agents/hatch.json` so subsequent board commands work out of the box. AI proposes configuration; user confirms before any mutation.
-
----
 
 ## Integration with Platform Agentic Workflows
 
@@ -41,7 +28,7 @@ Platform agentic workflows and hatch3r are complementary: use platform workflows
 
 ## 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
 
@@ -53,7 +40,7 @@ Follow the **Token-Saving Directives** in `hatch3r-board-shared`.
 
 If the user requests quick mode, defaults mode, or passes a `--quick` or `--defaults` flag: use all auto-detected values without prompting and proceed directly to execution with a single confirmation. Specifically:
 
-1. Auto-detect owner/repo from `.agents/hatch.json` (skip ASK in 1.1).
+1. Auto-detect owner/repo from `.hatch3r/hatch.json` (skip ASK in 1.1).
 2. Default to "Create new project" if `board.projectNumber` is null (skip ASK in 1.2).
 3. Use `{repo} Board` as the project name (skip ASK in 1.2a).
 4. Auto-detect default branch via `git rev-parse --abbrev-ref origin/HEAD` (skip ASK in 1.2b).
@@ -73,7 +60,7 @@ This command runs in two phases: **Planning** (collect all answers) then **Execu
 
 Run BEFORE Phase 1. Halt on the first failure with an actionable fix command. Do not prompt for board configuration choices until every prerequisite below succeeds.
 
-1. **Run the shared Prerequisite Check.** Execute the `Prerequisite Check` block in `hatch3r-board-shared` §"Prerequisite Check (run at the start of every board command)" — verifies `.agents/hatch.json` exists, owner/repo configured, and platform CLI authenticated (`gh auth status` / `az account show` / `glab auth status`).
+1. **Run the shared Prerequisite Check.** Execute the `Prerequisite Check` block in `hatch3r-board-shared` §"Prerequisite Check (run at the start of every board command)" — verifies `.hatch3r/hatch.json` exists, owner/repo configured, and platform CLI authenticated (`gh auth status` / `az account show` / `glab auth status`).
 
 2. **Verify platform credentials at the env-var layer.** The shared prereq check confirms the CLI is authenticated; this step additionally verifies the underlying credential is present for non-interactive runs:
 
@@ -97,12 +84,12 @@ Run BEFORE Phase 1. Halt on the first failure with an actionable fix command. Do
    **If platform is `gitlab`:**
    - Run `glab auth status`. If it fails, check for `GITLAB_TOKEN`. If neither is configured, ASK using the same plain-text fallback shape with options: (1) `glab auth login` interactively, (2) provide GITLAB_TOKEN, (3) abort. Default: 1.
 
-3. **Verify owner/repo identity.** Read `.agents/hatch.json` and confirm both top-level `owner`/`repo` (or `board.owner`/`board.repo` as fallback) are set and non-empty. If either is empty, ASK using the user-question-protocol plain-text fallback shape:
+3. **Verify owner/repo identity.** Read `.hatch3r/hatch.json` and confirm both top-level `owner`/`repo` (or `board.owner`/`board.repo` as fallback) are set and non-empty. If either is empty, ASK using the user-question-protocol plain-text fallback shape:
 
    ```
-   **Question:** Owner/repo are not configured in `.agents/hatch.json`. How should I capture them?
+   **Question:** Owner/repo are not configured in `.hatch3r/hatch.json`. How should I capture them?
 
-   1. Provide owner and repo now — paste in this turn; I will write them to `.agents/hatch.json` after Phase 1 confirmation.
+   1. Provide owner and repo now — paste in this turn; I will write them to `.hatch3r/hatch.json` after Phase 1 confirmation.
    2. Run `npx hatch3r config` first — abort, configure repo identity, then re-run `hatch3r-board-init`.
 
    Default if no response: 1
@@ -122,8 +109,8 @@ Collect all configuration choices upfront. No GitHub API calls or file writes in
 
 #### 1.1: Read Configuration
 
-1. Read `.agents/hatch.json` and cache the `board` config.
-2. Read `platform` from `.agents/hatch.json`. Default to `github` if missing. Cache for the run.
+1. Read `.hatch3r/hatch.json` and cache the `board` config.
+2. Read `platform` from `.hatch3r/hatch.json`. Default to `github` if missing. Cache for the run.
 3. Resolve owner/repo per `hatch3r-board-shared`: **Use top-level `owner`/`repo` first.** Fall back to `board.owner`/`board.repo` if top-level values are empty.
 4. If both are set (from either source), note: "Using owner=`{owner}`, repo=`{repo}`, platform=`{platform}`."
 5. If either is missing:
@@ -135,7 +122,7 @@ Update the in-memory config with the provided values.
 #### 1.2: Choose Mode
 
 **If platform is `github`:**
-1. If `board.projectNumber` is already set in `.agents/hatch.json`, default to **B** (Connect to existing project #{board.projectNumber}).
+1. If `board.projectNumber` is already set in `.hatch3r/hatch.json`, default to **B** (Connect to existing project #{board.projectNumber}).
 2. If `board.projectNumber` is null or missing, default to **A** (Create new).
 
 **If platform is `azure-devops`:**
@@ -158,15 +145,15 @@ No separate prompt — the project name is included in the consolidated plan con
 
 #### 1.2b: Default Branch
 
-1. Auto-detect the default branch: run `git rev-parse --abbrev-ref origin/HEAD` and strip the `origin/` prefix. If the command fails (e.g., no remote configured), fall back to `board.defaultBranch` from `.agents/hatch.json`, then to `"main"`.
+1. Auto-detect the default branch: run `git rev-parse --abbrev-ref origin/HEAD` and strip the `origin/` prefix. If the command fails (e.g., no remote configured), fall back to `board.defaultBranch` from `.hatch3r/hatch.json`, then to `"main"`.
 2. Record the detected branch name. This value is written to `board.defaultBranch` and used by board-pickup (checkout, PR base) and other agents.
 
 No separate prompt — the detected branch is included in the consolidated plan confirmation (Step 1.6).
 
 #### 1.3: Area Labels
 
-1. Auto-suggest area labels from the top-level source directories in the codebase. Scan the repository root and common source roots (`src/`, `packages/`, `apps/`) for top-level directories that represent distinct areas (e.g., `frontend`, `backend`, `api`, `infra`, `cli`, `docs`). Exclude non-area directories (`node_modules`, `.git`, `dist`, `build`, `.github`, `.agents`, `coverage`, `__tests__`).
-2. If `board.areas` already has entries in `.agents/hatch.json`, use those as the default and note the source.
+1. Auto-suggest area labels from the top-level source directories in the codebase. Scan the repository root and common source roots (`src/`, `packages/`, `apps/`) for top-level directories that represent distinct areas (e.g., `frontend`, `backend`, `api`, `infra`, `cli`, `docs`). Exclude non-area directories (`node_modules`, `.git`, `dist`, `build`, `.github`, `.hatch3r`, `coverage`, `__tests__`).
+2. If `board.areas` already has entries in `.hatch3r/hatch.json`, use those as the default and note the source.
 3. Present the auto-detected areas in the consolidated plan confirmation (Step 1.6) where the user can confirm, add, remove, or skip area labels.
 
 No separate prompt — area labels are included in the consolidated plan confirmation (Step 1.6).
@@ -209,7 +196,7 @@ Board Init Plan:
 
 Execute all planned mutations in sequence. No further questions unless a mutation fails.
 
-**--resume flag.** When invoked with `--resume`, board-init checks `board.workflows.itemClosedEnabled` in `.agents/hatch.json`. If true, Phase 2.1 through 2.5 are skipped (project, status field, labels, migration, config write-back have already succeeded) and execution jumps directly to the workflow verification gate (§2.2 step 6 above) for the GitHub platform, then proceeds to §2.6 (Create Board Overview Issue) on success. If the gate still fails, the command re-halts with the same actionable message. Non-GitHub platforms ignore `--resume` and run Phase 2 normally.
+**--resume flag.** When invoked with `--resume`, board-init checks `board.workflows.itemClosedEnabled` in `.hatch3r/hatch.json`. If true, Phase 2.1 through 2.5 are skipped (project, status field, labels, migration, config write-back have already succeeded) and execution jumps directly to the workflow verification gate (§2.2 step 6 above) for the GitHub platform, then proceeds to §2.6 (Create Board Overview Issue) on success. If the gate still fails, the command re-halts with the same actionable message. Non-GitHub platforms ignore `--resume` and run Phase 2 normally.
 
 #### 2.1: Create or Connect Project
 
@@ -361,7 +348,7 @@ Execute all planned mutations in sequence. No further questions unless a mutatio
 
 #### 2.3: Create Label Taxonomy
 
-1. Read the label taxonomy from `board.labels` in `.agents/hatch.json`.
+1. Read the label taxonomy from `board.labels` in `.hatch3r/hatch.json`.
 2. If labels are not defined or empty, use these defaults:
 
 | Category  | Labels |
@@ -535,7 +522,7 @@ Board Init Complete:
   Areas: [list or "none"]
   Migration: N issues migrated from Project #X (or "skipped")
   Board overview: #{issueNumber}
-  Config: .agents/hatch.json updated
+  Config: .hatch3r/hatch.json updated
 ```
 
 ---
@@ -557,4 +544,4 @@ Board Init Complete:
 - **Collect all choices in Phase 1 before any mutations in Phase 2.**
 - **Never skip Planning questions or the plan confirmation step.**
 - **Require proper authentication** for the configured platform. If mutations fail with permission errors, surface platform-specific auth requirements.
-- **Preserve existing `.agents/hatch.json` content** outside the `board` key when writing config back.
+- **Preserve existing `.hatch3r/hatch.json` content** outside the `board` key when writing config back.

package/{commands/hatch3r-board-refresh.md → dist/content/skills/hatch3r-board-refresh/SKILL.md}

@@ -1,9 +1,7 @@
 ---
 id: hatch3r-board-refresh
-type: command
-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]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -14,17 +12,6 @@ parallel_tool_default: true
 
 Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
 
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation.
-
-All board operations MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared`.
-
-# Board Refresh -- Regenerate the Board Overview Dashboard
-
-Scan all open issues/work items on **{owner}/{repo}** (read from `.agents/hatch.json` board config), compute board health metrics, build implementation lanes from dependency analysis, and regenerate the `meta:board-overview` dashboard issue with current data, model recommendations, and health diagnostics. The `platform` field determines whether to interact with GitHub Issues, Azure DevOps Work Items, or GitLab Issues. This is a lightweight, read-heavy command -- the only mutation is updating (or creating) the single board overview issue.
-
----
 
 ## Integration with GitHub Agentic Workflows
 
@@ -44,7 +31,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
 
@@ -58,10 +45,10 @@ Execute these steps in order. **Do not skip any step.**
 
 ### Step 1: Read Configuration
 
-1. Read `.agents/hatch.json` and cache the full config (top-level `owner`/`repo`, `platform`, and `board` section).
-2. Read `platform` from `.agents/hatch.json`. Default to `github` if missing.
+1. Read `.hatch3r/hatch.json` and cache the full config (top-level `owner`/`repo`, `platform`, and `board` section).
+2. Read `platform` from `.hatch3r/hatch.json`. Default to `github` if missing.
 3. Resolve owner/repo per `hatch3r-board-shared`: use top-level `owner`/`repo` first, fall back to `board.owner`/`board.repo` if top-level values are empty.
-4. If both are missing, abort with: "Cannot refresh board -- owner and repo are not configured in `.agents/hatch.json`. Run `board-init` first."
+4. If both are missing, abort with: "Cannot refresh board -- owner and repo are not configured in `.hatch3r/hatch.json`. Run `board-init` first."
 5. Note `board.projectNumber` -- if null, board sync will be skipped later.
 
 ---

package/{commands/hatch3r-board-shared.md → dist/content/skills/hatch3r-board-shared/SKILL.md}

@@ -1,9 +1,7 @@
 ---
 id: hatch3r-board-shared
-type: shared-context
-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]
+tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -13,21 +11,16 @@ parallel_tool_default: true
 
 Shared context for `hatch3r-board-fill`, `hatch3r-board-groom`, `hatch3r-board-pickup`, `hatch3r-board-refresh`, and related board commands. Read once per run and cache.
 
-## Agent Pipeline
-
-This command provides shared context and procedures for board commands. It does not spawn sub-agents directly.
-
----
 
 ## Prerequisite Check (run at the start of every board command)
 
 Before reading configuration, validate that prerequisites are met. If any check fails, stop immediately with an actionable error message. For interactive sessions where credentials are missing, use the `agents/shared/user-question-protocol.md` plain-text fallback shape to offer the user a numbered choice (interactive login / paste-token / abort) instead of a bare stop message.
 
-1. **hatch.json exists:** If `.agents/hatch.json` is missing or unreadable, stop with:
+1. **hatch.json exists:** If `.hatch3r/hatch.json` is missing or unreadable, stop with:
    > "Board commands require a hatch3r project. Run `npx hatch3r init` to set up your project first."
 
 2. **owner/repo configured:** If both top-level `owner`/`repo` and `board.owner`/`board.repo` are empty, stop with:
-   > "Board commands require owner and repo. Run `npx hatch3r config` to set your repository identity, or provide them in `.agents/hatch.json` under the top-level `owner` and `repo` fields."
+   > "Board commands require owner and repo. Run `npx hatch3r config` to set your repository identity, or provide them in `.hatch3r/hatch.json` under the top-level `owner` and `repo` fields."
 
 3. **Platform authentication:** Verify CLI authentication for the configured platform. On failure, ASK via user-question-protocol with three numbered options (interactive login / paste-token / abort) and default to option 1 if no response.
    - **GitHub:** Run `gh auth status`. If it fails or the `project` scope is missing, check `GITHUB_TOKEN`/`GH_TOKEN` env vars first; if absent, ASK: (1) `gh auth login` interactively, (2) paste a PAT with `project` scope (set GITHUB_TOKEN for this session only), (3) abort. Reference: https://docs.github.com/en/issues/planning-and-tracking-with-projects
@@ -35,7 +28,7 @@ Before reading configuration, validate that prerequisites are met. If any check
    - **GitLab:** Run `glab auth status`. If it fails, check `GITLAB_TOKEN`; if absent, ASK: (1) `glab auth login` interactively, (2) provide GITLAB_TOKEN, (3) abort. Confirm access to project `{namespace}/{project}`.
 
 4. **projectNumber set (for commands other than board-init):** For `board-fill`, `board-groom`, `board-pickup`, and `board-refresh`, if `board.projectNumber` is null, stop with:
-   > "No project board configured. Run the `board-init` command first to create or connect a project board. This sets up the board.projectNumber in `.agents/hatch.json`."
+   > "No project board configured. Run the `board-init` command first to create or connect a project board. This sets up the board.projectNumber in `.hatch3r/hatch.json`."
 
 5. **GitHub PAT project scope (GitHub only, for board-init/fill/groom/pickup):** If GitHub mutations fail with permission errors, surface:
    > "GitHub Projects V2 requires the `project` scope on your PAT. Run `gh auth refresh -s project` to add it. Classic PATs need `admin:org` for org-owned projects."
@@ -46,7 +39,7 @@ Report each failed prerequisite with the specific fix command. Do not proceed pa
 
 ## Board Configuration
 
-All board commands read project-specific configuration from `.agents/hatch.json`. The GitHub owner and repo are defined at the top level (`owner`, `repo`). Board-specific configuration (Projects v2 IDs, label taxonomy, branch conventions, area labels) lives under the `board` key. **Read `.agents/hatch.json` at the start of every run and cache both top-level and `board` config for the duration.**
+All board commands read project-specific configuration from `.hatch3r/hatch.json`. The GitHub owner and repo are defined at the top level (`owner`, `repo`). Board-specific configuration (Projects v2 IDs, label taxonomy, branch conventions, area labels) lives under the `board` key. **Read `.hatch3r/hatch.json` at the start of every run and cache both top-level and `board` config for the duration.**
 
 **Owner/repo resolution:** Use top-level `owner`/`repo`. Fall back to `board.owner`/`board.repo` if top-level values are empty (backward compatibility).
 
@@ -95,7 +88,7 @@ If any field is `null` or missing, the corresponding feature is disabled (e.g.,
 
 ## Platform Detection
 
-Read `platform` from `.agents/hatch.json`. This determines all CLI commands, API patterns, and terminology for this run. If `platform` is missing or empty, default to `github`.
+Read `platform` from `.hatch3r/hatch.json`. This determines all CLI commands, API patterns, and terminology for this run. If `platform` is missing or empty, default to `github`.
 
 > Platform-specific details: see `commands/board/shared-github.md`
 > Platform-specific details: see `commands/board/shared-azure-devops.md`
@@ -141,7 +134,7 @@ Board sync is **MANDATORY**, not optional. The following rules override any "ski
 6. **Cross-reference: every epic/work item and sub-issue must have its board item ID tracked for subsequent updates.** After adding an item to the board, store the returned item ID in the run cache keyed by issue number.
 7. **`has-dependencies` label consistency:** Every issue with a non-empty `## Dependencies` section (containing at least one `Blocked by` or `Recommended after` reference) MUST have the `has-dependencies` label. Issues whose `## Dependencies` section contains only `None` MUST NOT have the label. Board commands enforce this during creation and update.
 8. **Retry-then-halt fallback policy.** When the Board Sync Procedure's full fallback chain (platform CLI -> MCP) fails for a single item, retry the full chain exactly twice with 2-second then 8-second backoffs. If the third attempt fails, halt that item (not the whole run), roll back only the specific status label this run added (snapshot the item's label set at start-of-sync; do not revert labels that pre-existed or were set concurrently by a human), surface the item to the user as a blocker, and record all three attempts with timestamps under `sync_results` in the run cache.
-9. **Null-option abort.** If any `board.statusOptions.*` key required by a planned sync mutation is null in `.agents/hatch.json`, halt the mutation before it fires with: "Cannot sync {status:label}: board.statusOptions.{key} is null in .agents/hatch.json. Run `hatch3r-board-init` to populate status option IDs." Do not proceed with remaining items in the batch.
+9. **Null-option abort.** If any `board.statusOptions.*` key required by a planned sync mutation is null in `.hatch3r/hatch.json`, halt the mutation before it fires with: "Cannot sync {status:label}: board.statusOptions.{key} is null in .hatch3r/hatch.json. Run `hatch3r-board-init` to populate status option IDs." Do not proceed with remaining items in the batch.
 10. **Retry budget ceiling.** No more than 20% of items in a batch may enter retry (rule 8). If the ceiling is exceeded, halt the batch -- this pattern indicates systemic failure (auth expired, project moved, rate limit exceeded), not per-item noise. Record a single batch-level error in the run cache `errors` entry in addition to the per-item `sync_results`.
 
 ---

package/{skills → dist/content/skills}/hatch3r-bug-fix/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-bug-fix
 description: Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-cli-fd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-cli-fd
 description: "User-friendly find replacement, gitignore-aware. Use when locating filenames or directories by glob with parallel walking; invoke `fd`. Outputs newline-separated hit records; bound results with `-c` or `--max-count`."
-tags: ["cli-tools", "search", "core"]
+tags: ["cli-tools", "search", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-cli-fzf/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-cli-fzf
 description: "Interactive fuzzy finder for TTY pickers. Use when ad-hoc interactive picker over piped stdin streams from another command; invoke `fzf`. Requires a TTY; degrade gracefully to non-interactive batch in CI."
-tags: ["cli-tools", "interactive"]
+tags: ["cli-tools", "interactive", "maintenance"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-cli-gh/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-cli-gh
 description: "GitHub CLI — repos, issues, PRs, releases, gists. Use when drafting GitHub pull requests, issues, releases, gists, or workflow dispatches; invoke `gh`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
-tags: ["cli-tools", "forge", "core"]
+tags: ["cli-tools", "forge", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -60,7 +60,7 @@ Live-tail status checks for a PR — return value reflects the worst check state
 
 ## Wrong Choice When
 
-- Don't reach for `gh` against a GitLab or Azure DevOps remote. Reach for `glab` (`hatch3r-cli-glab`) or `az repos`/`az devops` (`hatch3r-cli-az-devops`).
+- Don't reach for `gh` against a GitLab or Azure DevOps remote. Reach for `glab` or `az repos`/`az devops` (both covered in `hatch3r-cli-toolbox` — Forges section).
 - Don't use `gh auth login` flows when an audit trail of who authorized what is required; OAuth scopes granted to the CLI are user-bound. Reach for the GitHub web UI plus org-level SSO logs.
 - Don't use `gh api` for high-volume bulk fetches (>10k records) — rate limits bite. Reach for the GraphQL endpoint via `gh api graphql -F query=@file.gql` with pagination, or a GitHub App token.
 
@@ -68,8 +68,8 @@ Live-tail status checks for a PR — return value reflects the worst check state
 
 | Tool | When to prefer |
 |------|----------------|
-| `glab` (`hatch3r-cli-glab`) | GitLab forges — same operations, different vendor. |
-| `az-devops` (`hatch3r-cli-az-devops`) | Azure DevOps forges. |
+| `glab` (toolbox section) | GitLab forges — same operations, different vendor. |
+| `az-devops` (toolbox section) | Azure DevOps forges. |
 | `git` + `curl` against REST | Minimal environment (CI runner) where installing `gh` is blocked; trade convenience for raw HTTP. |
 | GitHub web UI | Operations needing org-level approval flows or SAML re-auth that the CLI cannot proxy. |
 

package/{skills → dist/content/skills}/hatch3r-cli-jq/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-cli-jq
 description: "JSON processor and query language. Use when shaping JSON streams via jq-syntax filters and select expressions; invoke `jq`. Reads stdin and emits stdout; integrates seamlessly into shell pipelines."
-tags: ["cli-tools", "json", "core"]
+tags: ["cli-tools", "json", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -56,14 +56,14 @@ Compact (`-c`) one-object-per-line projection — perfect input for `xargs -L1`
 ## Wrong Choice When
 
 - Don't use `jq` for bidirectional grep on flattened paths; the inverse (`gron` outputs `obj.foo.bar = …` lines you can `rg` then translate back). Reach for `gron`.
-- Don't use `jq` directly on multi-document YAML or front-matter Markdown. Reach for `yq` (`hatch3r-cli-yq`) and pipe `yq -o=json` into `jq` only if you need jq's filter language.
+- Don't use `jq` directly on multi-document YAML or front-matter Markdown. Reach for `yq` (toolbox section in `hatch3r-cli-toolbox`) and pipe `yq -o=json` into `jq` only if you need jq's filter language.
 - Don't reach for `jq` when the file is a stream of newline-delimited JSON (`.ndjson`); use `jq -c` per line or `jaq`/`fx` for stream-friendly behavior — `jq` without `-c` slurps the whole file.
 
 ## Alternatives
 
 | Tool | When to prefer |
 |------|----------------|
-| `yq` (`hatch3r-cli-yq`) | YAML, TOML, XML input — yq speaks them all, jq is JSON-only. |
+| `yq` (toolbox section) | YAML, TOML, XML input — yq speaks them all, jq is JSON-only. |
 | `gron` | Flatten JSON to `path = value` lines for grep-based exploration and reverse-translation. |
 | `dasel` | Single binary across JSON/YAML/TOML/XML with a path-query DSL — handy in CI where you do not want jq+yq. |
 | `fx` | Interactive JSON browsing in a TTY; jq is the right call in scripts. |

package/{skills → dist/content/skills}/hatch3r-cli-ripgrep/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-cli-ripgrep
 description: "Fast recursive grep with sane defaults and gitignore awareness. Use when regex content searches across large source trees with gitignore filtering; invoke `rg`. Outputs newline-separated hit records; bound results with `-c` or `--max-count`."
-tags: ["cli-tools", "search", "core"]
+tags: ["cli-tools", "search", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -55,7 +55,7 @@ Two-phase: file list first, then ranged scan — keeps stdout small when match d
 
 ## Wrong Choice When
 
-- Don't use `rg` to match by code structure (function calls, type signatures, JSX shape); literal regex misses renames and whitespace variants. Reach for `ast-grep` (`hatch3r-cli-ast-grep`).
+- Don't use `rg` to match by code structure (function calls, type signatures, JSX shape); literal regex misses renames and whitespace variants. Reach for `ast-grep` (see the ast-grep section in `hatch3r-cli-toolbox`).
 - Don't run `rg` against binary blobs (`.zst`, `.png`, lockfile snapshots); it skips them silently by default but explicit `-a` mode wastes CPU. Reach for category-specific tools (`zstd -d` then `rg`, or `xxd | rg` for hex).
 - Don't use `rg` to search a specific git revision or stash — it only sees the working tree. Reach for `git grep <rev>`.
 
@@ -63,7 +63,7 @@ Two-phase: file list first, then ranged scan — keeps stdout small when match d
 
 | Tool | When to prefer |
 |------|----------------|
-| `ast-grep` (`hatch3r-cli-ast-grep`) | Structural code patterns: matchers like `console.log($MSG)` that survive whitespace and identifier renames. |
+| `ast-grep` (toolbox section) | Structural code patterns: matchers like `console.log($MSG)` that survive whitespace and identifier renames. |
 | `git grep` | Search at a specific revision, tag, or stash — `rg` only reads the working tree. |
 | `fd` (`hatch3r-cli-fd`) piped into `rg` | Filename pre-filter when scoping by extension/age is faster than `rg --type`. |
 | `grep -RIn` | POSIX-only environment where ripgrep is not on PATH and install is blocked. |