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):
```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*