Create Specifications

Create Specifications

Produces a detailed technical specification from a requirements document, covering architecture, data models, API contracts, component design, and key sequences.

Prerequisites

• Apply the shared SDLC conventions in skills/sdlc/references/shared.md.
• If no argument is provided, locate the feature directory under .sdlc/features/ whose frontmatter issue field references $ISSUE_NUMBER.
• .sdlc/features/N-/requirements.md (must have passed review with findings verdict approved), or a requirements document provided in context or as a file path ($1)
• .sdlc/features/N-/existing-solutions.md (optional, if a prior-art survey was produced): adopt its recommendation and reuse the patterns it captured
• .sdlc/features/N-/codebase-analysis.md (optional, if existing code was analyzed): honor each component's change disposition and its "must not change" constraints, and follow the migration path for any refactor or replace

Steps

1. Read and understand the requirements document, the existing solutions survey if present, and the codebase analysis if present.
2. Identify the major components and their responsibilities.
3. Define data models: entities, attributes, and relationships.
4. Specify API contracts: endpoints, request/response schemas, and error codes.
5. Describe key sequences: user flows, system interactions, and async processes.
6. Document technical decisions and their rationale.
7. Identify risks, unknowns, and deferred decisions.
8. Design data models, API contracts, and persisted state for evolution so future versions stay forward compatible (see Forward Compatibility below).
9. Write the output to .sdlc/features/N-/specification.md.

Forward Compatibility

A forward-compatible design keeps working as the system evolves without forcing coordinated upgrades on every consumer. When specifying data models and API contracts, ensure they can grow additively:

• Tolerate unknown fields: consumers must ignore (or preserve) fields they do not recognize rather than rejecting the payload. Specify this explicitly for every schema.
• Handle unknown enum values gracefully: closed enums that throw on unseen values lock out future additions. Prefer open enums, or require consumers to fail soft on unknown values.
• Prefer additive changes: new optional fields, new endpoints, and new values are safe; removing, renaming, or repurposing existing ones is not. Call out which elements are part of the stable surface versus open to change.
• Version the contract: include a schema/API version field where practical, and state the compatibility policy (e.g., additive-only within a major version).
• Reserve extension points for known likely future change (reserved field numbers, extension columns, feature flags) rather than baking in assumptions that the current shape is final.
• Avoid positional coupling and fixed-set assumptions that would make a future addition a breaking change.

Output Format

Use the template at skills/sdlc/templates/features/specification.md (copied to .sdlc/templates/features/specification.md by /initialize-sdlc-directory; use the project's customized copy if present). Write the result to the artifact path named in the steps above. Client → Service → DB | | | POST /thing | |---------------->| | |--- INSERT --- | 201 Created | |

Out of Scope

## Outcome

If `$OUTCOME_YAML` is set, emit `verdict: approved` there per `skills/sdlc/references/shared.md`, If the artifact could not be produced, omit the file.

## Example Usage

**Scenario 1: Feature with an API and database**
Requirements describe a password reset flow.
Spec defines the `password_reset_tokens` table, `POST /auth/reset-password` endpoint, token expiry sequence, and email dispatch contract.

**Scenario 2: Background job**
Requirements ask for async processing.
Spec defines the job queue schema, worker interface, retry policy, and failure alerting sequence.

## Completion Checklist

Before handing off to review, confirm:

- [ ] Data models and API contracts designed for forward compatibility (tolerate unknown fields/values, additive changes)

Self-check the draft against the [`review-specifications` checklist](../review-specifications/SKILL.md) and fix what you can, so review finds less to flag.

## Next Step

Run `/review-specifications` to audit for ambiguities, inconsistencies, and gaps before moving on.
Once approved, continue with `/create-plan`.

## Useful Commands Reference

No CLI commands required. This skill operates on document content provided in context.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tomzx](https://github.com/tomzx)
- **Source:** [tomzx/agents](https://github.com/tomzx/agents)
- **License:** MIT

Install and usage instructions live in the source repository linked above.