Framework management

<!-- Inlined into every SKILL.md via {{PREAMBLE_CORE}}. Keep ≤30 lines. -->

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Framework Management

Goal: Find, install, create, and manage both skills and agents within the superomni framework — through a single, unified discovery-first workflow.

Iron Law: Discover Before Creating

Never create a skill or agent from scratch without first checking built-ins and the network. Duplicate skills and agents fragment the framework and create maintenance burden.

Good Example

Need: "I need something that audits performance"
Step 1: bin/agent-manager list → found: planner-reviewer (engineering mode includes performance analysis)
Action: Use the built-in planner-reviewer agent
Result: No new agent needed — DONE

Bad Example (AVOID)

Need: "I need something that checks security"
Action: Immediately create agents/my-security-checker.md from scratch
[VIOLATED: planner-reviewer (security audit mode) already exists — checked built-ins first]

---

Phase 1: Identify What You Need

Answer these questions first:

1. Component type: Skill (process/workflow for Claude to follow) or Agent (specialized persona for delegation)?
2. Domain: What area does it cover? (testing / security / design / planning / etc.)
3. Trigger: When should it activate?
4. Output: What does it produce? (report / code / file / recommendation?)

COMPONENT SPEC
────────────────────────────────────────
Type:     skill | agent
Name:     [proposed name — verb-noun or domain]
Domain:   [area of expertise]
Trigger:  [when it should activate]
Output:   [what it produces]
────────────────────────────────────────

Phase 2: Check Built-ins

Always check existing components first:

# List all built-in agents
bin/agent-manager list 2>/dev/null || ls agents/

# List all built-in skills
bin/skill-manager list 2>/dev/null || ls skills/

# Search for overlap
grep -rn "name:" skills/*/SKILL.md.tmpl | grep -i "<your-keyword>" | head -10
grep -l "<your-keyword>" agents/*.md | head -5

Current built-in agents (5 canonical, after consolidation):

Agent	Specialty	Modes / consolidated responsibilities
planner-reviewer	Plan authoring + multi-lens review (strategy / engineering / evaluation / security / code-review)	absorbs retired planner, architect, ceo-advisor, evaluator, code-reviewer, security-auditor
frontend-designer	UX review: 10-dimension scoring, AI slop detection, impeccable check	renamed from designer
explorer	Read-only isolated-context repo exploration (debug evidence, code survey)	absorbs retired debugger (Phase 2: trace evidence)
refactoring-agent	Behavior-preserving code refactoring	unchanged
doc-writer	Diff-driven documentation generation	unchanged

Gate: If a built-in component fits → use or extend it. Stop here. If none fits → proceed to Phase 3.

Phase 3: Search the Network

If no built-in covers your need:

# Search GitHub for agents
bin/agent-manager search <your-query> 2>/dev/null

# Search GitHub for skills
bin/skill-manager search <your-query> 2>/dev/null

Known registries to check manually:

• https://github.com/obra/superpowers/tree/main/agents
• https://github.com/garrytan/gstack/tree/main/agents
• https://github.com/obra/superpowers/tree/main/skills

Gate: If suitable → install it (Phase 4A). If nothing suitable → create from scratch (Phase 4B).

Phase 4A: Install from URL

# Install an agent from GitHub
bin/agent-manager install https://raw.githubusercontent.com/user/repo/main/agents/my-agent.md

# Install a skill from GitHub
bin/skill-manager install https://raw.githubusercontent.com/user/repo/main/skills/my-skill/SKILL.md

# Verify installation
bin/agent-manager list
bin/skill-manager list

Phase 4B: Create from Scratch

Creating an Agent

Agents are markdown files in agents/<name>.md. Required sections:

# [Agent Name]

You are the **superomni [Name]** — [one-sentence specialty].

## Your Identity
[Who you are and what framework you apply]

## Iron Law: [Non-negotiable rule]
[The one rule this agent must never violate]

## Your Process

### Phase 1: [Name]
[Steps, commands, outputs]

### Phase N: [Final phase]
[...]

## Output Format

\`\`\`
[AGENT TYPE] REPORT
════════════════════════════════════════
Agent:   superomni [Name]
[Key fields]

Status: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════════════════════════════
\`\`\`

# Scaffold (copy any canonical agent as a starting template)
cp agents/planner-reviewer.md agents/<new-name>.md
# Edit to match new specialty

Creating a Skill

Skills are SKILL.md.tmpl files in skills/<name>/. Required sections:

---
name: <skill-name>
description: |
  [2-3 sentences].
  Triggers: "keyword 1", "keyword 2".
allowed-tools: [Bash, Read, Write, Edit, Grep, Glob]
when_to_use: |
  [When this skill applies + boundary vs. peer skills. Include NOT-for-X clauses.]
produces: ~
consumes: ~
---

{{PREAMBLE_CORE}}

{{PREAMBLE_REF_LINK}}

# [Skill Title]

**Goal:** [One sentence.]

## Iron Law
[Non-negotiable rule]

## Phase 1: [Name]
[Steps]

## Phase N: Report

\`\`\`
[SKILL] REPORT
════════════════
Status: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════
\`\`\`

# Scaffold
SKILL_NAME="your-skill-name"
mkdir -p "skills/${SKILL_NAME}"
# Write SKILL.md.tmpl, then build:
bin/build-skills skills/${SKILL_NAME}/SKILL.md.tmpl

Quality Checklist (Skills)

• {{PREAMBLE_CORE}} (inline core) and {{PREAMBLE_REF_LINK}} (ref link) are both present. The legacy single-token form is deprecated and emits a build-time warning.
• when_to_use, produces, consumes are declared in frontmatter (Anthropic-spec compliance)
• YAML has name, description (with trigger phrases), allowed-tools
• At least one Iron Law with Good/Bad examples
• Phase structure (numbered phases)
• Defined output format with status protocol

Quality Checklist (Agents)

• Single focused specialty — no overlap with existing agents
• Iron Law (non-negotiable rule)
• Phase-based protocol (3–5 phases)
• Structured output report with DONE/BLOCKED status

Phase 5: Register and Validate

# Build the SKILL.md (if creating a skill)
bin/build-skills --force

# Run validation
npm test

# Register in CLAUDE.md (skills only)
# Add row to the Skills Available table

Framework Management Report

FRAMEWORK MANAGEMENT REPORT
════════════════════════════════════════
Operation:    [list | install | create | check]
Component:    [skill | agent]
Name:         [component name]
Source:       [built-in | network | created from scratch]
Discovery:    [built-ins checked ✓ | network searched ✓]

Built-in agents:   [N]
Built-in skills:   [N]

Status: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════════════════════════════

Supporting Files (Reference / Examples / Scripts)

When a skill's SKILL.md body grows beyond ~280 lines, extract reference material into skills/<name>/reference/<topic>.md (subdirectory, kebab-case topic). This follows Anthropic's progressive-disclosure convention.

Single project-wide rule:

• Reference: reference/<topic>.md (one file per topic; never a flat reference.md).
• Examples: examples/<name>.md (sample inputs/outputs Claude reads for shape).
• Scripts: scripts/<name>.{py,sh,js} (executable code Claude runs; never loaded as text).
• Linking: use ${CLAUDE_SKILL_DIR}/reference/<topic>.md in URLs — runtime-resolved.

Five advisory warnings in lib/check-skill-docs.js enforce skill-doc hygiene: (a) SKILL.md ≥ 300 lines && no reference/ dir, (b) any flat reference.md at a skill root, (c) generated SKILL.md with CRLF line endings, (d) literal {{PREAMBLE*}} token in raw prose (post-canonical occurrence), (e) any .tmpl mentioning CHANGELOG.md without a gen:changelog pointer (v0.6.11+). A separate hard-error scan catches deprecated phrases from v0.6.0.

Migration audit tool: when migrating a repo-wide invariant (e.g., a token rename, a deprecated API), run bin/audit-repo-invariants <pattern> (or npm run audit:invariants -- <pattern>) first. It lists all files referencing the pattern grouped by directory so you can classify usage sites vs sister-tools before editing — this catches the v0.6.0-style miss where lib/validate-skills.sh was overlooked during the legacy single-token preamble migration.

CHANGELOG draft generator (v0.6.10+): for new sprints, run npm run gen:changelog -- --version <X.Y.Z> to scaffold the CHANGELOG entry from Conventional Commits in the range last-tag..HEAD. The tool prints a skeleton draft to stdout (Added / Fixed / Changed / Removed sections + commit hash trailers); manually complete the Why this matters, Verified, and Deferred (v0.X.Y+ backlog) subsections before pasting into CHANGELOG.md. Uses lib/gen-changelog.js.

Reference: see reference/supporting-files.md for the full convention, subdirectory semantics, and canonical examples from the 5 skills trimmed in sprint v3 (2026-05-14).