Spec

Spec System

Every project's design lives in .spec/. Single source of truth for what you're building, why, and how. Read specs before writing code. Update specs when decisions change.

Agent quick start

1. Pick layer — global/root work → strategy.md; one named feature → feature.md + .spec/features/<name>/.
2. Pick route — explicit /spec <arg> → Routing § $ARGUMENTS; no arg → Routing § Route by task type.
3. Finish — bump updated: on every edited spec; run scripts/validate.sh (from your project root).

Why Specs Exist

• Persistent memory — decisions survive across sessions
• Separation of concerns — product thinking stays separate from implementation thinking
• Progressive disclosure — load only what you need, when you need it
• Shared language — consistent vocabulary between product and tech

The Two-Layer Model

Specs come in two layers. Use the right one for the job — mixing them is the most common mistake.

.spec/
│
│  ─── ROOT LAYER (high-level, persistent) ──────────────
│
├── product.md                # mini PRD — story, requirements, principles
├── tech.md                   # architecture summary — stack, principles, basic implementation
├── design.md                 # cross-cutting product/UX design language
├── plan.md                   # implementation roadmap
├── lessons.md                # accumulated mistakes, read at session start
├── product-{topic}.md        # cross-cutting product branch (design system, conventions)
├── tech-{topic}.md           # cross-cutting tech branch (infrastructure, observability)
│
│  ─── FEATURE LAYER (detailed, branch-scoped) ──────────────
│
├── features/<name>/
│   ├── product.md            # what this feature does (requirements)
│   ├── tech.md               # how this feature is built (architecture)
│   ├── design.md             # optional, feature UX / interaction detail
│   ├── plan.md               # optional, feature-scoped roadmap (`<name>/n` units)
│   └── research.md           # optional, discovery artifacts
│
└── archive/<name>/           # transient post-wrapup safety net (deleted before merge)

Root layer rules:

• product.md is the mini PRD: story, target user, requirements, design principles, non-goals.
• tech.md is the architecture summary: design philosophy, stack, file layout, state contracts, basic implementation, build sequence, risks.
• design.md is the cross-cutting design language: UX principles, interaction conventions, interface tone, and reusable design patterns. It may bridge product and implementation vocabulary when that helps design stay actionable.
• plan.md sequences the work at the root layer: feature map, Feature Sequence with binary whole-feature gates, current focus. Current-only — no long-horizon backlog. Unit-level detail (<name>/n) lives in features/<name>/plan.md. See reference/plan.md.
• Branch docs (product-{topic}.md, tech-{topic}.md) cover cross-cutting concerns only — things that span every feature. Design system. Infrastructure. Naming conventions. If the topic is really about one feature, it belongs in the feature layer.

Feature layer rules:

• One directory per feature in .spec/features/<name>/. Always contains product.md and tech.md. Recommended: plan.md with stable unit IDs (<name>/n). Optionally design.md, research.md. Every feature product.md includes a Scope table (Owns / Does not own). Each feature is a closed, deliverable, testable box; cross-feature order is a whole-feature gate in the root plan, never a unit-to-unit edge.
• Feature specs are branch-scoped: written during DESIGN, consumed during IMPL, merged into root layer during COMPOUND, archived as a transient safety net, then deleted before the branch merges (agent prompts after validation). CODE IS TRUTH; archive is never read for active work (see Wrapped-up features).
• Cross-cutting decisions from a feature get merged into root tech.md or relevant branch doc. Feature-specific detail does not promote — it is discarded with the deleted folder.

Strategy vs Feature — Which layer?

Rule of thumb: one buildable unit of work with a name → feature layer. Something that spans every feature → root branch doc (product-{topic}.md / tech-{topic}.md). If unsure, default to feature; extract to a branch doc when the same concern keeps recurring.

Feature authoring flow

Ladder: locate & name → interview WHAT → rigor gate → sketch HOW → plan units → skip check.

• product.md — requirements with SHALL/MUST + GWT scenarios; Scope table; no code.
• tech.md — paths, contracts, files traced from the repo; only filled sections.
• plan.md — stable unit IDs citing requirement IDs; verification evidence per unit.

Full steps, rigor gate, and skip conditions: feature.md.

Superpower tips

The spec skill is a format + constraints + validation layer. The actual authoring work at each step is best done by delegating to the right superpower with a spec constraint document injected. Suggest these to the user proactively — don't wait to be asked.

How to suggest: at the start of each step, tell the user which superpower fits and offer to delegate. Example:

"I can use superpowers:writing-plans for this step — it's purpose-built for decomposing requirements into implementable units. I'll inject the spec plan format as a constraint so the output is ready to commit. Want me to do that?"

If the user says no, proceed with the spec skill's own guidance in feature.md and strategy.md. Never require superpowers — they enhance, they don't gate.

Navigation Rules

1. Read entrypoints first. Branch docs and feature specs assume you have parent context.
2. Read lessons at session start. Past mistakes inform current decisions.
3. Never load all specs at once. Load only what's relevant.
4. Follow the links. Entrypoints link to features and branches. Trust the graph.

Strict Rules

1. Read before write. Never edit a spec you haven't read in this session.
2. Root specs stay high-level. No feature-level detail in root product.md or tech.md — use features/<name>/. (Canonical statement; do not duplicate elsewhere.)
3. One concern per doc. Product specs contain zero code. Tech specs contain zero UX opinions. Design-system docs may cross the line — they're the only exception.
4. Bump updated:. Change the updated: date every time you edit a spec.
5. Keep cross-references alive. Link parent ↔ child both ways. List children in entrypoint frontmatter.
6. Validate after changes. Run scripts/validate.sh from your project root.
7. Feature specs are branch-scoped. Don't write them as if they're permanent. Cross-cutting decisions merge to root; the feature folder is archived transiently then deleted before the branch merges (see below). No backlog in any spec — work-ready items only; long-term ideas live in an external tracker.

Wrapped-up features

When a feature arc completes (COMPOUND / wrap-up), follow this sequence:

1. Promote — merge cross-cutting blocks from features/<name>/tech.md (and product/design when relevant) into root .spec/{product,tech,design,plan}.md. Use <!-- merge --> markers or hand-merge; see reference/tech.md.
2. Record — append a tagged lesson to .spec/lessons.md when a durable rule surfaced (via vibe compound).
3. Update root plan — set the feature to DONE in the .spec/plan.md Feature Sequence and cleanse delivered detail to a one-line note. Link the live surface (skill path, root doc section, test suite) — not the removed feature folder.
4. Archive transiently — mv features/<name>/ archive/<name>/ as a safety net (e.g. CI fails right after wrapup). Archive is never read for active work — CODE IS TRUTH.
5. Prompt to delete — after validation passes, prompt the user to delete archive/<name>/. The folder should be gone before the branch merges; keeping it is the justified exception, not the default.

Why delete and not hoard: the repo holds value-prop + architecture + current plan only. Decision archaeology that has standalone value can be kept in archive deliberately; otherwise delete — live artifacts (skill bundle, root specs, tests) are the truth.

This repo: spec-framework was deleted, not archived — truth lives in this skill bundle, root .spec/ entrypoints, and spec/tests/run.sh.

Agent rules after wrap-up:

• Route to root plan.md Feature Sequence + live implementation paths — never restore features/<name>/ because validation failed on a wrapped-up feature.
• Do not load archive/<name>/ by default; it is cold, transient storage when it exists.
• Full lifecycle steps: feature.md § Lifecycle and § Archive and delete.

Roles

Four subagents live under agents/ with their own SKILL.md. Invoke via /spec <role> or by phase-routing below. Each names an executor and the constraint document to inject — the subagent is thin wiring between spec constraints and the appropriate superpowers executor.

Two steps delegate inline, with no subagent file: plan-unit writing routes to superpowers:writing-plans with reference/plan.md + stable-ID rules, and /spec audit runs scripts/validate.sh directly.

Promote-first rule: at each step, offer the executor before running anything. Example: "I can use superpowers:writing-plans here — want me to?" If declined or unavailable, self-execute using the constraint document as guidance. Never silently skip the offer; never block on the answer.

Routing

$ARGUMENTS:

Route by task type:

Design.md Compatibility

For visual identity or UI design systems, prefer the public DESIGN.md format: YAML frontmatter for machine-readable tokens plus markdown prose for human rationale. Use it inside .spec/design.md or .spec/features/<name>/design.md; do not move design docs out of .spec/.

Useful token groups:

• colors
• typography
• rounded
• spacing
• components

Recommended section order for visual design docs:

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

For non-visual workflow design, the same file may omit tokens and use prose-only sections such as interaction conventions, information hierarchy, and agent tone.

Current Project State

!bash .agents/skills/spec/scripts/list-specs.sh

Config

The skill reads .spec/.config.yaml at session start on any /spec invocation. Absent file or missing keys fall back to documented defaults without error.

Output density is not a config key. It follows the vibe flow's single style note — concise, no filler; security and irreversible-action warnings stay in full prose (see the flow's SKILL.md § Style). Standalone, the spec skill writes to that same style. There are no per-phase output levels to configure.

Config read MUST happen before any offer or execution so suggest-superpowers suppression takes effect from the first step. See setup interview below for how the file is written.

Setup, Templates, Validation

Setup

When the user runs /spec setup:

1. Check for .spec/.config.yaml:

   • If present: show current settings; ask "Which setting would you like to update?" → update only the named setting; re-confirm; write; done.
   • If absent: run the full interview below.

2. Interview (3 questions — conversational, not a form):

   Q1 — Workflow orchestration: "Are you driving spec work through the vibe flow — the single vibe skill via /flow — or running /spec commands directly? Under the flow, phase routing and output density are handled by the flow cursor and its style note." → Answer: yes (flow) | no (manual)

   Q2 — Available superpowers: "Which AI skills/superpowers are available? all, none, or custom (I'll list each)." → Answer: all | none | {per-superpower booleans}

   Q3 — Proactive suggestions: "Should I suggest superpowers at each authoring step, or stay quiet and self-execute? Default: yes." → Answer: yes | no

3. Show summary and ask for confirmation before writing anything.

4. On confirm: write .spec/.config.yaml; then run setup.sh to create entrypoint templates. Report what was created.

5. After setup: surface next steps — /spec strategy or /spec feature <name>.

Invariants: .spec/.config.yaml MUST be written even when user accepts all defaults. setup.sh MUST NOT be called until the user confirms the summary.

Templates

Paths are under reference/templates/ (copy into your project's .spec/).

Branch docs (product-{topic}.md, tech-{topic}.md, plan-{topic}.md): use the dedicated templates below. Set type: product-topic / tech-topic / plan-topic and parent/scope/covers per reference/product.md and reference/tech.md.

Detailed writing guides

• Product: reference/product.md — root vs feature, cross-cutting branches
• Tech: reference/tech.md — root vs feature, merge markers, cross-cutting branches
• Design: reference/design.md — root vs feature, tokens + prose
• Plans: reference/plan.md

Validation

scripts/validate.sh (run from your project root) — checks frontmatter, naming, internal links, orphaned children, and feature-folder consistency under .spec/.