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 — only the second step branches.

:::info Last verified 2026-04-28 against hatch3r 1.7.0. URLs and credential flows reverified each audit cycle (P3 — Adapter & MCP Currency). :::

Prerequisites

Node.js 22 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 — Cursor, Claude Code, Copilot, OpenCode, Windsurf, Amp, Codex CLI, Gemini CLI, Cline / Roo, Aider, Kiro, Goose, Zed, Amazon Q, or Antigravity.

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

Step 1 — Initialize hatch3r

npx hatch3r init

Interactive flow (~2 minutes). hatch3r asks 9 questions, in this order:

Platform — GitHub, Azure DevOps, or GitLab. Auto-detected from your git remote; press Enter to accept.
Repo identity — owner / org / repo name. Auto-filled from git remote where possible.
Default branch — used by board, PR, and release commands.
Project type — greenfield (new) or brownfield (existing). Filters out content irrelevant to your situation.
Team size — solo or team. Solo skips board-management content.
Content profile — minimal, standard, full (recommended), or custom. See the profile table below.
Tools — multi-select from the 15 supported adapters.
Worktree isolation — only asked if you selected a worktree-capable tool.
MCP servers — multi-select from 10 servers (3 default, 7 opt-in). Platform-aware: the GitHub / ADO / GitLab MCP that matches your platform is pre-selected.

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

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

What gets created

Path	Purpose
`.agents/`	Canonical, tool-agnostic source (agents, skills, rules, commands, mcp/)
`.agents/hatch.json`	Manifest with content selection, tool list, MCP servers, integrity checksums
`.agents/AGENTS.md`	Generated index of installed content
`AGENTS.md` (repo root)	Rich agent roster with skill and command links
Tool-specific outputs	`.cursor/`, `CLAUDE.md`, `.windsurfrules`, `.clinerules`, `GEMINI.md`, etc. — one per selected tool
`.env.mcp`	Secret placeholder file (gitignored) — only created if you enabled MCP
`.gitignore`	Updated to exclude `.env.mcp`
`.worktreeinclude`	Created only if a worktree-capable tool is selected

Content profiles

Profile	What's included	Best for
Minimal	Core agents and core rules only (`core` tag)	Quick setup, minimal footprint
Standard	Full development lifecycle without niche audits	Most projects
Full (recommended)	Everything including board management and all audits	Large teams, full coverage
Custom	Interactive picker per artifact type	Fine-grained control

The profile is combined with greenfield/brownfield and solo/team filters, so a solo + greenfield + standard install carries materially less content than team + brownfield + full.

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
# ... and any others your selected servers need

Where to obtain each credential

Server	Env var	Where to obtain	Required scopes / notes
GitHub	`GITHUB_PAT`	github.com/settings/tokens/new	Classic PAT: `repo`, `read:org`, `project`. Fine-grained PATs still cannot access user-owned Projects V2 as of 2026 — for board commands on user-owned projects, classic is required.
Brave Search	`BRAVE_API_KEY`	api-dashboard.search.brave.com/register	Brave retired the free tier in 2026. New users get $5/month in credits (~1,000 queries); legacy free-plan users grandfathered to 2,000/month. Credit card required.
Sentry	`SENTRY_AUTH_TOKEN`	sentry.io/settings/account/api/auth-tokens/	User token for personal MCP. Org-scoped tokens (Org Settings → Auth Tokens) are preferred for shared / CI use.
Postgres	`POSTGRES_URL`	Your database provider	Format: `postgresql://user:pass@host:5432/db`. Treat as a secret.
Linear	`LINEAR_API_KEY`	linear.app/settings/api	Personal API keys are still supported. OAuth 2.0 is preferred for shared installations.
Azure DevOps	`AZURE_DEVOPS_PAT`, `AZURE_DEVOPS_ORG`	Microsoft Learn — Use PATs	Scopes: Work Items (R/W), Code (R/W), Build (R), Project and Team (R). Microsoft now recommends Entra ID over PATs; PATs still work for hatch3r MCP, but Entra-backed orgs require sign-in every 90 days to keep PATs active.
GitLab	`GITLAB_TOKEN`	gitlab.com/-/user_settings/personal_access_tokens	Scope: `api`. For automation contexts, consider Project Access Tokens or Group Access Tokens instead of personal PATs. Self-hosted: also set `GITLAB_HOST=https://gitlab.example.com`.

For deeper guidance — fine-grained PAT permission tables, Claude Code permission opinions, custom MCP server registration — see the MCP Setup guide.

Loading secrets into your editor

Two patterns, depending on the tool:

Auto-loaded — VS Code / Copilot read env vars from the env object hatch3r writes into .vscode/mcp.json. No sourcing needed; just fill .env.mcp and let the adapter regenerate the per-tool config on the next sync.

Source-and-launch — Cursor, Claude Code, Windsurf, Amp, Codex, Gemini, Cline / Roo, Kiro all expect env vars to be present in the process that launches the editor:

# macOS / Linux (zsh, bash)
set -a && source .env.mcp && set +a && cursor .          # or: claude / windsurf / etc.

# Windows (PowerShell)
Get-Content .env.mcp | ForEach-Object {
  if ($_ -match '^\s*([^#][^=]+)=(.*)$') {
    [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), 'Process')
  }
}
cursor .

Persist tokens by adding the set -a; source .env.mcp; set +a lines to ~/.zshrc / ~/.bashrc, or paste them into Cursor's per-server pencil-icon UI.

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. In 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

Pick the path that matches the work in front of you.

Greenfield (new project)

/hatch3r-project-spec   # Generate specs from your project vision
/hatch3r-roadmap        # Phased plan with epics, broken into milestones

Brownfield (existing codebase)

/hatch3r-codebase-map   # Reverse-engineer specs from the current code
/hatch3r-roadmap        # Plan improvements off the analysis

Single feature (no full project)

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

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

Run inside your editor:

/hatch3r-board-init

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. It 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
- Replace Stripe webhook polling with idempotent event ingestion

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: /hatch3r-board-groom 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 → implement → review loop (reviewer + fixer, max 3 iterations) → final quality gates (test-writer + security-auditor). When the loop converges clean, it opens a PR.

The reviewer + fixer loop is automatic — there is no separate review command.

Repeat this step until the board drains.

Step 8 — Maintain canonical state

Day-to-day commands you will run as you edit .agents/ content or rotate tools:

Command	When to run
`npx hatch3r sync`	After editing anything inside `.agents/`. Re-generates all tool outputs from the canonical state.
`npx hatch3r status`	Drift check — does any generated file differ from what canonical would produce?
`npx hatch3r validate`	Pre-commit / CI structural check — frontmatter, cross-references, content compliance. Exit 0 means clean.
`npx hatch3r verify`	SHA-256 + manifest integrity check. `--fix` auto-runs `update` to heal drift.
`npx hatch3r config`	Reconfigure platform, tools, MCP servers, features, or content selection — fully interactive.
`npx hatch3r update`	Pull the latest hatch3r templates, safe-merging into your customizations. Use `--offline` to skip the npm fetch.
`npx hatch3r clean`	Remove all hatch3r-managed artifacts.

Step 9 — Release

/hatch3r-release

release 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
npx hatch3r sync --repos frontend         # sync only frontend/
npx hatch3r sync --dry-run                # preview without writing
npx hatch3r config                        # add or remove repos, change sync strategy

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

Where to read next

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

Prerequisites​

Step 1 — Initialize hatch3r​

What gets created​

Content profiles​

Step 2 — Add MCP credentials​

Where to obtain each credential​

Loading secrets into your editor​

Step 3 — Restart your editor​

Step 4 — Define scope​

Greenfield (new project)​

Brownfield (existing codebase)​

Single feature (no full project)​

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

Step 5 — Set up the board​

Step 6 — Fill the board​

Step 7 — Pick up work​

Step 8 — Maintain canonical state​

Step 9 — Release​

Multi-Repo Workspace​

Where to read next​