hatch3r 1.1.0 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 **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 16 agents, 25 skills, 22 rules, 33 commands, and MCP integrations -- optimized for your coding tool of choice.
+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, 25 skills, 22 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
 
@@ -14,7 +14,7 @@ Requires Node.js 22+.
 npx hatch3r init
 ```
 
-That's it. hatch3r detects your repo, asks which platform and tools you use, and generates everything. The platform (GitHub, Azure DevOps, or GitLab) is auto-detected from your git remote. Run into issues? See [Troubleshooting](docs/troubleshooting.md).
+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
 
@@ -23,63 +23,30 @@ That's it. hatch3r detects your repo, asks which platform and tools you use, and
 | **Agents** | 16 | Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, and more |
 | **Skills** | 25 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, recipes, API spec, CI pipeline, migration, customization, and more |
 | **Rules** | 22 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, and more |
-| **Commands** | 33 | Board init, board fill, board groom, board pickup, board refresh, planning (feature, bug, refactor), workflow, quick-change, revision, debug, healthcheck, security-audit, context-health, cost-tracking, onboard, benchmark, customization, 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 Platforms
-
-hatch3r supports three project management platforms as first-class targets:
-
-| Platform | Board system | MCP server | Auth |
-|----------|-------------|------------|------|
-| **GitHub** | Projects V2 | GitHub MCP (remote) | `GITHUB_PAT` |
-| **Azure DevOps** | Boards / Work Items | @tiberriver256/mcp-server-azure-devops | `AZURE_DEVOPS_PAT`, `AZURE_DEVOPS_ORG` |
-| **GitLab** | Issues / Boards | glab mcp | `GITLAB_TOKEN` |
-
-Platform is auto-detected from your git remote during `hatch3r init`. All board commands, agents, rules, and skills adapt to your selected platform. The manifest uses generic `namespace`/`project`/`repo` fields (backward-compatible with `owner`/`repo`).
-
-## Supported Tools
-
-- **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.md`, specs
-- **Goose** -- `.goosehints`
-- **Zed** -- `.rules`
-
-### MCP Configuration
-
-**Connecting MCP servers**
-
-- **Cursor (init):** MCP config is written to `.cursor/mcp.json` when you run `npx hatch3r init` and select MCP servers. Restart Cursor after init.
-- **Cursor (plugin):** The plugin provides `mcp.json` at the project root. Cursor loads it from there or from `~/.cursor/mcp.json` (project-level takes precedence).
-- **Claude Code:** Config goes to `.mcp.json` in the project root.
-- **Other tools:** Copilot uses `.vscode/mcp.json`; Cline/Roo uses `.roo/mcp.json`.
-
-**Managing secrets**
-
-`hatch3r init` creates a `.env.mcp` file at the project root with all required environment variables for your selected MCP servers. This file is gitignored by default. Fill in your API keys:
-
-```bash
-# .env.mcp (generated by hatch3r init)
-GITHUB_PAT=ghp_xxxx
-BRAVE_API_KEY=xxxx
-```
-
-How secrets are loaded depends on your editor:
-
-- **VS Code / Copilot**: Secrets load automatically from `.env.mcp` via the native `envFile` field -- no extra steps.
-- **Cursor / Claude Code / others**: Source the file before launching your editor: `set -a && source .env.mcp && set +a && cursor .`
-
-See [docs/mcp-setup.md](docs/mcp-setup.md) for full setup, per-server details, and PAT scope guidance.
+## Supported Tools (14 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/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
 
@@ -101,70 +68,29 @@ AGENTS.md              <- Generated (OpenCode, Amp, Codex adapters)
 GEMINI.md              <- Generated (Gemini adapter)
 .clinerules            <- Generated (Cline adapter)
 CONVENTIONS.md         <- Generated (Aider adapter)
-kiro.md                <- Generated (Kiro adapter)
+.kiro/                 <- Generated (Kiro adapter)
 .goosehints            <- Generated (Goose adapter)
 .rules                 <- Generated (Zed adapter)
+.amazonq/              <- Generated (Amazon Q adapter)
+.worktreeinclude       <- Generated (worktree isolation)
 ```
 
 hatch3r keeps one source of truth in `.agents/` and generates native configuration for each tool.
 
 ## Workflow
 
-hatch3r provides a full project lifecycle, from setup to release. Here is the typical flow:
-
-### 1. Initialize
-
-```bash
-npx hatch3r init
-```
-
-Interactive setup detects your repository and platform (GitHub, Azure DevOps, or GitLab), asks which coding tools you use, and generates all agents, skills, rules, commands, and MCP configuration. See the [agentic process diagrams](docs/agentic-process.md) for a visual overview of the full workflow.
-
-> **Next steps after init:** For a new project, run `hatch3r-project-spec`. For an existing codebase, run `hatch3r-codebase-map`. To plan a single feature, run `hatch3r-feature-plan`. To investigate a complex bug, run `hatch3r-bug-plan`. To plan a refactoring effort, run `hatch3r-refactor-plan`. For small, board-free changes (typos, config tweaks, small refactors), run `hatch3r-quick-change`. Or skip straight to creating a `todo.md` and running `hatch3r-board-fill`.
-
-### For new projects (greenfield)
-
-If you're starting from scratch, use `hatch3r-project-spec` to generate documentation from your vision, then `hatch3r-roadmap` to create a phased plan:
-
-1. Run `hatch3r-project-spec` with your project idea — produces `docs/specs/`, `docs/adr/`, and `todo.md`
-2. Run `hatch3r-roadmap` to refine the plan into dependency-ordered epics
-3. Continue with `hatch3r-board-fill` (step 4 below) to create GitHub issues
+hatch3r provides a full project lifecycle, from setup to release:
 
-### For existing projects (brownfield)
+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.
 
-If you're adding hatch3r to an existing codebase, use `hatch3r-codebase-map` to analyze what's already there:
-
-1. Run `hatch3r-codebase-map` — spawns analyzers to discover modules, conventions, and tech debt
-2. Run `hatch3r-roadmap` to plan improvements from the analysis
-3. Continue with `hatch3r-board-fill` (step 4 below) to create GitHub issues
-
-### 2. Set up the board
-
-Run the `hatch3r-board-init` command to create or connect a GitHub Projects V2 board. You do not need to manually create a GitHub Project -- `hatch3r-board-init` handles project creation via GraphQL, configures status fields (Backlog, Ready, In Progress, In Review, Done), creates the full label taxonomy, and writes all IDs back to `hatch.json`.
-
-### 3. Define work
-
-Create a `todo.md` file at the project root with your planned work -- epics, features, bugs, refactors, anything. One item per line.
-
-### 4. Fill the board
-
-Run `hatch3r-board-fill` to parse `todo.md` and turn items into GitHub issues. `hatch3r-board-fill` classifies each item by type, priority, executor, area, and risk. It groups items into epics, analyzes dependencies, builds a dependency DAG, determines implementation order, identifies parallel work, and marks issues as `status:ready` when all readiness criteria are met.
-
-### 5. Groom the backlog (ongoing)
-
-As priorities shift, scope evolves, and work gets completed, run `hatch3r-board-groom` to refine the backlog. It surfaces stale items, priority imbalances, missing metadata, and decomposition candidates, then lets you selectively re-prioritize, reclassify, re-scope, archive, or restructure existing issues. Run periodically -- not required every cycle, but recommended when the board drifts from current reality.
-
-### 6. Pick up work
-
-Run `hatch3r-board-pickup` to auto-select the next best issue based on dependency order, priority, and readiness. It performs collision detection against in-progress work and open PRs, creates a branch, delegates implementation to the appropriate skill (or spawns parallel sub-agents for epics), runs quality checks, and creates a pull request with full board status sync.
-
-### 7. Review cycle
-
-The reviewer agent reviews the work. If Critical or Warning findings exist, the fixer agent automatically implements fixes, and the reviewer re-reviews — this loop repeats until clean (max 3 iterations). After the review loop passes, the test-writer and security-auditor agents run final quality checks in parallel. For structured post-implementation revision, open a fresh context window and run `hatch3r-revision` -- it interviews you for feedback, scans for agent leftovers, delegates fixes to specialist sub-agents, and drives toward merge readiness.
-
-### 8. Release
-
-Run the `hatch3r-release` command to cut a versioned release. It classifies merged PRs to determine the semantic version bump, generates a grouped changelog, runs quality gates, creates a git tag, publishes a GitHub release, and optionally triggers deployment.
+> **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
 
@@ -177,169 +103,39 @@ 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 worktree-setup <path>  # Set up gitignored files in a worktree
 npx hatch3r add <pack>    # Install a community pack (coming soon)
 ```
 
 ### Agent Commands
 
-These commands are invoked inside your coding tool (e.g., as Cursor commands):
-
-**`hatch3r-board-init`** -- Bootstrap a GitHub Projects V2 board for your repository. Creates a new project or connects to an existing one, configures status fields with five default columns, creates the full hatch3r label taxonomy (type, executor, status, priority, risk, meta), prompts for default branch (main/master), optionally migrates issues from another project, and writes all project IDs back to `hatch.json`. All mutations require user confirmation.
-
-**`hatch3r-board-fill`** -- Parse `todo.md` and create GitHub epics and issues with full board reorganization. Deduplicates against existing issues, classifies each item by type/executor/priority/area/risk, groups into epics, builds a dependency graph, determines implementation order, identifies parallel work lanes, and marks issues as `status:ready` when all readiness criteria are met. Reads project documentation and codebase context to produce well-scoped issues.
-
-**`hatch3r-board-groom`** -- Ongoing backlog refinement for existing board items. Scans all open issues, surfaces health-driven refinement suggestions (stale items, priority imbalances, missing metadata, decomposition candidates, duplicates), and lets you selectively apply grooming actions: re-prioritize, reclassify, re-scope, demote to triage, archive stale items, decompose oversized issues, merge duplicates, refresh dependencies, and remediate board health gaps. Complements `hatch3r-board-fill` (which ingests new work) and `hatch3r-board-refresh` (which is read-only).
-
-**`hatch3r-board-pickup`** -- Pick up the next best issue from the board for development. Auto-selects based on dependency order and priority when no specific issue is referenced. Performs collision detection against in-progress work, creates a branch, marks the issue in-progress, runs adaptive deep context analysis (complexity scoring, requirements elicitation, similar implementation discovery, transitive dependency tracing), delegates to the appropriate implementation skill with convention lock, and creates a pull request with label transitions and Projects V2 status sync.
-
-**`hatch3r-board-refresh`** -- Regenerate the living board overview dashboard on demand. Scans all open and recently closed issues, computes board health metrics (missing metadata, stale issues, blocked dependency chains), assigns recommended models using the quality-first heuristic, and updates the `meta:board-overview` issue with current status tables, epic progress, and health diagnostics. No user prompts required.
-
-**`hatch3r-board-shared`** -- Shared context and procedures referenced by all board commands. Provides board configuration from `hatch.json`, GitHub context, Projects V2 sync procedure, label taxonomy, tooling directives, and token-saving guidelines. Not invoked directly.
-
-**`hatch3r-healthcheck`** -- Create a full-product QA and testing audit epic. Discovers logical modules from the project's directory structure, creates a parent epic with one sub-issue per module plus cross-cutting audits for inter-module wiring and product vision alignment. Each audit sub-issue, when picked up via `hatch3r-board-pickup`, performs deep static analysis and produces a findings epic with actionable sub-issues.
-
-**`hatch3r-security-audit`** -- Create a full-product security audit epic. Discovers logical modules from the project's directory structure, creates a parent epic with one sub-issue per module plus cross-cutting audits for trust boundaries and OWASP Top 10 alignment. Each module sub-issue audits 7 security domains (authentication, input validation, data protection, access control, secret management, error handling, API security) and produces a findings epic with severity-rated, actionable sub-issues.
-
-**`hatch3r-dep-audit`** -- Scan, assess, and upgrade npm dependencies. Runs `npm audit` and `npm outdated` across root and workspace packages, categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths via Context7 and web search, upgrades packages one at a time with testing after each, and creates tracking issues for any unaddressed items.
-
-**`hatch3r-release`** -- Cut a versioned release with changelog. Determines the semantic version bump from merged PR classifications, generates a grouped changelog (features, fixes, refactors, docs, infra), runs quality verification, bumps `package.json`, creates a git tag, publishes a GitHub release with notes, and optionally verifies deployment.
+These commands are invoked inside your coding tool (e.g., as Cursor commands).
 
-**`hatch3r-project-spec`** -- Generate complete project documentation from a project vision using parallel researcher sub-agents (stack, features, architecture, pitfalls, UX, business model & market, production & scale). Produces `docs/specs/`, `docs/adr/`, and `todo.md`. Works for any project type -- web apps, APIs, CLIs, libraries, or monorepos.
+**Board management:** `board-init`, `board-fill`, `board-groom`, `board-pickup`, `board-refresh`, `board-shared`
 
-**`hatch3r-api-spec`** -- Generate API specifications from project requirements and existing code. Produces OpenAPI/Swagger specs with endpoint definitions, request/response schemas, authentication, and documentation. Integrates with `hatch3r-project-spec` for greenfield and `hatch3r-codebase-map` for brownfield.
+**Planning:** `project-spec`, `codebase-map`, `roadmap`, `feature-plan`, `bug-plan`, `refactor-plan`, `migration-plan`, `test-plan`, `api-spec`
 
-**`hatch3r-codebase-map`** -- Analyze an existing codebase to reverse-engineer specifications. Spawns parallel analyzer sub-agents to discover modules, dependencies, conventions, and tech debt. Outputs structured documentation to `docs/specs/` and `docs/adr/`.
+**Workflow:** `workflow`, `quick-change`, `revision`, `debug`, `onboard`, `benchmark`, `hooks`, `learn`, `recipe`
 
-**`hatch3r-roadmap`** -- Generate a phased roadmap from specs or project vision. Breaks work into epics and features with dependency ordering and parallel work lane identification. Outputs to `todo.md` in `hatch3r-board-fill` format, ready for immediate board population.
+**Operations:** `healthcheck`, `security-audit`, `dep-audit`, `release`, `context-health`, `cost-tracking`
 
-**`hatch3r-feature-plan`** -- Plan a single feature in depth. Spawns parallel researcher sub-agents (codebase impact, feature design, architecture, risk & pitfalls) to break a feature idea into a detailed spec, ADR(s) when architectural decisions are involved, and structured `todo.md` entries for `hatch3r-board-fill`. Optionally chains directly into `hatch3r-board-fill` to create GitHub issues.
+**Customization:** `agent-customize`, `command-customize`, `skill-customize`, `rule-customize`
 
-**`hatch3r-bug-plan`** -- Plan a complex bug investigation. Spawns parallel researcher sub-agents (symptom tracer, root cause investigator, impact assessor, regression researcher) to diagnose ambiguous bugs where the root cause is unknown. Produces an investigation report (`docs/investigations/`) with ranked hypotheses, evidence, and reproduction strategy, plus scoped `todo.md` entries for `hatch3r-board-fill`. Use when reproducing is non-trivial or multiple modules might be involved.
+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.
 
-**`hatch3r-refactor-plan`** -- Plan a refactoring or migration effort. Spawns parallel researcher sub-agents (current state analyzer, strategy designer, impact/risk assessor, migration path planner) to design a phased execution plan. Auto-detects the refactoring dimension (structural, logical, visual, migration, or mixed) and adapts researcher prompts accordingly. Produces a refactoring spec, ADR(s), and phased `todo.md` entries mapped to the appropriate execution skill.
+## MCP Configuration
 
-**`hatch3r-migration-plan`** -- Plan a database or system migration with backward-compatible schema changes, idempotent migration scripts, rollback plans, data validation, and phased execution strategy. Produces migration specs and `todo.md` entries for `hatch3r-board-fill`.
+`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.).
 
-**`hatch3r-onboard`** -- Interactive project onboarding for new team members and AI agents. Scans the repository to build a contextual overview of project structure, conventions, key modules, and development workflow. Produces a personalized onboarding guide.
+- **VS Code / Copilot**: Secrets load automatically via the native `envFile` field.
+- **Cursor / Claude Code / others**: Source the file first: `set -a && source .env.mcp && set +a && cursor .`
 
-**`hatch3r-benchmark`** -- Run and compare benchmark suites for code performance. Captures before/after metrics, detects regressions, and produces structured reports with statistical analysis.
+See [MCP Setup](https://docs.hatch3r.com/docs/guides/mcp-setup) for full setup, per-server details, and PAT scope guidance.
 
-**`hatch3r-workflow`** -- Guided development lifecycle with 4 phases: Analyze, Plan, Implement, and Review. Includes a quick mode for small tasks that skips unnecessary ceremony. Scale-adaptive -- adjusts depth based on issue complexity and scope.
+## Platform Agentic Workflows
 
-**`hatch3r-quick-change`** -- Lightweight command for small, board-free changes (typo fixes, constant tweaks, config updates, small refactors). Parses batch input, applies soft scope guards (5 files / 200 lines threshold), classifies items as trivial (inline) or nontrivial (implementer sub-agent), runs quality checks, and optionally delegates a light review. Supports batching multiple small changes into a single commit. Sits alongside `hatch3r-workflow` as a lower-ceremony alternative.
-
-**`hatch3r-revision`** -- User-guided revision of agent-implemented code in a fresh context window. Reconstructs what was done from the git diff, interviews the user for structured feedback, proactively scans for agent leftovers (dead code, TODOs, type issues), delegates fixes to specialist sub-agents (implementer, lint-fixer, test-writer), runs quality checks, commits and pushes, and assesses merge readiness. Designed for the feedback loop between implementation and merge.
-
-**`hatch3r-debug`** -- Standalone debug-and-fix command. Adds strategic debug logging (`[HATCH3R-DEBUG]` prefixed) to the affected code area, pauses for the user to reproduce the issue and provide runtime logs, performs root cause analysis from the collected evidence, implements the fix, removes all debug artifacts, and runs the full review-fix-test-security pipeline. Five stages: Gather Context, Add Debug Logging, Collect Logs, Root Cause Analysis, Implement Fix. No board integration required.
-
-**`hatch3r-hooks`** -- Interactive hook management for event-driven agent activation. View, add, remove, and test lifecycle hooks that trigger agents on specific events (e.g., post-commit, pre-push, issue assignment). Supports both local and CI hook targets.
-
-**`hatch3r-learn`** -- Capture learnings from completed issues, code reviews, and architectural decisions into reusable knowledge files. Learnings are indexed by topic and auto-consulted when similar work is encountered in the future.
-
-**`hatch3r-context-health`** -- Monitor conversation context health and detect degradation during long agent sessions. Provides metrics on token usage, context window utilization, and recommendations for when to start a fresh session.
-
-**`hatch3r-cost-tracking`** -- Track token usage and estimated costs across agent workflows. Provides per-command and per-agent cost breakdowns with budget alerts.
-
-**`hatch3r-recipe`** -- Create and manage composable workflow recipes. Recipes are reusable workflow templates that chain multiple commands and skills into repeatable sequences.
-
-**`hatch3r-agent-customize`** -- Configure per-agent customization via `.customize.yaml` files. Allows project-specific agent behavior overrides without modifying managed agent definitions.
-
-**`hatch3r-command-customize`** -- Configure per-command customization via `.customize.yaml` files. Allows project-specific command behavior overrides without modifying managed command definitions.
-
-**`hatch3r-skill-customize`** -- Configure per-skill customization via `.customize.yaml` files. Allows project-specific skill behavior overrides without modifying managed skill definitions.
-
-**`hatch3r-rule-customize`** -- Configure per-rule customization via `.customize.yaml` files. Allows project-specific rule behavior overrides without modifying managed rule definitions.
-
-## Agents
-
-| Agent | Description |
-|-------|-------------|
-| **a11y-auditor** | Accessibility specialist who audits WCAG AA compliance -- keyboard navigation, color contrast, ARIA attributes, and reduced motion support. |
-| **architect** | Architecture design and review specialist who evaluates system structure, proposes improvements, and produces ADRs. |
-| **ci-watcher** | CI/CD specialist who monitors GitHub Actions runs, reads failure logs to identify root causes, and suggests focused fixes with local verification commands. |
-| **context-rules** | Dynamic context rule generation agent that creates and maintains context-aware rules based on project patterns and conventions. |
-| **dependency-auditor** | Supply chain security analyst who scans for CVEs, evaluates upgrade paths, assesses bundle size impact, and verifies lockfile integrity. |
-| **devops** | CI/CD and deployment operations specialist who manages build pipelines, infrastructure configuration, and deployment workflows. |
-| **docs-writer** | Technical writer who maintains specs, ADRs, glossary, and process documentation, keeping them in sync with code changes. |
-| **implementer** | Focused implementation agent for a single sub-issue. Receives issue context from a parent orchestrator, delivers code and tests, and reports structured results. Does not handle git or board operations. |
-| **learnings-loader** | Load and apply project learnings from the knowledge base to provide relevant context for current development tasks. |
-| **lint-fixer** | Code quality enforcer who fixes ESLint, Prettier, and TypeScript strict mode violations without changing logic. Removes dead code and unused imports. |
-| **perf-profiler** | Performance engineer who profiles runtime performance, analyzes bundle size, identifies memory leaks, and benchmarks against defined performance budgets. |
-| **researcher** | Research specialist who performs deep investigation on assigned topics using parallel analysis. Used as a sub-agent by planning commands (project-spec, feature-plan, bug-plan, refactor-plan). |
-| **reviewer** | Senior code reviewer who checks for correctness, security, privacy invariants, performance regressions, and accessibility. Outputs structured feedback by priority (critical, warning, suggestion). |
-| **fixer** | Targeted fix agent that takes structured reviewer output (Critical and Warning findings) and implements minimal, focused fixes. Operates in the review loop between reviewer iterations. |
-| **security-auditor** | Security analyst who audits database rules, cloud functions, and data flows. Verifies privacy invariants, writes security rules tests, and validates entitlement enforcement. |
-| **test-writer** | QA engineer who writes deterministic, isolated tests -- unit, integration, E2E, security rules, and contract tests. Focuses on edge cases and regression coverage. |
-
-## Skills
-
-| Skill | Description |
-|-------|-------------|
-| **a11y-audit** | Comprehensive WCAG AA audit with automated scanning, manual verification, and fix implementation. |
-| **agent-customize** | Configure per-agent customization via `.customize.yaml` files. |
-| **api-spec** | API specification generation from project requirements, producing OpenAPI/Swagger specs with endpoint definitions, schemas, and documentation. |
-| **architecture-review** | Evaluate architectural decisions, compare options with pros/cons, and produce ADRs following the project template. |
-| **bug-fix** | Diagnose root cause, implement minimal fix, and write a regression test that fails before the fix. TDD/test-first workflow option. |
-| **ci-pipeline** | CI/CD pipeline setup and configuration for GitHub Actions, including build, test, lint, and deploy workflows. |
-| **command-customize** | Configure per-command customization via `.customize.yaml` files. |
-| **context-health** | Monitor conversation context health and detect degradation during long sessions. |
-| **cost-tracking** | Track token usage and estimated costs across agent workflows. |
-| **dep-audit** | Audit npm dependencies for CVEs and freshness, research migration paths, upgrade one at a time with testing. |
-| **feature** | End-to-end feature implementation as a vertical slice covering data model, domain logic, API, and UI. TDD/test-first workflow option. |
-| **gh-agentic-workflows** | Set up GitHub Agentic Workflows for continuous AI-powered triage, testing, and documentation automation. Includes DoD, verification, troubleshooting, and rollback. |
-| **incident-response** | Structured triage, mitigation, root cause analysis, and post-mortem for production incidents with follow-up issues. |
-| **issue-workflow** | 8-step development workflow for GitHub issues: parse, load skill, read specs, plan, implement, test, PR, address review. |
-| **logical-refactor** | Change business logic or data flows without adding features, with explicit invariant tracking and verification. |
-| **migration** | Database and system migration planning with backward-compatible schema changes, rollback plans, and phased execution. |
-| **perf-audit** | Profile and optimize against defined performance budgets with before/after measurements for every change. |
-| **pr-creation** | Create pull requests following project conventions -- branch naming, PR template, self-review checklist, and size guidelines. |
-| **qa-validation** | E2E validation workflow producing structured pass/fail reports with evidence and ship/hold recommendations. |
-| **recipe** | Create and manage composable workflow recipes. |
-| **refactor** | Internal code quality improvement without changing external behavior, with behavioral preservation tests. |
-| **release** | Cut a release with semantic versioning, changelog generation, pre-release/RC support, git tagging, and deploy verification. |
-| **rule-customize** | Configure per-rule customization via `.customize.yaml` files. |
-| **skill-customize** | Configure per-skill customization via `.customize.yaml` files. |
-| **visual-refactor** | UI/UX changes matching design mockups with WCAG AA accessibility and responsiveness verification. |
-
-## Rules
-
-| Rule | Description |
-|------|-------------|
-| **accessibility-standards** | WCAG AA compliance, ARIA, focus management, color contrast, keyboard and screen reader support, and inclusive design. |
-| **agent-orchestration** | Agent delegation patterns, sub-agent spawning conventions, result aggregation, and multi-agent coordination protocols. |
-| **api-design** | Endpoint versioning, request validation, idempotency keys, structured error responses, auth, CORS, CSP, pagination, and webhook security. |
-| **browser-verification** | When and how to verify UI changes in the browser via automation MCP — dev server lifecycle, navigation, interaction, visual regression, screenshot evidence. |
-| **ci-cd** | CI/CD pipeline standards, build caching, artifact management, deployment gates, and rollback procedures. |
-| **code-standards** | TypeScript strict mode, naming conventions (`camelCase`/`PascalCase`/`SCREAMING_SNAKE`), and function/file length limits. |
-| **component-conventions** | Component structure, typed props/emits, design tokens, WCAG AA accessibility, loading/error/empty states, form UX, and 60fps render targets. |
-| **data-classification** | Data sensitivity levels, PII handling, encryption requirements, retention policies, and cross-border compliance. |
-| **deep-context** | Deep context retrieval, codebase understanding, and efficient context management for AI agents. |
-| **dependency-management** | Lockfile hygiene, new-dependency justification, CVE patching timelines (48h for critical), and bundle size budgets. |
-| **feature-flags** | Flag naming (`FF_AREA_FEATURE`), storage, evaluation, gradual rollout, dependencies, kill switches, 30-day cleanup deadlines, and audit. |
-| **git-conventions** | Git workflow, branch naming, commit message conventions, and merge strategy. |
-| **i18n** | Internationalization, RTL support, locale management, and ICU message format. |
-| **learning-consult** | When and how to consult project learnings during development. |
-| **migrations** | Backward-compatible schema changes, idempotent scripts, rollback plans, and deploy-then-migrate ordering. |
-| **observability** | Structured JSON logging, OpenTelemetry, SLO/SLI, distributed tracing, alerting, dashboards, and no PII in logs. |
-| **performance-budgets** | Core Web Vitals, API latency, database query budgets, bundle size, and enforcement mechanisms. |
-| **secrets-management** | Secret rotation, vault integration, environment variable handling, and credential lifecycle management. |
-| **security-patterns** | Input validation, output encoding, auth enforcement, AI/agentic security, and OWASP alignment. |
-| **testing** | Deterministic, isolated, fast tests with clear naming, regression coverage, no network in unit tests, no `any`. |
-| **theming** | Dark mode, `prefers-color-scheme`, CSS custom properties, and semantic color tokens. |
-| **tooling-hierarchy** | Priority order for knowledge: project specs > codebase > library docs (Context7 MCP) > web research; GitHub CLI-first. |
-
-## Board Management
-
-hatch3r includes a complete board management system supporting GitHub, Azure DevOps, and GitLab:
-
-- **`hatch3r-board-init`** -- Create or connect a GitHub Projects V2 board with status fields, label taxonomy, and optional migration
-- **`hatch3r-board-fill`** -- Parse `todo.md`, create epics/issues, deduplicate, analyze dependencies, set implementation order
-- **`hatch3r-board-groom`** -- Ongoing backlog refinement: re-prioritize, reclassify, re-scope, archive stale items, decompose, merge duplicates, refresh dependencies
-- **`hatch3r-board-pickup`** -- Auto-pick the next best issue, check collisions, delegate to sub-agents, create PRs
-- **`hatch3r-board-refresh`** -- Regenerate the board overview dashboard with current state, health metrics, and model recommendations
-- **`hatch3r-board-shared`** -- Configurable shared context (org, repo, project board IDs, label taxonomy)
-
-Configure your board in `hatch.json`:
+hatch3r includes a complete board management system supporting GitHub, Azure DevOps, and GitLab. Configure in `hatch.json`:
 
 ```json
 {
@@ -351,148 +147,61 @@ Configure your board in `hatch.json`:
   },
   "models": {
     "default": "opus",
-    "agents": {
-      "hatch3r-lint-fixer": "sonnet"
-    }
+    "agents": { "hatch3r-lint-fixer": "sonnet" }
   }
 }
 ```
 
-## Model Selection
-
-hatch3r lets you set preferred AI models per agent. Configure via `hatch.json` (global default and per-agent overrides), canonical agent frontmatter (`model: opus` in `.agents/agents/*.md`), or `.hatch3r/agents/{id}.customize.yaml`. Resolution order: customization file > manifest per-agent > agent frontmatter > manifest default. If you omit `models`, each tool uses its own default.
-
-See [docs/model-selection.md](docs/model-selection.md) for the full guide, aliases, and platform support.
-
 ## Sub-Agentic Architecture
 
-hatch3r includes a proven sub-agentic delegation system:
-
-- **Four-phase pipeline** -- Research → Implement → Review Loop (reviewer + fixer, max 3 iterations) → Final Quality (testing + security)
+- **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 in the review loop
+- **Fixer agent** -- Takes reviewer findings and implements targeted fixes
 - **Issue workflow skill** -- 8-step structured workflow with parallel sub-agent delegation for epics
-- **Board pickup** -- Dependency-aware auto-pick with collision detection and sub-agent orchestration
 - **Tooling hierarchy** -- Project docs > Codebase search > Library docs (Context7) > Web research
 
-## Documentation Structure
-
-hatch3r projects use a `docs/` folder with three core subdirectories. The docs-writer agent reads source code and maintains these docs automatically, keeping specs, decisions, and processes in sync with implementation.
-
-```
-docs/
-  specs/        Modular specifications with stable IDs
-  adr/          Architecture Decision Records
-  process/      Process documentation
-```
+## Content Profiles
 
-### `docs/specs/` -- Specifications
+During `hatch3r init`, you choose a content profile:
 
-Modular spec files that define what the system does. Each spec covers one logical domain (data model, event model, auth, etc.) and uses stable IDs for cross-referencing.
+| 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 |
 
-| File | Purpose |
-|------|---------|
-| `00_glossary.md` | Term definitions, stable ID prefixes, TOC for all specs |
-| `01_core-engine.md` | Core engine behavior, invariants, acceptance criteria |
-| `02_event-model.md` | Event schemas, lifecycle, validation rules |
-| `03_quality-engineering.md` | Performance budgets, testing pyramid, coverage targets |
-
-Conventions:
-- Every spec starts with a **Purpose** section and ends with **Owner / Reviewers / Last updated**.
-- Use stable IDs from the glossary (e.g., `INV-001`, `EVT_USER_CREATED`) so agents and humans can reference specific requirements across docs, issues, and code.
-- Feature matrices, invariants, and schemas use tables. Acceptance criteria use checklists.
-
-### `docs/adr/` -- Architecture Decision Records
-
-Numbered records that capture significant architectural decisions, their context, and consequences.
-
-| File | Purpose |
-|------|---------|
-| `0001_template.md` | ADR template with required sections |
-| `0002_adapter-pattern.md` | Example: why the project uses an adapter pattern |
-
-Each ADR includes: Status, Date, Decision Makers, Context, Decision, Alternatives Considered (with pros/cons table), Consequences, Compliance checklist, and Related links. New ADRs use the next available number and are saved as `XXXX_short-title.md`. Superseded ADRs are updated to reference their replacement.
-
-### `docs/process/` -- Process Documentation
-
-Guides for recurring workflows -- how the team (human or agent) ships, reviews, and maintains the project.
-
-Examples: branching strategy, release process, on-call runbook, code review checklist, agent delegation guidelines.
-
-### Relationship to the GSD Framework
-
-The [GSD (Get Shit Done)](https://github.com/gsd-build/get-shit-done) framework is a spec-driven development system for AI coding assistants. hatch3r shares GSD's conviction that structured documentation prevents context degradation, but the two projects organize that documentation differently.
-
-**Shared principles:**
-
-- Documentation is the primary context source for AI agents, not just a reference for humans.
-- Specifications are modular and scoped to single domains rather than monolithic.
-- State and decisions are captured in version-controlled markdown, not ephemeral chat.
-- Stable identifiers enable reliable cross-referencing across docs, code, and issues.
-
-**Structural differences:**
-
-| Concern | GSD | hatch3r |
-|---------|-----|---------|
-| Project state | `STATE.md` (single file, session memory) | `docs/specs/` (distributed across domain specs) |
-| Requirements | `REQUIREMENTS.md` (flat, phase-tagged) | `docs/specs/*.md` (modular, per-domain with stable IDs) |
-| Architectural decisions | Inline in `STATE.md` or plans | `docs/adr/` (dedicated, numbered, templated) |
-| Project vision | `PROJECT.md` | `docs/specs/00_glossary.md` + project README |
-| Process docs | Encoded in GSD commands and agents | `docs/process/` (explicit, human-readable guides) |
-| Planning artifacts | `.planning/` (research, plans, summaries) | GitHub Issues + board commands |
-| Scope | Single-project, single-runtime | Multi-project, multi-editor via adapters |
-
-GSD optimizes for a linear milestone-driven workflow with a single AI runtime. hatch3r's `docs/` structure is editor-agnostic and designed to be consumed by any agent system -- Cursor, Copilot, Claude Code, OpenCode, or custom tooling. The explicit `docs/adr/` directory reflects hatch3r's emphasis on long-lived, multi-contributor projects where architectural decisions need formal traceability rather than inline state tracking.
-
-## Presets
-
-hatch3r currently ships with the `default` preset which includes everything. Additional preset packs (web-app, api-service, cli-tool, monorepo, legacy, security) are planned for future releases.
+Content is tagged with workflow, context, and domain tags. After init, use `hatch3r config` to add or remove individual content items.
 
 ## Customization
 
-hatch3r uses a naming convention to separate managed from custom files:
+hatch3r separates managed from custom files:
 
-- `hatch3r-*` files are managed by hatch3r
+- `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 14 adapters: Cursor, Claude, Copilot, Cline, Codex, Gemini, Windsurf, Amp, OpenCode, Aider, Kiro, Goose, Zed, Amazon Q.
 
-**All hatch3r-generated markdown files** (rules, agents, skills, commands, bridge files, shared instruction files like `AGENTS.md`, `CLAUDE.md`, `.windsurfrules`) use managed blocks. Bridge files are emitted by 11 adapters: Cursor, Claude, Copilot, Cline, Codex, Gemini, Windsurf, Amp, OpenCode, Aider, Kiro. Only the content between `<!-- HATCH3R:BEGIN -->` and `<!-- HATCH3R:END -->` is updated on `hatch3r sync` or `hatch3r update`. Content you add outside these markers is preserved. Config files (JSON, TOML, YAML) are fully regenerated.
-
-```
-.cursor/rules/
-  hatch3r-code-standards.mdc     # Managed — add custom content outside the block
-  my-project-conventions.mdc     # Custom — never touched
-```
-
-Example: add your own sections to any hatch3r file:
+## Model Selection
 
-```markdown
-<!-- HATCH3R:BEGIN -->
-...managed content (updated on sync/update)...
-<!-- HATCH3R:END -->
+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.
 
-## My Custom Section
-...never overwritten...
-```
+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 in your Cursor settings for instant access to all rules, skills, agents, and commands without running `init`.
-
-## Community Packs
-
-Community pack support is coming soon.
+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 in the [Docusaurus docs site](docs-site/) (`cd docs-site && npm start`).
+Full documentation is available at [docs.hatch3r.com](https://docs.hatch3r.com).
 
-- [MCP Setup](docs/mcp-setup.md) — Connecting MCP servers and managing secrets
-- [Adapter Capability Matrix](docs/adapter-capability-matrix.md) — Per-tool support and output paths
-- [Agent Teams](docs/agent-teams.md) — Multi-agent team coordination and delegation patterns
-- [Model Selection](docs/model-selection.md) — Configuring AI models per agent
-- [Agentic Process](docs/agentic-process.md) — Visual diagrams of init flow, board workflow, and agent orchestration
-- [Troubleshooting](docs/troubleshooting.md) — Common issues and solutions
-- [Changelog](CHANGELOG.md) — Release history
+- [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
 

package/agents/hatch3r-a11y-auditor.md

@@ -2,6 +2,7 @@
 id: hatch3r-a11y-auditor
 description: Accessibility specialist who audits for WCAG AA compliance. Use when auditing accessibility, reviewing UI components, or fixing a11y issues.
 model: standard
+tags: [review, a11y]
 ---
 You are an accessibility specialist for the project.
 
@@ -38,12 +39,14 @@ Browser verification provides ground-truth confirmation that cannot be achieved
 
 ## Standards to Enforce
 
+Follow the full accessibility standards defined in `.agents/rules/hatch3r-accessibility-standards.md` (WCAG 2.2 AA compliance, keyboard navigation, focus management, color/contrast, screen reader support, ARIA patterns, motion, forms). Summary of key thresholds:
+
 | Requirement         | Standard | Details                                                          |
 | ------------------- | -------- | ---------------------------------------------------------------- |
-| Reduced motion      | WCAG 2.1 | All animations respect `prefers-reduced-motion` and user setting |
-| Color contrast      | WCAG AA  | Text contrast ratio ≥ 4.5:1                                      |
-| Keyboard navigation | WCAG 2.1 | All interactive elements focusable with visible focus indicator  |
-| Screen reader       | WCAG 2.1 | Dynamic state announced via `aria-live` regions                  |
+| Reduced motion      | WCAG 2.2 | All animations respect `prefers-reduced-motion` and user setting |
+| Color contrast      | WCAG AA  | Text contrast ratio >= 4.5:1, non-text >= 3:1                   |
+| Keyboard navigation | WCAG 2.2 | All interactive elements focusable with visible focus indicator  |
+| Screen reader       | WCAG 2.2 | Dynamic state announced via `aria-live` regions                  |
 | High contrast mode  | Custom   | User-configurable high contrast theme supported                  |
 
 ## Commands

package/agents/hatch3r-architect.md

@@ -2,6 +2,7 @@
 id: hatch3r-architect
 description: System architect who designs architecture, creates ADRs, analyzes dependencies, designs APIs and database schemas, and evaluates architectural trade-offs. Use when making architectural decisions, designing new systems, or evaluating design trade-offs.
 model: standard
+tags: [planning]
 ---
 You are a senior system architect for the project.
 

package/agents/hatch3r-ci-watcher.md

@@ -2,6 +2,7 @@
 id: hatch3r-ci-watcher
 description: CI/CD specialist who monitors CI pipeline runs, diagnoses failures, and suggests fixes. Use when CI fails, when waiting for CI results, or when investigating flaky tests.
 model: fast
+tags: [devops]
 ---
 You are a CI/CD specialist for the project.
 

package/agents/hatch3r-context-rules.md

@@ -2,6 +2,7 @@
 id: hatch3r-context-rules
 description: Context-aware rules engine that applies coding standards based on file type, location, and project conventions. Use when enforcing project rules on save or reviewing files against established patterns.
 model: fast
+tags: [core, maintenance]
 ---
 You are a context-aware rules engine for the project.