obra/superpowers — what to adopt for IKA Concierge

Author: Jesse Vincent (Prime Radiant). License: MIT. Posture: cross-platform skills framework for AI coding agents — not knowledge work. Distributed for Claude Code · Codex CLI/App · Factory Droid · Gemini CLI · OpenCode · Cursor · GitHub Copilot CLI from one repo.

Surface area: 14 skills (process discipline + meta), 1 SessionStart hook, install scripts per platform. No connectors / MCP servers / domain knowledge.

Skill file format: skills/<slug>/SKILL.md with YAML frontmatter (just name + description) followed by markdown body. Schema is intentionally lighter than Anthropic plugins.

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

# Overview
...
# When to Use
...
# The Iron Law
...

Stated principles (verbatim from README):

• Test-Driven Development — write tests first, always
• Systematic over ad-hoc — process over guessing
• Complexity reduction — simplicity as primary goal
• Evidence over claims — verify before declaring success

Adopt count: 5 hard adopts · 5 partials/opt-ins · 4 skips. Adopt skills run as IKA-curated tier on the Engineering neuron of the Company template; inherit-down to sub-neurons by default.

Superpowers ships a single Claude Code hook (hooks/hooks.json):

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|clear|compact",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start",
        "async": false
      }]
    }]
  }
}

The hook injects the using-superpowers skill's content into the system prompt on session start, on /clear, and after auto-compact. That is: discipline is enforced by re-priming the model after every context reset, not by a single bootstrap.

What this maps to in IKA Concierge

Our Conversation Surface already assembles per-turn context (per-neuron skills + integrations + recent thread + briefing). What we have not formalized is the equivalent of hook events: the moments at which always-on skills get re-injected. Lift the contract:

Today our spec implies all three but doesn't name the contract. Naming it lets the per-IKA Skills registry declare which skills are always_on (re-injected at every event) vs on_demand (only injected when description matches).

Schema extension

• Add always_on BOOL column to neuron_skills link table. Default false. When true, skill's description fires on every hook event.
• Add skill_hooks table for skills that ship their own hook scripts (forward-compat with Anthropic plugins that may add hooks in v2 of their schema).

The most subtle and load-bearing rule in Superpowers' writing-skills meta-skill:

Description is trigger-focused, not workflow-focused. "Use when..." statements describe when to apply the skill, never how it works.

The reasoning: the LLM uses the description to decide whether to invoke. If the description summarizes the workflow, the model often follows the description instead of reading the full skill content — a silent failure mode where the skill is "invoked" but its substantive rules never load.

How this changes our SKILL.md schema

Current schema (from /ika-pro-architecture/#per-neuron-skills): SKILL.md descriptor with name, description, version, allowed tools, allowed integrations, vetting tier, source URL, sha256, ed25519 signature, license.

Addition: description must start with "Use when…" and describe trigger conditions only. skill-creator's system prompt enforces this on draft. Validation rule on publish: reject if description contains workflow verbs ("does", "performs", "generates", "outputs", "transforms"). Vetting at the curator level catches the rest.

Examples

Superpowers' writing-skills also requires authors to ship a baseline test: show the agent failing the task without the skill (RED), then succeeding with the skill (GREEN). This treats skills as TDD-style artifacts.

Where this fits in our 3-tier vetting

Schema

• skill_tests — id, skill_id, baseline_prompt, expected_red_signal, expected_green_signal, author_proof_url. Test runs at publish-time + weekly drift check.
• UX: a "skill quality" badge on the catalog row when test pair has been validated in the last 7 days.

• The "iron-law" TDD framing as universal default. Superpowers treats TDD as non-negotiable. IKA's prosumer surface includes prototyping, exploratory data work, and copywriting drafts where tests-first is friction. TDD remains a skill the user can install on Engineering neurons; never global.
• The "invoke skill before ANY response, including clarifying questions" rule. Their using-superpowers demands skill lookup even for simple clarifications. For a conversational concierge that talks 100+ times a day, this would burn token budget and slow turns. IKA's classifier gate already does the cheap routing.
• Git-worktrees and finishing-a-development-branch as skills. These are specific to git-flow engineering work. Out of scope for the universal IKA shell.
• The cross-platform installer machinery (install scripts for 7 agent platforms). IKA is its own platform. The shape — one skill, many install paths — is achieved through our wire-format compatibility with Anthropic's plugin.json instead.
• Their flat namespace. Superpowers uses a single top-level /skills/ directory. We need per-neuron scoping + inheritance; flat namespace doesn't survive multi-tenant prosumer scale.

Action plan

1. S1 — Import 5 skills as IKA-curated. brainstorming · writing-plans · systematic-debugging · verification-before-completion · writing-skills. Vendor under /vendored/superpowers/<slug>/SKILL.md; pin commit; declare MIT license; sign with our ed25519. Default install: Engineering neuron in Company template; inherit-down. ~½ day.
2. S2 — SessionStart hook contract. Add named events (startup / clear / compact) to our Conversation Surface context-assembly path; add always_on BOOL to neuron_skills; add skill_hooks table. ~1 day.
3. S3 — Trigger-focused description rule. Update SKILL.md descriptor schema; enforce in skill-creator via system prompt; add validator to publish path. ~½ day. Backfill: walk our existing curated skills and rewrite descriptions that drift into workflow-summarizing.
4. S4 — RED/GREEN skill test for community-with-sig tier. New skill_tests table; CI runs baseline prompt without + with skill, expects different outputs; publish blocked until pass. ~1 day for the test runner, ~½ day for UX badge.
5. S5 — verification-before-completion as default on agent-as-assignee task closure. When an agent flips a task to submitted-for-review, the verification-before-completion skill fires automatically and writes its evidence (logs, artifacts, asserts) to the task's review thread. ~½ day wiring.
6. S6 — lift writing-skills' rules into skill-creator system prompt. The trigger-focused-description rule, the "one excellent example beats many mediocre", the "flowcharts only for non-obvious decisions", the "close loopholes explicitly" guidance — all become part of the bootstrap prompt for new drafts. ~½ day.

Effort

~4 days total (S1–S6). All slot inside our existing Per-neuron Skills + Commands + Plugins sections — no new entity needed.

What this unlocks

Three quiet wins. First: when the user installs a Superpowers skill from upstream, IKA speaks the same SKILL.md frontmatter shape — drop-in install. Second: agent-as-assignee task closures get the same discipline a senior IC would apply (verification, not assertion). Third: the next 200 skills the IKA catalog accrues are higher quality, because the description-trigger rule + RED/GREEN test pair are gates, not suggestions.

• Hook events beyond the three Superpowers names. We almost certainly want more: before_agent_invocation, after_task_closure, on_neuron_switch. Recommendation: ship the three named events first, extend as need surfaces.
• Conflict with Anthropic plugins' future hook schema. Anthropic's plugin.json doesn't yet specify hooks. If they ship a hook schema that differs from Superpowers', we'll have two shapes to support. Recommendation: adopt Superpowers' shape now (it's the only de-facto standard); migrate if Anthropic ships differently.
• RED/GREEN gate for our existing IKA-curated skills. Auto-block existing skills until their test pair lands, or grandfather them with a "tests pending" badge? Recommendation: grandfather with a visible badge + 90-day deadline.
• Always-on quota. If every neuron declares 10 always-on skills, the system prompt grows linearly. Cap per-IKA total always-on count (recommend 6) and surface it in the per-neuron Skills UI as a budget chip.