mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
d73705736f
* feat: make apply instructions schema-aware
The `generateApplyInstructions` function was hardcoded to check for
`spec-driven` artifacts. This change makes it read artifact definitions
from the schema's new `apply` block, enabling support for different
workflows like TDD.
Changes:
- Add `ApplyPhaseSchema` Zod schema with `requires`, `tracks`, and
`instruction` fields to types.ts
- Update `SchemaYamlSchema` to include optional `apply` field
- Add `apply` block to spec-driven and tdd schemas
- Refactor `generateApplyInstructions` to:
- Load schema via `resolveSchema()`
- Read `apply.requires` for required artifacts
- Check artifact existence dynamically (supports glob patterns)
- Use `apply.tracks` for progress tracking (or skip if null)
- Use `apply.instruction` for custom guidance
- Build `contextFiles` from all existing artifacts in schema
- Handle fallback when schema has no `apply` block (require all artifacts)
- Add 8 new tests for schema-aware apply behavior
* fix: improve apply instructions robustness and consistency
- Fix artifactOutputExists to properly handle glob patterns cross-platform
by using path.sep and verifying actual file matches
- Remove redundant if/else in contextFiles loop
- Distinguish between missing tracks file vs empty tracks file
- Use consistent { error: } key in ApplyPhaseSchema validation
- Rename fallback test to accurately describe what it tests
* test: add fallback behavior tests for schemas without apply block
Add two tests that verify the fallback logic when a schema lacks an
apply block:
- Blocks when not all artifacts exist (requires ALL artifacts)
- Ready state with default instruction when all artifacts exist
Uses XDG_DATA_HOME to create temporary user schemas for testing.
149 lines
6.3 KiB
YAML
149 lines
6.3 KiB
YAML
name: spec-driven
|
|
version: 1
|
|
description: Default OpenSpec workflow - proposal → specs → design → tasks
|
|
artifacts:
|
|
- id: proposal
|
|
generates: proposal.md
|
|
description: Initial proposal document outlining the change
|
|
template: 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.
|
|
requires: []
|
|
|
|
- id: specs
|
|
generates: "specs/**/*.md"
|
|
description: Detailed specifications for the change
|
|
template: spec.md
|
|
instruction: |
|
|
Create specification files that define WHAT the system should do.
|
|
|
|
Create one spec file per capability/feature area in specs/<name>/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.
|
|
requires:
|
|
- proposal
|
|
|
|
- id: design
|
|
generates: design.md
|
|
description: Technical design document with implementation details
|
|
template: design.md
|
|
instruction: |
|
|
Create the design document that explains HOW to implement the change.
|
|
|
|
When to include design.md (create only if any apply):
|
|
- Cross-cutting change (multiple services/modules) or new architectural pattern
|
|
- New external dependency or significant data model changes
|
|
- Security, performance, or migration complexity
|
|
- Ambiguity that benefits from technical decisions before coding
|
|
|
|
Sections:
|
|
- **Context**: Background, current state, constraints, stakeholders
|
|
- **Goals / Non-Goals**: What this design achieves and explicitly excludes
|
|
- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
|
|
- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
|
|
- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
|
|
- **Open Questions**: Outstanding decisions or unknowns to resolve
|
|
|
|
Focus on architecture and approach, not line-by-line implementation.
|
|
Reference the proposal for motivation and specs for requirements.
|
|
|
|
Good design docs explain the "why" behind technical decisions.
|
|
requires:
|
|
- proposal
|
|
|
|
- id: tasks
|
|
generates: tasks.md
|
|
description: Implementation tasks derived from specs and design
|
|
template: tasks.md
|
|
instruction: |
|
|
Create the task list that breaks down the implementation work.
|
|
|
|
Guidelines:
|
|
- Group related tasks under ## numbered headings
|
|
- Each task is 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
|
|
|
|
- [ ] 1.1 Create new module structure
|
|
- [ ] 1.2 Add dependencies to package.json
|
|
|
|
## 2. Core Implementation
|
|
|
|
- [ ] 2.1 Implement data export function
|
|
- [ ] 2.2 Add CSV formatting utilities
|
|
```
|
|
|
|
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.
|
|
requires:
|
|
- specs
|
|
- design
|
|
|
|
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.
|