hatch3r 1.0.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 11 agents, 22 skills, 18 rules, 25 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,60 +14,44 @@ Requires Node.js 22+.
 npx hatch3r init
 ```
 
-That's it. hatch3r detects your repo, asks which tools you use, and generates everything. 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
 
 | Category | Count | Highlights |
 |----------|-------|-----------|
-| **Agents** | 11 | Code reviewer, test writer, security auditor, implementer (sub-agentic), researcher, and more |
-| **Skills** | 22 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, recipes, customization, and more |
-| **Rules** | 18 | Code standards, error handling, testing, API design, observability, theming, i18n, security patterns, agent orchestration, and more |
-| **Commands** | 25 | Board init, board fill, board pickup, board refresh, planning (feature, bug, refactor), healthcheck, security-audit, context-health, cost-tracking, customization, and more |
-| **MCP Servers** | 5 | GitHub, Context7, Filesystem, Playwright, Brave Search |
-
-## 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`, `.cursorrules`
-
-### 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.
+| **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** | 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 (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
 
 ```
-/.agents/              <- Canonical source (tool-agnostic)
+.agents/              <- Canonical source (tool-agnostic)
   ├── agents/
   ├── skills/
   ├── rules/
@@ -83,63 +67,30 @@ CLAUDE.md              <- Generated (Claude 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)
+.worktreeinclude       <- Generated (worktree isolation)
 ```
 
-hatch3r keeps one source of truth in `/.agents/` and generates native configuration for each tool.
+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, asks which coding tools you use (Cursor, Copilot, Claude Code, OpenCode, Windsurf, Amp, Codex CLI, Gemini CLI, Cline), and generates all agents, skills, rules, commands, and MCP configuration.
-
-> **Next steps after init:** For a new project, run `project-spec`. For an existing codebase, run `codebase-map`. To plan a single feature, run `feature-plan`. To investigate a complex bug, run `bug-plan`. To plan a refactoring effort, run `refactor-plan`. Or skip straight to creating a `todo.md` and running `board-fill`.
-
-### For new projects (greenfield)
-
-If you're starting from scratch, use `project-spec` to generate documentation from your vision, then `roadmap` to create a phased plan:
-
-1. Run `project-spec` with your project idea — produces `docs/specs/`, `docs/adr/`, and `todo.md`
-2. Run `roadmap` to refine the plan into dependency-ordered epics
-3. Continue with 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 `codebase-map` to analyze what's already there:
-
-1. Run `codebase-map` — spawns analyzers to discover modules, conventions, and tech debt
-2. Run `roadmap` to plan improvements from the analysis
-3. Continue with board-fill (step 4 below) to create GitHub issues
-
-### 2. Set up the board
-
-Run the `board-init` command to create or connect a GitHub Projects V2 board. You do not need to manually create a GitHub Project -- 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 `board-fill` to parse `todo.md` and turn items into GitHub issues. 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. Pick up work
-
-Run `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.
-
-### 6. Review cycle
-
-The reviewer, test-writer, and security-auditor agents review the work. Address feedback, push fixes, and re-request review.
-
-### 7. Release
-
-Run the `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
 
@@ -147,143 +98,44 @@ Run the `release` command to cut a versioned release. It classifies merged PRs t
 
 ```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 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):
-
-**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.
-
-**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.
-
-**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, delegates to the appropriate implementation skill (or spawns parallel sub-agents for epics), runs quality checks, and creates a pull request with label transitions and Projects V2 status sync.
-
-**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.
-
-**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.
-
-**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 board-pickup, performs deep static analysis and produces a findings epic with actionable sub-issues.
-
-**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.
-
-**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.
-
-**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.
-
-**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.
+These commands are invoked inside your coding tool (e.g., as Cursor commands).
 
-**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/`.
+**Board management:** `board-init`, `board-fill`, `board-groom`, `board-pickup`, `board-refresh`, `board-shared`
 
-**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 `board-fill` format, ready for immediate board population.
+**Planning:** `project-spec`, `codebase-map`, `roadmap`, `feature-plan`, `bug-plan`, `refactor-plan`, `migration-plan`, `test-plan`, `api-spec`
 
-**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 `board-fill`. Optionally chains directly into `board-fill` to create GitHub issues.
+**Workflow:** `workflow`, `quick-change`, `revision`, `debug`, `onboard`, `benchmark`, `hooks`, `learn`, `recipe`
 
-**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 `board-fill`. Use when reproducing is non-trivial or multiple modules might be involved.
+**Operations:** `healthcheck`, `security-audit`, `dep-audit`, `release`, `context-health`, `cost-tracking`
 
-**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.
+**Customization:** `agent-customize`, `command-customize`, `skill-customize`, `rule-customize`
 
-**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.
+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.
 
-**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.
+## MCP Configuration
 
-**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 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.).
 
-**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.
+- **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 .`
 
-**cost-tracking** -- Track token usage and estimated costs across agent workflows. Provides per-command and per-agent cost breakdowns with budget alerts.
+See [MCP Setup](https://docs.hatch3r.com/docs/guides/mcp-setup) for full setup, per-server details, and PAT scope guidance.
 
-**recipe** -- Create and manage composable workflow recipes. Recipes are reusable workflow templates that chain multiple commands and skills into repeatable sequences.
+## Platform Agentic Workflows
 
-**agent-customize** -- Configure per-agent customization via `.customize.yaml` files. Allows project-specific agent behavior overrides without modifying managed agent definitions.
-
-**command-customize** -- Configure per-command customization via `.customize.yaml` files. Allows project-specific command behavior overrides without modifying managed command definitions.
-
-**skill-customize** -- Configure per-skill customization via `.customize.yaml` files. Allows project-specific skill behavior overrides without modifying managed skill definitions.
-
-**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. |
-| **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. |
-| **dependency-auditor** | Supply chain security analyst who scans for CVEs, evaluates upgrade paths, assesses bundle size impact, and verifies lockfile integrity. |
-| **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. |
-| **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). |
-| **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. |
-| **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. |
-| **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. |
-| **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 |
-|------|-------------|
-| **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. |
-| **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. |
-| **dependency-management** | Lockfile hygiene, new-dependency justification, CVE patching timelines (48h for critical), and bundle size budgets. |
-| **error-handling** | Structured error hierarchy, typed error codes, exponential backoff for retries, and correlation IDs for tracing. |
-| **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. |
-| **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 for GitHub-based workflows:
-
-- **board-init** -- Create or connect a GitHub Projects V2 board with status fields, label taxonomy, and optional migration
-- **board-fill** -- Parse `todo.md`, create epics/issues, deduplicate, analyze dependencies, set implementation order
-- **board-pickup** -- Auto-pick the next best issue, check collisions, delegate to sub-agents, create PRs
-- **board-refresh** -- Regenerate the board overview dashboard with current state, health metrics, and model recommendations
-- **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
 {
@@ -295,142 +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)
 - **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
-- **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
-```
-
-### `docs/specs/` -- Specifications
-
-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.
-
-| 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 |
+## Content Profiles
 
-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.
+During `hatch3r init`, you choose a content profile:
 
-### `docs/adr/` -- Architecture Decision Records
+| 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 |
 
-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. 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
-  hatch3r-error-handling.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
 
-- [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
-- [Model Selection](docs/model-selection.md) — Configuring AI models per agent
-- [Troubleshooting](docs/troubleshooting.md) — Common issues and solutions
+Full documentation is available at [docs.hatch3r.com](https://docs.hatch3r.com).
+
+- [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

@@ -1,7 +1,8 @@
 ---
 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: sonnet
+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
@@ -53,7 +56,22 @@ Browser verification provides ground-truth confirmation that cannot be achieved
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
+- **GitHub:** `gh` CLI
+- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
+- **GitLab:** `glab` CLI
+
+## Context7 MCP Usage
+
+- Use `resolve-library-id` then `query-docs` to look up correct ARIA patterns and component accessibility APIs for the project's UI framework (e.g., React ARIA, Radix UI, Headless UI, Vuetify a11y props).
+- Verify that components use the correct accessibility attributes by checking the framework's current documentation rather than relying on potentially outdated training data.
+- Look up accessibility testing library APIs (axe-core, jest-axe, Playwright accessibility snapshots) for audit automation.
+
+## Web Research Usage
+
+- Use web search for current WCAG success criteria interpretation and techniques when auditing specific patterns (e.g., combobox, carousel, data table, drag-and-drop).
+- Use web search for WAI-ARIA Authoring Practices and design pattern guidance for complex interactive components.
+- Use web search for screen reader compatibility notes across assistive technologies (NVDA, JAWS, VoiceOver) when findings involve cross-AT support.
 
 ## Sub-Agent Delegation
 

package/agents/hatch3r-architect.md

@@ -1,6 +1,8 @@
 ---
 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.
 
@@ -35,6 +37,8 @@ You are a senior system architect for the project.
 - Design data models with migration paths from the current schema.
 - Specify API contracts with request/response shapes, error codes, and pagination.
 - Address cross-cutting concerns: auth, logging, error handling, caching, rate limiting.
+- Use Context7 MCP (`resolve-library-id` then `query-docs`) to verify API capabilities and constraints of frameworks, databases, and infrastructure libraries involved in the design.
+- Use web research for architecture pattern comparisons, scalability benchmarks, and technology evaluation when making trade-off decisions.
 
 ### 3. Evaluate Trade-Offs
 
@@ -80,7 +84,22 @@ For decisions that warrant long-term documentation:
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
+- **GitHub:** `gh` CLI
+- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
+- **GitLab:** `glab` CLI
+
+## Context7 MCP Usage
+
+- Use `resolve-library-id` then `query-docs` to look up current API surfaces for frameworks, ORMs, message brokers, and infrastructure libraries involved in architectural decisions.
+- Verify API contract assumptions (e.g., database driver connection pooling, cache client TTL semantics, queue library acknowledgement modes) before recommending architecture.
+- Prefer Context7 over guessing API capabilities or relying on potentially outdated training data when evaluating technology trade-offs.
+
+## Web Research Usage
+
+- Use web search for architecture pattern references, scalability case studies, and performance benchmarks when evaluating trade-offs between alternatives.
+- Use web search for current best practices and known pitfalls for specific technology choices (e.g., Redis vs Memcached for session storage, WebSocket vs SSE for real-time).
+- Use web search for cloud service limits, pricing models, and SLA guarantees when infrastructure decisions affect the architecture.
 
 ## Output Format