writers-pattern · diff
git:20260319.c97e02c to git:20260323.a091579
108 added, 160 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: Creates a new file writer in src/writers/ following the established pattern. Writers export a named async function that takes config objects and returns string[] of written file paths. Use when adding support for new platforms, config file formats, or modifying output generation. Includes YAML frontmatter for SKILL.md files and uses fs.writeFileSync for synchronous writes. Do NOT use for reading or parsing existing configs—use fingerprint pattern instead.
+ description: Creates or modifies a file writer in src/writers/ following the established pattern for generating AI agent configs. Writers export a named async function returning string[] of written file paths, use fs.writeFileSync for synchronous writes, mkdirSync recursive for dirs, and YAML frontmatter for SKILL.md files. Use when adding support for new platforms or config file formats, or modifying existing writers in src/writers/claude/, src/writers/cursor/, src/writers/codex/, or src/writers/github-copilot/. Do NOT use for reading or parsing existing configs — use fingerprint pattern instead. Do NOT use for telemetry or metrics — use src/telemetry/ pattern.
---
# Writers Pattern
## Critical
- - Writers MUST export a named async function (not default export) that returns `Promise<string[]>` of written file paths
- - SKILL.md files MUST include YAML frontmatter block at the top:
- ```yaml
- ---
- name: skill-name
- description: brief description
- ---
- ```
- - Use `fs.writeFileSync()` directly; do NOT use higher-level abstractions
- - All written paths MUST be relative to project root (e.g., `.cursor/rules/example.md`)
- - Verify the target directory exists before writing; use `fs.mkdirSync(dir, { recursive: true })`
- - Return empty array `[]` only if no files were actually written
+ 1. **Writers ALWAYS export an async function** matching the signature: `export async function writePlatformName(payload: WriterPayload): Promise<string[]>`
+ 2. **Return value MUST be string[]** — array of absolute file paths written. Used by `writeSetup()` in `src/writers/index.ts` for undo/backup tracking.
+ 3. **Use fs.writeFileSync (synchronous)** — no async file I/O. All writers use blocking writes with `{ encoding: 'utf-8' }`.
+ 4. **mkdirSync({ recursive: true })** before every write. Fail fast on permission errors; do NOT swallow them.
+ 5. **For SKILL.md files** (and only SKILL.md): prepend YAML frontmatter block before markdown body. Frontmatter is generated separately; the writer provides structure only.
+ 6. **Verify payload type** before accessing fields. Reference `WriterPayload` from `src/llm/types.ts`.
## Instructions
- 1. **Create the writer file in `src/writers/`**
- - File naming: `<platform>.ts` (e.g., `claude.ts`, `cursor.ts`, `codex.ts`)
- - Import required modules at the top:
- ```typescript
- import fs from 'fs';
- import path from 'path';
- ```
- - Verify: Writer file exists and compiles with `npm run build`
+ 1. Create file `src/writers/{platform}/index.ts` (replace `{platform}` with lowercase platform name).
+ - Verify: Does `src/writers/` already have a directory for this platform? If yes, modify the existing `index.ts`.
+ - Reference existing writers: `src/writers/claude/index.ts`, `src/writers/cursor/index.ts`.
- 2. **Define the exported async function signature**
- - Function name matches file purpose (e.g., `writeCursorRules`, `writeClaudeConfig`)
- - Accepts parameters matching the config objects from `src/types.ts` (e.g., `config: Config`, `skills: Skill[]`)
- - Return type: `Promise<string[]>`
- - Example:
- ```typescript
- export async function writeCursorRules(
- config: Config,
- rules: Rule[]
- ): Promise<string[]> {
- const written: string[] = [];
- // implementation
- return written;
- }
- ```
- - Verify: Function signature matches existing writers in `src/writers/claude/index.ts`, `src/writers/cursor/index.ts`
+ 2. Import required modules at the top:
+ ```typescript
+ import path from 'path';
+ import { writeFileSync, mkdirSync } from 'fs';
+ import { WriterPayload } from '../../llm/types';
+ ```
+ - Verify: All imports are available in the project. Do NOT use fs.promises or async/await for file ops.
- 3. **Create output directory structure**
- - Determine target directory (e.g., `.cursor/rules/`, `docs/`, `.ai/`)
- - Call `fs.mkdirSync(targetDir, { recursive: true })` before writing
- - Example:
- ```typescript
- const rulesDir = path.join(process.cwd(), '.cursor', 'rules');
- fs.mkdirSync(rulesDir, { recursive: true });
- ```
- - Verify: Directory creation does not throw EACCES or permission errors
+ 3. Define the async function signature matching the pattern:
+ ```typescript
+ export async function write{PlatformName}(payload: WriterPayload): Promise<string[]> {
+ const writtenPaths: string[] = [];
+ // function body
+ return writtenPaths;
+ }
+ ```
+ - Replace `{PlatformName}` with camelCase (e.g., `writeCursor`, `writeClaude`).
+ - Verify: Function is named `write{Platform}` and is the default export or named export.
- 4. **For SKILL.md files, prepend YAML frontmatter**
- - Frontmatter block must be first lines of file:
- ```yaml
- ---
- name: skill-name-kebab-case
- description: what this skill does
- ---
- ```
- - Follow with markdown body (no additional frontmatter separators)
- - Example:
- ```typescript
- const skillContent = `---
- name: example-skill
- description: does something useful
- ---
+ 4. Extract payload fields and compute target paths:
+ ```typescript
+ const { projectRoot, configs } = payload;
+ const outputDir = path.join(projectRoot, '.cursor', 'rules'); // example
+ ```
+ - Verify: `projectRoot` exists in payload and is an absolute path. Check existing writers for platform-specific directory conventions.
+ - This step uses output from Step 3.
- # Example Skill
+ 5. For each config to write, create directory with mkdirSync:
+ ```typescript
+ mkdirSync(outputDir, { recursive: true });
+ ```
+ - Verify: Directory creation succeeds or throws (do NOT catch and ignore).
+ - This step depends on Step 4.
- Instructions here...`;
- fs.writeFileSync(skillPath, skillContent, 'utf-8');
- ```
- - Verify: Skill file renders correctly with `cat .cursor/rules/example.md` and frontmatter is valid YAML
+ 6. Build file content string matching the platform's expected format:
+ - If YAML-based (Claude, Cursor): use `yaml.stringify()` from existing writers or format manually.
+ - If Markdown: build markdown string directly.
+ - If JSON: use `JSON.stringify()` with proper indentation.
+ - Verify: Content matches a sample from the codebase (e.g., run `caliber init` on test project).
+ - This step uses the payload from Step 3.
- 5. **Track written paths and return array**
- - Push each successfully written file path to `written` array
- - Paths must be relative to project root (e.g., `.cursor/rules/security.md`, not `/absolute/path`)
- - Example:
- ```typescript
- const skillPath = path.join(rulesDir, 'security.md');
- fs.writeFileSync(skillPath, skillContent, 'utf-8');
- written.push(path.relative(process.cwd(), skillPath));
- return written;
- ```
- - Verify: All returned paths use forward slashes and are relative (no leading `/`)
+ 7. Write file synchronously:
+ ```typescript
+ const filePath = path.join(outputDir, 'filename.ext');
+ writeFileSync(filePath, content, { encoding: 'utf-8' });
+ writtenPaths.push(filePath);
+ ```
+ - Verify: File exists on disk after write. Check with `fs.existsSync(filePath)`.
+ - This step uses output from Steps 5 and 6.
- 6. **Export function in `src/writers/index.ts`**
- - Add named export: `export { writeCursorRules } from './cursor';`
- - Verify: `npm run build` succeeds and function is importable from `src/writers/index.ts`
+ 8. For SKILL.md files specifically, check if `configs.skills` is populated:
+ ```typescript
+ if (payload.configs.skills && payload.configs.skills.length > 0) {
+ const skillContent = buildSkillFrontmatter(payload.configs.skills);
+ // write skill file
+ }
+ ```
+ - Verify: Frontmatter structure matches `src/writers/claude/index.ts` or `src/writers/cursor/index.ts` examples.
+ - This step uses payload from Step 3.
+ 9. Register the new writer in `src/writers/index.ts` by importing and calling it:
+ ```typescript
+ import { write{PlatformName} } from './{platform}';
+ // in writeSetup():
+ const paths = await write{PlatformName}(payload);
+ writtenPaths.push(...paths);
+ ```
+ - Verify: `writeSetup()` calls the function and collects returned paths.
+ - This step depends on Step 3.
+
+ 10. Add unit tests in `src/writers/__tests__/{platform}.test.ts`:
+ - Mock `fs.writeFileSync` and `mkdirSync` using `vi.mock('fs')`.
+ - Verify that returned paths match written files.
+ - Test payload validation (missing fields should throw).
+ - Verify: Tests pass with `npm run test -- src/writers/__tests__/{platform}.test.ts`.
+
## Examples
- **User says:** "Add a new writer for generating JSON config files in `.caliber/config.json`"
+ **User says:** "Add a writer for GitHub Copilot that writes to `.github/copilot-instructions.md`"
**Actions taken:**
- 1. Create `src/writers/json-config.ts`
- 2. Write function signature:
- ```typescript
- import fs from 'fs';
- import path from 'path';
-
- export async function writeJsonConfig(config: Config): Promise<string[]> {
- const written: string[] = [];
- const configDir = path.join(process.cwd(), '.caliber');
- fs.mkdirSync(configDir, { recursive: true });
-
- const configPath = path.join(configDir, 'config.json');
- fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
- written.push(path.relative(process.cwd(), configPath));
-
- return written;
- }
- ```
- 3. Add to `src/writers/index.ts`: `export { writeJsonConfig } from './json-config';`
- 4. Run `npm run build` — verify no errors
- 5. Return: `['.caliber/config.json']`
+ 1. Create `src/writers/github-copilot/index.ts` (note: directory may already exist).
+ 2. Import `path`, `writeFileSync`, `mkdirSync` from fs.
+ 3. Define `export async function writeGithubCopilot(payload: WriterPayload): Promise<string[]>`.
+ 4. Extract `payload.projectRoot` and compute `path.join(projectRoot, '.github')`.
+ 5. Call `mkdirSync(path.join(projectRoot, '.github'), { recursive: true })`.
+ 6. Build markdown content from `payload.configs.claudeMd` and rules.
+ 7. Write file: `writeFileSync(path.join(projectRoot, '.github', 'copilot-instructions.md'), content, { encoding: 'utf-8' })`.
+ 8. Return `[path.join(projectRoot, '.github', 'copilot-instructions.md')]`.
+ 9. In `src/writers/index.ts`, import and call: `const ghPaths = await writeGithubCopilot(payload); writtenPaths.push(...ghPaths);`
+ 10. Write tests verifying file creation, content structure, and error handling.
- **User says:** "Add a skill writer that generates SKILL.md files with YAML frontmatter"
+ **Result:** When `caliber init` runs, GitHub Copilot instructions are written alongside Claude and Cursor configs.
- **Actions taken:**
- 1. Create `src/writers/skills.ts`
- 2. Write function:
- ```typescript
- export async function writeSkills(skills: Skill[]): Promise<string[]> {
- const written: string[] = [];
- const skillsDir = path.join(process.cwd(), '.cursor', 'rules');
- fs.mkdirSync(skillsDir, { recursive: true });
-
- for (const skill of skills) {
- const content = `---
- name: ${skill.name}
- description: ${skill.description}
- ---
+ ## Anti-patterns
- ${skill.body}`;
- const skillPath = path.join(skillsDir, `${skill.name}.md`);
- fs.writeFileSync(skillPath, content, 'utf-8');
- written.push(path.relative(process.cwd(), skillPath));
- }
- return written;
- }
- ```
- 3. Export in `src/writers/index.ts`
- 4. Verify with: `cat .cursor/rules/example-skill.md` shows valid frontmatter
+ 1. **DO NOT use async/await for file I/O.** ❌ Wrong: `await writeFile()`, `await mkdir()`. ✅ Correct: Use `writeFileSync()` and `mkdirSync()`. All writers in the codebase use blocking I/O for simplicity and atomicity.
- ## Common Issues
+ 2. **DO NOT swallow fs errors with try/catch.** ❌ Wrong: `try { mkdirSync(...) } catch (e) { /* ignore */ }`. ✅ Correct: Let errors propagate — the caller in `src/writers/index.ts` logs them. Silent failures break undo/backup tracking.
- **Error: `ENOENT: no such file or directory`**
- - Cause: Target directory does not exist
- - Fix: Add `fs.mkdirSync(targetDir, { recursive: true })` before `fs.writeFileSync()`
- - Verify: `ls -la .cursor/rules/` shows directory was created
+ 3. **DO NOT call writer functions directly; return file paths and let `writeSetup()` aggregate them.** ❌ Wrong: Calling `writeGithubCopilot()` in a loop manually. ✅ Correct: Return `string[]` from your function and let `src/writers/index.ts` collect and track them.
- **Error: `EACCES: permission denied`**
- - Cause: No write permissions to target directory
- - Fix: Check file permissions: `ls -la .cursor/` and ensure current user owns directory
- - If using Docker: ensure volume mounts have correct permissions
+ ## Common Issues
- **Error: `Function returns Promise but should return string[]`**
- - Cause: Forgot `async` keyword in function declaration
- - Fix: Change `function writeCursor(...)` to `async function writeCursor(...)`
- - Verify: Return type is `Promise<string[]>` not `string[]`
+ **Error: "ENOENT: no such file or directory, open '/path/to/file'"**
+ - Cause: `mkdirSync()` was not called before `writeFileSync()`.
+ - Fix: Always call `mkdirSync(dirPath, { recursive: true })` before writing to that directory. Check Step 5.
- **Frontmatter not rendering in SKILL.md**
- - Cause: YAML block not first lines of file or missing closing `---`
- - Fix: Ensure template is exactly:
- ```
- ---
- name: skill-name
- description: description
- ---
-
- # Markdown body starts here
- ```
- - Verify: `head -5 .cursor/rules/skill.md` shows `---` on line 1 and line 4
+ **Error: "TypeError: payload.configs is undefined"**
+ - Cause: `WriterPayload` is not destructured correctly or type validation is missing.
+ - Fix: Add explicit type check: `if (!payload || !payload.configs) throw new Error('Invalid payload');` at function start. Verify `WriterPayload` import from `src/llm/types.ts`.
- **Returned paths have absolute paths instead of relative**
- - Cause: Forgot to use `path.relative(process.cwd(), fullPath)`
- - Fix: Always wrap full paths with `path.relative(process.cwd(), ...)`
- - Verify: `console.log(written[0])` shows `.cursor/rules/...` not `/home/user/project/...`
+ **Undo/backup files not created when writer runs**
+ - Cause: Writer function was called outside `writeSetup()` or returned paths were not collected.
+ - Fix: Ensure the writer is registered in `src/writers/index.ts` and `writeSetup()` collects returned paths: `writtenPaths.push(...resultPaths);`. Verify with `npm run test -- src/writers/__tests__/get-files-to-write.test.ts`.
- **Export not found in src/writers/index.ts**
- - Cause: Function not added to barrel export
- - Fix: Add `export { writeNewFormat } from './new-format';` to `src/writers/index.ts`
- - Verify: `npm run build` succeeds and `import { writeNewFormat } from './writers'` works
+ **SKILL.md frontmatter appears as markdown text instead of parsed metadata**
+ - Cause: Frontmatter was not returned as `{ frontmatter: string, body: string }` or structure doesn't match YAML spec.
+ - Fix: Frontmatter must be `---\nkey: value\n---\n` at the start of the file. Check `src/writers/claude/index.ts` for the exact format. Use `yaml.stringify()` for consistency.