hatch3r

Crack the egg. Hatch better agents.

hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. Ship Ready as of Cycle 8 (audit score 83.74/100, 0 Critical findings, 15 platform adapters wired, 21-domain governance audit cycle operational). One command gives you the full set of agents, skills, rules, commands, hooks, and MCP integrations -- optimized for your coding tool of choice (live counts in governance/inventory.json ). Selective init installs only what you need based on your project type and team size.

Quick Start

Requires Node.js 22+.

npx hatch3r init

That's it. hatch3r detects your repo, asks about your project context (greenfield/brownfield, solo/team), lets you choose a content profile (minimal/standard/full/custom), and generates everything. The platform (GitHub, Azure DevOps, or GitLab) is auto-detected from your git remote. Run into issues? See Troubleshooting.

What You Get

| Category | Count | Highlights | |----------|-------|-----------| | Agents | 19 | Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, handoff loader / preparer, and more | | Skills | 63 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, handoff prepare / resume, recipes, API spec, CI pipeline, migration, customization, 30 per-tool CLI skills, and more | | Rules | 42 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, handoff readiness, and more | | Commands | 38 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, handoff (prepare/resume/list/complete/prune), and more | | CLI tools | 29 across 3 tiers | Tier-1 default (ripgrep, fd, jq, yq, gh, delta, bat, sd, ast-grep, zstd); tier-2 conditional (Playwright, duckdb, qsv, taplo, glab, az-devops, Docker, llm, fzf, lazygit, difftastic); tier-3 opt-in (RTK, Stagehand, aichat, mods, Comby, miller, csvkit, Podman) -- emitted as per-tool canonical skills + a decision-tree overview | | MCP Servers | 10 (opt-in) | Playwright, Context7, Filesystem, GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab -- gated behind a Yes/No prompt during init (default No since 1.7.5; pass --mcp to restore prior --yes behavior) | | Platforms | 3 | GitHub, Azure DevOps, GitLab -- auto-detected from git remote |

Supported Tools (15 Adapters)

| Tool | Output | |------|--------| | Cursor | .mdc rules, agents, skills, commands, MCP config | | GitHub Copilot | instructions, prompts, GitHub agents | | Claude Code | CLAUDE.md, skills, .mcp.json | | OpenCode | AGENTS.md, opencode.json | | Windsurf | .windsurfrules | | Amp | AGENTS.md | | Codex CLI | AGENTS.md, codex.md | | Gemini CLI | GEMINI.md | | Cline / Roo Code | .clinerules | | Aider | CONVENTIONS.md | | Kiro | .kiro/steering/, .kiro/settings/mcp.json | | Goose | .goosehints | | Zed | .rules | | Amazon Q | .amazonq/rules/, .amazonq/mcp.json | | Antigravity | .antigravity/rules.md, .antigravity/settings.json |

Platform is auto-detected from your git remote during hatch3r init. All board commands, agents, rules, and skills adapt to your selected platform.

How It Works

.agents/              <- Canonical source (tool-agnostic)
  ├── agents/
  ├── skills/
  ├── rules/
  ├── commands/
  ├── mcp/
  ├── AGENTS.md
  └── hatch.json       <- Manifest

.cursor/               <- Generated (Cursor adapter)
.github/               <- Generated (Copilot adapter)
CLAUDE.md              <- Generated (Claude adapter)
.windsurfrules         <- Generated (Windsurf adapter)
AGENTS.md              <- Generated (OpenCode, Amp, Codex adapters)
GEMINI.md              <- Generated (Gemini adapter)
.clinerules            <- Generated (Cline adapter)
CONVENTIONS.md         <- Generated (Aider adapter)
.kiro/                 <- Generated (Kiro adapter)
.goosehints            <- Generated (Goose adapter)
.rules                 <- Generated (Zed adapter)
.amazonq/              <- Generated (Amazon Q adapter)
.antigravity/          <- Generated (Antigravity adapter)
.worktreeinclude       <- Generated (worktree isolation)

hatch3r keeps one source of truth in .agents/ and generates native configuration for each tool.

Multi-Repo Workspaces

hatch3r can manage multiple git repos from a single workspace root. Run hatch3r init in a non-git directory containing git subdirectories and it auto-detects the workspace layout.

my-platform/                   <- Workspace root (not a git repo)
  .agents/                     <- Shared canonical source
    workspace.json             <- Workspace manifest
    hatch.json
    agents/
    rules/
    ...
  frontend/                    <- Git repo (gets its own generated files)
    .cursor/
    CLAUDE.md
    ...
  backend/                     <- Git repo
    .cursor/
    CLAUDE.md
    ...
  infra/                       <- Git repo
    .cursor/
    CLAUDE.md
    ...

npx hatch3r init --workspace              # force workspace mode
npx hatch3r sync                          # cascade to all repos
npx hatch3r sync --repos frontend backend # sync specific repos
npx hatch3r sync --dry-run                # preview changes
npx hatch3r config                        # manage repos and sync strategy

Content flows from workspace defaults into each sub-repo with optional per-repo overrides (tools, features, include/exclude content). Sub-repos receive independent copies, not symlinks. See the Workspace guide for full details.

Workflow

hatch3r provides a full project lifecycle, from setup to release:

1. Initialize -- npx hatch3r init detects your repo and platform, asks about context and profile, generates agents/skills/rules/commands/MCP. For headless CI, pass --yes with optional flags. See agentic process diagrams.
2. Set up the board -- hatch3r-board-init creates or connects a Projects V2 board with status fields, label taxonomy, and config writeback.
3. Define work -- Create a todo.md at the project root (one item per line).
4. Fill the board -- hatch3r-board-fill parses todo.md, classifies items, groups into epics, builds a dependency DAG, and marks issues status:ready.
5. Groom the backlog -- hatch3r-board-groom surfaces stale items, priority imbalances, and decomposition candidates for selective refinement.
6. Pick up work -- hatch3r-board-pickup auto-selects the next issue by dependency order and priority, creates a branch, delegates implementation, and opens a PR.
7. Review cycle -- Reviewer + fixer agents loop (max 3 iterations) until clean, then test-writer and security-auditor run final checks.
8. Release -- hatch3r-release determines the semver bump, generates a changelog, tags, and publishes.

After init: For greenfield, run hatch3r-project-spec then hatch3r-roadmap. For brownfield, run hatch3r-codebase-map. For a single feature, run hatch3r-feature-plan. For small changes, run hatch3r-quick-change.

Commands

CLI Commands

npx hatch3r init          # Interactive setup
npx hatch3r config        # Reconfigure tools, MCP servers, features, and platform
npx hatch3r sync          # Re-generate from canonical state
npx hatch3r update        # Pull latest templates (safe merge)
npx hatch3r status        # Check sync status between canonical and generated files
npx hatch3r validate      # Validate canonical .agents/ structure
npx hatch3r verify        # Verify file integrity checksums
npx hatch3r clean                 # Remove generated files (optional --reinit)
npx hatch3r worktree-setup <path>  # Set up gitignored files in a worktree
npx hatch3r worktree-cleanup <path> # Clean up worktree-specific files
npx hatch3r cli-tools     # Manage CLI tools (picker / list / install / detect)
npx hatch3r mcp           # Manage MCP servers (setup / list / remove / env-check)
npx hatch3r add <pack>    # Install a community pack (coming soon)

hatch3r cli-tools and hatch3r mcp are side-door entry points for users who skipped a section during init or want to revisit later. Each accepts subcommands: cli-tools defaults to opening the picker (list, install, detect are the other subcommands); mcp requires a subcommand (setup, list, remove <id>, env-check).

Agent Commands

These commands are invoked inside your coding tool (e.g., as Cursor commands).

Board management: board-init, board-fill, board-groom, board-pickup, board-refresh, board-shared

Planning: project-spec, codebase-map, roadmap, feature-plan, bug-plan, refactor-plan, migration-plan, test-plan, api-spec

Workflow: workflow, quick-change, revision, debug, onboard, benchmark, hooks, learn, recipe, pr-resolve, handoff

Operations: healthcheck, security-audit, dep-audit, release, context-health, cost-tracking, report

Customization: create, agent-customize, command-customize, skill-customize, rule-customize

All commands are prefixed with hatch3r- (e.g., hatch3r-board-fill). See the CLI Commands reference and Agent Commands reference for full details.

CLI Tools

Since 1.7.5, hatch3r ships a first-class CLI-tools surface area as the token-efficient alternative to MCP. The picker runs during init (3 tiers grouped, tier-1 default-on, tier-2 conditional on detected project signals, tier-3 opt-in advanced). Detection probes each tool via command -v / where with a 2s timeout; the installer prints copy-paste commands grouped by package manager and never executes on your behalf. Every selected tool ships a per-tool skill (skills/hatch3r-cli-{id}/SKILL.md) plus the hatch3r-cli-overview decision-tree skill, emitted to the 13 skill-capable adapters.

Manage CLI tools at any time:

npx hatch3r cli-tools           # open picker
npx hatch3r cli-tools list      # selection + install status
npx hatch3r cli-tools install   # print install commands for missing tools
npx hatch3r cli-tools detect    # read-only detection report

See CLI Tools for the full 29-tool table, decision tree, and trade-off discussion vs MCP.

MCP Configuration

Since 1.7.5, MCP is opt-in. npx hatch3r init gates MCP behind a Yes/No prompt (default No) after the features picker. Declining the gate skips MCP entirely — no .env.mcp, no mcp.json, no servers in the manifest. When you accept the gate, hatch3r init creates a .env.mcp file with required environment variables for your selected MCP servers (gitignored by default) and writes MCP config to the tool-appropriate location (.cursor/mcp.json, .mcp.json, .vscode/mcp.json, etc.).

• VS Code / Copilot: Secrets are passed via the env object in .vscode/mcp.json.
• Cursor / Claude Code / others: Source the file first: set -a && source .env.mcp && set +a && cursor .

Manage MCP at any time via npx hatch3r mcp setup | list | remove <id> | env-check. See MCP Setup for full setup, per-server details, and PAT scope guidance.

Upgrading from 1.7.1 or earlier?

BREAKING for npx hatch3r init --yes CI scripts: As of 1.7.5, MCP servers are no longer configured by default in non-interactive mode. Add --mcp to your invocation to restore prior behavior — without it, manifest.mcp.servers will be empty and no .env.mcp will be created. The interactive init flow gates MCP behind a Yes/No prompt defaulting to No.

CLI tools land as the recommended default. Existing 1.7.1 manifests upgrade silently (cliTools is optional — absence is treated as opted-out). Run npx hatch3r cli-tools on an existing project to opt in; the picker offers tier-1 default-on plus tier-2 tools matching your project signals, and prints per-OS install commands without executing them. npx hatch3r clean → npx hatch3r init preserves your cliTools.selected selection.

Platform Agentic Workflows

hatch3r includes a complete board management system supporting GitHub, Azure DevOps, and GitLab. Configure in hatch.json:

{
  "board": {
    "owner": "my-org",
    "repo": "my-repo",
    "projectNumber": 1,
    "areas": ["area:frontend", "area:backend", "area:infra"]
  },
  "models": {
    "default": "opus",
    "agents": { "hatch3r-lint-fixer": "sonnet" }
  }
}

Sub-Agentic Architecture

• Four-phase pipeline -- Research, Implement, Review Loop (reviewer + fixer, max 3 iterations), Final Quality (testing + security)
• Implementer agent -- Receives a single sub-issue, delivers code + tests, reports back
• Fixer agent -- Takes reviewer findings and implements targeted fixes
• Issue workflow skill -- 8-step structured workflow with parallel sub-agent delegation for epics
• Tooling hierarchy -- Project docs > Codebase search > Library docs (Context7) > Web research

Content Profiles

During hatch3r init, you choose a content profile:

| Profile | What's included | Best for | |---------|----------------|----------| | Minimal | Core agents and workflows only (core tag) | Quick setup, minimal footprint | | Standard (recommended) | Full development lifecycle without niche audits | Most projects | | Full | Everything including board management and all audits | Large teams, full coverage | | Custom | Choose exactly what you need | Fine-grained control |

Content is tagged with workflow, context, and domain tags. After init, use hatch3r config to add or remove individual content items.

How hatch3r differs from Ruler

Ruler (@intellectronica/ruler) is the closest architectural analogue to hatch3r -- both distribute from a single canonical source to multiple AI coding tools. Ruler's model is simpler per-adapter emission of markdown rules only. hatch3r ships a deeper content model, integrity surface, and governance system:

| Dimension | hatch3r | Ruler | |-----------|---------|-------| | Tool targets | 15 native adapters generating tool-specific primitives (Cursor .mdc frontmatter, Claude Code skills + hooks, Kiro steering, Copilot prompts) | 32 rule-distribution targets (markdown rules only; no tool-specific feature utilization) | | Canonical content model | 6 artifact types (agents, skills, rules, commands, hooks, MCP servers) plus board workflows and learning loop, indexed in hatch.json | 1 artifact type (rules) | | Managed blocks | <!-- HATCH3R:BEGIN --> / <!-- HATCH3R:END --> markers on every bridge file preserve user content across updates (src/merge/managedBlocks.ts) | Full-file replacement semantics | | Integrity manifest | SHA-256 per-file + manifest-level checksum in hatch.json; safe merge via temp file + atomic rename (src/merge/safeWrite.ts, src/integrity/index.ts) | None | | Governance audit cycle | 21-domain audit cycle with 121 sub-agents, 4-wave execution, closed-loop PRD evolution (governance/AUDIT.md, governance/AUDIT-EXECUTE.md) | None | | Supply-chain provenance | npm OIDC trusted publishing + --provenance attestations via .github/workflows/release.yml (SLSA-level provenance) | Not published with OIDC trusted publishing | | Security | OWASP Agentic Top 10 coverage via src/pipeline/agentToolAllowlist.ts + src/pipeline/mcpDescriptionScan.ts + src/pipeline/promptGuard.ts (500KB input / 1MB output limits) | Rule distribution only |

See governance/COMPETITIVE-ANALYSIS.md section 4 (Feature Comparison) for the full matrix.

Customization

hatch3r separates managed from custom files:

• hatch3r-* files are managed by hatch3r and fully replaced on update
• Files without the prefix are your customizations and are never touched
• All hatch3r-generated markdown files use managed blocks (<!-- HATCH3R:BEGIN --> / <!-- HATCH3R:END -->). Content outside these markers is preserved. Bridge files are emitted by 15 adapters: Cursor, Claude, Copilot, Cline, Codex, Gemini, Windsurf, Amp, OpenCode, Aider, Kiro, Goose, Zed, Amazon Q, Antigravity.

Model Selection

Configure preferred AI models per agent via hatch.json (global default and per-agent overrides), canonical agent frontmatter, or .hatch3r/agents/{id}.customize.yaml. Resolution order: customization file > manifest per-agent > agent frontmatter > manifest default.

See Model Selection for the full guide.

Cursor Plugin

hatch3r is also available as a Cursor plugin. Enable it for instant access to all rules, skills, agents, and commands without running init.

Documentation

Full documentation is available at docs.hatch3r.com.

• Vision -- Framework north-star vision and principles
• MCP Setup -- Connecting MCP servers and managing secrets
• Adapter Capability Matrix -- Per-tool support and output paths
• Agent Teams -- Multi-agent team coordination and delegation patterns
• Model Selection -- Configuring AI models per agent
• Agentic Process -- Visual diagrams of init flow, board workflow, and agent orchestration
• Troubleshooting -- Common issues and solutions
• Changelog -- Release history

License

MIT