Skip to main content

Quick Start

A copy-paste-runnable walkthrough that takes a project from empty to released using hatch3r. The path is the same for greenfield and brownfield work — the spec step (Step 4) auto-detects which one you are in and branches for you. Deep-reference tables (prompt walkthrough, created files, --import migration, profile comparison, timing data) live in the Quick Start Reference.

:::info Last verified 2026-07-11 against hatch3r 2.5.0. URLs and credential flows reverified each audit cycle (P3 — Adapter & MCP Currency). MCP is pure opt-in since 2.0.0 — interactive init does not prompt for it; enable with npx hatch3r init --mcp or npx hatch3r mcp setup. :::

Prerequisites​

  • Node.js 22.13 or later — the only hard prerequisite. Check with node --version.
  • A git repository at the working directory, OR a non-git folder containing one or more git subdirectories (workspace mode is auto-detected).
  • One of the supported tools — Claude Code, Cursor, or GitHub Copilot. (As of 1.9.0, hatch3r supports these 3 adapters only; see CHANGELOG for the 1.9.0 scope cut.)

That is it. No global install, no preflight setup.

Step 1 — Initialize hatch3r​

npx hatch3r init

Interactive flow, 1-2 minutes measured (init prints a Completed in Xs line) — 7 prompts on a fresh GitHub greenfield repo: platform → repo identity → content profile → maturity → communication style → tools → CLI-tools picker. Every prompt is auto-detected or seeded from your git remote and history, so pressing Enter through the defaults is a working path. Prompt-by-prompt walkthrough and per-platform prompt counts: init prompts; spec/PR timing estimates: time to first value.

For headless / CI use, pass --yes with optional flags:

npx hatch3r init --yes --preset standard --tools claude --project-type brownfield --team-size team

Migrating from another tool​

Carry existing rules across on the same init run — converted rules land under .hatch3r/overrides/rules/ and survive later syncs. Conversion and conflict semantics: reference.

npx hatch3r init --import cursor   # formats: cursor | copilot | windsurf | cursorrules | agents
npx hatch3r init --import auto     # one pass over every detected format

What gets created​

init writes the .hatch3r/ state directory — manifest (hatch.json), your overrides/, learnings/, handoffs/ — plus per-tool outputs (.claude/ + CLAUDE.md, .cursor/, or .github/copilot-instructions.md and companions) and, with MCP enabled, a gitignored .env.mcp. Canonical content is read from the bundled npm package, never materialized into your repo. Full path-by-path table: what gets created.

Content profiles​

Four profiles set the capability dial: Minimal (core orchestration + implementation), Standard (recommended — the full development lifecycle), Full (everything, including performance and AI feature engineering), and Custom (interactive picker). The security, UI/UX, and content-quality floor ships at every profile and is never dropped. Maturity (solo/team/scaleup/enterprise) is a separate axis — every tier installs the full corpus; the dial changes how deeply agents invest (Maturity Tiers). Profile comparison table and additive-upgrade / visible-downgrade semantics: content profiles.

Step 2 — Add MCP credentials​

Skip this step if you did not enable any credential-requiring MCP server. The 3 default servers (Playwright, Context7, Filesystem) need nothing.

The 7 opt-in servers each need an API key or token. Open .env.mcp and fill the placeholder values:

# .env.mcp — generated by hatch3r init (gitignored)
GITHUB_PAT=ghp_xxxxxxxxxxxx
BRAVE_API_KEY=BSA_xxxxxxxx

Per-server obtain links, required scopes, and fine-grained PAT tables: MCP Setup guide. VS Code / Copilot auto-load these vars from the generated config; Cursor and Claude Code expect them in the process that launches the editor — Windows (PowerShell) loading and token persistence: MCP credentials.

set -a && source .env.mcp && set +a && cursor .   # macOS / Linux; or: claude .

Step 3 — Restart your editor​

MCP configs are read on editor launch — close and reopen so the new .cursor/mcp.json / .mcp.json / etc. takes effect. Verify connection: most editors show MCP status in their Tools / Settings panel (Cursor: Settings → Tools & MCP — each enabled server should show a green dot and its tools should appear in the Available Tools list inside chat).

Step 4 — Define scope​

Full project — greenfield or brownfield​

/hatch3r-spec       # Auto-detects greenfield vs brownfield and runs the matching spec flow
/hatch3r-roadmap    # Phased plan with epics, broken into milestones

hatch3r-spec is the 2.0.0 unified spec orchestrator: on a new project it generates specs from your vision; on an existing codebase it reverse-engineers specs from the current code. It picks the branch by detecting project state — to force one branch, the split commands remain as a legacy path: /hatch3r-project-spec (greenfield only) or /hatch3r-codebase-map (brownfield only), each followed by /hatch3r-roadmap.

Single feature (no full project)​

/hatch3r-feature-plan   # Plan one feature in depth — no board needed

After /hatch3r-feature-plan produces the plan, run /hatch3r-workflow (Quick Mode) — it walks the implement → review → test pipeline standalone, no board required.

Tiny change (typo / config tweak / one-file refactor)​

/hatch3r-quick-change   # Skip everything below; this is a complete one-shot flow

If you took the tiny-change path, you are done — jump to Step 8.

Step 5 — Set up the board​

:::note Board workflows are team-scoped Steps 5–7 (board init / fill / pickup) install only when your repo resolved to team size. hatch3r init infers team size from git history (more than one distinct commit-author email ⇒ team) and defaults a single-author or fresh repo to solo, where the board cluster is not installed. If you ran a solo install, init prints a one-line note saying so — re-run with --team-size team (or switch later via hatch3r config) to add the board chain. Solo developers who work issue-by-issue can skip to Step 8 and drive single features without a board. :::

Invoke the hatch3r-board-init skill from your editor (Claude Code: Skill: hatch3r-board-init; Cursor: load the skill from the skills picker; Copilot: reference the skill in the chat).

This creates or connects a project board on your detected platform — a GitHub Projects V2 board, an Azure DevOps board, or a GitLab Issues board — and writes back the resolved board owner / project number / area labels into hatch.json so subsequent commands target the correct board. Skip this step for the single-feature path.

Step 6 — Fill the board​

Write a todo.md at the project root with one line per work item:

- Add OIDC login support for the customer portal
- Migrate analytics events to the new schema

Then run:

/hatch3r-board-fill

board-fill parses todo.md, classifies each item (feature / bug / refactor / migration / test), groups items into epics, builds a dependency DAG, and marks ready items as status:ready on the board. For backlog hygiene later: invoke the hatch3r-board-groom skill — it surfaces stale items, priority imbalances, and decomposition candidates.

Step 7 — Pick up work​

/hatch3r-board-pickup

board-pickup selects the next status:ready issue by dependency order and priority, creates a feature branch, and runs the four-phase agent pipeline: research → plan gate (Tier >= 2 persists a plan to docs/plans/ and asks before implementing) → implement → review loop (reviewer + fixer, max 3 iterations — automatic, there is no separate review command) → final quality gates (test-writer + security-auditor). When the loop converges clean, it opens a PR.

Repeat this step until the board drains.

Step 8 — Maintain canonical state​

Day-to-day commands you will run as you edit .hatch3r/overrides/ content or rotate tools. Also available: verify (non-zero exit on drift, for CI), config (interactive reconfigure), clean (removes managed artifacts, preserving .hatch3r/ user state) — full command detail: CLI Commands.

CommandWhen to run
npx hatch3r syncAfter editing anything under .hatch3r/overrides/ or upgrading hatch3r. Re-generates all tool outputs from bundled canonical content + your overrides.
npx hatch3r statusDrift check — does any adapter-output file differ from what hatch3r would regenerate now?
npx hatch3r validatePre-commit / CI structural check — frontmatter, cross-references, content compliance on bundled content + your overrides. Exit 0 means clean.
npx hatch3r updatePull the latest hatch3r templates, safe-merging into your customizations. Use --offline to skip the npm fetch.

Step 9 — Release​

Prerequisite: npm run lint && npm run typecheck && npm run test && npm run build must pass — the release skill verifies these and halts on failure. Before invoking it, also run npx hatch3r validate to confirm canonical content has not drifted (it is the framework's drift-detection gate and the release skill does not run it for you).

Invoke the hatch3r-release skill — it reads the conventional-commit history since the last tag, decides the semver bump (patch / minor / major), generates a changelog entry, tags, and publishes per your project's release config.

That closes the loop: init → spec → board → pickup → release.

Multi-Repo Workspace​

If your working directory is a non-git folder containing multiple git subdirectories (e.g. frontend/, backend/, infra/), hatch3r auto-detects workspace mode. Force it explicitly with --workspace:

npx hatch3r init --workspace
npx hatch3r sync                          # cascade to all repos (--repos <name> to target one)
npx hatch3r sync --dry-run                # preview without writing

The shared .hatch3r/ lives at the workspace root; each sub-repo gets independent adapter outputs (not symlinks), with optional per-repo overrides for tools, features, and content. See the Workspace guide for details.

  • Quick Start Reference — init prompt walkthrough, created-files table, --import details, profile comparison, MCP credential notes
  • MCP Setup — full per-server configuration, PAT scope tables, custom MCP servers, Claude Code permissions
  • Workflow guide — the deeper view of the four-phase pipeline and review loop
  • Adapter Capability Matrix — which adapters emit MCP, hooks, skills, etc.
  • Troubleshooting — common init / sync / MCP errors and fixes