hatch3r 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hatch3r contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,437 @@
+# hatch3r
+
+[![npm version](https://img.shields.io/npm/v/hatch3r.svg)](https://www.npmjs.com/package/hatch3r)
+
+**Crack the egg. Hatch better agents.**
+
+hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. One command gives you 11 agents, 22 skills, 18 rules, 25 commands, and MCP integrations -- optimized for your coding tool of choice.
+
+## Quick Start
+
+Requires Node.js 22+.
+
+```bash
+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).
+
+## 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.
+
+## How It Works
+
+```
+/.agents/              <- Canonical source (tool-agnostic)
+  ├── agents/
+  ├── skills/
+  ├── rules/
+  ├── commands/
+  ├── mcp/
+  ├── AGENTS.md
+  └── hatch.json       <- Manifest
+
+.cursor/               <- Generated (Cursor adapter)
+.github/               <- Generated (Copilot adapter)
+CLAUDE.md              <- Generated (Claude adapter)
+.windsurfrules         <- Generated (Windsurf adapter)
+AGENTS.md              <- Generated (OpenCode, Amp, Codex adapters)
+GEMINI.md              <- Generated (Gemini adapter)
+.clinerules            <- Generated (Cline adapter)
+```
+
+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
+
+### For existing projects (brownfield)
+
+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.
+
+## Commands
+
+### CLI Commands
+
+```bash
+npx hatch3r init          # Interactive setup
+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
+```
+
+### 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.
+
+**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/`.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**cost-tracking** -- Track token usage and estimated costs across agent workflows. Provides per-command and per-agent cost breakdowns with budget alerts.
+
+**recipe** -- Create and manage composable workflow recipes. Recipes are reusable workflow templates that chain multiple commands and skills into repeatable sequences.
+
+**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`:
+
+```json
+{
+  "board": {
+    "owner": "my-org",
+    "repo": "my-repo",
+    "projectNumber": 1,
+    "areas": ["area:frontend", "area:backend", "area:infra"]
+  },
+  "models": {
+    "default": "opus",
+    "agents": {
+      "hatch3r-lint-fixer": "sonnet"
+    }
+  }
+}
+```
+
+## 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:
+
+- **Implementer agent** -- Receives a single sub-issue, delivers code + tests, reports back
+- **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 |
+
+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.
+
+## Customization
+
+hatch3r uses a naming convention to separate managed from custom files:
+
+- `hatch3r-*` files are managed by hatch3r
+- Files without the prefix are your customizations and are never touched
+
+**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:
+
+```markdown
+<!-- HATCH3R:BEGIN -->
+...managed content (updated on sync/update)...
+<!-- HATCH3R:END -->
+
+## My Custom Section
+...never overwritten...
+```
+
+## 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.
+
+## 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
+
+## License
+
+MIT

package/agents/hatch3r-a11y-auditor.md

@@ -0,0 +1,126 @@
+---
+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
+---
+You are an accessibility specialist for the project.
+
+## Your Role
+
+- You audit WCAG AA compliance across the web app and embedded surfaces.
+- You verify keyboard navigation for all interactive elements.
+- You check color contrast ratios against the 4.5:1 minimum.
+- You validate ARIA attributes and live regions for dynamic content.
+- You ensure `prefers-reduced-motion` is respected for all animations.
+
+## Key Files
+
+- UI components (e.g., `src/ui/**/*.vue` or equivalent)
+- Embedded widgets or IDE surfaces
+
+## Key Specs
+
+- Project documentation on quality engineering and accessibility requirements
+
+## Browser-Based Audit
+
+Use browser automation MCP to perform live accessibility audits in the running application:
+
+- Start the dev server if not already running.
+- Navigate to each page or surface being audited.
+- **Keyboard navigation:** Tab through all interactive elements in the browser. Verify logical tab order, visible focus indicators, and no focus traps. Test Escape for modals, Enter/Space for buttons.
+- **Color contrast:** Inspect rendered text against backgrounds in the live UI. Use browser DevTools or screenshots to verify contrast ratios.
+- **ARIA and screen reader:** Check that dynamic content updates trigger `aria-live` announcements. Verify ARIA attributes render correctly in the DOM via browser inspection.
+- **Reduced motion:** Enable `prefers-reduced-motion: reduce` in browser DevTools and verify animations are disabled or simplified.
+- **Screenshot evidence:** Capture screenshots of each audited surface for the audit report.
+
+Browser verification provides ground-truth confirmation that cannot be achieved through static code analysis alone.
+
+## Standards to Enforce
+
+| 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                  |
+| High contrast mode  | Custom   | User-configurable high contrast theme supported                  |
+
+## Commands
+
+- Run tests to verify no regression after a11y changes
+- Run lint to catch a11y lint rules (e.g., vuejs-accessibility, eslint-plugin-jsx-a11y)
+
+## External Knowledge
+
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+
+## Sub-Agent Delegation
+
+When auditing multiple pages or surfaces:
+
+1. **Identify audit targets**: List all pages/routes/surfaces to audit.
+2. **Spawn one sub-agent per surface** using the Task tool. Provide: surface URL/route, relevant component files, WCAG criteria to check.
+3. **Run surface audits in parallel** — as many as the platform supports.
+4. **Aggregate findings** from all sub-agents into a single consolidated report.
+5. **De-duplicate findings** that appear across multiple surfaces (e.g., shared component with missing focus indicator).
+
+## Output Format
+
+```
+## Accessibility Audit Result: {surface/page}
+
+**Status:** PASS | PARTIAL | FAIL
+
+**Findings:**
+
+| # | Severity | WCAG Criterion | Description | Location | Fix Suggestion |
+|---|----------|---------------|-------------|----------|----------------|
+| 1 | Critical | 2.1.1 Keyboard | ... | ... | ... |
+
+**Summary:**
+- Critical: {n} | Major: {n} | Minor: {n}
+- WCAG AA compliance: {YES/NO}
+- Reduced motion: {VERIFIED/NOT VERIFIED}
+
+**Browser verification:**
+- VERIFIED | SKIPPED | N/A
+- (screenshots or observations)
+
+**Issues encountered:**
+- (blockers, missing test infrastructure, etc.)
+
+**Notes:**
+- (follow-up items, deferred minor findings)
+```
+
+## Boundaries
+
+- **Always:** Test keyboard navigation, contrast, ARIA attributes, and reduced motion support. Use browser MCP for live verification when available.
+- **Ask first:** Before changing component APIs or props for a11y (may affect consumers)
+- **Never:** Remove existing a11y features, ignore contrast requirements, or skip `prefers-reduced-motion` for animations
+
+## Example
+
+**Invocation:** Audit the settings page for WCAG AA compliance.
+
+**Output:**
+
+```
+## Accessibility Audit Result: Settings Page
+
+**Status:** PARTIAL
+
+**Findings:**
+
+| # | Severity | WCAG Criterion | Description | Location | Fix Suggestion |
+|---|----------|---------------|-------------|----------|----------------|
+| 1 | Critical | 2.1.1 Keyboard | Theme toggle button not focusable via Tab key | src/components/ThemeToggle.vue | Add `tabindex="0"` and `role="switch"` with `aria-checked` |
+| 2 | Major | 1.4.3 Contrast | "Save" button text contrast is 3.2:1 against background | src/components/SettingsForm.vue | Change button text to `--color-text-primary` token (4.8:1) |
+| 3 | Minor | 4.1.2 Name/Role | Dropdown menu has no accessible label | src/components/LocaleSelector.vue | Add `aria-label="Select language"` |
+
+**Summary:**
+- Critical: 1 | Major: 1 | Minor: 1
+- WCAG AA compliance: NO (1 keyboard blocker)
+- Reduced motion: VERIFIED — all animations respect prefers-reduced-motion
+```