@fission-ai/openspec 0.17.2 → 0.18.0

package/schemas/spec-driven/templates/design.md

@@ -0,0 +1,19 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->

package/schemas/spec-driven/templates/proposal.md

@@ -0,0 +1,23 @@
+## 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 -->

package/schemas/spec-driven/templates/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

package/schemas/spec-driven/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->

package/schemas/tdd/schema.yaml

@@ -0,0 +1,213 @@
+name: tdd
+version: 1
+description: Test-driven development workflow - tests → implementation → docs
+artifacts:
+  - id: spec
+    generates: spec.md
+    description: Feature specification defining requirements
+    template: spec.md
+    instruction: |
+      Create the feature specification that defines WHAT to build.
+
+      Sections:
+      - **Feature**: Name and high-level description of the feature's purpose and user value
+      - **Requirements**: List of specific requirements. Use SHALL/MUST for normative language.
+      - **Acceptance Criteria**: Testable criteria in WHEN/THEN format
+
+      Format requirements:
+      - Each requirement should be specific and testable
+      - Use `#### Scenario: <name>` with WHEN/THEN format for acceptance criteria
+      - Define edge cases and error scenarios explicitly
+      - Every requirement MUST have at least one scenario
+
+      Example:
+      ```
+      ## Feature: User Authentication
+
+      Users can securely log into the application.
+
+      ## Requirements
+
+      ### Requirement: Password validation
+      The system SHALL validate passwords meet minimum security requirements.
+
+      #### Scenario: Valid password accepted
+      - **WHEN** password has 8+ chars, uppercase, lowercase, and number
+      - **THEN** password is accepted
+
+      #### Scenario: Weak password rejected
+      - **WHEN** password is less than 8 characters
+      - **THEN** system displays "Password too short" error
+      ```
+
+      This spec drives test creation - each scenario becomes a test case.
+    requires: []
+
+  - id: tests
+    generates: "tests/*.test.ts"
+    description: Test files written before implementation
+    template: test.md
+    instruction: |
+      Write tests BEFORE implementation (TDD red phase).
+
+      File naming:
+      - Create test files as `tests/<feature>.test.ts`
+      - One test file per feature/capability
+      - Use descriptive names matching the spec
+
+      Test structure:
+      - Use Given/When/Then format matching spec scenarios
+      - Group related tests with `describe()` blocks
+      - Each scenario from spec becomes at least one `it()` test
+
+      Coverage requirements:
+      - Cover each requirement from the spec
+      - Include happy path (success cases)
+      - Include edge cases (boundary conditions)
+      - Include error scenarios (invalid input, failures)
+      - Tests should fail initially (no implementation yet)
+
+      Example:
+      ```typescript
+      describe('Password validation', () => {
+        it('accepts valid password with all requirements', () => {
+          // GIVEN a password meeting all requirements
+          const password = 'SecurePass1';
+          // WHEN validating
+          const result = validatePassword(password);
+          // THEN it should be accepted
+          expect(result.valid).toBe(true);
+        });
+
+        it('rejects password shorter than 8 characters', () => {
+          // GIVEN a short password
+          const password = 'Short1';
+          // WHEN validating
+          const result = validatePassword(password);
+          // THEN it should be rejected with message
+          expect(result.valid).toBe(false);
+          expect(result.error).toBe('Password too short');
+        });
+      });
+      ```
+
+      Follow the spec requirements exactly - tests verify the spec.
+    requires:
+      - spec
+
+  - id: implementation
+    generates: "src/*.ts"
+    description: Implementation code to pass the tests
+    template: implementation.md
+    instruction: |
+      Implement the feature to make tests pass (TDD green phase).
+
+      TDD workflow:
+      1. Run tests - confirm they fail (red)
+      2. Write minimal code to pass ONE test
+      3. Run tests - confirm that test passes (green)
+      4. Refactor if needed while keeping tests green
+      5. Repeat for next failing test
+
+      Implementation guidelines:
+      - Write minimal code to pass each test - no more, no less
+      - Run tests frequently to verify progress
+      - Keep functions small and focused
+      - Use clear, descriptive names
+
+      Code organization:
+      - Create source files in `src/<feature>.ts`
+      - Export public API clearly
+      - Keep implementation details private
+      - Add JSDoc comments for public functions
+
+      Example structure:
+      ```typescript
+      /**
+       * Validates a password meets security requirements.
+       * @param password - The password to validate
+       * @returns Validation result with valid flag and optional error
+       */
+      export function validatePassword(password: string): ValidationResult {
+        if (password.length < 8) {
+          return { valid: false, error: 'Password too short' };
+        }
+        // ... additional checks
+        return { valid: true };
+      }
+      ```
+
+      Don't over-engineer - implement only what tests require.
+    requires:
+      - tests
+
+  - id: docs
+    generates: "docs/*.md"
+    description: Documentation for the implemented feature
+    template: docs.md
+    instruction: |
+      Document the implemented feature.
+
+      Sections:
+      - **Overview**: What the feature does and why it exists (1-2 paragraphs)
+      - **Getting Started**: Quick start guide to use the feature immediately
+      - **Examples**: Code examples showing common use cases
+      - **Reference**: Detailed API documentation, configuration options
+
+      Guidelines:
+      - Write for the user, not the developer
+      - Start with the most common use case
+      - Include copy-pasteable code examples
+      - Document all configuration options with defaults
+      - Note any limitations, edge cases, or gotchas
+      - Link to related features or specs
+
+      Example structure:
+      ```markdown
+      ## Overview
+
+      Password validation ensures user passwords meet security requirements
+      before account creation or password changes.
+
+      ## Getting Started
+
+      Import and use the validation function:
+
+      ```typescript
+      import { validatePassword } from './password';
+
+      const result = validatePassword('MySecurePass1');
+      if (!result.valid) {
+        console.error(result.error);
+      }
+      ```
+
+      ## Examples
+
+      ### Basic validation
+      ...
+
+      ### Custom error handling
+      ...
+
+      ## Reference
+
+      ### validatePassword(password)
+
+      | Parameter | Type | Description |
+      |-----------|------|-------------|
+      | password | string | The password to validate |
+
+      **Returns**: `{ valid: boolean, error?: string }`
+      ```
+
+      Reference the spec for requirements, implementation for details.
+    requires:
+      - implementation
+
+apply:
+  requires: [tests]
+  tracks: null
+  instruction: |
+    Run tests to see failures. Implement minimal code to pass each test.
+    Refactor while keeping tests green.

package/schemas/tdd/templates/docs.md

@@ -0,0 +1,15 @@
+## Overview
+
+<!-- Feature overview -->
+
+## Getting Started
+
+<!-- Quick start guide -->
+
+## Examples
+
+<!-- Code examples -->
+
+## Reference
+
+<!-- API reference or additional details -->

package/schemas/tdd/templates/implementation.md

@@ -0,0 +1,11 @@
+## Implementation Notes
+
+<!-- Technical implementation details -->
+
+## API
+
+<!-- Public API documentation -->
+
+## Usage
+
+<!-- Usage examples -->

package/schemas/tdd/templates/spec.md

@@ -0,0 +1,11 @@
+## Feature: <!-- feature name -->
+
+<!-- Feature description -->
+
+## Requirements
+
+<!-- List of requirements -->
+
+## Acceptance Criteria
+
+<!-- List of acceptance criteria -->

package/schemas/tdd/templates/test.md

@@ -0,0 +1,11 @@
+## Test Plan
+
+<!-- Describe the testing strategy -->
+
+## Test Cases
+
+### <!-- Test case name -->
+
+- **Given:** <!-- preconditions -->
+- **When:** <!-- action -->
+- **Then:** <!-- expected result -->