/hatch3r-roadmap

§0 Detect Ambiguity (P8 B1)

Orchestration boilerplate: see commands/shared/orchestration-frame.md → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.

Roadmap — Generate Phased Roadmap from Specs & Vision

Generate a dependency-aware, priority-ordered roadmap with two parallel dimensions: business milestones and technical milestones. Spawns parallel researcher sub-agents (business priority, technical readiness) to inform prioritization with market timing, competitive pressure, revenue impact, and production readiness gaps. Outputs to todo.md in the exact format that hatch3r-board-fill expects, with items tagged as [BIZ], [TECH], or [BOTH]. Optionally generates a root-level AGENTS.md. Works for both greenfield projects (from hatch3r-project-spec output) and brownfield projects (from hatch3r-codebase-map output).

Agent Pipeline

Stage	Agent(s)	Parallel	Required
1. Research	hatch3r-researcher (2 parallel: Business Priority, Technical Readiness)	Yes	Yes
2. Document Generation	hatch3r-docs-writer (todo.md generation)	No	Yes
3. AGENTS.md	hatch3r-docs-writer (AGENTS.md generation/rework)	No	Yes

Parallel-safety conditions (per rules/hatch3r-agent-orchestration.md §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.

---

Shared Context

Read the hatch3r-board-shared skill at the start of the run. It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.

Token-Saving Directives

Follow the Token-Saving Directives in hatch3r-board-shared.

Confidence Propagation Contract

Every sub-agent delegation prompt in this command MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the quality_charter: agents/shared/quality-charter.md reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.

Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (agents/shared/quality-charter.md). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.

Downstream propagation: every business-priority and technical-readiness recommendation (market-timing, revenue-impact ordering, debt-velocity estimate) carries a high/medium/low confidence rating sourced from the researcher sub-agent — web-sourced market estimates are medium at best unless tied to a cited benchmark. The Step 4 roadmap presentation and Step 6 summary MUST preserve the signal. Dropping it between stages is a gate failure.

---

Workflow

Execute these steps in order. Do not skip any step. Ask the user at every checkpoint marked with ASK. When in doubt, ASK — it is better to ask one question too many than to make one wrong assumption. Discovery questions are never wasted.

Step 0: Triage

Classify the roadmap request before delegating:

• Tier 1 (trivial): small project with focused scope (under 20 backlog items), single dimension (technical only); reduced fanout (1 researcher: Technical Readiness) and condensed todo.md output.
• Tier 2 (standard): standard dual-lens roadmap (business + technical) with both researchers; standard pipeline with parallel research and AGENTS.md generation.
• Tier 3 (deep): enterprise/scale company with regulatory deadlines, multi-quarter horizon, or 50+ backlog items; full pipeline with deep web research and confirm milestones with the user before writing files.

If Tier 1, run the reduced researcher set and skip Step 7 (AGENTS.md) unless requested. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline with deep research, surface market-timing intelligence, and confirm phased plan with the user before file writes.

Step 0.5: Emit Pre-Execution Cost Preview

Before the first sub-agent dispatch (Step 3 parallel researchers), surface the cost preview so a deep-research roadmap run is never started blind. Emit the cost_estimate block per rules/hatch3r-cost-visibility.md Pre-Execution Estimate, calibrated to the Step 0 triage tier:

cost_estimate:
  expected_sa_count: <triage tier → Tier 1 ~1 (technical-readiness only), Tier 2 ~2-3, Tier 3 up to 3 (+ AGENTS.md docs-writer)>
  estimated_input_tokens_static_frame: <int>
  estimated_web_research_queries: <int>            # market + benchmark research; Tier 3 is web-heavy
  triage_tier: light | standard | deep
  estimated_duration_min: <int>

The Step 1 business-discovery interview is user-driven and excluded from the duration estimate. Post-execution actuals + delta land in the Iteration Summary recap (cost facet; full blocks on the Cost: exception line beyond ±25%) per rules/hatch3r-cost-visibility.md Post-Execution Actuals. Token telemetry sources from src/pipeline/observability.ts.

Effort Override (Decision 17)

Auto-tiering can misclassify — a focused single-dimension roadmap scored as Deep, or an enterprise multi-quarter roadmap scored as Light. The user override is the recovery path mandated by hatch3r's universal --effort override contract ("User overridable via --effort flag"):

• --effort=light|standard|deep forces the named tier, bypassing the Step 0 auto-classification (which controls researcher count and web-research depth).
• The override wins over the auto-detected tier; record both the auto-detected tier and the override in the run context so the Cost estimate block reports the budget delta.
• No override passed → the Step 0 auto-classification stands.

---

Step 1: Load Project Context & Business Discovery

1a. Load Existing Documentation

1. Check for existing documentation:
   • docs/specs/technical/ — technical specifications
   • docs/specs/business/ — business specifications
   • docs/specs/ (flat) — legacy spec layout (pre-dual-lens)
   • docs/adr/ — architectural decision records
   • docs/codebase-health.md — health report (from codebase-map)
   • Existing todo.md — current backlog
   • README.md — project overview
   • Root AGENTS.md — existing agent instructions
2. Read discovered documents selectively — TOC/headers first (first ~30 lines), full content only for sections relevant to roadmap planning.
3. If no docs exist, ASK user for project vision and goals (text input or reference to a document).
4. For brownfield projects: scan current GitHub issues via gh issue list --state open --limit 100 to understand existing tracked work. Paginate if more than 100 issues.

1b. Load Session Context

Check for .hatch3r-session.json (written by hatch3r-codebase-map or hatch3r-project-spec). If found, pre-fill company stage and business context. Confirm with the user rather than re-asking.

1c. Onboarding Scope Selection

ASK: "Should I generate a roadmap for the full product, or only specific parts? If specific, list the domains, modules, or feature areas to focus on."

1d. Company Stage Assessment

If not loaded from .hatch3r-session.json:

ASK: "To calibrate the roadmap to your situation, tell me about your company/project stage:

• Company stage: pre-revenue / early-revenue / growth / scale / enterprise
• Team composition: solo founder, small team (2-5), medium (5-20), large (20+)
• Current user/revenue scale: no users yet, beta (<1K), early traction (1K-50K), growth (50K-500K), scale (500K+)
• Funding/runway: bootstrapped, pre-seed, seed, Series A+, profitable
• Regulatory/compliance needs: none, basic (GDPR/SOC2), heavy (HIPAA/PCI/FedRAMP)
• Deployment maturity: no deployment yet, manual, CI/CD, full GitOps"

Cache the stage assessment. It drives stage-adaptive prioritization:

• Pre-revenue / early-revenue: Prioritize speed-to-market. Front-load core value delivery and minimum viable infrastructure. Defer polish and scale.
• Growth: Prioritize scaling bottlenecks and retention features. Balance new features with production hardening.
• Scale / enterprise: Prioritize reliability, compliance, and governance. Front-load SLA readiness and security hardening.

1e. Business Context & Roadmap Goals

ASK: "To build a business-aware roadmap, I need additional context:

• Target launch date or next major milestone: when is the next business deadline?
• Key business KPIs for the next 6-12 months: what metrics define success?
• Team capacity: how many devs, approximate hours/week available?
• Market timing pressures: competitor launches, regulatory deadlines, seasonal peaks, funding milestones?
• Revenue targets: any specific revenue or user growth targets for the next 6-12 months?
• Dependencies on external parties: partners, vendors, API providers, design agencies?

Any other priorities or constraints I should factor into the roadmap?"

1f. Present Context Summary

Context Loaded:
  Technical Specs: {N} files in docs/specs/technical/
  Business Specs:  {N} files in docs/specs/business/
  ADRs:            {N} files in docs/adr/
  Health report:   {found / not found}
  Existing todo.md: {found with N items / not found}
  AGENTS.md:       {found / not found}
  Open GitHub issues: {N}
  Session context: {loaded from .hatch3r-session.json / gathered fresh}

Company Stage:    {stage}
Team Capacity:    {N} devs, {hours}/week
Next Milestone:   {milestone} by {date}
Key KPIs:         {list}
Market Pressures: {list or none}

Gaps: {list any missing context}

ASK: "Here is the context I loaded. Provide additional goals, constraints, or priorities? (or confirm to proceed)"

---

Step 2: Analyze & Categorize Work

1. From technical specs: extract all requirements, acceptance criteria, and gaps.
2. From business specs: extract business rules, GTM requirements, competitive gaps, and production readiness gaps.
3. From ADRs: extract pending decisions and their implementation work.
4. From health report (if exists): extract debt items and improvement opportunities.
5. From existing GitHub issues: map already-tracked work to avoid duplication.
6. Categorize all work items by:

Dimension	Values
Scope	[BIZ] business-driven, [TECH] technically-driven, [BOTH] cross-cutting
Domain/area	Which module, subsystem, or business domain does this touch?
Type	feature, bug fix, refactor, infrastructure, documentation, QA, GTM, compliance
Effort	S (< 1 day), M (1-3 days), L (3-5 days), XL (> 5 days, should be an epic)
Impact	critical path, quality of life, nice-to-have, revenue-blocking, scale-blocking
Dependencies	What must come first? (both technical and business dependencies)

7. Present a categorized summary table of all extracted work items, with separate sections for business-driven, technically-driven, and cross-cutting items.

---

Step 3: Spawn Parallel Research Sub-Agents

Launch one sub-agent per research domain below concurrently using the Task tool with subagent_type: "generalPurpose". Each receives the full context from Steps 1-2.

Both sub-agent prompts must include:

• All loaded project context (specs, ADRs, health report, existing backlog)
• Company stage, business context, and roadmap goals from Step 1
• The categorized work items from Step 2
• Instruction to use web search for market research, benchmarks, and best practices
• Explicit instruction: do NOT create any files — return output as a structured result

Sub-Agent 1: Business Priority Researcher

Prompt context: Full project context, business specs, company stage, market pressures, KPIs.

Task: Research and recommend business-driven prioritization using web search for market intelligence.

1. Market timing windows:
   • Research the product category for seasonal patterns, industry events, regulatory deadlines
   • Identify windows of opportunity (competitor gaps, market shifts, funding cycles)
   • Flag time-sensitive items that must ship by a specific date
2. Competitive pressure analysis:
   • Research competitor release cadences and recent launches
   • Identify feature gaps that competitors are filling (urgency signals)
   • Find differentiation opportunities that should be prioritized
3. Revenue-impact ordering:
   • Which features drive conversion most? (based on industry benchmarks)
   • Which features drive retention most? (churn reduction)
   • Which features unlock new revenue streams or market segments?
   • Order features by expected revenue impact
4. Regulatory deadlines:
   • Research compliance timelines for the product's industry and geography
   • Identify must-have certifications and their lead times
   • Flag regulatory blockers that constrain launch timing
5. User acquisition channel requirements:
   • What technical capabilities are needed for each GTM channel (PLG requires self-serve, SEO requires content, API-first requires docs)
   • Order channel enablement work by expected ROI

Output structure:

## Business Priority Intelligence

### Market Timing
| Window | Deadline | Items Affected | Priority Impact |
|--------|----------|---------------|----------------|
| {window} | {date} | {items} | {how it changes priority} |

### Competitive Urgency
| Feature/Area | Competitor Activity | Urgency | Recommendation |
|-------------|-------------------|---------|----------------|
| {area} | {what competitors are doing} | high/med/low | {action} |

### Revenue Impact Ordering
| Rank | Feature/Area | Revenue Mechanism | Impact Estimate | Evidence |
|------|-------------|-------------------|-----------------|----------|
| 1 | {feature} | {conversion/retention/expansion/new segment} | {high/med/low} | {benchmark or reasoning} |

### Regulatory Timeline
| Requirement | Deadline | Effort | Blocking |
|------------|----------|--------|----------|
| {requirement} | {date} | {S/M/L/XL} | {what it blocks} |

### Channel Requirements
| Channel | Required Capabilities | Priority | Expected ROI |
|---------|---------------------|----------|-------------|
| {channel} | {what needs to be built} | {P0-P3} | {high/med/low} |

### Recommended Business Milestones
1. {milestone}: {date target} — {what it unlocks}
2. ...

Sub-Agent 2: Technical Readiness Researcher

Prompt context: Full project context, technical specs, health report, company stage.

Task: Evaluate technical readiness and recommend infrastructure prioritization. Use web search for industry benchmarks and best practices.

1. Tech debt velocity impact:
   • Which debt items slow down feature delivery most?
   • Quantify: "fixing X would speed up Y by approximately Z%"
   • Recommend debt paydown ordering by delivery velocity impact
2. Infrastructure prerequisites for scaling milestones:
   • What infrastructure must be in place before hitting 1K, 10K, 100K users?
   • Map infrastructure gaps to business milestones
   • Flag "too late to fix" items that need lead time
3. Production readiness gaps blocking launch/growth:
   • What's missing for a credible production launch?
   • What's missing for scaling beyond initial traction?
   • Grade each gap by business impact
4. Technical dependencies constraining business priorities:
   • Which business features are blocked by technical prerequisites?
   • Build a dependency graph: business priorities → technical enablers
   • Identify the critical path through technical enablers
5. Industry benchmarks for performance/reliability:
   • Research performance benchmarks for the product category (page load times, API latency, uptime)
   • Research reliability expectations for the company stage
   • Identify gaps between current state and benchmarks

Output structure:

## Technical Readiness Intelligence

### Debt Velocity Impact
| Debt Item | Affected Areas | Velocity Impact | Fix Effort | ROI |
|-----------|---------------|----------------|-----------|-----|
| {item} | {modules} | {estimated slowdown} | {S/M/L/XL} | {high/med/low} |

### Infrastructure Milestones
| User Milestone | Prerequisites | Current State | Gap | Lead Time |
|---------------|--------------|--------------|-----|-----------|
| 1K users | {list} | {status} | {missing} | {days} |
| 10K users | {list} | {status} | {missing} | {days} |
| 100K users | {list} | {status} | {missing} | {days} |

### Production Readiness Blockers
| Blocker | Business Impact | Fix Effort | Deadline |
|---------|----------------|-----------|----------|
| {blocker} | {what it blocks} | {S/M/L/XL} | {when needed} |

### Technical → Business Dependency Map
| Business Priority | Technical Prerequisites | Status |
|------------------|----------------------|--------|
| {business item} | {technical items that must come first} | {ready/blocked} |

### Performance Benchmarks
| Metric | Industry P50 | Industry P90 | Current | Gap |
|--------|-------------|-------------|---------|-----|
| {metric} | {value} | {value} | {value or unknown} | {gap} |

### Recommended Technical Milestones
1. {milestone}: {deadline} — {what it enables}
2. ...

Wait for all sub-agents to complete before proceeding.

---

Step 4: Generate Dual-Lens Phased Roadmap

Merge the categorized work items from Step 2 with the research intelligence from Step 3 to build a roadmap with two parallel dimensions.

4a. Business Milestones Lane

Map business-driven milestones across the timeline:

Milestone Type	Examples
Revenue milestones	Launch, first paying customer, MRR targets, break-even
User acquisition milestones	Beta launch, public launch, growth targets, market expansion
Market timing milestones	Competitive windows, seasonal peaks, conference launches
Compliance milestones	Certifications, audits, regulatory deadlines
Fundraising milestones	Metrics needed for next round, demo-ready state

4b. Technical Milestones Lane

Map technically-driven milestones across the timeline:

Milestone Type	Examples
Infrastructure readiness	MVP infra (solo tier), scaling infra (team/scaleup tier), multi-region, enterprise tier per CONSTITUTION §6 Decision 4
Production hardening	Monitoring, alerting, incident response, SLA readiness
Technical debt paydown	Prioritized by business impact (velocity improvement)
Platform capabilities	APIs, integrations, extensibility, developer experience
Security & compliance	Auth hardening, vulnerability scanning, audit trails

4c. Phase Rules (Enhanced)

Phase	Label	Business Criteria	Technical Criteria
P0	Critical / Launch Blockers	Revenue-blocking features, regulatory deadlines, market timing windows	Security fixes, data integrity, core infrastructure dependencies
P1	Core Features	Primary value-delivering features, conversion-critical flows, first GTM channel enablement	Essential integrations, performance baselines, CI/CD, compound system integrity checks
P2	Important	Secondary features, retention improvements, additional GTM channels	Quality improvements, significant refactors, testing gaps, monitoring
P3	Nice to Have	Polish, upsell features, market expansion preparation	Optimizations, non-critical enhancements, developer experience
P4+	Future Ideas	Long-term market plays, new segments, platform strategy	Long-term architecture evolution, experimental technology

4d. Within Each Priority Tier

1. Order by dependency (both technical and business prerequisites first).
2. Group related items into epics (2+ related items = epic candidate).
3. Identify parallel work lanes (independent business and technical tracks that can be worked simultaneously).
4. Estimate effort for each item/epic.
5. Map business milestones to the technical items that enable them.
6. Calibrate to team capacity from Step 1e.

4e. Present the Roadmap

Roadmap Overview:
  P0: N items (N BIZ, N TECH, N BOTH) — estimated effort: X days
  P1: N items (N BIZ, N TECH, N BOTH) — estimated effort: X days
  P2: N items (N BIZ, N TECH, N BOTH) — estimated effort: X days
  P3: N items (N BIZ, N TECH, N BOTH) — estimated effort: X days
  Future: N items

Business Milestones:
  {date/phase}: {milestone} — requires: {items}
  {date/phase}: {milestone} — requires: {items}

Technical Milestones:
  {date/phase}: {milestone} — enables: {business items}
  {date/phase}: {milestone} — enables: {business items}

Parallel Lanes:
  Lane A (Business): {theme} — P0 items 1-3, P1 items 4-5
  Lane B (Technical): {theme} — P0 items 6-7, P1 items 8-10
  Lane C (Cross-cutting): {theme} — P0 items 11-12

Critical Path: item 1 → item 3 → item 5 → item 8
Business-Critical Path: {biz milestone 1} → {biz milestone 2} → {launch}

ASK: "Here is the proposed dual-lens roadmap with business and technical milestones. Review:

• Are the business milestones and their timelines realistic?
• Are the technical prerequisites mapped with accurate dependency links?
• Adjust priorities, add/remove items, change grouping? (confirm / adjust)"

---

Step 5: Generate todo.md

Write todo.md in the canonical Todo Grammar defined in hatch3r-board-shared — the single source of truth that hatch3r-board-fill Step 1 parses. Emit ## P{N} — {Label} priority headers and - [ ] **[BIZ|TECH|BOTH] {title}**: {description}. Ref: {path}. item lines exactly as the grammar specifies; the template below is the authoring example for this command.

Format specification:

## P0 — Critical / Launch Blockers

- [ ] **[TECH] {Infrastructure item}**: {Description. Scope: {what's in}. Enables: {business milestone}.} Ref: docs/specs/technical/{spec}.md.
- [ ] **[BIZ] {Market-driven item}**: {Description. Revenue impact: {impact}. Deadline: {if time-sensitive}.} Ref: docs/specs/business/{spec}.md.
- [ ] **[BOTH] {Cross-cutting item}**: {Description}. Ref: docs/specs/{spec}.md.

## P1 — Core Features

- [ ] **[TECH] {Feature title}**: {Description}. Ref: docs/specs/technical/{spec}.md.
- [ ] **[BIZ] {Business feature}**: {Description. Conversion/retention impact: {impact}.} Ref: docs/specs/business/{spec}.md.

## P2 — Important

- [ ] **[TECH] {Refactor/improvement title}**: {Description. Velocity impact: {improvement}.} Ref: docs/adr/{adr}.md.
- [ ] **[BIZ] {Business requirement}**: {Description}. Ref: docs/specs/business/{spec}.md.

## P3 — Nice to Have

- [ ] **[TECH] {Enhancement title}**: {Description}.
- [ ] **[BIZ] {Business enhancement}**: {Description}.

## Future Ideas

- [ ] **[TECH] {Long-term technical item}**: {Description}.
- [ ] **[BIZ] {Long-term business item}**: {Description}.

Format requirements:

• Each item on one line as - [ ] **[BIZ/TECH/BOTH] {bold title}**: {description}.
• Include Ref: with source spec/ADR path when the item was derived from a specific document. Use docs/specs/business/ or docs/specs/technical/ paths matching the item's category.
• For business items: include revenue/conversion/retention impact where known.
• For technical items: include what business milestone they enable where applicable.
• For time-sensitive items: include deadline or market window.
• Epic-level items should be substantial enough for board-fill to break into sub-issues.
• Group by priority tier with ## P{N} — {Label} headers.
• Standalone items should be self-contained tasks.
• Items must be actionable — no vague "improve X" without specific scope.

If todo.md already exists:

ASK: "todo.md already exists with {N} items. (a) Replace entirely, (b) Append new items, (c) Merge (deduplicate and reorganize)"

• For replace: overwrite the file entirely.
• For append: add new items under appropriate priority headers, preserving existing content.
• For merge: compare existing items with new ones semantically, deduplicate, and reorganize by priority. Preserve existing [BIZ]/[TECH]/[BOTH] tags if present.

---

Step 6: Write & Summary

1. Spawn a hatch3r-docs-writer sub-agent via the Task tool (subagent_type: "generalPurpose") to write todo.md to the project root. The docs-writer receives the confirmed roadmap output from Step 4 and the format specification from Step 5, and follows the hatch3r-docs-writer agent protocol.
2. Update .hatch3r-session.json with roadmap context (if company stage and business context were gathered fresh in this run):

{
  "timestamp": "{ISO timestamp}",
  "command": "hatch3r-roadmap",
  "companyStage": { ... },
  "businessContext": { ... },
  "scope": "{full / specific parts}",
  "roadmapGoals": { ... }
}

3. Present a summary:

Roadmap Written: todo.md

  Total items:     N (X epics, Y standalone)
  By scope:        BIZ: N, TECH: N, BOTH: N
  By priority:     P0: N, P1: N, P2: N, P3: N, Future: N
  Estimated total effort: ~X days
  Recommended parallel lanes: N
  Team capacity:   {N} devs × {hours}/week = ~{available days}
  Estimated duration: ~{weeks} weeks at current capacity

Business Milestones:
  {milestone 1}: {target date/phase}
  {milestone 2}: {target date/phase}

Technical Milestones:
  {milestone 1}: {target date/phase}
  {milestone 2}: {target date/phase}

---

Step 7: AGENTS.md Generation

ASK: "Generate or update the root-level AGENTS.md with a project summary derived from the roadmap and specs? This file serves as the 'README for agents' — consumed by OpenCode, Windsurf, and other AI coding tools so they understand your project's business context, architecture, and conventions from the first interaction.

(a) Yes — generate it, (b) No — skip, (c) Let me review the content first."

If yes or review-first: spawn a hatch3r-docs-writer sub-agent via the Task tool (subagent_type: "generalPurpose") to generate AGENTS.md at the project root following the hatch3r-docs-writer agent protocol. The docs-writer receives the roadmap context and spec references. The generated AGENTS.md should follow this structure:

# {Project Name} — Agent Instructions

> Auto-generated by hatch3r-roadmap on {today's date}. Review and adjust before use.

## Project Purpose

{One-paragraph vision/purpose from business overview}

## Business Context

- **Business model**: {type}
- **Revenue model**: {model}
- **Company stage**: {stage}
- **Target market**: {segments}
- **Key metrics**: {KPIs}

## Technology Stack

{Concise stack summary — languages, frameworks, databases, infrastructure}

## Architecture Overview

{Architecture style, key components, deployment topology — 3-5 sentences}

## Module Map

| Module | Purpose |
| ------ | ------- |
| {module} | {one-line description} |

## Key Business Rules & Domain Constraints

{Top 5-10 business rules that agents must respect when making changes}

- {rule}: {constraint}

## Conventions

{Key coding conventions agents should follow — naming, patterns, testing}

## Current Roadmap Focus

{What the team is currently working on — P0/P1 items from the roadmap}

- **Current phase**: {description}
- **Key milestones**: {next 2-3 milestones}

## Documentation Reference

- Business specs: `docs/specs/business/`
- Technical specs: `docs/specs/technical/`
- Architecture decisions: `docs/adr/`
- Roadmap: `todo.md`

If the user chose "review first," present the content and ASK for confirmation before writing.

If AGENTS.md already exists, ASK before overwriting: "Root AGENTS.md already exists. (a) Replace entirely, (b) Append hatch3r section, (c) Skip."

---

Step 8: Cross-Command Handoff

ASK: "Roadmap complete. Recommended next steps:

• Run hatch3r-board-fill to create GitHub issues from the todo.md
• Run hatch3r-board-pickup to start working on the highest-priority items

Which would you like to run next? (or none)"

Future command: hatch3r-test-plan — generates a test plan from the current task context (issue, spec references, acceptance criteria) covering unit, integration, and E2E test scenarios. Not yet implemented; tracked for a future release.

---

Resumability (Decision 27/30)

roadmap is long-running — a Tier 3 brownfield discovery fans out parallel researcher sub-agents across Business-Priority and Technical-Readiness intelligence (Steps 2–3), then generates a dual-lens phased roadmap, todo.md, AGENTS.md, and a cross-command handoff (Steps 4–8). Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-running the multi-mode researcher fan-out.

Orchestration boilerplate: see commands/shared/orchestration-frame.md → Checkpoint Contract. Per-command slots: workspace .roadmap-workspace/; step range the Step 0 → Step 8 progression; wave = researcher-batch index across business + technical lenses; snapshot/rollback paths docs/roadmap/, todo.md, and AGENTS.md; meta adds roadmapSlug. Write points: after Step 1 context + business discovery completes, after Step 2 categorization locks, after Step 3 researcher fan-out returns, after the Step 4 dual-lens roadmap synthesis is confirmed by ASK, and after each Step 5–7 file write (roadmap doc, todo.md, AGENTS.md) so already-generated artifacts survive a crash and are not regenerated on resume. Also after Step 8 cross-command handoff dispatch.

---

Per-Turn Pipeline-State Header (Bypass Protection)

Orchestration boilerplate: see commands/shared/orchestration-frame.md → Per-Turn Pipeline-State Header. Phase mapping for roadmap: 1 = vision intake + horizon scoping, 2 = researcher/spec sub-agent dispatch (themes, milestones, dependencies), 3 = roadmap synthesis + sequencing, 4 = roadmap write + iteration-summary. Tier 1 runs are exempt per the Tier 1 exemption.

End-of-Turn Delegation Attestation (Bypass Protection)

Orchestration boilerplate: see commands/shared/orchestration-frame.md → End-of-Turn Delegation Attestation. Per-command mutated-file slot: roadmap doc, milestone files, theme specs.

Iteration Summary (mandatory output)

Close the run with the recap-contract Iteration Summary per rules/hatch3r-iteration-summary.md: a 1–2 line recap (status, outcome, files · sub-agents · gates · cost delta) plus every exception line whose firing condition holds — silence asserts the default. Omitting the recap fails that rule's Validation Gate (CONSTITUTION §6 Decision 37; Replaces: 28).

Cost Visibility (Decision 29)

Orchestration boilerplate: see commands/shared/orchestration-frame.md → Cost Estimate for the 5-field cost_estimate schema and the post-execution cost_actuals + delta contract; both land in the Iteration Summary recap (cost facet; full blocks on the Cost: exception line beyond ±25%) per rules/hatch3r-cost-visibility.md.

Cost estimate (Decision 29)

This command emits cost transparency per rules/hatch3r-cost-visibility.md and CONSTITUTION §6 Decision 29:

• Pre-execution cost_estimate — emitted in Step 0.5 before the first researcher dispatch (Step 3).
• Post-execution cost_actuals + delta — appended to the Iteration Summary recap (cost facet; full blocks on the Cost: exception line beyond ±25%) per rules/hatch3r-cost-visibility.md.

Per-tier expected_sa_count calibration (from frontmatter sub_agents_spawned.count: 2 × tier heuristic in rules/hatch3r-cost-visibility.md Pre-Execution Estimate): Tier 1 ≈ 1 (technical-readiness researcher only, condensed todo.md); Tier 2 ≈ 2-3 (both researchers + todo.md docs-writer); Tier 3 up to 3 (both researchers with deep web research + AGENTS.md docs-writer). This command is web-research-heavy at Tier 3 — estimated_web_research_queries typically dominates the cost delta. Deltas beyond 25% absolute value carry flagged_for_review: true. Token telemetry sources from src/pipeline/observability.ts; estimation primitives from src/pipeline/costEstimator.ts.

---

Error Handling

• No specs or docs found: Fall back to user-provided vision. Warn that the roadmap will be less detailed without structured specs. Offer to run hatch3r-project-spec or hatch3r-codebase-map first.
• Existing todo.md conflict: Always ASK before modifying — never overwrite silently.
• Very large scope (>50 items): Suggest splitting into phases or focus areas. Present only the first phase in detail and summarize the rest.
• GitHub issue fetch failure: Proceed without deduplication check. Warn user that duplicates may exist.
• Ambiguous priority: Default to P2. Flag for user review in Step 4.
• Sub-agent failure: Retry the failed researcher once. If it fails again, proceed with the other researcher's output and note the gap. ASK the user whether to continue with partial research.
• Business context gaps: If the user cannot answer business discovery questions, proceed with "TBD" markers and flag these items as needing business input before implementation.
• Stage assessment unclear: Default to "early-revenue" if the user is unsure. This provides balanced prioritization without over- or under-engineering the roadmap.
• No business specs found: If only technical specs exist (legacy layout), generate a technical-only roadmap and recommend running hatch3r-project-spec or hatch3r-codebase-map to create business specs.

Adapter Parity Within the Supported Set

hatch3r supports 3 adapters as of 1.9.0 (Cursor, Claude Code, Copilot). Adapter parity within that supported set is enforced by capability-matrix tests; no adapter-parity work should land in roadmaps unless those tests detect a regression. If a regression is detected, track the gap as a [TECH] item at P2 priority or higher.

Guardrails

• Never skip ASK checkpoints. Every step with an ASK must pause for user confirmation.
• When in doubt, ASK. It is better to ask one question too many than to make one wrong assumption. Discovery questions are never wasted.
• Never write files without user review and confirmation. All generated content is presented first.
• Never overwrite todo.md without explicit user confirmation.
• todo.md format must match the canonical Todo Grammar in hatch3r-board-shared — the single source of truth hatch3r-board-fill Step 1 parses (## P{N} — {Label} headers; - [ ] **[BIZ|TECH|BOTH] {title}**: {description} items).
• Keep items at the right granularity — epic-level for complex features (XL effort), standalone for simple tasks (S/M effort).
• Always reference source documentation (specs, ADRs) where items were derived from. Use docs/specs/business/ or docs/specs/technical/ paths matching the item's category.
• Do not duplicate work already tracked in GitHub issues.
• Effort estimates are rough; label each estimate explicitly with the (estimate) suffix.
• Respect existing priority conventions in the project.
• Stage-adaptive prioritization. Never recommend enterprise-tier (per CONSTITUTION §6 Decision 4) solutions for solo-tier pre-revenue startups. Never recommend MVP shortcuts for scaleup-tier or enterprise-tier companies. Calibrate all prioritization to the company stage from Step 1d.
• Business milestones must map to technical enablers. Every business milestone should have its technical prerequisites identified and scheduled ahead of it.
• Technical items must justify business impact. Every technical item (refactor, debt paydown, infrastructure) should state what business outcome it enables or unblocks.
• Never overwrite AGENTS.md without explicit user confirmation.
• Sub-agents must not create files. They return structured text results to the orchestrator. Only the orchestrator writes files.

---

Execute This Plan

Close the run with the Plan-Execution Handoff block immediately after the Iteration Summary recap — a sanctioned post-recap trailer (when the Remaining Work terminal block also fires per rules/hatch3r-iteration-summary.md, it renders after this block as the run's very last output) (frontmatter plan_handoff: true; format + shapes: commands/shared/orchestration-frame.md → Plan-Execution Handoff (terminal block)).

Fill Shape B (chain) — the roadmap's todo.md IS the plan, so the first line is the canonical next command, not a --plan-file invocation: /hatch3r-board-fill (still a fenced copy-paste prompt with <one-line scope> from the roadmap's milestone summary and top-3 criteria from the P1 items), then /hatch3r-board-pickup to start delivery. Suppressed when this flow runs under /hatch3r-plan — the router emits one consolidated block.