# AGENTS.md

<!-- SUPERPOWERS_SKILLS_START -->
## 🎯 SKILLS

Skills extend your capabilities with proven workflows.

### Discover Skills First

**Before starting any task**, check for relevant skills:
1. Use your native skill tool to list available skills.
2. Review skill descriptions/frontmatter to identify relevant ones.

### Skill Loading Rules

- Load skills **JIT only** — never preload to "understand" them.
- Follow skill instructions **exactly as written** — no skimming, no shortcuts.
- If a skill has a checklist, create a todo for **each item** — no mental tracking.
- Simple tasks benefit from skills as much as complex ones.

**Skill priority (highest to lowest):** Project → Personal

### Using Tools with Skills

1. **Native skill tool** — load skills via your platform's native skill tool.
2. **Symlinked skills** — Superpowers skills are symlinked into your platform's skills directory.
3. **Fallback** — if a skill isn't found via the native tool, inspect the configured skill directories and read its `SKILL.md` directly.
4. **Tool equivalence** — when a skill references a tool you don't have, substitute your equivalent.

### Why Skills Matter

Skills encode proven techniques that prevent mistakes. Not using them means repeating solved problems and missing edge cases.

**If a skill exists for your task, you MUST use it.**

---

## Version Check

Periodically, e.g. once per day check the version of superpowers-agent:
1. **CURRENT_VERSION** — run a `superpowers-agent` command and extract `X.Y.Z` from the `^^SAV:X.Y.Z^^` string in its output.
2. **NPM_LATEST_VERSION** — run `npm view @complexthings/superpowers-agent version`.
3. Compare by **semver precedence, not string comparison** (e.g. `9.10.0` > `9.9.0`). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:
   > Your superpowers-agent has updates (`CURRENT_VERSION` → `NPM_LATEST_VERSION`). Run:
   > ```sh
   > npm install -g @complexthings/superpowers-agent
   > superpowers-agent bootstrap && superpowers-agent setup-skills
   > ```
   If versions match, or either lookup fails (e.g. no network), continue silently.

---

*Generated by Superpowers on 2026-07-12*
<!-- SUPERPOWERS_SKILLS_END -->

## What This Project Is

**Superpowers Agent** is a CLI (`superpowers-agent`, alias `superpowers`) that manages reusable markdown-based "skills" for AI coding assistants. It delivers skills to Claude, GitHub Copilot, Cursor, Gemini, OpenCode, and Codex. Skills live in `skills/` (this repo) and `.agents/skills/`, and bootstrap symlinks them into each assistant's config directory. Published to npm as `@complexthings/superpowers-agent`.

## Build & Development

The CLI source lives in `.agents/` and is built with **Bun** (`packageManager: bun@1.3.8`). Run scripts from the `.agents/` directory:

```bash
cd .agents
bun run build            # Build minified ESM bundle → .agents/superpowers-agent
bun run watch            # Build in watch mode
bun run dev              # Run CLI from source (bun src/cli.js)
bun run dev:link         # Symlink the `superpowers-agent` bin to the dev source
bun run production:link  # Symlink the bin to the built bundle
```

The build (`.agents/build.js`) uses the `Bun.build` API, so it must run under **bun**, not node. Output is `.agents/superpowers-agent` — a polyglot shebang script that execs `bun` if present, otherwise `node`.

The CLI has **no runtime dependencies** (pure Node.js/Bun built-ins). The only dev dependency is `husky`. Node engines: `^20 || ^22 || ^24`.

## Testing

Run the automated test suite from `.agents` with `bun test`. There is no root-level test script; run CLI commands directly for manual acceptance checks.

## Architecture

### Source (`.agents/src/`)

| Layer | Files | Responsibility |
|-------|-------|---------------|
| CLI entry | `cli.js` | Command dispatch table |
| Commands | `commands/bootstrap.js`, `update.js`, `simple-commands.js` | Command implementations |
| Core | `core/config.js`, `paths.js`, `platform-detection.js`, `git.js` | Config, path resolution, platform detection, git helpers |
| Skills | `skills/finder.js`, `locator.js`, `installer.js`, `executor.js`, `parser.js` | Skill discovery, install, execution pipeline |
| Agents | `agents/installer.js`, `agents/platforms.js` | Install agent definitions (`.github/agents/*.agent.md`, `.opencode/agents/*.md`) into platform dirs |
| Integrations | `integrations/claude.js`, `codex.js`, `copilot.js`, `cursor.js`, `gemini.js`, `opencode.js` | Per-platform symlink/config setup |
| Utils | `utils/symlinks.js`, `frontmatter.js`, `output.js`, `file-ops.js` | Shared helpers |

### Skill Discovery Priority (highest → lowest)

1. `.agents/skills/` — project-level
2. `~/.agents/skills/` — personal cross-project
3. `~/.agents/superpowers/skills/` — bundled community skills

### CLI Commands

From `.agents/src/cli.js` dispatch table:

- **Core:** `bootstrap [--no-update] [--force]`, `version`, `check-updates`, `update [--no-reinstall]`
- **Config:** `config-get`, `config-set <key> <value>`
- **Skills:** `setup-skills`, `session-context [--format=claude|copilot|raw]`
- **Install/manage skills:** `add <url-or-path|@alias> [path]`, `add-repository <git-url> [--as=@alias]`, `list-repositories`, `pull <url-or-path|@alias>`, `rm <url-or-path|@alias>`
- **Integrations:** `install-cursor-hooks`, `install-aliases`

### Key Flows

- **`bootstrap`** → detects installed AI platforms → symlinks skills into each platform's skills dir → writes platform config files
- **Native skill tools** → discover and load skills from their configured directories
- **`add <url-or-path|@alias>`** → clones a git repo or copies a local path → installs skills into `~/.agents/superpowers/skills/`
- **`update`** → checks the npm registry for a newer version → reports if an update is available

### Skill Structure

Each skill is a directory with a `SKILL.md` file:

```
skills/
└── <category>/
    └── <skill-name>/
        ├── SKILL.md         # Frontmatter (name, description) + instructions
        ├── scripts/         # Optional support scripts
        └── resources/       # Optional templates/data
```

`SKILL.md` frontmatter fields: `name`, `description`, and optional `metadata` (e.g. `version`). The set of bundled skills and their lockfile state are tracked in `skill.json` and `skills-lock.json` at the repo root.

## Versioning & Publishing

The `.husky/pre-commit` hook keeps the root `package.json` and `.agents/package.json` versions in sync: on commit it picks the higher of the two, writes both, refreshes lockfiles, rebuilds the bundle (`cd .agents && bun install && bun run build`), and stages the affected files. Don't hand-edit one version without the other.

The package is published to npm as `@complexthings/superpowers-agent` (registry auth via the `COMPLEX_THINGS_NPM_TOKEN` in `.npmrc`). The current version is whatever `package.json` reports — do not hardcode it elsewhere.

## Agent skills

### Issue tracker

Issues and PRDs are tracked as GitHub issues on `complexthings/superpowers`, managed via the `gh` CLI. See `docs/agents/issue-tracker.md`.

### Triage labels

The five canonical triage roles use their default label strings (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.

### Domain docs

Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root (created lazily). See `docs/agents/domain.md`.

@RTK.md