Skip to main content

Customization

hatch3r is designed to be extended without conflicting with managed updates.

When to use which mechanism​

Three mechanisms separate hatch3r-managed content from your project's customizations. Pick by intent, not by file type:

IntentMechanismWhere it livesWhat survives hatch3r sync
Add a project-specific rule / agent / skill that hatch3r does not shipNon-prefixed file (no hatch3r- prefix).cursor/rules/my-rule.mdc, .claude/agents/my-agent.md, etc.The whole file — hatch3r never reads or writes it
Append project-specific guidance to a hatch3r-managed file (e.g. notes under CLAUDE.md)Managed blockOutside the <!-- HATCH3R:BEGIN --> / <!-- HATCH3R:END --> markers in the managed fileEverything outside the markers
Override a single field on a hatch3r-shipped artifact (model, scope, frontmatter) without forking it.customize.yaml.hatch3r/{agents,skills,rules,commands}/{id}.customize.yamlThe override file — hatch3r reads it on every sync
Replace a hatch3r-shipped artifact's body entirelyCanonical override.hatch3r/overrides/{type}/{id}.mdThe override file — adapters prefer this over the bundled canonical

Rule of thumb: use .customize.yaml for narrow field overrides (model selection, tag tweak), use canonical overrides for whole-body rewrites, use managed blocks for free-form notes alongside generated content, and use non-prefixed files for original project artifacts.

Managed vs. Custom Files​

hatch3r uses a naming convention to separate managed from custom files:

  • hatch3r-* files are managed by hatch3r
  • Files without the prefix are your customizations and are never touched
.cursor/rules/
  hatch3r-code-standards.mdc     # Managed
  hatch3r-git-conventions.mdc    # Managed
  my-project-conventions.mdc     # Custom -- never touched

Managed Blocks​

All hatch3r-generated markdown files use managed blocks. Only the content between <!-- HATCH3R:BEGIN --> and <!-- HATCH3R:END --> is updated on hatch3r sync or hatch3r update. Content you add outside these markers is preserved.

<!-- HATCH3R:BEGIN -->
...managed content (updated on sync/update)...
<!-- HATCH3R:END -->

## My Custom Section
...never overwritten...

Config files (JSON, TOML, YAML) are fully regenerated on sync. For details on how managed blocks work across the adapter system, see Adapter System.

Per-Component Customization​

hatch3r provides .customize.yaml files for fine-grained overrides without modifying managed definitions.

Agents​

Create .hatch3r/agents/{agent-id}.customize.yaml (the file is keyed by id via its filename, so set only the override fields — model for agents):

model: codex

Run the /hatch3r-customize skill (an AI-tool slash command inside Cursor or Claude Code) for interactive setup across every artifact type.

Skills​

Create .hatch3r/skills/{skill-id}.customize.yaml. Skills accept description and enabled:

description: Feature workflow tuned for our service conventions

The /hatch3r-customize skill handles skills too — pass the skill id when it asks what to customize.

Rules​

Create .hatch3r/rules/{rule-id}.customize.yaml. Rules accept scope (when the rule applies) plus description and enabled:

scope: always

The /hatch3r-customize skill handles rules too — pass the rule id when it asks what to customize.

Rule precedence and generated filenames​

Rules declare an optional precedence: critical|high|normal|low field in canonical frontmatter (default normal). Per-file rule adapters (cursor, copilot) emit filenames prefixed with a two-digit rank — 10- (critical), 30- (high), 50- (normal), 70- (low) — so generated output loads in precedence order. The Claude adapter inlines always-apply rules into CLAUDE.md in precedence order.

Validate with npx hatch3r validate. Parity between .md and .mdc variants is enforced by npm run validate:rule-parity. See Rules reference.

Commands​

Create .hatch3r/commands/{command-id}.customize.yaml. Commands accept description and enabled:

enabled: false

The /hatch3r-customize skill handles commands too — pass the command id when it asks what to customize.

Authoring New User-Tier Artifacts​

The /hatch3r-customize skill above adjusts hatch3r's stock content. To author a brand-new project-specific artifact that hatch3r does not ship, use the create command.

/hatch3r-create walks you through type selection (agent, skill, rule, command, or hook), name, description, tags, adapter scope, and type-specific fields. It then delegates to the hatch3r-creator sub-agent, which composes the frontmatter and body skeleton, runs the same strict frontmatter/security/structural gates the framework uses on canonical content (block on failure) plus style/lean checks as warnings, and atomic-writes the file.

Outputs land under .hatch3r/overrides/{type}/{name}.md:

  • Rule artifacts also receive a paired .mdc companion via the .md → .mdc scope transform.
  • Skill artifacts create a {name}/SKILL.md subdirectory.

Files under .hatch3r/overrides/ are preserved across hatch3r update and hatch3r clean. Names beginning with hatch3r- are reserved for canonical framework content and rejected at validation. Run hatch3r sync after creation to propagate the artifact to all enabled adapter outputs.

See the create command reference for the full input contract and gate behavior.

Switching tools​

When you change your selected tools with hatch3r config (for example, dropping Claude Code and adding Cursor), your project-level work is tool-agnostic and is not lost. Here is what happens to each category:

CategoryWhat happens on switch
.hatch3r/overrides/, .hatch3r/learnings/, .hatch3r/handoffs/, .hatch3r/mcp/Carries forward unconditionally. These directories are tool-neutral state — hatch3r config never archives or rewrites them.
Removed tool's adapter output (.claude/, .cursor/, .github/, bridge files)Archived to .hatch3r-archive/ (recoverable). The removed tool's native files are swept per its archive prefix set.
Added tool's adapter outputGenerated from bundled canonical content on the next sync. Restart your editor to pick it up.
.env.mcp MCP secretsShared across tools — no re-entry needed. Cursor and Claude Code require sourcing .env.mcp before launch (set -a && source .env.mcp && set +a); VS Code / Copilot auto-load it via .vscode/mcp.json.

How learnings replay on the new tool: the canonical agents (hatch3r-reviewer, hatch3r-researcher, hatch3r-implementer, hatch3r-fixer, and others) read .hatch3r/learnings/INDEX.md on their first invocation, per the mandatory consultation gate in rules/hatch3r-learning-system.md. You do not re-point the new tool's agents at your learnings; they consult INDEX.md automatically when it is present. The same is true of handoff documents under .hatch3r/handoffs/.

Composable Recipes​

Recipes are reusable workflow templates that chain multiple commands and skills into repeatable sequences. Use the recipe command to create and manage them.

Event-Driven Hooks​

Hooks trigger agents on specific lifecycle events (e.g., post-commit, pre-push, issue assignment). Use the hooks command to view, add, remove, and test hooks. Supports both local and CI hook targets.

Presets​

hatch3r ships with 4 content presets: Minimal (core orchestration + implementation plus floor), Standard (recommended — full dev lifecycle plus floor; drops 2 capability clusters: AI feature engineering + performance), Full (every capability, including AI feature engineering and performance), and Custom (pick exactly what you need). Select during hatch3r init or change later with hatch3r config.

Task-Type Routing​

hatch3r sync emits a ## Task Type → Routing table into each adapter's bridge instruction file (CLAUDE.md for Claude Code, copilot-instructions.md for Copilot, the inlined orchestration doc for Cursor). Each row maps a workflow or domain tag (planning, implementation, review, devops, maintenance, board, security-review, accessibility, performance, customize, core-workflow) to:

  • Primary — the best-matching agent, slash-command, or skill for that task type
  • Fallback Agents — other agents carrying the same tag
  • Skills and Rules — relevant supporting content

The table is rebuilt from the selected content on every sync: customizing your content selection (adding or removing agents/skills/commands/rules) changes which rows and fallbacks appear. Rows are built by buildTaskRouterModel() in src/cli/shared/agentsContent.ts.