OpenSpec — Prompts
The most important prompt content in OpenSpec lives in:
schemas/spec-driven/schema.yaml — per-artifact instruction: fields (the directives given to the AI for each artifact)schemas/spec-driven/templates/*.md — blank starter templates the AI fills insrc/commands/workflow/instructions.ts — the XML-tagged output format the CLI emits to the AI- Generated
SKILL.md files (per-tool, installed into .tool/skills/openspec-*/SKILL.md)
Excerpt 1 — Proposal Artifact Instruction (from schemas/spec-driven/schema.yaml)
This is the verbatim instruction: field for the proposal artifact. It is injected into the AI's context whenever it creates proposal.md.
instruction: |
Create the proposal document that establishes WHY this change is needed.
Sections:
- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
- **Capabilities**: Identify which specs will be created or modified:
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
- **Impact**: Affected code, APIs, dependencies, or systems.
IMPORTANT: The Capabilities section is critical. It creates the contract between
proposal and specs phases. Research existing specs before filling this in.
Each capability listed here will need a corresponding spec file.
Keep it concise (1-2 pages). Focus on the "why" not the "how" -
implementation details belong in design.md.
This is the foundation - specs, design, and tasks all build on this.
Technique: Explicit section-by-section decomposition with named constraints ("1-2 sentences", "Keep it concise (1-2 pages)"), a role separation directive ("Focus on the 'why' not the 'how'"), and a named IMPORTANT warning that highlights cross-artifact dependency ("The Capabilities section is critical. It creates the contract between proposal and specs phases.").
Excerpt 2 — Specs Artifact Instruction (from schemas/spec-driven/schema.yaml)
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>/ when creating the delta spec at specs/<capability>/spec.md.
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.
MODIFIED requirements workflow:
1. Locate the existing requirement in openspec/specs/<capability>/spec.md
2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
4. Ensure header text matches exactly (whitespace-insensitive)
Common pitfall: Using MODIFIED with partial content loses detail at archive time.
If adding new concerns without changing existing behavior, use ADDED instead.
Example:
ADDED Requirements
Requirement: User can export data
The system SHALL allow users to export their data in CSV format.
Scenario: Successful export
- WHEN user clicks "Export" button
- THEN system downloads a CSV file with all user data
REMOVED Requirements
Requirement: Legacy export
Reason: Replaced by new export system
Migration: Use new export endpoint at /api/v2/export
Specs should be testable - each scenario is a potential test case.
Technique: Structured delta-diff format with four named operation types (ADDED / MODIFIED / REMOVED / RENAMED), normative language enforcement (SHALL/MUST), a "CRITICAL" header-level warning to prevent silent parser failures, a numbered step-by-step MODIFIED workflow, and an inline example. The technique surfaces common pitfalls ("Using MODIFIED with partial content loses detail at archive time") to pre-empt AI mistakes.
Excerpt 3 — Tasks Artifact Instruction (from schemas/spec-driven/schema.yaml)
instruction: |
Create the task list that breaks down the implementation work.
**IMPORTANT: Follow the template below exactly.** The apply phase parses
checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
Guidelines:
- Group related tasks under ## numbered headings
- Each task MUST be a checkbox: `- [ ] X.Y Task description`
- Tasks should be small enough to complete in one session
- Order tasks by dependency (what must be done first?)
Example:
1. Setup
2. Core Implementation
Reference specs for what needs to be built, design for how to build it.
Each task should be verifiable - you know when it's done.
Technique: Machine-parseable format constraint (- [ ] X.Y required for automated progress tracking) combined with cross-artifact grounding ("Reference specs for what needs to be built, design for how to build it"). The instruction explains why the format is required (the apply phase parses it), giving the AI a principled reason not to deviate.
Excerpt 4 — Apply Phase Instruction (from schemas/spec-driven/schema.yaml)
apply:
requires: [tasks]
tracks: tasks.md
instruction: |
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.
Technique: Minimal instruction that defers all complexity to the pre-generated planning artifacts. The AI is instructed to read context files (the proposal, specs, design, tasks it has already agreed to), not to re-plan. "Pause if you hit blockers or need clarification" is the only human-approval gate built into the schema.
When openspec instructions <artifact> is run, the CLI emits structured XML-like tags for the AI to consume:
// Opening tag
console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
// Warning for blocked artifacts
console.log('<warning>');
console.log('This artifact has unmet dependencies. Complete them first or proceed with caution.');
console.log(`Missing: ${missing.join(', ')}`);
console.log('</warning>');
// Task directive
console.log('<task>');
console.log(`Create the ${artifactId} artifact for change "${changeName}".`);
console.log(description);
console.log('</task>');
// Project context (AI constraint - do not include in output)
console.log('<project_context>');
console.log('<!-- This is background information for you. Do NOT include this in your output. -->');
console.log(context);
console.log('</project_context>');
Technique: XML/HTML-like semantic tags (<artifact>, <task>, <warning>, <project_context>, <rules>, <template>, <dependencies>, <unlocks>) to segment the AI's context into distinct roles. The <!-- This is background information for you. Do NOT include this in your output. --> comment is a meta-instruction embedded in the context block. This is a structured-context prompting pattern that prevents context bleed into generated output.
Excerpt 6 — Proposal Template (from schemas/spec-driven/templates/proposal.md)
This is the blank template the AI fills in:
## Why
<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
## What Changes
<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
## Capabilities
### New Capabilities
<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
- `<name>`: <brief description of what this capability covers>
### Modified Capabilities
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
Only list here if spec-level behavior changes. Each needs a delta spec file.
Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
- `<existing-name>`: <what requirement is changing>
## Impact
<!-- Affected code, APIs, dependencies, systems -->
Technique: HTML comments as inline context hints (explaining what to write and why) rather than leaving empty sections. The template constrains the AI to kebab-case identifiers and explicitly references how each capability entry creates a downstream file (specs/<name>/spec.md), making the template self-documenting.