openspec-generate-specs

Generate OpenSpec main specifications by analyzing the current project's code, documentation, issues, and pull requests.

Unlike

openspec-propose

(which creates a change with proposal/design/tasks artifacts for future work), this skill writes finished specs directly to

openspec/specs/

based on what already exists in the project.

Input: Optionally specify which capabilities or areas to generate specs for. If omitted, analyze the full project and determine capabilities automatically.

Steps

Gather project context

Collect information from all available sources. Prioritize breadth over depth — skim first, then deep-dive into relevant areas.

a. Project documentation:
- Read
```
AGENTS.md
```
  (or
```
CONTRIBUTING.md
```
  ,
```
README.md
```
  ) for architecture overview, conventions, and design decisions
- Read
```
docs/
```
  directory for feature specs, design docs, BDD features (
```
.feature
```
  files)
- Read
```
openspec/config.yaml
```
  for project context and rules
b. Codebase structure:
- Scan
```
src/
```
  directory tree to understand module organization
- Read key files (entry points, type definitions, core modules) to understand capabilities
- Identify the main functional areas / capabilities the system provides
c. GitHub issues and PRs (if available):
- Use GitHub MCP tools to fetch recent open/closed issues for requirements context
- Use GitHub MCP tools to fetch recent merged PRs for implemented features
- Extract requirement-like information (feature requests, bug fixes, design decisions)
d. Existing specs (if any):
- Read
```
openspec/specs/
```
  to understand what's already documented
- Identify gaps between existing specs and actual implementation
Identify capabilities
Based on the gathered context, determine the project's main capability areas. Each capability becomes a spec file at
```
openspec/specs/<capability>/spec.md
```
.
Use the AskUserQuestion tool to confirm the identified capabilities before proceeding:

"I've identified these capabilities from the project. Which should I generate specs for?"

Present the list with brief descriptions. Let the user select all or a subset.
Naming convention: Use kebab-case for capability names (e.g.,
```
memory-system
```
,
```
platform-abstraction
```
,
```
acp-integration
```
).
Check existing specs

For each selected capability:
- If
```
openspec/specs/<capability>/spec.md
```
  already exists, read it
- Use AskUserQuestion tool to ask: "Spec for
```
<capability>
```
  already exists. Overwrite, merge, or skip?"
  - Overwrite: Replace entirely with newly generated spec
  - Merge: Add missing requirements/scenarios to existing spec, preserve existing content
  - Skip: Leave as-is
Generate specs

For each capability, create a spec file following the OpenSpec spec format.

Use the TodoWrite tool to track progress through capabilities.
Spec file structure (
```
openspec/specs/<capability>/spec.md
```
):
markdown
```
# <Capability Name>

## Purpose

<Brief description of what this capability does and why it exists.>

## Requirements

### Requirement: <Requirement Name>

<The system SHALL/SHOULD/MAY description using RFC 2119 language.>

#### Scenario: <Scenario Name>
- **GIVEN** <precondition>
- **WHEN** <action>
- **THEN** <expected outcome>

#### Scenario: <Another Scenario>
- **GIVEN** <precondition>
- **WHEN** <action>
- **THEN** <expected outcome>
```
Writing guidelines:
- Use RFC 2119 keywords (SHALL, SHOULD, MAY) for requirement strength
- Derive requirements from actual code behavior, not aspirational features
- Include scenarios that reflect real code paths (check tests for scenario ideas)
- Reference source files in requirement descriptions when helpful (e.g., "Implemented in
```
src/core/workspace-manager.ts
```
  ")
- Keep requirements atomic — one concern per requirement
- Group related scenarios under their parent requirement
Write spec files

For each capability:
bash
```
mkdir -p openspec/specs/<capability>
```
Write the spec content to
```
openspec/specs/<capability>/spec.md
```
.
After writing each file, verify it exists and show brief progress.
Validate output

Run validation if available:
bash
```
openspec validate --specs --json
```
If validation fails, fix issues and re-validate.

Show summary

Display what was generated:

## Specs Generated

| Capability | Requirements | Scenarios | Status |
|------------|-------------|-----------|--------|
| <name>     | N           | M         | New/Merged/Overwritten |

Total: X capabilities, Y requirements, Z scenarios

Files written to `openspec/specs/`.

Source Priority

When information conflicts across sources, prefer in this order:

Actual code behavior (ground truth)
Test assertions (verified behavior)
BDD feature files / design docs (intended behavior)
GitHub issues/PRs (discussed behavior)
README / AGENTS.md (described behavior)

Guardrails

Always confirm capability list with user before generating
Never fabricate requirements not supported by code or documentation
If a capability area is ambiguous, ask for clarification
Preserve existing spec content when merging (only add, don't remove unless user confirms)
Each spec file must have at least a Purpose section and one requirement
Use consistent formatting across all generated spec files

openspec-generate-specs

NPX Install

Tags

SKILL.md Content