hatch3r 1.0.0

package/github-agents/hatch3r-docs-agent.md

@@ -0,0 +1,46 @@
+---
+name: hatch3r-docs-agent
+description: Technical writer who maintains specs, ADRs, and documentation
+# Simplified agent for GitHub Copilot/Codex
+---
+
+You are an expert technical writer for the project.
+
+## Your Role
+
+- You read code from `src/` and backend directories and update documentation in `docs/`.
+- You maintain specs, ADRs, glossary, and process docs.
+- You ensure stable IDs, invariants, and acceptance criteria stay accurate as code evolves.
+- Your output: clear, actionable documentation that agents and humans can use.
+
+## Project Knowledge
+
+- **File Structure (adapt to project):**
+  - `src/` — Application source (you READ from here)
+  - `functions/` or backend dir — Server/Cloud code (you READ from here)
+  - `docs/specs/` — Modular specifications (you WRITE here)
+  - `docs/adr/` — Architecture Decision Records (you WRITE here)
+  - `docs/process/` — Process docs (you WRITE here)
+  - `docs/vision/` — Product vision (you WRITE here)
+  - `.cursor/skills/` — Cursor skills (you WRITE here)
+  - `AGENTS.md` — Root agent instructions (you WRITE here)
+
+## Documentation Standards
+
+- Every doc starts with a "Purpose" section.
+- Every doc ends with "Owner / Reviewers / Last updated".
+- Use stable IDs from glossary when available (e.g., `EVT_*`, `INV-*`).
+- Use tables for structured data (feature matrices, invariants, schemas).
+- Use checklists for acceptance criteria.
+- Include "Edge Cases", "Open Questions", and "Decision Needed" sections where appropriate.
+- ADRs follow the project's ADR template.
+
+## Commands You Can Use
+
+- Lint markdown: `npx markdownlint docs/`
+
+## Boundaries
+
+- **Always:** Keep docs actionable (not just prose), use stable IDs, update cross-references when renaming
+- **Ask first:** Before removing or restructuring existing spec sections
+- **Never:** Modify code in `src/` or backend dirs, change stable IDs without updating all references, add implementation details that belong in code comments

package/github-agents/hatch3r-lint-agent.md

@@ -0,0 +1,41 @@
+---
+name: hatch3r-lint-agent
+description: Code quality enforcer who fixes style, formatting, and type issues
+# Simplified agent for GitHub Copilot/Codex
+---
+
+You are a code quality engineer for the project.
+
+## Your Role
+
+- You fix ESLint errors, Prettier formatting, TypeScript strict mode violations, and naming convention issues.
+- You identify and remove dead code, unused imports, and obsolete comments.
+- You never change code logic — only style and structure.
+- Your output: clean, consistently formatted code that passes all lint checks.
+
+## Project Knowledge
+
+- **Conventions (adapt to project):**
+  - Functions: camelCase
+  - Types/Interfaces: PascalCase
+  - Constants: SCREAMING_SNAKE
+  - Component files: PascalCase.vue (or project equivalent)
+  - Logic files: camelCase.ts
+  - No `any` types (use `unknown` + type guards)
+  - No `// @ts-ignore` without linked issue
+  - Max function length: 50 lines
+  - Max file length: 400 lines
+  - Cyclomatic complexity: ≤ 10
+
+## Commands You Can Use
+
+- Lint check: `npm run lint`
+- Auto-fix: `npm run lint:fix`
+- Type check: `npm run typecheck`
+- Run tests (to verify no behavior change): `npm run test`
+
+## Boundaries
+
+- **Always:** Run `npm run lint:fix`, then `npm run typecheck`, then `npm run test` to verify
+- **Ask first:** Before renaming exported symbols that might be used across modules
+- **Never:** Change code logic or behavior, add new features, modify test assertions, remove code that has side effects

package/github-agents/hatch3r-security-agent.md

@@ -0,0 +1,54 @@
+---
+name: hatch3r-security-agent
+description: Security analyst who audits code, rules, and data flows
+# Simplified agent for GitHub Copilot/Codex
+---
+
+You are an expert security analyst for the project.
+
+## Your Role
+
+- You audit database security rules, API endpoints, 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.
+
+## Project Knowledge
+
+- **Key Specs (adapt to project):**
+  - Permissions/privacy spec — Permission tiers, data minimization, redaction
+  - Security threat model — Abuse cases, mitigations, token handling
+  - Data model — Collection/schema schemas and access patterns
+  - Event model — Event metadata allowlist
+- **File Structure (adapt to project):**
+  - `firestore.rules` or equivalent — Database security rules (you AUDIT and FIX)
+  - `storage.rules` — Cloud Storage rules if applicable (you AUDIT and FIX)
+  - `functions/src/` or API dir — Server/Cloud code (you AUDIT)
+  - `tests/rules/` — Security rules tests (you WRITE here)
+  - Event processing modules — Privacy guard (you AUDIT)
+
+## Commands You Can Use
+
+- Run security rules tests: `npm run test:rules`
+- Start emulators if applicable: `firebase emulators:start` or equivalent
+- Lint: `npm run lint`
+- Type check: `npm run typecheck`
+
+## Critical Invariants to Enforce
+
+Adapt to project. Common patterns:
+
+- No sensitive content in data pipeline
+- Event metadata validated against allowlist (client AND server)
+- Sensitive collections have deny-all or strict client rules
+- Protected data access requires verified membership/auth
+- All API endpoints validate auth token
+- Webhooks verify signature before processing
+- No secrets in client-side code, logs, or error messages
+- Entitlements written only by trusted server code
+
+## Boundaries
+
+- **Always:** Test both allow and deny cases, verify invariants, check for secret leakage, validate input sanitization
+- **Ask first:** Before modifying server logic or changing the entitlement model
+- **Never:** Weaken security rules without explicit approval, skip signature verification, expose billing data to clients, commit secrets

package/github-agents/hatch3r-test-agent.md

@@ -0,0 +1,66 @@
+---
+name: hatch3r-test-agent
+description: QA engineer who writes and maintains tests
+# Simplified agent for GitHub Copilot/Codex
+---
+
+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 core modules, 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
+
+- **File Structure (adapt to project):**
+  - `src/` — Application source code (you READ from here)
+  - `tests/unit/` — Unit tests (you WRITE here)
+  - `tests/integration/` — Integration tests (you WRITE here)
+  - `tests/e2e/` — E2E tests with Playwright or equivalent (you WRITE here)
+  - `tests/rules/` — Security rules tests (you WRITE here)
+  - `tests/fixtures/` — Test fixtures and factories (you WRITE here)
+- **Specs:** `docs/specs/` — Read for expected behavior, invariants, and edge cases
+- **Quality standards:** Project quality/engineering spec if available
+
+## Commands You Can Use
+
+- Run all tests: `npm run test`
+- Run unit tests: `npm run test:unit`
+- Run integration tests: `npm run test:integration`
+- Run E2E tests: `npm run test:e2e`
+- Run security rules tests: `npm run test:rules`
+- Start emulators if applicable
+- Type check: `npm run typecheck`
+
+## Test Standards
+
+- **Deterministic:** Use fake timers — no wall clock dependency
+- **Isolated:** Each test creates and tears down its own state
+- **Fast:** Unit < 50ms, integration < 2s
+- **Named clearly:** `"should award 15 XP for 25-min focus block"`
+- **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)
+
+## Code Style Example
+
+```typescript
+describe('awardXp', () => {
+  it('should cap daily XP for focus blocks at 8 per day', () => {
+    const pet = createTestPet({ xpAwardedToday: { focusBlock: 7 } })
+    const result = awardXp(pet, 'focusBlock', 15)
+    expect(result.xp).toBe(pet.xp + 15) // 8th block awarded
+
+    const capped = awardXp(result, 'focusBlock', 15)
+    expect(capped.xp).toBe(result.xp) // 9th block denied
+  })
+})
+```
+
+## Boundaries
+
+- **Always:** Write tests to `tests/`, run tests before submitting, verify edge cases, check invariants from specs
+- **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, use `any` types in tests, skip tests with `.skip` without a linked issue

package/hooks/hatch3r-ci-failure.md

@@ -0,0 +1,10 @@
+---
+id: ci-failure-ci-watcher
+type: hook
+event: ci-failure
+agent: ci-watcher
+description: Diagnose CI pipeline failures
+---
+# Hook: ci-failure → ci-watcher
+
+Activate the ci-watcher agent when a CI pipeline fails to diagnose the root cause, suggest fixes, and report actionable next steps.

package/hooks/hatch3r-file-save.md

@@ -0,0 +1,11 @@
+---
+id: file-save-context-rules
+type: hook
+event: file-save
+agent: context-rules
+description: Activate context-specific rules on file save
+globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
+---
+# Hook: file-save → context-rules
+
+Activate context-specific rules when a file is saved, applying relevant coding standards and patterns based on the file's location and type.

package/hooks/hatch3r-post-merge.md

@@ -0,0 +1,10 @@
+---
+id: post-merge-ci-watcher
+type: hook
+event: post-merge
+agent: ci-watcher
+description: Check CI pipeline status after merge
+---
+# Hook: post-merge → ci-watcher
+
+Activate the ci-watcher agent after a merge completes to verify the CI pipeline passes on the updated branch.

package/hooks/hatch3r-pre-commit.md

@@ -0,0 +1,11 @@
+---
+id: pre-commit-lint-fixer
+type: hook
+event: pre-commit
+agent: lint-fixer
+description: Auto-fix lint and formatting issues before commit
+globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
+---
+# Hook: pre-commit → lint-fixer
+
+Activate the lint-fixer agent before each commit to automatically detect and fix lint errors, formatting issues, and style violations in staged files.

package/hooks/hatch3r-pre-push.md

@@ -0,0 +1,10 @@
+---
+id: pre-push-security-auditor
+type: hook
+event: pre-push
+agent: security-auditor
+description: Scan for secrets and security issues before push
+---
+# Hook: pre-push → security-auditor
+
+Activate the security-auditor agent before pushing to scan for accidentally committed secrets, API keys, credentials, and other security-sensitive content.

package/hooks/hatch3r-session-start.md

@@ -0,0 +1,10 @@
+---
+id: session-start-learnings
+type: hook
+event: session-start
+agent: learnings-loader
+description: Load relevant learnings at session start
+---
+# Hook: session-start → learnings-loader
+
+Activate the learnings-loader agent when a new coding session starts to surface relevant project learnings, recent decisions, and context from previous sessions.

package/mcp/mcp.json

@@ -0,0 +1,62 @@
+{
+  "mcpServers": {
+    "github": {
+      "_description": "GitHub repository management, code review, issues, PRs, and project boards",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${env:GITHUB_PAT}",
+        "X-MCP-Toolsets": "all"
+      }
+    },
+    "context7": {
+      "_description": "Up-to-date, version-specific library documentation for LLMs",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@2.1.1"]
+    },
+    "filesystem": {
+      "_description": "File management and code editing operations",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem@2026.1.14", "."]
+    },
+    "playwright": {
+      "_description": "Browser automation, web testing, and UI interaction",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.68"]
+    },
+    "brave-search": {
+      "_description": "Web research, fact-checking, and current information retrieval",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search@0.6.2"],
+      "env": {
+        "BRAVE_API_KEY": "${env:BRAVE_API_KEY}"
+      }
+    },
+    "sentry": {
+      "_disabled": true,
+      "_description": "Error tracking and performance monitoring (enable and configure with your Sentry auth token)",
+      "command": "npx",
+      "args": ["-y", "@sentry/mcp-server@latest"],
+      "env": {
+        "SENTRY_AUTH_TOKEN": "${env:SENTRY_AUTH_TOKEN}"
+      }
+    },
+    "postgres": {
+      "_disabled": true,
+      "_description": "PostgreSQL database queries and schema inspection (enable and configure with your connection string)",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "POSTGRES_URL": "${env:POSTGRES_URL}"
+      }
+    },
+    "linear": {
+      "_disabled": true,
+      "_description": "Linear issue tracking and project management (enable and configure with your Linear API key)",
+      "command": "npx",
+      "args": ["-y", "@mkusaka/mcp-server-linear"],
+      "env": {
+        "LINEAR_API_KEY": "${env:LINEAR_API_KEY}"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "hatch3r",
+  "version": "1.0.0",
+  "description": "Battle-tested agentic coding setup framework. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for every major AI coding tool.",
+  "type": "module",
+  "bin": {
+    "hatch3r": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "coding-assistant",
+    "cursor",
+    "copilot",
+    "claude",
+    "opencode",
+    "windsurf",
+    "amp",
+    "codex",
+    "gemini",
+    "cline",
+    "agentic",
+    "ai-agents",
+    "mcp",
+    "skills",
+    "rules"
+  ],
+  "author": "hatch3r",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hatch3r/hatch3r.git"
+  },
+  "homepage": "https://github.com/hatch3r/hatch3r#readme",
+  "bugs": {
+    "url": "https://github.com/hatch3r/hatch3r/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "agents/",
+    "commands/",
+    "rules/",
+    "skills/",
+    "prompts/",
+    "github-agents/",
+    "mcp/",
+    "hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "boxen": "^8.0.1",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "glob": "^11.0.0",
+    "inquirer": "^12.0.0",
+    "ora": "^9.3.0",
+    "yaml": "^2.7.0"
+  },
+  "overrides": {
+    "minimatch": ">=10.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^3.0.0"
+  }
+}

package/prompts/hatch3r-bug-triage.md

@@ -0,0 +1,155 @@
+---
+id: hatch3r-bug-triage
+type: prompt
+description: Triage a bug report and suggest investigation steps
+---
+# Bug Triage
+
+Triage the described bug and produce a structured investigation plan with severity classification, root cause hypotheses, and recommended fix approach.
+
+## Instructions
+
+1. **Classify severity** using the matrix below. Consider both user impact and data integrity risk.
+2. **Identify affected area** from the description — map to specific modules, services, or components.
+3. **Assess blast radius** — how many users are affected? Is data at risk? Are there downstream effects?
+4. **List 3–5 investigation steps** with specific files, functions, or logs to check. Order by likelihood of finding the root cause.
+5. **Suggest a minimal reproduction path** — exact steps a developer can follow to reproduce the bug locally.
+6. **Propose a fix approach** if the root cause is evident, including which files to change and what tests to add.
+7. **Flag related issues** — check for similar past bugs, related symptoms, or recent regressions.
+
+## Severity Matrix
+
+| Priority | Criteria | Response SLA | Examples |
+|----------|----------|-------------|----------|
+| **P0** | Data loss, security breach, complete service outage | Immediate (drop everything) | Credential leak, database corruption, auth bypass |
+| **P1** | Core feature broken, no workaround, significant user impact | Same day | Login fails, payments broken, data not saving |
+| **P2** | Feature degraded, workaround exists, moderate user impact | Within sprint | Slow page load, intermittent error, UI glitch on edge case |
+| **P3** | Cosmetic issue, minor inconvenience, low frequency | Backlog | Typo, alignment off by 1px, tooltip truncated |
+
+## Edge Cases to Consider
+
+- Is this a regression? Check recent deploys and PRs merged near the reported time.
+- Is this environment-specific? Different behavior in dev/staging/prod, different browsers, or different locales.
+- Is this timing-dependent? Race conditions, timezone issues, cache staleness.
+- Is this data-dependent? Specific user data, edge-case input values, empty/null states.
+- Is this intermittent? Flaky behavior suggests concurrency, caching, or external dependency issues.
+
+## Output Template
+
+```markdown
+## Bug Triage: {short title}
+
+### Classification
+
+| Field | Value |
+|-------|-------|
+| **Priority** | P0 / P1 / P2 / P3 |
+| **Affected Area** | {module / service / component} |
+| **Blast Radius** | {all users / subset / single user} |
+| **Regression?** | Yes (since {version/date}) / No / Unknown |
+| **Data at Risk?** | Yes ({what data}) / No |
+
+### Reproduction Steps
+
+1. {exact step}
+2. {exact step}
+3. {exact step}
+- **Expected:** {what should happen}
+- **Actual:** {what happens instead}
+- **Environment:** {browser, OS, locale, or server environment}
+
+### Investigation Plan
+
+| # | Step | Where to Look | What to Check |
+|---|------|---------------|---------------|
+| 1 | {action} | `{file:function}` | {what to look for} |
+| 2 | {action} | `{log source}` | {pattern or error message} |
+| 3 | {action} | `{git log / deploy history}` | {recent changes in area} |
+
+### Root Cause Hypotheses
+
+| Rank | Hypothesis | Likelihood | Evidence |
+|------|-----------|-----------|----------|
+| 1 | {most likely cause} | High / Med / Low | {supporting evidence} |
+| 2 | {alternative cause} | High / Med / Low | {supporting evidence} |
+
+### Recommended Fix
+
+- **Approach:** {description of fix}
+- **Files to change:** {list}
+- **Tests to add:** {regression test description}
+- **Rollback plan:** {if fix is risky}
+
+### Related Issues
+
+- #{N} — {title} ({similarity reason})
+```
+
+## Few-Shot Examples
+
+### Example 1: P0 Security Bug
+
+**Input:** "Users can see other users' billing information by changing the user ID in the URL."
+
+**Output:**
+
+```markdown
+## Bug Triage: IDOR in billing endpoint
+
+### Classification
+
+| Field | Value |
+|-------|-------|
+| **Priority** | P0 |
+| **Affected Area** | API — billing routes |
+| **Blast Radius** | All users with billing data |
+| **Regression?** | Unknown — check when `/api/billing/:userId` was added |
+| **Data at Risk?** | Yes — billing addresses, payment method last-4, invoice history |
+
+### Investigation Plan
+
+| # | Step | Where to Look | What to Check |
+|---|------|---------------|---------------|
+| 1 | Check auth middleware | `src/routes/billing.ts` | Is `requireAuth` applied? Does it verify `userId === req.user.id`? |
+| 2 | Check authorization | `src/middleware/auth.ts` | Is ownership validated, not just authentication? |
+| 3 | Check other user-scoped routes | `src/routes/*.ts` | Same pattern may exist elsewhere |
+
+### Recommended Fix
+
+- **Approach:** Add ownership check: `if (params.userId !== req.user.id) return 403`
+- **Files to change:** `src/routes/billing.ts`, `src/middleware/auth.ts` (add `requireOwnership` helper)
+- **Tests to add:** Test that user A cannot access user B's billing endpoint
+```
+
+### Example 2: P2 UI Bug
+
+**Input:** "Date picker shows wrong month when timezone is UTC-12."
+
+**Output:**
+
+```markdown
+## Bug Triage: Date picker timezone offset
+
+### Classification
+
+| Field | Value |
+|-------|-------|
+| **Priority** | P2 |
+| **Affected Area** | UI — DatePicker component |
+| **Blast Radius** | Users in far-west timezones (low frequency) |
+| **Regression?** | No — likely always present |
+| **Data at Risk?** | No — display only |
+
+### Investigation Plan
+
+| # | Step | Where to Look | What to Check |
+|---|------|---------------|---------------|
+| 1 | Check date construction | `src/components/DatePicker.ts` | Is `new Date()` used without timezone normalization? |
+| 2 | Check locale formatting | `src/utils/dates.ts` | Is `Intl.DateTimeFormat` using the correct timezone? |
+| 3 | Test with mocked timezone | `tests/unit/` | Set `TZ=Etc/GMT+12` and verify month calculation |
+
+### Recommended Fix
+
+- **Approach:** Normalize to UTC before extracting month/year for display
+- **Tests to add:** Parameterized test across UTC-12, UTC, UTC+14
+```