hatch3r 1.0.0

package/prompts/hatch3r-code-review.md

@@ -0,0 +1,131 @@
+---
+id: hatch3r-code-review
+type: prompt
+description: Review code changes for quality, security, and correctness
+---
+# Code Review
+
+Review the provided code changes for quality, security, and correctness. Produce a structured review report with actionable feedback.
+
+## Instructions
+
+1. **Correctness** — Does the code do what it is supposed to? Verify against acceptance criteria, spec references, and expected behavior. Check for off-by-one errors, missing null/undefined handling, incorrect operator usage, and logic inversions.
+2. **Security** — Input validation at boundaries, auth checks on every route, no secrets in code or logs, CSRF protection on mutations, parameterized queries, safe deserialization. Flag any trust boundary violations.
+3. **Code Quality** — Naming follows conventions, functions < 50 lines, files < 400 lines, cyclomatic complexity ≤ 10, no dead code or unused imports, DRY without over-abstraction.
+4. **Type Safety** — No `any`, no `@ts-ignore` without a linked issue, discriminated unions preferred over type assertions, `satisfies` over `as` where applicable.
+5. **Performance** — No N+1 queries, no unnecessary allocations in hot paths, lazy loading for large imports, no unbounded list fetches, bundle size impact assessed.
+6. **Testing** — New logic has unit tests, bug fixes have regression tests, edge cases covered, mocks are minimal and focused.
+7. **Accessibility** — If UI changes: keyboard navigation, WCAG AA contrast (4.5:1), ARIA attributes, `prefers-reduced-motion` respected.
+8. **Error Handling** — Errors caught and handled at the appropriate level, user-facing errors are informative but safe (no stack traces), fail-closed defaults.
+
+## Edge Cases to Watch
+
+- Empty collections and null/undefined inputs at boundaries
+- Concurrent modifications and race conditions
+- Unicode and multi-byte string handling
+- Timezone-sensitive date operations
+- Large payload sizes and pagination exhaustion
+- Partial failures in batch operations
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Security vulnerability, data loss risk, privacy violation, incorrect business logic | Must fix before merge |
+| **Warning** | Performance regression, missing tests, code quality violation, poor error handling | Should fix, PR author decides timing |
+| **Suggestion** | Naming improvement, alternative pattern, readability enhancement | Nice to have, not blocking |
+
+## Output Template
+
+```markdown
+## Code Review: {file or PR scope}
+
+**Verdict:** APPROVE | REQUEST CHANGES | COMMENT
+
+### Critical
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | `src/auth.ts:42` | Missing token expiry check | Add `if (isExpired(token)) throw new AuthError(...)` |
+
+### Warnings
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | `src/api/users.ts:78` | No test for empty input case | Add unit test for `getUser(undefined)` |
+
+### Suggestions
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | `src/utils.ts:15` | `data` is vague | Rename to `userProfile` for clarity |
+
+### Summary
+
+- Critical: {n} | Warnings: {n} | Suggestions: {n}
+- Test coverage: {assessed / not assessed}
+- Security: {no issues / issues found}
+```
+
+## Few-Shot Examples
+
+### Example 1: Security Issue Found
+
+**Input:** A diff adding a new API endpoint:
+
+```typescript
+app.post("/api/admin/users", async (req, res) => {
+  const user = await db.createUser(req.body);
+  res.json(user);
+});
+```
+
+**Output:**
+
+```markdown
+## Code Review: src/routes/admin.ts
+
+**Verdict:** REQUEST CHANGES
+
+### Critical
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | `src/routes/admin.ts:12` | No auth middleware on admin endpoint | Add `requireAuth("admin")` middleware before handler |
+| 2 | `src/routes/admin.ts:13` | `req.body` used without validation | Add zod schema: `const body = CreateUserSchema.parse(req.body)` |
+
+### Warnings
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | `src/routes/admin.ts:14` | Full user object returned including password hash | Return `omit(user, ["passwordHash"])` |
+
+### Summary
+
+- Critical: 2 | Warnings: 1 | Suggestions: 0
+- Security: AUTH MISSING, INPUT UNVALIDATED
+```
+
+### Example 2: Clean Code with Minor Suggestions
+
+**Input:** A utility function refactor with tests.
+
+**Output:**
+
+```markdown
+## Code Review: src/utils/format.ts
+
+**Verdict:** APPROVE
+
+### Suggestions
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | `src/utils/format.ts:8` | `formatDate` accepts `any` | Use `Date | string | number` union type |
+
+### Summary
+
+- Critical: 0 | Warnings: 0 | Suggestions: 1
+- Test coverage: 4 new tests added, edge cases covered
+- Security: no issues
+```

package/prompts/hatch3r-pr-description.md

@@ -0,0 +1,173 @@
+---
+id: hatch3r-pr-description
+type: prompt
+description: Generate a pull request description from staged changes
+---
+# PR Description
+
+Generate a pull request description for the current changes. Analyze the diff and produce a structured, reviewer-friendly PR description.
+
+## Instructions
+
+1. **Analyze the staged diff and recent commits** on this branch. Identify all files changed, lines added/removed, and the nature of each change.
+2. **Identify the type of change:**
+
+   | Type | Prefix | When to Use |
+   |------|--------|-------------|
+   | Feature | `feat:` | New functionality or capability |
+   | Fix | `fix:` | Bug fix or error correction |
+   | Refactor | `refactor:` | Code restructuring without behavior change |
+   | Docs | `docs:` | Documentation only |
+   | Test | `test:` | Adding or updating tests only |
+   | Infra | `infra:` | CI/CD, build config, tooling |
+   | Perf | `perf:` | Performance improvement |
+   | Security | `security:` | Security fix or hardening |
+
+3. **Write a concise title** following Conventional Commits: `{type}: {short description}` (max 72 characters).
+4. **Write the body** with structured sections (see template below).
+5. **Assess risk level** — low (docs, tests), medium (new feature, refactor), high (auth, data model, security).
+
+## Edge Cases to Handle
+
+- **Multiple change types:** If the PR spans types (e.g., feature + tests + docs), use the primary type and note others in the summary.
+- **Breaking changes:** Always include a `## Breaking Changes` section with migration instructions. Prefix title with `feat!:` or `fix!:`.
+- **Large PRs:** If the diff exceeds 500 lines, suggest splitting. List logical split points.
+- **No linked issue:** Flag this — every PR should reference an issue.
+- **Reverts:** Use `revert:` prefix and link to the original PR being reverted.
+
+## Output Template
+
+```markdown
+## {type}: {short description}
+
+### Summary
+
+- {what changed — 1-3 bullet points explaining the change and why it was needed}
+
+### Changes
+
+| File | Change | Description |
+|------|--------|-------------|
+| `{path}` | Added / Modified / Deleted | {what and why} |
+
+### Test Plan
+
+- [ ] {how to verify the changes work — specific steps}
+- [ ] {edge case verified}
+- [ ] Lint and typecheck pass
+- [ ] All tests pass
+
+### Risk Assessment
+
+| Factor | Level | Notes |
+|--------|-------|-------|
+| **Scope** | Low / Med / High | {number of files, modules touched} |
+| **Data impact** | None / Low / High | {any schema or data changes} |
+| **Security** | None / Low / High | {auth, input validation, secrets} |
+| **Rollback** | Easy / Complex | {can this be reverted cleanly?} |
+
+### Breaking Changes
+
+{None, or describe what breaks and how to migrate}
+
+### Related
+
+- Closes #{issue_number}
+- Related: #{other_issue}
+```
+
+## Few-Shot Examples
+
+### Example 1: Feature PR
+
+**Input:** Diff adds a new rate-limiting middleware, updates 3 route files, adds tests.
+
+**Output:**
+
+```markdown
+## feat: add rate limiting to public API endpoints
+
+### Summary
+
+- Add token-bucket rate limiter middleware to prevent abuse of public endpoints
+- Apply 100 req/min limit to auth endpoints, 1000 req/min to read endpoints
+- Return standard `429 Too Many Requests` with `Retry-After` header
+
+### Changes
+
+| File | Change | Description |
+|------|--------|-------------|
+| `src/middleware/rateLimiter.ts` | Added | Token-bucket implementation with Redis backing |
+| `src/routes/auth.ts` | Modified | Apply rate limiter with auth-tier limits |
+| `src/routes/api.ts` | Modified | Apply rate limiter with standard-tier limits |
+| `tests/unit/rateLimiter.test.ts` | Added | 8 tests covering burst, steady-state, and reset |
+
+### Test Plan
+
+- [ ] Verify 429 returned after exceeding limit
+- [ ] Verify `Retry-After` header is accurate
+- [ ] Verify rate limit resets after window expires
+- [ ] Load test confirms no false positives under normal traffic
+
+### Risk Assessment
+
+| Factor | Level | Notes |
+|--------|-------|-------|
+| **Scope** | Medium | 3 route files + new middleware |
+| **Data impact** | None | No schema changes |
+| **Security** | Low | Additive security improvement |
+| **Rollback** | Easy | Remove middleware from routes |
+
+### Breaking Changes
+
+None
+
+### Related
+
+- Closes #42
+```
+
+### Example 2: Bug Fix PR
+
+**Input:** Diff fixes an off-by-one error in pagination, adds a regression test.
+
+**Output:**
+
+```markdown
+## fix: correct off-by-one in cursor pagination
+
+### Summary
+
+- Fix pagination returning duplicate items when cursor falls on page boundary
+- Root cause: `>=` comparison should have been `>` in cursor offset calculation
+
+### Changes
+
+| File | Change | Description |
+|------|--------|-------------|
+| `src/db/pagination.ts` | Modified | Fix boundary comparison operator |
+| `tests/unit/pagination.test.ts` | Modified | Add regression test for boundary cursor |
+
+### Test Plan
+
+- [ ] Verify no duplicates at page boundary (regression test added)
+- [ ] Verify first page, last page, and empty result still work
+- [ ] Existing pagination tests still pass
+
+### Risk Assessment
+
+| Factor | Level | Notes |
+|--------|-------|-------|
+| **Scope** | Low | Single line fix + test |
+| **Data impact** | None | Read-only query change |
+| **Security** | None | No auth changes |
+| **Rollback** | Easy | Revert single commit |
+
+### Breaking Changes
+
+None
+
+### Related
+
+- Closes #87
+```

package/rules/hatch3r-accessibility-standards.md

@@ -0,0 +1,77 @@
+---
+id: hatch3r-accessibility-standards
+type: rule
+description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
+scope: always
+---
+# Accessibility Standards
+
+## WCAG 2.2 AA Compliance
+
+All user-facing features must meet WCAG 2.2 Level AA conformance. This is the baseline — Level AAA is aspirational for critical user flows.
+
+## Keyboard Navigation
+
+- All interactive elements must be reachable and operable via keyboard alone.
+- Tab order follows the visual reading order (left-to-right, top-to-bottom for LTR languages).
+- Never use `tabindex` values greater than 0. Use `tabindex="0"` to add to natural flow, `tabindex="-1"` for programmatic focus only.
+- Custom widgets implement standard keyboard patterns: arrow keys for navigation within a group, Enter/Space for activation, Escape to dismiss.
+- Keyboard traps are forbidden. Every focused element must have a keyboard-accessible exit.
+- Skip navigation links appear as the first focusable element on pages with repeated navigation.
+
+## Focus Management
+
+- Focus is visible at all times. Custom focus indicators must have a minimum 3:1 contrast ratio against the background.
+- When content changes dynamically (modals, drawers, toasts), move focus to the new content.
+- When a modal or dialog closes, return focus to the element that triggered it.
+- Single-page application route changes move focus to the main content heading or a skip link target.
+- Never remove focus outlines globally. If overriding browser defaults, provide an equally visible alternative.
+
+## Color and Contrast
+
+- Text contrast ratio: minimum 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold).
+- Non-text contrast: minimum 3:1 for UI components (borders, icons, form controls) and graphical objects.
+- Never convey information through color alone. Use additional indicators: icons, text labels, patterns.
+- Test with color blindness simulators (protanopia, deuteranopia, tritanopia).
+- Dark mode and light mode must independently meet contrast requirements.
+
+## Screen Reader Support
+
+- All images have meaningful `alt` text or `alt=""` for decorative images.
+- Form controls have associated `<label>` elements (using `for`/`id` or wrapping).
+- Use semantic HTML elements (`<nav>`, `<main>`, `<header>`, `<footer>`, `<section>`, `<article>`) before reaching for ARIA roles.
+- Dynamic content updates use `aria-live` regions: `polite` for non-urgent updates, `assertive` for critical alerts.
+- Tables have `<caption>` and use `<th scope="col|row">` for header cells.
+- Icon-only buttons include `aria-label` or visually hidden text.
+
+## ARIA Patterns
+
+- Follow the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) for all custom widgets.
+- ARIA role must match keyboard behavior — a `role="button"` element must respond to Enter and Space.
+- Use `aria-expanded`, `aria-selected`, `aria-checked` to communicate widget state.
+- `aria-describedby` links error messages and help text to form controls.
+- Avoid ARIA when native HTML provides the same semantics. First rule of ARIA: don't use ARIA if native HTML works.
+- Test ARIA implementations with at least two screen readers (VoiceOver + NVDA or JAWS).
+
+## Motion and Animation
+
+- All animations must respect `prefers-reduced-motion: reduce`. Disable non-essential motion.
+- Essential animations (progress indicators, loading states) simplify rather than disable entirely.
+- No content flashes more than 3 times per second (seizure safety — WCAG 2.3.1).
+- Auto-playing media has a visible pause/stop mechanism.
+
+## Forms and Input
+
+- Group related form controls with `<fieldset>` and `<legend>`.
+- Error messages identify the field in error and describe how to fix it.
+- Required fields are indicated both visually and programmatically (`aria-required="true"` or `required`).
+- Input validation provides feedback inline and in an error summary.
+- Time limits are either removable, adjustable (10x minimum), or preceded by a warning with option to extend.
+
+## Testing with Assistive Technology
+
+- Test with a screen reader on every feature branch that modifies UI.
+- Minimum testing matrix: VoiceOver (macOS/iOS) + Chrome, NVDA + Firefox (Windows).
+- Run automated accessibility checks (axe-core, Lighthouse) in CI.
+- Automated tools catch ~30% of accessibility issues. Manual testing is required for keyboard flows, screen reader experience, and cognitive accessibility.
+- Maintain an accessibility test checklist per component type (form, modal, navigation, data table).

package/rules/hatch3r-accessibility-standards.mdc

@@ -0,0 +1,75 @@
+---
+description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
+alwaysApply: true
+---
+# Accessibility Standards
+
+## WCAG 2.2 AA Compliance
+
+All user-facing features must meet WCAG 2.2 Level AA conformance. This is the baseline — Level AAA is aspirational for critical user flows.
+
+## Keyboard Navigation
+
+- All interactive elements must be reachable and operable via keyboard alone.
+- Tab order follows the visual reading order (left-to-right, top-to-bottom for LTR languages).
+- Never use `tabindex` values greater than 0. Use `tabindex="0"` to add to natural flow, `tabindex="-1"` for programmatic focus only.
+- Custom widgets implement standard keyboard patterns: arrow keys for navigation within a group, Enter/Space for activation, Escape to dismiss.
+- Keyboard traps are forbidden. Every focused element must have a keyboard-accessible exit.
+- Skip navigation links appear as the first focusable element on pages with repeated navigation.
+
+## Focus Management
+
+- Focus is visible at all times. Custom focus indicators must have a minimum 3:1 contrast ratio against the background.
+- When content changes dynamically (modals, drawers, toasts), move focus to the new content.
+- When a modal or dialog closes, return focus to the element that triggered it.
+- Single-page application route changes move focus to the main content heading or a skip link target.
+- Never remove focus outlines globally. If overriding browser defaults, provide an equally visible alternative.
+
+## Color and Contrast
+
+- Text contrast ratio: minimum 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold).
+- Non-text contrast: minimum 3:1 for UI components (borders, icons, form controls) and graphical objects.
+- Never convey information through color alone. Use additional indicators: icons, text labels, patterns.
+- Test with color blindness simulators (protanopia, deuteranopia, tritanopia).
+- Dark mode and light mode must independently meet contrast requirements.
+
+## Screen Reader Support
+
+- All images have meaningful `alt` text or `alt=""` for decorative images.
+- Form controls have associated `<label>` elements (using `for`/`id` or wrapping).
+- Use semantic HTML elements (`<nav>`, `<main>`, `<header>`, `<footer>`, `<section>`, `<article>`) before reaching for ARIA roles.
+- Dynamic content updates use `aria-live` regions: `polite` for non-urgent updates, `assertive` for critical alerts.
+- Tables have `<caption>` and use `<th scope="col|row">` for header cells.
+- Icon-only buttons include `aria-label` or visually hidden text.
+
+## ARIA Patterns
+
+- Follow the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) for all custom widgets.
+- ARIA role must match keyboard behavior — a `role="button"` element must respond to Enter and Space.
+- Use `aria-expanded`, `aria-selected`, `aria-checked` to communicate widget state.
+- `aria-describedby` links error messages and help text to form controls.
+- Avoid ARIA when native HTML provides the same semantics. First rule of ARIA: don't use ARIA if native HTML works.
+- Test ARIA implementations with at least two screen readers (VoiceOver + NVDA or JAWS).
+
+## Motion and Animation
+
+- All animations must respect `prefers-reduced-motion: reduce`. Disable non-essential motion.
+- Essential animations (progress indicators, loading states) simplify rather than disable entirely.
+- No content flashes more than 3 times per second (seizure safety — WCAG 2.3.1).
+- Auto-playing media has a visible pause/stop mechanism.
+
+## Forms and Input
+
+- Group related form controls with `<fieldset>` and `<legend>`.
+- Error messages identify the field in error and describe how to fix it.
+- Required fields are indicated both visually and programmatically (`aria-required="true"` or `required`).
+- Input validation provides feedback inline and in an error summary.
+- Time limits are either removable, adjustable (10x minimum), or preceded by a warning with option to extend.
+
+## Testing with Assistive Technology
+
+- Test with a screen reader on every feature branch that modifies UI.
+- Minimum testing matrix: VoiceOver (macOS/iOS) + Chrome, NVDA + Firefox (Windows).
+- Run automated accessibility checks (axe-core, Lighthouse) in CI.
+- Automated tools catch ~30% of accessibility issues. Manual testing is required for keyboard flows, screen reader experience, and cognitive accessibility.
+- Maintain an accessibility test checklist per component type (form, modal, navigation, data table).

package/rules/hatch3r-agent-orchestration.md

@@ -0,0 +1,160 @@
+---
+id: hatch3r-agent-orchestration
+type: rule
+description: Mandatory agent delegation, skill loading, and subagent usage directives for ALL tasks in ALL contexts
+scope: always
+---
+# Agent Orchestration
+
+This rule governs when and how to delegate work to hatch3r agents, load skills, and spawn subagents. These directives are mandatory — not suggestions.
+
+## Universal Applicability
+
+This rule applies to EVERY context without exception:
+
+- **Board-pickup** (epic, sub-issue, standalone, batch)
+- **Workflow command** (full mode and quick mode)
+- **Plain chat** (single task or multiple tasks)
+- **Issue references** (e.g., "implement #5")
+- **Natural language requests** (e.g., "add a dark mode toggle")
+
+Whether the user invokes a command or simply asks for a task in conversation, the full sub-agent pipeline defined below is mandatory. There is no context where implementing code inline (without sub-agents) is acceptable.
+
+## Universal Sub-Agent Pipeline
+
+Every task MUST follow this three-phase pipeline:
+
+**Phase 1 — Research:** Spawn `hatch3r-researcher` for context gathering. Skip only for trivial single-line edits (typos, comment fixes, single-value config changes). All other tasks require researcher context.
+
+**Phase 2 — Implement:** Spawn `hatch3r-implementer` for ALL code changes. One dedicated implementer per task. Never implement inline — always delegate via the Task tool.
+
+**Phase 3 — Quality:** Spawn ALL applicable specialists in parallel after implementation:
+
+| Specialist | When | Mandatory? |
+|-----------|------|------------|
+| `hatch3r-reviewer` | After every implementation | YES — always |
+| `hatch3r-test-writer` | After every code change | YES — always for code changes |
+| `hatch3r-security-auditor` | After every code change | YES — always for code changes |
+| `hatch3r-docs-writer` | After every implementation | EVALUATE — spawn when changes affect APIs, architecture, user-facing behavior, or when specs/ADRs need updating |
+| `hatch3r-lint-fixer` | When lint errors present | Conditional |
+| `hatch3r-a11y-auditor` | When UI/accessibility changes | Conditional |
+| `hatch3r-perf-profiler` | When performance-sensitive changes | Conditional |
+| `hatch3r-dependency-auditor` | When dependencies change | Conditional |
+| `hatch3r-ci-watcher` | When CI fails | Conditional |
+
+## Agent Roster
+
+| Agent | Purpose | Invoke When |
+|-------|---------|-------------|
+| `hatch3r-researcher` | Context gathering across 12 research modes | ALWAYS before implementation. Skip only for trivial single-line edits. Select modes by task type. |
+| `hatch3r-implementer` | Focused single-task implementation | ALWAYS. One dedicated implementer per task — standalone issues, epic sub-issues, batched issues, and plain chat tasks all get dedicated implementers. |
+| `hatch3r-reviewer` | Code review for quality, security, performance | ALWAYS after implementation, before PR creation. |
+| `hatch3r-test-writer` | Regression and coverage tests | ALWAYS for code changes. Not just bugs — every code change gets tests. |
+| `hatch3r-security-auditor` | Security rules, data flows, access control | ALWAYS for code changes. Not just `area:security` — every code change gets a security review. |
+| `hatch3r-docs-writer` | Specs, ADRs, documentation maintenance | ALWAYS evaluate. Spawn when changes affect APIs, architecture, or user-facing behavior. |
+| `hatch3r-lint-fixer` | Style, formatting, type error cleanup | After implementation when lint errors are present. |
+| `hatch3r-a11y-auditor` | WCAG AA compliance checks | When UI/accessibility changes are made. |
+| `hatch3r-perf-profiler` | Performance profiling and optimization | When performance-sensitive changes are made. |
+| `hatch3r-dependency-auditor` | Supply chain security, CVE scanning | When dependencies change or new packages are added. |
+| `hatch3r-ci-watcher` | CI/CD failure diagnosis and fix suggestions | When CI fails during or after implementation. |
+
+## Mandatory Delegation Directives
+
+### Context Gathering (Before Implementation)
+
+You MUST spawn a `hatch3r-researcher` subagent before implementing any task. Skip only for trivial single-line edits (typos, comment fixes, single-value config changes). Select research modes by task type:
+
+- **`type:bug`**: modes `symptom-trace`, `root-cause`, `codebase-impact`
+- **`type:feature`**: modes `codebase-impact`, `feature-design`, `architecture`
+- **`type:refactor`**: modes `current-state`, `refactoring-strategy`, `migration-path`
+- **`type:qa`**: modes `codebase-impact`
+
+Use depth `quick` for low-risk tasks, `standard` for medium-risk, `deep` for high-risk.
+
+### Implementation Delegation
+
+You MUST spawn a `hatch3r-implementer` subagent via the Task tool for ALL code changes. Never implement inline.
+
+- **Single standalone issue**: Spawn one `hatch3r-implementer`. The orchestrator coordinates git, PR, and board operations.
+- **Plain chat single task**: Spawn one `hatch3r-implementer`. Create synthetic issue context first (title, acceptance criteria, type).
+- **Epics with sub-issues**: Spawn one `hatch3r-implementer` per sub-issue. Execute level-by-level respecting dependency order.
+- **Multiple standalone issues (batch)**: Treat as a batch. Group by dependency level, spawn one `hatch3r-implementer` per issue, execute level-by-level. Shared branch, combined PR.
+
+### Post-Implementation Quality Pipeline
+
+You MUST spawn specialist subagents after implementation completes. Launch as many independent subagents in parallel as the platform supports — no artificial concurrency limit.
+
+**Always spawn (mandatory for every code change):**
+
+1. `hatch3r-reviewer` — code review. Include the diff and acceptance criteria in the prompt.
+2. `hatch3r-test-writer` — tests for all code changes. Unit tests for new logic, regression tests for bug fixes, integration tests for cross-module changes.
+3. `hatch3r-security-auditor` — security review of all code changes. Audit data flows, access control, input validation, and secret management.
+
+**Always evaluate (spawn when applicable):**
+
+4. `hatch3r-docs-writer` — spawn when changes affect public APIs, architectural patterns, user-facing behavior, or when specs/ADRs need updating. If no documentation impact exists, skip silently.
+
+**Conditional specialists (spawn when triggered):**
+
+5. `hatch3r-lint-fixer` — when lint or type errors are present after implementation.
+6. `hatch3r-a11y-auditor` — when UI or accessibility changes are made.
+7. `hatch3r-perf-profiler` — when performance-sensitive changes are made.
+8. `hatch3r-dependency-auditor` — when dependencies change or new packages are added.
+
+## Skill Loading Directives
+
+Before implementing any task, you MUST read and follow the matching hatch3r skill:
+
+| Task Type | Skill |
+|-----------|-------|
+| `type:bug` | `hatch3r-bug-fix` |
+| `type:feature` | `hatch3r-feature` (aka `hatch3r-feature-implementation`) |
+| `type:refactor` + `area:ui` | `hatch3r-visual-refactor` |
+| `type:refactor` + behavior change | `hatch3r-logical-refactor` |
+| `type:refactor` (other) | `hatch3r-refactor` (aka `hatch3r-code-refactor`) |
+| `type:qa` | `hatch3r-qa-validation` |
+
+When a skill references agents under "Required Agent Delegation", those delegations are mandatory — you MUST spawn the listed agents via the Task tool.
+
+## Subagent Spawning Protocol
+
+When spawning any subagent via the Task tool:
+
+1. **Use `subagent_type: "generalPurpose"`** for all hatch3r agent delegations.
+2. **Include in every subagent prompt**:
+   - The agent protocol to follow (e.g., "Follow the hatch3r-implementer agent protocol").
+   - All `scope: always` rules from `/.agents/rules/` that apply.
+   - The project's tooling hierarchy (Context7 MCP for library docs, web research for current context).
+   - Relevant learnings from `/.agents/learnings/` if the directory exists.
+3. **Launch as many independent subagents in parallel as the platform supports.** Do not impose an artificial concurrency limit. Use maximum parallelism for independent work.
+4. **Await and review results** before proceeding. If a subagent reports BLOCKED or PARTIAL, surface to the user.
+
+## Single-Task Plain Chat Protocol
+
+When the user provides a single task in plain chat (no command invoked, no issue reference), the full sub-agent pipeline still applies:
+
+1. **Classify** the task by type (bug/feature/refactor/QA/other) based on context.
+2. **Create synthetic issue context** — title, acceptance criteria, and type — from the user's instruction.
+3. **Run the Universal Sub-Agent Pipeline**: Phase 1 (Research) → Phase 2 (Implement) → Phase 3 (Quality).
+4. For GitHub issue references in chat (e.g., "fix #5"), fetch issue details via `gh issue view` and use them as the task context instead of creating synthetic context.
+
+This ensures consistent quality regardless of how the task was initiated.
+
+## Multi-Task Detection (Plain Chat)
+
+When the user provides multiple tasks in a single message — numbered lists, comma-separated instructions, multiple issue references (e.g., "implement #1, #3, #7"), or multiple distinct requests — you MUST parallelize them:
+
+1. **Parse** the message into individual discrete tasks. Each distinct implementation request is one task.
+2. **Classify** each task by type (bug/feature/refactor/QA/other) based on context or explicit labels.
+3. **Build a dependency graph** among the tasks. Independent tasks share the same level and run in parallel.
+4. **Spawn one `hatch3r-researcher` subagent per task** (skip for trivial single-line edits only). Launch in parallel.
+5. **Spawn one `hatch3r-implementer` subagent per task** per dependency level.
+6. **For GitHub issue references**: fetch issue details via `gh issue view` and use them as the task context.
+7. **For natural language tasks**: create synthetic issue context (title, acceptance criteria, type) from the instruction. Pass this context to the implementer subagent.
+8. **Spawn the full quality pipeline** after all implementations complete: reviewer + test-writer + security-auditor (always), plus docs-writer, auditors as applicable.
+
+This directive applies regardless of whether board-pickup was invoked. Any context where implementation tasks are identified MUST use one subagent per task with maximum parallelism.
+
+## Rule Application
+
+All hatch3r rules with `scope: always` apply to every implementation task, including work delegated to subagents. When constructing subagent prompts, include the rule directives — subagents do not automatically inherit the parent's rule context.