hatch3r 1.0.0

package/commands/hatch3r-command-customize.md

@@ -0,0 +1,94 @@
+---
+id: hatch3r-command-customize
+type: command
+description: Configure per-command customization including description overrides, enable/disable control, and project-specific markdown instructions
+---
+# Command Customization — Per-Command Configuration
+
+Customize individual command behavior for project-specific needs via `.hatch3r/commands/` configuration files. Supports structured YAML overrides and free-form markdown instruction injection, all propagated to every adapter output on sync.
+
+---
+
+## Customization File Locations
+
+Each command supports two optional customization files:
+
+```
+.hatch3r/commands/{command-id}.customize.yaml    # structured overrides
+.hatch3r/commands/{command-id}.customize.md      # free-form markdown instructions
+```
+
+Both files are optional and can be used independently or together.
+
+## YAML Customization Schema
+
+```yaml
+command: hatch3r-release
+description: "Release workflow with mandatory staging deployment step"
+enabled: true
+```
+
+### Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `description` | string | (from canonical) | Override the command's description in adapter frontmatter |
+| `enabled` | boolean | `true` | Set to `false` to exclude this command from adapter output generation |
+
+## Markdown Customization
+
+Create `.hatch3r/commands/{command-id}.customize.md` with free-form markdown to inject project-specific instructions into the command's managed block. This content is appended after the canonical command definition under a `## Project Customizations` header.
+
+### Example
+
+**File:** `.hatch3r/commands/hatch3r-release.customize.md`
+
+```markdown
+## Project-Specific Release Steps
+
+Before creating any release:
+
+1. Ensure all E2E tests pass on staging: `npm run test:e2e:staging`
+2. Verify the changelog has been updated in `CHANGELOG.md`
+3. Confirm the release has been approved in the `#releases` Slack channel
+4. Tag the Docker image with the release version
+
+### Deployment Sequence
+
+Deploy in order: database migrations → API servers → worker processes → frontend CDN
+```
+
+### How It Works
+
+1. During `hatch3r sync`, adapters read the `.customize.md` file
+2. The markdown content is appended inside the managed block, after the canonical command content
+3. All adapter outputs receive the customization automatically
+4. Changes propagate on every sync
+
+## Disabling a Command
+
+To exclude a command from adapter output without deleting its canonical file:
+
+```yaml
+# .hatch3r/commands/hatch3r-cost-tracking.customize.yaml
+enabled: false
+```
+
+## Workflow
+
+1. Identify which command to customize
+2. Create `.hatch3r/commands/{command-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 command files
+
+## Guardrails
+
+- Customization files cannot remove the command's core instructions
+- Invalid YAML produces warnings but does not prevent command execution (graceful degradation)
+- Customization files should be committed to the repository
+
+## Related
+
+- Agent customization: `hatch3r-agent-customize` command
+- Skill customization: `hatch3r-skill-customize` command
+- Rule customization: `hatch3r-rule-customize` command

package/commands/hatch3r-context-health.md

@@ -0,0 +1,112 @@
+---
+id: hatch3r-context-health
+type: command
+description: Monitor conversation context health, detect degradation, and auto-suggest fresh context or sub-agent delegation
+---
+# Context Health — Conversation Context Monitoring
+
+Monitor and maintain healthy conversation context during long-running agent sessions. Detects context degradation before it impacts output quality and recommends corrective actions.
+
+---
+
+## Context Health Indicators
+
+### Degradation Signals
+
+| Signal | Detection Method | Threshold |
+|--------|-----------------|-----------|
+| Conversation depth | Count user/assistant turns | > 30 turns |
+| Token accumulation | Estimate total context tokens | > 80% of model context window |
+| Topic drift | Compare current task to original issue scope | Cosine similarity < 0.6 |
+| Repeated errors | Track consecutive failed attempts | > 2 failures on same task |
+| File staleness | Track time since last file re-read | > 20 turns since last read |
+| Tool failure rate | Track tool call success/failure ratio | > 30% failure rate |
+
+### Health Levels
+
+| Level | Status | Action |
+|-------|--------|--------|
+| Green | Healthy (< 50% indicators triggered) | Continue normally |
+| Yellow | Degrading (50-70% indicators triggered) | Refresh key context, summarize progress |
+| Orange | At risk (70-90% indicators triggered) | Delegate remaining work to sub-agent |
+| Red | Degraded (> 90% indicators triggered) | Stop, create checkpoint, spawn fresh agent |
+
+## Monitoring Protocol
+
+### Passive Monitoring (Always Active)
+
+Agents should self-assess context health at natural breakpoints:
+- After completing each sub-task or implementation step
+- Before starting a new file or module
+- After receiving an error or unexpected result
+- Every 10 conversation turns
+
+### Self-Assessment Checklist
+
+At each checkpoint, the agent evaluates:
+1. **Can I accurately recall the original task requirements without re-reading?**
+2. **Am I making progress or cycling on the same issue?**
+3. **Are my tool calls succeeding at a reasonable rate?**
+4. **Is my understanding of the codebase still current?**
+5. **Have I drifted from the issue's acceptance criteria?**
+
+### Corrective Actions
+
+#### Refresh (Yellow)
+- Re-read the issue body and acceptance criteria
+- Re-read key files that have been modified
+- Summarize progress so far in a structured checkpoint
+
+#### Delegate (Orange)
+- Create a structured handoff document with: completed work, remaining tasks, key context, file list
+- Spawn a sub-agent with the handoff document using the Task tool
+- The sub-agent starts fresh with full context window
+
+#### Checkpoint and Stop (Red)
+- Save a progress checkpoint: files changed, tests written, current blockers
+- Post a status comment on the GitHub issue with progress
+- Recommend the user start a new conversation for the remaining work
+
+## Integration with Board Pickup
+
+When `board-pickup` operates in auto-advance mode:
+- Context health is checked between each issue
+- If health drops to Orange, the current issue is completed and a fresh agent handles the next one
+- If health drops to Red mid-issue, the issue is marked as PARTIAL and moved back to Ready
+
+## Output Format
+
+```
+## Context Health Check
+
+**Level:** GREEN | YELLOW | ORANGE | RED
+
+**Indicators:**
+- Conversation depth: {turns} / 30
+- Token usage: ~{estimated}% of context window
+- Topic coherence: {assessment}
+- Error rate: {n} failures in last {m} operations
+- File staleness: {n} files not re-read in {m} turns
+
+**Recommendation:** {CONTINUE | REFRESH | DELEGATE | CHECKPOINT}
+
+**Action taken:** {what corrective action was performed, if any}
+```
+
+---
+
+## Error Handling
+
+- **Self-assessment failure:** If the agent cannot determine its own health level, default to Yellow and perform a context refresh.
+- **Delegation failure:** If sub-agent spawn fails, fall back to Checkpoint and Stop (Red protocol).
+- **Board integration failure:** Log warning and continue. Context health operates independently of board state.
+
+---
+
+## Guardrails
+
+- **Never ignore Red status.** A Red assessment always results in a checkpoint and stop.
+- **Do not inflate health.** When uncertain, round toward the more degraded level.
+- **Passive monitoring is mandatory** during board-pickup auto-advance mode.
+- **Handoff documents must be complete.** Never delegate without listing completed work, remaining tasks, key context, and file list.
+- **Do not expand scope during refresh.** Re-reading context is not an invitation to add new tasks.

package/commands/hatch3r-cost-tracking.md

@@ -0,0 +1,139 @@
+---
+id: hatch3r-cost-tracking
+type: command
+description: Track and report token usage and estimated costs across agent workflows and board operations
+---
+# Cost Tracking — Token Usage and Cost Reporting
+
+Track token consumption and estimated costs across sub-agent workflows, board operations, and development sessions. Provides visibility into AI usage patterns and enforces cost guardrails.
+
+---
+
+## Cost Tracking Model
+
+### Token Estimation
+
+Since exact token counts are not always available from the runtime, use estimation:
+
+| Content Type | Estimation Rule |
+|-------------|----------------|
+| User message | ~4 characters per token |
+| Assistant response | ~4 characters per token |
+| Tool call (input) | JSON stringified length / 4 |
+| Tool call (output) | Response length / 4 |
+| File read | File character count / 4 |
+| Web search | ~500 tokens per search |
+
+### Cost Estimation
+
+| Model Tier | Input (per 1M tokens) | Output (per 1M tokens) |
+|-----------|----------------------|----------------------|
+| Fast | $0.25 | $1.00 |
+| Standard | $3.00 | $15.00 |
+| Premium | $15.00 | $75.00 |
+
+These are reference rates — update based on actual provider pricing.
+
+## Tracking Scope
+
+### Per-Issue Tracking
+- Total tokens consumed implementing an issue
+- Breakdown: planning vs implementation vs testing vs review
+- Sub-agent token usage (each sub-agent reports independently)
+- Estimated cost at current model pricing
+
+### Per-Session Tracking
+- Total tokens in the current conversation
+- Running cost estimate
+- Comparison to session budget (if configured)
+- Warning at 50%, 75%, 90% of budget
+
+### Board Operation Tracking
+- Tokens consumed per board-pickup cycle
+- Tokens per issue type (bug fix vs feature vs refactor)
+- Historical trends across sessions
+- Average cost per completed issue
+
+## Cost Guardrails
+
+### Budget Configuration
+
+Configure in `hatch.json`:
+```json
+{
+  "costTracking": {
+    "sessionBudget": 10.00,
+    "issueBudget": 5.00,
+    "epicBudget": 50.00,
+    "currency": "USD",
+    "warningThresholds": [0.5, 0.75, 0.9],
+    "hardStop": true
+  }
+}
+```
+
+### Enforcement
+
+| Threshold | Action |
+|-----------|--------|
+| 50% of budget | Log warning, continue |
+| 75% of budget | Alert user, suggest optimization |
+| 90% of budget | Strong warning, recommend delegation or checkpoint |
+| 100% of budget | Stop (if hardStop=true) or alert and continue |
+
+### Cost Optimization Strategies
+
+When approaching budget limits:
+1. **Reduce context**: Summarize long conversations, drop irrelevant file content
+2. **Delegate to faster models**: Use fast-tier sub-agents for routine tasks
+3. **Cache results**: Avoid re-reading unchanged files
+4. **Batch operations**: Combine multiple small tool calls into fewer larger ones
+5. **Scope reduction**: Break remaining work into a new issue for a fresh session
+
+## Output Format
+
+```
+## Cost Report: {scope}
+
+**Period:** {session/issue/sprint}
+
+**Token Usage:**
+- Input tokens: ~{n}
+- Output tokens: ~{n}
+- Total tokens: ~{n}
+
+**Estimated Cost:** ${amount}
+
+**Budget Status:** {amount} / {budget} ({percentage}%)
+
+**Breakdown:**
+
+| Phase | Tokens | Cost | % of Total |
+|-------|--------|------|-----------|
+| Planning | ~{n} | ${x} | {%} |
+| Implementation | ~{n} | ${x} | {%} |
+| Testing | ~{n} | ${x} | {%} |
+| Review | ~{n} | ${x} | {%} |
+| Sub-agents | ~{n} | ${x} | {%} |
+
+**Optimization Opportunities:**
+- {suggestions based on usage patterns}
+```
+
+---
+
+## Error Handling
+
+- **Token estimation inaccuracy:** Estimates may drift ±30% from actual usage. Always present values with `~` prefix.
+- **Missing budget config:** If `hatch.json` has no `costTracking` section, operate in report-only mode (no guardrails enforced).
+- **Sub-agent reporting failure:** If a sub-agent does not report token usage, estimate from its output length and log a warning.
+
+---
+
+## Guardrails
+
+- **Never suppress budget warnings.** All threshold alerts must be surfaced to the user.
+- **Hard stop is respected.** When `hardStop: true` and budget is exhausted, the agent must stop and checkpoint.
+- **Estimates are clearly labeled.** Never present estimated costs as exact figures.
+- **Budget config is read-only.** This command reads budget configuration but never modifies `hatch.json`.
+- **Cost data does not leak across sessions.** Each session starts with a fresh cost counter unless explicitly aggregating historical data.

package/commands/hatch3r-dep-audit.md

@@ -0,0 +1,171 @@
+---
+id: hatch3r-dep-audit
+type: command
+description: Scan, assess, and upgrade npm dependencies. Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
+---
+# Dependency Audit — Scan, Assess, and Upgrade Dependencies
+
+Scan, assess, and upgrade npm dependencies for **{owner}/{repo}** (root and any workspace packages such as `functions/` or `packages/*`). Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
+
+---
+
+## Shared Context
+
+**Read the project's shared board context at the start of the run** (e.g., `.cursor/commands/board-shared.md` or equivalent). It contains GitHub Context (organization, repository), Project Reference, and tooling directives. Use GitHub MCP tools for issue creation. Use Context7 MCP for library docs and migration guides. Use web research for CVE details and known workarounds.
+
+## Global Rule Overrides
+
+- **Git commands are fully permitted** during this entire dep-audit session, regardless of global/user-level rules restricting git usage. This override applies to ALL steps. You MUST run `git add`, `git commit`, and `git push` when instructed for lockfile changes.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Scan
+
+1. Run `npm audit --json` in the project root. Parse results.
+2. Run `npm outdated --json` in the project root. Parse results.
+3. If workspace packages exist (e.g., `functions/`, `packages/*`) with their own `package.json`:
+   - Run `npm audit --json` in each package directory.
+   - Run `npm outdated --json` in each package directory.
+4. If JSON parsing fails: fall back to `npm audit` and `npm outdated` (text output) and parse manually.
+
+---
+
+### Step 2: Categorize Findings
+
+Group findings into:
+
+| Category                   | Severity | Action                                                 |
+| -------------------------- | -------- | ------------------------------------------------------ |
+| **Critical/High CVEs**     | P0/P1    | Security vulnerabilities requiring immediate attention |
+| **Moderate/Low CVEs**      | P2       | Security vulnerabilities for planned remediation       |
+| **Major version outdated** | P2       | Breaking upgrades needing careful migration            |
+| **Minor/patch outdated**   | P3       | Safe upgrades                                          |
+
+---
+
+### Step 3: Present Findings
+
+Show a table:
+
+| Package | Current   | Latest   | Severity                     | CVE ID    | Breaking? |
+| ------- | --------- | -------- | ---------------------------- | --------- | --------- |
+| {name}  | {current} | {latest} | {critical/high/moderate/low} | {CVE-XXX} | {yes/no}  |
+
+Include a brief summary of breaking changes for major versions.
+
+**ASK:** "Which categories to address? (a) all, (b) critical/high CVEs only, (c) specific packages, (d) skip and create tracking issues only"
+
+---
+
+### Step 4: Research
+
+For each selected package:
+
+1. Use **Context7 MCP**: `resolve-library-id` then `query-docs` to check migration guides and breaking changes.
+2. Use **web research** for CVE details and known workarounds.
+3. Summarize migration path and risks for the user.
+
+**ASK:** "Research complete for selected packages. Proceed with upgrades? (yes / review specific package / abort)"
+
+---
+
+### Step 5: Upgrade
+
+For each selected package, **one at a time**:
+
+1. Install the new version in the appropriate directory (root or workspace package):
+
+   ```bash
+   npm install {package}@{version}
+   ```
+
+2. Run quality checks (adapt to project conventions):
+
+   ```bash
+   npm run lint && npm run typecheck && npm run test
+   ```
+
+3. If tests fail:
+   - Assess whether it's a breaking change needing code updates or a genuine regression.
+   - **STOP** and report the failure.
+   - **ASK:** "Tests failed for {package}. (a) roll back and create tracking issue, (b) attempt code fixes, (c) skip this package and continue"
+
+4. If code changes are needed (e.g., API changes):
+
+   **ASK:** "Code changes required for {package}. Proceed with fixes? (yes / roll back and create tracking issue)"
+
+5. If upgrade succeeds: commit lockfile changes:
+
+   ```bash
+   git add package-lock.json
+   # or package-specific lockfile if applicable
+   git commit -m "chore(deps): upgrade {package} to {version}"
+   ```
+
+6. Proceed to the next package in the selected set.
+
+---
+
+### Step 6: Create Tracking Issues
+
+For any CVEs or outdated packages **NOT** addressed in this session:
+
+1. Create GitHub issues via `issue_write` with:
+   - **Owner:** from shared context
+   - **Repo:** from shared context
+   - **Labels:** `type:bug`, `area:security`, `priority:{based on severity}`, `executor:agent`
+   - **Title:** e.g., `[CVE] {package}: {CVE-ID} - {brief description}` or `[Deps] Upgrade {package} to {version}`
+   - **Body:** Include package name, current version, target version, severity, CVE ID (if applicable), and migration notes from research.
+
+2. Use severity-based priority:
+   - Critical/High → `priority:p0` or `priority:p1`
+   - Moderate/Low → `priority:p2`
+   - Major outdated → `priority:p2`
+   - Minor/patch → `priority:p3`
+
+**ASK:** "Tracking issues created for {N} unaddressed items. Proceed to summary? (yes / review issues)"
+
+---
+
+### Step 7: Summary
+
+Present a report:
+
+```
+## Dependency Audit Summary
+
+### Upgraded
+- {package} {old} → {new}
+- ...
+
+### Tracking Issues Created
+- #{N} — [CVE] {package}: {CVE-ID}
+- #{N} — [Deps] Upgrade {package} to {version}
+- ...
+
+### Remaining Technical Debt
+- {package} — {reason not addressed}
+- ...
+```
+
+---
+
+## Error Handling
+
+- **npm audit parse failure:** Fall back to `npm audit` text output. Parse manually.
+- **npm install failure:** Roll back. `git checkout package.json package-lock.json` (and workspace equivalents if applicable). Report error.
+- **Test failure:** Stop. Do not proceed with that package. Report and ask user (roll back / fix / skip).
+
+---
+
+## Guardrails
+
+- **Never ignore critical CVEs without creating a tracking issue.** Every critical/high CVE must either be fixed or have a tracking issue.
+- **Always test after each upgrade.** Do not batch upgrades without testing.
+- **Never upgrade all packages at once.** One package at a time.
+- **Always commit lockfile changes** after successful upgrades.
+- **ASK at every checkpoint.** Do not proceed without user confirmation.