SuperSpec — Prompts (Verbatim)
SuperSpec's prompts live in schema.yaml as instruction: fields within each artifact definition. These are passed to the AI as instructions when OpenSpec's continue command advances to each artifact.
1. brainstorm artifact instruction (verbatim from schema.yaml)
instruction: |
Use the Skill tool to invoke **superpowers:brainstorming**.
IMPORTANT output redirection:
- Do NOT write to `docs/superpowers/specs/`. Instead, write the
brainstorming design output directly to this change's `brainstorm.md`.
- If brainstorming produces a design document, also write it to
this change's `design.md` (this will pre-fill the design artifact).
After brainstorming completes, summarize the agreed design in
brainstorm.md using the template structure.
The brainstorming skill will:
1. Explore project context
2. Ask clarifying questions (one at a time)
3. Propose 2-3 approaches with trade-offs
4. Present design sections for approval
5. Output the validated design
Prompting technique: Skill invocation instruction + output redirection override. The instruction tells the AI to invoke an external skill (superpowers:brainstorming) and explicitly overrides where that skill writes its output — this is a cross-framework output routing pattern.
instruction: |
Create specification files that define WHAT the system should do.
Create one spec file per capability listed in the proposal's Capabilities section.
- New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
- Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/
Delta operations (use ## headers):
- **ADDED Requirements**: New capabilities
- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
- **RENAMED Requirements**: Name changes only - use FROM:/TO: format
Format requirements:
- Each requirement: `### Requirement: <name>` followed by description
- Use SHALL/MUST for normative requirements (avoid should/may)
- Each scenario: `#### Scenario: <name>` with WHEN/THEN format
- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or
bullets will fail silently.
- Every requirement MUST have at least one scenario.
Prompting technique: Normative language enforcement (SHALL/MUST) + silent-failure prevention. The "CRITICAL" annotation flags a subtle formatting requirement (4 vs 3 hashtags) that would cause silent downstream failures in OpenSpec's parser.
3. apply instruction — Pre-flight commit (verbatim excerpt)
apply:
instruction: |
0. **Pre-flight — commit change artifacts to current branch**:
Before creating the worktree, verify that the change directory
`openspec/changes/<name>/` is committed on the current branch.
This prevents drift between the main checkout and the worktree
during implementation.
Steps:
a. Run `git status --porcelain openspec/changes/<name>/`
b. If untracked entries (lines starting with `??`), stage and commit
ONLY this change's directory (do NOT use `git add -A`):
git add openspec/changes/<name>/
git commit -m "docs(openspec): scaffold <name> change
Captures pre-implementation artifacts (brainstorm/proposal/
specs/tasks/plan) so the implementation worktree starts
with the change directory already tracked."
Prompting technique: Defensive git procedure with explicit failure mode prevention. The git add -A anti-pattern is explicitly named and forbidden. The commit message format is specified verbatim including the conventional commit type.
4. verify artifact instruction (verbatim excerpt)
instruction: |
IMPORTANT timing note:
- Unlike other artifacts, verify.md is produced AFTER the apply
phase completes, NOT during planning. The `requires: [plan]`
edge exists only for schema graph purposes — the actual
verification step MUST run on a completed implementation.
The verify step MUST perform the following checks:
1. Structural validation: Run `openspec validate --all --json`
2. Task completion: Confirm every checkbox in tasks.md is `- [x]`
3. Delta spec sync state: Compare change specs vs. openspec/specs/<capability>/spec.md
4. Design/specs coherence: Spot-check design.md decisions against specs
5. Implementation signal: Confirm all code changes are committed
Prompting technique: Timing disambiguation (the requires graph edge is structural only, not temporal) + explicit 5-point verification checklist with machine-readable commands.
Key Prompting Techniques
- Skill invocation delegation: Instructions tell the AI to invoke named external skills, not to perform the action directly
- Output redirection overrides: SuperSpec consistently overrides default output paths to keep all artifacts in the change directory
- Silent-failure prevention: Critical formatting requirements (4 hashtags) are annotated with "CRITICAL" and "will fail silently"
- Defensive git procedures: Pre-flight checks name and forbid anti-patterns (
git add -A)
- Timing disambiguation: Temporal ordering is separated from dependency graph edges