phoenixvc

retort

One YAML spec. Consistent AI agent configs for every tool your team uses.

Every AI coding assistant has its own config format — CLAUDE.md, .cursor/rules/, .windsurf/rules/, GEMINI.md, .junie/guidelines.md, AGENTS.md, and more. Keeping them in sync by hand means duplicated effort and drift. retort solves this: describe your project once, run retort sync, and get correct, project-aware configs for all 16 supported tools — automatically, on every sync.

---

Supported targets

Tool	Output
Claude Code	.claude/ — CLAUDE.md, agents, commands, rules, hooks, skills
Cursor	.cursor/rules/, .cursor/commands/, team configs
Windsurf	.windsurf/rules/, .windsurf/teams/, workflows
GitHub Copilot	.github/copilot-instructions.md, chat modes, prompts
Gemini CLI	GEMINI.md, .gemini/
Codex / OpenAI	.agents/skills/
JetBrains Junie	.junie/guidelines.md ✓ shipped
Cline	.clinerules/
Roo Code	.roo/rules/
Warp	WARP.md
VS Code	.vscode/settings.json (brand-driven theme + editor config)
GitHub Actions	.github/workflows/ — CI, branch protection, drift check
MCP / A2A	.mcp/servers.json, a2a-config.json
Docs	AGENTS.md, AGENT_TEAMS.md, QUALITY_GATES.md, RUNBOOK_AI.md

---

How it works

.agentkit/spec/project.yaml    ← describe your project once
.agentkit/spec/teams.yaml      ← agent teams and their scopes
.agentkit/spec/commands.yaml   ← slash commands
.agentkit/spec/rules.yaml      ← coding rules by domain
           ↓
       retort sync
           ↓
CLAUDE.md  .claude/  .cursor/  .windsurf/  GEMINI.md
.junie/  .agents/  .github/  WARP.md  AGENTS.md  ...

The sync engine reads your specs, renders Handlebars templates for each target tool, and writes the output. Generated files include a GENERATED — DO NOT EDIT header so the engine can detect drift. Running sync again is safe and idempotent.

---

Quick start

# Use as a GitHub template, then:
npx retort init       # scans your repo, writes project.yaml interactively
npx retort sync       # generates all tool configs

# Or via pnpm after installing locally:
pnpm --dir .agentkit retort:sync

After sync, commit the generated output alongside your spec changes. The CI drift check will fail if you forget.

# Check what would change without writing:
npx retort sync --diff

# Regenerate only specific targets:
npx retort sync --only claude,cursor

# Interactive apply — confirm each changed file:
npx retort sync --interactive

---

Agent teams

retort generates configs for 13 built-in agent teams, each with a defined scope, accepted task types, and slash command: