hatch3r 1.8.0 → 2.0.0

package/README.md

@@ -4,129 +4,76 @@
 
 **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`](governance/inventory.json) <!-- counts auto-derived; see governance/inventory.json -->). Selective init installs only what you need based on your project type and team size.
+hatch3r is an open-source CLI and editor plugin (Claude Code + Cursor) that installs a tool-agnostic agentic coding setup into any repository. Audited each release across 24 governance domains and generated for 3 platform adapters (Claude Code, Cursor, GitHub Copilot). 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`](governance/inventory.json) <!-- counts auto-derived; see governance/inventory.json -->). Selective init installs only what you need based on your project type and team size.
+
+> **v1.9.0 scope cut:** As of 1.9.0 hatch3r supports only Claude Code, Cursor, and GitHub Copilot. Twelve adapters were removed in a hard cut; canonical content is now read from the bundled npm package (no `.agents/` materialization in user repos), and the manifest moved to `.hatch3r/hatch.json`. See [CHANGELOG.md](CHANGELOG.md) for the full breaking-change list and migration notes.
 
 ## Quick Start
 
 Requires Node.js 22+.
 
 ```bash
-npx hatch3r init
+npx hatch3r init --default  # recommended: zero-prompt setup with the standard profile
+npx hatch3r init            # interactive: customize profile, tools, and CLI tools (6 prompts for GitHub greenfield; +1 for Azure DevOps, +1 for `custom` preset, +1 for workspace mode)
 ```
 
-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).
+`--default` generates a working standard-profile setup with no questions — the fastest path to a configured repo. The interactive `init` detects your repo, infers your project context (greenfield/brownfield, solo/team), then walks platform → repo identity → content profile (minimal/standard/full/custom) → tools → CLI-tools picker, and generates everything. MCP is not prompted — opt in with `--mcp` or `npx hatch3r mcp setup` later. The platform (GitHub, Azure DevOps, or GitLab) is auto-detected from your git remote either way. Run into issues? See [Troubleshooting](https://docs.hatch3r.com/docs/troubleshooting).
+
+**Already using Cursor?** Carry your existing rules across with `npx hatch3r init --import cursor` — they land under `.hatch3r/overrides/rules/` (`.md` + `.mdc`) with per-file conflict reporting. See [Migrating from another tool](https://docs.hatch3r.com/docs/getting-started/quick-start#migrating-from-another-tool).
 
 ## 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 |
+| **Agents** | 29 | Code reviewer, lint-fixer, dependency auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, handoff loader / preparer, 9 content-quality specialists (UI/UX/security/reliability/testability/scalability/performance/maintainability/enhancability), and more |
+| **Skills** | 53 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, handoff prepare / resume, recipes, API spec, CI pipeline, migration, customization, board lifecycle, ad-hoc orchestration scaffold, 5 standalone CLI-tool skills (ripgrep, jq, gh, fd, fzf) + a 24-tool `cli-toolbox`, and more |
+| **Rules** | 67 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, fan-out discipline, right-sizing, deep context analysis, handoff readiness, mobile + backend stack rules, and more |
+| **Commands** | 30 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, bug-pipeline, revision, debug, healthcheck, security-audit, onboard, benchmark, 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) |
+| **MCP Servers** | 10 (opt-in) | Playwright, Context7, Filesystem, GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab -- pure opt-in since 2.0.0: `init --mcp` or `npx hatch3r mcp setup` (interactive init does not prompt for MCP; `features.mcp` defaults to false) |
 | **Platforms** | 3 | GitHub, Azure DevOps, GitLab -- auto-detected from git remote |
 
-## Supported Tools (15 Adapters)
+## Supported Tools (3 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/                              <- hatch3r footprint in your repo
+  ├── hatch.json                       <- Manifest
+  ├── overrides/                       <- User-authored canonical overrides (escape hatch)
+  ├── learnings/                       <- /learn-captured project knowledge
+  ├── handoffs/                        <- Cross-session handoff bundles
+  └── mcp/mcp.json                     <- Resolved MCP server config
+
+.claude/                               <- Generated (Claude Code adapter) + CLAUDE.md at repo root
+.cursor/                               <- Generated (Cursor adapter)
+.github/copilot-instructions.md        <- Generated (Copilot adapter, plus .github/instructions, .github/prompts, .github/agents)
+.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
-```
+Canonical content (agents, skills, rules, commands, hooks) lives inside the bundled npm package -- adapters read from there directly, so end-user repos no longer contain a `.agents/` mirror. The only hatch3r-managed directory in your repo is `.hatch3r/`. hatch3r can also manage multiple git repos from a single workspace root -- see the [Workspace guide](https://docs.hatch3r.com/docs/guides/workspace).
 
-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.
+**Where canonical content lives:** to inspect the exact agent/rule/skill files a generated output was produced from, look inside the installed package at `node_modules/hatch3r/dist/content/` (the `agents/`, `skills/`, `rules/`, `commands/`, `hooks/`, `mcp/` subtree). A global install resolves under your npm global prefix (`npm root -g` → `hatch3r/dist/content/`). This bundled tree is read-only and is the single source of truth for canonical inputs.
 
 ## 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).
+1. **Initialize** -- `npx hatch3r init` detects your repo and platform, asks about profile, tools, and CLI tools, generates agents/skills/rules/commands. For headless CI, pass `--yes` (add `--mcp` to also configure MCP servers).
 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.
+5. **Groom the backlog** -- `hatch3r-board-groom` surfaces stale items, priority imbalances, and decomposition candidates.
 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.
+7. **Review cycle** -- Reviewer + fixer agents loop (max 3 iterations) until clean, then testability and security specialists 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`.
@@ -136,95 +83,49 @@ hatch3r provides a full project lifecycle, from setup to release:
 ### CLI Commands
 
 ```bash
-npx hatch3r init          # Interactive setup
+npx hatch3r init          # Interactive setup (or --default for zero prompts)
 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 validate      # Validate bundled canonical content + on-disk adapter outputs
+npx hatch3r verify        # Drift check on adapter outputs (non-zero exit on drift)
+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`
+`hatch3r cli-tools` and `hatch3r mcp` are side-door entry points for users who skipped a section during init. `cli-tools` defaults to the picker (`list`, `install`, `detect` are the other subcommands); `mcp` requires a subcommand (`setup`, `list`, `remove <id>`, `env-check`).
 
-**Planning:** `project-spec`, `codebase-map`, `roadmap`, `feature-plan`, `bug-plan`, `refactor-plan`, `migration-plan`, `test-plan`, `api-spec`
+Every non-stub command accepts `--format <human|json>` and `--quiet`; mutating commands add `--dry-run`. `--format json` emits exactly one JSON document on stdout and is an exit-2 usage error on a prompting invocation.
 
-**Workflow:** `workflow`, `quick-change`, `revision`, `debug`, `onboard`, `benchmark`, `hooks`, `learn`, `recipe`, `pr-resolve`, `handoff`
+### Agent Commands
 
-**Operations:** `healthcheck`, `security-audit`, `dep-audit`, `release`, `context-health`, `cost-tracking`, `report`
+Invoked inside your coding tool (e.g., as Cursor commands). All are prefixed `hatch3r-`.
 
-**Customization:** `create`, `agent-customize`, `command-customize`, `skill-customize`, `rule-customize`
+- **Board management:** `board-fill`, `board-pickup` (lifecycle helpers `board-init`, `board-groom`, `board-refresh`, `board-shared` ship as skills)
+- **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`, `pr-resolve`, `handoff`
+- **Operations:** `healthcheck`, `security-audit`, `report` (helpers `dep-audit`, `release`, `context-health`, `cost-tracking`, `recipe` ship as skills)
+- **Customization:** `create` (single `hatch3r-customize` skill covers agent/command/skill/rule customization)
 
-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.
+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.
 
 ## 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:
-
-```bash
-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](https://docs.hatch3r.com/docs/getting-started/cli-tools) for the full 29-tool table, decision tree, and trade-off discussion vs MCP.
+Since 1.7.5, hatch3r ships a first-class CLI-tools surface 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). 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. 5 essentials (ripgrep, jq, gh, fd, fzf) ship as standalone skills; the remaining 24 tools live in a single `hatch3r-cli-toolbox` skill, emitted to all 3 adapters. Manage at any time via `npx hatch3r cli-tools [list|install|detect]`. See [CLI Tools](https://docs.hatch3r.com/docs/getting-started/cli-tools) for the full 29-tool table and the 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](https://docs.hatch3r.com/docs/guides/mcp-setup) for full setup, per-server details, and PAT scope guidance.
-
-## Upgrading from 1.7.1 or earlier?
+Since 1.7.5, MCP is **opt-in**; since 2.0.0 interactive `npx hatch3r init` no longer offers an MCP prompt. Without an opt-in, init skips MCP entirely -- no `.env.mcp`, no `mcp.json`, no servers in the manifest, and `features.mcp` stays false. When you opt in (`init --mcp` on any init path, or `npx hatch3r mcp setup` afterwards), hatch3r writes a gitignored `.env.mcp` with the required environment variables and MCP config to the tool-appropriate location (`.cursor/mcp.json`, `.mcp.json`, `.vscode/mcp.json`).
 
-**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.
+- **VS Code / Copilot:** secrets pass via the `env` object in `.vscode/mcp.json`.
+- **Cursor / Claude Code / others:** source the file first: `set -a && source .env.mcp && set +a && cursor .`
 
-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`:
-
-```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
+Manage MCP at any time via `npx hatch3r mcp setup | list | remove <id> | env-check`. **CI note:** interactive init no longer offers MCP, and `npx hatch3r init --yes` does not configure it by default -- opt in via `npx hatch3r mcp setup` or `init --mcp`. See [MCP Setup](https://docs.hatch3r.com/docs/guides/mcp-setup) for per-server details and PAT scope guidance.
 
 ## Content Profiles
 
@@ -233,55 +134,44 @@ 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 |
+| **Standard** (recommended) | Full lifecycle; drops AI feature engineering + performance capability clusters -- pick Full if you need those | 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.
+After init, use `hatch3r config` to add or remove individual content items.
+
+## Sub-Agentic Architecture
 
-## How hatch3r differs from Ruler
+A four-phase pipeline (Research, Implement, Review Loop with reviewer + fixer at max 3 iterations, Final Quality with testing + security) drives implementation. The implementer agent receives a single sub-issue and returns code + tests; the fixer agent applies targeted fixes from reviewer findings; the issue-workflow skill runs an 8-step flow with parallel sub-agent delegation for epics. Tooling hierarchy: project docs > codebase search > library docs (Context7) > web research. See [Agent Teams](https://docs.hatch3r.com/docs/guides/agent-teams) for delegation patterns; hatch3r is complementary to rule-distribution tools like Ruler — it owns the full generation pipeline rather than distributing a single instruction file.
 
-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:
+## Why hatch3r vs just AGENTS.md?
 
-| 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 |
+AGENTS.md (Linux Foundation AAIF spec, 60K+ repos as of January 2026) is the greatest-common-denominator markdown standard for agent instructions; it is consumed by 20+ tools including Cursor, Copilot, Codex, and Gemini CLI. hatch3r is complementary: AGENTS.md describes one file's content; hatch3r owns the entire generation pipeline that emits tool-native configurations across 5 artifact classes (rules, skills, commands, hooks, MCP servers) for 3 supported platforms (Claude Code, Cursor, GitHub Copilot). Three measurable differences:
 
-See [governance/COMPETITIVE-ANALYSIS.md](governance/COMPETITIVE-ANALYSIS.md) section 4 (Feature Comparison) for the full matrix.
+- **Scope:** AGENTS.md is one flat instruction file per repo; hatch3r generates platform-specific structured output (`.mdc` rules with frontmatter scoping for Cursor, `CLAUDE.md` with managed blocks for Claude Code, `.github/instructions/` + `.github/prompts/` for Copilot) plus board commands, MCP server configs, and event-driven hooks.
+- **Currency:** AGENTS.md content is hand-edited per project; hatch3r ships canonical content (29 agents + 66 rules + 53 skills + 30 commands + 7 hooks + 10 MCP servers — see [`governance/inventory.json`](governance/inventory.json)) audited weekly across 24 governance domains.
+- **Adoption path:** AGENTS.md remains the spec hatch3r-emitted Cursor / Claude / Copilot configurations align with — the 1.9.0 hard-cut withdrew direct AGENTS.md emission per CONSTITUTION §6 Decision #12, but AAIF spec evolution feeds per-adapter feature work for the 3 supported adapters. Use AGENTS.md alone when one flat file suffices for your project; use hatch3r when you need the full content + tooling stack.
 
 ## 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](https://docs.hatch3r.com/docs/guides/model-selection) for the full guide.
+- `hatch3r-*` files are managed and fully replaced on update; files without the prefix are your customizations and are never touched.
+- All hatch3r-generated markdown uses managed blocks (`<!-- HATCH3R:BEGIN -->` / `<!-- HATCH3R:END -->`); content outside the markers is preserved.
+- User-authored canonical overrides live under `.hatch3r/overrides/` (escape hatch); adapters prefer overrides over bundled content.
+- Configure preferred AI models per agent via `hatch.json` (global default + per-agent overrides), 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).
 
-## Cursor Plugin
+## Editor 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`.
+hatch3r ships plugin manifests for both Claude Code (`.claude-plugin/marketplace.json`) and Cursor (`.cursor-plugin/plugin.json`). Install it straight from this repo as a marketplace — in Claude Code, run `/plugin marketplace add hatch3r/hatch3r` then `/plugin install hatch3r@hatch3r` — for access to all rules, skills, agents, and commands without running `init`.
 
 ## Documentation
 
-Full documentation is available at [docs.hatch3r.com](https://docs.hatch3r.com).
+Full documentation is at [docs.hatch3r.com](https://docs.hatch3r.com).
 
-- [Vision](governance/VISION.md) -- Framework north-star vision and principles
+- [Vision](https://docs.hatch3r.com/docs/about) -- 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