Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hatch3r/hatch3r

Production-ready spec driven development setup for AI coding agents in any repo with one command. Pre-configured with 11 agents, 22 skills, 18 rules, 25 commands & MCP integrations for Cursor, GitHub Copilot, Claude Code, Windsurf, Amp, Codex, Gemini CLI, Cline & OpenCode.
https://github.com/hatch3r/hatch3r

agentic agents ai claude cli codex coding-assistant copilot cursor developer-tools gemini mcp windsurf

Last synced: 21 days ago
JSON representation

Production-ready spec driven development setup for AI coding agents in any repo with one command. Pre-configured with 11 agents, 22 skills, 18 rules, 25 commands & MCP integrations for Cursor, GitHub Copilot, Claude Code, Windsurf, Amp, Codex, Gemini CLI, Cline & OpenCode.

Awesome Lists containing this project

README 

          
# hatch3r



[![npm version](https://img.shields.io/npm/v/hatch3r.svg)](https://www.npmjs.com/package/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. One command gives you up to 16 agents, 26 skills, 26 rules, 34 commands, and MCP integrations -- optimized for your coding tool of choice. Selective init installs only what you need based on your project type and team size.



## Quick Start



Requires Node.js 22+.



```bash

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](https://docs.hatch3r.com/docs/troubleshooting).



## What You Get



| Category | Count | Highlights |

|----------|-------|-----------|

| **Agents** | 16 | Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, and more |

| **Skills** | 26 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, recipes, API spec, CI pipeline, migration, customization, and more |

| **Rules** | 26 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, and more |

| **Commands** | 34 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, and more |

| **MCP Servers** | 10 (3 default + 7 opt-in) | Playwright, Context7, Filesystem (default); GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab (opt-in) |

| **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

    ...

```



```bash

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](https://docs.hatch3r.com/docs/guides/workspace) 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](https://docs.hatch3r.com/docs/guides/agentic-process).

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



```bash

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   # Set up gitignored files in a worktree

npx hatch3r worktree-cleanup  # Clean up worktree-specific files

npx hatch3r add     # Install a community pack (coming soon)

```



### 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`



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



**Customization:** `agent-customize`, `command-customize`, `skill-customize`, `rule-customize`



All commands are prefixed with `hatch3r-` (e.g., `hatch3r-board-fill`). See the [CLI Commands reference](https://docs.hatch3r.com/docs/reference/commands/cli-commands) and [Agent Commands reference](https://docs.hatch3r.com/docs/reference/commands/agent-commands) for full details.



## MCP Configuration



`hatch3r init` creates a `.env.mcp` file with required environment variables for your selected MCP servers (gitignored by default). MCP config is written 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 .`



See [MCP Setup](https://docs.hatch3r.com/docs/guides/mcp-setup) for full setup, per-server details, and PAT scope guidance.



## Platform Agentic Workflows



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



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



## 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 (`` / ``). 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](https://docs.hatch3r.com/docs/guides/model-selection) for the full guide.



## Cursor Plugin



hatch3r is also available as a [Cursor plugin](https://cursor.com/marketplace). Enable it for instant access to all rules, skills, agents, and commands without running `init`.



## Documentation



Full documentation is available at [docs.hatch3r.com](https://docs.hatch3r.com).



- [Vision](governance/VISION.md) -- Framework north-star vision and principles

- [MCP Setup](https://docs.hatch3r.com/docs/guides/mcp-setup) -- Connecting MCP servers and managing secrets

- [Adapter Capability Matrix](https://docs.hatch3r.com/docs/reference/adapter-capability-matrix) -- Per-tool support and output paths

- [Agent Teams](https://docs.hatch3r.com/docs/guides/agent-teams) -- Multi-agent team coordination and delegation patterns

- [Model Selection](https://docs.hatch3r.com/docs/guides/model-selection) -- Configuring AI models per agent

- [Agentic Process](https://docs.hatch3r.com/docs/guides/agentic-process) -- Visual diagrams of init flow, board workflow, and agent orchestration

- [Troubleshooting](https://docs.hatch3r.com/docs/troubleshooting) -- Common issues and solutions

- [Changelog](CHANGELOG.md) -- Release history



## License



MIT