@complexthings/superpowers-agent 10.0.3 → 11.0.0

package/skills/collaboration/leveraging-cli-tools/scripts/setup-rtk.sh

@@ -1,217 +0,0 @@
-#!/usr/bin/env bash
-# setup-rtk.sh — verify rtk is configured for the current agentic harness.
-#
-# Contract:
-#   - Default (no args): CHECK + REPORT only. Detects the harness, prints
-#     config status per-check ([ok]/[missing]), and prints the EXACT rtk
-#     commands that would fix any gap. Changes NOTHING.
-#   - `--apply`: runs the planned fix commands for the DETECTED harness only.
-#     Every fix is a call to `rtk init ...`, which is itself create-if-absent
-#     and never overwrites existing config, so re-running is always safe.
-#   - If the harness can't be determined, every harness is checked read-only
-#     and nothing is ever applied (there's no single harness to act on).
-#
-# Usage:
-#   scripts/setup-rtk.sh            # check + report (safe, default)
-#   scripts/setup-rtk.sh --apply    # run the planned fix commands
-
-set -euo pipefail
-
-APPLY=false
-if [ "${1:-}" = "--apply" ]; then
-  APPLY=true
-fi
-
-if ! command -v rtk >/dev/null 2>&1; then
-  echo "[--] rtk is not installed or not on PATH — nothing to check."
-  echo "     Install rtk first, then re-run this script."
-  exit 1
-fi
-
-REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-PLANNED=()
-
-plan() {
-  PLANNED+=("$1")
-  echo "  planned: $1"
-}
-
-run_planned() {
-  for cmd in "${PLANNED[@]}"; do
-    echo "  running: $cmd"
-    eval "$cmd"
-  done
-}
-
-# --- Harness detection -------------------------------------------------
-# Sensible, lazy heuristic: harness-specific env vars first, then config
-# dirs. Order matters — check the most specific/reliable signal first.
-detect_harness() {
-  if [ -n "${CLAUDECODE:-}" ] || [ -n "${CLAUDE_CODE_ENTRYPOINT:-}" ]; then
-    echo claude; return
-  fi
-  if [ -n "${CODEX_SANDBOX:-}" ] || [ -n "${CODEX_HOME:-}" ]; then
-    echo codex; return
-  fi
-  if [ -n "${OPENCODE_MODEL:-}" ] || [ -d "$HOME/.config/opencode" ] && [ -n "${OPENCODE_EXPERIMENTAL_MARKDOWN:-}${OPENCODE_BIN_PATH:-}" ]; then
-    echo opencode; return
-  fi
-  if [ -n "${PI_AGENT:-}" ] || [ -n "${PI_HOME:-}" ]; then
-    echo pi; return
-  fi
-  if [ -n "${GITHUB_COPILOT_CLI:-}" ] || [ -n "${COPILOT_AGENT:-}" ]; then
-    echo copilot; return
-  fi
-  echo unknown
-}
-
-# --- Per-harness checks -------------------------------------------------
-# Each check prints [ok]/[missing] status lines and calls `plan` for any
-# gap. None of these mutate anything by themselves.
-
-check_claude() {
-  echo "Claude Code:"
-  local show
-  show="$(rtk init --show 2>&1)"
-  local core global_bad local_bad
-  core="$(printf '%s\n' "$show" | grep -E '(Hook:|RTK\.md:|Global \(|Local \(|settings\.json:)' || true)"
-  global_bad="$(printf '%s\n' "$core" | grep -v 'Local (' | grep -v '^\[ok\]' || true)"
-  local_bad="$(printf '%s\n' "$core" | grep 'Local (' | grep -v '^\[ok\]' || true)"
-
-  if [ -z "$global_bad" ] && [ -z "$local_bad" ]; then
-    echo "$core" | sed 's/^/  /'
-    echo "  [ok] rtk fully configured for Claude Code"
-    return
-  fi
-
-  echo "$core" | sed 's/^/  /'
-  if [ -n "$global_bad" ]; then
-    plan "rtk init -g --auto-patch"
-  fi
-  if [ -n "$local_bad" ]; then
-    plan "rtk init --auto-patch"
-  fi
-  CLAUDE_NEEDS_RESTART=true
-}
-
-check_opencode() {
-  echo "OpenCode:"
-  local plugin="$HOME/.config/opencode/plugins/rtk.ts"
-  if [ -f "$plugin" ]; then
-    echo "  [ok] plugin installed ($plugin)"
-  else
-    echo "  [missing] plugin not found ($plugin)"
-    plan "rtk init -g --opencode"
-  fi
-}
-
-check_pi() {
-  echo "pi:"
-  local ext="$HOME/.pi/agent/extensions/rtk.ts"
-  local repo_rtk="$REPO_ROOT/RTK.md"
-  if [ -f "$ext" ]; then
-    echo "  [ok] extension installed ($ext)"
-  else
-    echo "  [missing] extension not found ($ext)"
-    plan "rtk init -g --agent pi"
-  fi
-  if [ -f "$repo_rtk" ]; then
-    echo "  [ok] repo RTK.md present ($repo_rtk)"
-  else
-    echo "  [missing] repo RTK.md not found ($repo_rtk)"
-    plan "rtk init --codex"
-  fi
-}
-
-check_codex() {
-  echo "codex:"
-  local codex_home="${CODEX_HOME:-$HOME/.codex}"
-  local global_rtk="$codex_home/RTK.md"
-  local repo_rtk="$REPO_ROOT/RTK.md"
-  if [ -f "$global_rtk" ]; then
-    echo "  [ok] global RTK.md present ($global_rtk)"
-  else
-    echo "  [missing] global RTK.md not found ($global_rtk)"
-    plan "rtk init -g --codex"
-  fi
-  if [ -f "$repo_rtk" ]; then
-    echo "  [ok] repo RTK.md present ($repo_rtk)"
-  else
-    echo "  [missing] repo RTK.md not found ($repo_rtk)"
-    plan "rtk init --codex"
-  fi
-}
-
-check_copilot() {
-  echo "GitHub Copilot:"
-  local global_hook="$HOME/.copilot/hooks/rtk-rewrite.json"
-  local repo_hook="$REPO_ROOT/.github/hooks/rtk-rewrite.json"
-  if [ -f "$global_hook" ]; then
-    echo "  [ok] global hook present ($global_hook)"
-  else
-    echo "  [missing] global hook not found ($global_hook)"
-    plan "rtk init -g --copilot"
-  fi
-  if [ -f "$repo_hook" ]; then
-    echo "  [ok] repo hook present ($repo_hook)"
-  else
-    echo "  [missing] repo hook not found ($repo_hook)"
-    plan "rtk init --copilot"
-  fi
-}
-
-# --- Main ----------------------------------------------------------------
-CLAUDE_NEEDS_RESTART=false
-HARNESS="$(detect_harness)"
-
-case "$HARNESS" in
-  claude)
-    echo "Detected harness: Claude Code"
-    check_claude
-    ;;
-  opencode)
-    echo "Detected harness: OpenCode"
-    check_opencode
-    ;;
-  pi)
-    echo "Detected harness: pi"
-    check_pi
-    ;;
-  codex)
-    echo "Detected harness: codex"
-    check_codex
-    ;;
-  copilot)
-    echo "Detected harness: GitHub Copilot"
-    check_copilot
-    ;;
-  unknown)
-    echo "Harness could not be determined — checking all harnesses read-only."
-    check_claude
-    check_opencode
-    check_pi
-    check_codex
-    check_copilot
-    echo
-    echo "No single harness detected, so nothing can be applied automatically."
-    echo "Re-run on the target machine/agent, or configure manually with the commands above."
-    exit 0
-    ;;
-esac
-
-echo
-if [ "${#PLANNED[@]}" -eq 0 ]; then
-  echo "rtk is already configured for $HARNESS. Nothing to do."
-  exit 0
-fi
-
-if [ "$APPLY" = true ]; then
-  echo "Applying fixes for $HARNESS..."
-  run_planned
-  if [ "$HARNESS" = "claude" ] && [ "$CLAUDE_NEEDS_RESTART" = true ]; then
-    echo
-    echo "rtk config changed for Claude Code — please restart Claude Code to pick it up."
-  fi
-else
-  echo "Run again with --apply to execute the planned command(s) above."
-fi

package/skills/collaboration/leveraging-cli-tools/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.0.0",
-    "name": "leveraging-cli-tools",
-    "title": "leveraging-cli-tools",
-    "aliases": [
-        "leveraging-cli-tools",
-        "collaboration/leveraging-cli-tools"
-    ]
-}

package/skills/meta/create-skill-json/SKILL.md

@@ -1,370 +0,0 @@
----
-name: create-skill-json
-description: Generate a skill.json metadata file for a skill from its SKILL.md and directory structure. Use when adding a new skill to a repository, updating an existing skill's metadata, or standardizing skill.json files. Triggers whenever someone mentions generating, creating, or updating skill.json files.
-metadata:
-  version: 1.1.0
----
-
-# Create skill.json
-
-## Overview
-
-Generate a `skill.json` metadata file for a skill based on its `SKILL.md` frontmatter and directory structure. This ensures consistent skill metadata across repositories.
-
-**Core principle:** skill.json is generated from existing information (frontmatter, file structure), not created from scratch with assumptions.
-
-**CRITICAL:** skill.json contains **EXACTLY 5 FIELDS** - no more, no less. Any additional fields are forbidden.
-
-## Input Requirements
-
-You must be given:
-- A path to a `SKILL.md` file, OR
-- A path to a directory containing a `SKILL.md` file
-
-## Process
-
-### 1. Validate Input
-
-```bash
-# If given directory path
-if [ -d "$input_path" ]; then
-    skill_dir="$input_path"
-    skill_md="${skill_dir}/SKILL.md"
-else
-    skill_md="$input_path"
-    skill_dir="$(dirname "$input_path")"
-fi
-
-# Verify SKILL.md exists
-if [ ! -f "$skill_md" ]; then
-    echo "Error: SKILL.md not found at $skill_md"
-    exit 1
-fi
-```
-
-### 2. Extract Frontmatter Data
-
-Read the SKILL.md file and extract frontmatter fields:
-
-```yaml
----
-name: human-readable-name
-description: One-line summary of what the skill does and when to use it.
-metadata:
-  version: 1.0.0  # Optional, defaults to 1.0.0
----
-```
-
-**Required fields from frontmatter:**
-- `name` → becomes `title` in skill.json
-- `metadata.version` (or top-level `version`) → use if present, otherwise default to "1.0.0"
-
-### 3. Determine Skill Name (with Namespace)
-
-The skill `name` in skill.json includes a **namespace prefix** based on where the skill lives:
-
-| Location | Namespace | Example name |
-|----------|-----------|--------------|
-| `~/.agents/superpowers/skills/` | `superpowers:` | `superpowers:debugging/memory-profiling` |
-| `.agents/skills/` (project) | none | `debugging/memory-profiling` |
-| `~/.agents/skills/` (personal) | none | `debugging/memory-profiling` |
-
-The path component after the namespace is the **relative path from the skills root directory**.
-
-**Examples:**
-- Superpowers skill at `~/.agents/superpowers/skills/debugging/memory-profiling/` → name: `superpowers:debugging/memory-profiling`
-- Project skill at `./skills/meta/create-skill-json/` → name: `meta/create-skill-json`
-- Personal skill at `~/.agents/skills/collaboration/brainstorming/` → name: `collaboration/brainstorming`
-
-**When context is ambiguous** (can't determine location), ask the user or default to no prefix.
-
-### 4. Identify Helper Files
-
-Helper files are files in the skill directory (excluding SKILL.md itself) that the skill **references or uses**. Focus on files that support agents executing the skill.
-
-**Include in helpers array:**
-- `scripts/` — executable scripts referenced in the skill
-- `examples/` — example code or files used in the skill
-- `templates/` — reusable templates the skill instructs agents to use
-- `references/` — reference documents the skill tells agents to read
-- `assets/` — static resources the skill uses
-- Root-level support files (e.g., `package.json`, `*.sh`, `*.py` that aren't test files)
-
-**Path format:** Relative to the skill directory (where skill.json will live)
-
-```json
-"helpers": [
-  "scripts/profile-heap.js",
-  "scripts/analyze-snapshots.py",
-  "examples/node-example.js",
-  "package.json"
-]
-```
-
-**Exclude from helpers:**
-- `SKILL.md` itself
-- `skill.json` (if it already exists)
-- Hidden files (starting with `.`)
-- Test/evaluation files (`test-*.md`, `evals/`, `*-workspace/`)
-- Documentation not used by the skill: `README.md`, `CHANGELOG.md`, `LICENSE.txt`
-- `node_modules/`, build artifacts
-
-**If helpers array is empty**, omit the field entirely (don't include `"helpers": []`).
-
-### 5. Generate Aliases
-
-Aliases allow users to reference the skill with shorter names.
-
-**Standard aliases (in this order):**
-1. Just the skill name (shortest): `skill-name`
-2. The full path: `category/skill-name`
-
-**Example:**
-```json
-"aliases": [
-  "memory-profiling",
-  "debugging/memory-profiling"
-]
-```
-
-**Optional:** Add a well-known abbreviation as a third alias only when it is clearly recognized — don't invent aliases.
-
-**Do NOT add random synonyms** — stick to the standard two aliases unless an obvious abbreviation exists.
-
-### 6. Create skill.json
-
-Assemble the complete skill.json with **EXACTLY these 5 fields** (or 4 if helpers is empty):
-
-```json
-{
-  "version": "1.0.0",
-  "name": "superpowers:category/skill-name",
-  "title": "Human-Readable Title",
-  "helpers": [
-    "scripts/helper1.js"
-  ],
-  "aliases": [
-    "skill-name",
-    "category/skill-name"
-  ]
-}
-```
-
-When helpers is empty, omit it:
-
-```json
-{
-  "version": "1.0.0",
-  "name": "superpowers:category/skill-name",
-  "title": "Human-Readable Title",
-  "aliases": [
-    "skill-name",
-    "category/skill-name"
-  ]
-}
-```
-
-**FORBIDDEN:** Do NOT add any other fields. No `description`, `tags`, `capabilities`, `triggers`, `keyConcepts`, `components`, `references`, `quickReference`, `resources`, `stats`, `when_to_use`, or any other creative fields.
-
-### 7. Write and Validate
-
-Write the skill.json file to the skill directory:
-
-```bash
-output_path="${skill_dir}/skill.json"
-echo "$skill_json" > "$output_path"
-
-# Optional: Validate JSON syntax
-if command -v jq &> /dev/null; then
-    jq empty "$output_path" 2>&1 || echo "Warning: Invalid JSON generated"
-fi
-
-echo "Created: $output_path"
-```
-
-Also run `skills-ref validate` if the tool is available:
-
-```bash
-if command -v skills-ref &> /dev/null; then
-    skills-ref validate "$skill_dir" && echo "Skill validation passed"
-fi
-```
-
-## Complete Example
-
-**Input:** `~/.agents/superpowers/skills/debugging/memory-profiling/`
-
-**Directory structure:**
-```
-~/.agents/superpowers/skills/debugging/memory-profiling/
-├── SKILL.md
-├── scripts/
-│   ├── profile-heap.js
-│   ├── analyze-snapshots.py
-│   └── compare-profiles.sh
-└── examples/
-    └── node-example.js
-```
-
-**SKILL.md frontmatter:**
-```yaml
----
-name: memory-profiling
-metadata:
-  version: 2.1.0
----
-```
-
-**Generated skill.json:**
-```json
-{
-  "version": "2.1.0",
-  "name": "superpowers:debugging/memory-profiling",
-  "title": "memory-profiling",
-  "helpers": [
-    "scripts/profile-heap.js",
-    "scripts/analyze-snapshots.py",
-    "scripts/compare-profiles.sh",
-    "examples/node-example.js"
-  ],
-  "aliases": [
-    "memory-profiling",
-    "debugging/memory-profiling"
-  ]
-}
-```
-
-## FORBIDDEN FIELDS
-
-**skill.json must contain EXACTLY 4-5 fields** (version, name, title, helpers [optional], aliases). The following fields are explicitly FORBIDDEN:
-
-### Documentation Fields (belongs in SKILL.md)
-- ❌ `description` - Use SKILL.md frontmatter `description` field
-- ❌ `when_to_use` - Use SKILL.md frontmatter or content
-- ❌ `keyConcepts` - Document in SKILL.md content
-- ❌ `overview` - Document in SKILL.md content
-
-### Discovery Fields (handled by native skill discovery)
-- ❌ `tags` - Use SKILL.md frontmatter fields for search
-- ❌ `keywords` - Use SKILL.md content for search
-- ❌ `triggers` - Use SKILL.md `description` field
-- ❌ `categories` - Path already indicates category
-
-### Capability Fields (documented in SKILL.md)
-- ❌ `capabilities` - Document in SKILL.md content
-- ❌ `features` - Document in SKILL.md content
-- ❌ `commands` - Document in SKILL.md content
-
-### Reference Fields (use helper files)
-- ❌ `references` - Link to helper files in SKILL.md
-- ❌ `resources` - Add to `helpers` array if needed
-- ❌ `links` - Add to SKILL.md content
-
-### Structure Fields (use helper files)
-- ❌ `components` - Document in SKILL.md or helper files
-- ❌ `quickReference` - Create as helper file if needed
-
-### Metadata Fields (not used by tooling)
-- ❌ `author` - Track in git history
-- ❌ `license` - Inherited from repository
-
-### Statistics/Config Fields (unnecessary)
-- ❌ `stats` - Not used by any tooling
-- ❌ `config` - Create as helper file if needed
-
-## Rationalization Table
-
-| Rationalization | Counter |
-|-----------------|---------|
-| "Adding `description` helps with discoverability" | NO. Description is in SKILL.md frontmatter. Native skill discovery reads it. |
-| "`tags` make it easier to categorize and search" | NO. Native skill discovery uses SKILL.md content and frontmatter. Path already indicates category. |
-| "`capabilities` document what the skill does" | NO. That's what SKILL.md content is for. skill.json is for tooling, not documentation. |
-| "`triggers` help agents know when to use this" | NO. SKILL.md `description` field serves this purpose. Don't duplicate. |
-| "These fields might be useful for future features" | YAGNI violation. No imaginary consumers. Only add fields when tooling actually needs them. |
-| "`helpers: []` is cleaner than omitting the field" | NO. Omit empty arrays — real skill.json files do not include `helpers` when empty. |
-| "Other skill systems use these fields" | Irrelevant. superpowers-agent uses 4-5 fields. Period. |
-| "Extra metadata is harmless" | NO. Bloats files, creates maintenance burden, misleads about what tooling uses. |
-
-## Common Mistakes
-
-### ❌ Missing namespace prefix for superpowers skills
-```json
-"name": "debugging/memory-profiling"  // WRONG for superpowers skills
-```
-
-**Fix:** Add the `superpowers:` prefix for skills in `~/.agents/superpowers/skills/`:
-```json
-"name": "superpowers:debugging/memory-profiling"  // CORRECT
-```
-
-### ❌ Wrong alias order
-```json
-"aliases": ["debugging/memory-profiling", "memory-profiling"]  // WRONG - long path first
-```
-
-**Fix:** Short name first, full path second:
-```json
-"aliases": ["memory-profiling", "debugging/memory-profiling"]  // CORRECT
-```
-
-### ❌ Including empty helpers array
-```json
-"helpers": []  // WRONG - omit if empty
-```
-
-**Fix:** Omit the field entirely when there are no helpers:
-```json
-// Just leave out "helpers" when there's nothing to list
-```
-
-### ❌ Including test/eval files in helpers
-```json
-"helpers": ["test-scenarios.md", "evals/evals.json"]  // WRONG - test files aren't helpers
-```
-
-**Fix:** Only include files that agents use when executing the skill.
-
-### ❌ Adding creative aliases
-```json
-"aliases": ["memory-profiling", "heap-profiling", "memory-analysis"]  // WRONG
-```
-
-**Fix:** Standard two aliases unless a well-known abbreviation exists:
-```json
-"aliases": ["memory-profiling", "debugging/memory-profiling"]  // CORRECT
-```
-
-## Fields Reference
-
-| Field | Source | Required | Default |
-|-------|--------|----------|---------|
-| `version` | Frontmatter `metadata.version` | No | `"1.0.0"` |
-| `name` | Namespace + skill directory path | Yes | N/A |
-| `title` | Frontmatter `name` field | Yes | N/A |
-| `helpers` | Referenced support files | No | Omit if empty |
-| `aliases` | Generated from path | Yes | `["skill-name", "category/skill-name"]` |
-
-## Verification
-
-After creating skill.json, verify:
-
-- [ ] JSON is valid syntax (use `jq` if available)
-- [ ] **File contains exactly 4 or 5 top-level fields** (version, name, title, [helpers], aliases)
-- [ ] No forbidden fields present
-- [ ] `version` matches SKILL.md frontmatter (or is "1.0.0")
-- [ ] `name` includes correct namespace prefix (`superpowers:` for superpowers repo, none for project/personal)
-- [ ] `title` matches `name` field from SKILL.md frontmatter
-- [ ] `helpers` array lists only referenced support files (omitted if empty)
-- [ ] `aliases` has short name first, full path second
-- [ ] File saved to same directory as SKILL.md
-- [ ] `skills-ref validate` passes (if tool available)
-
-**Field count check:**
-```bash
-jq 'keys | length' skill.json  # Must output: 4 or 5
-```
-
-## Related Skills
-
-- **superpowers:writing-skills** - Create new skills following TDD methodology
-- **superpowers:gardening-skills-wiki** - Maintain and organize skill collections

package/skills/meta/create-skill-json/skill.json

@@ -1,9 +0,0 @@
-{
-  "version": "1.1.0",
-  "name": "create-skill-json",
-  "title": "create-skill-json",
-  "aliases": [
-    "create-skill-json",
-    "meta/create-skill-json"
-  ]
-}

package/skills/meta/create-skill-json/test-scenarios.md

@@ -1,29 +0,0 @@
-# Test Scenarios for create-skill-json Skill
-
-## Purpose
-Test that agents strictly follow the 5-field structure and don't add creative extras.
-
-## Baseline Behavior (WITHOUT strict enforcement)
-Agent adds fields like: `description`, `tags`, `capabilities`, `triggers`, `keyConcepts`, `quickReference`, `components`, `references`, etc.
-
-## Test Scenario 1: Documentation-Rich Skill
-**Setup:** Large skill with extensive frontmatter and multiple reference files
-**Pressure:** Agent wants to "preserve valuable information" from references
-**Expected Behavior:** Only 5 fields in skill.json, no documentation fields
-
-## Test Scenario 2: Tool-Heavy Skill  
-**Setup:** Skill with scripts/, examples/, templates/ subdirectories
-**Pressure:** Agent wants to categorize helpers by type
-**Expected Behavior:** Flat helpers array, no categorization fields
-
-## Test Scenario 3: Domain-Specific Skill
-**Setup:** Skill for specific technology (e.g., Adobe Commerce)
-**Pressure:** Agent wants to add `tags`, `capabilities`, `triggers` for "discoverability"
-**Expected Behavior:** No extra metadata fields
-
-## Common Rationalizations to Block
-- "Adding description helps with discoverability" → NO, description is in SKILL.md
-- "Tags make it easier to find" → NO, native skill discovery uses SKILL.md frontmatter
-- "Capabilities document what it does" → NO, that's in SKILL.md content
-- "These fields might be useful later" → YAGNI violation
-- "Other tools might use them" → No other tools exist, don't design for imaginary consumers

package/skills/setup-skills/SKILL.md

@@ -1,54 +0,0 @@
----
-name: setup-skills
-description: Run superpowers-agent setup-skills to detect which AI harnesses (Claude Code, GitHub Copilot, OpenCode, Pi, Codex) are present in a project and wire up its skills infrastructure — .agents/skills/, per-harness symlinks, and each harness's instruction file. Use whenever starting a new project with AI agents, when skills symlinks are missing, when AGENTS.md or CLAUDE.md lacks skills configuration, when a user asks to "set up skills", "install skills", "bootstrap skills", or "initialize superpowers". Also use when skills aren't being discovered, or before creating project-specific skills if the infrastructure doesn't exist yet.
----
-
-# Setup Skills
-
-This skill does one thing: run `superpowers-agent setup-skills` and follow the output it gives you exactly.
-
-## Run the Command
-
-From the project root:
-
-```bash
-superpowers-agent setup-skills
-```
-
-## What the Command Does
-
-- Creates `.agents/`, `.agents/skills/`, and `.agents/docs/SUPERPOWERS.md` (the reference doc every generated instruction file links to).
-- Detects harnesses by dot-folder existence or CLI binary on PATH: Claude Code (`.claude`/`claude`), GitHub Copilot (`.github`/`copilot`), OpenCode (`.opencode`/`opencode`), Pi (`.pi`/`pi`), Codex (`.codex`/`codex`).
-- Writes/updates `AGENTS.md` unconditionally (creating it if missing) with tool mappings for Copilot, OpenCode, Pi, and Codex.
-- Updates `CLAUDE.md` in place only if one already exists at the project root or in `.agents/` — it never creates a fresh `CLAUDE.md`.
-- Creates or updates `.github/copilot-instructions.md` only when GitHub Copilot is detected.
-- Keeps exactly one backup per instruction file it touches (dedupes old `*.backup*` files).
-- Symlinks each detected harness's skills dir back to `.agents/skills/`: `.claude/skills`, `.github/skills`, `.opencode/skill` (singular). Pi and Codex read `.agents/skills/` directly — no symlink.
-
-## Follow the Output Exactly
-
-The command output is authoritative. Read it, act on it, and do not skip any steps it prescribes. It adapts to the harnesses detected in your project and tells you precisely what was created, updated, or skipped.
-
-If the command prints follow-up instructions, complete them before continuing with your task.
-
-If it fails for any reason other than not-found (e.g. permission denied, partial failure), surface the exact error and stop — do not continue or leave the project half-configured.
-
-## If superpowers-agent Is Not Found
-
-Install it first, then rerun:
-
-```bash
-npm install -g @complexthings/superpowers-agent
-superpowers-agent setup-skills
-```
-
-## After Setup
-
-Project-specific skills belong in `.agents/skills/`. All AI agents working in the project discover them automatically via the symlinks the command created.
-
-To verify, use your platform's native skill tool and confirm the project skills are available.
-
-## Related Skills
-
-- Use your platform's native skill tool to discover available skills after setup.
-- Follow your platform's skill guidance for loading and applying them.