Writers Pattern

Platform Writer Pattern

Critical

• Every writer MUST:

  1. Export a single named function: write<Platform>Config(config: <PlatformConfig>): string[]
  2. Accept a platform-specific config interface defining what content to write
  3. Return string[] of all written file paths (used by manifest and progress display)
  4. Create parent directories with fs.mkdirSync(dir, { recursive: true }) before writing files
  5. Wrap skill frontmatter exactly as shown in Step 4 (YAML between --- markers)
  6. NOT modify files outside the intended platform directories (e.g., Claude writer only touches .claude/, CLAUDE.md, .mcp.json)

• Integration point: Every writer MUST be imported and called in src/writers/index.ts within the writeSetup() function. Missing this step means the writer will never execute.

• Validation before Step 1: Verify the platform name is unique (ls src/writers/ shows no <platform>/index.ts). If it exists, you are modifying, not adding.

Instructions

Step 1: Define the Platform Config Interface

Verify the platform name is unique (see Critical). Create src/writers/<platform>/index.ts.

At the top of the file, define a config interface that describes all content the writer accepts. The interface MUST include:

• A main markdown/text file (e.g., claudeMd, cursorrules, agentsMd, instructions)
• Optional nested arrays: rules, skills, mcpServers, instructionFiles, etc.
• Each rule/skill/file has at minimum: name or filename, content, and for skills, description

Example (matching GitHub Copilot pattern already in codebase):

interface CopilotConfig {
  instructions: string;  // Main content
  instructionFiles?: Array<{ filename: string; content: string }>;
}

Validation: Confirm the interface property names match platform conventions (e.g., Claude uses claudeMd, Cursor uses cursorrules). Check existing writers: src/writers/claude/index.ts line 9, src/writers/cursor/index.ts line 9, src/writers/codex/index.ts line 5.

Step 2: Implement the Writer Export Function

Export a function named write<Platform>Config(config: <PlatformConfig>): string[] that:

1. Initialize an empty written: string[] = [] array to track all written paths.

2. For the main config file (e.g., CLAUDE.md for Claude, .cursorrules for Cursor):

   • Wrap the content with platform-specific blocks: Use helpers from src/writers/pre-commit-block.ts
   • Common blocks: appendPreCommitBlock(content, platform), appendLearningsBlock(content), appendSyncBlock(content)
   • Examples from actual codebase:
     • Claude (src/writers/claude/index.ts line 19-22): appendSyncBlock(appendLearningsBlock(appendPreCommitBlock(config.claudeMd)))
     • Cursor (src/writers/cursor/index.ts line 19-22): No sync block; injects rules instead (pre-commit, learnings, sync as separate files)
     • Codex (src/writers/codex/index.ts line 13-16): appendLearningsBlock(appendPreCommitBlock(config.agentsMd, 'codex'))
     • Copilot (src/writers/github-copilot/index.ts line 19-22): appendSyncBlock(appendLearningsBlock(appendPreCommitBlock(config.instructions, 'copilot')))
   • Write to the exact path (e.g., fs.writeFileSync('CLAUDE.md', wrappedContent)) and push to written.

3. For rules (if applicable): Platform convention determines directory.

   • Cursor uses .cursor/rules/, Claude uses .claude/rules/ (see src/writers/index.ts lines 123-126 and 135-137)
   • For each rule: create the directory, write to <dir>/<rule.filename>, push path to written
   • Cursor special case (src/writers/cursor/index.ts line 24-27): Cursor injects three system rules:

     const preCommitRule = getCursorPreCommitRule();
     const learningsRule = getCursorLearningsRule();
     const syncRule = getCursorSyncRule();
     const allRules = [...(config.rules || []), preCommitRule, learningsRule, syncRule];

4. For skills: Write with YAML frontmatter.

   • Directory pattern: .claude/skills/<skillName>/SKILL.md, .cursor/skills/<skillName>/SKILL.md, .agents/skills/<skillName>/SKILL.md, .opencode/skills/<skillName>/SKILL.md
   • Frontmatter format (exact indentation from src/writers/claude/index.ts line 40-47):

     ---
     name: <skill.name>
     description: <skill.description>
     paths:
       - <optional path pattern 1>
       - <optional path pattern 2>
     ---
     <skill.content>

   • For Opencode (src/writers/opencode/index.ts line 30): Use buildSkillContent(skill) from src/lib/builtin-skills.js instead of manual frontmatter.
   • Create directory with fs.mkdirSync(skillDir, { recursive: true }), write skill, push to written

5. For MCP Servers (if applicable): Write/merge JSON at platform-specific path.

   • Claude (src/writers/claude/index.ts line 54-65): .mcp.json at root
   • Cursor (src/writers/cursor/index.ts line 54-69): .cursor/mcp.json
   • Pattern: Read existing servers (if file exists, try to parse JSON with try/catch), merge with new servers using spread operator { ...existingServers, ...config.mcpServers }, write merged object
   • Wrap in { mcpServers: mergedServers } and output as pretty-printed JSON: JSON.stringify(wrapped, null, 2)

6. For instruction files (GitHub Copilot, src/writers/github-copilot/index.ts line 26-33): Write to .github/instructions/ directory.

   • Create directory, iterate files, write each to <dir>/<file.filename>, push paths

Return the written array.

Validation: Confirm all file write operations are synchronous (fs.writeFileSync, fs.mkdirSync). Ensure every written path is added to the array. No async operations allowed.

Step 3: Add Type Exports (if complex interface)

If the config interface may be reused elsewhere (e.g., in src/writers/index.ts for the AgentSetup type), export the interface from the module.

Validation: Check src/writers/index.ts lines 15-19 to see if new agent setup params are needed.

Step 4: Import and Register in src/writers/index.ts

Open src/writers/index.ts. At the top (around line 2-6), add:

import { write<Platform>Config } from './<platform>/index.js';

Update the AgentSetup interface (around line 12-20):

• Add '<platform>' to the targetAgent tuple (line 13: ('claude' | 'cursor' | 'codex' | 'opencode' | 'github-copilot' | '<platform>')[])
• Add a new property: <platform>?: Parameters<typeof write<Platform>Config>[0];

Update getFilesToWrite() function (starting line 117): Add a new conditional block:

if (setup.targetAgent.includes('<platform>') && setup.<platform>) {
  files.push('<main-config-file>');
  if (setup.<platform>.rules) {
    for (const r of setup.<platform>.rules) files.push(`<rules-dir>/${r.filename}`);
  }
  if (setup.<platform>.skills) {
    for (const s of setup.<platform>.skills) files.push(`<skills-dir>/${s.name}/SKILL.md`);
  }
  // ... repeat for other config types (mcpServers, instructionFiles, etc.)
}

Update writeSetup() function (starting line 22): Add a new conditional block before the return (after line 56):

if (setup.targetAgent.includes('<platform>') && setup.<platform>) {
  written.push(...write<Platform>Config(setup.<platform>));
}

Validation: Confirm the function call order in writeSetup() is consistent (line 37-56): claude → cursor → codex → opencode → github-copilot → (new platform). This ensures AGENTS.md is written once if shared (as with Codex/Opencode, see line 50-52).

Step 5: Add Tests

Create src/writers/__tests__/<platform>.test.ts following the vitest pattern in src/writers/__tests__/codex.test.ts:

1. Mock fs module: vi.mock('fs')
2. Mock return values in beforeEach: vi.mocked(fs.existsSync).mockReturnValue(false)
3. Test that:
   • Main config file is written to correct path
   • Returned array includes all written paths
   • Directories are created before file writes (use .toHaveBeenCalledWith(path, { recursive: true }))
   • Skills have correct frontmatter format (check vi.mocked(fs.writeFileSync).mock.calls)
   • MCP/instruction files are merged/created correctly
   • Pre-commit/learnings/sync blocks are included in main file (expect content .toContain('caliber:managed:pre-commit'))

Run: npm test -- src/writers/__tests__/<platform>.test.ts

Validation: All tests pass. Confirm mocked file operations match actual file system structure.