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.