hatch3r 1.8.0 → 2.0.0

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

@@ -1,9 +1,9 @@
 ---
 id: hatch3r-board-groom
-type: command
-orchestrator: false
+name: hatch3r-board-groom
+type: skill
 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 +14,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 +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
 
@@ -56,10 +45,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.
 
 ---
@@ -696,6 +685,15 @@ Board Groom Complete:
 
 ---
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single-issue re-scope): inline.
+- Tier 2 (multi-issue grooming with reclassification across lanes): spawn parallel sub-agents per lane via the Task tool.
+- Tier 3 (full-board re-grooming): one fresh sub-agent per lane or epic; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **Issue listing failure:** Retry once, then fall back to MCP. If both fail, abort with platform-specific auth guidance:

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

@@ -1,9 +1,9 @@
 ---
 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]
+name: hatch3r-board-init
+type: skill
+description: Initializes 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, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -14,17 +14,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 +30,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 +42,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 +62,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 +86,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 +111,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 +124,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 +147,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 +198,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 +350,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,11 +524,20 @@ 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
 ```
 
 ---
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single-board scaffold with defaults): inline.
+- Tier 2 (board + multiple lanes + seed issues): spawn parallel sub-agents per concern via the Task tool.
+- Tier 3 (multi-board or migration-from-existing init): one fresh sub-agent per board or lane; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **API/CLI failure:** Report the error and suggest checking authentication:
@@ -557,4 +555,9 @@ 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.
+
+## References
+
+- [Using the API to manage Projects (GraphQL) — GitHub docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects) — accessed 2026-05-31, official-docs (GitHub). Source for the `createProjectV2` / `addProjectV2ItemById` / `updateProjectV2ItemFieldValue` mutations and the owner-node-ID requirement in Phase 2.
+- [gh auth refresh — GitHub CLI manual](https://cli.github.com/manual/gh_auth_refresh) — accessed 2026-05-31, official-docs (GitHub). Source for the `project` scope requirement (`gh auth refresh -s project`) and the `GITHUB_TOKEN`/`GH_TOKEN` PAT fallback in the authentication and error-handling steps.

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

@@ -1,9 +1,9 @@
 ---
 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]
+name: hatch3r-board-refresh
+type: skill
+description: Regenerates 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, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -14,17 +14,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 +33,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 +47,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.
 
 ---
@@ -258,6 +247,15 @@ Board Refresh Complete:
 
 ---
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single-board refresh, no re-scoping): inline.
+- Tier 2 (multi-lane refresh with re-scoping or reclassification): spawn parallel sub-agents per lane via the Task tool.
+- Tier 3 (cross-board reconciliation): one fresh sub-agent per board or lane; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **Issue listing failure:** Retry once, then fall back to MCP. If both fail, abort with platform-specific auth guidance:

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

@@ -1,9 +1,9 @@
 ---
 id: hatch3r-board-shared
-type: shared-context
-orchestrator: false
+name: hatch3r-board-shared
+type: skill
 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 +13,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)
+## §0 Detect Ambiguity + Prerequisite Check (P8 B1) — 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 +30,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 +41,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 +90,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 +136,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`.
 
 ---
@@ -306,6 +301,36 @@ The export is idempotent and safe to re-set. `GH_PAGER` is scoped to `gh`; `PAGE
 
 ---
 
+## Todo Grammar
+
+Single source of truth for the `todo.md` line format shared by the producers (`hatch3r-roadmap` Step 5, `hatch3r-project-spec` Step 6) and the consumer (`hatch3r-board-fill` Step 1). Producers MUST emit this grammar; board-fill MUST parse it with the rules below so checkbox glyphs and scope tags never leak into issue titles and priority headers never parse as items.
+
+**Line forms:**
+
+| Form | Pattern | Parse as |
+|------|---------|----------|
+| Priority header | `## P{N} — {Label}` (N = 0–3) | Section header — sets the `priority:p{N}` default for items beneath it. NOT a todo item. |
+| Future-ideas header | `## Future Ideas` | Section header — items beneath it default to `priority:p3`. NOT a todo item. |
+| Todo item | `- [ ] **[{TAG}] {Title}**: {Description}[ Ref: {path}.]` | One todo item. `{TAG}` ∈ `{BIZ, TECH, BOTH}`. |
+
+**Parse rules (board-fill Step 1 applies in order):**
+
+1. **Skip headers.** A line matching `^## ` (priority header or `## Future Ideas`) is a section marker, not an item. Record its `P{N}` value (or `p3` for `## Future Ideas`) as the priority default for items until the next header.
+2. **Strip the list/checkbox token.** Strip a leading list marker (`- ` or `* `) and, if present, a checkbox token (`[ ]` or `[x]`, case-insensitive) that immediately follows it. Lines without `- `/`* ` are not items.
+3. **Extract the scope tag.** Parse the leading `**[{TAG}]` token; capture `{TAG}` ∈ `{BIZ, TECH, BOTH}` and remove it from the title. `BIZ` → business-driven, `TECH` → technically-driven, `BOTH` → cross-cutting. Feed the tag into Step 3 classification (area/executor lean), not the title.
+4. **Split title and description.** The bold span `**…**` is the item title (strip the surrounding `**`); the text after the first `:` is the description. A trailing `Ref: {path}.` carries the source spec/ADR path — surface it as a documentation reference, not part of the title.
+5. **Carry the priority default.** Apply the enclosing header's `P{N}` as the item's default `priority:*` (overridable by Step 3 triage). Items above the first header default to `p2`.
+
+Items not matching the todo-item form (blank lines, prose, stray bullets without a `**[{TAG}]…**` span) are skipped with a one-line note in the parsed-list output so the user can correct malformed entries.
+
+---
+
+## Fan-out Discipline (P8 B2)
+
+Reference library — no fan-out. This skill ships shared board context (configuration, sync procedures, tooling directives) consumed by the delegating board commands (`board-fill`, `board-pickup`, `board-init`, `board-refresh`, `board-groom`). It spawns no sub-agents itself; fan-out is owned by the consuming command per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
+---
+
 ## Token-Saving Directives
 
 These apply to all board commands. Follow them to minimize token consumption.
@@ -335,3 +360,8 @@ All mutating board commands MUST maintain a run cache with the following entries
 | `errors` | `{step, issue?, message, recoverable}[]` | All errors encountered during the run |
 
 Initialize all entries at the start of the run. Populate incrementally as operations execute. The reconciliation procedure reads these entries to detect and fix drift.
+
+## References
+
+- [gh auth refresh — GitHub CLI manual](https://cli.github.com/manual/gh_auth_refresh) — accessed 2026-05-31, official-docs (GitHub). Source for the `project` scope requirement (`gh auth refresh -s project`), the classic-PAT `admin:org` note, and the `GITHUB_TOKEN`/`GH_TOKEN` fallback in the prerequisites/authentication section.
+- [Using the API to manage Projects (GraphQL) — GitHub docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects) — accessed 2026-05-31, official-docs (GitHub). Source for the Projects V2 IDs, status-field sync, and built-in "Item closed" / "Pull request merged" workflow behavior the shared board config and sync procedures depend on.