# Vibespec Init

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-v0lka-skills-vibespec-init`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [v0lka](https://agentstack.voostack.com/s/v0lka)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [v0lka](https://github.com/v0lka)
- **Source:** https://github.com/v0lka/skills/tree/main/development/sdd/vibespec-init

## Install

```sh
agentstack add skill-v0lka-skills-vibespec-init
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Spec System Initialization

Bootstrap a complete specification system for a project by analyzing its codebase and generating an initial set of structured, agent-optimized spec documents.

## Context

A spec system gives AI agents deterministic context about intended behavior, interfaces, and architectural decisions — enabling safe changes without full codebase exploration. This skill creates the system from scratch, tailored to the project's actual structure.

## Prerequisites

- The project must have an existing codebase (not an empty repo)
- No `specs/` directory should exist yet (or user confirms overwrite)
- The agent needs to understand the project's language(s), module system, and directory structure

---

## Procedure

### Step 1 — Confirm scope and location

Ask the user:
1. Where should the specs live? (default: `specs/` at repository root)
2. Is there an existing `AGENTS.md` or similar file to add a pointer to specs?
3. Are there specific areas they want prioritized or skipped?

If `specs/` already exists, warn the user and ask whether to overwrite or abort.

### Step 2 — Analyze the codebase

Perform a systematic analysis to identify:

**Layers / Modules:**
- Top-level directories and their responsibilities
- Import/dependency direction between layers
- Entry points and initialization flow

**Domains:**
- Conceptual areas of functionality (NOT mirroring file structure)
- Key types, interfaces, and data structures per domain
- Primary flows (happy paths)

**Boundaries:**
- Where layers interact (interfaces, RPC, events, shared types)
- Dependency direction rules (who imports whom)
- Data transformation at boundaries

**Architectural decisions already made:**
- Technology choices evident from dependencies (DB, frameworks, protocols)
- Patterns in use (event-driven, layered, hexagonal, etc.)
- Constraints from the build system or module structure

**Configuration:**
- Config file format and location
- Key parameters and their domains

Document your findings as working notes before proceeding to generation.

### Step 3 — Design the spec structure

Based on analysis, design the directory structure:

```
specs/
├── META.md
├── INDEX.md
├── WORKFLOW.md
│
├── architecture/
│   └── (identified system-level concerns)
│
├── domains/
│   ├── /
│   │   ├── README.md
│   │   └── .md (if domain has multiple components)
│   └── .md (if single-file domain)
│
├── contracts/
│   └── -.md (for each identified boundary)
│
└── decisions/
    └── _template.md
```

Present the proposed structure to the user for approval before generating files.

### Step 4 — Generate META.md

Use the template from `assets/meta-template.md` as the base. Adapt the "File Organization" section to reflect the actual structure designed in Step 3.

META.md is the foundational document — all other specs reference it for templates and rules. Generate it first.

### Step 5 — Generate architecture specs

For each identified system-level concern, create a spec in `architecture/`:

Common topics (generate only those relevant to the project):
- **layers.md** — layer hierarchy, import rules, responsibilities
- **data-flow.md** — request lifecycle, event flow
- **security-model.md** — auth, authorization, policy enforcement

Follow the Architecture template from META.md. Include:
- ASCII dependency diagram
- Import rules as invariants
- Anti-patterns specific to this project's architecture

### Step 6 — Generate domain specs

For each identified domain:

**If domain has multiple components** → create a directory:
- `README.md` (Domain README template) — overview, key files, core types, flow, invariants
- `.md` (Domain Detail template) — one per significant component

**If domain is simple** → create a single file:
- `.md` (Domain README template)

**Content generation rules:**
- Key Files: verify each path exists before including
- Core Types: extract actual type definitions from code (code blocks)
- Flow: trace the actual happy path through code and render as ASCII
- Invariants: derive from code patterns, tests, and comments (state affirmatively)
- Configuration: extract from actual config files/structs

### Step 7 — Generate contract specs

For each identified boundary between layers/modules:
- One contract file per boundary
- Include actual interface definitions from code
- Document initialization (how things are wired at startup)
- Derive "Breaking Change Checklist" from observed coupling

### Step 8 — Generate ADR template and initial ADRs

Create `decisions/_template.md` from `assets/adr-template.md`.

Generate ADRs for architectural decisions that are:
- Non-obvious from the code alone
- Constraints that future developers/agents must respect
- Technology choices with rejected alternatives

Common candidates:
- Module structure choice (monorepo vs multi-repo, single module vs workspace)
- Database/storage choice
- Key framework or library selection
- Build system or deployment architecture

### Step 9 — Generate INDEX.md

Create the navigation file with:
1. **Task → Spec table**: map common development tasks to spec files
2. **Dependency graph**: ASCII diagram of layer relationships
3. **Directory listing**: all spec files organized by section

### Step 10 — Generate WORKFLOW.md

Use the template from `assets/workflow-template.md` as the base. Customize:
- Section 6 "Workflow for Typical Tasks" — add project-specific task workflows
- Examples throughout should reference this project's actual domains and components

### Step 11 — Update AGENTS.md (if exists)

If the project has an `AGENTS.md` or equivalent agent instructions file, add a pointer:

```markdown
## Specifications

Detailed system specs live in `specs/`. Before making structural changes, read the relevant spec:

- Start with `specs/INDEX.md` to find the right document for your task.
- `specs/META.md` defines spec formats and update rules.
```

### Step 12 — Final validation

Run the validation checklist across all generated specs:

- [ ] Every spec file follows the correct template (all sections present, correct order)
- [ ] All cross-references resolve to existing files
- [ ] All "Key Files" paths point to actual files in the repo
- [ ] Invariants are stated affirmatively
- [ ] INDEX.md lists every spec file
- [ ] META.md "File Organization" matches actual directory structure
- [ ] No project-internal jargon used without definition
- [ ] ASCII diagrams render correctly in monospace

Present a summary to the user:
```
SPEC INIT COMPLETE
═══════════════════════════════════
Generated:
  META.md, WORKFLOW.md, INDEX.md
  Architecture specs: N
  Domain specs: N (M READMEs + K detail files)
  Contract specs: N
  ADRs: N + template

Total files: N
```

---

## Quality Guidelines

- **Accuracy over completeness**: it's better to generate fewer specs with correct content than many specs with guesses. If unsure about behavior, mark with `` and note it in the summary.
- **Derive from code, don't invent**: every claim in a spec must be traceable to actual code. Read the source before writing about it.
- **Respect domain boundaries**: one source file may participate in multiple domains. Assign it to the domain where its primary responsibility lies.
- **Start lean**: generate only specs for areas with clear, documentable behavior. Thin areas can be added later via `vibespec-create`.
- **Ask when unsure**: if the codebase has ambiguous boundaries or unclear patterns, ask the user rather than guessing.

## Source & license

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

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

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-v0lka-skills-vibespec-init
- Seller: https://agentstack.voostack.com/s/v0lka
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.