hatch3r 1.0.0

package/commands/hatch3r-feature-plan.md

@@ -0,0 +1,379 @@
+---
+id: hatch3r-feature-plan
+type: command
+description: Plan a single feature in depth -- spawn parallel researchers, produce feature spec, ADR(s), and structured todo.md entries for board-fill.
+---
+# Feature Plan — Single Feature Specification from Idea to Board-Ready Epic
+
+Take a single feature idea and produce a complete feature specification (`docs/specs/`), architectural decision records (`docs/adr/`) when needed, and structured `todo.md` entries (epic + sub-items) ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (codebase impact, feature design, architecture, risk & pitfalls) to analyze the feature from multiple angles before generating artifacts. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
+
+---
+
+## Shared Context
+
+**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+
+## Token-Saving Directives
+
+1. **Do not re-read files already cached.** Once researcher outputs are collected, reference them in memory — do not re-invoke sub-agents.
+2. **Limit documentation reads.** When reading existing project files for context, read TOC/headers first (~30 lines), expand only relevant sections.
+3. **Structured output only.** All sub-agent prompts require structured markdown output — no prose dumps.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Gather Feature Description
+
+1. **ASK:** "Tell me about the feature you want to plan. I need:
+   - **Feature name**
+   - **Description / goal** (one paragraph — what does it do and why is it needed?)
+   - **Target personas** (who benefits from this feature?)
+   - **Known constraints** (timeline, tech mandates, backward compatibility, etc.)
+
+   You can also point me to an existing spec section, PRD passage, or GitHub issue and I'll extract these from it."
+
+2. If the user provides a document reference or issue, read it and extract the four fields above.
+3. Present a structured summary:
+
+```
+Feature Brief:
+  Name:        {name}
+  Goal:        {one-paragraph description}
+  Personas:    {list with brief impact}
+  Constraints: {list}
+```
+
+**ASK:** "Does this capture the feature correctly? Adjust anything before I send this to the research phase."
+
+---
+
+### Step 2: Load Project Context
+
+1. Check for existing documentation:
+   - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
+   - `docs/adr/` — architectural decision records (scan for decisions relevant to the feature area)
+   - `README.md` — project overview
+   - `/.agents/hatch.json` — board configuration
+   - Existing `todo.md` — current backlog (check for overlap or related items)
+2. Scan GitHub issues via `search_issues` for existing work related to the feature. Note duplicates or partial overlaps.
+3. If `/.agents/learnings/` exists, scan for learnings relevant to the feature area. Match by area and tags against the feature brief.
+4. Present a context summary:
+
+```
+Context Loaded:
+  Specs:            {N} files in docs/specs/ ({relevant ones listed})
+  ADRs:             {N} files in docs/adr/ ({relevant ones listed})
+  Existing todo.md: {found with N items / not found}
+  Related issues:   {N} open issues with overlap ({list issue numbers})
+  Learnings:        {N} relevant learnings ({areas})
+  Gaps:             {list any missing context}
+```
+
+**ASK:** "Here is the context I loaded. Provide additional constraints, related work, or context? (or confirm to proceed)"
+
+---
+
+### Step 3: Spawn Parallel Researcher Sub-Agents
+
+Spawn one sub-agent per research domain below concurrently, each following the **hatch3r-researcher agent protocol**. Each receives the confirmed feature brief from Step 1 and the context summary from Step 2.
+
+**Each sub-agent prompt must include:**
+- The full confirmed feature brief
+- The project context summary from Step 2
+- Instruction to follow the **hatch3r-researcher agent protocol**
+- The assigned mode (one per sub-agent) and depth level `deep`
+
+| Sub-Agent | Researcher Mode | Focus |
+|-----------|----------------|-------|
+| 1 | `codebase-impact` | Map affected files, modules, integration points, coupling, and existing patterns |
+| 2 | `feature-design` | Break down into sub-tasks, user stories, acceptance criteria, edge cases, effort |
+| 3 | `architecture` | Data model, API contracts, component design, ADR candidates, dependencies |
+| 4 | `risk-assessment` | Technical risks, security, performance, breaking changes, common pitfalls |
+
+Each sub-agent produces the structured output defined by its mode in the hatch3r-researcher agent specification.
+
+Wait for all sub-agents to complete before proceeding.
+
+---
+
+### Step 4: Synthesize & Review Research
+
+1. Present a **merged summary** combining key findings from all researchers:
+
+```
+Research Summary:
+
+Feature:          {name}
+Affected files:   {N} files across {M} modules
+Sub-tasks:        {N} tasks ({X} parallelizable)
+Effort:           {total estimate}
+ADRs needed:      {N} architectural decisions
+Risks:            {N} risks ({X} high, {Y} med, {Z} low)
+Breaking changes: {N} ({list if any})
+Priority:         {recommended P-level}
+```
+
+2. **Highlight conflicts** between researchers. Common conflict types:
+   - Feature design researcher scopes work that the risk researcher flags as dangerous
+   - Architecture researcher proposes a pattern that contradicts existing codebase conventions found by the codebase impact researcher
+   - Effort estimates that seem inconsistent with the scope of changes identified
+
+3. For each conflict, present both sides and a recommended resolution.
+
+**ASK:** "Here is the merged research summary. Conflicts (if any) are highlighted above. Options:
+- **Confirm** to proceed with spec and todo generation
+- **Adjust** specific findings (tell me what to change)
+- **Re-run** a specific researcher with updated parameters
+- **Descope** to reduce the feature size"
+
+---
+
+### Step 5: Generate Feature Spec
+
+From the merged researcher outputs, generate a feature specification document. Present all content for review before writing any files.
+
+#### Feature Spec — `docs/specs/{NN}_{feature-slug}.md`
+
+Determine the next sequential number by scanning existing files in `docs/specs/`. Use slugified feature name (lowercase, hyphens).
+
+```markdown
+# {Feature Name}
+
+## Overview
+
+{2-3 sentence summary of the feature and its purpose, derived from the confirmed feature brief}
+
+## Scope
+
+### In Scope
+- {item derived from feature design researcher}
+
+### Out of Scope
+- {item — explicitly listed to prevent scope creep}
+
+## Personas Affected
+
+| Persona | Impact | Key Flows |
+|---------|--------|-----------|
+| {name} | {how this feature affects them} | {flows} |
+
+## Requirements
+
+| Req ID | Requirement | Priority | Source |
+|--------|-------------|----------|--------|
+| {feature-slug}-R01 | {requirement} | P0/P1/P2/P3 | {researcher / feature brief} |
+
+## Sub-Features
+
+| # | Sub-Feature | User Story | Acceptance Criteria | Effort |
+|---|-------------|-----------|---------------------|--------|
+| 1 | {title} | {story} | {criteria as checklist} | S/M/L/XL |
+
+## Architecture
+
+### Data Model Changes
+{From architecture researcher — tables, schemas, migrations}
+
+### API / Interface Contracts
+{From architecture researcher — endpoints, interfaces}
+
+### Component Design
+{From architecture researcher — new and modified components}
+
+## Dependencies
+
+| Depends On | Type | Status | Notes |
+|-----------|------|--------|-------|
+| {dependency} | Hard/Soft | Exists/Needs building | {notes} |
+
+## Edge Cases
+
+- {edge case}: {expected behavior}
+
+## Risks & Mitigations
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| {risk} | {level} | {strategy} |
+
+## Implementation Order
+
+{Topological ordering of sub-tasks with parallel lanes identified}
+
+1. {task} (prerequisite — no dependencies)
+2. {task} (depends on 1)
+3. {task} + {task} (parallel — both depend on 2)
+4. {task} (depends on 3)
+
+---
+
+**Owner / Reviewers / Last updated**
+Owner: {tbd}
+Reviewers: {tbd}
+Last updated: {today's date}
+```
+
+If a glossary exists (`docs/specs/00_glossary.md`), reference its stable IDs where applicable. If the feature introduces new entities or events, note them for glossary update.
+
+**ASK:** "Here is the generated feature spec. Review the content before I write the file:
+- `{NN}_{feature-slug}.md` — {sub-feature count} sub-features, {requirement count} requirements, {risk count} risks
+
+Confirm, or tell me what to adjust."
+
+---
+
+### Step 6: Generate ADR(s) (If Applicable)
+
+Only proceed if the architecture researcher identified decisions requiring ADRs in Step 3. If no ADRs are needed, skip to Step 7.
+
+From the architecture researcher's "Architectural Decisions Requiring ADRs" output, create one ADR per decision.
+
+#### ADR Format — `docs/adr/{NNNN}_{decision-slug}.md`
+
+Determine the next sequential number by scanning existing files in `docs/adr/`. Use slugified decision titles.
+
+```markdown
+# ADR-{NNNN}: {Decision Title}
+
+## Status
+
+Proposed
+
+## Date
+
+{today's date}
+
+## Context
+
+{Why this decision is needed — business and technical context, derived from the feature brief and architecture researcher findings}
+
+## Decision
+
+{What was decided and why}
+
+## Alternatives Considered
+
+| Alternative | Pros | Cons | Why Not |
+|-------------|------|------|---------|
+| {option} | {pros} | {cons} | {reason} |
+
+## Consequences
+
+### Positive
+- {consequence}
+
+### Negative
+- {consequence}
+
+### Risks
+- {risk}: {mitigation}
+
+## Related
+
+- Feature spec: `docs/specs/{NN}_{feature-slug}.md`
+```
+
+**ASK:** "Here are {N} ADR(s) generated from architectural decisions for this feature. Review before I write the files:
+{list with titles}
+
+Confirm, or tell me what to adjust."
+
+---
+
+### Step 7: Generate todo.md Entries
+
+From the feature design researcher's sub-task catalog and the synthesized research, generate structured `todo.md` entries in the format that `hatch3r-board-fill` expects.
+
+#### Entry Structure
+
+One **epic-level entry** with a description referencing the feature spec, followed by **individual sub-item entries** if the feature breaks into 2+ sub-tasks:
+
+```markdown
+- [ ] **{Feature name} epic**: {Feature overview, scope, key sub-tasks}. Ref: docs/specs/{NN}_{feature-slug}.md.
+- [ ] **{Sub-task 1 title}**: {Description with acceptance criteria summary}. Ref: docs/specs/{NN}_{feature-slug}.md.
+- [ ] **{Sub-task 2 title}**: {Description with acceptance criteria summary}. Ref: docs/specs/{NN}_{feature-slug}.md.
+```
+
+If the feature is small enough to be a single task (effort S or M, no meaningful sub-tasks), produce a single standalone entry instead of an epic.
+
+#### Placement
+
+Determine the appropriate priority header based on the priority recommended in Step 4. Place entries under the matching `## P{N} — {Label}` header.
+
+#### If `todo.md` Already Exists
+
+**ASK:** "todo.md already exists with {N} items. How should I add the new entries?
+- **(a) Append** under the appropriate priority header
+- **(b) Merge** — deduplicate against existing items and reorganize
+- **(c) Show me the entries** and I'll place them manually"
+
+#### If `todo.md` Does Not Exist
+
+Create a new `todo.md` with the appropriate priority header and the new entries.
+
+Present the drafted entries for review.
+
+**ASK:** "Here are the todo.md entries for this feature ({N} items — 1 epic + {M} sub-items). Review before I write:
+
+{entries}
+
+Confirm, or tell me what to adjust."
+
+---
+
+### Step 8: Write All Files
+
+After all content is confirmed:
+
+1. Write the feature spec to `docs/specs/{NN}_{feature-slug}.md`. Create the `docs/specs/` directory if it does not exist.
+2. Write ADR(s) to `docs/adr/{NNNN}_{decision-slug}.md` (if any). Create the `docs/adr/` directory if it does not exist.
+3. Write or update `todo.md` at the project root.
+4. If a glossary exists and the feature introduces new entities/events, note glossary updates needed (do not modify the glossary automatically — flag for manual update or a follow-up `project-spec` run).
+5. Present a summary of all files created or modified:
+
+```
+Files Created/Updated:
+  docs/specs/
+    {NN}_{feature-slug}.md    — {sub-feature count} sub-features, {requirement count} requirements
+  docs/adr/
+    {NNNN}_{decision}.md      — {decision title}  (if applicable)
+    ...
+  todo.md                      — {N} entries added ({1} epic + {M} sub-items)
+  Glossary update needed:      {yes/no — list new entities/events if yes}
+```
+
+---
+
+### Step 9 (Optional): Chain into Board-Fill
+
+**ASK:** "All files written. Run `hatch3r-board-fill` to create GitHub issues from the new todo.md entries? (yes / not now)"
+
+If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that board-fill will perform its own deduplication, grouping, dependency analysis, and readiness assessment on the entries.
+
+---
+
+## Error Handling
+
+- **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
+- **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
+- **File write failure:** Report the error and provide the full file content so the user can create the file manually.
+- **Missing project context:** If no `hatch3r-board-shared` or `/.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **No existing specs or docs:** Proceed without spec references. Warn that the feature spec will be less contextualized without existing project documentation. Recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` first for best results.
+- **Duplicate detection:** If the feature overlaps significantly with existing todo.md items or GitHub issues found in Step 2, present the overlap and ASK whether to proceed (augment existing / replace / abort).
+
+## Guardrails
+
+- **Never skip ASK checkpoints.** Every step with an ASK must pause for user confirmation.
+- **Never write files without user review and confirmation.** All generated content is presented first.
+- **Always delegate research to the hatch3r-researcher agent protocol.** Researcher sub-agents handle Context7 MCP, web research, and the tooling hierarchy internally.
+- **Stay within the feature scope** defined by the user in Step 1. Do not invent sub-features the user did not describe or imply. Flag scope expansion opportunities but do not act on them without explicit approval.
+- **todo.md must be compatible with board-fill format** — markdown checklist with bold titles, grouped by priority, referencing source specs.
+- **ADRs use the same format as `hatch3r-project-spec`** — Status, Date, Context, Decision, Alternatives, Consequences.
+- **Feature spec must reference existing glossary IDs** where a glossary exists. Do not create conflicting stable IDs.
+- **Do not over-specify.** Keep the spec at the right level of detail for board-fill to create actionable issues. Avoid implementation details that belong in code.
+- **All 4 researchers must complete before proceeding to Step 4.** Do not generate specs from partial research.
+- **Respect the project's tooling hierarchy** for knowledge augmentation: project docs first, then codebase exploration, then Context7 MCP, then web research.
+- **Preserve existing todo.md content.** Never overwrite or reorganize existing items without explicit user approval.

package/commands/hatch3r-healthcheck.md

@@ -0,0 +1,307 @@
+---
+id: hatch3r-healthcheck
+type: command
+description: Create a full-product QA and testing audit epic with one sub-issue per project module
+---
+# Healthcheck — Full Product QA & Testing Audit
+
+Create a healthcheck epic on **{owner}/{repo}** with one sub-issue per logical project module, plus cross-module wiring and vision/roadmap alignment audits. Each sub-issue is a deep static-analysis audit task that, when picked up by the board workflow, produces a findings epic with actionable sub-issues for achieving full QA and testing coverage. The command only creates the initial audit epic — it does NOT execute any audits.
+
+---
+
+## Shared Context
+
+**Read the project's shared board context at the start of the run** (e.g., `.cursor/commands/board-shared.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
+
+## Token-Saving Directives
+
+Follow any **Token-Saving Directives** in the shared context file.
+
+---
+
+## Module Discovery
+
+The product is divided into logical modules. Discover modules from the project structure:
+
+1. **Scan for modules:** Inspect top-level directories (e.g., `src/`, `functions/`, `packages/`) and identify logical units.
+2. **Map to specs:** If `docs/specs/` exists, map each module to relevant spec files.
+3. **Build taxonomy:** Produce a table of modules with their directories and primary specs.
+
+Example structure (adapt to project):
+
+| # | Module | Directories | Primary Specs |
+|---|--------|-------------|----------------|
+| 1 | Core Engine | `src/engine/` | `02_core-engine.md` |
+| 2 | Events | `src/events/` | `03_event-model.md` |
+| ... | ... | ... | ... |
+
+Plus two cross-cutting audits:
+
+| # | Audit | Scope |
+|---|-------|-------|
+| W | Cross-Module Wiring | Integration points between all modules |
+| R | Product vs Vision, Roadmap & Concept Alignment | Implementation vs product vision, roadmap, and specs |
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Load Context & Pre-Flight Check
+
+1. Read the shared board context and cache GitHub Context, Projects v2 config, and sync procedure.
+2. If `docs/specs/00_glossary.md` exists, read the first 30 lines for TOC/section headers.
+3. Scan for existing healthcheck epics: `search_issues` with `owner: {owner}`, `repo: {repo}`, query `label:meta:healthcheck state:open`.
+4. If an open healthcheck epic exists:
+
+**ASK:** "An open healthcheck epic already exists: #{number} — {title}. (a) Abort, (b) close the existing one and create a new healthcheck, (c) proceed and create a second healthcheck."
+
+5. Fetch all open issues (`list_issues`, paginate, exclude `meta:board-overview`). Cache for Board Overview regeneration in Step 7.
+
+---
+
+### Step 2: Determine Audit Modules
+
+1. Build the module taxonomy from directory structure (see Module Discovery above).
+2. If the user specified specific modules in their invocation, filter the taxonomy to only those modules. The two cross-cutting audits (Wiring, Roadmap) are always included unless the user explicitly excludes them.
+3. Validate that the directories for each selected module exist in the workspace. Warn if any directory is missing.
+
+Present the selected modules:
+
+```
+Healthcheck Audit Scope:
+
+Level 1 (parallel):
+  1. {Module 1} — {path}/
+  2. {Module 2} — {path}/
+  ...
+
+Level 2 (after all Level 1 complete):
+  W. Cross-Module Wiring — integration points
+  R. Product vs Vision, Roadmap & Concept Alignment — vision + roadmap + specs
+```
+
+**ASK:** "These modules will be audited. Confirm, add, or remove modules."
+
+---
+
+### Step 3: Create Healthcheck Epic
+
+Create the parent epic via `issue_write` with `method: create`, `owner: {owner}`, `repo: {repo}`.
+
+**Title:** `[Healthcheck]: Full Product QA & Testing Audit`
+
+**Labels:** `type:epic`, `meta:healthcheck`, `status:ready`, `executor:agent`, `priority:p1`, `area:testing`
+
+**Body:**
+
+```markdown
+## Overview
+
+Full-product healthcheck audit covering {N} logical modules plus cross-module wiring and roadmap alignment analysis. Each sub-issue performs a deep static analysis of one module and produces a findings epic with actionable sub-issues for achieving full QA and testing coverage.
+
+## Sub-Issues
+
+### Level 1 — Module Audits (parallel)
+
+- [ ] #{part-1} — Audit: {Module 1}
+- [ ] #{part-2} — Audit: {Module 2}
+      ...
+
+### Level 2 — Cross-Cutting Audits (after all Level 1)
+
+- [ ] #{wiring} — Audit: Cross-Module Wiring
+- [ ] #{roadmap} — Audit: Product vs Vision, Roadmap & Concept Alignment
+
+## Implementation Order
+
+### 1
+
+- [ ] #{part-1} — Audit: {Module 1}
+- [ ] #{part-2} — Audit: {Module 2}
+      ...all module audits...
+
+### 2 -- after #{part-1}, #{part-2}, ... #{part-N}
+
+- [ ] #{wiring} — Audit: Cross-Module Wiring
+- [ ] #{roadmap} — Audit: Product vs Vision, Roadmap & Concept Alignment
+
+## Acceptance Criteria
+
+- [ ] All sub-issue audits completed
+- [ ] One findings epic created per audited module (with `meta:healthcheck-findings` label)
+- [ ] All findings epics have sub-issues with acceptance criteria
+- [ ] All findings epics integrated into Projects v2 board
+- [ ] Cross-cutting findings epics have correct dependencies on module findings epics
+
+## Dependencies
+
+None.
+```
+
+Record the returned `number` and internal numeric `id` for the epic.
+
+---
+
+### Step 4: Create Module Audit Sub-Issues
+
+For each module in the selected taxonomy, create a sub-issue via `issue_write` with `method: create`.
+
+**Title:** `Audit: {Module Name}`
+
+**Labels:** `type:qa`, `status:ready`, `executor:agent`, `priority:p1`
+
+**Body:** Use the Module Audit Sub-Issue Template below, filling in the module-specific fields.
+
+After creating each sub-issue, link it to the parent epic via `sub_issue_write` with `method: add`, using the parent `issue_number` and the child's internal numeric `id`.
+
+Record all returned sub-issue numbers for use in Step 5.
+
+#### Module Audit Sub-Issue Template
+
+```markdown
+## Audit: {Module Name}
+
+> Parent: #{healthcheck-epic-number} — [Healthcheck]: Full Product QA & Testing Audit
+
+### Scope
+
+**Directories:** {comma-separated directory paths from taxonomy}
+**Primary Specs:** {spec filenames from taxonomy}
+**Test Directories:** Search `tests/unit/`, `tests/integration/`, `tests/e2e/`, `tests/rules/` for files matching this module.
+
+### Audit Protocol
+
+Perform a deep static analysis of this module. Do NOT execute tests or modify code — review source files, spec documents, and existing test files only.
+
+#### 1. Test Coverage Analysis
+
+- List all exported functions, classes, and modules in the scope directories
+- Map each to existing test files in `tests/`
+- Identify untested code paths and missing test scenarios
+- Assess test quality: meaningful assertions, edge cases, error paths
+
+#### 2. Spec Compliance
+
+- Read the referenced specs fully
+- Compare implementation against every requirement in the spec
+- Flag deviations, partial implementations, and missing features
+
+#### 3. Testing Pyramid Assessment
+
+- Unit tests: coverage percentage estimate and quality assessment
+- Integration tests: cross-module interactions and contract tests
+- E2E tests: critical user flows covered for this module
+- Security tests: invariants validated
+- Performance tests: budget compliance verified
+
+#### 4. Code Quality
+
+- Error handling completeness (all error paths covered)
+- Edge case coverage (boundary values, empty states, overflow)
+- Input validation at module boundaries
+- TypeScript strict mode compliance (no `any`, no `@ts-ignore` without linked issue)
+- Max function length and file length compliance per project standards
+
+#### 5. Performance & Privacy
+
+- Performance budget compliance per project quality docs
+- Privacy invariant adherence per project security docs
+
+### Output — Findings Epic
+
+After completing the audit, create a findings epic on GitHub.
+
+**Create via `issue_write`:**
+
+- **Title:** `[QA Findings]: {Module Name}`
+- **Labels:** `type:epic`, `meta:healthcheck-findings`, `status:ready`, `executor:agent`, `priority:p1`
+- **Body:** Overview of findings count and severity, sub-issues checklist, implementation order, acceptance criteria ("done when all finding sub-issues are resolved").
+
+**Create sub-issues** — one per actionable finding. Each must include:
+
+- Problem description with evidence (file paths, line references, spec section)
+- Suggested fix approach
+- Acceptance criteria (specific and testable)
+- Labels: `type:qa` for test gaps, `type:bug` for spec deviations, `type:refactor` for code quality, plus relevant `area:*` label
+
+**Link sub-issues** to the findings epic via `sub_issue_write`.
+
+**Board integration** — for the findings epic and every sub-issue:
+
+Follow the **Projects v2 Sync Procedure** from `hatch3r-board-shared` (gh CLI primary). Set status to Ready using the project's status field option ID.
+
+### Completion
+
+Return to the parent orchestrator with:
+
+- Findings epic issue number
+- Total findings count
+- Breakdown by type (test gaps, spec deviations, code quality, performance, privacy)
+- Any blockers encountered
+```
+
+---
+
+### Step 5: Create Cross-Cutting Audit Sub-Issues
+
+Create two additional sub-issues with dependencies on all module audit sub-issues.
+
+#### 5a. Cross-Module Wiring Audit
+
+**Title:** `Audit: Cross-Module Wiring`
+
+**Labels:** `type:qa`, `status:ready`, `executor:agent`, `priority:p1`, `has-dependencies`
+
+**Body:** Scope: Analyze integration points between all project modules. This audit runs AFTER all module audits complete — use their findings for additional context. Follow the same Output — Findings Epic instructions as module audits. Include Dependencies section: Blocked by #{part-audit-1}, #{part-audit-2}, ... #{part-audit-N}
+
+Link to parent epic via `sub_issue_write`.
+
+#### 5b. Product vs Vision, Roadmap & Concept Alignment Audit
+
+**Title:** `Audit: Product vs Vision, Roadmap & Concept Alignment`
+
+**Labels:** `type:qa`, `status:ready`, `executor:agent`, `priority:p1`, `has-dependencies`
+
+**Body:** Scope: Compare the current implementation against the product vision, roadmap, and all specification documents. This audit runs AFTER all module audits complete. Include Dependencies section: Blocked by #{part-audit-1}, #{part-audit-2}, ... #{part-audit-N}. Follow the same Output — Findings Epic instructions.
+
+Link to parent epic via `sub_issue_write`.
+
+---
+
+### Step 6: Finalize Epic & Set Dependencies
+
+1. **Update the healthcheck epic body** with the actual sub-issue numbers in the Sub-Issues checklist and Implementation Order section. Use `issue_write` with `method: update`.
+
+2. **Verify dependency sections** on the wiring and roadmap sub-issues contain the correct module audit sub-issue numbers.
+
+3. Present a summary with epic number, sub-issues, and total count.
+
+---
+
+### Step 7: Board Integration
+
+1. **Projects v2 Sync:** Follow the **Projects v2 Sync Procedure** from `hatch3r-board-shared` (gh CLI primary) for the healthcheck epic and ALL sub-issues. Set status to Ready using the project's status field option ID.
+
+2. **Board Overview Regeneration:** Regenerate the Board Overview using the **Board Overview Template** from the shared context. Use cached board data from Step 1, updated with the newly created healthcheck epic. Skip silently if no board overview issue exists.
+
+---
+
+## Error Handling
+
+- `search_issues` failure: retry once, then warn and proceed (assume no existing healthcheck).
+- `issue_write` failure: report the error, retry once. If still failing, present the drafted body for manual creation.
+- `sub_issue_write` failure: report but do not delete the created sub-issue. Note the unlinking for manual fix.
+- Projects v2 sync failure (gh CLI or MCP): warn and continue. Board sync can be fixed later via board-refresh.
+
+## Guardrails
+
+- **Never skip ASK checkpoints.**
+- **Use GitHub MCP tools for issue operations** (create, update, link). For Projects v2 board integration, follow the sync procedure from hatch3r-board-shared (gh CLI primary).
+- **The command ONLY creates issues.** It does NOT execute any audits, run tests, or modify code.
+- **Always include the `meta:healthcheck` label** on the healthcheck epic.
+- **Always include `meta:healthcheck-findings`** in the output instructions for audit sub-issues.
+- **Preserve dependency ordering.** Level 2 sub-issues must reference all Level 1 sub-issues in their Dependencies section.
+- **Board Overview is auto-maintained.** Exclude it from all analysis. One board overview issue at a time.
+- **Do not expand scope.** The command creates exactly the discovered modules plus the two cross-cutting audits. No additional issue types.