tamirs-superpowers / rules

---
description: "Core facts about this repo — what it is, what NOT to do, and how it is distributed"
alwaysApply: true
---

# tamirs-superpowers — plugin structure

A **multi-platform agent plugin** (Markdown + JSON + Bash only) for five platforms and six runtime surfaces: Claude (Claude Code, Claude Desktop), Codex CLI, Cursor IDE, Gemini CLI, and OpenCode CLI. No build step, no `package.json`, no compiled output.

Policy is canonical and lives once: `AGENTS.md` is the shared entrypoint, `core/` holds the portable framework (policies, roles, workflow schemas, capabilities), `rules/` holds contributor rules. These `.mdc` files are thin Cursor adapters — when one disagrees with a canonical rule, the canonical rule wins.

## What lives where

| Path | Purpose |
|------|---------|
| `AGENTS.md` | Shared entrypoint — read first |
| `core/` | Portable policies, roles, workflow schemas, capability facts |
| `rules/` | Canonical contributor rules (index: `rules/README.md`) |
| `plugin-version.json` | Single source of truth for the version |
| `.cursor-plugin/plugin.json` | Cursor manifest (skills + MCP; no hooks) |
| `skills/<domain>/<name>/SKILL.md` | One skill per folder; directory name = slash command |
| `hooks/` | Hook wiring + scripts (Claude Code and Codex load these; Cursor does not) |
| `scripts/` | User-facing scripts and validators — **no** `.sh` at repo root |
| `.mcp.json` | MCP server stubs (env var placeholders only — no real tokens) |

## Hard constraints

- No `runs-on: [self-hosted]` in any CI workflow — use `ubuntu-latest`
- No secrets or tokens committed — `.mcp.json` uses `${ENV_VAR}` syntax only
- No employer-internal references anywhere
- No `marketplace.json` in this repo — published through `Tamircohen28/tamirs-marketplace`
- `SKILL.md` frontmatter validates against `core/schemas/skill-frontmatter.json`

## Validate after every change

```bash
make validate
```

## Version bump after shipped changes

Edit `plugin-version.json`, then `bash scripts/check-version-truth.sh --sync`. Canonical rule: `rules/dev/plugin-version-bump.md`.