hatch3r 1.1.0 → 1.3.0

package/agents/modes/similar-implementation.md

@@ -0,0 +1,70 @@
+---
+id: researcher-mode-similar-implementation
+type: mode
+description: Search the codebase for analogous features and extract implementation conventions.
+parent: hatch3r-researcher
+---
+### Mode: `similar-implementation`
+
+Search the codebase for analogous features, components, or modules and extract their implementation conventions as a reference for the implementer. The goal is to ensure new code follows established patterns rather than inventing new approaches.
+
+**Protocol:**
+
+1. Parse the task to extract the core *type* of work — CRUD resource, dashboard widget, API endpoint, auth flow, data pipeline, form, modal, notification, list/table view, search feature, file upload, webhook handler, background job, etc.
+2. Search the codebase for modules and components that perform the same *type* of work. Use file name patterns, directory structure, import analysis, and semantic code search.
+3. Rank matches by structural similarity: file organization, patterns used, complexity level, recency.
+4. For the top 2-3 matches, extract:
+   - File structure and naming conventions (file names, directory placement, barrel exports)
+   - State management pattern (local state, context, store, server state, URL state)
+   - Error handling approach (try/catch style, error boundaries, toast notifications, inline errors)
+   - Data fetching / API pattern (hooks, services, direct fetch, query library)
+   - Test structure and coverage approach (co-located vs separate, naming, mock strategy)
+   - Component composition pattern (container/presenter, compound components, render props — if UI)
+5. Identify where the proposed feature MUST differ from references and why (different data shape, different auth model, different performance requirements).
+6. Present reference implementations with a recommendation for which to follow.
+
+**Output structure:**
+
+```markdown
+## Similar Implementation Analysis
+
+### Work Type Classification
+- **Detected type:** {type of work — e.g., "CRUD resource with list view and detail page"}
+- **Search strategy:** {how references were found — file patterns, directory scan, semantic search}
+
+### Reference Implementations
+| # | Module / Feature | Location | Similarity | Why It's a Good Reference |
+|---|-----------------|----------|-----------|--------------------------|
+| 1 | {name} | {directory/file path} | High/Med | {what makes it analogous} |
+| 2 | {name} | {directory/file path} | High/Med | {what makes it analogous} |
+
+### Convention Extraction
+
+#### Reference 1: {name}
+| Aspect | Convention | Files |
+|--------|-----------|-------|
+| File structure | {pattern — e.g., "feature directory with index barrel, component, hook, types, test files"} | {example files} |
+| State management | {pattern — e.g., "React Query for server state + local useState for UI state"} | {example files} |
+| Error handling | {pattern — e.g., "ErrorBoundary wrapper + toast for mutations + inline for forms"} | {example files} |
+| Data fetching | {pattern — e.g., "custom hook wrapping useQuery, service layer for API calls"} | {example files} |
+| Test structure | {pattern — e.g., "co-located .test.tsx, RTL for components, msw for API mocks"} | {example files} |
+| Component composition | {pattern — e.g., "container fetches data, presenter renders, shared via compound"} | {example files} |
+
+### Recommendation
+- **Primary reference:** {name} — follow this for {rationale}
+- **Secondary reference:** {name} — consult for {specific aspect}
+
+### Divergence Warnings
+| # | Aspect | Reference Pattern | Required Divergence | Reason |
+|---|--------|------------------|-------------------|--------|
+| 1 | {aspect} | {what the reference does} | {what the new feature must do differently} | {why} |
+
+### Pattern-Match Checklist for Implementer
+- [ ] File structure follows {reference} convention
+- [ ] State management uses {pattern} as established in {reference}
+- [ ] Error handling follows {pattern} from {reference}
+- [ ] Data fetching uses {pattern} from {reference}
+- [ ] Test structure matches {pattern} from {reference}
+- [ ] Component composition follows {pattern} from {reference}
+- [ ] Documented divergences with justification for each
+```

package/agents/modes/symptom-trace.md

@@ -0,0 +1,39 @@
+---
+id: researcher-mode-symptom-trace
+type: mode
+description: Trace reported symptoms through the codebase to find divergence points.
+parent: hatch3r-researcher
+---
+### Mode: `symptom-trace`
+
+Trace reported symptoms through the codebase. Map the execution path from user action to observed failure. Identify where expected behavior diverges from actual behavior.
+
+**Output structure:**
+
+```markdown
+## Symptom Trace
+
+### Execution Path
+| # | Step | File / Function | Expected Behavior | Observed / Likely Behavior |
+|---|------|----------------|-------------------|---------------------------|
+| 1 | {user action or trigger} | {entry point} | {what should happen} | {what likely happens} |
+| 2 | {next step in flow} | {file:function} | {expected} | {observed or inferred} |
+
+### Divergence Point
+- **Where:** {file:function or module where behavior diverges}
+- **What:** {description of the divergence}
+- **Evidence:** {code patterns, conditions, or state that suggest this is the divergence point}
+
+### Error Propagation
+| From | To | How | Observable? |
+|------|----|-----|-------------|
+| {origin} | {downstream} | {mechanism — exception, bad state, silent failure} | Yes/No |
+
+### Affected Code Paths
+| Path | Entry Point | Risk of Symptom | Notes |
+|------|-------------|----------------|-------|
+| {flow name} | {file:function} | High/Med/Low | {why this path is affected} |
+
+### Data Flow Concerns
+- {any data integrity, state management, or concurrency concerns identified during tracing}
+```

package/agents/modes/test-pattern.md

@@ -0,0 +1,61 @@
+---
+id: researcher-mode-test-pattern
+type: mode
+description: Extract existing test conventions, framework usage, mock patterns, and helper libraries.
+parent: hatch3r-researcher
+---
+### Mode: `test-pattern`
+
+Extract existing test conventions, framework usage, mock patterns, and helper libraries to ensure new tests follow established patterns. Used by `hatch3r-test-plan` to align the test strategy with the project's existing test infrastructure.
+
+**Output structure:**
+
+```markdown
+## Test Pattern Analysis
+
+### Framework & Tooling Inventory
+| Tool | Version | Config File | Purpose |
+|------|---------|------------|---------|
+| {vitest/jest/playwright/stryker/etc.} | {version} | {config path} | {unit/integration/E2E/mutation} |
+
+### Directory Conventions
+| Test Type | Directory | Naming Pattern | Co-located? |
+|-----------|-----------|---------------|-------------|
+| Unit | {path} | {pattern — e.g., *.test.ts} | Yes/No |
+| Integration | {path} | {pattern} | Yes/No |
+| E2E | {path} | {pattern} | Yes/No |
+| Fixtures | {path} | {pattern} | — |
+| Quarantine | {path or "none"} | {pattern} | — |
+
+### Mock & Fixture Patterns
+| Pattern | Where Used | Convention | Compliance with hatch3r-testing |
+|---------|-----------|-----------|-------------------------------|
+| {fakes / stubs / mocks / MSW / nock / etc.} | {example files} | {how the project uses this pattern} | {aligned — fakes > stubs > mocks / divergent — explain} |
+
+### Test Helper Library
+| Helper | Location | Purpose | Used By |
+|--------|----------|---------|---------|
+| {factory function / builder / custom matcher / setup utility} | {file path} | {what it does} | {which test files use it} |
+
+### Property-Based Testing Usage
+| Status | Library | Where Used | Coverage |
+|--------|---------|-----------|---------|
+| {Active / Not used / Minimal} | {fast-check / etc. or "none"} | {file paths or "N/A"} | {which function types are covered} |
+
+### Convention Compliance
+| Convention (hatch3r-testing rule) | Current State | Compliance |
+|----------------------------------|--------------|-----------|
+| Deterministic (no wall clock) | {compliant / violations found} | {details} |
+| Isolated (own setup/teardown) | {compliant / violations found} | {details} |
+| Fast (unit < 50ms, integration < 2s) | {compliant / unknown / violations} | {details} |
+| Named clearly (behavior descriptions) | {compliant / mixed / non-compliant} | {details} |
+| No network in unit tests | {compliant / violations found} | {details} |
+| No type escape hatches | {compliant / violations found} | {details} |
+| Fakes > stubs > mocks hierarchy | {followed / partially / not followed} | {details} |
+| Factory over fixtures | {followed / partially / not followed} | {details} |
+```
+
+**Depth scaling:**
+- **quick**: Framework inventory + directory conventions only.
+- **standard**: Full inventory, directory conventions, mock patterns, and convention compliance summary.
+- **deep**: All sections exhaustively. Include test helper library analysis, property-based testing status, and detailed convention compliance with file-level violations.

package/agents/shared/external-knowledge.md

@@ -0,0 +1,11 @@
+---
+id: shared-external-knowledge
+type: reference
+description: Shared external knowledge reference for all agents — tooling hierarchy, platform CLI, Context7 MCP, and web research guidance.
+---
+## External Knowledge
+
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
+- **GitHub:** `gh` CLI
+- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
+- **GitLab:** `glab` CLI

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

@@ -0,0 +1,81 @@
+---
+id: hatch3r-board-pickup-azure-devops
+type: command
+description: Azure DevOps-specific platform procedures for board-pickup. Covers az CLI commands for work item listing, status updates, collision detection, PR creation, and state transitions.
+tags: [board, team, azure-devops]
+---
+# Board Pickup — Azure DevOps Platform Details
+
+Platform-specific procedures for Azure DevOps. Referenced from `hatch3r-board-pickup`.
+
+---
+
+## Step 1a: Fetch and Parse Board State — Azure DevOps
+
+**Fetch all open work items:**
+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).
+
+**Check sub-issues per work item:**
+- `az boards work-item relation list --id N`.
+
+**Fetch tags:**
+- Extract from `System.Tags` field.
+
+---
+
+## Step 3: Collision Detection — Azure DevOps
+
+**In-progress work items:**
+- `az boards query --wiql "SELECT ... WHERE [System.State] = 'Active' AND [System.Tags] CONTAINS 'status:in-progress'"`.
+
+**Open PRs:**
+- `az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status active`.
+
+---
+
+## Step 4: Update Issue Status — Azure DevOps
+
+**Update work item state and tags:**
+- `az boards work-item update --id N --state "Active"` and update tags to include `status:in-progress`.
+
+**Sync board status:**
+Follow the **Azure Boards Work Item State Sync** from `commands/board/shared-azure-devops.md` for each work item marked `status:in-progress` (including parent epic). Set state to "Active".
+
+---
+
+## Step 8: Create Pull Request — Azure DevOps
+
+**PR template:** Check `.azuredevops/pull_request_template.md`.
+
+**Create PR:**
+`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).
+
+`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+
+**Link PR to epic:**
+`az boards work-item relation add --id {epic_id} --relation-type "ArtifactLink" --target-id {pr_id}` or link via PR description.
+
+**Verify PR body linkage:**
+Read back the created PR description and verify it contains `Closes #N` for every work item addressed. If any reference is missing:
+`az repos pr update --id {pr_number} --description "..."`.
+
+---
+
+## Step 8a: Post-PR Label Transition — Azure DevOps
+
+**Transition to `status:in-review`:**
+`az boards work-item update --id N --state "Resolved"` and update tags to include `status:in-review`.
+
+**Sync Board:**
+Follow the full **Azure Boards Work Item State Sync** from `commands/board/shared-azure-devops.md` for:
+- Each `Closes #N` work item: Set state to "Resolved".
+- Parent epic (all sub-issues addressed): Set state to "Resolved".
+- Parent epic (partial): Verify state is "Active"; set it if not.
+
+---
+
+## Error Handling — Azure DevOps
+
+- **Work item listing failure** (`az boards query`): retry once, then ask user for work item ID.
+- **Work item update failure** (`az boards work-item update`): warn and continue (tags not blocking).
+- **PR creation failure** (`az repos pr create`): present error and manual instructions.

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.