hatch3r 1.1.0 → 1.3.0

package/commands/board/pickup-gitlab.md

@@ -0,0 +1,81 @@
+---
+id: hatch3r-board-pickup-gitlab
+type: command
+description: GitLab-specific platform procedures for board-pickup. Covers glab CLI commands for issue listing, status updates, collision detection, MR creation, and label transitions.
+tags: [board, team, gitlab]
+---
+# Board Pickup — GitLab Platform Details
+
+Platform-specific procedures for GitLab. Referenced from `hatch3r-board-pickup`.
+
+---
+
+## Step 1a: Fetch and Parse Board State — GitLab
+
+**Fetch all open issues:**
+1. `glab issue list -R {namespace}/{project} --state opened --per-page 100`. Paginate to get all.
+
+**Check sub-issues per issue:**
+- `glab api projects/{project_id}/issues/{N}/links`.
+
+**Fetch labels:**
+- Extract from issue data.
+
+---
+
+## Step 3: Collision Detection — GitLab
+
+**In-progress issues:**
+- `glab issue list -R {namespace}/{project} --label "status::in-progress" --state opened`.
+
+**Open MRs:**
+- `glab mr list -R {namespace}/{project} --state opened`.
+
+---
+
+## Step 4: Update Issue Status — GitLab
+
+**Update status labels:**
+- `glab issue update N --unlabel "status::ready" --label "status::in-progress"`.
+
+**Sync board status:**
+Follow the **GitLab Board Label-Based Sync** from `commands/board/shared-gitlab.md` for each issue marked `status:in-progress` (including parent epic). Set label to `status::in-progress`.
+
+---
+
+## Step 8: Create Merge Request — GitLab
+
+**MR template:** Check `.gitlab/merge_request_templates/`.
+
+**Create MR:**
+`glab mr create -R {namespace}/{project} --source-branch {branch} --target-branch {base} --title "..." --description "..."`. Use `Closes #N` syntax in the description for auto-close on merge.
+
+`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+
+**Link MR to epic:**
+Reference the epic issue number in the MR description. GitLab auto-links MRs to issues mentioned with `Closes #N`.
+
+**Verify MR body linkage:**
+Read back the created MR description and verify it contains `Closes #N` for every issue addressed. If any reference is missing:
+`glab mr update {mr_number} -R {namespace}/{project} --description "..."`.
+
+---
+
+## Step 8a: Post-MR Label Transition — GitLab
+
+**Transition labels to `status:in-review`:**
+`glab issue update N --unlabel "status::in-progress" --label "status::in-review"`.
+
+**Sync Board:**
+Follow the full **GitLab Board Label-Based Sync** from `commands/board/shared-gitlab.md` for:
+- Each `Closes #N` issue: Set label to `status::in-review`.
+- Parent epic (all sub-issues addressed): Set label to `status::in-review`.
+- Parent epic (partial): Verify label is `status::in-progress`; set it if not.
+
+---
+
+## Error Handling — GitLab
+
+- **Issue listing failure** (`glab issue list`): retry once, then ask user for issue number.
+- **Issue update failure** (`glab issue update`): warn and continue (labels not blocking).
+- **MR creation failure** (`glab mr create`): present error and manual instructions.

package/commands/board/pickup-modes.md

@@ -0,0 +1,143 @@
+---
+id: hatch3r-board-pickup-modes
+type: command
+description: Auto-advance mode, error handling, and guardrails for board-pickup. Covers --auto/--unattended operation, safety guardrails, and specification generation.
+tags: [board, team]
+---
+# Board Pickup — Modes, Guardrails, and Error Handling
+
+Supplementary protocols for `hatch3r-board-pickup`. Referenced from the core command file.
+
+---
+
+## Specification Generation (Step 3b — Optional)
+
+When the picked issue lacks a detailed specification, generate one before implementation:
+
+### When to Generate
+
+- Issue body has acceptance criteria but no implementation spec
+- Issue is type `feature` or `refactor` (bugs typically don't need specs)
+- Issue has complexity label `complex` or `epic`
+
+### Specification Generation Process
+
+1. **Analyze the issue**: Parse title, body, labels, linked issues, and parent epic context.
+2. **Research context**: Read relevant project documentation, existing code in the affected area, and related specs.
+3. **Generate specification** with the following structure:
+
+```
+## Specification: #{issue_number} — {title}
+
+### Problem Statement
+{what needs to change and why}
+
+### Proposed Solution
+{high-level approach}
+
+### Technical Design
+- **Data model changes**: {new/modified schemas}
+- **API changes**: {new/modified endpoints}
+- **UI changes**: {new/modified components}
+- **Dependencies**: {new libraries or services}
+
+### Implementation Plan
+1. {ordered steps}
+
+### Test Strategy
+- Unit: {what to unit test}
+- Integration: {what to integration test}
+- E2E: {what to E2E test}
+
+### Risks & Mitigations
+- {risk}: {mitigation}
+
+### Out of Scope
+- {explicitly excluded items}
+```
+
+4. **ASK:** Present the generated specification to the user for validation before proceeding to implementation.
+5. **Store**: Save the validated spec as a comment on the issue for traceability.
+
+### Skip Specification
+
+Skip this step when:
+- Issue already has a linked spec document
+- Issue is a simple bug fix with clear reproduction steps
+- Issue has `skip-spec` label
+- Auto-advance mode is active (see below)
+
+---
+
+## Auto-Advance Mode
+
+When invoked with `--auto` or `--unattended`, the board pickup operates with reduced human checkpoints for sustained autonomous operation.
+
+### Behavior Changes in Auto Mode
+
+| Checkpoint | Normal Mode | Auto Mode |
+|-----------|-------------|-----------|
+| Issue selection | ASK user to confirm | Auto-select highest priority ready issue(s); **auto-batch** independent issues up to `--max-batch` (default 4) |
+| Specification generation | ASK user to validate | Auto-generate and attach, skip validation |
+| Implementation plan | ASK user to review | Auto-proceed with plan |
+| PR creation | ASK user to confirm | Auto-create PR |
+| Review feedback | Wait for human review | Proceed to next issue/batch |
+
+In auto mode, batch pickup is the default when multiple independent issues are available. The system auto-selects up to `--max-batch` independent issues and processes them in parallel via Step 6c.
+
+### Safety Guardrails (Always Active)
+
+These checkpoints are NEVER skipped, even in auto mode:
+- **Destructive operations**: Database migrations, file deletions, security rule changes always require confirmation
+- **Breaking changes**: API contract changes, public interface modifications always require confirmation
+- **Cost thresholds**: Stop if estimated token cost exceeds configured limit (default: $10 per issue)
+- **Error threshold**: Stop after 3 consecutive implementation failures
+- **Scope limits**: Maximum 10 issues per auto session (configurable)
+
+### Activation
+
+```
+/hatch3r board-pickup --auto
+/hatch3r board-pickup --auto --max-issues=5 --cost-limit=20
+/hatch3r board-pickup --auto --max-batch=4
+```
+
+### Session Report
+
+At the end of an auto session, generate a summary:
+- Issues completed: {count}
+- Issues batched: {count per batch}
+- PRs created: {list}
+- Issues blocked: {list with reasons}
+- Total estimated cost: {tokens/cost}
+- Learnings captured: {count}
+
+---
+
+## Error Handling
+
+> Platform-specific details: see `commands/board/pickup-github.md` (Error Handling)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Error Handling)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Error Handling)
+
+- **Issue listing/search failure:** retry once, then ask user for issue number.
+- **Issue update failure:** warn and continue (labels not blocking).
+- **Quality verification failure:** fix before creating PR/MR.
+- **PR/MR creation failure:** present error and manual instructions.
+
+---
+
+## Guardrails
+
+- **Never skip collision check** (Step 3).
+- **Never skip ASK checkpoints.**
+- **Always work on a dedicated branch.** Never commit to the default branch.
+- **Stay within scope.** Note related work but do not implement it.
+- **One PR per pickup session.** A single issue, epic, or batch produces one PR. Split large epics into multiple PRs.
+- **One sub-agent per issue.** Every issue MUST be delegated to its own `hatch3r-implementer` sub-agent -- never implement multiple issues inline. This applies to standalone issues (6a), epic sub-issues (6b), and batch issues (6c).
+- **Maximize parallelism.** Launch as many independent sub-agents concurrently as the platform supports. Only serialize when dependency order or file conflicts require it.
+- **Respect the issue-type skill** as source of truth for implementation.
+- **Respect dependency and implementation order.** Warn and suggest blockers.
+- **Prefer `status:ready` issues.** Warn if selecting non-ready.
+- **Board Overview is auto-maintained.** Exclude from all analysis.
+- **Always create a PR.** Every board-pickup session MUST end with a PR (Steps 7a-8) unless explicitly abandoned by the user or the epic is an audit that produces no code changes. If quality checks fail in Step 7, fix the issues and re-run Step 7 -- do not exit without completing Steps 7a, 8, 8a, and 9.

package/commands/board/pickup-post-impl.md

@@ -0,0 +1,120 @@
+---
+id: hatch3r-board-pickup-post-impl
+type: command
+description: Post-implementation steps for board-pickup (Steps 7-10). Covers quality verification, commit/push, PR/MR creation, label transitions, board sync, dashboard refresh, reconciliation, and learnings capture.
+tags: [board, team]
+---
+# Board Pickup — Post-Implementation Steps (7-10)
+
+Post-implementation workflow for `hatch3r-board-pickup`. Referenced from the core command file.
+
+---
+
+## Step 7: Quality Verification
+
+Run the project's quality checks (linting, type checking, tests). Refer to the project's `AGENTS.md`, `README.md`, or `package.json` scripts for the appropriate commands.
+
+Verify: all AC met, tests passing, no lint errors, dead code removed, project-specific invariants respected.
+
+---
+
+## Step 7a: Commit & Push
+
+Stage, commit, and push all changes so the branch exists on the remote before PR creation.
+
+**Single issue or epic:**
+
+```bash
+git add -A
+git commit -m "{type}: {short description} (#{issue})"
+git push -u origin {branch-name}
+```
+
+- Use the branch type prefix (`feat`, `fix`, `refactor`, `qa`) matching the branch name.
+- Reference the issue number in the commit message.
+- If `git push` fails (e.g., branch already exists on remote), use `git push` without `-u`.
+
+**Batch mode:** Create one commit covering all issues in the batch.
+
+```bash
+git add -A
+git commit -m "batch: {short description} (#N, #M, #K)"
+git push -u origin {branch-name}
+```
+
+- List all issue numbers in the commit message.
+- If all issues share a type, use that type prefix instead of `batch`.
+
+---
+
+## Step 8: Create Pull Request / Merge Request
+
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 8)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 8)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 8)
+
+Follow the project's PR/MR creation skill or conventions:
+
+1. **Title:** `{type}: {short description} (#issue)` — for batch mode: `batch: {short description} (#N, #M, #K)`.
+2. **Determine epic link type:** If working on an epic's sub-issues, check whether ALL sub-issues of the parent epic are addressed by this PR/MR (listed as `Closes #N`) or are already closed. If yes → use `Closes #<epic-number>` so the epic auto-closes on merge. If some sub-issues remain open and unaddressed → use `Relates to #<epic-number>`.
+3. **Body:** Use the repository's PR/MR template if available (see platform sub-file for template location). Fill: Summary, Type, Changes, Testing, Rollout plan. Include a **Related Issues** section listing:
+   - `Closes #N` for each issue addressed by this PR/MR (including all batch issues).
+   - `Closes #<epic>` (all sub-issues addressed) OR `Relates to #<epic>` (partial) for the parent epic.
+   - Always list both the epic and all sub-issues in the Related Issues section regardless of partial/full completion.
+   - **Batch mode:** List `Closes #N` for every issue in the batch. Include a per-issue summary of changes in the body.
+4. **Create PR/MR** using the platform CLI (see platform sub-file for exact command).
+5. **Link PR/MR to epic** using the platform-specific method (see platform sub-file).
+6. **Verify PR body linkage** and auto-fix missing `Closes #N` references (see platform sub-file).
+
+---
+
+## Step 8a: Post-PR/MR Label Transition & Board Sync
+
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 8a)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 8a)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 8a)
+
+1. **Transition labels to `status:in-review`:** For each `Closes #N` issue (including all batch issues), update status labels using the platform CLI (see platform sub-file). If ALL sub-issues addressed, also transition the parent epic.
+2. **Sync Board:** Run the full **Board Sync Procedure** from `hatch3r-board-shared` for each item (see platform sub-file for specific targets).
+
+---
+
+## Step 9: Post-PR Housekeeping
+
+1. If all sub-issues addressed, confirm the PR body uses `Closes #<epic-number>` so the epic will auto-close on merge and transition to Done.
+2. Remind user `Closes #N` auto-closes on merge.
+3. If partial:
+
+**ASK:** "PR created. N remaining sub-issues on epic #X. Continue with next sub-issue or stop?"
+
+### 9a. Refresh Board Dashboard
+
+**This step is mandatory. Do not skip.**
+
+If a `meta:board-overview` issue exists on the board, refresh it now using cached board data updated with mutations from Steps 4, 8, and 8a. Include the `Recommended Model` column in all issue listings per the Board Overview section in `hatch3r-board-shared`. Do NOT re-fetch all issues; use cached data. Skip silently if no `meta:board-overview` issue exists.
+
+### 9b. 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 modified during this pickup run. Output the reconciliation report before proceeding to Step 10.
+
+---
+
+## Step 10: Capture Learnings
+
+After PR creation, capture learnings from this development session.
+
+1. Reflect on the implementation:
+   - Were there any unexpected challenges or blockers?
+   - Did any patterns or approaches work particularly well?
+   - Were there decisions made that future developers should know about?
+   - Were any pitfalls discovered that should be avoided next time?
+
+2. If learnings are identified:
+   - Create learning files in `.agents/learnings/` following the learning file format (see `hatch3r-learn` command).
+   - Include the issue number as `source-issue`.
+   - Tag with relevant area labels from the issue.
+   - **ASK:** "Learnings captured: {list}. Anything else to note? (add more / done)"
+
+3. If no significant learnings: skip silently. Not every task produces learnings. Do not prompt in this case.

package/commands/board/shared-azure-devops.md

@@ -0,0 +1,149 @@
+---
+id: hatch3r-board-shared-azure-devops
+type: shared-context
+description: Azure DevOps-specific platform details for board shared context. Covers Work Items, Azure Boards, az CLI, and MCP tools.
+tags: [board, team, azure-devops]
+---
+# Board Shared Reference — Azure DevOps Platform Details
+
+Platform-specific procedures for Azure DevOps. Referenced from `hatch3r-board-shared`.
+
+---
+
+## Platform Detection — Azure DevOps
+
+Use `az devops` / `az boards` / `az repos` CLI. Issues = Work Items. PRs = Pull Requests. Board = Azure Boards. Requires `az login` or `AZURE_DEVOPS_PAT`.
+
+### CLI Command Reference
+
+| Action | Command |
+|--------|---------|
+| Create work item | `az boards work-item create --org https://dev.azure.com/{namespace} --project {project} --type "User Story" --title "..."` |
+| List work items | `az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT..."` |
+| View work item | `az boards work-item show --org https://dev.azure.com/{namespace} --id N` |
+| Update work item | `az boards work-item update --org https://dev.azure.com/{namespace} --id N` |
+| Close work item | `az boards work-item update --org https://dev.azure.com/{namespace} --id N --state Closed` |
+| Create PR | `az repos pr create --org https://dev.azure.com/{namespace} --project {project}` |
+| Add tag | `az boards work-item update --id N --fields "System.Tags=x"` |
+| Add comment | `az boards work-item update --id N --discussion "..."` |
+| Board sync | Board column = Work Item State |
+
+### MCP Tool Reference
+
+| Action | MCP Tool |
+|--------|----------|
+| Create work item | `create_work_item` |
+| Read work item | `get_work_item` |
+| List work items | `list_work_items` |
+| Search work items | `search_work_items` |
+| Add relation | Work Item parent-child relation |
+| Create PR | `create_pull_request` |
+
+### Terminology
+
+| Concept | Azure DevOps Term |
+|---------|-------------------|
+| Work unit | Work Item |
+| Code review | Pull Request (PR) |
+| Board | Azure Boards |
+| Labels | Tags + Area Paths |
+| Project identifier | `project` name |
+| Status tracking | Work Item State |
+
+---
+
+## Azure DevOps Context
+
+Derived from `.agents/hatch.json` board config:
+
+- **Organization:** top-level `owner` (maps to Azure DevOps organization name)
+- **Project:** top-level `repo` (maps to Azure DevOps project name)
+- **Default branch:** `board.defaultBranch` (fallback: `"main"`)
+- **Type labels → Work Item Tags:** `board.labels.types` (applied as Tags on work items)
+- **Executor labels → Tags:** `board.labels.executors`
+- **Status labels → Work Item State:** `board.labels.statuses` (mapped to Work Item State field)
+- **Area Paths:** `board.areas` (mapped to Azure DevOps Area Paths)
+- **PR template:** Check `.azuredevops/pull_request_template.md` if present.
+
+### Azure DevOps Project Reference (cache for the full run)
+
+- **Organization URL:** `https://dev.azure.com/{namespace}`
+- **Project name:** `board.projectNumber` (repurposed as Azure DevOps project name)
+- **Work Item States:** `Backlog` → `New`, `Ready` → `Active`, `In Progress` → `Active`, `In Review` → `Resolved`, `Done` → `Closed`
+
+---
+
+## Azure Boards Work Item State Sync
+
+Azure Boards syncs via Work Item State changes. There is no separate "add to board" step -- work items appear on the board automatically based on their State and Area Path.
+
+**Status label → Work Item State mapping:**
+
+| Label                | Work Item State |
+| -------------------- | --------------- |
+| `status:triage`      | `New`           |
+| `status:ready`       | `Active`        |
+| `status:in-progress` | `Active`        |
+| `status:in-review`   | `Resolved`      |
+| `status:blocked`     | `New`           |
+| (done)               | `Closed`        |
+
+**Steps for each work item to sync:**
+
+1. **Update Work Item State:** `az boards work-item update --org https://dev.azure.com/{namespace} --id {N} --state "{state}"` using the label→state mapping above.
+2. **Update Area Path (if area labels changed):** `az boards work-item update --org https://dev.azure.com/{namespace} --id {N} --area-path "{project}\\{area}"`.
+3. **Update Tags:** `az boards work-item update --org https://dev.azure.com/{namespace} --id {N} --fields "System.Tags={comma-separated tags}"`.
+
+**MCP fallback:** If `az` CLI fails, fall back to Azure DevOps MCP `update_work_item` with the corresponding state and field values.
+
+**For PRs:** PRs are managed via `az repos pr update --id {N} --status active|completed`. Board sync for PRs is automatic in Azure DevOps when linked to work items.
+
+**Resilience:** If any call fails, retry once. If it still fails, surface a warning and continue. If `az` CLI and MCP are both unavailable, warn: "Azure Boards sync skipped -- run `az login` or set AZURE_DEVOPS_PAT."
+
+---
+
+## Sub-Issue Linking — Azure DevOps
+
+### Three-Tier Fallback Chain
+
+1. **Primary — CLI relation:**
+   `az boards work-item relation add --id {child_id} --relation-type "System.LinkTypes.Hierarchy-Reverse" --target-id {parent_id}`.
+   Record link status as `native`.
+
+2. **Fallback 1 — Comment trace:**
+   If relation add fails:
+   `az boards work-item update --id {epic} --discussion "Sub-issue: #{child} — {title} (linking failed)"`.
+   Record link status as `comment-only`.
+
+### Verification
+
+After linking, verify via `az boards work-item relation list --id {epic}` and check parent-child relations.
+
+---
+
+## Board Sync Enforcement — Azure DevOps
+
+1. **Status updates:** Set via `az boards work-item update --state`.
+2. **Fallback escalation:** `az boards work-item update` CLI → Azure DevOps MCP → surface error to user. Silent skipping is prohibited.
+3. **Board item tracking:** After updating a work item, store the work item ID in the run cache keyed by issue number.
+
+---
+
+## Cross-Cutting Tooling — Azure DevOps CLI-First
+
+**Prerequisites:** `az login` must be completed, or `AZURE_DEVOPS_PAT` environment variable set. Run `az devops configure --defaults organization=https://dev.azure.com/{namespace} project={project}` to set defaults.
+
+| Operation            | Primary (`az` CLI)                                                                             | Fallback (MCP)         |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ---------------------- |
+| List work items      | `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.State] <> 'Closed'"` | `list_work_items`      |
+| Read work item       | `az boards work-item show --id N`                                                              | `get_work_item`        |
+| Create work items    | `az boards work-item create --type "User Story" --title "..." --description "..."`             | `create_work_item`     |
+| Update work items    | `az boards work-item update --id N --fields "field=value"`                                     | `update_work_item`     |
+| Search work items    | `az boards query --wiql "SELECT ... WHERE [System.Title] CONTAINS '...'"` | `search_work_items`    |
+| Manage relations     | `az boards work-item relation add --id N --relation-type "System.LinkTypes.Hierarchy-Forward" --target-id M` | Work Item relation API |
+| Add comments         | `az boards work-item update --id N --discussion "..."`                                         | N/A                    |
+| Create PRs           | `az repos pr create --title "..." --source-branch "..." --target-branch "..."`                 | `create_pull_request`  |
+| Read PR details      | `az repos pr show --id N`                                                                      | N/A                    |
+| Manage tags          | `az boards work-item update --id N --fields "System.Tags=tag1; tag2"`                          | N/A                    |
+| Board sync           | Work Item State updates (automatic board placement)                                             | N/A                    |
+| CI/Pipelines         | `az pipelines run list` / `az pipelines run show`                                              | N/A                    |