feat: Out-of-the-box compatibility with all AI tools — generate all tool configs from agent.yaml

[iliassjabali]

Problem

AgentSpec currently only generates for LangGraph and has Claude Code (CLAUDE.md) baked in. Every major AI coding tool has its own config convention:

Tool	Config file
Claude Code	CLAUDE.md
OpenAI Codex	AGENTS.md
OpenCode	AGENTS.md + optional opencode.json
Gemini CLI	.gemini/GEMINI.md or .gemini/config.yaml
Cursor	.cursor/rules
Windsurf	.windsurfrules
Continue	.continue/config.yaml

Users shouldn't need to install separate adapter packages or pick a framework. agent.yaml should be the single source of truth, and AgentSpec should generate all of these from it automatically.

---

Proposed solution: Universal agentspec sync command

A new agentspec sync <manifest> command that reads agent.yaml and writes all tool config files at once. No adapters. No framework selection. Just one command.

agentspec sync agent.yaml

Output:

✓ CLAUDE.md       (Claude Code)
✓ AGENTS.md          (OpenAI Codex + OpenCode)
✓ opencode.json      (OpenCode — model/tool bindings)
✓ .gemini/GEMINI.md  (Gemini CLI)
✓ .cursor/rules   (Cursor)
✓ .windsurfrules  (Windsurf)

Every tool in the project automatically gets the right context from the same manifest.

---

What each generated file contains (all derived from agent.yaml)

All files are generated from the same fields: metadata.name, metadata.description, spec.model, spec.tools, spec.prompts.system, spec.guardrails.

AGENTS.md (Codex):

# <name>
<description>

## Model
<provider> / <model-id>

## Tools
- tool-name: description

## Instructions
<system prompt>

## Guardrails
<guardrail rules>

.gemini/GEMINI.md (Gemini CLI):
Same structure — Gemini CLI reads markdown files in .gemini/.

.cursor/rules (Cursor):
Same content adapted for Cursor's rules format.

.windsurfrules (Windsurf):
Plain markdown, same content.

CLAUDE.md (already exists — keep generating it as today).

---

Tasks

Core: agentspec sync command

• Add packages/cli/src/commands/sync.ts
• Register command in packages/cli/src/cli.ts
• Load and validate manifest with existing loadSpec()
• Generate all tool config files from manifest fields
• Support --only <tool> flag to generate a single file (e.g. --only codex)
• Support --dry-run flag to preview without writing
• Print summary table of written files

File generators (plain functions, no adapter packages)

• generateClaudeMd(spec) → CLAUDE.md
• generateAgentsMd(spec) → AGENTS.md (shared by Codex + OpenCode)
• generateOpencodeJson(spec) → opencode.json
• generateGeminiMd(spec) → .gemini/GEMINI.md
• generateCursorRules(spec) → .cursor/rules
• generateWindsurfRules(spec) → .windsurfrules

All functions live in packages/cli/src/commands/sync/generators.ts — no new packages.

Watch mode (nice to have)

• agentspec sync --watch re-generates on agent.yaml changes

Tests

• Unit test each generator function with a fixture manifest
• Integration test: agentspec sync writes expected files to a temp dir

Docs

• Add sync command to CLI reference in docs/
• Update README with "works out of the box with all tools" messaging

---

CLI usage

# Sync all tool configs
agentspec sync agent.yaml

# Only generate for Codex
agentspec sync agent.yaml --only codex

# Preview without writing
agentspec sync agent.yaml --dry-run

# Watch for changes
agentspec sync agent.yaml --watch

---

Acceptance criteria

• agentspec sync generates correct files for Claude Code, Codex, OpenCode, Gemini, Cursor, Windsurf
• All files are derived solely from agent.yaml — no extra config needed
• --dry-run prints diff without writing
• --only <tool> restricts output to one tool
• No new packages required — all generators are plain functions in the CLI package
• Existing agentspec generate (LangGraph code gen) is unchanged