openspec-generate-specs

OpenSpec Specification Generator

Generate OpenSpec spec files that help developers understand and safely modify an existing system.

This skill works for any project domain, but it is only for current-state documentation in brownfield projects.

Its purpose is to bootstrap OpenSpec for a project that already exists by recording implemented behavior in separate specs.

It should remain useful for applications, APIs, libraries, internal tools, automation, and infrastructure-oriented repositories alike.

Do not use this skill for proposals, future design, or planned changes that are not yet implemented. If the user wants speculative design work, use a different workflow.

Outcome

For each selected capability, produce or update openspec/specs/<capability>/spec.md with:

• A Purpose section
• At least one requirement with RFC 2119 language
• One or more scenarios that make the requirement concrete
• Enough operational and architectural context that a future developer can tell what the capability is responsible for, what must remain true, and where to start implementing or modifying it

Quality Bar

Optimize for these qualities in every generated spec set:

• Clarity over exhaustiveness. Capture the behavior and constraints that matter for safe implementation, not every incidental detail.
• Modular boundaries first. Default to one spec per feature, slice, workflow, adapter, provider, or other unit that could reasonably be implemented, changed, added, or removed independently.
• Behavior-shaped boundaries. Each spec should describe one coherent capability that a developer can reason about without reconstructing the system from several thin documents, but do not collapse multiple independently changeable slices into one broad system-level spec.
• Honest evidence handling. Separate implemented behavior, inferred meaning, and open questions. Do not present a guessed rule as implemented unless the code or other supporting evidence justifies it.
• Explicit invariants. Call out shared rules, ownership boundaries, ordering constraints, state transitions, and failure expectations when they materially affect design or implementation.
• Operational usefulness. Include triggers, entry points, decision rules, persistence semantics, and runtime boundaries when they matter to future changes.
• Shared layers only when necessary. Create broader specs for foundations, runtime layers, or cross-cutting contracts only when they are important shared foundations and cannot be described cleanly inside a single modular feature spec.

Workflow

1. Confirm current-state scope

   Confirm that the task is to document behavior the system already implements.

   This skill is only for current-state documentation. Use it to describe the system as it exists today, not to define future behavior.

   If the user mixes current-state documentation with proposed changes, ask them to narrow the scope to the implemented behavior that should be recorded now.

2. Gather project context

   Collect context broadly before going deep. Start with the sources that are most likely to describe the capability clearly.

   Read sources in this order when available:

   • Project guidance: AGENTS.md, CONTRIBUTING.md, README.md
   • Existing OpenSpec assets: openspec/config.yaml, openspec/specs/
   • User request, issue text, design notes, architecture docs, ADRs, .feature files, product docs
   • Main code paths and tests: src/, app/, lib/, packages/, tests/, or equivalent
   • Recent issues and pull requests, if tooling is available

   While reading, focus on decision-making surfaces:

   • entry points and interfaces
   • domain models and state transitions
   • business rules and validation
   • workflows, jobs, commands, handlers, and routes
   • data ownership and persistence boundaries
   • configuration, runtime behavior, startup, scheduling, and health surfaces
   • tests that define expected outcomes or edge cases

   During this pass, keep a lightweight inventory of candidate capabilities with:

   • capability name in progress
   • primary actor, caller, or trigger
   • primary observable outcome
   • whether it appears independently implementable, replaceable, or removable
   • key invariants or constraints
   • strongest evidence anchors
   • whether the candidate is strongly evidenced by code, tests, docs, or only partially evidenced

3. Identify capability boundaries

   Derive capability candidates from the system's actual behavior and current implementation boundaries, not from folder names or idealized architecture.

   Use kebab-case for capability names such as workspace-indexing, order-cancellation, report-export, or theme-customization.

   Use these decomposition lenses as needed:

   • Actor lens: who or what invokes the behavior
   • Workflow lens: what end-to-end outcome the system produces
   • Interface lens: API, command, event, page, protocol, or other interaction surface
   • Modularity lens: what could realistically be implemented, added, replaced, disabled, or removed without redesigning the whole system
   • Domain lifecycle lens: creation, approval, publication, reconciliation, archival, deletion, and similar transitions
   • Runtime lens: scheduling, background work, startup, orchestration, retries, health checks, or resilience behavior
   • Policy lens: validation, authorization, prioritization, quotas, deduplication, ownership, and other cross-cutting rules

   The final capability list may contain any number of specs, be that 5- or 50 specs. The number of specs is not a quality metric; use the system and its boundaries to decide how many specs to create, not a feeling of what a good number of specs looks like. Remember creating these specs will be delegated to a host of other agents in seperate forks, so creating any number of specs is achievable.

   Bias toward the smallest capability boundary that still produces a useful spec. If one broad candidate contains several slices that a team could implement or retire separately, split them.

   In particular, do not group multiple providers, integrations, adapters, backends, external systems, or strategy implementations into one capability when each has its own behavior, mapping, configuration, runtime contract, or test surface. Prefer one spec per such slice, plus a separate shared-layer spec only if a real shared contract needs to be preserved.

   Keep a candidate as its own capability when most of these are true:

   • it has a distinct trigger, actor, interface, or runtime boundary
   • it has a primary observable outcome that can be stated simply
   • it carries rules or constraints that are not merely incidental details of a larger flow
   • it could plausibly be implemented, modified, replaced, enabled, disabled, or removed with limited impact on adjacent slices
   • it can be implemented, tested, or changed with a mostly local understanding
   • a future maintainer could read this spec and know where to start

   Split a candidate when:

   • one document would bundle several providers, integrations, adapters, external systems, or strategy implementations that behave differently enough to be changed separately
   • one document would otherwise mix unrelated outcomes or actors
   • one part is a reusable policy or invariant that affects multiple workflows
   • the implementation already treats the slices independently
   • different slices have different configuration, mappings, state handling, persistence rules, external dependencies, or test anchors
   • a team could reasonably add, remove, or swap one slice without rewriting the others
   • the requirement list starts reading like a table of contents instead of one contract

   Merge adjacent candidates when:

   • they share the same trigger, outcome, and invariants
   • they are not realistically implemented or changed independently
   • splitting them would force developers to consult multiple thin specs to understand one real change
   • the current implementation still treats them as one coherent workflow

   Create broader system-layer or cross-cutting specs only when they describe infrastructure that multiple feature specs build on, such as shared orchestration, authorization policy, persistence conventions, event contracts, or runtime lifecycle rules.

   Avoid these anti-patterns:

   • naming capabilities after folders or layers instead of behavior
   • creating entity-only specs when the real behavior is broader than one data type
   • splitting conceptual sub-steps that are never triggered or reasoned about independently
   • collapsing several modular features into one spec just because they belong to the same subsystem
   • grouping multiple providers or integrations into a single spec when each one would merit its own implementation slice
   • writing separate specs for exceptions when a single rule would stay clearer and more accurate
   • letting a hoped-for architecture override the real system shape

   Example of preferred granularity:

   • prefer holfuy-station-sync, metfrost-station-sync, portwind-station-sync, and windsmobi-station-sync
   • only add a broader spec such as weather-station-platform-contract if there is a real shared contract or layer that those separate specs build upon

   Before writing any spec, prepare a candidate list with:

   • capability name
   • one-sentence purpose
   • why it is separate from adjacent candidates
   • primary trigger or entry point
   • primary observable outcome
   • why it is modular enough to deserve its own spec, or why it must remain a broader shared-layer spec
   • strongest evidence anchors

4. Present the capability list and stop for user direction

   After exploration, Reply with an enumerate list of specs followed by the "next step" section. For each one, include:

   • capability name
   • one-line purpose

   Next step: Give the user these

Content truncated.