# 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 update.

- Skill: `v0lka/vibespec-create` (Agent Skill)
- Install (CLI): `npx skillmds@latest add v0lka/vibespec-create`
- Raw SKILL.md: https://api.skillmd.com/api/skills/v0lka/vibespec-create/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: v0lka (https://skillmd.com/u/v0lka)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/v0lka/vibespec-create

---


# 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** | New architectural decision | `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:**
- Determine the next sequential number by checking existing files in `specs/decisions/`
- Numbers are NEVER reused (even for superseded ADRs)
- Once `Status: Accepted`, the ADR is immutable
- To change a 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 an 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)
- [ ] 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