# hatch3r — Development Instructions

> Last updated: 2026-05-26

> This file governs framework development. It is NOT generated output — it is the agentic setup for developing hatch3r itself.

hatch3r is an open-source CLI (TypeScript, Commander.js) that generates tool-agnostic agentic coding setups for 3 AI coding tools (Claude Code, Cursor, GitHub Copilot) from a canonical source model (this repo's top-level `agents/`, `skills/`, `rules/`, `commands/`, `hooks/`) and platform adapters. In v1.9.0 the adapter set was hard-cut from 15 to 3 and canonical content is shipped in the bundled npm package — end-user repos no longer materialize a `.agents/` mirror.

---

## Architecture

| Directory | Contents |
|-----------|----------|
| `src/cli/commands/` | 14 CLI commands: init, sync, status, update, validate, verify, config, clean, add, worktree-setup, worktree-cleanup, cliTools, mcp, explain <!-- count auto-derived; see governance/inventory.json (cliCommands) --> |
| `src/adapters/` | 3 platform adapters: cursor, claude, copilot <!-- count auto-derived; see governance/inventory.json (adapters) --> |
| `src/pipeline/` | 18 pipeline modules: adapterTimeout, adapterToolTranslator, agentIdentity, agentToolAllowlist, circuitBreaker, complianceVerification, diffHash, failureLog, mcpDescriptionScan, observability, phaseOutputSchema, phaseTimeout, pipelineContext, pipelineTimeout, promptGuard, repoSubstitution, retryWithBackoff, reviewLoop <!-- count auto-derived; see governance/inventory.json (pipeline) --> |
| `src/content/` | Content indexing, presets (minimal/standard/full), tag system |
| `src/merge/` | Safe write (temp+rename atomic), managed block tracking |
| `src/content/contentRoot.ts` | `resolveBundledContentRoot()` — locates bundled canonical content shipped inside the npm package |
| `agents/` `skills/` `rules/` `commands/` `hooks/` | Canonical content artifacts. Top-level agents map to `inventory.json.counts.agents`; supporting `agents/modes/` and `agents/shared/` files are reference material outside the inventory count. Per-class totals (agents, skills, rules, commands, hooks) and full file lists: `governance/inventory.json` (regenerated by `npm run inventory`, CI gate `inventory --check-docs` runs 11 drift probes against README + CLAUDE.md + `.cursor-plugin/plugin.json`) <!-- counts auto-derived; see governance/inventory.json --> |
| `checks/` `prompts/` `github-agents/` | Additional content directories not yet tracked in `inventory.json`: 6 checks, 0 prompts (canonical ships none; class reserved for pack supply per `governance/pack-trust-model.md`), 4 github-agents (filesystem-derived) |
| `governance/` | 8 Binding Pillars, 21 audit domains, audit cycle, closed-loop phases |
| `.claude/` | Rules, skills, hooks for framework development |

Entry: `src/cli/index.ts` | Build: tsup to `dist/` | Test: vitest | Lint: eslint

---

## Development Commands

```
npm test                    # vitest (global: 78/65/80/80 stmt/branch/func/line)
npm run lint                # eslint
npx tsc --noEmit            # typecheck
npm run build               # tsup
npx hatch3r validate        # content structure + frontmatter + cross-ref
```

Critical module thresholds: `src/merge/` (90/80/90/90), `src/content/` `src/adapters/customization.ts` (85/75/85/85).

Commits: Conventional Commits (`feat|fix|refactor|test|docs|chore|audit(scope): msg`), DCO sign-off required (`git commit -s`).

---

## The 8 Binding Pillars

Every change must serve at least one pillar. Full definitions: `governance/CONSTITUTION.md` §2 P1-P8.

| Pillar | Name | Enforcement | Primary Ref |
|--------|------|-------------|-------------|
| P1 | CLI UI/UX Excellence | Actionable errors, progressive disclosure, first-run success | D10 |
| P2 | Scientific & Practical Quality | Adversarial thinking, root-cause orientation, measurable criteria | D1,D5,D7,D13 |
| P3 | Adapter & External Tool Currency | Web-research platform docs + CLI tool releases + CVE feeds each cycle | D2,D9,D21 |
| P4 | Comprehensive Lean Coverage | No bloat, no duplication, single-source-of-truth, every file earns existence | D5,D16 |
| P5 | Governance Self-Quality | Governance passes its own tests, anti-slop, lean thresholds | D16,D18,D19 |
| P6 | Security & Trust Governance | OWASP ASI compliance, trust delegation, prompt injection guards | D15 |
| P7 | Speed & Token Efficiency | Static-first prompts, parallel tools, triage-first orchestration | D06 |
| P8 | Clarification & Fan-out Discipline | B1 ambiguity gate via `agents/shared/user-question-protocol.md`; B2 sub-agent count + rationale emission on delegating artifacts | D5,D7,D13 |

**Pillar Compliance Test** (required for governance/content changes):
1. Which pillar(s) does this change serve? If none → reject.
2. What measurable improvement does it produce?
3. Does it increase governance size? If yes → justify net value exceeding size cost.

---

## Orchestrator Self-Discipline (Bypass Protection)

Every assistant turn in this repo that causes a file mutation AND operates as an orchestrator-style flow — whether via a registered `/h4tcher-*` command OR an ad-hoc multi-phase task — MUST:

1. Emit the **Per-Turn Pipeline-State Header** at turn start when the task is Tier >= 2 (per `rules/hatch3r-agent-orchestration.md` -> Per-Turn Pipeline-State Header).
2. Spawn `hatch3r-implementer` via the Task tool for every code mutation (per `rules/hatch3r-agent-orchestration.md` -> Implementation Delegation; Mandatory Delegation Directive). No inline `Edit`/`Write`/`MultiEdit` from the orchestrator turn itself except the `hatch3r-quick-change` Tier 1 carve-out.
3. Emit the **End-of-Turn Delegation Attestation** block immediately before the Iteration Summary, citing per-file the spawning sub-agent invocation and the `delegation_proof_id` it returned (per `rules/hatch3r-agent-orchestration.md` -> End-of-Turn Delegation Attestation).

Ad-hoc multi-phase workflows do not exempt these requirements. If you are running research and review sub-agents but inlining implementation, you are in bypass mode (CHANGELOG #73). Halt and re-delegate.

---

## Governance References

| File | Purpose |
|------|---------|
| `governance/VISION.md` | North star: identity, audience, quality bar, principles |
| `governance/CONSTITUTION.md` | Design rationale: 8 pillars (P1-P8), traceability matrix, lean thresholds |
| `governance/AUDIT.md` | Audit prompt: 21 domains, 121 sub-agents, behavioral charter |
| `governance/AUDIT-EXECUTE.md` | Execution: 4-wave model, regression gates, closed-loop phases |
| `governance/RE-ENVISION.md` | Holistic governance sparring engine — 10 parallel layer SAs + 20-theme dialog; hybrid edit authority (direct-edit / CL-3 / §8 amendment) |
| `governance/EVOLVE.md` | Cross-cycle assessment + prompt mechanics refinement |
| `governance/pack-trust-model.md` | Trust tiers + signing methods for distributed packs (referenced from D15) |
| `governance/audit/domains/D01-D21` + `D15-trust-reference.md` | Domain definitions with sub-agent checklists; D15 trust delegation governed appendix (EVOLVE P2, 2026-04-19); D22/D23/D24 authored in subsequent audit cycles per Decision 19 |
| `governance/audit/templates/` | Sub-agent role templates + `calibration-protocol.md` for finding scoring |

Content fixes flow through the audit cycle (AUDIT.md then AUDIT-EXECUTE.md). No ad-hoc governance edits.

---

## Anti-Slop Wordlist

Zero tolerance in all `.md` files under `governance/`, `agents/`, `commands/`, `rules/`, `skills/`, `hooks/`. FAIL if any appear without measurable qualifier:

| Banned | Use Instead |
|--------|-------------|
| "best possible", "best-in-class", "world-class" | Specific measurable target |
| "comprehensive and thorough", "exhaustive" | Specific scope statement |
| "robust and resilient" | Named resilience pattern (circuit breaker, retry with backoff) |
| "high-quality" (no measure) | Specific quality metric |
| "ensure" (no method) | Specific verification step |
| "properly", "correctly" (no criterion) | Specific passing condition |
| "as needed", "as appropriate" (no trigger) | Specific trigger condition |
| "scalable" (no dimension) | Specific scale target (N users, M repos) |
| "carefully", "thoroughly" | Remove or replace with specific action |
| "it is important to note", "this section describes" | Remove — state the thing directly |
| "obviously", "clearly", "naturally", "intuitively", "without doubt", "certainly" (when not citing a source) | Cite specific source (file:line OR URL with access date) |
| "this might affect", "could be useful" (without specific impact) | Specify measurable impact prediction OR concrete use case |
| "successfully completed", "everything works", "works as expected" (without verification) | Cite verification command + result (e.g., "npm test exit 0, 432/432 passing") |
| "enterprise-grade", "production-grade" (without maturity tier) | Specify maturity tier per CONSTITUTION §2 P5 + Decision 4 (solo/team/scaleup/enterprise) |

---

## Key Patterns

- **Adapter:** Extend `BaseAdapter` (`src/adapters/base.ts`), implement `doGenerate()`, use `readCanonicalFiles()` (reads from `resolveBundledContentRoot()`, not the user's repo), `applyCustomization()`, `wrapInManagedBlock()`, register in `src/adapters/index.ts`
- **Safe writes:** Temp file + atomic rename via `src/merge/safeWrite.ts`
- **Managed blocks:** `HATCH3R:BEGIN`/`HATCH3R:END` markers preserve user content during updates
- **Pipeline:** Circuit breaker (transient vs substantive failure), prompt guard (500KB input/1MB output), phase timeouts, tool allowlists per agent
- **Content frontmatter:** YAML with `id`, `type`, `description`, `tags`; `hatch3r-` filename prefix
- **Manifest + user state:** `.hatch3r/hatch.json` (manifest, schemaVersion 3), `.hatch3r/overrides/` (canonical overrides), `.hatch3r/learnings/`, `.hatch3r/handoffs/`, `.hatch3r/mcp/`
- **Drift detection:** `hatch3r status` / `hatch3r verify` regenerate adapter outputs from bundled content and diff against the on-disk copy — no `.integrity.json` checksum file

---

## Lean Thresholds

From `governance/CONSTITUTION.md` §2 P5:

| Metric | Limit |
|--------|-------|
| CONSTITUTION.md | <=250 lines (+25 per binding pillar; P8 baseline) |
| VISION.md | <=250 lines |
| AUDIT.md | <=600 lines |
| AUDIT-EXECUTE.md | <=700 lines |
| RE-ENVISION.md | <=550 lines |
| EVOLVE.md | <=400 lines |
| pack-trust-model.md | <=300 lines |
| Domain file | 30-80 lines (SA ≤5); SA × 15 lines (SA >5) |
| Cross-file duplication | <5% |
| Anti-slop phrases | 0 per file |
| Checklist items/sub-agent | 4-8 |
| Governance total | <=3000 lines |

---

## Rules & Skills

- **Rules:** `.claude/rules/` — Loaded automatically each session. Enforce pillar-specific constraints.
- **Skills:** `.claude/skills/h4tcher-*/` — Invokable as `/h4tcher-<name>`. The `h4tcher-` prefix marks framework-internal slash commands so they are visually distinct in Claude Code's slash-command picker. Capability lifecycle presets:
  - `/h4tcher-capability-discover` — pre-flight artifact scan
  - `/h4tcher-capability-add` — author a new artifact (delegates to `h4tcher-content/adapter/domain-author`)
  - `/h4tcher-capability-refactor` — rename/split/merge/restructure with cross-reference scrubbing
  - `/h4tcher-capability-remove` — phase out with migration notes and reference cleanup
  - `/h4tcher-scoped-audit` — bounded focused audit of a maintainer-described slice (read-only, in-chat report)
- **Hooks:** `.claude/settings.json` — SessionStart loads governance context, Pre/PostToolUse inject reminders.
