hatch3r 1.8.0 → 1.9.0

package/{skills → dist/content/skills}/hatch3r-issue-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-issue-workflow
 description: Guides the 8-step agentic development workflow for issues/work items. Covers parsing issues, loading skills, reading specs, planning, implementing, testing, opening PRs/MRs, and addressing review. Use when working on any issue/work item or when the user mentions an issue number.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -10,7 +10,7 @@ cache_friendly: true
 
 ## Quick Start
 
-When assigned an issue or work item (GitHub Issue, Azure DevOps Work Item, or GitLab Issue — check `platform` in `.agents/hatch.json`), follow these 8 steps in order:
+When assigned an issue or work item (GitHub Issue, Azure DevOps Work Item, or GitLab Issue — check `platform` in `.hatch3r/hatch.json`), follow these 8 steps in order:
 
 ```
 Task Progress:
@@ -108,8 +108,8 @@ Skip this step if the issue has no user-facing UI changes.
 
 - Use the project's PR/MR template. Fill every section.
 - Link to the issue/work item. Include plan, implementation summary, test evidence.
-- **Base branch:** Use `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
-- Open a code review using the platform CLI (check `platform` in `.agents/hatch.json`):
+- **Base branch:** Use `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
+- Open a code review using the platform CLI (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** `gh pr create --base {defaultBranch} --head {branch} --title "..." --body "..."`
   - **Azure DevOps:** `az repos pr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
   - **GitLab:** `glab mr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`

package/{skills → dist/content/skills}/hatch3r-migration/SKILL.md

@@ -2,7 +2,7 @@
 id: hatch3r-migration
 type: skill
 description: Plan and execute migrations for databases, frameworks, and dependencies. Covers breaking change analysis, phased rollout, and rollback procedures.
-tags: [implementation, brownfield]
+tags: [implementation, ctx:brownfield-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-observability-verify/SKILL.md

@@ -118,7 +118,6 @@ The orchestrator running this skill emits a single-line verdict per gate (`GATE_
 
 ## Cross-References
 
-- `rules/hatch3r-observability.md`
 - `rules/hatch3r-observability-logging.md`
 - `rules/hatch3r-observability-metrics.md`
 - `rules/hatch3r-observability-tracing.md` (includes AI agent instrumentation; was previously split as `-detail`)

package/{skills → dist/content/skills}/hatch3r-perf-audit/SKILL.md

@@ -97,7 +97,7 @@ Common strategies:
 ## Step 5: Implement Optimizations
 
 - Apply changes incrementally. Measure before and after each change.
-- Document before/after for each metric in PR/MR or audit report (check `platform` in `.agents/hatch.json` for PR vs MR terminology).
+- Document before/after for each metric in PR/MR or audit report (check `platform` in `.hatch3r/hatch.json` for PR vs MR terminology).
 - Respect `prefers-reduced-motion` — do not add animations that ignore it.
 - Run full test suite after each optimization to avoid functional regressions.
 

package/{skills → dist/content/skills}/hatch3r-pr-creation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-pr-creation
 description: Create a pull request or merge request following project conventions including branch naming, PR/MR template, checklist, and rollout plan. Use when opening or preparing a PR/MR, or when the user asks to create a PR or MR.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -10,7 +10,7 @@ cache_friendly: true
 
 # PR / MR Creation Workflow
 
-> **Platform detection:** Check `platform` in `.agents/hatch.json` to determine terminology and CLI. GitHub/Azure DevOps use "Pull Request" (PR); GitLab uses "Merge Request" (MR).
+> **Platform detection:** Check `platform` in `.hatch3r/hatch.json` to determine terminology and CLI. GitHub/Azure DevOps use "Pull Request" (PR); GitLab uses "Merge Request" (MR).
 
 ## Quick Start
 
@@ -85,12 +85,12 @@ Examples:
 - `feat: add user preferences panel (#42)`
 - `fix: correct validation for email field (#87)`
 
-Create the PR/MR using the platform CLI (check `platform` in `.agents/hatch.json`):
+Create the PR/MR using the platform CLI (check `platform` in `.hatch3r/hatch.json`):
 - **GitHub:** `gh pr create --base {defaultBranch} --head {branch} --title "..." --body "..."`
 - **Azure DevOps:** `az repos pr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
 - **GitLab:** `glab mr create --source-branch {branch} --target-branch {defaultBranch} --title "..." --description "..."`
 
-Use `board.defaultBranch` from `.agents/hatch.json` as the target branch (fallback: `"main"`).
+Use `board.defaultBranch` from `.hatch3r/hatch.json` as the target branch (fallback: `"main"`).
 
 ## Required Agent Delegation
 

package/{skills → dist/content/skills}/hatch3r-qa-validation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-qa-validation
 description: E2E validation workflow producing a structured pass/fail report with evidence. Use when running QA validation, acceptance testing, verifying releases, or working on QA E2E validation issues.
-tags: [core, review]
+tags: [review, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -95,7 +95,7 @@ Produce a structured report with:
 
 - File new issues for bugs discovered during validation.
 - If validation fails, state what must be fixed before re-validation.
-- Post report as comment on the issue/work item or linked PR/MR (check `platform` in `.agents/hatch.json`).
+- Post report as comment on the issue/work item or linked PR/MR (check `platform` in `.hatch3r/hatch.json`).
 
 ## Error Handling
 

package/{skills → dist/content/skills}/hatch3r-recipe/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-recipe
 description: Create, test, and manage workflow recipes that compose hatch3r capabilities into guided sequences. Use when creating new recipes, customizing existing ones, or troubleshooting recipe execution.
-tags: [core]
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -49,9 +49,89 @@ Map out the dependency graph:
 - Identify steps that can run in parallel
 - Mark checkpoint steps where user confirmation adds value
 
+## Recipe Schema
+
+Recipes are YAML files stored in `.hatch3r/recipes/` (project-level) or `~/.hatch3r/recipes/` (user-level):
+
+```yaml
+name: greenfield-setup
+version: 1.0.0
+description: Full greenfield project setup from spec to first PR
+author: hatch3r
+tags: [setup, greenfield, planning]
+
+prerequisites:
+  - GitHub repository initialized
+  - hatch3r initialized (hatch3r init)
+
+variables:
+  project_name:
+    description: Project name
+    required: true
+  tech_stack:
+    description: Primary tech stack
+    required: true
+    options: [react, vue, next, express, fastify]
+
+steps:
+  - id: generate-spec
+    name: Generate Project Specification
+    command: hatch3r-project-spec
+    inputs:
+      project_name: "{{ project_name }}"
+    checkpoint: true
+
+  - id: init-board
+    name: Initialize Project Board
+    skill: hatch3r-board-init
+    depends_on: [generate-spec]
+    checkpoint: true
+
+  - id: security-baseline
+    name: Security Baseline Audit
+    command: hatch3r-security-audit
+    depends_on: [init-board]
+    parallel_with: [a11y-baseline]
+
+  - id: a11y-baseline
+    name: Accessibility Baseline
+    skill: hatch3r-a11y-audit
+    depends_on: [init-board]
+    parallel_with: [security-baseline]
+
+completion:
+  message: "Project {{ project_name }} is set up."
+  next_steps:
+    - Continue with `board-pickup` to implement remaining issues
+```
+
+Recipes can also reference other recipes as steps via `recipe: <name>` with `inputs:`.
+
+## Built-in Recipes
+
+1. **Greenfield Setup** — spec → board → audit → first issue
+2. **Legacy Onboarding** — codebase analysis → codebase map → board setup → healthcheck → first improvements
+3. **Security Hardening** — security audit → dep audit → findings triage → hardening
+4. **Performance Sprint** — perf audit → budget review → optimization → verification
+5. **Release Preparation** — healthcheck → test validation → security scan → changelog → release
+6. **Quality Gate** — lint fix → test coverage review → a11y audit → perf audit → security scan
+
+## Execution Modes
+
+| Mode | Behavior |
+|------|----------|
+| Interactive (default) | Pause at checkpoints, show progress |
+| Auto (`--auto`) | Skip checkpoints, run all steps autonomously |
+| Dry-run (`--dry-run`) | Show execution plan without running |
+| Resume (`--resume`) | Continue from last checkpoint |
+
+Workflow: parse recipe → check prerequisites → collect variables (CLI args or prompt) → build DAG from `depends_on`/`parallel_with` → execute (parallelizing where possible) → handle checkpoints → report completion.
+
+Guardrails: recipes must not bypass safety checkpoints for destructive operations; YAML is validated against the schema before execution; circular dependencies are detected and rejected; variable injection is sanitized to prevent command injection.
+
 ## Step 3: Write Recipe YAML
 
-Create the recipe file in `.hatch3r/recipes/` following the schema defined in the `hatch3r-recipe` command. Include:
+Create the recipe file in `.hatch3r/recipes/` following the schema above. Include:
 - Clear name and description
 - Required variables with descriptions
 - Steps with proper `depends_on` and `parallel_with` relationships

package/{skills → dist/content/skills}/hatch3r-refactor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-refactor
 description: Internal code quality improvement workflow without changing external behavior. Use when refactoring code structure, simplifying modules, or improving maintainability.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-release/SKILL.md

@@ -40,7 +40,7 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 ## Step 1: Determine Version Bump
 
 - Review changes since last release: merged PRs/MRs, commit history.
-- List merged PRs/MRs since last tag using the platform tools (check `platform` in `.agents/hatch.json`):
+- List merged PRs/MRs since last tag using the platform tools (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** Use **GitHub MCP** (`search_issues`, PR search) or `gh pr list --state merged --base {defaultBranch}`
   - **Azure DevOps:** `az repos pr list --status completed --target-branch {defaultBranch}`
   - **GitLab:** `glab mr list --state merged --target-branch {defaultBranch}`
@@ -82,7 +82,7 @@ npm run build
 
 - Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`.
 - Push tag: `git push origin vX.Y.Z`.
-- Create the release using the platform CLI (check `platform` in `.agents/hatch.json`):
+- Create the release using the platform CLI (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** `gh release create vX.Y.Z --title "vX.Y.Z" --notes "{changelog}"` (or use **GitHub MCP** if available)
   - **Azure DevOps:** `az repos tag create vX.Y.Z` — attach release notes as a wiki page or work item, and upload build artifacts via Azure Artifacts
   - **GitLab:** `glab release create vX.Y.Z --name "vX.Y.Z" --notes "{changelog}"`
@@ -103,6 +103,39 @@ npm run build
 - Watch user-reported issues for first 24h.
 - If errors spike: rollback and investigate.
 
+## Pre-Release Support
+
+Version formats: alpha (`x.y.z-alpha.N`), beta (`x.y.z-beta.N`), release candidate (`x.y.z-rc.N`). Workflow:
+
+1. Tag pre-release (e.g., `v1.2.0-beta.1`).
+2. Publish to npm with `--tag` (`npm publish --tag beta`).
+3. Smoke-test against the pre-release package.
+4. Promote: publish stable without pre-release suffix.
+5. Deprecate pre-release versions after stable release.
+
+npm distribution tags: `latest` (stable), `beta`, `next` (RCs), `alpha`. GitHub releases for pre-releases use `--prerelease`.
+
+## CHANGELOG.md Format
+
+Follow Keep a Changelog:
+- `### Added` — new features
+- `### Changed` — changes to existing functionality
+- `### Deprecated` — soon-to-be removed
+- `### Removed` — removed features
+- `### Fixed` — bug fixes
+- `### Security` — vulnerability fixes
+
+Entries grouped under `## [x.y.z] - YYYY-MM-DD`. Generate entry as part of the release commit; stage `CHANGELOG.md` alongside `package.json`. If `CHANGELOG.md` does not exist, create it with the standard header pointing to keepachangelog.com and semver.org.
+
+## Rollback Procedure
+
+If a release introduces critical issues:
+
+- **npm:** `npm deprecate package@version "Critical issue — use version X instead"`. Within 72h, `npm unpublish package@version` is permitted (only inside npm's unpublish window). Publish a hotfix as a new patch release.
+- **Git:** create a revert commit on the default branch, tag a new patch version, push to trigger the release workflow.
+- **Communication:** update CHANGELOG with rollback notice, open a post-mortem issue, notify users via release notes/discussions.
+- Always create a tracking issue documenting the incident. Never auto-rollback or auto-unpublish without explicit user confirmation; prefer deprecation over unpublish.
+
 ## Error Handling
 
 - **Quality gates fail during release preparation**: Do not proceed with the release. Fix the failing gate (test failures, lint errors, type errors), re-run all gates, and restart the release process.

package/{skills → dist/content/skills}/hatch3r-ui-ux-verify/SKILL.md

@@ -2,7 +2,7 @@
 id: hatch3r-ui-ux-verify
 type: skill
 description: UI/UX verification gate before declaring a feature done — axe-core, scripted keyboard trace, accessibility-tree snapshot, four-state coverage, visual-regression baseline, one human screen-reader pass per release
-tags: [ui, ux, a11y]
+tags: [review, floor:ui-ux, ui, ux, a11y]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{skills → dist/content/skills}/hatch3r-visual-refactor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-visual-refactor
 description: UI/UX change workflow matching design, accessibility, and responsiveness requirements. Use when making visual changes, updating components, working on UI issues, or implementing design mockups.
-tags: [implementation]
+tags: [implementation, floor:ui-ux]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hatch3r",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Battle-tested agentic coding setup framework. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for every major AI coding tool.",
   "type": "module",
   "exports": {
@@ -13,7 +13,8 @@
     "hatch3r": "./dist/cli/index.js"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsx scripts/copy-content.ts",
+    "postbuild": "tsx scripts/copy-content.ts",
     "dev": "tsup --watch",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
@@ -43,12 +44,6 @@
     "cursor",
     "copilot",
     "claude",
-    "opencode",
-    "windsurf",
-    "amp",
-    "codex",
-    "gemini",
-    "cline",
     "agentic",
     "ai-agents",
     "mcp",
@@ -73,20 +68,13 @@
     "node": ">=22.0.0"
   },
   "files": [
-    "dist/cli/",
-    "agents/",
-    "checks/",
-    "commands/",
-    "rules/",
-    "skills/",
-    "prompts/",
-    "github-agents/",
-    "mcp/",
-    "hooks/",
+    "dist/",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
+    "@inquirer/core": "^11.1.9",
+    "@inquirer/figures": "^2.0.5",
     "boxen": "^8.0.1",
     "chalk": "^5.4.0",
     "commander": "^14.0.3",

package/commands/hatch3r-agent-customize.md

@@ -1,201 +0,0 @@
----
-id: hatch3r-agent-customize
-type: command
-orchestrator: false
-description: Override agent persona, model selection, preset enablement, and repo-file apply-scope via YAML plus markdown injection under .hatch3r/agents/
-tags: [customize]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation. Customization file management is performed inline.
-
-# Agent Customization — Per-Agent Configuration
-
-Customize individual agent behavior for project-specific needs via `.hatch3r/agents/` configuration files. Supports structured YAML overrides and free-form markdown instruction injection, all propagated to every adapter output on sync.
-
----
-
-## Customization File Locations
-
-Each agent supports two optional customization files:
-
-```
-.hatch3r/agents/{agent-id}.customize.yaml    # structured overrides
-.hatch3r/agents/{agent-id}.customize.md      # free-form markdown instructions
-```
-
-Both files are optional and can be used independently or together.
-
-## YAML Customization Schema
-
-```yaml
-agent: hatch3r-reviewer
-model: claude-opus-4-6
-description: "Security-focused code reviewer for healthcare platform"
-enabled: true
-```
-
-### Fields
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `model` | string | (from canonical/manifest) | Override the agent's model preference |
-| `description` | string | (from canonical) | Override the agent's description in adapter frontmatter |
-| `enabled` | boolean | `true` | Set to `false` to exclude this agent from adapter output generation |
-
-### Model Resolution Order
-
-Model is resolved with the following priority (highest wins):
-
-1. `.hatch3r/agents/{id}.customize.yaml` → `model`
-2. `hatch.json` → `models.agents.{id}`
-3. Canonical agent frontmatter → `model`
-4. `hatch.json` → `models.default`
-
-Model aliases are supported: `opus`, `sonnet`, `haiku`, `codex`, `gemini-pro`, etc.
-
-## Markdown Customization
-
-Create `.hatch3r/agents/{agent-id}.customize.md` with free-form markdown to inject project-specific instructions into the agent's managed block. This content is appended after the canonical agent definition under a `## Project Customizations` header.
-
-### Example
-
-**File:** `.hatch3r/agents/hatch3r-reviewer.customize.md`
-
-```markdown
-## Domain-Specific Review Rules
-
-This is a healthcare SaaS platform handling PHI data.
-All data must be encrypted at rest and in transit. HIPAA compliance is mandatory.
-
-### Additional Review Checklist
-
-- Verify no PHI in logs, error messages, or client responses
-- All data stores use AES-256 encryption
-- All data access is logged with user ID and timestamp
-
-### Architecture Context
-
-Microservices architecture with event sourcing.
-Services communicate via RabbitMQ.
-PostgreSQL for persistence, Redis for caching.
-```
-
-### How It Works
-
-1. During `hatch3r sync` or `hatch3r init`, adapters read the `.customize.md` file
-2. The markdown content is appended **inside** the managed block, after the canonical agent content
-3. All adapter outputs (Cursor, Claude, Copilot, etc.) receive the customization automatically
-4. Changes to `.customize.md` propagate on every sync — edit once, apply everywhere
-
-### Resulting Adapter Output
-
-The adapter wraps the result in hatch3r-managed block comments (literal markers omitted here so this file itself stays valid):
-
-```markdown
-[managed-block-start]
-{canonical agent content}
-
----
-
-## Project Customizations
-
-{content from .customize.md}
-[managed-block-end]
-```
-
-Replace `[managed-block-start]` / `[managed-block-end]` with the actual `<!-- HATCH3R\:BEGIN -->` / `<!-- HATCH3R\:END -->` markers in real adapter output.
-
-Content placed **outside** the managed block markers by directly editing adapter output files is always preserved.
-
-## Per-Agent Customization Examples
-
-| Agent | Common Customizations |
-|-------|----------------------|
-| reviewer | Domain review checklists, severity focus, architecture context |
-| security-auditor | Compliance requirements (HIPAA, SOC2, PCI), custom invariants |
-| test-writer | Coverage targets, required test types, framework preferences |
-| implementer | Architecture constraints, coding patterns, dependency restrictions |
-| a11y-auditor | Additional WCAG criteria, custom accessibility requirements |
-| perf-profiler | Custom performance budgets, monitoring tool guidance |
-| dependency-auditor | Approved/denied dependency lists, update policies |
-| docs-writer | Documentation templates, terminology glossary |
-| lint-fixer | Custom lint rules, auto-fix preferences |
-| ci-watcher | Custom CI job knowledge, failure pattern library |
-
-## Disabling an Agent
-
-To exclude an agent from adapter output without deleting its canonical file:
-
-```yaml
-# .hatch3r/agents/hatch3r-a11y-auditor.customize.yaml
-enabled: false
-```
-
-The agent's canonical definition remains in `.agents/agents/` but no adapter output is generated for it.
-
-## Protected Agents
-
-Some agents have `protected: true` in their canonical frontmatter. This field marks agents whose core behavior must not be weakened or bypassed through customization, because they enforce critical quality and security invariants.
-
-### Currently Protected Agents
-
-| Agent | Why Protected |
-|-------|--------------|
-| `hatch3r-reviewer` | Enforces code quality, privacy invariants, and security review. Weakening or disabling it would allow unsafe code to merge unreviewed. |
-| `hatch3r-security-auditor` | Enforces security rules, access control auditing, and privacy invariant verification. Disabling it would leave security gaps undetected. |
-| `hatch3r-test-writer` | Enforces test coverage requirements and regression testing. Disabling it would allow untested code to ship. |
-
-### What Protection Means
-
-- **Cannot be disabled.** Setting `enabled: false` in a `.customize.yaml` file for a protected agent is ignored. The agent is always included in adapter output.
-- **Cannot have scope or description overridden.** The `description` field in a `.customize.yaml` file is ignored for protected agents. Their canonical description is always used to prevent narrowing or misrepresenting the agent's responsibilities.
-- **Model overrides ARE allowed.** You can override the `model` field for protected agents via `.customize.yaml` or `hatch.json`. Choosing a more capable model for a protected agent is a valid use case.
-- **Markdown customization IS allowed.** You can add project-specific instructions via `.customize.md` (e.g., domain-specific review checklists, compliance requirements). These are appended to the canonical content and extend the agent's scope — they cannot reduce it.
-
-### Frontmatter Format
-
-```yaml
----
-id: hatch3r-example-agent
-description: Expert code reviewer for the project...
-protected: true
-model: standard
----
-```
-
-The `protected` field is set in the canonical agent definition and cannot be overridden by customization files.
-
-## Workflow
-
-1. Identify which agent to customize
-2. Create `.hatch3r/agents/{agent-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 files (e.g., `.cursor/agents/`)
-
-## Guardrails
-
-- Customization files cannot remove the agent's core role or boundaries
-- Invalid YAML produces warnings but does not prevent agent execution (graceful degradation)
-- Customization files should be committed to the repository
-
-## Unified Skill
-
-This command's workflow is handled by the `hatch3r-customize` skill with `type: agent`. The skill provides root-cause analysis, multi-stakeholder review, and quality gate steps that extend the workflow above. Invoke the skill directly or use this command for the agent-specific reference documentation (model resolution, protected agents, per-agent examples).
-
-## Related
-
-- Skill customization: `hatch3r-skill-customize` command
-- Command customization: `hatch3r-command-customize` command
-- Rule customization: `hatch3r-rule-customize` command
-- Model selection: [Model Selection](https://docs.hatch3r.com/docs/guides/model-selection) — configuration, aliases, resolution order
-- Platform support: [Adapter Capability Matrix](https://docs.hatch3r.com/docs/reference/adapter-capability-matrix) — model emission per adapter (native vs guidance)

package/commands/hatch3r-command-customize.md

@@ -1,113 +0,0 @@
----
-id: hatch3r-command-customize
-type: command
-orchestrator: false
-description: Tune slash-command display text, orchestrator sub-agent dispatch pipeline, and invocation arguments via .hatch3r/commands/ YAML and markdown overrides
-tags: [customize]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation. Customization file management is performed inline.
-
-# 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. Run `npm run test:e2e:staging` and confirm all E2E tests pass on 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
-
-## Unified Skill
-
-This command's workflow is handled by the `hatch3r-customize` skill with `type: command`. The skill provides root-cause analysis, multi-stakeholder review, and quality gate steps that extend the workflow above.
-
-## Related
-
-- Agent customization: `hatch3r-agent-customize` command
-- Skill customization: `hatch3r-skill-customize` command
-- Rule customization: `hatch3r-rule-customize` command