vibespec-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
Install
npx skills add https://github.com/v0lka/skills/tree/main/development/vibespec/vibespec-create
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install v0lka-skills@llmmart
git clone https://github.com/v0lka/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole v0lka/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.mdinside a domain directory: overview and entry point_template.mdprefix: 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
# [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
# [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
# 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
# [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)
# 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 vibespec-init Step 8 and the WORKFLOW.md template):
Create an ADR only if the decision meets BOTH:
- Constrains work beyond the immediate change — cross-domain, cross-cutting, or hard to reverse
- Had real alternatives considered and rejected — a genuine choice existed, and the rejected options are worth remembering
OR meets this one alone:
- 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 leadingNNNfrom 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: Acceptedlocks an ADR only once its current content is committed to the repository — verify withgit 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:
- Add an entry to the "Navigation by Task" table (if applicable)
- Add an entry to the "Directory Listing" section
- 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
Files (skills)
-
SKILL.md 8.5 KB
--- name: vibespec-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 vibespec-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
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.