hatch3r 1.0.0 → 1.2.0

package/commands/hatch3r-board-fill.md

@@ -1,11 +1,23 @@
 ---
 id: hatch3r-board-fill
 type: command
-description: Create GitHub epics and issues from todo.md, reorganize the board with dependency analysis, readiness assessment, and implementation ordering.
+description: Create epics and issues/work items from todo.md, reorganize the board with dependency analysis, readiness assessment, and implementation ordering. Supports GitHub, Azure DevOps, and GitLab.
+tags: [board, team]
 ---
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Context Gathering | Explore sub-agents (codebase exploration) | Yes | When application context needed |
+| 2. Issue Creation | Orchestrator (inline, GitHub MCP) | No | Yes |
+| 3. Board Sync | Orchestrator (Projects v2 sync) | No | Yes |
+
+All issue operations MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared`.
+
 # Board Fill -- Create Epics & Issues from todo.md + Board Reorganization
 
-Create GitHub epics (with sub-issues) or standalone issues from items in `todo.md`, using the GitHub MCP tools against **{owner}/{repo}** (read from `/.agents/hatch.json` board config). Before creating anything, board-fill **triages each item through interactive questioning** to extract scope, intent, unknowns, and acceptance criteria from the user -- ensuring issues are genuinely ready for implementation, not just structurally complete. On every run, board-fill also performs a **full board reorganization**: grouping standalone issues into epics, decomposing oversized items, analyzing dependencies, setting implementation order, identifying parallel work, and marking issues as `status:ready` when all readiness criteria (structural + substantive) are met. AI proposes groupings, dependencies, and ordering; user confirms before anything is created or updated. Duplicate topics are detected and skipped.
+Create epics (with sub-issues) or standalone issues/work items from items in `todo.md`, using the platform's CLI and MCP tools against **{owner}/{repo}** (read from `.agents/hatch.json` board config). The `platform` field determines whether to use GitHub Issues, Azure DevOps Work Items, or GitLab Issues. Before creating anything, board-fill **triages each item through interactive questioning** to extract scope, intent, unknowns, and acceptance criteria from the user -- ensuring issues are genuinely ready for implementation, not just structurally complete. On every run, board-fill also performs a **full board reorganization**: grouping standalone issues into epics, decomposing oversized items, analyzing dependencies, setting implementation order, identifying parallel work, and marking issues as `status:ready` when all readiness criteria (structural + substantive) are met. AI proposes groupings, dependencies, and ordering; user confirms before anything is created or updated. Duplicate topics are detected and skipped.
 
 ---
 
@@ -15,15 +27,18 @@ hatch3r's board commands operate as the **implementation orchestration layer** a
 
 - **board-init** sets up the project management structure that agentic workflows operate within
 - **board-fill** creates the work items that agentic workflows can triage and label
+- **board-groom** refines existing work items as priorities, scope, and dependencies evolve over time
 - **board-pickup** orchestrates the implementation -> review -> merge pipeline that goes beyond what generic agentic workflows provide
 
+For ongoing refinement of existing board items (re-prioritization, reclassification, re-scoping, archiving stale items, dependency cleanup), use `hatch3r-board-groom` instead of re-running board-fill.
+
 GitHub Agentic Workflows and hatch3r are complementary: use agentic workflows for continuous background automation, use hatch3r board commands for structured delivery orchestration.
 
 ---
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
+**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.
 
 ## Token-Saving Directives
 
@@ -43,14 +58,37 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 **ASK:** "Here are the items I found in todo.md. Which items should I process? (all / specific numbers / exclude specific numbers)"
 
+#### 1a. Product Vision Input (Optional)
+
+1. Check if a product vision document exists at `.agents/product-vision.md`.
+2. If found, read and cache the vision document for use in Steps 2.5 and 4.
+3. If not found, check whether the user provided a vision statement inline with the board-fill invocation (e.g., as a quoted string or file path argument).
+4. If a vision is available from either source, note: "Product vision loaded — will use for triage context and issue scoping."
+5. If no vision is available, proceed without it. Do not prompt the user for one.
+
 ---
 
 ### Step 1.5: Full Board Scan
 
 Scan the entire board to build an inventory of all existing work. This scan feeds into all subsequent steps. **Cache everything retrieved here.**
 
-1. Fetch ALL open issues using `list_issues` with `owner: {board.owner}`, `repo: {board.repo}`, `state: OPEN`. Paginate to retrieve every issue. **Exclude** any issue with the `meta:board-overview` label from all subsequent processing.
-2. For each issue, fetch labels (`issue_read` with `method: get_labels`) and check for sub-issues (`issue_read` with `method: get_sub_issues`).
+1. **Platform-specific: Fetch all open issues/work items**
+
+   **If platform is `github`:**
+   - Fetch ALL open issues using `gh issue list -R {owner}/{repo} --state open --limit 500 --json number,title,labels,state,createdAt,updatedAt,body` (fall back to `list_issues` MCP with `owner: {board.owner}`, `repo: {board.repo}`, `state: OPEN`). Paginate to retrieve every issue.
+
+   **If platform is `azure-devops`:**
+   - Fetch ALL active work items: `az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT [System.Id], [System.Title], [System.State], [System.Tags], [System.CreatedDate], [System.ChangedDate] FROM WorkItems WHERE [System.State] <> 'Closed' AND [System.State] <> 'Removed'"` (fall back to `list_work_items` MCP).
+
+   **If platform is `gitlab`:**
+   - Fetch ALL open issues: `glab issue list -R {namespace}/{project} --state opened --per-page 100` (paginate to retrieve all).
+
+   **Exclude** any issue/work item with the `meta:board-overview` label/tag from all subsequent processing.
+
+2. For each issue, fetch labels and check for sub-issues:
+   - **GitHub:** `issue_read` with `method: get_labels` and `method: get_sub_issues`.
+   - **Azure DevOps:** Tags from `System.Tags` field; parent-child relations via `az boards work-item relation list --id N`.
+   - **GitLab:** Labels from issue data; related issues via `glab api projects/{project_id}/issues/{N}/links`.
 3. Categorize every open issue:
    - **Epic** -- has sub-issues
    - **Sub-issue** -- is a child of an epic
@@ -76,7 +114,10 @@ Board Health:
 
 For each selected todo item:
 
-1. `search_issues` with keywords derived from the item.
+1. **Platform-specific: Search for existing matches**
+   - **GitHub:** `gh search issues -R {owner}/{repo} "{keywords}"` (fall back to `search_issues` MCP).
+   - **Azure DevOps:** `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] CONTAINS '{keywords}'"` (fall back to `search_work_items` MCP).
+   - **GitLab:** `glab issue list -R {namespace}/{project} --search "{keywords}"`.
 2. Compare against cached board inventory semantically.
 3. Classify: **Duplicate** / **Partial overlap** / **No match**.
 
@@ -96,6 +137,17 @@ Compare existing open issues pairwise for semantic duplicates. Present any findi
 
 Before classifying items, extract the information needed to produce genuinely ready issues. Todo items are often terse one-liners; this step surfaces the user's actual intent, scope, and constraints that the AI cannot infer.
 
+#### Vision-Aware Triage (Conditional)
+
+If a product vision was loaded in Step 1a, apply these modifications to the triage process:
+
+1. **Derive context from the vision first.** For each triage dimension (Scope, Value, Unknowns, Size, Stakeholder), check whether the product vision document provides clear answers. Extract relevant goals, user segments, success metrics, and stated priorities from the vision.
+2. **Reduce questioning.** Only ask triage questions for dimensions that the vision does not clearly address. If the vision states the target user, value proposition, and scope boundaries for an item's domain, mark those dimensions as "Clear (from vision)" and skip the corresponding questions.
+3. **Reference vision goals explicitly.** When classifying items or asking remaining triage questions, cite the specific vision goal or statement that informs the classification (e.g., "Per the product vision goal 'Zero-config onboarding', this item aligns with...").
+4. **Greenfield streamlining.** For greenfield projects where the vision covers all major work areas, batch all items into a single triage pass. Present the vision-derived context for each item and ask the user to confirm or override in one prompt rather than per-item questioning.
+
+If no product vision is available, proceed with the full triage process below.
+
 #### 2.5a. Assess Clarity
 
 For each remaining item, score its clarity across six dimensions:
@@ -196,7 +248,7 @@ If the user flagged unresolved unknowns or research needs in triage, consider wh
 
 **Priority:** `priority:p0` (critical/security) / `priority:p1` (broken, no workaround) / `priority:p2` (degraded, default) / `priority:p3` (cosmetic, nice-to-have). Use the user's stated urgency and impact from triage (Value/Why answers) to override keyword defaults. Default `p2` only when both the todo text AND triage answers are ambiguous; security defaults to `p1`+.
 
-**Area:** Read area labels from `board.areas` in `/.agents/hatch.json`. If the list is empty, infer areas from the repository's directory structure. Assign all relevant area labels.
+**Area:** Read area labels from `board.areas` in `.agents/hatch.json`. If the list is empty, infer areas from the repository's directory structure. Assign all relevant area labels.
 
 **Risk:** `risk:low` (isolated, easy rollback) / `risk:med` (shared modules, moderate scope) / `risk:high` (architectural, security-critical). Incorporate triage context: if the user surfaced unknowns, external dependencies, or broad blast radius, escalate risk accordingly. Items with unresolved spikes default to `risk:med`+.
 
@@ -220,7 +272,7 @@ Use explore subagents or direct file reads to understand the current state of so
 
 #### 4b.5. Consult Project Learnings
 
-1. If `/.agents/learnings/` exists, scan for learnings relevant to the areas touched by the todo items.
+1. If `.agents/learnings/` exists, scan for learnings relevant to the areas touched by the todo items.
 2. Match by `area` and `tags` in learning frontmatter against the area labels assigned in Step 3.
 3. Surface relevant learnings in the Context Summary output:
    - **Pitfalls** for areas being touched (highest priority -- include specific warnings)
@@ -236,9 +288,17 @@ Follow the project's tooling hierarchy for external knowledge augmentation (Cont
 
 Skip if all items are purely internal (no external library involvement).
 
+#### 4d. Product Vision Context (When Available)
+
+If a product vision was loaded in Step 1a:
+
+1. Include the product vision as **primary context** for issue scoping. Vision-stated goals, success metrics, target users, and scope boundaries take precedence over inferred context when drafting issue bodies and acceptance criteria.
+2. Map each todo item to the specific vision goal(s) it supports. Include this mapping in the Context Summary output so that Steps 5 and 6 can reference it.
+3. Flag any todo items that do not clearly map to a stated vision goal — these may represent scope creep or infrastructure work that supports the vision indirectly.
+
 #### Output
 
-Present a brief **Context Summary**: key constraints from documentation, current implementation state, external findings (if any).
+Present a brief **Context Summary**: key constraints from documentation, current implementation state, external findings (if any), and product vision alignment (if vision is available).
 
 ---
 
@@ -428,25 +488,87 @@ After the table, present the ASK. Only render full issue bodies for the specific
 
 ### Step 7: Create & Update Issues via GitHub MCP
 
+All issue operations in this command MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared` and the **Batch Operations** directive. Every created/updated issue must be synced to the board immediately, with status, priority, and area fields populated.
+
+#### 7-pre. Collect Batch Plan & Approve
+
+Before executing any GitHub API calls, collect ALL planned operations into a single batch and get one user approval:
+
+1. **Collect all creation operations** into a table, ordered by dependency (epics first, then sub-issues, then standalone):
+
+```
+| # | Title | Type | Labels | Epic Assignment | Status |
+|---|-------|------|--------|-----------------|--------|
+| 1 | {epic title} | Epic | {labels} | — | {status} |
+| 2 | {sub-issue title} | Sub-issue | {labels} | → Epic #1 | {status} |
+| 3 | {standalone title} | Standalone | {labels} | — | {status} |
+```
+
+2. **Collect all update operations** for existing issues (from Steps 5, 5.5, 5.6) into a second table:
+
+```
+| Issue # | Title | Updates |
+|---------|-------|---------|
+| #{N} | {title} | {add dependencies, regroup under epic, mark ready, etc.} |
+```
+
+3. **Collect all post-creation operations** (sub-issue linking, Projects v2 board sync) into a count summary:
+
+```
+Post-creation operations: {X} sub-issue links, {Y} board sync calls, {Z} status updates
+```
+
+**ASK:** "Here is the full batch of GitHub operations. {N} issues to create, {M} issues to update, {P} post-creation operations. Confirm to execute all, or adjust?"
+
+After the user confirms, execute all operations in 7a–7b below **without additional per-item prompts**. Report progress inline (e.g., "Created #N... Linked sub-issue #M...").
+
 #### 7a. Create New Issues
 
-Execute in dependency order (parents before children):
+Execute in dependency order (parents before children). Do not prompt between operations — the batch was approved in 7-pre.
+
+**Phase 1 — Create all issues/work items:**
+
+**Platform-specific: Issue creation**
 
-1. **Epics first:** `issue_write` with `method: create`, `owner: {board.owner}`, `repo: {board.repo}`. Include `## Dependencies` section and `has-dependencies` label. Record the returned `number` and internal numeric `id` field.
-2. **Sub-issues:** Create each, then link via `sub_issue_write` with `method: add` using the parent `issue_number` and child's internal numeric `id` (NOT the issue number or node_id).
-3. **Standalone issues:** Create with `## Dependencies` and `has-dependencies`.
-4. **Add to project board + sync initial status:** For each created issue, run the full **Projects v2 Sync Procedure** from `hatch3r-board-shared` (gh CLI primary). This adds the item to the board, captures its item ID from the response, and sets the Projects v2 status to match the issue's `status:*` label (typically `status:ready` or `status:triage`). Use the label → option ID mapping from the sync procedure.
+**If platform is `github`:**
+1. **Epics first:** `gh issue create -R {owner}/{repo} --title "..." --body "..." --label "..."` (fall back to `issue_write` MCP with `method: create`). Include `## Dependencies` section and `has-dependencies` label (per rule 7 of Board Sync Enforcement). Record the returned `number` and internal numeric `id` field.
+2. **Sub-issues:** Create each. Include `## Dependencies` section. Add `has-dependencies` label if the sub-issue has any dependency references (per rule 7 of Board Sync Enforcement). Record the returned `number` and internal numeric `id` field.
+3. **Standalone issues:** Create with `## Dependencies` and `has-dependencies` (when dependencies exist, per rule 7).
+
+**If platform is `azure-devops`:**
+1. **Epics first:** `az boards work-item create --org https://dev.azure.com/{namespace} --project {project} --type "Epic" --title "..." --description "..." --fields "System.Tags=has-dependencies"` (fall back to `create_work_item` MCP). Record the returned work item `id`.
+2. **Sub-issues:** Create as User Stories or Tasks: `az boards work-item create --type "User Story" --title "..." --description "..."`. Record the returned `id`.
+3. **Standalone issues:** Create as User Stories with `## Dependencies` and `has-dependencies` tag.
+
+**If platform is `gitlab`:**
+1. **Epics first:** `glab issue create -R {namespace}/{project} --title "..." --description "..." --label "has-dependencies"`. Record the returned issue number.
+2. **Sub-issues:** Create each. Record the returned issue number.
+3. **Standalone issues:** Create with `## Dependencies` and `has-dependencies` label.
+
+**Phase 2 — Link sub-issues** (after all issues exist):
+
+For each sub-issue, follow the **Sub-Issue Linking Procedure** from `hatch3r-board-shared`. Use the three-tier fallback chain (MCP native → CLI body-reference → comment trace) and record link status per child in the run cache under `link_results`.
+
+**Phase 3 — Sync to board** (after all issues and links are created):
+
+For each created issue, run the full **Board Sync Procedure** from `hatch3r-board-shared`. This adds the item to the board and sets the status to match the issue's `status:*` label (typically `status:ready` or `status:triage`).
 
 #### 7b. Update Existing Issues (Board Reorganization)
 
 For issues needing updates (from Steps 5, 5.5, 5.6):
 
-1. **Add/update `## Dependencies`:** Read current body, append/replace section, update via `issue_write`. Add `has-dependencies` label.
+1. **Add/update `## Dependencies`:** Read current body, append/replace section, update via platform CLI or MCP. Add `has-dependencies` label/tag.
+   - **GitHub:** `gh issue edit N --body "..."` or `issue_write` MCP.
+   - **Azure DevOps:** `az boards work-item update --id N --description "..."`.
+   - **GitLab:** `glab issue update N --description "..."`.
 2. **Regenerate `## Implementation Order`** (epics only): Derive from the sub-issues' `## Dependencies` DAG (see Dependency Data Model in `hatch3r-board-shared`). Replace the existing section entirely -- do not manually edit it.
-3. **Apply epic regrouping:** Link standalones to epics via `sub_issue_write`. Update epic body.
+3. **Apply epic regrouping:** Link standalones to epics using the **Sub-Issue Linking Procedure** from `hatch3r-board-shared`. Update epic body with the new sub-issue reference.
 4. **Mark `status:ready`:** Remove `status:triage`, add `status:ready`. Do not downgrade existing statuses.
-5. **Add missing labels** if user opted to fill gaps.
-6. **Sync Projects v2 Status:** For each issue whose status label was set or changed in this run (including issues newly marked `status:ready` in step 4 above), run the full **Projects v2 Sync Procedure** from `hatch3r-board-shared` (gh CLI primary). This ensures the Projects v2 board column matches the label. Skip issues already synced in Step 7a.4.
+   - **GitHub:** `gh issue edit N --remove-label "status:triage" --add-label "status:ready"`.
+   - **Azure DevOps:** `az boards work-item update --id N --state "Active" --fields "System.Tags=+status:ready;-status:triage"`.
+   - **GitLab:** `glab issue update N --unlabel "status::triage" --label "status::ready"`.
+5. **Add missing labels/tags** if user opted to fill gaps.
+6. **Sync Board Status:** For each issue whose status was set or changed in this run, run the full **Board Sync Procedure** from `hatch3r-board-shared`. This ensures the board view matches the label. Skip issues already synced in Phase 3.
 
 #### 7c. Present Summary
 
@@ -467,15 +589,29 @@ Board Summary: N created, M updated, X marked ready, Y still triage, Z parallel
 **This step is mandatory. Do not skip.**
 
 1. Search the cached board inventory for an open issue labeled `meta:board-overview`.
-2. Compute Implementation Lanes using the **Lane Computation Algorithm** from `hatch3r-board-shared`. Use the cached dependency DAG from Step 5.5 as input.
+2. Compute Implementation Lanes using the **Lane Computation Algorithm** (steps 1-12) from `hatch3r-board-shared`. Use the cached dependency DAG from Step 5.5 as input. This includes inter-lane dependency computation, lane phasing, and the Lane Dependency Map.
 3. Assign models to all open issues using the **Model Selection Heuristic (Quality-First)** from `hatch3r-board-shared`.
-4. **If found:** Regenerate the dashboard body using the **Board Overview Issue Format** template from `hatch3r-board-shared`, populated with cached board data updated with mutations from Step 7. Update the issue body via `gh issue edit` (fall back to `issue_write` MCP).
-5. **If not found:** Create a new board overview issue using the **Board Overview Issue Format** template from `hatch3r-board-shared`, populated with current board data (all issues from this run plus existing board state). Label it `meta:board-overview` and add it to the project board.
+4. **If found:** Regenerate the dashboard body using the **Board Overview Issue Format** template from `hatch3r-board-shared`, populated with cached board data updated with mutations from Step 7. Update the issue body using platform CLI (fall back to MCP):
+   - **GitHub:** `gh issue edit {N} --body "..."` (fall back to `issue_write` MCP).
+   - **Azure DevOps:** `az boards work-item update --id {N} --description "..."`.
+   - **GitLab:** `glab issue update {N} --description "..."`.
+5. **If not found:** Create a new board overview issue using the **Board Overview Issue Format** template from `hatch3r-board-shared`, populated with current board data. Label/tag it `meta:board-overview` and sync to the board:
+   - **GitHub:** `gh issue create` or `issue_write` MCP, then add to project board.
+   - **Azure DevOps:** `az boards work-item create` with `meta:board-overview` tag.
+   - **GitLab:** `glab issue create` with `meta:board-overview` label.
 
 Do NOT re-fetch all issues; use cached data.
 
 ---
 
+### Step 7.8: End-of-Run Reconciliation
+
+**This step is mandatory. Do not skip.**
+
+Run the **End-of-Run Reconciliation Procedure** from `hatch3r-board-shared`. This verifies board sync, sub-issue links, label consistency, and PR linkage for all issues created or updated during this run. Output the reconciliation report before proceeding to Step 8.
+
+---
+
 ### Step 8: Cleanup
 
 **ASK:** "All issues created. Should I remove processed items from `todo.md`? (yes / no / only created ones)"
@@ -486,16 +622,16 @@ If yes, edit `todo.md` to remove lines for created issues. Preserve skipped/excl
 
 ## Error Handling
 
-- `search_issues` failure: retry once, then warn and proceed without dedup.
-- `issue_write` failure: report, skip that issue, continue. Summarize failures at end.
-- `sub_issue_write` failure: report but do not delete the created issue.
+- **Search failure** (GitHub `search_issues` / Azure DevOps `az boards query` / GitLab `glab issue list --search`): retry once, then warn and proceed without dedup.
+- **Issue/work item creation failure** (GitHub `issue_write` / Azure DevOps `az boards work-item create` / GitLab `glab issue create`): report, skip that issue, continue. Summarize failures at end.
+- **Sub-issue linking failure** (GitHub `sub_issue_write` / Azure DevOps relation add / GitLab issue link): report but do not delete the created issue.
 - Never create an issue without user confirmation in Step 6.
 
 ## Guardrails
 
 - **Never create issues for topics already covered** without explicit user approval.
 - **Never skip ASK checkpoints.**
-- **Use correct labels** from the label taxonomy defined in `/.agents/hatch.json` (type, priority, area, risk, executor, status, has-dependencies, meta labels).
+- **Use correct labels** from the label taxonomy defined in `.agents/hatch.json` (type, priority, area, risk, executor, status, has-dependencies, meta labels).
 - **Keep issue bodies concise.** Acceptance criteria must be grounded in user-stated requirements from triage, not fabricated from the todo text alone.
 - **No dependency cycles.** Flag and resolve before proceeding.
 - **Never downgrade issue status.** Only upgrade `status:triage` → `status:ready`.