hatch3r 1.6.2 → 1.7.1

package/commands/hatch3r-create.md

@@ -0,0 +1,197 @@
+---
+id: hatch3r-create
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-creator]
+description: Author a custom user-tier artifact (agent, skill, rule, command, or hook) for this project. Generates frontmatter and body skeleton, applies strict + gentle quality gates, writes to .agents/user/{type}/, and offers to sync to all enabled adapters.
+tags: [core, customize]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
+---
+
+## Agent Pipeline
+
+This command runs as an orchestrator. After collecting inputs in Phase 1, it delegates artifact composition and the strict + gentle gate funnel to `hatch3r-creator` via the Task tool. Phase 3 runs `hatch3r validate` and surfaces results inline.
+
+# `/hatch3r-create` — Author a User-Tier Artifact
+
+Use this command when you need a project-specific agent, skill, rule, command, or hook that does not exist in the canonical hatch3r corpus. The command writes one new artifact under `.agents/user/{type}/` per invocation, runs the same frontmatter/security/structural gates the framework uses on canonical content (strict — block on failure), and runs style/lean checks as warnings (gentle — save proceeds, warnings reported).
+
+The 5 supported types: **agent** (sub-agent invokable from orchestrators), **skill** (workflow recipe), **rule** (always or glob-scoped guidance), **command** (slash command, inline or orchestrator), **hook** (event-triggered agent invocation).
+
+---
+
+## Workflow
+
+The command runs in three phases. Phase 1 collects every input upfront. Phase 2 delegates to `hatch3r-creator`. Phase 3 verifies and reports. No file is written until the user confirms the plan in Step 1.7.
+
+## Step 0: Triage
+
+Classify the artifact-authoring request before delegating:
+
+- **Tier 1 (trivial)**: small rule, snippet command, or single-event hook with clear scope; inline frontmatter assembly with minimal type-specific prompts.
+- **Tier 2 (standard)**: standard agent, skill, or orchestrator command with frontmatter and body skeleton; standard pipeline with `hatch3r-creator` delegation and full strict-gate funnel.
+- **Tier 3 (deep)**: artifact with cross-cutting tool allowlists, custom adapters, or pipeline integration; full pipeline with `hatch3r-creator` and confirm the plan with the user before writing.
+
+If Tier 1, run Phase 1 with reduced prompts (skip optional dimensions). If Tier 2, run the standard pipeline below. If Tier 3, expand Phase 1 dimension probing and confirm the plan summary explicitly with the user before delegating.
+
+**Parallel-dispatch directive:** When two or more steps below are independent (no shared files, no data dependency), issue all tool calls or sub-agent spawns in a single turn. Sequential dispatch of independent work is a finding under P7 (efficiency charter §P2).
+
+---
+
+### Phase 1 — Collect & Plan
+
+#### 1.1: Choose Artifact Type
+
+Present the 5 types with one-sentence descriptions and ask the user to select one.
+
+```
+Which type of artifact?
+  1) agent    — A sub-agent invoked by orchestrators via the Task tool
+  2) skill    — A reusable workflow recipe followed by an agent
+  3) rule     — Coding/process guidance applied always or by glob match
+  4) command  — A slash-command entry point (inline or orchestrator)
+  5) hook     — An event-triggered agent invocation (pre-commit, file-save, etc.)
+```
+
+**ASK:** "Select artifact type (1-5)."
+
+Cache the selection as `type`.
+
+#### 1.2: Choose Name
+
+**ASK:** "Provide a kebab-case name for the artifact (lowercase, hyphens only, no spaces). Example: `pr-summarizer`."
+
+Validate the name against the regex `^[a-z][a-z0-9-]*$`. Reject and re-ask if:
+
+- The name fails the regex (uppercase, underscores, leading digit, etc.).
+- The name starts with `hatch3r-` — this prefix is reserved for canonical framework content. Show: "Names starting with `hatch3r-` are reserved for canonical framework artifacts. Choose a different prefix or omit the prefix entirely. The framework will namespace the file path under `.agents/user/{type}/` automatically."
+
+Cache the validated name as `name`.
+
+#### 1.3: Description
+
+**ASK:** "Provide a one-paragraph description (minimum 60 characters). This appears in the AI tool's artifact picker — make it specific enough that the right artifact is selected when the user asks."
+
+Reject and re-ask if the description is shorter than 60 characters. Cache as `description`.
+
+#### 1.4: Tags
+
+Present the known tag set: `core, customization, planning, implementation, review, performance, a11y, security, board`.
+
+**ASK:** "Select one or more tags (comma-separated). You may add custom project tags after the known set, e.g., `implementation, my-team`."
+
+Cache as `tags` (array).
+
+#### 1.5: Adapter Scope (Optional)
+
+**ASK:** "Restrict this artifact to specific adapters? Press Enter to default to ALL enabled adapters (full parity), or list adapter names like `claude, cursor`."
+
+Cache as `adapters` (array, or `null` for full parity).
+
+#### 1.6: Type-Specific Prompts
+
+Branch on the cached `type`:
+
+- **agent:** Ask for `model` preference (default: `standard`; options: `fast | standard | reasoning`). Ask for an optional tool-allowlist hint (free-text). Cache as `model` and `toolHint`.
+- **skill:** Confirm the subdirectory layout. Show: "Skill files are stored as `.agents/user/skills/{name}/SKILL.md` (a new directory will be created). Continue?" — ASK Y/n.
+- **rule:** Ask for scope: `always` (loaded every session) or `conditional` (loaded by glob match). If `conditional`, ASK for a comma-separated glob list (e.g., `src/**/*.ts, src/**/*.tsx`). Then ASK for `precedence` (one of `critical | high | normal | low`, default `normal`). Cache as `ruleScope`, `ruleGlobs`, `rulePrecedence`.
+- **command:** ASK whether this is an orchestrator command. If yes, ASK for the agent pipeline as a comma-separated list of agent IDs (each ID must reference an existing agent — canonical or under `.agents/user/agents/`). Cache as `isOrchestrator` and `agentPipeline`.
+- **hook:** ASK for the hook event from the enum: `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`. Reject any value outside this enum and re-ask. Cache as `hookEvent`.
+
+#### 1.7: Plan Summary & Confirmation
+
+Render the proposed file path, full frontmatter block, and body-skeleton outline. For an agent plan, the summary lists `Path`, `Type`, `Name`, `Description` (first 80 chars), `Tags`, `Adapters` (or "all enabled"), `Model`; then the frontmatter block; then the body-skeleton outline (`<task>`, `<context>`, Implementation Protocol numbered steps, `<rules>`). For other types, swap the type-specific slots from Step 1.6.
+
+**ASK:** "Confirm to delegate authoring to `hatch3r-creator`, or specify changes (e.g., 'change model to fast', 'add tag: review')."
+
+Loop until the user confirms.
+
+---
+
+### Phase 2 — Delegate to `hatch3r-creator`
+
+Use the Task tool to invoke the `hatch3r-creator` sub-agent. If `hatch3r-creator` is not registered in the current session, fall back to `general-purpose` and pass the same input contract — the agent file is part of this release and lives at `agents/hatch3r-creator.md`.
+
+Pass the collected slots as a structured input:
+
+```
+{
+  type:          "{type}",
+  name:          "{name}",
+  description:   "{description}",
+  tags:          [{tags}],
+  adapters:      [{adapters}] | null,
+  model:         "{model}",        // agent only
+  toolHint:      "{toolHint}",     // agent only (optional)
+  ruleScope:     "{ruleScope}",    // rule only
+  ruleGlobs:     [{ruleGlobs}],    // rule only (when scope=conditional)
+  rulePrecedence:"{rulePrecedence}", // rule only
+  isOrchestrator: {bool},          // command only
+  agentPipeline: [{agentPipeline}],// command only (when isOrchestrator=true)
+  hookEvent:     "{hookEvent}"     // hook only
+}
+```
+
+The sub-agent composes frontmatter + body, calls `saveUserContent` from `src/content/userContent.ts` (the canonical strict + gentle gate funnel), and atomic-writes the file via `src/merge/safeWrite.ts`. For rule artifacts, `saveUserContent` also generates the paired `.mdc` companion using the `.md → .mdc` scope transform documented in `rules/hatch3r-content-authoring.md`. For skill artifacts, it creates the `{name}/` subdirectory and writes `SKILL.md` inside.
+
+Wait for the sub-agent's structured return:
+
+```
+{
+  status:       "WRITTEN" | "STRICT_GATE_FAILED" | "BLOCKED",
+  paths:        ["{absolute path}"],
+  strictErrors: [{message, gate, line?}],
+  gentleWarnings: [{message, gate, line?}]
+}
+```
+
+If `status: "STRICT_GATE_FAILED"`, surface every entry in `strictErrors` to the user verbatim and offer to retry Phase 1 with corrections. Do not proceed to Phase 3.
+
+If `status: "BLOCKED"`, surface the blocker (e.g., user file collision) and stop.
+
+---
+
+### Phase 3 — Post-Create Housekeeping
+
+Only run this phase when Phase 2 returns `status: "WRITTEN"`.
+
+#### 3.1: Validate
+
+Run `hatch3r validate --verbose` and capture stdout + exit code. Surface every error and warning related to the new artifact verbatim, plus a summary line: "Validate completed with N errors, M warnings (X relate to the new artifact)." If validate reports errors that block the artifact, instruct the user to edit the file directly at the printed absolute path or re-run `/hatch3r-create` after deleting the file.
+
+#### 3.2: Print Path & Sync Offer
+
+Print the absolute path(s) and the next-step pointer:
+
+```
+Created:
+  /abs/path/.agents/user/{type}/{name}.md
+  /abs/path/.agents/user/rules/{name}.mdc   (rule only — paired companion)
+
+Next step:
+  Run `hatch3r sync` to propagate this artifact to all enabled adapter outputs
+  (.cursor/, .claude/, .github/copilot-instructions.md, etc.).
+
+Edit your artifact directly anytime — `.agents/user/` is preserved across
+`hatch3r update` and `hatch3r clean`.
+```
+
+---
+
+## Constraints / Anti-Patterns
+
+- **Never overwrite an existing user file.** Collision with an existing path under `.agents/user/{type}/` is a strict-gate failure raised by `hatch3r-creator` (status `BLOCKED` with the conflicting path).
+- **Never write to canonical content directories.** All output goes under `.agents/user/`. Writes to `agents/`, `skills/`, `rules/`, `commands/`, or `hooks/` are rejected.
+- **Never bypass strict gates.** Strict failures (frontmatter, ID collision, deny patterns, paired-file parity, orchestrator contract, hook event enum, ≤10KB size) block the save.
+- **Pillar coverage required.** Every user artifact must declare at least one of P1–P6 in tags or body. Authors that do not select a pillar-aligned tag are warned by the gentle gate; the artifact still saves but the warning surfaces in Phase 3.
+- **One artifact per invocation.** Re-run `/hatch3r-create` for additional artifacts.
+
+---
+
+## Quality Charter
+
+This command and the `hatch3r-creator` sub-agent both inherit the standards in `agents/shared/quality-charter.md` — confidence levels, root-cause orientation, measurable acceptance criteria, and graceful failure with corrective messages.

package/commands/hatch3r-debug.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch
 description: Standalone debug-and-fix workflow — add strategic debug logging, collect runtime logs from the user, perform root cause analysis, implement the fix, and clean up all debug artifacts.
 tags: [core, implementation]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 # Debug — Instrument, Diagnose, and Fix from Runtime Evidence
 
@@ -83,6 +87,18 @@ If the user declines, skip all browser steps. Do not ask again during the sessio
 
 Execute these stages in order. **Do not skip any stage.** Ask the user at every checkpoint marked with ASK.
 
+## Triage
+
+Classify the debug request before delegating:
+
+- **Tier 1 (trivial)**: single-file bug with one obvious instrumentation point and known reproduction; reduced researcher depth (`quick`) and minimal logging.
+- **Tier 2 (standard)**: bug spanning 2–4 files with multiple instrumentation points; standard pipeline with researcher (`symptom-trace`) and implementer for logging and fix.
+- **Tier 3 (deep)**: cross-module or intermittent bug requiring deep root-cause analysis; full pipeline with `deep` researcher depth and confirm fix approach with the user before mutating files.
+
+If Tier 1, run the standard stages with reduced researcher depth. If Tier 2, run the full pipeline below. If Tier 3, expand researcher modes (add `regression` if relevant) and confirm the diagnosis with the user before Stage 5.
+
+---
+
 ### Stage 1: Gather Bug Context
 
 **Goal:** Understand the bug, its symptoms, affected area, and reproduction path before instrumenting anything.

package/commands/hatch3r-dep-audit.md

@@ -5,6 +5,9 @@ orchestrator: false
 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.
 tags: [maintenance, security]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-feature-plan.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Design a new capability -- draft user stories, acceptance criteria, data model, API surface, and sub-issue breakdown as an epic-shaped todo.md for greenfield features
 tags: [core, planning]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -38,6 +42,18 @@ Take a single feature idea and produce a complete feature specification (`docs/s
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the feature-planning request before delegating:
+
+- **Tier 1 (trivial)**: small feature scoped to one module with clear AC; reduced fanout (1–2 researchers), produce a single standalone todo entry instead of an epic.
+- **Tier 2 (standard)**: standard feature touching 2–5 modules with sub-tasks; standard pipeline with all 5 parallel researcher modes and ADR generation if architectural decisions arise.
+- **Tier 3 (deep)**: cross-cutting feature with new architecture, multiple integrations, or breaking changes; full pipeline with deep research and confirm spec scope with the user before writing files.
+
+If Tier 1, run the reduced researcher set and skip Step 6 (ADRs). If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including ADR generation and confirm spec scope explicitly before writing files.
+
+---
+
 ### Step 1: Gather Feature Description
 
 1. **ASK:** "Tell me about the feature you want to plan. I need:

package/commands/hatch3r-healthcheck.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Open a QA and reliability epic surveying coverage gaps, flaky tests, and regression blind spots with one testing sub-issue per module plus cross-module wiring audit
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-hooks.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Define and manage event-driven hooks that activate agents on project events
 tags: [core, devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-learn.md

@@ -5,6 +5,9 @@ orchestrator: false
 description: Capture learnings from development sessions into reusable knowledge files for future consultation.
 tags: [core, maintenance]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
 ---
 
 ## Agent Pipeline

package/commands/hatch3r-migration-plan.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-architect, hatch3r-docs-writer]
 description: Create a phased migration plan for a major dependency or framework upgrade. Analyzes breaking changes and produces an actionable plan with rollback procedures.
 tags: [planning, brownfield]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -39,6 +43,18 @@ Take a dependency or framework upgrade target and produce a complete migration p
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the migration request before delegating:
+
+- **Tier 1 (trivial)**: minor version bump with no breaking changes; produce a single-phase todo entry without ADRs or architect involvement.
+- **Tier 2 (standard)**: single major version jump with bounded breaking changes; standard pipeline with both parallel researchers and the architect for impact mapping.
+- **Tier 3 (deep)**: multi-major-version jump or framework migration (e.g., CRA -> Vite); full pipeline with research and confirm phased plan with the user before writing files.
+
+If Tier 1, run a condensed pipeline that skips the architect when no breaking changes exist. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including incremental-vs-direct trade-off analysis and confirm phasing with the user before writing files.
+
+---
+
 ### Step 1: Gather Migration Target
 
 1. **ASK:** "Tell me about the migration you're planning. I need:

package/commands/hatch3r-onboard.md

@@ -6,6 +6,10 @@ agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Generate a comprehensive onboarding guide for a new developer joining the project -- spawn parallel researchers to analyze codebase structure, architecture, and conventions, then produce a tailored onboarding document with setup instructions, architecture walkthrough, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet.
 tags: [brownfield, team]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+triage_tiers: [1, 2, 3]
 ---
 
 ## Agent Pipeline
@@ -38,6 +42,18 @@ Take a new developer's role, experience level, and focus areas and produce a com
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
 
+## Step 0: Triage
+
+Classify the onboarding-guide request before delegating:
+
+- **Tier 1 (trivial)**: small project (<500 files) or condensed guide for a single role; reduced fanout (1 researcher: codebase-overview), abbreviated guide.
+- **Tier 2 (standard)**: standard project with both technical and team context; standard pipeline with all 3 parallel researchers (codebase-overview, architecture, conventions).
+- **Tier 3 (deep)**: large monorepo or staff-level guide covering system architecture, integration boundaries, and scaling considerations; full pipeline with deep researcher depth and confirm sections with the user.
+
+If Tier 1, run the reduced researcher set and skip experience-level depth tailoring. If Tier 2, run the standard pipeline below. If Tier 3, expand researcher depth and confirm guide sections with the user before generating the document.
+
+---
+
 ### Step 1: Gather Context
 
 1. **ASK:** "Tell me about the developer who will use this onboarding guide. I need: