hatch3r 1.0.0

package/commands/hatch3r-hooks.md

@@ -0,0 +1,282 @@
+---
+id: hatch3r-hooks
+type: command
+description: Define and manage event-driven hooks that activate agents on project events
+---
+# Hooks — Event-Driven Agent Activation
+
+Define, edit, and manage event-driven hooks that automatically activate hatch3r agents when specific project events occur. Hook definitions are tool-agnostic — the adapter pipeline translates them into tool-native configurations during `npx hatch3r sync`.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Discover Current State
+
+1. Check `/.agents/hooks/` for existing hook definition files (`.md` files with frontmatter).
+2. Read `/.agents/hatch.json` for configured tools and features.
+3. List existing hooks with their event, agent, and conditions.
+
+Present the current state:
+
+```
+Current Hooks: {list with id, event, agent — or "none"}
+Configured Tools: {tools from hatch.json}
+Hooks Feature: {enabled/disabled}
+```
+
+**ASK:** "Current hooks: {list or 'none'}. Tools: {list}. What would you like to do? (a) Add a new hook, (b) Edit existing hook, (c) Remove a hook, (d) List all hooks, (e) Sync hooks to tools"
+
+---
+
+### Step 2: Define Hook
+
+For adding a new hook:
+
+#### 2a. Select Event
+
+Present available events with descriptions:
+
+| Event | Description | Use Cases |
+|-------|-------------|-----------|
+| `pre-commit` | Triggered before a commit is created | Lint checks, secret scanning, test running |
+| `post-merge` | Triggered after a branch merge | Dependency updates, migration checks, notification |
+| `ci-failure` | Triggered when CI/CD pipeline fails | Auto-diagnosis, fix suggestions |
+| `file-save` | Triggered when a file is saved | Auto-formatting, auto-testing, live validation |
+| `session-start` | Triggered when a new coding session starts | Context loading, status checks |
+| `pre-push` | Triggered before pushing to remote | Full test suite, build verification |
+| `pre-implementation` | Triggered before implementing a sub-issue | Context loading, spec review, learning consultation |
+| `post-implementation` | Triggered after implementing a sub-issue | Learning capture, code quality check, doc updates |
+| `pre-review` | Triggered before code review starts | Checklist generation, context preparation |
+| `post-review` | Triggered after code review completes | Fix tracking, learning capture, approval notifications |
+| `pre-release` | Triggered before a release workflow | Changelog verification, version validation, dependency audit |
+| `post-release` | Triggered after a release completes | Monitoring setup, notification, deploy verification |
+| `pre-test` | Triggered before test execution | Test environment setup, fixture preparation |
+| `post-test` | Triggered after test execution completes | Coverage reporting, flaky test detection, result analysis |
+| `on-error` | Triggered when any workflow step fails | Error diagnosis, auto-retry, escalation, incident logging |
+| `on-context-switch` | Triggered when agent context is refreshed or delegated | State persistence, handoff documentation |
+| `on-dependency-change` | Triggered when dependencies are added/updated/removed | Security audit, compatibility check, license validation |
+| `on-security-finding` | Triggered when a security issue is discovered | Alert escalation, auto-fix suggestions, incident creation |
+
+**ASK:** "Select an event for this hook."
+
+#### 2b. Select Agent
+
+Present available hatch3r agents:
+
+- `lint-fixer` — Automatic lint error resolution
+- `test-writer` — Test generation for new or changed code
+- `reviewer` — Code review and quality checks
+- `security-auditor` — Security vulnerability scanning
+- `ci-watcher` — CI/CD pipeline monitoring and diagnosis
+- `a11y-auditor` — Accessibility compliance checks
+- `perf-profiler` — Performance analysis and optimization
+- `dependency-auditor` — Dependency security and update checks
+- `docs-writer` — Documentation generation and updates
+
+If the user wants a custom agent name not in this list, accept it but warn that the agent must exist in `/.agents/agents/`.
+
+**ASK:** "Select an agent to activate when this event fires."
+
+#### 2c. Define Conditions (Optional)
+
+- **Glob patterns:** Which files trigger this hook (e.g., `src/**/*.ts`, `*.css`)
+- **Branch patterns:** Which branches (e.g., `main`, `release/*`)
+
+**ASK:** "Add conditions? (glob patterns, branch patterns, or skip for 'always activate')"
+
+#### 2d. Write Hook Definition File
+
+Generate the hook definition file at `/.agents/hooks/{event}-{agent-short-name}.md`:
+
+```markdown
+---
+id: {event}-{agent-short-name}
+type: hook
+event: {selected-event}
+agent: {selected-agent}
+description: {user-provided or auto-generated description}
+globs: {comma-separated glob patterns, if any}
+branches: {comma-separated branch patterns, if any}
+---
+# Hook: {event} → {agent}
+
+{Description of what this hook does and when it activates.}
+
+## Activation
+
+- **Event:** {event}
+- **Agent:** {agent}
+- **Conditions:** {glob patterns, branch patterns, or "always"}
+
+## Tool-Specific Behavior
+
+- **Claude Code:** For session-start → SessionStart. For pre-commit, post-merge, ci-failure, file-save, pre-push: no native mapping — adapter may use no-op or alternative strategy (see mapping note below).
+- **Cursor:** Maps to glob-based rule activation in `.cursor/rules/`
+- **Others:** Hook definition stored; sync when adapter support is added
+```
+
+Claude Code event mapping: **Claude Code's native hook events (PreToolUse, PostToolUse, SubagentStart, SessionStart) are tool-lifecycle events and do NOT map to git/project events.** PreToolUse fires before every tool call; PostToolUse fires after every tool completes; SubagentStart fires when a subagent spawns. Only `session-start` → `SessionStart` is semantically correct. For pre-commit, post-merge, ci-failure, file-save, and pre-push, the Claude Code adapter may use a no-op or alternative strategy (e.g., Cursor rules) — do not map these to PreToolUse/PostToolUse/SubagentStart, as that would cause hooks to fire on every tool invocation instead of the intended event.
+
+**ASK:** "Hook definition: {summary}. Create? (yes / adjust / cancel)"
+
+---
+
+### Step 3: Edit Existing Hook
+
+For editing an existing hook:
+
+1. List all hooks and ask which to edit.
+2. Show current definition.
+3. Ask what to change (event, agent, conditions, description).
+4. Update the hook file in `/.agents/hooks/`.
+
+**ASK:** "Updated hook: {summary}. Save? (yes / revert / cancel)"
+
+---
+
+### Step 4: Remove a Hook
+
+1. List all hooks and ask which to remove.
+2. Show the hook definition.
+
+**ASK:** "Remove hook '{id}'? This will delete `/.agents/hooks/{filename}`. (yes / cancel)"
+
+3. Delete the file. Warn that tool-specific generated files (e.g., `.cursor/rules/hatch3r-hook-*.mdc`) will be cleaned up on the next `npx hatch3r sync`.
+
+---
+
+### Step 5: Sync Hooks to Tools
+
+1. Read all hook definitions from `/.agents/hooks/`.
+2. For each configured tool in `hatch.json`, describe what will be generated:
+   - **Claude Code:** Hook documentation appended to managed section of `CLAUDE.md`
+   - **Cursor:** Glob-based `.mdc` rule files in `.cursor/rules/hatch3r-hook-*.mdc`
+   - **Others:** No-op (hook definitions stored for future adapter support)
+3. Present the list of files that will be generated/updated.
+
+**ASK:** "Hooks will generate these files: {list}. Run `npx hatch3r sync` to apply. (understood / sync now)"
+
+If user chooses "sync now", instruct them to run `npx hatch3r sync` in the terminal.
+
+---
+
+## Custom Events
+
+Define project-specific hook events beyond the built-in types:
+
+- **Event naming**: `custom:{domain}:{action}` (e.g., `custom:billing:subscription-change`)
+- **Event registration**: Add custom events to `hatch.json` under `hooks.customEvents`
+- **Event triggering**: Agents trigger custom events via `emit-hook custom:{name}` in their workflows
+- **Event payload**: Custom events can pass structured data to hook handlers via JSON payload
+
+### Custom Event Definition
+
+In `hatch.json`:
+
+```json
+{
+  "hooks": {
+    "customEvents": [
+      {
+        "name": "custom:billing:subscription-change",
+        "description": "Fired when a subscription plan changes",
+        "payload": { "userId": "string", "oldPlan": "string", "newPlan": "string" }
+      }
+    ]
+  }
+}
+```
+
+Custom events follow the same hook definition format as built-in events — create a hook file in `/.agents/hooks/` with `event: custom:{domain}:{action}`.
+
+---
+
+## Hook Chaining
+
+Hooks can trigger other hooks in sequence:
+
+- **Chain definition**: Define ordered hook chains in `hatch.json` under `hooks.chains`
+- **Execution order**: Hooks in a chain execute sequentially; failure in any hook stops the chain
+- **Error handling**: Chain-level error handlers can catch and handle failures from individual hooks
+- **Conditional chaining**: Hooks can conditionally trigger next hook based on output (pass/fail/skip)
+
+### Chain Definition
+
+In `hatch.json`:
+
+```json
+{
+  "hooks": {
+    "chains": [
+      {
+        "id": "pre-release-pipeline",
+        "description": "Full pre-release validation chain",
+        "steps": [
+          { "hook": "pre-release-security-auditor", "on_fail": "stop" },
+          { "hook": "pre-release-test-writer", "on_fail": "stop" },
+          { "hook": "pre-release-docs-writer", "on_fail": "warn" }
+        ],
+        "on_error": "notify"
+      }
+    ]
+  }
+}
+```
+
+Chains are triggered by referencing the chain ID as the hook target. Individual hook results (`pass`, `fail`, `skip`) determine whether the chain continues.
+
+---
+
+## Hook Execution Ordering
+
+When multiple hooks are registered for the same event:
+
+- **Priority**: Hooks have a priority field (1-100, lower runs first, default 50)
+- **Parallel vs Sequential**: Hooks at the same priority level run in parallel; different priority levels run sequentially
+- **Timeout**: Each hook has a configurable timeout (default 30 seconds). Timed-out hooks are reported as failures.
+- **Isolation**: Each hook runs in its own context. Hook outputs are collected but don't affect other hooks unless chained.
+
+### Priority Configuration
+
+Add `priority` and `timeout` to hook frontmatter:
+
+```markdown
+---
+id: pre-commit-lint-fixer
+type: hook
+event: pre-commit
+agent: lint-fixer
+priority: 10
+timeout: 60
+---
+```
+
+### Execution Example
+
+For `pre-commit` with three hooks:
+1. `lint-fixer` (priority 10) — runs first
+2. `security-auditor` (priority 20) — runs second
+3. `test-writer` (priority 50) and `reviewer` (priority 50) — run in parallel, third
+
+---
+
+## Error Handling
+
+- `/.agents/hooks/` doesn't exist: create it automatically.
+- Invalid event type: warn and show the valid events table.
+- Agent not found in `/.agents/agents/`: warn but allow (agent may be added later).
+- Adapter doesn't support hooks: generate hook definition file anyway, warn that sync for that tool is a no-op.
+- Duplicate hook ID: warn and ask the user to choose a different name or overwrite.
+
+## Guardrails
+
+- **Never skip ASK checkpoints.**
+- Hook definitions are tool-agnostic — the adapters handle translation.
+- Never delete hook files without explicit user confirmation.
+- Always validate event names against the known events list.
+- Hook IDs must be unique across all hook definitions.
+- The command creates hook DEFINITIONS only — actual hook registration happens via `npx hatch3r sync`.
+- Do not modify adapter output files directly — they are managed by the sync pipeline.

package/commands/hatch3r-learn.md

@@ -0,0 +1,217 @@
+---
+id: hatch3r-learn
+type: command
+description: Capture learnings from development sessions into reusable knowledge files for future consultation.
+---
+# Learning Capture -- Extract and Store Development Insights
+
+Capture learnings from completed development sessions. Can be invoked manually after finishing work, automatically by board-pickup after PR merge, or with a specific issue number for targeted reflection.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Gather Learning Context
+
+1. Check what was recently completed:
+   - If invoked with an issue number: read the issue, its PR, and changes via `gh issue view` and `gh pr list --search`.
+   - If invoked standalone: **ASK** the user what they just completed.
+   - If invoked from board-pickup: use the issue/PR context already available.
+2. Scan recent git history for context (`git log --oneline -20` on the current branch).
+
+**ASK:** "What did you just complete? {auto-detected context}. Confirm or provide additional details."
+
+### Step 2: Extract Learnings
+
+1. Identify learnings in these categories:
+   - **Pattern Discovered**: A reusable approach that worked well.
+   - **Pitfall Encountered**: Something that caused problems or wasted time.
+   - **Decision Made**: An architectural or design decision with rationale.
+   - **Tool/Library Insight**: Something learned about a tool or library.
+   - **Process Improvement**: A workflow improvement suggestion.
+
+2. For each learning, capture:
+   - What happened (context).
+   - What was learned.
+   - When this applies in the future (trigger conditions).
+
+**ASK:** "I identified these learnings: {list}. Add, remove, or adjust any? Confirm to save."
+
+### Step 3: Write Learning Files
+
+For each confirmed learning, create a file in `/.agents/learnings/`.
+
+If `/.agents/learnings/` does not exist, create it.
+
+**Filename:** `{YYYY-MM-DD}_{short-slug}.md`
+
+**Content format:**
+
+```markdown
+---
+id: {short-slug}
+date: {YYYY-MM-DD}
+source-issue: #{issue-number}  # or "manual" if standalone
+category: pattern | pitfall | decision | tool-insight | process
+tags: [{area-labels}, {tech-stack-tags}]
+area: {module/subsystem affected}
+---
+## Context
+
+{What was being done when this learning occurred}
+
+## Learning
+
+{The actual insight -- what was learned}
+
+## Applies When
+
+{Future trigger conditions -- when should this learning be consulted}
+
+## Evidence
+
+{Links to relevant code, PRs, issues, or files}
+```
+
+**Guardrails for learning files:**
+- Never overwrite existing learning files.
+- If a duplicate learning is detected (similar to an existing file), **ASK** whether to merge or create separate.
+- Learnings must be specific and actionable, not generic advice.
+- Always include the "Applies When" section -- learnings without trigger conditions are not useful.
+- Tags should use the same vocabulary as the project's area labels.
+- Keep learnings concise -- max ~20 lines per learning file body.
+
+### Step 4: Summary
+
+Present all saved learnings with file paths.
+
+```
+Learnings Captured:
+  /.agents/learnings/{filename1}.md -- {category}: {one-line summary}
+  /.agents/learnings/{filename2}.md -- {category}: {one-line summary}
+```
+
+Remind user that these will be auto-consulted during future board-pickup and board-fill runs.
+
+---
+
+## Learning Lifecycle
+
+### Expiry & Deprecation
+- Learnings have an optional `expires` field (ISO date). Expired learnings are flagged during `hatch3r status`.
+- Learnings can be marked `deprecated: true` with a `superseded_by` reference to a newer learning.
+- During `hatch3r sync`, expired/deprecated learnings are moved to an `archived/` subdirectory (not deleted).
+- Quarterly review: agents prompt for learning review when > 50 active learnings exist.
+
+### Confidence Levels
+- `proven` — validated across multiple implementations
+- `experimental` — worked once, needs more validation
+- `hypothesis` — untested assumption, use with caution
+
+### Lifecycle Frontmatter Fields
+
+```markdown
+---
+id: {short-slug}
+date: {YYYY-MM-DD}
+source-issue: #{issue-number}
+category: pattern | pitfall | decision | tool-insight | process
+tags: [{area-labels}, {tech-stack-tags}]
+area: {module/subsystem affected}
+confidence: proven | experimental | hypothesis
+expires: {YYYY-MM-DD}          # optional
+deprecated: false               # set true to deprecate
+superseded_by: {learning-id}    # reference when deprecated
+---
+```
+
+### Archival
+
+Archived learnings are moved to `/.agents/learnings/archived/` with their original filename. An archival notice is prepended:
+
+```markdown
+> **Archived on {date}**: {reason — expired | deprecated | superseded by {id}}
+```
+
+---
+
+## Search & Discovery
+
+### Tag System
+- Learnings are tagged with categories: `performance`, `security`, `ux`, `architecture`, `testing`, `deployment`, `debugging`, `patterns`
+- Tags are defined in the learning frontmatter: `tags: [performance, caching]`
+- Agents search learnings by tag when starting relevant work (e.g., performance audit consults `performance`-tagged learnings)
+
+### Search Interface
+- `hatch3r learn search {query}` — full-text search across learning titles and content
+- `hatch3r learn list --tag={tag}` — filter by tag
+- `hatch3r learn list --status={active|deprecated|expired}` — filter by lifecycle status
+- `hatch3r learn list --recent` — show learnings added in last 30 days
+
+### Search Output Format
+
+```
+Learnings matching "{query}":
+  [{confidence}] {title} ({date}, tags: {tags})
+    /.agents/learnings/{filename}.md
+    Applies when: {trigger summary}
+```
+
+### Agent Auto-Consultation
+
+During `board-pickup` and `board-fill`, agents automatically consult learnings by:
+1. Matching area labels from the issue to learning tags
+2. Filtering to `active` status only (not expired/deprecated)
+3. Sorting by confidence (`proven` first) then by date (newest first)
+4. Presenting top 5 relevant learnings in the implementation context
+
+---
+
+## Learning Quality
+
+### Required Fields
+Every learning must include:
+- `title` — concise summary (< 80 chars)
+- `context` — when this learning applies
+- `insight` — what was learned
+- `evidence` — how it was validated (PR link, test result, metric)
+- `tags` — at least one category tag
+
+### Validation
+- Learnings without `evidence` are automatically tagged `hypothesis`
+- Learnings referenced in 3+ implementations are auto-promoted to `proven`
+- Learnings contradicted by newer evidence are flagged for review
+
+### Quality Checks During Step 3
+
+When writing learning files, validate:
+1. Title is under 80 characters
+2. At least one tag is present and matches project vocabulary
+3. "Applies When" section has specific trigger conditions (not vague)
+4. Evidence is present — if not, set `confidence: hypothesis` and warn the user
+5. Content does not duplicate an existing active learning (fuzzy match on title + tags)
+
+---
+
+## Error Handling
+
+- `/.agents/learnings/` directory doesn't exist: create it silently.
+- `/.agents/learnings/archived/` directory doesn't exist: create it when first archival occurs.
+- Duplicate learning detected: warn and **ASK** whether to merge or create separate.
+- No learnings identified: **ASK** user directly what they learned. If still nothing, skip silently.
+- Learning exceeds quality thresholds: warn user with specific violations and suggest fixes.
+- Search returns no results: suggest broader search terms or list all available tags.
+
+## Guardrails
+
+- **Never skip ASK checkpoints.**
+- **Never overwrite existing learning files.**
+- **Never delete learnings.** Use archival (move to `archived/`) instead of deletion.
+- **Learnings must be specific and actionable.** Reject generic advice like "write better tests."
+- **Always include trigger conditions** in the "Applies When" section.
+- **Tags must match project vocabulary** -- use area labels from `/.agents/hatch.json`.
+- **Max ~20 lines per learning** file body (excluding frontmatter).
+- **Learnings without evidence must be `hypothesis`.** Do not allow `proven` or `experimental` without evidence.
+- **Expired learnings are archived, not deleted.** Preserve institutional knowledge.

package/commands/hatch3r-migration-plan.md

@@ -0,0 +1,51 @@
+---
+id: hatch3r-migration-plan
+type: command
+description: Create a phased migration plan for a major dependency or framework upgrade. Analyzes breaking changes and produces an actionable plan with rollback procedures.
+---
+# Migration Plan Generator
+
+## Inputs
+
+- **Migration target:** dependency name and target version, or framework/platform change description
+- **Current version:** auto-detected from lockfile or specified manually
+- **Scope:** `full` (default) or `assessment-only` (just the analysis, no plan)
+
+## Procedure
+
+1. **Detect current state:**
+   - Read `package.json`, lockfile, or equivalent for current version
+   - Identify all direct and transitive dependents of the migration target
+   - Count usage sites in the codebase (imports, API calls)
+
+2. **Research breaking changes:**
+   - Read the changelog/release notes between current and target versions
+   - Use web research for migration guides, known issues, and community solutions
+   - Identify deprecated APIs, removed features, and behavioral changes
+
+3. **Impact analysis:**
+   - Map each breaking change to affected files in the codebase
+   - Classify impact: `trivial` (find-replace), `moderate` (logic change), `significant` (architectural change)
+   - Estimate effort per change (hours)
+   - Identify risk areas (data loss potential, security implications, performance impact)
+
+4. **Generate phased plan:**
+   - Phase 0: Preparation (add compatibility shims, increase test coverage on affected areas)
+   - Phase 1: Non-breaking updates (update config, add new imports alongside old)
+   - Phase 2: Migrate consumers (update code to use new APIs)
+   - Phase 3: Remove old code (delete shims, deprecated usage, old dependencies)
+   - Each phase includes: files to change, validation criteria, rollback steps
+
+5. **Output the plan** as a markdown document or GitHub issue(s).
+
+## Output
+
+- Migration assessment with breaking change inventory
+- Phased migration plan with effort estimates
+- Rollback procedure for each phase
+- Checklist of validation steps
+
+## Related
+
+- **Skill:** `hatch3r-migration` — execution workflow for the plan
+- **Skill:** `hatch3r-dep-audit` — dependency health check

package/commands/hatch3r-onboard.md

@@ -0,0 +1,56 @@
+---
+id: hatch3r-onboard
+type: command
+description: Generate an onboarding guide for a new developer joining the project. Covers setup, architecture, conventions, and key workflows.
+---
+# Onboarding Guide Generator
+
+## Inputs
+
+- **Role:** `frontend`, `backend`, `fullstack`, or `general` (default)
+- **Output:** `markdown` (default) or `issue` (create GitHub issue with guide)
+
+## Procedure
+
+1. **Project overview:**
+   - Read `package.json` (or equivalent) for project name, description, tech stack
+   - Read `README.md` for existing setup instructions
+   - Read `.agents/AGENTS.md` for agent architecture overview
+   - Summarize: what the project does, who uses it, primary tech stack
+
+2. **Development setup:**
+   - Detect package manager and runtime (Node, Python, Go, etc.)
+   - List prerequisites: runtime version, system dependencies, required tools
+   - Generate exact setup commands: clone, install, configure environment, run
+   - Include `.env.example` setup instructions if present
+   - Verify the setup works by listing the build/test commands
+
+3. **Architecture walkthrough:**
+   - Map the directory structure with purpose of each top-level directory
+   - Identify the main entry points (API server, CLI, web app)
+   - Document the data flow for a typical request/operation
+   - List key dependencies and their roles
+
+4. **Conventions and standards:**
+   - Read `.agents/rules/` for coding standards
+   - Summarize branch naming, commit message, and PR conventions
+   - Document the testing strategy (unit, integration, e2e) and how to run tests
+   - List available scripts/commands from the project's task runner
+
+5. **Key workflows:**
+   - How to create a feature branch and open a PR
+   - How to run the CI pipeline locally
+   - How to deploy (if applicable)
+   - Who to ask for help and where to find documentation
+
+6. **Generate the guide** as a single markdown document organized by section.
+
+## Output
+
+- Onboarding guide markdown document
+- Quick-reference cheat sheet (common commands, file locations, contacts)
+
+## Related
+
+- **Agent:** `hatch3r-docs-writer` — for maintaining documentation
+- **Skill:** `hatch3r-feature` — standard feature development workflow