--- name: caliber-ai-org/writers-pattern source: https://app.decimal.ai/s/caliber-ai-org-writers-pattern@1/SKILL.md source_sha256: 304c229be62e --- # Platform Writer Pattern ## Critical - **Every writer MUST**: 1. Export a single named function: `writeConfig(config: ): 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 `/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//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): ```typescript 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 `writeConfig(config: ): 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 `/`, push path to `written` - **Cursor special case** (`src/writers/cursor/index.ts` line 24-27): Cursor injects three system rules: ```typescript 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//SKILL.md`, `.cursor/skills//SKILL.md`, `.agents/skills//SKILL.md`, `.opencode/skills//SKILL.md` - Frontmatter format (exact indentation from `src/writers/claude/index.ts` line 40-47): ``` --- name: description: paths: - - --- ``` - 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 `/`, 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: ```typescript import { writeConfig } from './/index.js'; ``` Update the `AgentSetup` interface (around line 12-20): - Add `''` to the `targetAgent` tuple (line 13: `('claude' | 'cursor' | 'codex' | 'opencode' | 'github-copilot' | '')[]`) - Add a new property: `?: ParametersConfig>[0];` Update `getFilesToWrite()` function (starting line 117): Add a new conditional block: ```typescript if (setup.targetAgent.includes('') && setup.) { files.push(''); if (setup..rules) { for (const r of setup..rules) files.push(`/${r.filename}`); } if (setup..skills) { for (const s of setup..skills) files.push(`/${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): ```typescript if (setup.targetAgent.includes('') && setup.) { written.push(...writeConfig(setup.)); } ``` **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__/.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__/.test.ts` **Validation**: All tests pass. Confirm mocked file operations match actual file system structure. ### Step 6: Update `detectSyncedAgents()` in `src/commands/refresh.ts` (Optional) If the platform writes config files with distinct naming (e.g., `.newplatform/`), update the detection logic around line 68-77 so end-user refresh output correctly identifies the synced platform: ```typescript if (joined.includes('.newplatform/') || joined.includes('newplatform-config')) { agents.push(''); } ``` **Validation**: Run `npm run refresh` and confirm the summary message lists the new platform. ## Examples ### Example 1: Add a hypothetical "DevCode" platform writer **User says**: "Add support for DevCode, a new agent that reads config from `.devcode/settings.md` and `.devcode/rules/` directory." **Actions taken**: 1. Create `src/writers/devcode/index.ts` (matching pattern from `src/writers/claude/index.ts`): ```typescript import fs from 'fs'; import path from 'path'; import { appendPreCommitBlock, appendLearningsBlock } from '../pre-commit-block.js'; interface DevcodeConfig { settingsMd: string; rules?: Array<{ filename: string; content: string }>; } export function writeDevcodeConfig(config: DevcodeConfig): string[] { const written: string[] = []; fs.writeFileSync( '.devcode/settings.md', appendLearningsBlock(appendPreCommitBlock(config.settingsMd, 'devcode')) ); written.push('.devcode/settings.md'); if (config.rules?.length) { const rulesDir = path.join('.devcode', 'rules'); if (!fs.existsSync(rulesDir)) fs.mkdirSync(rulesDir, { recursive: true }); for (const rule of config.rules) { const rulePath = path.join(rulesDir, rule.filename); fs.writeFileSync(rulePath, rule.content); written.push(rulePath); } } return written; } ``` 2. Update `src/writers/index.ts`: - Line 2: Add `import { writeDevcodeConfig } from './devcode/index.js';` - Line 13: Change `targetAgent` tuple to include `'devcode'` - Line 19: Add `devcode?: Parameters[0];` - Line 117+: Add devcode block to `getFilesToWrite()` (match Codex pattern lines 144-149) - Line 37+: Add devcode block to `writeSetup()` (match Codex pattern lines 45-47) - Line 68+: Update `detectSyncedAgents()` to check for `.devcode/` 3. Create `src/writers/__tests__/devcode.test.ts` (matching `src/writers/__tests__/codex.test.ts`): ```typescript import { describe, it, expect, vi, beforeEach } from 'vitest'; import fs from 'fs'; import path from 'path'; vi.mock('fs'); import { writeDevcodeConfig } from '../devcode/index.js'; describe('writeDevcodeConfig', () => { beforeEach(() => { vi.clearAllMocks(); vi.mocked(fs.existsSync).mockReturnValue(false); }); it('writes settings.md and rules', () => { const config = { settingsMd: '# DevCode Config', rules: [{ filename: 'style.md', content: 'Style rules' }], }; const written = writeDevcodeConfig(config); expect(written).toContain('.devcode/settings.md'); expect(written).toContain(path.join('.devcode', 'rules', 'style.md')); }); }); ``` 4. Run: `npm test && npm run build` **Result**: Caliber now generates `.devcode/settings.md` and rules on `caliber refresh` and `caliber init`. ## Common Issues **Issue**: "TypeError: writeConfig is not a function" - **Fix**: Verify the function is **exported** (not just defined). Check `export function writeConfig(...)` in the writer file. Missing `export` is a common mistake. **Issue**: "ENOENT: no such file or directory, open '.platform/config.md'" - **Fix**: The parent directory was not created. Ensure `fs.mkdirSync(parentDir, { recursive: true })` is called **before** `fs.writeFileSync(filePath, content)`. See correct order in `src/writers/claude/index.ts` lines 26-27. **Issue**: "Skill file has no frontmatter / malformed YAML" - **Fix**: Verify frontmatter format is exactly (no extra blank lines): ``` ---\nname: \ndescription: \n---\n ``` Use `[...].join('\n')` and test with a single skill first. Compare with working code in `src/writers/claude/index.ts` lines 40-48. **Issue**: "MCP servers not merging, file is truncated" - **Fix**: Confirm the merge pattern from `src/writers/claude/index.ts` line 54-65: read existing JSON (with try/catch), parse safely, merge with spread operator `{ ...existingServers, ...config.mcpServers }`, then write the merged object. Do NOT overwrite — always merge. **Issue**: "new writer is called but written files are empty array" - **Fix**: Verify the writer function returns the `written` array. Check that every file operation pushes to `written`. Missing a `written.push(filePath)` after `fs.writeFileSync()` is the most common error. See `src/writers/codex/index.ts` lines 17 and 32 for correct pattern. **Issue**: "Tests mock fs but actual files are created in .tmp/ or cause permission errors" - **Fix**: Ensure `vi.mock('fs')` is at the top of the test file before any imports. All `fs` operations will be mocked and return mock values from `beforeEach` setup. See `src/writers/__tests__/codex.test.ts` line 5. **Issue**: "Cursor pre-commit rule not applied, or learnings block missing" - **Fix**: Cursor injects system rules during the write, unlike Claude which uses block appenders. Check that `getCursorPreCommitRule()`, `getCursorLearningsRule()`, and `getCursorSyncRule()` are called and concatenated with user rules **before** iterating (see `src/writers/cursor/index.ts` lines 24-27). Claude and Codex use block-append helpers instead.