Imported from marcoskichel/empire (AGENTS.md). Install upstream with npx skills add marcoskichel/empire. Copyright stays with the author.

AGENTS.md

This file provides guidance for AI agents working with code in this repository.

Repo nature

• Claude Code plugin marketplace. No build, no lint, no test harness.
• Single marketplace (.claude-plugin/marketplace.json) exposes six plugins: empire (meta bundle), empire-git, empire-dev, empire-research, empire-product, empire-visual. Plus empire-rules (utility, auto-installed as a transitive dependency).
• Plugin content = markdown SKILL files, dynamic-workflow .js scripts (in empire-research and empire-dev), and bash scripts in empire-git.
• Validation = .github/workflows/validate.yml: pre-commit and manifest + SKILL.md spec checks; plus install-and-invoke in Claude Code.

Layout

• .claude-plugin/marketplace.json — marketplace manifest. Each plugins[] entry points to one of the plugins/empire-* dirs.
• plugins/empire-meta/.claude-plugin/plugin.json — meta plugin (name: "empire"). Empty skills dir. Uses dependencies field to auto-install the sub-plugins.
• plugins/empire-git/ — git workflow skills (worktree-*, pr-description, pr-merge) + bash scripts/.
• plugins/empire-dev/ — code team-review skill, address-review skill (driven by workflows/address-review.js), pre-implementation engineering skills (shape, weigh, slice), plus 12 bundled dev subagents (code review, paradigms, domain experts).
• plugins/empire-research/ — explore (open-ended), compare (closed), and dissect (claim investigation) research skills + workflows/*.js orchestration scripts, with research-analyst as bundled fallback subagent.
• plugins/empire-product/ — product skills (pitch, vet, recon, mint, distill, probe), plus three bundled subagents (project-idea-validator, competitive-analyst, market-researcher).
• plugins/empire-visual/ — visual-first output style (in output-styles/) + on-demand visualize skill for terminal-native ASCII diagrams. No subagents.
• plugins/empire-*/skills/<skill-name>/SKILL.md — one dir per skill. Skill name in frontmatter MUST match dir name.
• plugins/empire-*/workflows/<name>.js — dynamic-workflow scripts a skill drives through whatever JS workflow runner the host exposes (Claude Code Workflow({scriptPath}), pi workflow({scriptPath})); a copy is bundled into the skill dir via SCRIPT_BUNDLES so non-Claude hosts can resolve it. Plain JS run by the Claude Code workflow runtime; no package.json, no build. The runtime sometimes hands args over as a JSON string, so every script MUST start its arg reads with const input = typeof args === "string" ? JSON.parse(args) : args; and read fields off input, never off args (a raw args.foo throws before any agent launches, giving a 0/0 agents run). Scripts run in a vm context with no imports, so this line is copied per file by necessity.
• plugins/empire-*/README.md — one per plugin. Plugin-specific docs (skills list, triggers, source links). Root README.md is the project intro and links to these.
• docs/superpowers/{specs,plans}/ — gitignored. Local-only design notes. Never commit.

Skill authoring rules

• Use /skill-creator if available
• Frontmatter required: name, description. Optional: model, allowed-tools, argument-hint, disable-model-invocation.
• description MUST list trigger phrases verbatim — Claude auto-route uses them.
• Reference bundled scripts via ${CLAUDE_PLUGIN_ROOT}/scripts/<file>.sh. Never hardcode repo paths.
• Reference bundled workflows via ${CLAUDE_PLUGIN_ROOT}/workflows/<file>.js for Claude Code's Workflow tool, and via the skill-dir copy for other hosts' runners (pi's workflow). A skill that drives a workflow MUST document an inline-Agent fallback for hosts with no runner.
• Users invoke skills as /<plugin>:<skill-name> once installed. Plugin namespaces: empire-git, empire-dev, empire-research, empire-product, empire-visual. The meta empire plugin contributes no skills.
• After editing a SKILL.md, also update the matching section in the plugin's README.md (plugins/<plugin>/README.md) if triggers, args, or behavior changed. Update root README.md only if the one-line plugin description in the plugins table needs to change.

Codex parity

• Skills ship to both Claude Code (marketplace) and OpenAI Codex via skills.sh (npx skills add marcoskichel/empire -a codex), which reads marketplace.json. Keep SKILL.md bodies platform-neutral.
• Reference skill-bundled resources with relative paths (references/<file>.md, scripts/<file>) — not ${CLAUDE_PLUGIN_ROOT}. Relative refs resolve on both platforms and stay valid when skills.sh copies the skill dir verbatim. empire-git skills keep a ${CLAUDE_PLUGIN_ROOT}/scripts/ reference for Claude Code alongside a per-skill bundled scripts/ copy for other agents.
• Qualify Claude-only tools in bodies (e.g. "Claude Code: the Agent tool; other agents: their spawn mechanism"). Avoid bare /plugin:skill cross-refs in bodies; write "the <skill> skill".
• scripts/sync-codex.sh generates the Codex artifacts: personas bundled into dispatching skills (team-review, vet, recon, explore, compare), empire-git's shared scripts bundled per-skill (SCRIPT_BUNDLES), and the .agents/skills mirror. Run it after changing an agent or a bundled script; CI enforces sync via scripts/sync-codex.sh --check.
• .agents/skills/ is a generated symlink mirror for project-local Codex discovery. Never hand-edit; run scripts/sync-codex.sh.
• Output styles (empire-visual visual-first) are Claude-only; Codex has no output-style concept, so only skills port.

Adding a new skill

1. Use /skill-creator if available
2. Pick the right plugin (empire-git, empire-dev, empire-research, empire-product, or empire-visual). Create a new plugin only if the skill clearly fits no existing namespace.
3. Create plugins/<plugin>/skills/<name>/SKILL.md with frontmatter + body. Frontmatter name MUST match dir name.
4. Add a section to the plugin's README.md (plugins/<plugin>/README.md) under ## Skills, mirroring existing entries (description, triggers, source link). If the plugin's one-line summary in the root README.md table is now out of date, update it too.
5. If shipping a script, drop it in plugins/<plugin>/scripts/ and chmod +x.
6. Bump the version in plugins/<plugin>/.claude-plugin/plugin.json. If the change is user-visible across multiple sub-plugins, also bump plugins/empire-meta/.claude-plugin/plugin.json.
7. Test by installing the marketplace locally in Claude Code: /plugin marketplace add <local-path-or-fork> then /plugin install <plugin>@empire (or empire@empire for the bundle).

Conventions

• Kebab-case for skill dirs and script filenames.
• Conventional Commits with optional scope. Use the plugin name as scope: empire-git, empire-dev, empire-research, empire-product, empire-visual, empire-meta, empire-rules. Use marketplace for marketplace-level changes. Use ! for breaking marketplace/manifest changes.
• Skill prose voice depends on plugin:
  • empire-dev, empire-product, empire-research, empire-visual, empire-rules: imperative mood, MUST/SHOULD/MAY, fragments, <section> tags. See plugins/empire-dev/skills/team-review/SKILL.md as the reference.
  • empire-git: procedural prose with ## Step N headers permitted. Command-style tools read more clearly as numbered procedures than as fragment lists. See plugins/empire-git/skills/worktree-open/SKILL.md as the reference.
• allowed-tools declaration:
  • Declare on skills that directly invoke Bash/Read/Glob/Grep (e.g. worktree-*, sync-rules, pr-description).
  • Do NOT declare on skills that purely delegate to subagents via Agent tool (e.g. team-review, vet, recon, compare, explore, pitch).
• Bash scripts use set -euo pipefail, color-coded info/warn/die/success helpers (pattern in worktree-setup.sh).
• Node scripts (if any): dependency-free ESM, shell out to gh, no package.json/build. Keep pure logic exported and covered by a *.test.mjs (node --test); guard main() so importing for tests does not run it.

Formatting and linting

• All formatting + security hooks orchestrated by pre-commit (config in .pre-commit-config.yaml).
• Tools: prettier (markdown/yaml/json), shfmt (shell), shellcheck (shell security), actionlint (GH Actions), gitleaks (secrets).
• One-time dev setup: brew install pre-commit && pre-commit install.
• CI runs identical checks via .github/workflows/validate.yml.
• Never bypass with --no-verify. If a hook fails, fix the underlying issue.

What this repo is NOT

• Not a Node/Python/Go project. No package.json, no pyproject.toml, no build — keep it that way; don't add a build system or runtime deps unless asked.
• Not a backend. Skills run inside Claude Code on the user's machine. Assume zero server-side state.