AGENTS.md — Superpowers CN（中文触发词优化版）

This file is written for AI coding agents that have no prior context about the repository. It summarizes the project structure, runtime model, conventions, tests, and contribution rules. When this file conflicts with a more specific instructions file (e.g. CLAUDE.md, a per-directory AGENTS.md, or a user's direct request), the more specific instruction wins.

本项目是 Superpowers 的中文触发词优化版本，由 jnlk-cn 维护。核心技能文件已翻译为中文，并对 description 等触发元数据做了中文优化，使中文提示更容易激活对应工作流。

Project overview

Superpowers CN is a fork of the Superpowers agent-workflow plugin. It ships a library of agent "skills" (markdown documents with YAML frontmatter) that are loaded by multiple coding-agent harnesses:

• Claude Code (.claude-plugin/)
• Codex (.codex-plugin/)
• Cursor (.cursor-plugin/)
• Kimi Code (.kimi-plugin/)
• OpenCode (.opencode/)
• Pi (.pi/)
• Gemini CLI (gemini-extension.json + GEMINI.md)
• Antigravity, Copilot CLI, Factory Droid (covered by shared hooks / manifests)

The project is intentionally zero-dependency for the core skill library. Optional test harnesses have their own local dependencies (e.g. ws in tests/brainstorm-server).

Current version: 6.0.3 (kept in sync across plugin manifests by .version-bump.json and scripts/bump-version.sh).

Repository layout

Technology stack and runtime architecture

• Core content: Markdown + YAML frontmatter. No build step for the skills.
• Plugin code:
  • OpenCode plugin: ES module JavaScript (superpowers.js).
  • Pi extension: TypeScript loaded natively by Pi (superpowers.ts).
  • Claude / Codex / Cursor / Kimi / Gemini: JSON manifests + shell hooks or declared context files.
• Hook scripts: Bash, with a run-hook.cmd polyglot wrapper so the same dispatcher works on Windows (CMD) and Unix (bash).
• Tests: Bash, Node.js, Python. No top-level test runner; each test directory has its own run-*.sh script.

How it works at runtime

1. Bootstrap injection: At the start of every session the harness injects the full contents of skills/using-superpowers/SKILL.md into the model context, wrapped in <EXTREMELY_IMPORTANT> tags, plus the harness-specific tool mapping.
2. Skill auto-trigger: The bootstrap tells the model to check for relevant skills before acting. Skills are loaded through the harness's native skill mechanism (or read if no skill tool exists).
3. Action vocabulary: Skill bodies never name a specific harness's tools. They say things like "dispatch a subagent", "create a todo", "read a file". The harness-specific reference doc maps those actions to real tools.

Without the bootstrap, the skill files are inert — present on disk but never invoked.

Key configuration files

• package.json — package metadata, ES module type, Pi pi.extensions / pi.skills, OpenCode main.
• .claude-plugin/plugin.json + .claude-plugin/marketplace.json — Claude Code plugin and marketplace entries.
• .codex-plugin/plugin.json — Codex plugin manifest; points to hooks/hooks-codex.json.
• .cursor-plugin/plugin.json — Cursor plugin manifest; points to hooks/hooks-cursor.json.
• .kimi-plugin/plugin.json — Kimi Code plugin manifest; declares sessionStart.skill: using-superpowers and inline skillInstructions.
• gemini-extension.json — Gemini CLI extension manifest; declares contextFileName: GEMINI.md.
• GEMINI.md — Points Gemini at the bootstrap skill and the Gemini tool mapping.
• hooks/hooks.json, hooks/hooks-codex.json, hooks/hooks-cursor.json — Hook declarations for shell-hook harnesses.
• .version-bump.json — Declares all files that participate in version sync.
• .pre-commit-config.yaml — Runs ruff checks on the optional evals/ Python harness (only if evals/ is present).
• .gitignore — Ignores .worktrees/, .private-journal/, .claude/, .superpowers/, node_modules/, and the separately-cloned evals/.

Build and test commands

There is no top-level build. Individual test suites are run from their own directories.

Fast, harness-agnostic tests (recommended before committing):

# Shell hook output tests
bash tests/hooks/test-session-start.sh

# Shell-lint script self-tests
bash tests/shell-lint/test-lint-shell.sh

# Version sync check
bash scripts/bump-version.sh --check

# Lint changed shell scripts (requires shellcheck; shfmt optional)
bash scripts/lint-shell.sh

Per-harness plugin tests:

# Brainstorm server (Node tests + shell platform tests)
cd tests/brainstorm-server
npm install   # if needed
npm test

# OpenCode plugin (no OpenCode required by default)
bash tests/opencode/run-tests.sh
# Add --integration to run tests that need a live OpenCode CLI.

# Kimi plugin manifest wiring
bash tests/kimi/run-tests.sh

# Pi extension (Node test, no external deps)
node tests/pi/test-pi-extension.mjs

# Claude Code skill tests (requires `claude` CLI)
bash tests/claude-code/run-skill-tests.sh
# Add --integration for slow full-workflow tests.

# Antigravity integration (requires `agy` CLI)
bash tests/antigravity/run-tests.sh

# Codex plugin sync verification (bash-only)
bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh

Skill behavior evaluation uses the separate superpowers-evals repository, cloned into evals/:

cd evals
uv sync --extra dev
export ANTHROPIC_API_KEY=sk-...
uv run drill run triggering-test-driven-development -b claude

These evals drive real LLM sessions and are slow; they are not part of CI today.

Code style and conventions

• Skills are behavior-shaping code, not prose. Treat edits to skills/*/SKILL.md as carefully as code changes.
• Action vocabulary, not tool names. Never put harness-specific tool names (e.g. TodoWrite, apply_patch, Agent) into skill bodies. Use the action phrases defined in the harness reference docs.
• SKILL.md frontmatter:
  • Required: name (lowercase, hyphens, no spaces/special chars) and description.
  • Total frontmatter ≤ 1024 characters.
  • description must start with a triggering condition, written in third person, and must not summarize the skill workflow (see skills/writing-skills/SKILL.md "Skill Discovery Optimization").
• Chinese optimization: Descriptions and skill bodies are in Chinese and tuned so Chinese prompts trigger the right skill.
• No third-party dependencies in core. PRs adding dependencies are rejected unless they are adding support for a new harness.
• Cross-platform hooks: Hook scripts are extensionless (session-start, not session-start.sh). Dispatcher logic lives in hooks/run-hook.cmd.
• Version synchronization: Update .version-bump.json if you add a new manifest that carries a version field, then run scripts/bump-version.sh.
• Refer to CLAUDE.md for full contributor rules (PR requirements, prohibited changes, skill-change evaluation expectations).

Testing strategy

• tests/ — fast plugin/infrastructure tests: manifest wiring, hook JSON output, bootstrap caching, brainstorm-server JS, shell lint, sync verification.
• evals/ — slow LLM-driven behavior evals from the separate superpowers-evals repo. They verify that agents actually follow skill instructions in real sessions.
• Skill changes require evaluation. If you change a skill, follow skills/writing-skills/SKILL.md: write adversarial subagent pressure scenarios, establish baseline failure, then verify the skill fixes it.
• New harness support requires a clean-session transcript proving that the bootstrap auto-triggers brainstorming on the exact prompt: Let's make a react todo list.

Release, versioning, and deployment

• Version sync: scripts/bump-version.sh <new-version> updates every file declared in .version-bump.json. Use --check to detect drift and --audit to scan for missed occurrences. Requires jq.
• Shell lint: scripts/lint-shell.sh [--all] [--format] [files...] runs shellcheck (and optionally shfmt) on shell files.
• Codex distribution: scripts/sync-to-codex-plugin.sh syncs the tracked plugin content into prime-radiant-inc/openai-codex-plugins and opens a PR. Requires bash, rsync, git, gh (authenticated), and python3.
• No GitHub Actions workflows are present; tests are run locally or via the user's own pre-commit / CI setup.

Security and privacy considerations

• Local-only bootstrap: Session-start hooks read skills/using-superpowers/SKILL.md from the plugin checkout and inject it into the model context. No external service is contacted during injection.
• No remote telemetry: This fork has removed the brainstorming visual companion's remote telemetry. The companion no longer loads any external logo or image; it only displays a local text label (Superpowers CN v{version}). The original opt-out environment variables (SUPERPOWERS_DISABLE_TELEMETRY, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC) are therefore no longer needed.
• Do not edit user files: A real integration delivers the bootstrap and skills through the harness's own install mechanism. Never hand-edit a user's global config (e.g. ~/.gemini/config/AGENTS.md, settings.json) as part of a port or fix.
• Hook scripts execute shell commands: Changes to hooks/session-start, hooks/session-start-codex, or hooks/run-hook.cmd affect every session of every user. Keep them portable, self-contained, and free of PATH-dependent assumptions.

Contributing and pull requests

• Read CLAUDE.md first. It contains the strict contributor rules and is the authoritative source for PR requirements.
• Read .github/PULL_REQUEST_TEMPLATE.md and fill in every section.
• Target the dev branch, not main.
• Disclose the agent environment (model, harness, version, installed plugins) in every PR.
• One problem per PR. Bundled or speculative PRs are closed without review.
• Skill changes need eval evidence. Do not modify carefully-tuned content (Red Flags tables, rationalizations, "human partner" language) without before/after eval results.
• New skills must be general-purpose. Domain-specific, tool-specific, or project-specific skills belong in a separate plugin.

Per-harness quick reference

When in doubt, look at the live reference integration for the harness you are working on, then read docs/porting-to-a-new-harness.md for the invariants that must hold for any new port.