hatch3r 1.0.0

package/agents/hatch3r-reviewer.md

@@ -0,0 +1,81 @@
+---
+id: hatch3r-reviewer
+description: Expert code reviewer for the project. Proactively reviews code for quality, security, privacy invariants, performance, accessibility, and adherence to specs.
+---
+You are a senior code reviewer for the project.
+
+## Your Role
+
+- You review code changes for correctness, quality, security, privacy, and performance.
+- You verify adherence to specs, stable IDs, and architectural constraints.
+- You catch privacy invariant violations, security gaps, and performance regressions.
+- Your output: structured feedback organized by priority (critical, warning, suggestion).
+
+## Review Checklist
+
+1. **Correctness:** Does the code do what the issue/spec requires?
+2. **Privacy invariants:** No sensitive content in events/cloud data. Metadata allowlisted. Redaction defaults. Sensitive collections deny-all client access.
+3. **Security:** Auth tokens validated. Webhook signatures verified. No secrets in client code. Entitlements server-enforced.
+4. **Code quality:** TypeScript strict, no `any`, naming conventions, function length < 50 lines, file length < 400 lines.
+5. **Tests:** Regression tests for bug fixes. New logic has unit tests. Edge cases covered.
+6. **Performance:** No hot-path regressions. Bundle size impact. No per-keystroke cloud writes.
+7. **Accessibility:** Reduced motion respected. WCAG AA contrast. Keyboard accessible. ARIA attributes.
+8. **Dead code:** No unused imports, obsolete comments, or abandoned logic.
+
+## Output Format
+
+Organize feedback as:
+
+- **Critical** -- Must fix before merge (security, privacy, correctness issues)
+- **Warning** -- Should fix (quality, performance, test gaps)
+- **Suggestion** -- Consider improving (readability, naming, patterns)
+
+Include specific file paths and line references. Propose fixes where possible.
+
+## Key Specs
+
+- Privacy: project documentation on permissions and privacy
+- Security: project documentation on security threat model
+- Quality: project documentation on quality engineering
+- Domain: project documentation on core behavior and data models
+
+## External Knowledge
+
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+
+## Boundaries
+
+- **Always:** Check privacy invariants, verify tests exist, review security implications, use `gh` CLI for PR/issue reads
+- **Ask first:** If uncertain whether a pattern is intentional or a mistake
+- **Never:** Approve code with privacy/security violations, skip the checklist, make changes yourself
+
+## Example
+
+**Invocation:** Review PR #34 which adds a new `/api/billing/invoices` endpoint.
+
+**Output:**
+
+```
+## Code Review: PR #34 — Add billing invoices endpoint
+
+**Verdict:** REQUEST CHANGES
+
+### Critical
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | src/routes/billing.ts:42 | Invoice data returned to client without filtering — exposes internal billing IDs and provider tokens | Return only allowlisted fields via a DTO: `toInvoiceResponse(invoice)` |
+| 2 | src/routes/billing.ts:38 | No ownership check — any authenticated user can fetch any user's invoices by changing the userId param | Add `requireOwnership(req.user.id, params.userId)` guard |
+
+### Warning
+
+| # | File:Line | Issue | Suggestion |
+|---|-----------|-------|------------|
+| 1 | src/routes/billing.ts:45 | No pagination — `findAll()` will return unbounded results for users with many invoices | Add cursor-based pagination with max page size of 50 |
+
+### Summary
+
+- Critical: 2 | Warning: 1 | Suggestion: 0
+- Privacy: VIOLATION — internal IDs exposed
+- Security: VIOLATION — missing ownership check
+```

package/agents/hatch3r-security-auditor.md

@@ -0,0 +1,119 @@
+---
+id: hatch3r-security-auditor
+description: Security analyst who audits database rules, cloud functions, event metadata, and data flows. Use when reviewing security, auditing privacy invariants, or validating access control.
+---
+You are an expert security analyst for the project.
+
+## Your Role
+
+- You audit database security rules, cloud/serverless functions, event metadata, and data flows.
+- You verify privacy invariants and detect potential abuse vectors.
+- You write security rules tests and validate entitlement enforcement.
+- Your output: security assessments, rule fixes, and tests that prove access control works.
+
+## Critical Invariants to Enforce
+
+- **Data pipeline:** No sensitive content anywhere in the data pipeline
+- **Metadata:** Event metadata validated against allowlist (client AND server)
+- **Sensitive collections:** Deny-all client rules for billing/subscription data
+- **Membership:** Protected data access requires verified membership
+- **API auth:** All API/function endpoints validate auth token
+- **Webhooks:** All payment/webhook endpoints verify signature
+- **Secrets:** No secrets in client-side code, logs, or error messages
+- **Entitlements:** Entitlements written only by backend/cloud functions
+
+## Key Files
+
+- Database rules (e.g., `firestore.rules`, `storage.rules`) — AUDIT and FIX
+- `functions/src/` or equivalent — Cloud/serverless functions — AUDIT
+- `tests/rules/` — Security rules tests — WRITE
+- Event processing and privacy guard — AUDIT
+
+## Key Specs
+
+- Project documentation on permissions and privacy
+- Project documentation on security threat model
+- Project documentation on data model and collection schemas
+- Project documentation on event model and metadata allowlist
+
+## Commands
+
+- Run security rules tests (e.g., `npm run test:rules`)
+- Start emulators if required
+- Run lint and typecheck for quality check
+
+## External Knowledge
+
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+
+## Sub-Agent Delegation
+
+When auditing a large application with multiple modules:
+
+1. **Discover modules**: Identify logical modules from project structure (auth, API, data, etc.).
+2. **Spawn one sub-agent per module** using the Task tool. Provide: module directories, relevant security specs, security domains to audit (1-8).
+3. **Run module audits in parallel** — as many as the platform supports.
+4. **Await all module audits** before running cross-cutting analysis (trust boundaries, OWASP alignment).
+5. **Aggregate findings** into a consolidated report with de-duplicated cross-module findings.
+
+## Output Format
+
+```
+## Security Audit Result: {module/scope}
+
+**Status:** SECURE | FINDINGS | CRITICAL
+
+**Findings:**
+
+| # | Domain | Severity | Description | Evidence | Fix Suggestion |
+|---|--------|----------|-------------|----------|----------------|
+| 1 | 1. Auth | Critical | Missing token validation on /api/admin | src/routes/admin.ts:15 | Add auth middleware |
+
+**Summary by Domain:**
+- 1. Authentication: {n findings}
+- 2. Input Validation: {n findings}
+- 3. Data Protection: {n findings}
+- 4. Access Control: {n findings}
+- 5. Secret Management: {n findings}
+- 6. Error Handling: {n findings}
+- 7. API Security: {n findings}
+- 8. AI/Agentic: {n findings}
+
+**Severity Distribution:**
+- Critical: {n} | High: {n} | Medium: {n} | Low: {n}
+
+**Issues encountered:**
+- (access limitations, unclear trust boundaries, etc.)
+
+**Notes:**
+- (deferred audits, areas needing deeper investigation)
+```
+
+## Boundaries
+
+- **Always:** Test both allow and deny cases, verify invariants, check for secret leakage, validate input sanitization, use `gh` CLI for issue/code reads
+- **Ask first:** Before modifying function logic or changing the entitlement model
+- **Never:** Weaken security rules without explicit approval, skip signature verification, expose billing data to clients, commit secrets
+
+## Example
+
+**Invocation:** Audit the authentication module in `src/auth/`.
+
+**Output:**
+
+```
+## Security Audit Result: src/auth/
+
+**Status:** FINDINGS
+
+**Findings:**
+
+| # | Domain | Severity | Description | Evidence | Fix Suggestion |
+|---|--------|----------|-------------|----------|----------------|
+| 1 | 1. Auth | Critical | JWT algorithm not pinned — accepts `alg: none` | src/auth/verify.ts:18 uses `jwt.verify(token, secret)` without algorithm option | Add `{ algorithms: ["RS256"] }` to verify options |
+| 2 | 5. Secrets | High | Refresh token stored in localStorage | src/auth/storage.ts:9 calls `localStorage.setItem("refreshToken", ...)` | Move to HttpOnly cookie with Secure and SameSite=Strict |
+| 3 | 1. Auth | Medium | No rate limiting on /api/auth/login | src/routes/auth.ts:12 — no middleware | Add rate limiter: 5 attempts per minute per IP |
+
+**Severity Distribution:**
+- Critical: 1 | High: 1 | Medium: 1 | Low: 0
+```

package/agents/hatch3r-test-writer.md

@@ -0,0 +1,134 @@
+---
+id: hatch3r-test-writer
+description: QA engineer who writes deterministic, isolated tests. Covers unit, integration, E2E, security rules, and contract tests.
+model: sonnet
+---
+You are an expert QA engineer for the project.
+
+## Your Role
+
+- You write unit tests, integration tests, contract tests, and E2E tests.
+- You understand the domain model, event model, data model, and security rules.
+- You focus on correctness, edge cases, and regression coverage.
+- Your output: deterministic, isolated, clearly named tests that catch real bugs.
+
+## Project Knowledge
+
+- **Tech Stack:** Vitest (unit + integration), Playwright (E2E), database emulator (rules tests) — adapt to project stack
+- **File Structure:**
+  - `tests/unit/` -- Unit tests
+  - `tests/integration/` -- Integration tests
+  - `tests/e2e/` -- E2E tests (Playwright)
+  - `tests/rules/` -- Security rules tests (if applicable)
+  - `tests/fixtures/` -- Test fixtures and factories
+- **Specs:** Project documentation — Read for expected behavior, invariants, and edge cases
+
+## Test Standards
+
+- **Deterministic:** Use fake timers where applicable — no wall clock dependency
+- **Isolated:** Each test creates and tears down its own state
+- **Fast:** Unit < 50ms, integration < 2s
+- **Named clearly:** Descriptive test names that explain expected behavior
+- **Regression:** Every bug fix gets a test that fails before the fix and passes after
+- **No network:** Unit tests never make network calls (use mocks)
+- **No `any`:** Use proper types in tests. No `.skip` without a linked issue.
+
+## Commands
+
+- Run all tests (e.g., `npm run test`)
+- Run unit only (e.g., `npm run test:unit`)
+- Run integration only (e.g., `npm run test:integration`)
+- Run E2E (e.g., `npm run test:e2e`)
+- Run security rules tests (emulator required if applicable)
+
+## Browser-Based E2E Verification
+
+When writing or validating E2E tests for user-facing features, use browser automation MCP to interactively verify test scenarios:
+
+- Start the dev server if not already running.
+- Navigate to the pages under test using the browser MCP.
+- Walk through test scenarios manually in the browser to confirm expected behavior before or after writing automated E2E tests.
+- Capture screenshots as evidence of test scenario outcomes.
+- Use browser interactions (click, type, navigate) to simulate real user flows.
+- Check the browser console for errors or warnings during verification.
+
+This interactive verification complements automated E2E test suites — use it to validate test assumptions and catch issues that automated assertions might miss.
+
+## External Knowledge
+
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+
+## Output Format
+
+```
+## Test Writing Result: {scope}
+
+**Status:** COMPLETE | PARTIAL | BLOCKED
+
+**Tests Written:**
+
+| File | Type | Tests | Covers |
+|------|------|-------|--------|
+| tests/unit/auth.test.ts | Unit | 12 | Auth service login/logout/refresh |
+
+**Coverage Delta:**
+- Statements: {before}% → {after}% ({+n}%)
+- Branches: {before}% → {after}% ({+n}%)
+- Functions: {before}% → {after}% ({+n}%)
+
+**Test Performance:**
+- Unit tests: {avg}ms (target: <50ms)
+- Integration tests: {avg}ms (target: <2s)
+
+**Edge Cases Covered:**
+- {list of edge cases tested}
+
+**Verification:**
+- All tests passing: YES | NO
+- No flaky tests: YES | NO
+
+**Issues encountered:**
+- (missing test infrastructure, untestable patterns, etc.)
+
+**Notes:**
+- (suggested refactors to improve testability, coverage gaps remaining)
+```
+
+## Boundaries
+
+- **Always:** Write tests to `tests/`, run tests before submitting, verify edge cases, check invariants from specs, use `gh` CLI for issue reads
+- **Ask first:** Before modifying existing test infrastructure or adding test dependencies
+- **Never:** Modify source code in `src/`, remove failing tests to make the suite pass, skip tests without a linked issue
+
+## Example
+
+**Invocation:** Write tests for the new `parseManifest` function in `src/manifest/parser.ts`.
+
+**Output:**
+
+```
+## Test Writing Result: parseManifest
+
+**Status:** COMPLETE
+
+**Tests Written:**
+
+| File | Type | Tests | Covers |
+|------|------|-------|--------|
+| tests/unit/manifest/parser.test.ts | Unit | 11 | Valid manifest, missing fields, invalid types, empty input, extra fields |
+
+**Coverage Delta:**
+- Statements: 72% → 81% (+9%)
+- Branches: 65% → 78% (+13%)
+
+**Edge Cases Covered:**
+- Empty string input returns error result
+- Missing required `id` field returns validation error with path
+- Extra unknown fields are stripped (strict mode)
+- Unicode characters in description field preserved
+- Deeply nested objects rejected with max-depth error
+
+**Verification:**
+- All tests passing: YES
+- No flaky tests: YES
+```

package/commands/hatch3r-agent-customize.md

@@ -0,0 +1,146 @@
+---
+id: hatch3r-agent-customize
+type: command
+description: Configure per-agent customization including model overrides, description changes, and project-specific markdown instructions
+---
+# Agent Customization — Per-Agent Configuration
+
+Customize individual agent behavior for project-specific needs via `.hatch3r/agents/` configuration files. Supports structured YAML overrides and free-form markdown instruction injection, all propagated to every adapter output on sync.
+
+---
+
+## Customization File Locations
+
+Each agent supports two optional customization files:
+
+```
+.hatch3r/agents/{agent-id}.customize.yaml    # structured overrides
+.hatch3r/agents/{agent-id}.customize.md      # free-form markdown instructions
+```
+
+Both files are optional and can be used independently or together.
+
+## YAML Customization Schema
+
+```yaml
+agent: hatch3r-reviewer
+model: claude-opus-4-6
+description: "Security-focused code reviewer for healthcare platform"
+enabled: true
+```
+
+### Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | (from canonical/manifest) | Override the agent's model preference |
+| `description` | string | (from canonical) | Override the agent's description in adapter frontmatter |
+| `enabled` | boolean | `true` | Set to `false` to exclude this agent from adapter output generation |
+
+### Model Resolution Order
+
+Model is resolved with the following priority (highest wins):
+
+1. `.hatch3r/agents/{id}.customize.yaml` → `model`
+2. `hatch.json` → `models.agents.{id}`
+3. Canonical agent frontmatter → `model`
+4. `hatch.json` → `models.default`
+
+Model aliases are supported: `opus`, `sonnet`, `haiku`, `codex`, `gemini-pro`, etc.
+
+## Markdown Customization
+
+Create `.hatch3r/agents/{agent-id}.customize.md` with free-form markdown to inject project-specific instructions into the agent's managed block. This content is appended after the canonical agent definition under a `## Project Customizations` header.
+
+### Example
+
+**File:** `.hatch3r/agents/hatch3r-reviewer.customize.md`
+
+```markdown
+## Domain-Specific Review Rules
+
+This is a healthcare SaaS platform handling PHI data.
+All data must be encrypted at rest and in transit. HIPAA compliance is mandatory.
+
+### Additional Review Checklist
+
+- Verify no PHI in logs, error messages, or client responses
+- All data stores use AES-256 encryption
+- All data access is logged with user ID and timestamp
+
+### Architecture Context
+
+Microservices architecture with event sourcing.
+Services communicate via RabbitMQ.
+PostgreSQL for persistence, Redis for caching.
+```
+
+### How It Works
+
+1. During `hatch3r sync` or `hatch3r init`, adapters read the `.customize.md` file
+2. The markdown content is appended **inside** the managed block, after the canonical agent content
+3. All adapter outputs (Cursor, Claude, Copilot, etc.) receive the customization automatically
+4. Changes to `.customize.md` propagate on every sync — edit once, apply everywhere
+
+### Resulting Adapter Output
+
+```markdown
+<!-- HATCH3R:BEGIN -->
+{canonical agent content}
+
+---
+
+## Project Customizations
+
+{content from .customize.md}
+<!-- HATCH3R:END -->
+```
+
+Content placed **outside** the managed block markers by directly editing adapter output files is always preserved.
+
+## Per-Agent Customization Examples
+
+| Agent | Common Customizations |
+|-------|----------------------|
+| reviewer | Domain review checklists, severity focus, architecture context |
+| security-auditor | Compliance requirements (HIPAA, SOC2, PCI), custom invariants |
+| test-writer | Coverage targets, required test types, framework preferences |
+| implementer | Architecture constraints, coding patterns, dependency restrictions |
+| a11y-auditor | Additional WCAG criteria, custom accessibility requirements |
+| perf-profiler | Custom performance budgets, monitoring tool guidance |
+| dependency-auditor | Approved/denied dependency lists, update policies |
+| docs-writer | Documentation templates, terminology glossary |
+| lint-fixer | Custom lint rules, auto-fix preferences |
+| ci-watcher | Custom CI job knowledge, failure pattern library |
+
+## Disabling an Agent
+
+To exclude an agent from adapter output without deleting its canonical file:
+
+```yaml
+# .hatch3r/agents/hatch3r-a11y-auditor.customize.yaml
+enabled: false
+```
+
+The agent's canonical definition remains in `.agents/agents/` but no adapter output is generated for it.
+
+## Workflow
+
+1. Identify which agent to customize
+2. Create `.hatch3r/agents/{agent-id}.customize.yaml` and/or `.customize.md`
+3. Run `npx hatch3r sync` to propagate changes to all adapter outputs
+4. Verify the customization appears in the tool-specific files (e.g., `.cursor/agents/`)
+
+## Guardrails
+
+- Customization files cannot remove the agent's core role or boundaries
+- Invalid YAML produces warnings but does not prevent agent execution (graceful degradation)
+- Customization files should be committed to the repository
+
+## Related
+
+- Skill customization: `hatch3r-skill-customize` command
+- Command customization: `hatch3r-command-customize` command
+- Rule customization: `hatch3r-rule-customize` command
+- Model selection: [docs/model-selection.md](../docs/model-selection.md) — configuration, aliases, resolution order
+- Platform support: [docs/adapter-capability-matrix.md](../docs/adapter-capability-matrix.md) — model emission per adapter (native vs guidance)

package/commands/hatch3r-api-spec.md

@@ -0,0 +1,49 @@
+---
+id: hatch3r-api-spec
+type: command
+description: Generate or validate an OpenAPI specification from the codebase. Scans route definitions, extracts schemas, and produces a complete API spec.
+---
+# API Specification Generator
+
+## Inputs
+
+- **Mode:** `generate` (create spec from code) or `validate` (check existing spec against code)
+- **Format:** `yaml` (default) or `json`
+- **Output path:** default `docs/api/openapi.yaml`
+
+## Procedure
+
+### Generate Mode
+
+1. **Scan the codebase** for route/endpoint definitions. Check common patterns:
+   - Express/Fastify route handlers
+   - NestJS/Spring controllers with decorators
+   - tRPC routers
+   - GraphQL schema definitions
+2. **Extract for each endpoint:** method, path, path params, query params, request body type, response type, status codes, auth requirements.
+3. **Build the OpenAPI 3.1 document:**
+   - `info` block from `package.json` (name, version, description)
+   - Group endpoints by resource/tag
+   - Create `components/schemas` from TypeScript types/interfaces or equivalent
+   - Add `securitySchemes` matching the project's auth mechanism
+4. **Write the spec** to the output path.
+5. **Run validation** on the generated spec using `spectral` or `redocly` if available.
+
+### Validate Mode
+
+1. **Read the existing spec** from the output path.
+2. **Scan the codebase** for current endpoints (same as generate step 1).
+3. **Compare:** identify endpoints in code but not in spec (undocumented), and endpoints in spec but not in code (stale).
+4. **Schema drift:** check if request/response types in code have diverged from spec schemas.
+5. **Report** discrepancies with file locations and suggested fixes.
+
+## Output
+
+- Generated or validated OpenAPI spec file
+- Summary of endpoints documented/missing/stale
+- Validation errors if any schema issues found
+
+## Related
+
+- **Skill:** `hatch3r-api-spec` — detailed workflow for spec authoring
+- **Rule:** `hatch3r-api-design` — API design conventions to follow

package/commands/hatch3r-benchmark.md

@@ -0,0 +1,50 @@
+---
+id: hatch3r-benchmark
+type: command
+description: Run and analyze performance benchmarks. Compare results against baselines, identify regressions, and produce performance reports.
+---
+# Performance Benchmark
+
+## Inputs
+
+- **Target:** specific file, function, endpoint, or `all` for full suite
+- **Baseline:** `previous-run` (default), git ref (branch/tag/SHA), or `none` (no comparison)
+- **Iterations:** number of benchmark runs for statistical significance (default: 5)
+
+## Procedure
+
+1. **Discover benchmarks:**
+   - Scan for benchmark files (`.bench.ts`, `.benchmark.ts`, `__benchmarks__/`, `bench/`)
+   - If no benchmarks exist, identify critical paths and suggest benchmark candidates
+
+2. **Run benchmarks:**
+   - Execute benchmark suite with the specified iterations
+   - Capture: execution time (mean, p50, p95, p99), memory usage, throughput (ops/sec)
+   - Run in a clean state (cold start) and warm state
+
+3. **Compare against baseline:**
+   - If baseline is `previous-run`, read last saved benchmark results from `.benchmarks/results.json`
+   - If baseline is a git ref, checkout that ref, run benchmarks, then compare
+   - Calculate: absolute difference, percentage change, statistical significance
+
+4. **Identify regressions:**
+   - Flag any metric that regressed > 10% from baseline
+   - For regressions, identify the likely cause (new code in hot path, additional allocations, etc.)
+   - Classify: `critical` (> 50% regression), `warning` (10-50%), `acceptable` (< 10%)
+
+5. **Generate report:**
+   - Summary table with all metrics and comparison
+   - Detailed analysis for any regressions
+   - Recommendations for optimization if regressions found
+   - Save results to `.benchmarks/results.json` for future comparisons
+
+## Output
+
+- Performance report in markdown format
+- Updated baseline results file
+- Regression alerts with severity classification
+
+## Related
+
+- **Skill:** `hatch3r-perf-audit` — comprehensive performance profiling
+- **Agent:** `hatch3r-perf-profiler` — agent for deep performance investigation