writers-pattern · diff
git:20260424.9b749cd to git:20260425.1eec969
51 added, 250 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: writers-pattern
- description: Add a new platform writer module in src/writers/ that generates and writes agent config files for a supported platform. Each writer exports a function that accepts a config interface, creates directories (rules/, skills/, mcp configs), writes files with proper formatting and frontmatter, and returns string[] of written file paths. Use when adding platform support for a new agent, integrating a new code AI tool, or extending caliber to support new targets. Do NOT use for modifying existing writers, refactoring scoring logic, or changing how writers are invoked.
- paths:
- - src/writers/*/index.ts
- - src/writers/__tests__/*.test.ts
- - src/writers/index.ts
+ description: Adds a new platform writer in src/writers/ following existing patterns (claude, cursor, codex). Returns string[] of generated file paths. Integrates with writeSetup() orchestration. Use when implementing 'add platform', 'new writer', 'support new agent'. Do NOT use for refactoring existing writers or modifying writers/index.ts exports.
---
- # Platform Writer Pattern
+ # Writers 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.
+ - Each writer MUST export a **named synchronous** function: `export function write{Platform}Config(config: {PlatformConfig}): string[]`
+ - Writer MUST return `string[]` of written file paths (NOT `Promise<string[]>`) — all file I/O uses synchronous `fs` APIs
+ - Writers are called from `writeSetup()` in `src/writers/index.ts`; they must be synchronous to compose correctly
+ - Writer files live in `src/writers/{platform}/index.ts` with a platform-specific config interface defined in the same file
+ - Never use default exports — `src/writers/index.ts` imports all writers by their named export
## 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):
- ```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 `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:
- ```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/<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:
- ```typescript
- 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:
- ```typescript
- 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):
- ```typescript
- 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')`)
+ 1. **Create directory structure**
+ - Create `src/writers/{platform}/index.ts` (main writer)
+ - Create `src/writers/{platform}/__tests__/index.test.ts` (test file)
+ - Verify directory does not already exist: `ls -la src/writers/{platform}/` should return error
- Run: `npm test -- src/writers/__tests__/<platform>.test.ts`
+ 2. **Implement writer function signature**
+ - Define a platform-specific config interface at the top of the file (see `src/writers/claude/index.ts` for shape)
+ - Export named synchronous function: `export function write{Platform}Config(config: {PlatformConfig}): string[]`
+ - Initialize `const written: string[] = []` to track all written paths
+ - Use synchronous `fs.writeFileSync` and `fs.mkdirSync` — no async/await
+ - Return the `written` array at the end
- **Validation**: All tests pass. Confirm mocked file operations match actual file system structure.
+ 3. **Implement core write logic**
+ - For the main config file: use content-wrapping helpers from `src/writers/pre-commit-block.ts` (e.g., `appendPreCommitBlock`, `appendLearningsBlock`)
+ - For rules: create `<platform>/rules/` directory, write each rule, push paths to `written`
+ - For skills: create `<platform>/skills/<name>/` directory, write `SKILL.md` with YAML frontmatter, push paths to `written`
+ - For MCP servers: read existing JSON (if any), merge with spread operator, write back
+ - All writes use `fs.writeFileSync`; all directory creation uses `fs.mkdirSync(dir, { recursive: true })`
- ### 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:
+ 4. **Add test file**
+ - Create `src/writers/__tests__/{platform}.test.ts` following the vitest pattern in `src/writers/__tests__/codex.test.ts`
+ - Mock `fs` module: `vi.mock('fs')`
+ - Test that main config file is written to correct path and returned in the array
+ - Test skill frontmatter format is correct
+ - Verify test runs: `npm test -- src/writers/__tests__/{platform}.test.ts`
- ```typescript
- if (joined.includes('.newplatform/') || joined.includes('newplatform-config')) {
- agents.push('<Platform Name>');
- }
- ```
+ 5. **Register in src/writers/index.ts**
+ - Add import: `import { write{Platform}Config } from './{platform}/index.js'`
+ - Add platform to `AgentSetup.targetAgent` tuple
+ - Add `{platform}?: Parameters<typeof write{Platform}Config>[0]` to `AgentSetup`
+ - Add conditional write block in `writeSetup()` and `getFilesToWrite()`
- **Validation**: Run `npm run refresh` and confirm the summary message lists the new platform.
+ 6. **Verify integration**
+ - Run `npm run build` — must compile without errors
+ - Run `npm run test` — all tests pass
+ - Run `npx tsc --noEmit` — no type errors
## 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<typeof writeDevcodeConfig>[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'));
- });
- });
- ```
+ **User says**: "Add support for a new agent platform called Jetbrains"
- 4. Run: `npm test && npm run build`
+ **Actions**:
+ 1. Create `src/writers/jetbrains/index.ts` with a `JetbrainsConfig` interface
+ 2. Implement `export function writeJetbrainsConfig(config: JetbrainsConfig): string[]` — synchronous, uses `fs.writeFileSync`, returns `written` array
+ 3. Create `src/writers/__tests__/jetbrains.test.ts` using `vi.mock('fs')` pattern from `codex.test.ts`
+ 4. Add to `src/writers/index.ts`: import `{ writeJetbrainsConfig }`, add to `AgentSetup`, call in `writeSetup()`
+ 5. Run `npm run build && npm run test` — all pass
- **Result**: Caliber now generates `.devcode/settings.md` and rules on `caliber refresh` and `caliber init`.
+ **Result**: New writer available via `writeSetup()` orchestration; files are written synchronously and paths are returned.
## Common Issues
- **Issue**: "TypeError: write<Platform>Config is not a function"
- - **Fix**: Verify the function is **exported** (not just defined). Check `export function write<Platform>Config(...)` 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: <name>\ndescription: <desc>\n---\n<content>
- ```
- 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.
+ - **"TypeError: write{Platform}Config is not a function"** — Verify the function is exported: `export function write{Platform}Config(...)`. Missing `export` is a common mistake.
+ - **"ENOENT: no such file or directory"** — Ensure `fs.mkdirSync(parentDir, { recursive: true })` is called BEFORE `fs.writeFileSync(filePath, ...)`. See `src/writers/claude/index.ts` for correct order.
+ - **"Skill file has no frontmatter"** — Frontmatter format must be `---\nname: ...\ndescription: ...\n---\n<content>` (no extra blank lines). Compare with `src/writers/claude/index.ts` lines 40–48.
+ - **"written array is empty but files were created"** — Every `fs.writeFileSync()` call must be followed by `written.push(filePath)`. Check every file operation.
+ - **Build fails: 'platform' already exists** — Check if `src/writers/{platform}/` dir exists from prior attempt; remove or use different platform name