hatch3r 1.1.0 → 1.3.0

package/commands/hatch3r-board-pickup.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-board-pickup
 type: command
-description: Pick up one or more epics/issues from the project board for development. Handles dependency-aware selection, collision detection, branching, parallel sub-agent delegation, and batch execution. Supports GitHub, Azure DevOps, and GitLab.
+description: Pick up one or more epics/issues from the project board for development. Handles dependency-aware selection, collision detection, branching, parallel sub-agent delegation, and batch execution. Supports GitHub, Azure DevOps, and GitLab. Platform-specific details are in commands/board/pickup-{platform}.md.
+tags: [board, team]
 ---
 # Board Pickup -- Develop Issues from the Project Board
 
@@ -35,14 +36,7 @@ If **no**: all browser verification steps are skipped silently throughout the en
 
 ## Integration with GitHub Agentic Workflows
 
-hatch3r's board commands operate as the **implementation orchestration layer** above GitHub Agentic Workflows. While GitHub's agentic workflows handle continuous automation (triage, testing, documentation), hatch3r's board commands orchestrate the full delivery pipeline:
-
-- **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
-
-GitHub Agentic Workflows and hatch3r are complementary: use agentic workflows for continuous background automation, use hatch3r board commands for structured delivery orchestration.
+hatch3r board commands orchestrate the **implementation delivery pipeline** (init → fill → groom → pickup → PR) above GitHub Agentic Workflows, which handle continuous background automation (triage, testing, docs). The two are complementary.
 
 ---
 
@@ -70,29 +64,18 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 #### 1a. Fetch and Parse Board State
 
-**Platform-specific: Fetch all open items**
-
-**If platform is `github`:**
-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.
-
-**If platform is `azure-devops`:**
-1. `az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT [System.Id], [System.Title], [System.State], [System.Tags] FROM WorkItems WHERE [System.State] <> 'Closed' AND [System.State] <> 'Removed'"` (fall back to `list_work_items` MCP).
-
-**If platform is `gitlab`:**
-1. `glab issue list -R {namespace}/{project} --state opened --per-page 100`. Paginate to get all.
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 1a)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 1a)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 1a)
 
 **Exclude** `meta:board-overview` issues/work items.
 
-2. For each issue, check sub-issues:
-   - **GitHub:** `issue_read` with `method: get_sub_issues`.
-   - **Azure DevOps:** `az boards work-item relation list --id N`.
-   - **GitLab:** `glab api projects/{project_id}/issues/{N}/links`.
-3. Fetch labels/tags:
-   - **GitHub:** `issue_read` with `method: get_labels`.
-   - **Azure DevOps:** Extract from `System.Tags` field.
-   - **GitLab:** Extract from issue data.
-4. Parse `## Dependencies` sections for hard (`Blocked by #N`) and soft (`Recommended after #N`) references. Only hard dependencies affect availability categorization and block pickup; soft dependencies are advisory (note them in the presentation but do not treat as blockers).
-5. For epics, parse `## Implementation Order` sections.
+After fetching open items using the platform CLI:
+
+1. For each issue, check sub-issues using the platform-specific method.
+2. Fetch labels/tags using the platform-specific method.
+3. Parse `## Dependencies` sections for hard (`Blocked by #N`) and soft (`Recommended after #N`) references. Only hard dependencies affect availability categorization and block pickup; soft dependencies are advisory (note them in the presentation but do not treat as blockers).
+4. For epics, parse `## Implementation Order` sections.
 
 **Cache all data retrieved here for reuse in later steps.**
 
@@ -143,16 +126,9 @@ When the user selects **(f) batch** or references multiple issue numbers (e.g.,
 
 #### 1e. Auto-Pick (No Specific Issue Referenced)
 
-If the user invoked without referencing a specific issue, present an auto-pick. Skip if a specific issue was referenced.
+If no specific issue was referenced, auto-pick using: (1) `status:ready` + all blockers satisfied + not `in-progress`, (2) `executor:agent` or `executor:hybrid`, (3) Implementation Order position → priority → most downstream unblocking, (4) tiebreaker: epic sub-issues > standalone.
 
-**Selection criteria (in order):**
-
-1. Available: `status:ready`, all blockers satisfied, not already `status:in-progress`.
-2. `executor:agent` or `executor:hybrid` (skip `executor:human`).
-3. Follow the board's Implementation Order (earliest open level, highest-priority entry, most downstream unblocking). Fall back to priority-weighted topological sort.
-4. Tiebreaker: epic sub-issues > standalone; most downstream unblocking; higher priority.
-
-**Auto-pick batch mode:** When multiple independent issues are available, auto-pick selects all independent issues that share no mutual dependencies (configurable via `--max-batch`). Present as a batch recommendation.
+**Batch mode:** Auto-pick selects all independent issues with no mutual dependencies (configurable via `--max-batch`).
 
 **ASK:** "Pick up #N? Or batch: #N, #M, #K (independent, parallelizable). Options: (yes single / yes batch / pick alternative / show full board)"
 
@@ -201,14 +177,12 @@ When multiple issues are selected as a batch:
 
 ### Step 3: Collision Detection
 
-1. **In-progress issues:** Search using platform CLI:
-   - **GitHub:** `gh issue list -R {owner}/{repo} --label "status:in-progress" --state open` (fall back to `search_issues` MCP).
-   - **Azure DevOps:** `az boards query --wiql "SELECT ... WHERE [System.State] = 'Active' AND [System.Tags] CONTAINS 'status:in-progress'"`.
-   - **GitLab:** `glab issue list -R {namespace}/{project} --label "status::in-progress" --state opened`.
-2. **Open PRs/MRs:**
-   - **GitHub:** `gh pr list -R {owner}/{repo} --state open` (fall back to `search_pull_requests` MCP).
-   - **Azure DevOps:** `az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status active`.
-   - **GitLab:** `glab mr list -R {namespace}/{project} --state opened`.
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 3)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 3)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 3)
+
+1. **In-progress issues:** Search using platform CLI (see platform sub-file).
+2. **Open PRs/MRs:** Search using platform CLI (see platform sub-file).
 3. **Overlap analysis:** Flag hard collisions (same problem/files), soft collisions (related work), or no collision.
 4. **Intra-batch overlap (batch mode):** Check whether any issues within the batch are likely to touch the same files. If so, move conflicting issues to sequential dependency levels rather than parallel.
 
@@ -220,60 +194,9 @@ When multiple issues are selected as a batch:
 
 ### Step 3b: Specification Generation (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`
+> Full details: see `commands/board/pickup-modes.md` (Specification Generation)
 
-#### 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 GitHub 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)
+When the picked issue lacks a detailed specification (type `feature` or `refactor`, complexity `complex` or `epic`), generate one before implementation. Skip when: issue already has a linked spec, simple bug fix, `skip-spec` label, or auto-advance mode is active.
 
 ---
 
@@ -283,10 +206,11 @@ Skip this step when:
 
 > When picking up any sub-issue, the **parent epic MUST also be marked `status:in-progress`**.
 
-1. Update status labels/tags to `in-progress` using platform CLI:
-   - **GitHub:** `gh issue edit N --remove-label "status:ready" --add-label "status:in-progress"` (fall back to `issue_write` MCP).
-   - **Azure DevOps:** `az boards work-item update --id N --state "Active"` and update tags.
-   - **GitLab:** `glab issue update N --unlabel "status::ready" --label "status::in-progress"`.
+> Platform-specific details: see `commands/board/pickup-github.md` (Step 4)
+> Platform-specific details: see `commands/board/pickup-azure-devops.md` (Step 4)
+> Platform-specific details: see `commands/board/pickup-gitlab.md` (Step 4)
+
+1. Update status labels/tags to `in-progress` using platform CLI (see platform sub-file).
 2. Always mark parent epic as `status:in-progress`.
 3. When picking up an entire epic: mark ALL remaining open sub-issues as `status:in-progress`.
 4. **Batch mode:** Mark ALL issues in the batch as `status:in-progress`.
@@ -334,489 +258,37 @@ Use the issue type to select the appropriate hatch3r skill: `type:bug` → the h
 
 #### 6.pre: Consult Learnings
 
-Before delegating implementation:
-
-1. If `.agents/learnings/` exists, scan for learnings with matching `area` or `tags` that overlap with the issue's area labels or tech stack.
-2. Read the `## Applies When` section of matching learnings.
-3. Include any relevant learnings (especially `pitfall` category) in the sub-agent prompt or direct implementation context.
-4. If no learnings directory exists, skip silently.
-
-> **For audit epics:** If the selected epic represents an audit (e.g., healthcheck, security audit, dependency audit), customize this step based on the project's audit protocol. Audit epics typically produce GitHub issues as findings rather than code changes -- adjust the delegation flow accordingly and skip Steps 7-8a if no code changes are produced.
-
-**Do NOT execute the skill's PR creation steps.** Testing and PR creation are handled by board-pickup Steps 7-8 below, which include board-specific requirements (epic linking, label transitions, Projects v2 sync) that individual skills do not cover.
-
-**After all implementation completes, return here and continue with Step 7.**
-
----
-
-#### 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.
+Before delegating: scan `.agents/learnings/` for matching `area`/`tags`, include relevant learnings (especially `pitfall` category) in sub-agent context. Skip silently if no learnings directory exists.
 
-##### 6a.2. Core Implementation (Implementer Subagent)
+> **Audit epics:** Audit epics produce findings (issues) rather than code changes — adjust delegation and skip Steps 7-8a if no code changes.
 
-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.
+**Do NOT execute the skill's PR creation steps.** Steps 7-8 handle board-specific requirements (epic linking, label transitions, board sync).
 
 ---
 
-#### 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
+> Delegation protocols: `commands/board/pickup-delegation.md` (6a single issue), `commands/board/pickup-delegation-multi.md` (6b epics, 6c batch)
 
-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.
-
----
-
-### 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
-
-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. 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.
-
-   **Platform-specific templates:**
-   - **GitHub:** Check `.github/PULL_REQUEST_TEMPLATE.md`.
-   - **Azure DevOps:** Check `.azuredevops/pull_request_template.md`.
-   - **GitLab:** Check `.gitlab/merge_request_templates/`.
-
-4. **Platform-specific: Create PR/MR**
-
-   **If platform is `github`:**
-   Use `gh pr create -R {owner}/{repo} --head {branch} --base {base} --title "..." --body "..."` (fall back to `create_pull_request` MCP).
-
-   **If platform is `azure-devops`:**
-   Use `az repos pr create --org https://dev.azure.com/{namespace} --project {project} --source-branch {branch} --target-branch {base} --title "..." --description "..."` (fall back to `create_pull_request` MCP).
-
-   **If platform is `gitlab`:**
-   Use `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"`).
-
-5. **Link PR/MR to epic:**
-   - **GitHub:** `gh issue comment {epic} -R {owner}/{repo} --body "PR: #{pr_number}"` (fall back to `add_issue_comment` MCP).
-   - **Azure DevOps:** `az boards work-item relation add --id {epic_id} --relation-type "ArtifactLink" --target-id {pr_id}` or link via PR description.
-   - **GitLab:** Reference the epic issue number in the MR description. GitLab auto-links MRs to issues mentioned with `Closes #N`.
-
----
-
-### Step 8a: Post-PR/MR Label Transition & Board Sync
-
-1. **Transition labels to `status:in-review`:** For each `Closes #N` issue (including all batch issues), update status labels:
-   - **GitHub:** `gh issue edit N --remove-label "status:in-progress" --add-label "status:in-review"`.
-   - **Azure DevOps:** `az boards work-item update --id N --state "Resolved"` and update tags.
-   - **GitLab:** `glab issue update N --unlabel "status::in-progress" --label "status::in-review"`.
-   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** of the following items individually:
-   - **a. The PR/MR:** Set to "In Review" on the board.
-   - **b. Each `Closes #N` issue:** Set to "In Review". In batch mode, this includes every issue in the batch.
-   - **c. Parent epic (all sub-issues addressed):** Set to "In Review". The PR/MR body uses `Closes #<epic>`, so the epic will auto-close on merge and transition to Done.
-   - **d. Parent epic (partial -- some sub-issues remain):** Verify status is "In Progress"; set it if not. The PR/MR body uses `Relates to #<epic>` (epic stays open after merge).
-
----
-
-### 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.
+**After all implementation completes, return here and continue with Step 7.**
 
 ---
 
-### Step 10: Capture Learnings
-
-After PR creation, capture learnings from this development session.
+### Steps 7-10: Post-Implementation Pipeline
 
-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?
+> Full details: see `commands/board/pickup-post-impl.md`
 
-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)"
+Execute Steps 7-10 in order after all implementation completes:
 
-3. If no significant learnings: skip silently. Not every task produces learnings. Do not prompt in this case.
+- **Step 7:** Quality verification (lint, type check, tests, AC).
+- **Step 7a:** Commit and push all changes to the remote branch.
+- **Step 8:** Create PR/MR with proper `Closes #N` references. See platform sub-files for CLI commands.
+- **Step 8a:** Transition labels to `status:in-review` and sync board. See platform sub-files.
+- **Step 9:** Post-PR housekeeping: epic link verification, board dashboard refresh (9a, mandatory), end-of-run reconciliation (9b, mandatory).
+- **Step 10:** Capture learnings in `.agents/learnings/` if any were identified.
 
 ---
 
-## 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 |
+## Auto-Advance Mode, Error Handling, and Guardrails
 
-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}
-
----
+> Full details: see `commands/board/pickup-modes.md`
 
-## Error Handling
-
-- **Issue listing/search failure** (GitHub `list_issues` / Azure DevOps `az boards query` / GitLab `glab issue list`): retry once, then ask user for issue number.
-- **Issue update failure** (GitHub `issue_write` / Azure DevOps `az boards work-item update` / GitLab `glab issue update`): warn and continue (labels not blocking).
-- **Quality verification failure:** fix before creating PR/MR.
-- **PR/MR creation failure** (GitHub `create_pull_request` / Azure DevOps `az repos pr create` / GitLab `glab mr create`): 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.
+The modes file contains: auto-advance mode (`--auto`/`--unattended`), safety guardrails, error handling, and operational guardrails for board-pickup.