spec-create
/spec-create
Create a new specification document following the project's spec system templates and conventions. Use when adding a new domain, component, contract, architecture doc, or Architecture Decision Record (ADR). Ensures correct format, naming, placement, cross-references, and INDEX.md update.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Create a new specification document following the project's spec system templates and conventions. Use when adding a new domain, component, contract, architecture doc, or Architecture Decision Record (ADR). Ensures correct format, naming, placement, cross-references, and INDEX.md update.
Original author description
Create a new specification document following the project's spec system templates and conventions. Use when adding a new domain, component, contract, architecture doc, or Architecture Decision Record (ADR). Ensures correct format, naming, placement, cross-references, and INDEX.md update.
How it works
- Procedure
- Templates
- Content Principles
SKILL.md preview
---
name: spec-create
description: Create a new specification document following the project's spec system templates and conventions. Use when adding a new domain, component, contract, architecture doc, or Architecture Decision Record (ADR). Ensures correct format, naming, placement, cross-references, and INDEX.md update.
---
# Spec Create
Create a new specification document in the project's `specs/` system. This skill ensures the document follows the correct template, naming conventions, and is properly registered.
---
## Procedure
### Step 1 — Determine document type
Identify which of the 5 spec types you need to create:
| Type | When to use | Location |
|------|-------------|----------|
| **Domain README** | New conceptual domain (multiple components) | `specs/domains/<domain>/README.md` |
| **Domain Detail** | New component within an existing domain | `specs/domains/<domain>/<component>.md` |
| **Contract** | New boundary between layers/modules | `specs/contracts/<layer-a>-<layer-b>.md` |
| **Architecture** | New system-level concern (layers, security, flow) | `specs/architecture/<topic>.md` |
| **ADR** | Decision that passes the ADR bar test (see ADR-specific rules): constrains work beyond the immediate change AND had rejected alternatives, OR supersedes an existing ADR/invariant | `specs/decisions/NNN-slug.md` |
### Step 2 — Read META.md
Read `specs/META.md` to confirm the template for your chosen type. The templates below are generic — always prefer the project's META.md if it exists, as it may have project-specific additions.
### Step 3 — Apply naming conventions
- Files: `kebab-case.md`
- Domain directories: created only when a domain requires multiple files
- `README.md` inside a domain directory: overview and entry point
- `_template.md` prefix: template files (not actual specs)
- ADR files: `NNN-kebab-case-slug.md` (three-digit sequential number)
### Step 4 — Write the document using the correct template
---
## Templates
### Domain README
```markdown
# [Domain Name]
## Purpose
1-3 sentences. What this domain does in the system.
## Key Files
- `path/from/repo/root/file.ext` — role description
## Core Types
Key type definitions (code blocks) with brief explanations.
## Flow
ASCII diagram or numbered sequence showing the primary happy path.
## Invariants
Bullet list of properties that ALWAYS hold. Affirmative phrasing only.
## Configuration
Key parameters from configuration with defaults and valid values.
## Extension Points
How to add new behavior without breaking existing functionality.
## Related Specs
- [Spec Name](relative/path.md) — relationship context
```
### Domain Detail
```markdown
# [Component Name]
## Role
1 sentence: what this component does within its domain.
## Key Files
- `path/to/file.ext` — description
## Behavior
Detailed description. May include:
- State machines (ASCII)
- Decision tables
- Pseudocode
- Sequence diagrams
## Error Handling
How this component handles and propagates errors.
## Invariants
Properties that always hold for this component. Affirmative phrasing only.
## Related Specs
- [Spec Name](relative/path.md) — relationship context
```
### Contract
```markdown
# Contract: [Layer A] <-> [Layer B]
## Boundary Rule
One sentence: direction of dependency and what is NOT allowed.
## Interfaces
| Interface | Package | Consumed By | Purpose |
| --------- | ------- | ----------- | ------- |
## Initialization
How components are wired together at startup.
## Data Flow Across Boundary
What data crosses the boundary, in what form, in which direction.
## Error Propagation
Rules for wrapping/transforming errors at this boundary.
## Breaking Change Checklist
If you change X, you MUST also update Y.
```
### Architecture
```markdown
# [Topic]
## Context
Why this architectural aspect matters.
## [Main Content]
Diagrams, rules, descriptions. Structure varies by topic.
## Invariants
Architectural rules that must never be violated. Affirmative phrasing only.
## Anti-Patterns
What NOT to do, with brief explanation of why.
```
### ADR (Architecture Decision Record)
```markdown
# ADR-NNN: [Title]
## Status
Accepted
## Context
The problem or question that required a decision.
## Decision
What was decided.
## Consequences
Positive and negative impacts.
## Alternatives Considered
What was evaluated and why it was rejected.
```
**ADR-specific rules:**
**The ADR bar test** (the same criteria as spec-init Step 8 and the WORKFLOW.md template):
Create an ADR only if the decision meets BOTH:
1. **Constrains work beyond the immediate change** — cross-domain, cross-cutting, or hard to reverse
2. **Had real alternatives considered and rejected** — a genuine choice existed, and the rejected options are worth remembering
OR meets this one alone:
3. **Contradicts or supersedes** an existing ADR or a documented invariant.
**Do NOT create an ADR for:**
- An implementation detail → record it as an invariant in the domain spec
- A local, cheaply reversible choice → record it in the domain spec
- Restating an existing spec or invariant → do nothing
- A decision with no genuine alternatives → record it in the domain spec
**`Alternatives Considered` is the bar.** If that section cannot be filled honestly, it is not an ADR — the decision belongs in a domain spec.
- Determine the next sequential number by scanning ALL files in `specs/decisions/` — including superseded ADRs. The scan is number-keyed: parse the leading `NNN` from each filename (`NNN-slug.md`) and ignore the slug; next number = highest parsed NNN + 1
- Numbers are NEVER reused (even for superseded ADRs)
- Under parallel branches, a freshly allocated number is provisional until that branch merges — a sibling branch may have allocated the same number in the meantime
- If a duplicate number reaches the tree at merge time, the second-landed ADR takes the next free number. When renumbering, update ALL of: the filename, the `# ADR-NNN: [Title]` heading, `Superseded by [NNN](./NNN-slug.md)` links in other ADRs, INDEX.md entries, and any cross-references to this ADR in other specs
- `Status: Accepted` locks an ADR only once its current content is committed to the repository — verify with `git status --porcelain -- specs/decisions/NNN-slug.md`: empty output = committed = locked (outside a git repository, treat every accepted ADR as committed)
- An accepted ADR that is untracked, or whose current content carries uncommitted changes, is still an editable draft: refine, reword, or rewrite it in place — no superseding ADR is needed; the commit is what locks it
- To change a committed decision: create a NEW ADR, then update the old one's Status to `Superseded by [NNN](./NNN-slug.md)` (this is the only allowed edit to a committed accepted ADR)
---
### Step 5 — Write cross-references
- Use relative paths from `specs/` directory
- Format: `[display text](relative/path.md)`
- Section anchors: lowercase, hyphen-separated: `[section](path.md#section-name)`
- Source code references: backtick path from repo root, e.g. `` `src/module/file.ext` ``
### Step 6 — Update INDEX.md
After creating the new spec file:
1. Add an entry to the "Navigation by Task" table (if applicable)
2. Add an entry to the "Directory Listing" section
3. Maintain alphabetical/logical ordering within sections
### Step 7 — Validate (embedded checklist)
Before declaring done, verify:
- [ ] All sections from the template are present and in correct order
- [ ] Cross-references point to existing files (verify with file reads)
- [ ] Paths in Key Files are accurate (verify files exist)
- [ ] Invariants are stated affirmatively ("X always does Y", NOT "X never does Z")
- [ ] INDEX.md has been updated to include the new file
- [ ] Naming follows conventions (kebab-case, correct directory)
- [ ] ADR only: no other file in `specs/decisions/` carries the same NNN number
- [ ] No filler prose — every sentence carries information
- [ ] ASCII diagrams used for flows (not Mermaid or other renderers)
---
## Content Principles
- **Agent-optimized**: predictable structure, explicit cross-references, no filler prose
- **Invariants are affirmative**: "The scheduler always processes tasks in priority order" (not "The scheduler should not skip high-priority tasks")
- **Key Files use repo-root paths**: `src/core/scheduler.go`, not `./scheduler.go`
- **Tables for catalogs**: interface catalogs, tool registries, config mappings, decision tables
- **ASCII for diagrams**: must work without a renderer
- **No generated content**: specs describe intended behavior; discrepancy with code = bug
Versions
The database has no other skills named spec-create.
Database snapshot: 13.11.2026 · package version e3536ff7c7be (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100vibespec-create
Create a new specification document following the project's spec system templates and conventions. Use when adding a new domain, component, contract, architecture doc, or Architecture Decision Record (ADR). Ensures correct format, naming, placement, cross-references, and INDEX.md update. - 100record-decision
Append a new Architecture Decision Record (ADR) to the repo with an auto-incremented number and the MADR template. TRIGGER when the user says "record this decision", "log this decision", "add an ADR for X", "create an ADR about Y", "record the choice to use Postgres", "write up… - 100spec-write
Author timeless specification documents under spec/ (top-level or spec/feature/<FEATURE>.md) following the project hierarchy, naming conventions, and templates. Use when the user asks to write, design, or document a DataSpoke feature, component, or architectural decision as a… - 100adr
Create a new Architecture Decision Record (ADR) using MADR format. Use when the user wants to document an architectural decision, says "create an ADR", "we need an ADR for", or discusses a decision that should be recorded. - 100adr
Documents architecture decisions with auto-numbering following the ADR pattern. Triggers on keywords: adr, architecture decision, decision record - 86adr
Record an architecture decision as a short ADR in docs/adr and index it in docs/ARCHITECTURE.md. Use when a significant technical choice is made (state management, module boundaries, persistence, audio pipeline, a new shared pattern) or when the user asks to record or document a decision.