hatch3r 1.0.0 → 1.2.0

package/commands/hatch3r-board-shared.md

@@ -1,17 +1,22 @@
 ---
 id: hatch3r-board-shared
-type: command
-description: Shared context and procedures for all board commands. Provides GitHub context from hatch.json, Projects v2 sync, and tooling directives.
+type: shared-context
+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]
 ---
 # Board Shared Reference
 
-Shared context for `hatch3r-board-fill`, `hatch3r-board-pickup`, `hatch3r-board-refresh`, and related board commands. Read once per run and cache.
+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.
 
 ---
 
 ## 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 `.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.**
 
 **Owner/repo resolution:** Use top-level `owner`/`repo`. Fall back to `board.owner`/`board.repo` if top-level values are empty (backward compatibility).
 
@@ -54,259 +59,89 @@ All board commands read project-specific configuration from `/.agents/hatch.json
 
 If any field is `null` or missing, the corresponding feature is disabled (e.g., null `projectNumber` → skip Projects v2 sync).
 
-**`models`** — Optional. Preferred AI models for agents. `models.default` applies to all agents; `models.agents` overrides per agent. Use aliases (`opus`, `sonnet`, `codex`, `gemini-pro`) or full model IDs. Resolution order: `.hatch3r/agents/{id}.customize.yaml` > manifest per-agent > agent frontmatter > manifest default. See [docs/model-selection.md](../docs/model-selection.md) and [docs/adapter-capability-matrix.md](../docs/adapter-capability-matrix.md#agent-model-customization).
+**`models`** — Optional. Preferred AI models for agents. `models.default` applies to all agents; `models.agents` overrides per agent. Use aliases (`opus`, `sonnet`, `codex`, `gemini-pro`) or full model IDs. Resolution order: `.hatch3r/agents/{id}.customize.yaml` > manifest per-agent > agent frontmatter > manifest default. See [Model Selection](https://docs.hatch3r.com/docs/guides/model-selection) and [Adapter Capability Matrix](https://docs.hatch3r.com/docs/reference/adapter-capability-matrix#agent-model-customization).
 
 ---
 
-## GitHub Context
-
-Derived from `/.agents/hatch.json` board config:
+## Platform Detection
 
-- **Owner:** top-level `owner` (fallback: `board.owner`)
-- **Repository:** top-level `repo` (fallback: `board.repo`)
-- **Default branch:** `board.defaultBranch` (fallback: `"main"`)
-- **Type labels:** `board.labels.types`
-- **Executor labels:** `board.labels.executors`
-- **Status labels:** `board.labels.statuses`
-- **Dependency label:** `has-dependencies`
-- **Meta labels:** `board.labels.meta`
-- **Branch convention:** `board.branchConvention`
-- **Issue templates:** Check `.github/ISSUE_TEMPLATE/` if present in the repository.
-- **PR template:** Check `.github/PULL_REQUEST_TEMPLATE.md` if present.
+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`.
 
-### Project Reference (cache for the full run)
+> Platform-specific details: see `commands/board/shared-github.md`
+> Platform-specific details: see `commands/board/shared-azure-devops.md`
+> Platform-specific details: see `commands/board/shared-gitlab.md`
 
-If `board.projectNumber` is not null, verify via `gh project view {board.projectNumber} --owner {board.owner}` or `gh project field-list {board.projectNumber} --owner {board.owner}` on first use.
-
-- **Owner:** `board.owner`, **owner type:** infer from context (`org` or `user`)
-- **Project number:** `board.projectNumber`
-- **Status field ID:** `board.statusFieldId`
-- **Status option IDs:** Read from `board.statusOptions` (keys: `backlog`, `ready`, `inProgress`, `inReview`, `done`)
+Each platform sub-file contains: CLI command reference, MCP tool reference, terminology mapping, platform context, board sync procedure, sub-issue linking, board sync enforcement details, and CLI-first tooling directives.
 
 ---
 
-## Projects v2 Sync Procedure
-
-> **Skip entirely if `board.projectNumber` is null.**
-
-Use this procedure whenever a status label is set or changes and the board needs to reflect it. Labels are the source of truth; Projects v2 sync keeps the board view consistent. This includes newly created issues -- sync their initial status immediately after adding them to the board.
-
-**Prerequisites:** `gh auth refresh -s project` (Projects v2 via gh requires the `project` scope). gh CLI 2.40+ recommended.
-
-**Status label → Projects v2 option mapping:**
-
-Read the mapping from `board.statusOptions` in `/.agents/hatch.json`:
+## Board Sync Procedure
 
-| Label                | Option ID from hatch.json          |
-| -------------------- | ---------------------------------- |
-| `status:triage`      | `board.statusOptions.backlog`      |
-| `status:ready`       | `board.statusOptions.ready`        |
-| `status:in-progress` | `board.statusOptions.inProgress`   |
-| `status:in-review`   | `board.statusOptions.inReview`     |
-| `status:blocked`     | `board.statusOptions.backlog`      |
+> **Skip entirely if `board.projectNumber` is null (GitHub/GitLab) or project is not configured (Azure DevOps).**
 
-**Steps for each issue to sync (gh CLI primary):**
+Use this procedure whenever a status label is set or changes and the board needs to reflect it. Labels are the source of truth; board sync keeps the board view consistent. This includes newly created issues -- sync their initial status immediately after adding them to the board.
 
-1. **Resolve project node ID** (once per run, cache for the run): `gh project view {board.projectNumber} --owner {board.owner} --format json -q '.id'`. Required for step 3.
-2. **Add to board + capture item ID:** `gh project item-add {board.projectNumber} --owner {board.owner} --url https://github.com/{board.owner}/{board.repo}/issues/{N} --format json -q '.id'`. **Capture the item ID from the output.** This call is idempotent -- if the item already exists on the board it returns the existing item with its ID.
-3. **Update status:** `gh project item-edit --id {item_id} --project-id {project_node_id} --field-id {board.statusFieldId} --single-select-option-id {option_id}` using the label→option mapping from the table above.
-4. **Verify (first sync per run only):** After step 3, optionally confirm via `gh project item-list {board.projectNumber} --owner {board.owner} --format json` that the item's status matches. If it does not, retry step 3 once.
-
-**For PRs:** Use `--url https://github.com/{board.owner}/{board.repo}/pull/{N}` in step 2.
-
-**Fallback (rare):** If item-add does not return an item ID, use `gh project item-list {board.projectNumber} --owner {board.owner} --format json` and match by issue/PR content to obtain the item ID. Then proceed with step 3.
-
-**MCP fallback:** If gh CLI fails, `project` scope is unavailable, or gh version is too old, fall back to `projects_write` / `projects_get` / `projects_list` with `method: add_project_item`, `method: update_project_item`, `method: get_project_item`, `method: list_project_items` as in the legacy procedure.
-
-**Resilience:** If any call fails, retry once. If it still fails, surface a warning to the user and continue with the next item. If gh CLI and MCP are both unavailable, skip sync silently and warn: "Projects v2 sync skipped -- run `gh auth refresh -s project` or enable the `projects` toolset in your MCP configuration."
+> Platform-specific details: see `commands/board/shared-github.md` (GitHub Projects V2 Sync)
+> Platform-specific details: see `commands/board/shared-azure-devops.md` (Azure Boards Work Item State Sync)
+> Platform-specific details: see `commands/board/shared-gitlab.md` (GitLab Board Label-Based Sync)
 
 ---
 
-## Board Overview
-
-If `meta:board-overview` is included in `board.labels.meta`, board commands will look for an open issue with that label to use as a live dashboard. This dashboard is auto-maintained and MUST be regenerated at the end of every board command run that mutates issues. For on-demand regeneration without running a full board command, use `hatch3r-board-refresh`.
-
-Teams can extend the dashboard with project-specific sections, but the following structure and model recommendations are required.
-
-### Frontier Model Pool
+## Sub-Issue Linking Procedure
 
-When populating the board overview, assign a recommended model to each issue. The pool uses aliases that map to the project's configured model versions in `hatch.json`. Specific model IDs are intentionally omitted here to avoid staleness as model versions change — configure actual model IDs in `hatch.json` under `models`.
+Use this procedure whenever a child issue must be linked to a parent epic. Board commands that create sub-issues MUST follow the platform-specific fallback chain and record the link status.
 
-| Alias | Strength | Use When |
-| ----- | -------- | -------- |
-| `opus` | Code quality, multi-file refactoring, security, deep reasoning | Complex refactors, security-critical, architectural changes, `risk:high` |
-| `codex` | Agentic coding, long-running tasks, tool orchestration | Multi-step implementations, polyglot codebases, complex tool integrations |
-| `gemini-pro` | Large context windows, multimodal, web development | Massive context needs (large epics), web/frontend work |
-| `sonnet` | Balance of quality and speed | Standard features, bugs, docs, QA — when the top-tier model is overkill |
+> Platform-specific details: see `commands/board/shared-github.md` (Sub-Issue Linking — GitHub)
+> Platform-specific details: see `commands/board/shared-azure-devops.md` (Sub-Issue Linking — Azure DevOps)
+> Platform-specific details: see `commands/board/shared-gitlab.md` (Sub-Issue Linking — GitLab)
 
-### Model Selection Heuristic (Quality-First)
-
-1. **Default:** `opus` — highest code quality baseline.
-2. **Override to `codex`** if the issue involves heavy agentic coding, long-running multi-step tasks, or multi-language requirements.
-3. **Override to `gemini-pro`** if the issue requires processing very large context (large epic with many sub-issues spanning many files) or is primarily web/frontend work.
-4. **Downgrade to `sonnet`** ONLY for straightforward issues: simple bugs (`risk:low`), documentation (`type:docs`), QA validation (`type:qa`), or issues with clear bounded scope and no architectural impact.
-
-### Board Overview Issue Format
-
-Issue listings in the board overview MUST include a `Model` column. All board commands that regenerate the dashboard MUST use this canonical template. Omit any status section that has zero issues (except Status Summary, which always appears). Omit Board Health sub-sections that have no findings. Sort issues within each status group by priority (`P0` first), then by issue number.
-
-```markdown
-## Board Overview
-
-**Project:** {owner}/{repo}
-**Last refreshed:** {ISO date}
-
----
-
-## Status Summary
-
-| Status | Count |
-|--------|-------|
-| Backlog / Triage | {count} |
-| Ready | {count} |
-| In Progress | {count} |
-| In Review | {count} |
-| Externally Blocked | {count} |
-| **Total Open** | **{count}** |
+Cache link status per child (`native` / `advisory` / `comment-only`) in the run cache under `link_results`.
 
 ---
 
-## In Progress
-
-| # | Title | Type | Pri | Executor | Model |
-|---|-------|------|-----|----------|-------|
-| #{N} | {title} | {type} | {pri} | {executor} | {model} |
-
-## In Review
-
-| # | Title | Type | Pri | Executor | Model |
-|---|-------|------|-----|----------|-------|
-| #{N} | {title} | {type} | {pri} | {executor} | {model} |
-
-## Implementation Lanes
-
-Issues grouped into independent parallel work streams.
-Different lanes can be worked concurrently; within a lane, follow the listed order.
-
-### Lane 1: {area/theme}
-
-| Order | # | Title | Type | Pri | Executor | Model |
-|-------|---|-------|------|-----|----------|-------|
-| 1 | #{N} | {title} | {type} | {pri} | {executor} | {model} |
-| 2 | #{M} | {title} | {type} | {pri} | {executor} | {model} |
-
-### Lane 2: {area/theme}
+## Board Sync Enforcement
 
-| Order | # | Title | Type | Pri | Executor | Model |
-|-------|---|-------|------|-----|----------|-------|
-| 1 | #{N} | {title} | {type} | {pri} | {executor} | {model} |
+Board sync is **MANDATORY**, not optional. The following rules override any "skip if null" or "skip silently" language elsewhere when the board is configured (GitHub: `board.projectNumber` set; Azure DevOps: project configured; GitLab: board configured).
 
-## Cross-Epic Dependencies
-
-Dependency relationships between epics. Omit if no cross-epic dependencies exist.
-
-| Upstream Epic | Downstream Epic | Via |
-|---------------|-----------------|-----|
-| #{epicA} {title} | #{epicB} {title} | #{subX} blocks #{subY} |
-
-## Waiting on Dependencies
-
-`status:ready` issues with one or more unsatisfied blockers. Not yet available for pickup.
-
-| # | Title | Type | Waiting On | Model |
-|---|-------|------|------------|-------|
-| #{N} | {title} | {type} | #{blocker} ({blocker status}) | {model} |
-
-## Externally Blocked
-
-Issues with `status:blocked` -- waiting on external factors (approvals, environments, third-party services).
-
-| # | Title | Type | Reason | Model |
-|---|-------|------|--------|-------|
-| #{N} | {title} | {type} | {blocker reason} | {model} |
-
-## Backlog / Triage
-
-| # | Title | Type | Pri | Executor | Model |
-|---|-------|------|-----|----------|-------|
-| #{N} | {title} | {type} | {pri} | {executor} | {model} |
+1. **Every issue/work item created or updated by a board command MUST be synced to the board — no exceptions.** This includes newly created issues, status changes, label updates, and any mutation that affects board state. Skipping sync for any item is a violation of this policy.
+2. **Status MUST be updated after every status-changing operation.** The four canonical statuses — Ready, In Progress, In Review, Done — must be reflected on the board immediately after the corresponding label change. Do not batch status updates to "later" or defer them. See the platform sub-files for platform-specific status update commands.
+3. **All available board fields (priority, sprint, area, iteration) MUST be populated when the data is available.** Never leave a board field empty if the information exists in the issue's labels, body, or metadata.
+4. **Board overview dashboard MUST be regenerated after any batch of issue operations.** This is in addition to the per-run regeneration rule — if a board command performs multiple batches of mutations, the dashboard must reflect the final state.
+5. **Fallback: never silently skip sync.** See platform sub-files for escalation paths. Silent skipping is prohibited.
+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.
 
 ---
 
-## Board Health
-
-**Missing metadata:**
-- {list or "None -- all issues have required labels."}
+## End-of-Run Reconciliation Procedure
 
-**Stale issues:**
-- {list or "None -- all issues are active."}
+Every mutating board command (`board-fill`, `board-groom`, `board-pickup`) runs this procedure as its final step before the summary output. It catches silent failures and drift accumulated during the run.
 
-**Blocked chains:**
-- {list or "None -- no blocked dependencies."}
+1. **Board sync verification:** Re-attempt sync for any issue where `sync_results` in the run cache shows a failure. Use the full **Board Sync Procedure** fallback chain. Record final status.
+2. **Sub-issue link verification:** Review `link_results` in the run cache. For links recorded as `advisory`, retry the platform-specific primary link method once to upgrade to `native`. Report all non-native links (`advisory` / `comment-only`) in the reconciliation output.
+3. **Label consistency:** Verify all created/updated issues have required labels (`type:*`, `priority:*`, `executor:*`) and correct `has-dependencies` state per rule 7 of Board Sync Enforcement. Fix any gaps.
+4. **PR linkage:** For issues transitioned to `status:in-progress` or `status:in-review`, verify any associated open PR body contains `Closes #N` for the addressed issues. Auto-fix if missing by updating the PR body.
 
-**Epic ordering discrepancies:**
-- {list or "None -- all epic Implementation Order sections match sub-issue Dependencies."}
+### Reconciliation Report
 
----
+Output the reconciliation report immediately before the command summary:
 
-*This issue is auto-maintained by hatch3r board commands. Do not close.*
 ```
-
-### Dependency Data Model
-
-`## Dependencies` sections in individual issue bodies are the **single authoritative source** of dependency data. Every issue (epic, sub-issue, standalone) tracks its own blockers in its `## Dependencies` section using two reference types:
-
-- **Hard:** `Blocked by #N` -- this issue cannot start until #N is closed. Used for true producer/consumer relationships (A creates what B consumes) and explicit sequencing requirements.
-- **Soft:** `Recommended after #N` -- this issue can proceed in parallel with #N, but sequential execution is recommended (e.g., shared area overlap, reduced merge conflict risk). Soft dependencies are advisory; they do not block pickup or exclude issues from Implementation Lanes.
-
-When no dependencies exist, the section contains `None`.
-
-`## Implementation Order` sections in epic bodies are a **derived convenience view** -- they visualize the dependency DAG among an epic's sub-issues as numbered levels. Board commands that create or update epics MUST regenerate `## Implementation Order` from the sub-issues' `## Dependencies` sections, not the other way around. When the two diverge, `## Dependencies` wins.
-
-### Lane Computation Algorithm
-
-Used by both `board-refresh` and `board-fill` when generating the Implementation Lanes and Waiting on Dependencies sections. Input: all `status:ready` issues and their dependency data (from `## Dependencies` sections).
-
-1. **Collect** all `status:ready` issues.
-2. **Partition by hard-blocker satisfaction** -- for each collected issue, check all **hard** dependency references (`Blocked by #N`) in its `## Dependencies` section against the full board. An issue is **dependency-waiting** if any hard blocker is still open (regardless of the blocker's status). Soft dependencies (`Recommended after #N`) do not affect this partition. Separate into two sets:
-   - **Available** -- all hard blockers satisfied (closed) or no hard blockers. These proceed to lane computation (step 3+).
-   - **Dependency-waiting** -- one or more hard blockers still open. These are excluded from Implementation Lanes and listed in the **Waiting on Dependencies** section of the overview instead.
-3. **Build the available sub-graph** -- extract only the inter-dependencies among available issues (from parsed `## Dependencies` sections).
-4. **Group by dependency chains** -- issues with sequential dependencies go in the same lane, ordered topologically within the chain.
-5. **Group by area overlap** -- independent issues (no inter-dependencies) that share `area:*` labels go in the same lane. This avoids merge conflicts on the same files when multiple agents work in parallel.
-6. **General lane** -- issues with no dependencies and no area overlap form their own single-issue lanes. If three or more such issues exist, group them into a single "General" lane.
-7. **Name lanes** by the dominant `area:*` label or shared theme of the issues in the lane. Use "General" for the catch-all lane.
-8. **Sort lanes** by the highest-priority issue in each lane (`P0`-lane first, then `P1`, etc.). Break ties by lowest issue number.
-9. **Sort within lanes** by dependency order (blockers before dependents), then by priority, then by issue number.
-
-Example output:
-
+Reconciliation:
+  Board sync:   {N} synced, {M} failed (list failures)
+  Sub-issue links: {N} native, {M} advisory, {K} comment-only
+  Label gaps:   {N} fixed, {M} remaining (list)
+  PR linkage:   {N} verified, {M} missing `Closes` (list)
+  Errors:       {list or "None"}
 ```
-## Implementation Lanes
-
-Issues grouped into independent parallel work streams.
-Different lanes can be worked concurrently; within a lane, follow the listed order.
 
-### Lane 1: API
-
-| Order | # | Title | Type | Pri | Executor | Model |
-|-------|---|-------|------|-----|----------|-------|
-| 1 | #15 | Fix rate limiter | bug | P0 | agent | opus |
-
-### Lane 2: Auth
+---
 
-| Order | # | Title | Type | Pri | Executor | Model |
-|-------|---|-------|------|-----|----------|-------|
-| 1 | #12 | OAuth2 PKCE flow | feature | P1 | agent | opus |
-| 2 | #14 | Token refresh edge cases | bug | P2 | agent | sonnet |
+## Board Overview
 
-### Lane 3: General
+> Full details: see `commands/board/shared-board-overview.md` (model pool, model selection heuristic, dashboard template, dependency data model, lane computation algorithm)
 
-| Order | # | Title | Type | Pri | Executor | Model |
-|-------|---|-------|------|-----|----------|-------|
-| 1 | #18 | Migrate to ESM | refactor | P2 | agent | opus |
-| 2 | #21 | Update CI matrix | infra | P3 | agent | sonnet |
-```
+If `meta:board-overview` is included in `board.labels.meta`, board commands will look for an open issue with that label to use as a live dashboard. This dashboard is auto-maintained and MUST be regenerated at the end of every board command run that mutates issues. For on-demand regeneration without running a full board command, use `hatch3r-board-refresh`.
 
 ---
 
@@ -314,28 +149,23 @@ Different lanes can be worked concurrently; within a lane, follow the listed ord
 
 These directives apply to ALL board commands. They supplement the project's tooling hierarchy.
 
-### GitHub CLI-First
+### Platform CLI-First
+
+All board commands MUST use the platform CLI as the primary interface for operations. CLI tools have lower token cost and faster execution than MCP equivalents.
 
-All board commands MUST use `gh` CLI as the primary interface for GitHub operations. CLI tools have lower token cost and faster execution than MCP equivalents.
+> Platform-specific details: see `commands/board/shared-github.md` (Cross-Cutting Tooling — GitHub CLI-First)
+> Platform-specific details: see `commands/board/shared-azure-devops.md` (Cross-Cutting Tooling — Azure DevOps CLI-First)
+> Platform-specific details: see `commands/board/shared-gitlab.md` (Cross-Cutting Tooling — GitLab CLI-First)
 
-**Prerequisites:** `gh auth login` must be completed, or `GITHUB_TOKEN` environment variable set. For Projects v2: `gh auth refresh -s project`.
+### Batch Operations
 
-| Operation            | Primary (`gh` CLI)                                                                                          | Fallback (MCP)                                      |
-| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| List issues          | `gh issue list`                                                                                             | `list_issues`                                       |
-| Read issue details   | `gh issue view`                                                                                             | `issue_read`                                        |
-| Create/update issues | `gh issue create` / `gh issue edit`                                                                         | `issue_write`                                       |
-| Search issues        | `gh search issues`                                                                                          | `search_issues` / `semantic_issues_search`          |
-| Manage sub-issues    | `sub_issue_write` (MCP only — no CLI equivalent)                                                             | `sub_issue_write`                                   |
-| Add comments         | `gh issue comment`                                                                                          | `add_issue_comment`                                 |
-| Create PRs           | `gh pr create`                                                                                              | `create_pull_request`                               |
-| Read PR details      | `gh pr view`                                                                                                | `pull_request_read`                                 |
-| Manage labels        | `gh label create` / `gh label list`                                                                         | `issue_write` (with labels)                         |
-| Projects v2          | `gh project item-add`, `gh project item-edit`, `gh project item-list`, `gh project field-list`, `gh project view` | `projects_write` / `projects_get` / `projects_list` |
-| CI/Actions           | `gh run list` / `gh run view`                                                                               | N/A                                                 |
-| Releases             | `gh release create`                                                                                         | N/A                                                 |
+All board commands MUST minimize user approval prompts by batching related operations:
 
-Fallback to MCP only for operations the `gh` CLI cannot handle: sub-issue management (`sub_issue_write`).
+1. **Collect before executing.** Gather all planned mutations (issue creation, label changes, sub-issue linking, board sync) into a complete batch before making any API calls.
+2. **Present batch summaries.** Before executing a batch, present the user with a summary table of all operations in the batch (e.g., issues to create, labels to apply, links to establish).
+3. **Single approval per batch.** Request ONE user confirmation for the entire batch. Do not prompt per-item when a batch summary has already been approved.
+4. **Sequential execution after approval.** Once approved, execute all operations in the batch sequentially without additional per-item prompts. Report progress inline (e.g., "Created issue #N... Linked sub-issue #M...") but do not pause for confirmation between operations.
+5. **Batch error handling.** If an individual operation within an approved batch fails, log the failure, continue with remaining operations, and summarize all failures at the end of the batch. Do not re-prompt for each failure.
 
 ### Context7 MCP + Web Research
 
@@ -367,3 +197,22 @@ These apply to all board commands. Follow them to minimize token consumption.
 4. **Limit documentation reads.** Read project documentation selectively -- TOC/headers first, full content only for relevant sections.
 5. **Do NOT read issue templates.** Required structure is provided inline in the command.
 6. **Follow the project's tooling hierarchy** for knowledge augmentation (Context7 MCP, web research).
+
+---
+
+## Run Cache Requirements
+
+All mutating board commands MUST maintain a run cache with the following entries. The cache persists for the duration of the run and feeds into the End-of-Run Reconciliation Procedure.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `created_issues` | `Map<number, {title, type, labels}>` | All issues created during this run |
+| `updated_issues` | `Map<number, {title, changes[]}>` | All issues updated during this run |
+| `sync_results` | `Map<number, {status: success\|failure, method: cli\|mcp\|skipped}>` | Board sync outcome per issue |
+| `link_results` | `Map<number, {parent: number, status: native\|advisory\|comment-only}>` | Sub-issue link outcome per child |
+| `pr_created` | `{number, branch, issues_closed[]}` or `null` | PR created during this run (if any) |
+| `pr_association_map` | `Map<number, number[]>` | PR number → issue numbers it references |
+| `board_item_ids` | `Map<number, string>` | Issue number → board item ID for subsequent updates |
+| `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.

package/commands/hatch3r-bug-plan.md

@@ -2,7 +2,17 @@
 id: hatch3r-bug-plan
 type: command
 description: Plan a complex bug investigation -- spawn parallel researchers, produce diagnosis report with ranked hypotheses and structured todo.md entries for board-fill.
+tags: [core, planning]
 ---
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Research | `hatch3r-researcher` (4 parallel: symptom-trace, root-cause, impact-analysis, regression) | Yes | Yes |
+| 2. Document Generation | `hatch3r-docs-writer` (investigation report, ADRs) | Yes | Yes |
+| 3. Todo Generation | Orchestrator (inline) | No | Yes |
+
 # Bug Plan — Complex Bug Investigation from Symptom to Board-Ready Fix Items
 
 Take a complex or ambiguous bug report and produce a structured investigation report (`docs/investigations/`), architectural decision records (`docs/adr/`) when the fix requires significant design choices, and structured `todo.md` entries (scoped fix items) ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (symptom tracing, root cause investigation, impact assessment, regression research) to diagnose the bug from multiple angles before generating artifacts. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
@@ -66,10 +76,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
+   - `.agents/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 `.agents/learnings/` exists, scan for learnings relevant to the affected area. Match by area and tags against the bug brief.
 4. Present a context summary:
 
 ```
@@ -103,9 +113,12 @@ Spawn one sub-agent per research domain below concurrently, each following the *
 | 2 | `root-cause` | Rank hypotheses by likelihood, identify code smells, analyze dependencies |
 | 3 | `impact-analysis` | Map blast radius, affected flows/modules, data integrity risk, related symptoms |
 | 4 | `regression` | Analyze git history, dependency changes, identify introduction window |
+| 5 | `requirements-elicitation` | Detect ambiguities in the bug report — missing reproduction details, unclear expected behavior, unstated assumptions about environment or data state |
 
 Each sub-agent produces the structured output defined by its mode in the hatch3r-researcher agent specification.
 
+The `requirements-elicitation` sub-agent is particularly valuable for complex bugs because bug reports often contain ambiguous symptoms, unclear expected behavior, or missing environment/data context. Its structured questions help resolve unknowns before the investigation report is generated, reducing the chance of investigating the wrong hypothesis.
+
 Wait for all sub-agents to complete before proceeding.
 
 ---
@@ -389,7 +402,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 `.agents/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/hatch3r-codebase-map.md

@@ -2,11 +2,20 @@
 id: hatch3r-codebase-map
 type: command
 description: Reverse-engineer business and technical project specs from an existing codebase using parallel analyzer sub-agents with dual business/technical scoping
+tags: [planning, brownfield]
 ---
 # Codebase Map — Brownfield Codebase Analysis & Spec Generation
 
 Analyze an existing codebase to reverse-engineer project documentation across **two dimensions**: business domain analysis and technical architecture analysis. Discovers modules, dependencies, conventions, tech stack, technical debt, business logic, domain models, and production readiness using parallel analyzer sub-agents. Outputs structured specs to `docs/specs/business/` (business domain, market context, production readiness) and `docs/specs/technical/` (modules, conventions, stack, debt), plus inferred architectural decision records to `docs/adr/`. Optionally generates a root-level `AGENTS.md` as the project's "README for agents." This command is **purely read-only** until the final write step — all analysis is static (file reading, pattern matching). Works for any language or framework.
 
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Analysis | `hatch3r-researcher` analyzers (6 parallel: module, conventions, tech stack, concerns/debt, business domain, production readiness) | Yes | Yes |
+| 2. Document Generation | `hatch3r-docs-writer` (parallel: technical spec, business spec, ADRs, health report) | Yes | Yes |
+| 3. AGENTS.md | `hatch3r-docs-writer` (AGENTS.md generation/rework) | No | Yes |
+
 ---
 
 ## Shared Context
@@ -69,7 +78,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 `.agents/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:
@@ -978,7 +987,21 @@ Strengths:
 
 ### Step 7: Write All Files
 
-Write all confirmed files to disk.
+Spawn parallel `hatch3r-docs-writer` sub-agents via the Task tool (`subagent_type: "generalPurpose"`) to generate and write the documentation. Each docs-writer receives the merged analyzer output from Steps 3-6 and is responsible for one document category. All docs-writers run in parallel and follow the `hatch3r-docs-writer` agent protocol.
+
+| Docs-Writer | Responsibility | Input |
+|-------------|---------------|-------|
+| Technical Spec Writer | `docs/specs/technical/` (glossary, overview, module specs) | Merged analyzer outputs from Sub-Agents 1-4 |
+| Business Spec Writer | `docs/specs/business/` (glossary, overview, domain specs, production readiness) | Merged analyzer outputs from Sub-Agents 5-6, business context from Step 1 |
+| ADR Writer | `docs/adr/` (all architectural decision records) | Inferred decisions from Step 5 |
+| Health Report Writer | `docs/codebase-health.md` (if user confirmed in Step 6) | All 6 analyzer outputs, cross-reference findings from Step 3 |
+
+Each docs-writer prompt must include:
+- The full merged analyzer output relevant to its document category
+- The confirmed scope, company stage, and business context from Step 1
+- The directory structure and file naming conventions below
+- Instruction to follow the `hatch3r-docs-writer` agent protocol
+- Instruction to create directories as needed before writing files
 
 #### 7a. Create Directories
 
@@ -1080,13 +1103,27 @@ Next steps:
 
 ---
 
-### Step 8: AGENTS.md Generation
+### Step 8 — AGENTS.md (Mandatory)
+
+This step is MANDATORY, not optional.
 
-**ASK:** "Generate or update the root-level `AGENTS.md` with a project summary derived from the specs just created? This file serves as the 'README for agents' — consumed by OpenCode, Windsurf, and other AI coding tools so they understand your project's business context, architecture, and conventions from the first interaction.
+**If `AGENTS.md` exists at project root:**
 
-(a) Yes — generate it, (b) No — skip, (c) Let me review the content first."
+**ASK:** "Your existing AGENTS.md may be outdated after generating new documentation. Would you like to rework it based on the new specs?"
 
-If yes or review-first: generate `AGENTS.md` at the project root containing:
+- If **yes**: spawn a `hatch3r-docs-writer` sub-agent via the Task tool (`subagent_type: "generalPurpose"`) to regenerate AGENTS.md incorporating the newly generated specs, architecture overview, module map, and conventions. The docs-writer follows the `hatch3r-docs-writer` agent protocol.
+- If **no**: keep existing AGENTS.md unchanged. Log that the user declined the update.
+
+**If no `AGENTS.md` exists:**
+
+Generate AGENTS.md — there is no opt-out. Spawn a `hatch3r-docs-writer` sub-agent via the Task tool (`subagent_type: "generalPurpose"`) to create AGENTS.md following the `hatch3r-docs-writer` agent protocol. The docs-writer receives the full merged analyzer output and generates AGENTS.md with:
+- Project purpose and business context
+- Tech stack and architecture overview
+- Module map with responsibilities
+- Development conventions and patterns
+- Key specs and ADR references
+
+The generated `AGENTS.md` should follow this structure:
 
 ```markdown
 # {Project Name} — Agent Instructions
@@ -1137,10 +1174,6 @@ If yes or review-first: generate `AGENTS.md` at the project root containing:
 - Health report: `docs/codebase-health.md`
 ```
 
-If the user chose "review first," present the content and **ASK** for confirmation before writing.
-
-If `AGENTS.md` already exists, **ASK** before overwriting: "Root `AGENTS.md` already exists. (a) Replace entirely, (b) Append hatch3r section, (c) Skip."
-
 ---
 
 ### Step 9: Cross-Command Handoff

package/commands/hatch3r-command-customize.md

@@ -2,7 +2,13 @@
 id: hatch3r-command-customize
 type: command
 description: Configure per-command customization including description overrides, enable/disable control, and project-specific markdown instructions
+tags: [customize]
 ---
+
+## Agent Pipeline
+
+This command runs as a single orchestrator without sub-agent delegation. Customization file management is performed inline.
+
 # Command Customization — Per-Command Configuration
 
 Customize individual command behavior for project-specific needs via `.hatch3r/commands/` configuration files. Supports structured YAML overrides and free-form markdown instruction injection, all propagated to every adapter output on sync.

package/commands/hatch3r-context-health.md

@@ -2,7 +2,12 @@
 id: hatch3r-context-health
 type: command
 description: Monitor conversation context health, detect degradation, and auto-suggest fresh context or sub-agent delegation
+tags: [maintenance]
 ---
+## Agent Pipeline
+
+This command monitors context health and recommends delegation. It does not spawn sub-agents directly — it recommends when the orchestrator should delegate to sub-agents due to context degradation.
+
 # Context Health — Conversation Context Monitoring
 
 Monitor and maintain healthy conversation context during long-running agent sessions. Detects context degradation before it impacts output quality and recommends corrective actions.

package/commands/hatch3r-cost-tracking.md

@@ -2,7 +2,12 @@
 id: hatch3r-cost-tracking
 type: command
 description: Track and report token usage and estimated costs across agent workflows and board operations
+tags: [maintenance]
 ---
+## Agent Pipeline
+
+This command tracks token usage and costs. It does not spawn sub-agents directly — it monitors sub-agent usage across the session.
+
 # Cost Tracking — Token Usage and Cost Reporting
 
 Track token consumption and estimated costs across sub-agent workflows, board operations, and development sessions. Provides visibility into AI usage patterns and enforces cost guardrails.