Skip to main content
For new projects (greenfield), hatch3r provides a spec-first workflow that generates complete documentation from your vision before writing any code.

​
Overview

The greenfield workflow:
  1. Initialize — Set up hatch3r
  2. Generate specs — Use project-spec to create documentation
  3. Create roadmap — Use roadmap to plan phases
  4. Fill board — Generate GitHub issues with board-fill
  5. Implement — Use board-pickup to build features

​
1. Initialize Your Project

Start with an empty repository or create a new one:
1

Create repository

mkdir my-project
cd my-project
git init
npm init -y  # or your package manager
2

Install hatch3r

npx hatch3r init
3

Select tools

Choose which coding tools you use:
  • Cursor
  • GitHub Copilot
  • Claude Code
  • OpenCode
  • Windsurf
  • Amp
  • Codex CLI
  • Gemini CLI
  • Cline / Roo Code
4

Configure MCP servers

Select which MCP servers to enable:
  • GitHub (repos, issues, PRs, projects)
  • Context7 (library documentation)
  • Filesystem (project files)
  • Playwright (browser automation)
  • Brave Search (web research)

​
2. Generate Project Specs

Run the project-spec command to generate complete documentation:

​
What project-spec Does

project-spec spawns 7 parallel researcher sub-agents:

Stack Researcher

Recommends languages, frameworks, databases, and infrastructure calibrated to your company stage

Feature Researcher

Breaks your vision into features organized by domain/module with priority ordering

Architecture Researcher

Designs system architecture, data flows, and integration points

Pitfalls Researcher

Identifies risks, anti-patterns, security concerns, and scalability bottlenecks

UX Researcher

Analyzes user journeys, accessibility requirements, and visual design direction

Business Model Researcher

Validates business model, researches competitors, and recommends GTM strategy

Production Researcher

Designs infrastructure, scaling strategy, observability, and cost modeling

​
Running project-spec

1

Invoke the command

Run project-spec in your coding tool (e.g., Cursor command palette)
2

Answer discovery questions

project-spec will ask about:Core Vision:
  • Project name
  • Vision and purpose (one paragraph)
  • Target platforms (web, mobile, CLI, API, etc.)
  • Key user personas and goals
  • Known constraints (budget, timeline, tech mandates)
Company Stage:
  • Company stage (pre-revenue, early-revenue, growth, scale, enterprise)
  • Team composition and size
  • Current user/revenue scale
  • Funding/runway status
  • Regulatory/compliance needs
Business Context:
  • Business model type (SaaS, marketplace, platform, etc.)
  • Revenue model (subscription, transactional, freemium, etc.)
  • Top 3 competitors
  • Target market segments / ICP
  • Key business metrics/KPIs
3

Review researcher outputs

project-spec presents a merged summary of all researcher findings:
  • Stack recommendations with trade-offs
  • Feature catalog with complexity estimates
  • Architecture overview and decisions
  • Risk register (technical and business)
  • UX analysis and competitive research
  • Market sizing and GTM recommendations
  • Infrastructure blueprint and cost model
4

Confirm specs

Review and adjust the generated specs before writing files:Technical specs (docs/specs/technical/):
  • 00_glossary.md — Stable IDs for entities, events, modules
  • 01_overview.md — Technical overview
  • 02_{module}.md — One spec per module
Business specs (docs/specs/business/):
  • 00_business_glossary.md — Business entities and metrics
  • 01_business_overview.md — Business model and market context
  • 02_{domain}.md — One spec per business domain
  • 03_competitive_analysis.md — Competitor research
  • 04_gtm_strategy.md — Go-to-market plan
  • 05_production_blueprint.md — Infrastructure and cost model
5

Generate ADRs

project-spec creates Architecture Decision Records (ADRs) for each significant decision:
  • Framework/language choices
  • Database selection
  • Architecture patterns
  • Authentication approach
  • Payment/billing architecture
6

Create todo.md

project-spec generates an initial todo.md with prioritized items from:
  • Feature researcher’s priority ordering
  • Pitfalls researcher’s risk register
  • Business model researcher’s GTM requirements
  • Production researcher’s infrastructure needs
7

Optional: Generate AGENTS.md

Optionally create a root-level AGENTS.md as a “README for agents” with:
  • Project purpose
  • Business context
  • Technology stack
  • Architecture overview
  • Key business rules
  • Conventions

​
Example Output Structure

my-project/
├── docs/
│   ├── specs/
│   │   ├── business/
│   │   │   ├── 00_business_glossary.md
│   │   │   ├── 01_business_overview.md
│   │   │   ├── 02_user_management.md
│   │   │   ├── 03_competitive_analysis.md
│   │   │   ├── 04_gtm_strategy.md
│   │   │   └── 05_production_blueprint.md
│   │   └── technical/
│   │       ├── 00_glossary.md
│   │       ├── 01_overview.md
│   │       ├── 02_auth.md
│   │       ├── 03_api.md
│   │       └── 04_data-layer.md
│   └── adr/
│       ├── 0001_framework-choice.md
│       ├── 0002_database-selection.md
│       └── 0003_auth-strategy.md
├── todo.md
├── AGENTS.md
└── .hatch3r-session.json

​
3. Create a Roadmap

Run roadmap to generate a phased plan:
1

Run roadmap command

Execute roadmap in your coding tool
2

Review phases

roadmap breaks work into dependency-ordered phases:
  • Phase 1: Foundation — Core infrastructure and architecture
  • Phase 2: MVP Features — Minimum viable product
  • Phase 3: Growth — Scaling and optimization
  • Phase 4: Polish — UX improvements and nice-to-haves
3

Identify parallel lanes

roadmap identifies work that can proceed in parallel:
  • Frontend and backend can often progress independently
  • Infrastructure setup can run alongside feature development
  • Documentation can be written concurrently
4

Update todo.md

roadmap updates todo.md with phased, dependency-ordered items ready for board-fill

​
4. Fill the Board

Run board-fill to create GitHub issues:
1

Run board-init first

If you haven’t already, run board-init to set up your GitHub Projects V2 board
2

Run board-fill

Execute board-fill in your coding tool
3

Triage items

board-fill asks clarifying questions about each item:
  • Scope and boundaries
  • Value and motivation
  • Open questions or unknowns
  • External dependencies
  • Decomposition needs
4

Review classifications

Confirm type, priority, executor, area, and risk labels
5

Review groupings

Confirm epic groupings and standalone issues
6

Review dependencies

Confirm dependency relationships and implementation order
7

Create issues

board-fill creates GitHub issues and links them to your project board

​
5. Implementation Workflow

​
Pick Up First Issue

Run board-pickup to start implementing: 
# Auto-select next best issue
board-pickup

# Or specify an issue
board-pickup #123

​
Development Cycle

1

board-pickup selects issue

Based on dependency order, priority, and readiness
2

Create branch

Follows your branching convention
3

Implement feature

Delegates to the appropriate skill:
  • feature — End-to-end feature implementation
  • bug-fix — Minimal fix with regression test
  • refactor — Code quality improvement
4

Run tests

Executes test suite and quality checks
5

Create PR

With descriptive title, body, and self-review checklist
6

Review and merge

Automated review agents provide feedback
7

Repeat

Run board-pickup again for the next issue

​
Best Practices

Focus on the smallest viable product first. Use the company stage assessment to calibrate recommendations:
  • Pre-revenue: MVP-focused, lean analysis
  • Growth: Scaling-aware, performance considerations
  • Enterprise: Production-hardened, compliance-ready
Use the Business Model Researcher’s competitive analysis to validate your assumptions before building.
ADRs capture the context and rationale for decisions. Review and update them as you learn.
Specs are living documents. Update them as requirements change or implementation reveals new constraints.
Reference entities, events, and modules by their stable IDs from the glossary across docs, issues, and code.

​
Next Steps

Workflow Guide

Full project lifecycle from init to release

Board Fill

Learn how board-fill creates issues with dependency analysis

Documentation Structure

Understanding docs/specs/ and docs/adr/

Customization

Tailor hatch3r to your project needs

Build docs developers (and LLMs) love

Get started for freeTalk to us