hatch3r 1.0.0

package/skills/hatch3r-architecture-review/SKILL.md

@@ -0,0 +1,96 @@
+---
+id: hatch3r-architecture-review
+description: Evaluate architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
+---
+# Architecture Review Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read existing ADRs and the template
+- [ ] Step 2: Define the decision context — problem, constraints, options
+- [ ] Step 3: Evaluate options — pros/cons, prototype if needed, check ADR constraints
+- [ ] Step 4: For external library docs and current best practices, follow the project's tooling hierarchy
+- [ ] Step 5: Write ADR following the template
+- [ ] Step 6: Update affected specs or docs to reference the new ADR
+```
+
+## Step 1: Read Existing ADRs and Template
+
+- Read all ADRs in project docs to understand current architecture and constraints.
+- Read the ADR template (e.g., `docs/adr/0001_template.md` or equivalent).
+- Template sections: Status, Date, Decision Makers, Context, Decision, Alternatives Considered, Consequences, Compliance, Related.
+- Check if any existing ADR is superseded or conflicts with the proposed decision.
+- Read foundational ADRs for invariants.
+
+## Step 2: Define the Decision Context
+
+- **Problem:** What issue or opportunity motivates this decision?
+- **Constraints:** Technical (stack, performance budgets), organizational (timeline, team), regulatory (privacy, security).
+- **Options:** List 2–4 viable alternatives. Include "do nothing" or "status quo" if relevant.
+- **Stakeholders:** Who is affected? Who decides?
+
+Reference:
+
+- Performance budgets: project rules
+- Privacy/security invariants: project rules and specs
+- Data model: project documentation
+- Event model: project documentation
+
+## Step 3: Evaluate Options
+
+- For each option, list **pros** and **cons**.
+- Consider: complexity, maintainability, performance, security, cost, migration effort.
+- Prototype or spike if uncertainty is high — document findings.
+- Check against existing ADR constraints: does this align with core architecture?
+- Use a comparison table (as in the template):
+
+| Option | Pros | Cons |
+| ------ | ---- | ---- |
+| A      | ...  | ...  |
+| B      | ...  | ...  |
+
+## Step 4: External Research
+
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+- **GitHub MCP:** Search for related issues, prior discussions, or similar decisions in the repo.
+- **Context7 MCP:** Look up current API patterns for relevant libraries.
+- **Web search:** For novel problems, security advisories, or best practices.
+
+## Step 5: Write ADR
+
+Follow the project ADR template:
+
+- **Title:** `ADR-XXXX: Short descriptive title`
+- **Status:** `PROPOSED` (draft) or `ACCEPTED` (approved)
+- **Date:** YYYY-MM-DD
+- **Decision Makers:** Names/roles
+- **Context:** Problem, constraints, motivation
+- **Decision:** What we are doing
+- **Alternatives Considered:** Table with pros/cons
+- **Consequences:** Positive, negative, risks
+- **Compliance checklist:**
+  - [ ] Aligns with privacy/security specs
+  - [ ] Aligns with performance budgets
+  - [ ] Does not introduce new dependencies without justification
+- **Related:** Specs, issues, previous ADRs
+
+Save as `docs/adr/XXXX_short-title.md` (or project convention). Use next available number.
+
+## Step 6: Update Affected Docs
+
+- Add references to the new ADR in relevant specs (e.g., data model, event model, quality engineering).
+- Update ADR index if the project maintains one.
+- Link from related GitHub issues or PRs.
+- If superseding an ADR, update the old ADR's Status to `SUPERSEDED by ADR-XXXX`.
+
+## Definition of Done
+
+- [ ] ADR written following project template
+- [ ] Options evaluated with pros/cons table
+- [ ] Tooling-hierarchy followed for external research where relevant
+- [ ] Compliance checklist completed
+- [ ] Affected specs or docs updated to reference the ADR
+- [ ] No privacy/security invariant violations
+- [ ] Performance budgets considered

package/skills/hatch3r-bug-fix/SKILL.md

@@ -0,0 +1,129 @@
+---
+id: hatch3r-bug-fix
+description: Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Bug Fix Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read the issue and relevant specs
+- [ ] Step 2: Produce a diagnosis plan
+- [ ] Step 2b: Browser reproduction (if UI bug)
+- [ ] Step 2c: Test-first approach (TDD alternative — optional)
+- [ ] Step 3: Implement minimal fix
+- [ ] Step 4: Write regression test
+- [ ] Step 5: Verify all tests pass
+- [ ] Step 5b: Browser verification (if UI bug)
+- [ ] Step 6: Open PR
+```
+
+## Step 1: Read Inputs
+
+- Parse the issue body: problem description, reproduction steps, expected/actual behavior, severity, affected area.
+- Read relevant project documentation based on affected area (see spec mapping in project context).
+- Review existing tests in the affected area.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Diagnosis Plan
+
+Before fixing, output:
+
+- **Root cause hypothesis:** what is wrong and why
+- **Files to investigate:** list of files
+- **Reproduction strategy:** how to confirm the bug via tests
+- **Risks:** what could go wrong with the fix
+
+## Step 2b: Browser Reproduction (if UI Bug)
+
+Skip this step if the bug has no visual or interactive symptoms.
+
+- Ensure the dev server is running. If not, start it in the background.
+- Navigate to the page where the bug manifests.
+- Follow the reproduction steps from the issue to confirm the bug is observable.
+- Take a screenshot of the broken state as baseline evidence.
+- Note any browser console errors or warnings associated with the bug.
+
+## Step 2c: Test-First Approach (TDD Alternative)
+
+When the root cause is clear from diagnosis, write the regression test BEFORE implementing the fix:
+
+1. **Write a failing test** that reproduces the exact bug scenario from the issue's reproduction steps.
+2. **Run the test** — confirm it fails with the expected symptom (not a setup error).
+3. **Implement the minimal fix** (Step 3) to make the test pass.
+4. **Verify** the test now passes AND no other tests broke.
+
+This approach guarantees the fix addresses the actual bug and prevents regression. Prefer TDD when:
+- The bug has clear reproduction steps
+- The affected code has existing test infrastructure
+- The root cause is well-understood from Step 2
+
+Skip TDD and use the standard flow (Steps 3→4) when:
+- The bug requires exploratory debugging to locate
+- Test infrastructure needs setup first
+- The fix involves configuration or environment changes
+
+## Step 3: Minimal Fix
+
+- Fix the root cause with minimal changes.
+- Do not refactor unrelated code.
+- Do not introduce new dependencies unless absolutely necessary.
+- Remove dead code created by the fix.
+
+## Step 4: Regression Test
+
+- Write a test that **fails before** the fix and **passes after**.
+- Add edge case tests if the bug reveals coverage gaps.
+- Ensure all existing tests still pass.
+
+## Step 5: Verify
+
+```bash
+npm run lint && npm run typecheck && npm run test
+```
+
+## Step 5b: Browser Verification (if UI Bug)
+
+Skip this step if the bug had no visual or interactive symptoms.
+
+- Navigate to the same page where the bug was reproduced in Step 2b.
+- Follow the original reproduction steps — confirm the bug is now fixed.
+- Take a screenshot of the corrected state.
+- Verify no new visual regressions were introduced in the surrounding UI.
+- Check the browser console for errors or warnings.
+
+## Step 6: Open PR
+
+Use the project's PR template. Include:
+
+- Root cause explanation
+- Fix description with before/after behavior
+- Test evidence
+- Rollback plan (required for P0/P1)
+
+## Required Agent Delegation
+
+You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
+
+- **`hatch3r-researcher`** — MUST spawn before implementation with modes `symptom-trace`, `root-cause`, `codebase-impact`. Skip only for trivially simple bugs (`risk:low` AND `priority:p3`).
+- **`hatch3r-test-writer`** — MUST spawn after fix implementation to write regression tests covering the fixed behavior and related edge cases.
+- **`hatch3r-reviewer`** — MUST spawn after implementation for code review before PR creation.
+
+## Related Skills
+
+- **Skill**: `hatch3r-qa-validation` — use this skill for end-to-end verification of the bug fix
+
+## Definition of Done
+
+- [ ] Root cause identified and documented in PR
+- [ ] Fix implemented with minimal diff
+- [ ] Regression test written
+- [ ] All existing tests pass
+- [ ] No new linter warnings
+- [ ] Browser-verified fix (if UI bug)
+- [ ] Performance budgets maintained
+- [ ] Security/privacy invariants respected
+- [ ] If P0/P1: rollback plan documented

package/skills/hatch3r-ci-pipeline/SKILL.md

@@ -0,0 +1,76 @@
+---
+id: hatch3r-ci-pipeline
+type: skill
+description: Design and optimize CI/CD pipelines. Covers stage design, test parallelization, artifact management, and pipeline performance.
+---
+
+# CI Pipeline Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Audit existing pipeline
+- [ ] Step 2: Design stage structure
+- [ ] Step 3: Optimize test parallelization
+- [ ] Step 4: Configure artifact management
+- [ ] Step 5: Implement and validate
+```
+
+## Step 1: Audit Existing Pipeline
+
+- Map the current pipeline stages, their dependencies, and execution times.
+- Identify bottlenecks: which stages take the longest? Which block others unnecessarily?
+- Check for flaky tests that cause unnecessary reruns.
+- Review resource usage: are runners appropriately sized? Are caches effective?
+- Measure total pipeline duration from push to deployable artifact.
+
+## Step 2: Design Stage Structure
+
+- Organize into logical stages: install, lint, typecheck, unit test, integration test, build, deploy.
+- Maximize parallelism: lint, typecheck, and unit tests can run in parallel after install.
+- Use fail-fast: if lint fails, skip tests. If unit tests fail, skip integration tests.
+- Gate deployments behind all quality checks.
+- Separate environment-specific deployment stages (staging, production) with manual approval gates for production.
+
+## Step 3: Optimize Test Parallelization
+
+- Split test suites across multiple runners using test file sharding or test duration-based splitting.
+- Use test timing data from previous runs to balance shard workloads.
+- Run unit tests and integration tests on separate runners in parallel.
+- For monorepos: only run tests for changed packages and their dependents.
+- Cache test results for unchanged code paths where the test framework supports it.
+
+## Step 4: Configure Artifact Management
+
+- Build artifacts once, deploy the same artifact to all environments.
+- Tag artifacts with commit SHA and build number for traceability.
+- Set retention policies: keep production artifacts longer, clean up PR artifacts after merge.
+- Store build metadata (git SHA, branch, build time, test results) alongside artifacts.
+- Use content-addressable storage or artifact registries appropriate to the project (npm, Docker, S3).
+
+## Step 5: Implement and Validate
+
+- Implement pipeline changes incrementally — test each stage change in a feature branch.
+- Verify caching works correctly: first run populates cache, second run uses it.
+- Confirm parallel stages don't have hidden dependencies causing race conditions.
+- Measure pipeline duration improvement against the baseline from Step 1.
+- Document the pipeline architecture for the team.
+
+## Pipeline Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| Lint + typecheck | < 2 minutes |
+| Unit tests | < 5 minutes |
+| Integration tests | < 10 minutes |
+| Full pipeline (push to artifact) | < 15 minutes |
+| Cache hit ratio | > 80% |
+
+## Definition of Done
+
+- [ ] Pipeline stages optimized with maximum parallelism
+- [ ] Test parallelization configured and balanced
+- [ ] Artifact management with retention policies
+- [ ] Pipeline duration meets performance targets
+- [ ] Documentation updated with pipeline architecture

package/skills/hatch3r-command-customize/SKILL.md

@@ -0,0 +1,67 @@
+---
+id: hatch3r-command-customize
+description: Create and manage per-command customization files for description overrides, enable/disable control, and project-specific markdown instructions. Use when tailoring command behavior to project-specific needs.
+---
+# Command Customization Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify which command to customize
+- [ ] Step 2: Determine customization needs
+- [ ] Step 3: Create the customization files
+- [ ] Step 4: Sync to propagate changes
+- [ ] Step 5: Verify the customized output
+```
+
+## Step 1: Identify Command
+
+Determine which hatch3r command needs customization:
+- Review the commands in `.agents/commands/` and their default behavior
+- Identify gaps between default behavior and project needs
+- Check for existing customization files in `.hatch3r/commands/`
+
+## Step 2: Determine Customization Needs
+
+Decide which customization approach to use:
+
+**YAML (`.customize.yaml`)** — for structured overrides:
+- **Description**: Change how the command is described in adapter outputs
+- **Enabled**: Set to `false` to disable the command entirely
+
+**Markdown (`.customize.md`)** — for free-form instructions:
+- Project-specific workflow steps
+- Additional prerequisites or constraints
+- Custom deployment or release procedures
+
+## Step 3: Create Customization Files
+
+Create files in `.hatch3r/commands/`:
+
+**For YAML overrides:**
+```yaml
+# .hatch3r/commands/{command-id}.customize.yaml
+description: "Release workflow with staging validation"
+```
+
+**For markdown instructions:**
+Create `.hatch3r/commands/{command-id}.customize.md` with project-specific additions. This content is injected into the managed block under `## Project Customizations`.
+
+## Step 4: Sync
+
+Run `npx hatch3r sync` to propagate customizations to all adapter outputs.
+
+## Step 5: Verify
+
+Confirm customizations appear in adapter output files:
+- Check description in adapter outputs (where applicable)
+- Check markdown instructions appear inside the managed block
+- Verify disabled commands are absent from adapter outputs
+
+## Definition of Done
+
+- [ ] Customization files created in `.hatch3r/commands/`
+- [ ] `npx hatch3r sync` completes without errors
+- [ ] Adapter output files reflect the customizations
+- [ ] Customization files committed to the repository

package/skills/hatch3r-context-health/SKILL.md

@@ -0,0 +1,76 @@
+---
+id: hatch3r-context-health
+description: Monitor and maintain conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
+---
+# Context Health Monitoring
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Assess current context health
+- [ ] Step 2: Identify degradation signals
+- [ ] Step 3: Apply corrective action
+- [ ] Step 4: Verify health improvement
+```
+
+## Step 1: Assess Context Health
+
+Run through the self-assessment checklist:
+
+1. **Task recall**: Can you state the original task, acceptance criteria, and scope boundaries without looking?
+2. **Progress tracking**: List what's been completed and what remains.
+3. **Error check**: Count recent failed tool calls or incorrect assumptions.
+4. **File currency**: List files you've modified — when did you last read each one?
+5. **Scope check**: Compare your current work to the original issue description.
+
+## Step 2: Identify Degradation
+
+| Check | Healthy | Degraded |
+|-------|---------|----------|
+| Task recall | Can state requirements from memory | Need to re-read issue |
+| Progress | Clear forward momentum | Cycling or stuck |
+| Errors | Occasional, different causes | Repeated, same cause |
+| Files | Recently read and current | Stale, may have drifted |
+| Scope | Aligned with acceptance criteria | Drifted to tangential work |
+
+## Step 3: Apply Corrective Action
+
+### If 0-1 checks degraded (Green): Continue normally
+
+### If 2-3 checks degraded (Yellow): Refresh
+1. Re-read the issue body and acceptance criteria
+2. Re-read all files you've modified in this session
+3. Create a progress summary of completed work
+4. Re-plan remaining steps from the refreshed context
+
+### If 4 checks degraded (Orange): Delegate
+1. Create a handoff document with all context
+2. Spawn a sub-agent using the Task tool with the handoff
+3. Monitor the sub-agent's output
+4. Aggregate results
+
+### If 5 checks degraded (Red): Checkpoint and Stop
+1. Save all progress (files changed, tests written)
+2. Document remaining work and blockers
+3. Post progress on the GitHub issue
+4. Recommend fresh conversation
+
+## Step 4: Verify Improvement
+
+After corrective action:
+- Re-run the assessment checklist
+- Confirm health is at Green or Yellow
+- Resume work on the original task
+
+## Definition of Done
+
+- [ ] Context health assessed with all 5 checks
+- [ ] Degradation level determined (Green/Yellow/Orange/Red)
+- [ ] Appropriate corrective action taken
+- [ ] Health verified at Green or Yellow after correction
+
+## Related Skills & Agents
+
+- **Command**: `hatch3r-context-health` — full monitoring protocol with integration points
+- **Command**: `hatch3r-board-pickup` — auto-advance mode uses context health for session management

package/skills/hatch3r-cost-tracking/SKILL.md

@@ -0,0 +1,65 @@
+---
+id: hatch3r-cost-tracking
+description: Track token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
+---
+# Cost Tracking Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Review cost tracking configuration
+- [ ] Step 2: Estimate current session token usage
+- [ ] Step 3: Identify cost optimization opportunities
+- [ ] Step 4: Generate cost report
+```
+
+## Step 1: Review Configuration
+
+1. Check `hatch.json` for a `costTracking` section.
+2. Note configured budgets: `sessionBudget`, `issueBudget`, `epicBudget`.
+3. Note warning thresholds and whether `hardStop` is enabled.
+4. If no configuration exists, operate in report-only mode.
+
+## Step 2: Estimate Token Usage
+
+Estimate tokens for the current session using these rules:
+
+| Content Type | Rule |
+|-------------|------|
+| Messages | ~4 characters per token |
+| Tool calls | JSON length / 4 (input), response length / 4 (output) |
+| File reads | Character count / 4 |
+| Web searches | ~500 tokens per search |
+
+Calculate estimated cost using the model tier rates from the `hatch3r-cost-tracking` command reference.
+
+## Step 3: Identify Optimizations
+
+Review usage patterns for savings:
+
+- **Large file reads**: Were files read multiple times without changes? Cache instead.
+- **Model tier**: Could routine tasks (linting, formatting) use a faster/cheaper model?
+- **Context bloat**: Is irrelevant context accumulating? Summarize and trim.
+- **Batching**: Were multiple small tool calls made that could be combined?
+- **Scope creep**: Did work expand beyond the original issue? Scope back.
+
+## Step 4: Generate Report
+
+Produce a cost report using the output format from the `hatch3r-cost-tracking` command. Include:
+- Total estimated tokens (input + output)
+- Estimated cost at the current model tier
+- Budget status (if configured)
+- Top optimization opportunities
+
+## Definition of Done
+
+- [ ] Cost configuration reviewed (or report-only mode noted)
+- [ ] Token usage estimated for current session
+- [ ] Optimization opportunities identified
+- [ ] Cost report generated with budget status
+
+## Related Skills & Agents
+
+- **Command**: `hatch3r-cost-tracking` — full cost tracking protocol with guardrails and budget enforcement
+- **Skill**: `hatch3r-context-health` — context health monitoring complements cost tracking for session management

package/skills/hatch3r-dep-audit/SKILL.md

@@ -0,0 +1,82 @@
+---
+id: hatch3r-dep-audit
+description: Audit and update npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Dependency Audit Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Run npm audit + npm outdated, categorize findings
+- [ ] Step 2: Research CVEs via web search for critical/high
+- [ ] Step 3: Plan upgrades (breaking vs non-breaking, bundle impact)
+- [ ] Step 4: Implement upgrades one-by-one, run tests after each
+- [ ] Step 5: Verify quality gates and bundle size
+- [ ] Step 6: Open PR with upgrade rationale
+```
+
+## Step 1: Gather Findings
+
+- Run `npm audit` and capture output. Categorize by severity: critical, high, moderate, low.
+- Run `npm outdated` to identify packages with newer versions.
+- Cross-reference with project dependency management rules: fix high/critical before merge, patch within 48h for critical CVEs.
+- Document findings in a structured table: package, current version, available version, severity, CVE IDs (if any).
+
+## Step 2: Research CVEs
+
+For critical and high vulnerabilities:
+
+- Use **web search** to look up each CVE: exploitability, affected versions, fix version, workarounds.
+- Check npm advisories and GitHub security advisories for official guidance.
+- Prioritize: critical first, then high. Moderate/low can be batched.
+- Note any packages with no fix available — document mitigation or deferral rationale.
+
+## Step 3: Plan Upgrades
+
+Before changing anything:
+
+- **Breaking vs non-breaking:** Check each package's changelog (npm, GitHub releases). For external library docs and current best practices, follow the project's tooling hierarchy.
+- **Bundle impact:** Check bundle size budget from project rules. Run `npm run build` and measure before/after for each upgrade.
+- **Upgrade order:** Security fixes first, then non-breaking minor/patch, then breaking changes (one at a time).
+- **Risks:** List packages that may require code changes (e.g., major version bumps).
+
+## Step 4: Implement Upgrades
+
+- Upgrade **one package at a time** (or one logical group, e.g., all patch-level ecosystem packages).
+- After each upgrade: run `npm install`, then `npm run lint && npm run typecheck && npm run test`.
+- If tests fail: fix or revert. Document any required code changes.
+- Remove unused dependencies during the pass (per dependency-management rule).
+- Commit `package-lock.json` — never use `npm install --no-save`.
+
+## Step 5: Verify
+
+```bash
+npm run lint && npm run typecheck && npm run test
+npm run build
+```
+
+- Confirm bundle size within budget (if defined).
+- Run `npm audit` — no critical or high vulnerabilities remaining.
+- Ensure `package-lock.json` is committed.
+
+## Step 6: Open PR
+
+Use the project's PR template. Include:
+
+- **Upgrade rationale:** why each package was upgraded (CVE, freshness, feature).
+- **Breaking changes:** any code changes required and why.
+- **Bundle impact:** before/after gzipped size.
+- **Test evidence:** all tests pass, no regressions.
+- **Rollback plan:** if risky (e.g., major version bump).
+
+## Definition of Done
+
+- [ ] No critical or high CVEs remaining
+- [ ] All tests pass (lint, typecheck, unit, integration, E2E)
+- [ ] Bundle size within budget (if defined)
+- [ ] `package-lock.json` committed
+- [ ] PR includes upgrade rationale and bundle impact
+- [ ] No duplicate packages; unused deps removed