OpenSpec Progressive Superpowers

Configures OpenSpec’s config.yaml so that every artifact instruction automatically carries project context and invokes the right superpowers skills at each workflow step. This is a setup skill — run once per project, update when conventions or available skills change.

The problem it solves: Skills are session-scoped. If you invoke TDD in one session but create artifacts in another, TDD is forgotten. config.yaml is the cross-session memory that ensures conventions survive.

When to Use

• New project setup: After openspec init or when config.yaml is empty/default
• Missing discipline: Agent didn’t invoke TDD during apply, skipped progressive phases, ignored project conventions
• New skills added: Installed new superpowers or tech-specific skills that should be woven into the OpenSpec workflow
• Project docs changed: New PRD, updated system spec, changed tech stack

Process

Step 1: Discover Project Context

Scan for project documentation to extract context:

Search order:
1. docs/**/*.md, docs/**/*.txt         — specs, PRDs, architecture docs
2. CLAUDE.md, .claude/CLAUDE.md        — existing developer context
3. openspec/config.yaml                — current config (may be empty)
4. Cargo.toml, package.json, go.mod    — tech stack signals
5. openspec/specs/**/*.md              — existing capability specs

Extract from these sources:

• Project identity: Name, purpose, domain (1-2 sentences)
• Tech stack: Language, framework, key libraries, build system
• Architecture principles: From system spec or CLAUDE.md
• Subsystem structure: If multi-service, how they relate

Step 2: Discover Available Skills

Scan the installed skills to build a mapping of what’s available:

Superpowers skills (check the skill list in system prompt):

• superpowers:test-driven-development — TDD discipline
• superpowers:systematic-debugging — debugging methodology
• superpowers:brainstorming — creative exploration before implementation
• superpowers:writing-plans — plan creation from specs
• superpowers:executing-plans — plan execution with review checkpoints
• superpowers:verification-before-completion — evidence-based verification
• superpowers:requesting-code-review — review after implementation
• superpowers:finishing-a-development-branch — branch completion workflow

Tech-specific skills (check installed plugins):

• fp-rust — FP-first Rust conventions
• fp-kstream-design / fp-kstream-implement — Kafka Streams
• Any other domain-specific skills

OpenSpec skills:

• openspec-progressive-implementation — progressive phase discipline

Only reference skills that are actually installed. Do NOT reference skills that don’t exist in the environment.

Step 3: Map Skills to OpenSpec Workflow Steps

Build the mapping. Each OpenSpec artifact type and action maps to specific skills:

Step 4: Generate config.yaml

Write openspec/config.yaml with two sections:

context: section

Project identity and development discipline. This is injected into every openspec instructions call. Structure it as:

context: |
  ## Project: <name>
  <1-2 sentence description from project docs>

  Reference docs:
  <list paths to key docs: system spec, PRDs, etc.>

  ## Tech Stack
  <language, framework, key libraries, build system>

  ## Architecture Principles
  <from system spec or CLAUDE.md — keep to 3-5 bullets>

  ## Development Discipline
  <list each discipline with its skill reference>
  - TDD (red-green-refactor): Use superpowers:test-driven-development during apply.
  - Progressive implementation: Use openspec-progressive-implementation for
    proposal and tasks artifacts.
  - <tech-specific>: Use <skill-name> when writing <language> code.

rules: section

Per-artifact constraints. These are injected when creating specific artifact types.

rules:
  proposal:
    - Follow progressive-implementation discipline when defining phases.
    - Each phase must be reviewable, testable, contract-bounded, and documented.
    - "Contracts exposed" section required per phase.
    - Reference PRD section numbers for traceability.
  specs:
    - Every requirement MUST have at least one WHEN/THEN scenario.
    - Scenarios must be directly translatable to TDD test cases.
  design:
    - Justify decisions with rationale and alternatives considered.
    - Flag risks with mitigations.
  tasks:
    - Follow progressive-implementation discipline for task structure.
    - Each phase's LAST task must update documentation with manual verification steps.
    - Include phase header with Contracts exposed, Gate criteria, and Docs update target.
    - Order tasks within each phase for TDD — test first, then implementation.
    - Each task must be completable in one TDD cycle.
    - Gate tasks (build, test, lint) required at the end.

Step 5: Present for Review

Show the generated config.yaml to the user. Highlight:

• Which project docs were used for context
• Which skills were discovered and mapped
• Any gaps (e.g., “no tech-specific skill found for your language”)

Anti-Rationalization Table

Maintenance

Re-run this skill when:

• New PRD or system spec is added
• Tech stack changes (new language, framework)
• New skills are installed
• After a retrospective reveals a discipline gap (like TDD not being invoked)