[deve1993]

Summary

Makes the superpowers Claude Code plugin the team's single source for the 14 process skills (brainstorming, writing-plans, systematic-debugging, test-driven-development, …). Until now Claude saw two versions of each: plugin 6.3.0 on one machine, and an older fork in .agents/skills/ served through SkillBrain. Codex is not affected and keeps reading .agents/skills/.

Design: docs/superpowers/specs/2026-09-14-superpowers-integration-design.md · Plan: docs/superpowers/plans/2026-09-14-superpowers-integration.md

Changes

• Importer guard (packages/storage/src/import-skills.ts): new exported SUPERSEDED_BY_PLUGIN set. import-skills --reactivate now skips those 14 names. Their catalog rows will be deprecated on purpose, but the files stay in the bundle for Codex, so without the guard a recovery run would resurrect the forks. Normal imports, --full prune and the security gate are unchanged. New Vitest case; note in DEPLOY-SKILLS.md; CLI help and JSDoc updated.
• Plugin enabled for the repo (.opencode/settings.json, read by Claude Code as .claude/settings.json): enabledPlugins for superpowers@claude-plugins-official. Existing hooks untouched.
• CLAUDE.md: new "Superpowers (process skills)" section. It covers the one exception to "skills come only from SkillBrain", the install command, and removing duplicate symlinks from a local .claude/skills/. Agent Routing rows point at the matching skills.
• AGENTS.md: Smart Intake still decides what to build; superpowers now governs how code is written.
  • FIX → systematic-debugging.
  • COMPONENTE / REFACTOR → brainstorming, then either a direct TDD implementation (bounded) or writing-plans → subagent-driven-development (architectural).
  • New "Workflow tecnico (Superpowers)" section: maps the Iron Rules onto the superpowers phases, notes what applies to Codex, and says where specs and plans live.
• Bundled agent prompts (packages/codegraph/data/agents/{builder,planner}/AGENT.md): builder steps annotated with their skills; planner hands technical design to the main session. This changes the bundle hash, so the boot import re-runs on the next deploy.

After merge (manual rollout)

1. Redeploy SkillBrain on Coolify. Check agent_read({ name: "builder" }) shows the superpowers: annotations.
2. Soft-delete the 14 forks in prod with the admin route DELETE /api/skills/:name. It is reversible and audit-logged. Then check skill_route no longer suggests them. Today brainstorming ranks Feat/skill usage telemetry #1 for "brainstorm and design a new feature".
3. Anyone with a local .claude/skills/ mirror: remove the 14 symlinks (see CLAUDE.md).

Test plan

• pnpm --filter @skillbrain/storage test: 39/39, including the new --reactivate guard case (RED before the change: 2 reactivated instead of 1)
• packages/codegraph: tsc --noEmit clean, build ok, 308/308 tests
• pnpm --filter @skillbrain/skill-guard test: 17/17
• Per-task spec/quality reviews and a whole-branch review. The final review's findings (routing on the bounded path, Codex note) are fixed in b4d992e.
• Fresh Claude Code session with a clean config offers to install the plugin

Known follow-ups (not in this PR)

• The AGENTS.md Delegation Map still lists subagent_type values for SkillBrain agent prompts, which are not native Claude Code subagents.
• The spec's Iron Rules recap table (§3.3) is a step behind the final AGENTS.md wording.
• No test yet checks that the SUPERSEDED_BY_PLUGIN names still match the bundled skill names.

🤖 Generated with Claude Code