hatch3r 1.0.0 → 1.2.0

package/commands/board/pickup-delegation-multi.md

@@ -0,0 +1,197 @@
+---
+id: hatch3r-board-pickup-delegation-multi
+type: command
+description: Multi-issue sub-agent delegation protocols for board-pickup Steps 6b (epics) and 6c (batch). Covers level-by-level parallel execution, shared context, and quality pipelines.
+tags: [board, team]
+---
+# Board Pickup — Multi-Issue Delegation (Steps 6b, 6c)
+
+Delegation details for Steps 6b and 6c of `hatch3r-board-pickup`. Referenced from the core command file.
+
+---
+
+## 6b. Epics -- Sub-Agent Delegation (One Implementer Per Sub-Issue)
+
+For epics with sub-issues, delegate each sub-issue to a dedicated implementer sub-agent. The parent orchestrator (this agent) coordinates dependency order, parallelism, and git operations.
+
+### 6b.1. Parse Sub-Issues Into Dependency Levels
+
+1. Fetch the epic's `## Implementation Order` section.
+2. Group sub-issues by dependency level:
+   - **Level 1:** Sub-issues with no unsatisfied blockers (can start immediately).
+   - **Level N:** Sub-issues whose blockers are all in levels < N.
+3. Within each level, identify parallelizable sub-issues (no mutual dependencies).
+
+### 6b.2. Prepare Shared Context
+
+Before spawning implementer sub-agents, delegate context gathering to the **hatch3r-researcher agent protocol**.
+
+1. Read the epic body (goal, scope, constraints).
+2. Spawn a researcher sub-agent following the **hatch3r-researcher agent protocol** with:
+   - **Research brief:** The epic title, goal, scope, constraints, and area labels.
+   - **Modes:** `codebase-impact`, `risk-assessment`
+   - **Depth:** `standard` for most epics. Use `quick` if the epic has fewer than 3 sub-issues or is well-specified with linked specs. Use `deep` if the epic spans multiple modules or introduces new patterns.
+   - **Project context:** Pre-loaded documentation references from area labels.
+3. Await the researcher result. Include the structured output as shared context in all implementer sub-agent prompts in Step 6b.3.
+
+### 6b.2b. Per-Sub-Issue Complexity Scoring and Tier-Adjusted Research
+
+After the shared epic-level research, score each sub-issue individually and run additional research for sub-issues that warrant it.
+
+1. **Score each sub-issue** per the `hatch3r-deep-context` rule to determine the analysis tier (Light / Standard / Deep).
+
+2. **For Tier 2+ sub-issues**, spawn per-sub-issue **hatch3r-researcher** sub-agents via the Task tool (`subagent_type: "generalPurpose"`). Launch as many concurrently as the platform supports.
+
+   Each per-sub-issue researcher prompt must include:
+   - The sub-issue title, body, acceptance criteria, and area labels.
+   - Research modes by issue type (same as Step 6a.1).
+   - **Tier-adjusted modes** (per `hatch3r-deep-context`):
+     - Tier 2: add `requirements-elicitation` + `similar-implementation` at `quick` depth
+     - Tier 3: add `requirements-elicitation` + `similar-implementation` at `deep` depth, plus `codebase-impact` at `deep` depth with transitive tracing
+   - Depth by risk level, with complexity tier overriding upward.
+   - The shared epic-level researcher output from Step 6b.2 (to avoid redundant analysis).
+
+3. **Await all per-sub-issue researchers.** Collect structured outputs. Each researcher's output feeds exclusively into its corresponding implementer in Step 6b.3.
+
+4. **For Tier 2 sub-issues:** Present the `requirements-elicitation` questions to the user inline and await answers before proceeding.
+
+5. **For Tier 3 sub-issues:** Present a full Pre-Implementation Summary per the `hatch3r-deep-context` rule. Do NOT proceed to 6b.3 until all unresolved questions are answered.
+
+6. **Tier 1 sub-issues** skip this step — they use only the shared epic-level context from Step 6b.2.
+
+### 6b.3. Execute Level-by-Level With Parallel Sub-Agents
+
+For each dependency level, starting at Level 1:
+
+1. **Spawn one implementer sub-agent per sub-issue in the current level.** Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many sub-agents concurrently as the platform supports.
+
+2. **Each sub-agent prompt must include:**
+   - The sub-issue number, title, full body, and acceptance criteria.
+   - The issue type (bug/feature/refactor/QA) and corresponding hatch3r skill name.
+   - Parent epic context (title, goal, related sub-issues at the same level).
+   - The shared researcher output from Step 6b.2 (codebase impact and risk assessment as shared context).
+   - The per-sub-issue researcher output from Step 6b.2b (if this sub-issue scored Tier 2+).
+   - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
+   - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3) — explicit decisions on ambiguities.
+   - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
+   - Documentation references relevant to this sub-issue.
+   - Instruction to follow the hatch3r-implementer agent protocol.
+   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - Instruction to use GitHub MCP for issue reads, and follow the project's tooling hierarchy for external knowledge augmentation.
+   - Explicit instruction: do NOT create branches, commits, or PRs.
+
+3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
+
+4. **Review sub-agent results:**
+   - If any sub-agent reports BLOCKED or PARTIAL, **ASK** the user how to proceed (skip, fix manually, retry).
+   - If sub-agents modified overlapping files, review for conflicts and resolve before proceeding.
+
+5. **Advance to the next dependency level.** Repeat steps 1-4 until all levels are complete.
+
+### 6b.4. Post-Delegation Verification
+
+After all sub-agents complete:
+
+1. Run a combined quality check across all changes.
+2. Resolve any cross-sub-issue integration issues.
+3. Verify no file conflicts between parallel sub-agent outputs.
+
+---
+
+## 6c. Multi-Issue Batch -- Parallel Subagent Delegation (One Implementer Per Issue)
+
+For batches of multiple standalone issues (selected via batch mode in Step 1d or by referencing multiple issue numbers), delegate each issue to a dedicated implementer sub-agent. The parent orchestrator (this agent) coordinates dependency levels, parallelism, collision avoidance, and git operations.
+
+### 6c.1. Group Issues Into Dependency Levels
+
+1. Use the updated cross-issue dependency graph (from Step 2e, adjusted by Step 3.4).
+2. Group issues by dependency level:
+   - **Level 1:** Issues with no dependencies on other issues in the batch (can start immediately). Most standalone issues will be Level 1.
+   - **Level N:** Issues that depend on other issues in levels < N.
+3. Within each level, all issues are parallelizable (no mutual dependencies — conflicts were moved to separate levels in Step 3).
+
+### 6c.2. Context Gathering (Parallel Researchers)
+
+**Skip this step only** if ALL issues in the batch are trivial single-line edits (typos, comment fixes, single-value config changes) that score Tier 1 per `hatch3r-deep-context`. The `risk:low` and `priority:p3` labels alone are not sufficient to skip research — always score complexity first.
+
+Unlike epics (which share a single researcher), standalone issues in a batch are unrelated and each need individual context gathering.
+
+1. **Spawn one hatch3r-researcher sub-agent per issue** via the Task tool (`subagent_type: "generalPurpose"`). Launch as many concurrently as the platform supports.
+
+2. **Each researcher prompt must include:**
+   - The issue title, body, acceptance criteria, and area labels.
+   - Research modes by issue type (same as Step 6a.1).
+   - Tier-adjusted modes per `hatch3r-deep-context` (same as Step 6a.1).
+   - Depth by risk level (`quick` / `standard` / `deep`), with complexity tier overriding upward.
+   - Project context and documentation references.
+
+3. **Await all researchers.** Collect structured outputs. Each researcher's output feeds exclusively into its corresponding implementer in Step 6c.3. For Tier 2/3 issues, present elicitation questions to the user and await answers before proceeding.
+
+### 6c.3. Execute Level-by-Level With Parallel Implementers
+
+For each dependency level, starting at Level 1:
+
+1. **Spawn one hatch3r-implementer sub-agent per issue in the current level.** Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many sub-agents concurrently as the platform supports.
+
+2. **Each sub-agent prompt must include:**
+   - The issue number, title, full body, and acceptance criteria.
+   - The issue type (bug/feature/refactor/QA) and corresponding hatch3r skill name.
+   - Batch context: sibling issues in the batch at the same level (for awareness, not implementation).
+   - The researcher output from Step 6c.2 for this specific issue (if that step was not skipped).
+   - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
+   - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3).
+   - **Blast radius data** from enhanced `codebase-impact` (Tier 3).
+   - Documentation references relevant to this issue.
+   - Instruction to follow the **hatch3r-implementer agent protocol**.
+   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - Explicit instruction: do NOT create branches, commits, or PRs.
+
+3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
+
+4. **Review sub-agent results:**
+   - If any sub-agent reports BLOCKED or PARTIAL, **ASK** the user how to proceed (skip, fix manually, retry).
+   - If sub-agents modified overlapping files, review for conflicts and resolve before proceeding.
+
+5. **Advance to the next dependency level.** Repeat steps 1-4 until all levels are complete.
+
+### 6c.4. Post-Batch Verification
+
+After all implementer sub-agents complete across all levels:
+
+1. Run a combined quality check across all changes from all issues.
+2. Resolve any cross-issue file conflicts or integration issues.
+3. Verify no regressions between parallel sub-agent outputs.
+
+### 6c.5. Post-Implementation Quality Pipeline
+
+After all implementations complete, run the two-stage quality pipeline across the entire batch. Use the Task tool with `subagent_type: "generalPurpose"`.
+
+**Stage 1 — Review Loop (sequential):**
+
+1. Spawn **`hatch3r-reviewer`** — code review of ALL changes across the batch. Include the full diff and acceptance criteria for each issue.
+2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes. When fixes touch shared or public interfaces, also include:
+   - **Blast radius data** from Step 6c.2 (if available) — so the fixer knows which consumers and contracts must be preserved.
+   - **Reference conventions** from Step 6c.2 (if available) — so the fixer maintains established patterns when applying fixes.
+3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
+4. Repeat steps 2-3 for a maximum of **3 iterations** until the reviewer reports 0 Critical + 0 Warning findings.
+5. If still not clean after 3 iterations, **ASK** the user how to proceed.
+
+**Stage 2 — Final Quality (parallel, after review loop is clean):**
+
+Launch as many independent sub-agents in parallel as the platform supports.
+
+**Always spawn (mandatory for every code change):**
+- **hatch3r-test-writer** — tests for all code changes across the batch.
+- **hatch3r-security-auditor** — security review of all code changes across the batch.
+
+**Always evaluate (spawn when applicable):**
+- **hatch3r-docs-writer** — spawn when any changes affect public APIs, architectural patterns, or user-facing behavior.
+
+**Conditional specialists (spawn when triggered by any issue in the batch):**
+- **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
+- **hatch3r-a11y-auditor** — spawn when any issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-perf-profiler** — spawn when any issue has `area:performance` label.
+
+Await all specialist sub-agents. Apply their feedback before proceeding to Step 7.

package/commands/board/pickup-delegation.md

@@ -0,0 +1,100 @@
+---
+id: hatch3r-board-pickup-delegation
+type: command
+description: Single-issue sub-agent delegation protocol for board-pickup Step 6a. Covers research, implementation, and quality pipeline for standalone issues.
+tags: [board, team]
+---
+# Board Pickup — Single-Issue Delegation (Step 6a)
+
+Delegation details for Step 6a of `hatch3r-board-pickup`. Referenced from the core command file.
+
+---
+
+## 6a. Single Standalone Issue -- Subagent Delegation
+
+For a single standalone issue (no sub-issues, not part of a batch), follow this three-phase approach: research, delegate to implementer, then specialist review.
+
+### 6a.1. Context Gathering (Researcher Subagent)
+
+**Skip this step only** for trivial single-line edits (typos, comment fixes, single-value config changes) that score Tier 1 per `hatch3r-deep-context`. The `risk:low` and `priority:p3` labels alone are not sufficient to skip research — always score complexity first.
+
+**Score the issue's complexity** per the `hatch3r-deep-context` rule to determine the analysis tier (Light / Standard / Deep). This determines which additional researcher modes to include alongside the standard task-type modes.
+
+Spawn a **hatch3r-researcher** sub-agent via the Task tool (`subagent_type: "generalPurpose"`) with:
+
+- **Research brief:** The issue title, body, acceptance criteria, and area labels.
+- **Modes by issue type:**
+  - `type:bug` → `symptom-trace`, `root-cause`, `codebase-impact`
+  - `type:feature` → `codebase-impact`, `feature-design`, `architecture`
+  - `type:refactor` → `current-state`, `refactoring-strategy`, `migration-path`
+  - `type:qa` → `codebase-impact`
+  - `type:docs` → `codebase-impact`
+  - `type:infra` → `codebase-impact`, `risk-assessment`
+- **Tier-adjusted modes** (per `hatch3r-deep-context`):
+  - Tier 2: add `requirements-elicitation` + `similar-implementation` at `quick` depth
+  - Tier 3: add `requirements-elicitation` + `similar-implementation` at `deep` depth, plus `codebase-impact` at `deep` depth with transitive tracing
+- **Depth:** `quick` for `risk:low`, `standard` for `risk:med`, `deep` for `risk:high`. The complexity tier may override depth upward.
+- **Project context:** Pre-loaded documentation references from area labels.
+
+Await the researcher result. Use its structured output to inform Steps 6a.2-6a.3.
+
+**For Tier 2:** Present the `requirements-elicitation` questions to the user inline and await answers before proceeding to 6a.2.
+
+**For Tier 3:** Present a full Pre-Implementation Summary per the `hatch3r-deep-context` rule. Do NOT proceed to 6a.2 until all unresolved questions are answered.
+
+### 6a.2. Core Implementation (Implementer Subagent)
+
+You MUST spawn a **hatch3r-implementer** sub-agent via the Task tool (`subagent_type: "generalPurpose"`). Do NOT implement inline — always delegate to a dedicated implementer to preserve orchestrator context for coordination, review, and integration.
+
+The implementer sub-agent prompt MUST include:
+- The issue number, title, full body, and acceptance criteria.
+- The issue type (bug/feature/refactor/QA) and corresponding hatch3r skill name.
+- The researcher output from Step 6a.1 (if that step was not skipped).
+- **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
+- **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3) — explicit decisions on ambiguities.
+- **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
+- Documentation references relevant to this issue.
+- Instruction to follow the **hatch3r-implementer agent protocol**.
+- All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
+- Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+- Explicit instruction: do NOT create branches, commits, or PRs.
+
+Await the implementer sub-agent. Collect its structured result (files changed, tests written, issues encountered).
+
+### 6a.3. Post-Implementation Quality Pipeline
+
+After implementation completes, run the two-stage quality pipeline. Use the Task tool with `subagent_type: "generalPurpose"`.
+
+**Stage 1 — Review Loop (sequential):**
+
+1. Spawn **`hatch3r-reviewer`** — code review of all changes. Include the diff and acceptance criteria in the prompt.
+2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes. When fixes touch shared or public interfaces, also include:
+   - **Blast radius data** from Step 6a.1 (if available) — so the fixer knows which consumers and contracts must be preserved.
+   - **Reference conventions** from Step 6a.1 (if available) — so the fixer maintains established patterns when applying fixes.
+3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
+4. Repeat steps 2-3 for a maximum of **3 iterations** until the reviewer reports 0 Critical + 0 Warning findings.
+5. If still not clean after 3 iterations, **ASK** the user how to proceed.
+
+**Stage 2 — Final Quality (parallel, after review loop is clean):**
+
+Launch as many independent sub-agents in parallel as the platform supports.
+
+**Always spawn (mandatory for every code change):**
+- **hatch3r-test-writer** — tests for all code changes. Unit tests for new logic, regression tests for bug fixes, integration tests for cross-module changes.
+- **hatch3r-security-auditor** — security review of all code changes. Audit data flows, access control, input validation, and secret management.
+
+**Always evaluate (spawn when applicable):**
+- **hatch3r-docs-writer** — spawn when changes affect public APIs, architectural patterns, or user-facing behavior. Skip silently if no documentation impact.
+
+**Conditional specialists (spawn when triggered):**
+- **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
+- **hatch3r-a11y-auditor** — spawn when issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-perf-profiler** — spawn when issue has `area:performance` label or changes touch hot paths.
+
+Each specialist sub-agent prompt MUST include:
+- The agent protocol to follow (e.g., "Follow the hatch3r-reviewer agent protocol").
+- All `scope: always` rule directives from `.agents/rules/` (subagents do not inherit rules automatically).
+- The diff or file changes to review.
+- The issue's acceptance criteria.
+
+Await all specialist sub-agents. Apply their feedback (fixes, additional tests, documentation updates) before proceeding to Step 7.

package/commands/board/pickup-github.md

@@ -0,0 +1,82 @@
+---
+id: hatch3r-board-pickup-github
+type: command
+description: GitHub-specific platform procedures for board-pickup. Covers gh CLI commands for issue listing, status updates, collision detection, PR creation, and label transitions.
+tags: [board, team, github]
+---
+# Board Pickup — GitHub Platform Details
+
+Platform-specific procedures for GitHub. Referenced from `hatch3r-board-pickup`.
+
+---
+
+## Step 1a: Fetch and Parse Board State — GitHub
+
+**Fetch all open issues:**
+1. `gh issue list -R {owner}/{repo} --state open --limit 500 --json number,title,labels,state,createdAt,updatedAt,body` (fall back to `list_issues` MCP). Paginate to get all.
+
+**Check sub-issues per issue:**
+- `issue_read` with `method: get_sub_issues`.
+
+**Fetch labels:**
+- `issue_read` with `method: get_labels`.
+
+---
+
+## Step 3: Collision Detection — GitHub
+
+**In-progress issues:**
+- `gh issue list -R {owner}/{repo} --label "status:in-progress" --state open` (fall back to `search_issues` MCP).
+
+**Open PRs:**
+- `gh pr list -R {owner}/{repo} --state open` (fall back to `search_pull_requests` MCP).
+
+---
+
+## Step 4: Update Issue Status — GitHub
+
+**Update status labels:**
+- `gh issue edit N --remove-label "status:ready" --add-label "status:in-progress"` (fall back to `issue_write` MCP).
+
+**Sync board status:**
+Follow the **GitHub Projects V2 Sync** from `commands/board/shared-github.md` for each issue marked `status:in-progress` (including parent epic). Set status to "In Progress".
+
+---
+
+## Step 8: Create Pull Request — GitHub
+
+**PR template:** Check `.github/PULL_REQUEST_TEMPLATE.md`.
+
+**Create PR:**
+`gh pr create -R {owner}/{repo} --head {branch} --base {base} --title "..." --body "..."` (fall back to `create_pull_request` MCP).
+
+`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+
+**Link PR to epic:**
+`gh issue comment {epic} -R {owner}/{repo} --body "PR: #{pr_number}"` (fall back to `add_issue_comment` MCP).
+
+**Verify PR body linkage:**
+Read back the created PR body and verify it contains `Closes #N` for every issue addressed. If any `Closes #N` reference is missing:
+`gh pr edit {pr_number} -R {owner}/{repo} --body "..."`.
+
+---
+
+## Step 8a: Post-PR Label Transition — GitHub
+
+**Transition labels to `status:in-review`:**
+`gh issue edit N --remove-label "status:in-progress" --add-label "status:in-review"`.
+
+**Sync Board:**
+Follow the full **GitHub Projects V2 Sync** from `commands/board/shared-github.md` for:
+- The PR: Set to "In Review" on the board.
+- Each `Closes #N` issue: Set to "In Review".
+- Parent epic (all sub-issues addressed): Set to "In Review".
+- Parent epic (partial): Verify status is "In Progress"; set it if not.
+
+---
+
+## Error Handling — GitHub
+
+- **Issue listing failure** (`list_issues`): retry once, then ask user for issue number.
+- **Issue update failure** (`issue_write`): warn and continue (labels not blocking).
+- **PR creation failure** (`create_pull_request`): present error and manual instructions.

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.