hatch3r 1.0.0 → 1.2.0

package/commands/hatch3r-quick-change.md

@@ -0,0 +1,336 @@
+---
+id: hatch3r-quick-change
+type: command
+description: Lightweight command for small changes not worth tracking on the board. Adaptive ceremony with inline or sub-agent implementation, batch support, and soft scope guards.
+tags: [core, implementation]
+---
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Scale Assessment | Orchestrator (inline) | No | Yes |
+| 2. Implementation | `hatch3r-implementer` (nontrivial items) | Per item | Nontrivial only |
+| 3. Lint Fix | `hatch3r-lint-fixer` | No | When lint/type errors |
+| 4a. Review Loop | `hatch3r-reviewer` -> `hatch3r-fixer` (max 3 iterations) | No (sequential) | Nontrivial only |
+| 4b. Final Quality | `hatch3r-test-writer` + `hatch3r-security-auditor` | Yes | Nontrivial code changes |
+
+## Browser Automation
+
+At the start of this command, ask the user once:
+
+> "Would you like to enable browser verification for this session? This uses Playwright to test changes in the running application."
+
+If **yes**: implementation and review stages include browser verification steps — navigate to affected pages, interact with changed elements, check console for errors, capture screenshots.
+
+If **no**: all browser verification steps are skipped silently throughout the entire command.
+
+# Quick Change -- Fast Path for Small, Board-Free Changes
+
+Lightweight command for changes not worth tracking as board issues -- typo fixes, constant tweaks, small refactors, config updates, documentation edits. Adaptive ceremony: trivial changes are implemented inline; nontrivial changes delegate to the implementer agent with a light review. Supports batching multiple small changes into a single invocation and commit.
+
+Sits alongside `hatch3r-workflow` as a lower-ceremony alternative. If a change grows beyond quick-change territory, the command recommends switching to `hatch3r-workflow`.
+
+---
+
+## Scope
+
+This command intentionally skips:
+- Board context (`hatch3r-board-shared`)
+- GitHub issues and PRs
+- Researcher sub-agent
+- Full review pipeline (security-auditor, test-writer, docs-writer)
+- Learnings capture
+
+It retains:
+- Quality checks (lint, typecheck, test) -- always mandatory
+- Adaptive sub-agent delegation (implementer for nontrivial items)
+- Light code review (reviewer for nontrivial items only)
+- `scope: always` rules from `.agents/rules/`
+- Soft scope guards to prevent misuse
+
+---
+
+## Global Rule Overrides
+
+- **Git commands are fully permitted** during Step 7 (Git Action), including `git add`, `git commit`, and `git push`.
+
+## Token-Saving Directives
+
+1. **No shared context loading.** Do NOT read `hatch3r-board-shared`. Do NOT fetch GitHub issues or PRs.
+2. **Minimal researcher usage.** No researcher for Tier 1 items. For Tier 2 items that proceed through quick-change, only `similar-implementation` at `quick` depth. Tier 3 items must be routed to `hatch3r-workflow`.
+3. **Targeted file reads only.** Read only files directly relevant to the described change(s).
+4. **No learnings capture.** Quick changes are too small to produce meaningful learnings.
+5. **Minimal rule loading.** Load `scope: always` rules only when spawning sub-agents in Steps 4b or 6.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Input and Batch Parsing
+
+Parse the user's description into discrete change items.
+
+1. Extract each distinct change from the user's message. A single description may contain multiple changes (e.g., "rename this constant, fix that typo, and update the config default").
+2. For each change item, record:
+   - **Description**: what needs to change
+   - **Type**: fix / tweak / refactor / config / docs
+   - **Affected area**: inferred file paths or directories
+3. If the user describes a single change, treat it as a batch of one.
+
+---
+
+### Step 2: Scale Assessment (Soft Guard)
+
+Evaluate whether the described changes fit the quick-change scope.
+
+#### 2a. Estimate Scope
+
+For each change item, estimate:
+- Number of files affected
+- Approximate lines changed
+- Whether it touches security-sensitive areas (auth, payments, database schemas, access control)
+- Whether it introduces new dependencies or modules
+
+Aggregate across the batch for total estimated scope.
+
+#### 2b. Apply Soft Guard and Complexity Scoring
+
+**Score complexity** per the `hatch3r-deep-context` rule for the overall change (or each item individually if items are unrelated). Determine the analysis tier (Light / Standard / Deep).
+
+**Hard block — Tier 3 (Deep):** If any item scores Tier 3, quick-change is not appropriate.
+
+**ASK:** "This change scores Tier 3 (Deep complexity): {reason}. Quick-change does not provide the research depth needed. Options: (a) switch to `hatch3r-workflow`, (b) narrow the scope."
+
+Do NOT offer a "proceed anyway" option for Tier 3. The user must switch to workflow or narrow scope.
+
+**Soft guard — Tier 2 (Standard) or threshold triggers:** If any item scores Tier 2, or if any of these threshold triggers fire (any one is sufficient):
+- Estimated total exceeds **5 files**
+- Estimated total exceeds **~200 lines changed**
+- Changes touch security-sensitive areas
+- Changes require new dependencies or architectural decisions
+
+**ASK:** "This looks larger than a quick change: {reason}. Options: (a) proceed with lightweight research, (b) switch to `hatch3r-workflow` for full ceremony, (c) narrow the scope."
+
+If no threshold is triggered and all items are Tier 1, present the change list:
+
+```
+Quick Change Scope:
+  Items: {N}
+  1. {description} — {type} — {affected area}
+  2. ...
+  Estimated scope: {N} files, ~{N} lines
+```
+
+**ASK:** "Proceed with these changes? (yes / adjust)"
+
+---
+
+### Step 3: Classify Each Change Item
+
+Classify each item to determine the implementation path.
+
+#### Trivial Signals (inline implementation)
+
+- Single-file change
+- Config value update
+- Typo or comment fix
+- Import reordering or fix
+- Constant rename or value change
+- Single-line logic correction
+- Documentation text edit
+- Environment variable update
+
+#### Nontrivial Signals (implementer sub-agent)
+
+- Multiple files affected
+- New function, method, or module
+- Behavior change requiring test updates
+- Cross-module refactor
+- API signature change
+- Logic branch addition or removal
+
+Classify each item as **trivial** or **nontrivial**. If ambiguous, default to **nontrivial**.
+
+---
+
+### Step 4: Implementation (Adaptive)
+
+Implement each change item using the path determined by its classification.
+
+#### 4a. Trivial Items -- Inline Implementation
+
+For each trivial item:
+
+1. Read the target file.
+2. Make the change directly.
+3. Verify the file is syntactically valid (no broken imports, no parse errors).
+
+No sub-agent delegation. No researcher. Implement and move on.
+
+#### 4b. Nontrivial Items -- Implementer Sub-Agent
+
+For each nontrivial item (or group of related nontrivial items):
+
+1. Read `scope: always` rules from `.agents/rules/`.
+
+2. **Lightweight research (Tier 2 items only):** If the item scored Tier 2 in Step 2b and the user chose to proceed with lightweight research, spawn a `hatch3r-researcher` sub-agent with:
+   - **Modes:** `similar-implementation` at `quick` depth (1 reference implementation)
+   - **Research brief:** The change description and affected files.
+   - Await the result. Pass the output (reference conventions) to the implementer prompt in step 3.
+
+3. Spawn a `hatch3r-implementer` sub-agent via the Task tool (`subagent_type: "generalPurpose"`).
+
+The implementer prompt MUST include:
+- The change description and affected files.
+- All `scope: always` rule directives.
+- Explicit instruction: do NOT create branches, commits, or PRs.
+- **Reference conventions** from `similar-implementation` output (if step 2 ran) — triggers the implementer's Convention Lock step.
+- If no researcher ran: explicit instruction that no researcher context is available; work from the change description and codebase alone.
+
+If multiple nontrivial items affect **independent areas** (no shared files), spawn one implementer per area and run them in parallel.
+
+If multiple nontrivial items affect **overlapping files**, process them sequentially through a single implementer to avoid conflicts.
+
+4. Await the implementer result. If the implementer reports BLOCKED, **ASK** the user for guidance.
+
+---
+
+### Step 5: Quality Checks
+
+Run the project's quality gates. Refer to `package.json` scripts, `README.md`, or project conventions for the appropriate commands.
+
+#### 5a. Run Checks
+
+1. Lint (e.g., `npm run lint`)
+2. Type check (e.g., `npm run typecheck`)
+3. Test suite (e.g., `npm run test`)
+
+#### 5b. Handle Failures
+
+- **Simple failures** (unused import, formatting): fix inline.
+- **Lint/type failures requiring structured fixes**: spawn `hatch3r-lint-fixer` sub-agent with the specific errors.
+- **Test failures**: analyze the failure. If the change intentionally altered behavior and the test needs updating, update it. If the change broke something unintentionally, fix the change.
+
+Max 2 retry loops on quality check failures. After 2 retries:
+
+**ASK:** "Quality checks still failing after 2 fix attempts: {specific failures}. Options: (a) I'll fix manually, commit what we have, (b) keep trying, (c) abort changes."
+
+---
+
+### Step 6: Review and Final Quality (Nontrivial Items Only)
+
+Skip this step entirely if ALL items were classified as trivial in Step 3.
+
+#### 6a. Review Loop
+
+For nontrivial items, run an iterative review loop (max 3 iterations) until 0 Critical + 0 Warning findings remain:
+
+1. Spawn `hatch3r-reviewer` sub-agent via the Task tool (`subagent_type: "generalPurpose"`).
+
+The reviewer prompt MUST include:
+- The diff of all changes made (use `git diff` on the working tree).
+- Focus areas: **correctness and code quality only**. Skip security deep-dive, performance profiling, and documentation review.
+- All `scope: always` rule directives from `.agents/rules/`.
+- Iteration number and previous findings (if not the first iteration).
+
+2. Process reviewer output:
+   - If **0 Critical and 0 Warning** findings: review loop is clean. Proceed to Step 6b.
+   - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them, then re-run the reviewer (next iteration).
+   - **Suggestions**: skip. The point of quick-change is speed.
+
+3. If 3 iterations complete and findings remain, **ASK** the user whether to proceed or fix manually.
+
+4. After any fixes, re-run quality checks (Step 5a) to verify nothing broke.
+
+#### 6b. Final Quality
+
+After the review loop is clean, spawn both agents in parallel via the Task tool:
+
+1. `hatch3r-test-writer` — write or update tests for nontrivial code changes.
+2. `hatch3r-security-auditor` — lightweight security review of nontrivial code changes.
+
+Both prompts MUST include:
+- The diff of all changes made.
+- All `scope: always` rule directives from `.agents/rules/`.
+
+Apply any resulting changes (new tests, security fixes). Re-run quality checks (Step 5a) if changes were made.
+
+---
+
+### Step 7: Git Action
+
+**ASK:** "All changes complete. Quality checks pass. How should I handle git? (a) commit only, (b) commit and push, (c) skip git — leave changes in working tree"
+
+#### Option (a): Commit Only
+
+```bash
+git add -A
+git commit -m "{commit message}"
+```
+
+#### Option (b): Commit and Push
+
+```bash
+git add -A
+git commit -m "{commit message}"
+git push
+```
+
+If `git push` fails (e.g., no upstream), use `git push -u origin {branch}`.
+
+#### Option (c): Skip Git
+
+Leave all changes in the working tree. Do not stage or commit.
+
+#### Commit Message Format
+
+- **Single item**: `quick: {short description}` (e.g., `quick: fix typo in error message`)
+- **Batch**: `quick: {N} small changes` with a body listing each item:
+  ```
+  quick: 3 small changes
+
+  - fix typo in auth error message
+  - update default timeout to 30s
+  - remove unused import in utils.ts
+  ```
+
+---
+
+### Step 8: Summary
+
+Present a concise completion summary:
+
+```
+Quick Change Complete:
+  Items: {N} ({trivial_count} trivial, {nontrivial_count} nontrivial)
+  Files changed: {file list}
+  Quality: lint {pass/fail}, types {pass/fail}, tests {pass/fail}
+  Review: {skipped / N findings applied}
+  Git: {committed on {branch} / committed and pushed / skipped}
+```
+
+---
+
+## Error Handling
+
+- **Quality check failure after 2 retries**: Present the specific failures and ASK the user whether to commit partial progress, keep trying, or abort.
+- **Implementer sub-agent failure**: Retry once. If the retry fails, fall back to inline implementation for that item. If inline implementation also fails, report the item as unresolved and ASK.
+- **Reviewer flags critical issues**: Present them and ASK whether to fix or proceed without fixing.
+- **Scope creep during implementation**: If actual changes exceed the soft guard thresholds (5 files / 200 lines), warn the user and suggest deferring remaining items to a `hatch3r-workflow` session.
+- **Push failure**: Present the error. Use `git push -u origin {branch}` for new branches. For diverged branches, suggest `git pull --rebase` and ASK before proceeding.
+- **Context degradation (>15 turns)**: Quick changes should complete fast. If the session exceeds 15 turns, suggest starting fresh or switching to `hatch3r-workflow`.
+
+## Guardrails
+
+- **Never skip quality checks (Step 5)** -- even for trivial changes. Lint, typecheck, and test must pass.
+- **Never auto-commit without ASK (Step 7).** The user always decides the git action.
+- **Soft guard is advisory, not blocking.** The user can always override the scope warning.
+- **Stay within the described changes.** Do not expand scope, refactor adjacent code, or add features beyond what was requested.
+- **Recommend `hatch3r-workflow` if scope grows.** If implementation reveals the change is larger than expected, pause and recommend switching.
+- **No board operations.** Never create issues, update project boards, or sync with GitHub Projects.
+- **No PR creation.** Quick changes commit directly; PRs are the user's responsibility if needed.
+- **Respect `scope: always` rules** when delegating to sub-agents. Sub-agents do not inherit rules automatically.
+- **This command composes existing hatch3r agents** (implementer, reviewer, lint-fixer) -- it does not replace them.

package/commands/hatch3r-recipe.md

@@ -2,7 +2,13 @@
 id: hatch3r-recipe
 type: command
 description: Execute shareable workflow recipes that compose agents, skills, and commands into guided sequences for common development scenarios
+tags: [core]
 ---
+
+## Agent Pipeline
+
+This command orchestrates other commands and skills as recipe steps. It does not spawn sub-agents directly — the composed commands handle their own agent delegation.
+
 # Recipe System — Composable Workflow Orchestration
 
 Execute predefined or custom workflow recipes that chain hatch3r's agents, skills, and commands into repeatable guided sequences for common development scenarios.

package/commands/hatch3r-refactor-plan.md

@@ -2,7 +2,17 @@
 id: hatch3r-refactor-plan
 type: command
 description: Plan a refactoring or migration effort -- spawn parallel researchers, produce refactoring spec, ADR(s), and phased todo.md entries for board-fill.
+tags: [planning]
 ---
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Research | `hatch3r-researcher` (4 parallel: current-state, refactoring-strategy, risk-assessment, migration-path) | Yes | Yes |
+| 2. Document Generation | `hatch3r-docs-writer` (refactoring spec, ADRs) | Yes | Yes |
+| 3. Todo Generation | Orchestrator (inline) | No | Yes |
+
 # Refactor Plan — Refactoring & Migration Specification from Problem to Phased Execution
 
 Take a refactoring goal or migration need and produce a complete refactoring specification (`docs/specs/`), architectural decision records (`docs/adr/`) when the approach involves significant design choices, and structured `todo.md` entries (phased work items) ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (current state analysis, refactoring strategy, impact & risk assessment, migration path planning) to design the refactoring from multiple angles before generating artifacts. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
@@ -78,10 +88,10 @@ Refactoring Brief:
    - `docs/specs/` — project specifications (read TOC/headers first, expand relevant sections only)
    - `docs/adr/` — architectural decision records (scan for decisions relevant to the target area)
    - `README.md` — project overview
-   - `/.agents/hatch.json` — board configuration
+   - `.agents/hatch.json` — board configuration
    - Existing `todo.md` — current backlog (check for overlap or related items)
 2. Scan GitHub issues via `search_issues` for existing work related to the refactoring area. Note in-progress work, dependencies, or prior refactoring attempts.
-3. If `/.agents/learnings/` exists, scan for learnings relevant to the target area. Match by area and tags against the refactoring brief.
+3. If `.agents/learnings/` exists, scan for learnings relevant to the target area. Match by area and tags against the refactoring brief.
 4. Scan test coverage in the target area — identify which parts have strong test coverage (safe to refactor) vs. weak coverage (need tests first).
 5. Present a context summary:
 
@@ -117,9 +127,12 @@ Spawn one sub-agent per research domain below concurrently, each following the *
 | 2 | `refactoring-strategy` | Design transformations, behavioral invariants, interface contracts, effort |
 | 3 | `risk-assessment` | Breaking changes, downstream consumers, regression hotspots, rollback strategy |
 | 4 | `migration-path` | Phased execution plan, parallel lanes, rollback points, skill mapping |
+| 5 | `similar-implementation` | Find analogous refactored modules, extract their target patterns, recommend conventions to follow |
 
 Each sub-agent produces the structured output defined by its mode in the hatch3r-researcher agent specification. Modes `current-state` and `refactoring-strategy` apply dimension-specific focus (structural/logical/visual/migration) based on the dimension(s) passed in the brief.
 
+The `similar-implementation` sub-agent finds modules that have already been refactored or that represent the target state the refactoring should aim for. Its convention extraction ensures the refactored code aligns with established codebase patterns rather than inventing new ones.
+
 Wait for all sub-agents to complete before proceeding.
 
 ---
@@ -131,16 +144,17 @@ Wait for all sub-agents to complete before proceeding.
 ```
 Refactoring Summary:
 
-Title:             {title}
-Dimension(s):      {Structural / Logical / Visual / Migration}
-Affected files:    {N} files across {M} modules
-Phases:            {N} phases ({X} parallelizable)
-Total effort:      {estimate}
-ADRs needed:       {N} architectural decisions
-Risks:             {N} risks ({X} high, {Y} med, {Z} low)
-Breaking changes:  {N} ({list if any})
-Test gaps:         {N} areas need tests before refactoring
-Prerequisites:     {list — tests to add, docs to update, etc.}
+Title:               {title}
+Dimension(s):        {Structural / Logical / Visual / Migration}
+Affected files:      {N} files across {M} modules
+Phases:              {N} phases ({X} parallelizable)
+Total effort:        {estimate}
+ADRs needed:         {N} architectural decisions
+Risks:               {N} risks ({X} high, {Y} med, {Z} low)
+Breaking changes:    {N} ({list if any})
+Test gaps:           {N} areas need tests before refactoring
+Convention reference: {reference module} — refactored code should follow patterns from {name}
+Prerequisites:       {list — tests to add, docs to update, etc.}
 ```
 
 2. **Highlight conflicts** between researchers. Common conflict types:
@@ -162,6 +176,8 @@ Prerequisites:     {list — tests to add, docs to update, etc.}
 
 ### Step 5: Generate Refactoring Spec
 
+**Note:** Documents (refactoring spec and ADRs in Steps 5–6) should be generated by spawning parallel `hatch3r-docs-writer` sub-agents via the Task tool (`subagent_type: "generalPurpose"`) rather than the orchestrator writing directly.
+
 From the merged researcher outputs, generate a refactoring specification document. Present all content for review before writing any files.
 
 #### Refactoring Spec — `docs/specs/{NN}_{refactor-slug}.md`
@@ -403,7 +419,7 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Note that
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
 - **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
 - **File write failure:** Report the error and provide the full file content so the user can create the file manually.
-- **Missing project context:** If no `hatch3r-board-shared` or `/.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **Missing project context:** If no `hatch3r-board-shared` or `.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **No existing specs or docs:** Proceed without spec references. Warn that the refactoring spec will be less contextualized without existing project documentation. Recommend running `hatch3r-project-spec` or `hatch3r-codebase-map` first for best results.
 - **Duplicate detection:** If the refactoring overlaps significantly with existing todo.md items or GitHub issues found in Step 2, present the overlap and ASK whether to proceed (augment existing / replace / abort).
 - **Weak test coverage:** If the current state analyzer finds weak test coverage in the target area, the migration path planner MUST include a Phase 0 for test scaffolding. Do not proceed with refactoring phases without adequate coverage.

package/commands/hatch3r-release.md

@@ -1,14 +1,24 @@
+---
+id: hatch3r-release
+type: command
+description: Cut a versioned release with changelog generation, version bumping, and GitHub release creation.
+tags: [devops]
+---
 # Release — Cut a Versioned Release with Changelog
 
 Cut a versioned release for **{owner}/{repo}** with changelog generation, quality verification, version bump, git tagging, GitHub release creation, and optional deploy verification. Follows semantic versioning (major/minor/patch) based on merged PR classification.
 
 ---
 
+## Agent Pipeline
+
+This command runs as a single orchestrator without sub-agent delegation. Quality verification uses direct CLI commands (lint, typecheck, test) rather than specialist agents.
+
 ## 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, Project Reference, and tooling directives. Use GitHub MCP tools for issue/PR operations. Fallback to `gh` CLI for release creation (outside MCP catalog).
+**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context, Project Reference, and tooling directives. Use GitHub MCP tools for issue/PR operations. Fallback to `gh` CLI for release creation (outside MCP catalog).
 
-**Default branch:** Use `board.defaultBranch` from `/.agents/hatch.json` (fallback: `"main"`) for all git operations involving the base branch (e.g., `git log`, `search_pull_requests` with `base`, `git push origin`).
+**Default branch:** Use `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`) for all git operations involving the base branch (e.g., `git log`, `search_pull_requests` with `base`, `git push origin`).
 
 ## Global Rule Overrides
 
@@ -138,7 +148,7 @@ git tag v{version}
 
 ### Step 7: Push
 
-Use `{base}` = `board.defaultBranch` from `/.agents/hatch.json` (fallback: `"main"`).
+Use `{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
 
 ```bash
 git push origin {base} && git push origin v{version}