H4tcher Adapter Author

> Last updated: 2026-06-09

Adapter Author

Create or modify a platform adapter for hatch3r.

Step 0: P8 B1 Ambiguity Gate

Before any read or write, scan the user request against the four B1 triggers from .claude/rules/clarification-default.md (which carries the verbatim directive from governance/CONSTITUTION.md §2 P8 B1):

1. Ambiguous scope — request maps to ≥2 reasonable interpretations producing different adapters (e.g., "add Zed adapter" without specifying rules-only vs full-feature surface).
2. Multiple valid interpretations — ≥2 viable approaches with materially different cost, scope, or risk (e.g., bundling MCP support vs. deferring to a follow-up).
3. Irreversible action — deleting an existing adapter, renaming its public id, dropping output paths users may already depend on.
4. Missing acceptance criteria — no testable definition of done (e.g., no list of file paths, no capability matrix targets, no test coverage threshold).

If any trigger fires, ask via the platform-native question tool per agents/shared/user-question-protocol.md: one question per turn; bundle related sub-questions into a single multiple-choice prompt; 2-4 numbered options with one-line trade-offs; declare the default-if-no-response option. Do NOT proceed to Step 1 until the ambiguity is resolved or the user has confirmed the default.

Step 1: Understand the Contract

1. Read src/adapters/base.ts — the BaseAdapter abstract class defines:

• name: string — adapter identifier
• warnings: string[] — user-facing warnings
• doGenerate(ctx: AdapterContext): Promise — core generation logic
• getOutputPaths(agentsDir, manifest): Promise — files this adapter creates

1. Read src/adapters/canonical.ts — readCanonicalFiles(canonicalRoot, type, warnings) reads frontmatter-bearing markdown from the bundled content root resolved by resolveBundledContentRoot() (src/content/contentRoot.ts), not a user-repo .agents/ mirror (the legacy .agents/ materialisation no longer exists; canonical.ts:1020-1024)
2. Read src/adapters/customization.ts — applyCustomization() applies user overrides
3. Read src/adapters/mcp-utils.ts — MCP server config transformation

Step 2: Research the Target Platform

1. Web-search the target platform's official documentation for:

• Configuration file format and paths
• Agent/rule/skill capability support
• MCP server integration format
• Hook/event system
• Model configuration syntax

1. Cite documentation version and date in code comments

Step 3: Study Reference Implementations

1. Read the 3 supported adapters (per CONSTITUTION §6 Decision 12, 1.9.0 hard-cut):

• src/adapters/cursor.ts — full-featured reference (rules, agents, skills, MCP, hooks)
• src/adapters/claude.ts — CLAUDE.md output format
• src/adapters/copilot.ts — GitHub Copilot custom-instructions output

1. Read governance/audit/domains/D09-platform-adapters.md for per-adapter audit checklist

Step 4: Implement

1. Create src/adapters/{name}.ts:

• Export class extending BaseAdapter
• Implement doGenerate() — handle each content type (agents, skills, rules, commands, hooks, MCP)
• Implement getOutputPaths() — return all file paths this adapter creates
• Use wrapInManagedBlock() for merge-safe output
• Use resolveAgentModel() for model configuration

1. Register in src/adapters/index.ts:

• Add to adapterMap
• Add to TOOL_DISPLAY_NAMES
• Add to ADAPTER_CAPABILITIES matrix

Step 5: Test

1. Create src/__tests__/adapters/{name}.test.ts:

• Output path correctness
• Content format validation
• Feature flag behavior (when features are disabled)
• MCP format transformation
• Hook format if supported
• Managed block markers present
• Error handling for missing canonical files

1. Run: npm test, npx tsc --noEmit, npm run lint

Step 6: Verify

1. Run npx hatch3r validate with the new adapter configured
2. Verify D09 checklist items: output paths, format, feature flags, bridge orchestration, model emission, MCP, secrets, hooks

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hatch3r
• Source: hatch3r/hatch3r
• License: MIT
• Homepage: https://docs.hatch3r.com

Install and usage instructions live in the source repository linked above.