artibot

Imported from Yoodaddy0311/artibot (plugins/artibot/AGENTS.md). Install upstream with npx skills add Yoodaddy0311/artibot --skill artibot. Copyright stays with the author.

AGENTS.md — Cross-Tool Parity Seed

Scope: Artibot plugin (plugins/artibot/) Purpose: make Artibot's 30 agents + 114 skills + 80 commands usable not just from Claude Code but also from Cursor, Codex CLI, OpenCode, Windsurf, and Antigravity.

AGENTS.md is a cross-tool convention adopted by everything-claude-code and similar ecosystems. Each consumer tool reads this file (directly or via export) to register agents locally. Artibot's source of truth remains plugins/artibot/agents/*.md with Claude Code–style frontmatter; everything else is a projection of that.

1. Overview

The direct degradation mode already lists the supported non–Claude Code platforms: cursor, codex-cli, windsurf, antigravity (plus gemini-cli). AGENTS.md is the portable contract those runtimes consume.

Setup & Testing

Non–Claude Code tools do not read CLAUDE.md. This section mirrors the contributor-facing build/test/quality rules from CLAUDE.md so a tool that reads only AGENTS.md still knows how to verify a change. CLAUDE.md remains canonical — if the two ever disagree, CLAUDE.md wins.

Commands

Run these from plugins/artibot/.

Quality gates

• Read before write (no blind modifications)
• Functions < 50 lines, files < 800 lines
• Immutable patterns (spread/create new, never mutate)
• No hardcoded secrets or credentials (use env vars / ${ENV_VAR} placeholders)
• Coverage CI gate (scripts/ci/validate-coverage.js): Statements 85 / Branches 76 / Functions 85 / Lines 85 (the vitest.config.js local gate is 80/76/80/80)

Full contributor rules: see CLAUDE.md (Quality Gates + Testing sections) — this section is a projection of it, not an independent source.

2. Tool-by-tool mapping

2.1 Cursor

• Target path: .cursor/rules/<agent-name>.mdc
• Frontmatter: description, globs, alwaysApply
• Body: the agent's system prompt, verbatim.

2.2 Codex CLI

• Target: AGENTS.md at repo root (plain Markdown index) plus .codex/agents/<agent-name>.md for each agent body.
• Codex CLI auto-discovers AGENTS.md in the working tree.

2.3 OpenCode

• Target: .opencode/agents.json — single JSON array, one object per agent with name, model, systemPrompt, tools.

2.4 Windsurf

• Target: .windsurfrules for global guidance, .windsurf/workflows/<name>.md per command-equivalent.

2.5 Antigravity

• Target: same convention as Codex CLI (AGENTS.md + body files). Additional .antigravity/config.yaml maps Artibot categories to Antigravity roles.

Skills, Personas, Commands — How / Who / When

Artibot's three-layer behavioral model. Every agent interaction activates one or more of these layers:

Layer interaction rules

• A single request can activate one Skill, one Persona, and one Command simultaneously.
• Skills fire first (they gate the how), then Personas apply judgment within that process, then Commands provide the lifecycle wrapper.
• Skills are reusable across commands — tdd-workflow runs inside both /build and /test.
• Personas are reusable across skills — persona-architect applies judgment within spec-format, tool-design, and multi-agent-patterns.
• Commands are not reusable — each command owns its lifecycle phase and is entered once per phase boundary.

Distinguishing Skills from Personas

3. Conversion rules — Claude Code frontmatter → other tools

3.1 Source frontmatter (Claude Code)

---
name: backend-developer
description: Production-grade backend implementation with TDD.
model: opus
category: expert
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

3.2 Per-tool projection

3.3 Model policy mapping

Exporters that target non-Anthropic runtimes substitute a sane default; users override in the destination tool's config.

Single source of truth: the per-agent tier→model resolution is owned by lib/core/model-policy.js (resolveModel / resolveModelForPhase), reading artibot.config.json#/agents/modelPolicy. The table above is a projection of that resolver for export targets — do not treat it as an independent source.

4. Constraints & non-portable surface

Rule of thumb: if a feature depends on the Agent Teams API, it collapses to sequential execution on export. Users of non–Claude Code tools see graceful-degradation.mode = "direct" behavior described in artibot.config.json.

5. Install / activation guides

5.1 Claude Code (native)

# Already works — just enable the plugin
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# plugins/artibot/ is auto-discovered

5.2 Cursor

node plugins/artibot/scripts/export-to-tool.mjs --tool cursor --out ./.cursor/rules/
# Restart Cursor; agents appear under Rules for AI.

5.3 Codex CLI

node plugins/artibot/scripts/export-to-tool.mjs --tool codex --out ./
# Codex CLI will read AGENTS.md at next `codex` invocation.
codex agents list

5.4 OpenCode

node plugins/artibot/scripts/export-to-tool.mjs --tool opencode --out ./.opencode/
opencode agents reload

5.5 Windsurf

# Windsurf export is planned for v0.5.2.
# Manual bridge today: copy AGENTS.md content into .windsurfrules.
cp plugins/artibot/AGENTS.md .windsurfrules

5.6 Antigravity

# Antigravity reads AGENTS.md natively; no export needed beyond symlink.
ln -s plugins/artibot/AGENTS.md ./AGENTS.md

6. Agent catalogue (summary)

Full list: plugins/artibot/agents/*.md or artibot.config.json → agents.categories.

7. Community contribution

• Add a new target tool: create a converter in scripts/export-to-tool.mjs following the existing stub layout; add a row to §2 and §3.
• Improve an existing conversion: open a PR touching the converter + a fixture in test/fixtures/export-<tool>/.
• Report parity gaps: file an issue titled [parity] <tool>: <feature> with the Claude Code behaviour and what the other tool produced.

All contributions must respect Artibot's local-only data policy — exports happen on the contributor's machine, never via a hosted service.

8. Version alignment

Current plugin version: 4.69.0. That is 11 entries across 10 files — marketplace.json contributes two (version and release.current). Keep all eleven in lockstep; scripts/release-check.js enforces every one of them and exits 1 on any mismatch.

The entries added to the gate later are the ones that historically drifted, because until then nothing enforced them: the two README badges (the GitHub-visible root one in particular), and the marketplace JSON files, whose drift silently routes Claude Code's per-version plugin cache to stale code (2026-06-08 incident: 4.13.1 vs 4.19.6).

Two further checks live in the same script and are easy to miss:

• CHANGELOG entry — CHANGELOG.md must contain a level-2 heading for the current version; the square brackets are optional, so both ## [X.Y.Z] and ## X.Y.Z match. A missing entry is a blocking failure (exit 1), not a warning.
• Installed-copy drift — warns (exit 2, non-blocking) when ~/.claude/artibot/ is behind the source. Note the scope: it inspects only that one path. The marketplace mirror at ~/.claude/plugins/marketplaces/artibot/ and any copy under ~/.claude/plugins/artibot/ are not checked, so a green release check does not mean every local copy is current. npm run sync:local updates the direct install; the git-managed marketplace mirror needs claude plugin marketplace update artibot instead.

Release gate: install & update verification

Every release MUST also pass install/update integrity checks — npm run ci (and therefore npm run release) runs scripts/ci/validate-install.js, which:

• asserts install.sh ↔ install.ps1 feature parity (a capability matrix — adding a post-install step to one installer without the other fails the release; this is the drift that historically broke cross-machine /update on Windows)
• verifies scripts/update.js / scripts/update-platform.js still reference both installers and pass node --check
• best-effort bash -n install.sh and PowerShell parse of install.ps1 when those hosts are available (skipped with a warning on CI runners that lack them)

When you add or rename an install/update step, update PARITY_MATRIX in scripts/ci/validate-install.js so the parity check stays meaningful.

9. References

• Cross-tool seed project: https://github.com/stretchcloud/everything-claude-code
• Cursor rules format: https://docs.cursor.com/context/rules-for-ai
• Codex CLI agents: https://developers.openai.com/codex/cli
• OpenCode: https://opencode.ai
• Windsurf cascade: https://docs.codeium.com/windsurf
• Artibot degradation modes: plugins/artibot/artibot.config.json → team.gracefulDegradation.modes