vibe-spec

Vibe Spec

Create a compact, reviewable feature spec that gives people and agents one source of truth for why a change exists, what result it should produce, what rules constrain it, and how completion will be proven.

Rules

• Write artifact prose in the user's language; keep labels, paths, commands, code, IDs, status values, and quotes unchanged.
• Keep required template headings, field labels, tables, and status values exactly as shown for validator compatibility; localize placeholder prose and all human-readable explanatory content to the user's language or the source artifact's primary language.
• Deliver a usable draft instead of only suggesting what the user should write.
• Keep the workflow outcome-first: clarify only what changes scope, rules, acceptance, validation, or readiness.
• Follow AGENTS.md, CLAUDE.md, repository docs, and existing specs for product and technical context.
• Use references/spec-template.md as the required structure for new specs unless the user explicitly asks for another format.
• Preserve the Vibe template's metadata labels, section order, and table shapes.
• For Vibe specs, do not leave {...} placeholders in delivered specs. Use prose, framework-native route notation, or :id style route parameters.
• Keep specs short. Do not add sections or prose merely to make the document look complete.
• Maintain one source of truth. A fact, rule, state meaning, permission, constraint, or contract decision should be defined in exactly one place.
• When a design decision affects implementation risk, express the product or workflow truth in Rules and leave implementation-quality checks to vibe-plan, vibe-review, and vibe-commit.
• Separate known facts, assumptions, and unresolved questions.
• Never invent business rules, owners, dates, evidence, estimates, or dependencies.
• Use TBD for unknown scalar values. Put decision-blocking uncertainty in Open Questions.
• Write clarified context into the spec sections. Do not create a separate resolved-context artifact unless the user asks for one.
• Challenge vague terms such as "smart", "automatic", "sync", "real-time", "complete", or "usable" when they can change readiness or validation.
• Suggest a separate long-term architecture decision document only when a technical direction needs durable context, decision, consequences, and rejected alternatives outside the feature spec.
• When repo context supports a conservative V1 boundary, propose it as an explicit assumption instead of turning every unknown into a blocker.
• Keep the spec about problem, goal, rules, acceptance evidence, and open questions.
• Do not turn the spec into an implementation plan. Sequencing, file-level plans, rollout steps, and test execution belong in vibe-plan and vibe-test.
• Prefer existing endpoints, schemas, models, files, and workflows. Add new protocol surface only when the spec explains the gap.
• Capture domain-specific details only when they affect readiness, acceptance, privacy, compatibility, or feasibility. Put them in Rules as the single source of truth instead of scattering them across sections.
• For user-facing API errors, define the local localized copy rule in Rules: server status selects the client state; ordinary UI must not display raw server error body, codes, or exception strings.
• For production code fallback or reflection-style access, prefer explicit contracts. If it is still needed, capture the human-approved boundary in Rules or a blocking open question.
• For sync/import work, replace vague windows such as "recent" with explicit bounds or a blocking open question.
• If the user explicitly asks for a small direct skill edit, do not force a spec; state that the feature-spec step is being skipped.

Workflow

1. Decide Whether A Spec Is Needed

Create or update a feature spec for:

• A new user-facing or operational capability.
• A substantial iteration to existing behavior.
• A substantial change to a skill, workflow protocol, distribution path, or observability behavior.
• A bug fix that changes business rules, state, permissions, data, or cross-module behavior.
• Work requiring product, design, engineering, testing, operations, legal, or external coordination.

Do not force a spec for trivial copy, style, config, or narrow bug fixes when an existing issue already has enough context.

2. Discover And Clarify Context

Before drafting, form enough shared context to write a useful spec:

1. Read applicable AGENTS.md, CLAUDE.md, and repository documentation.
2. Inspect existing features/*/spec.md files for local style.
3. Read related issues, prototypes, screenshots, code, tests, contracts, and prior decisions.
4. Identify affected users, current behavior, desired outcome, constraints, dependencies, evidence, and existing mechanisms that may already fit.
5. Identify ambiguous domain terms and clarify only the ones that can change scope, rules, acceptance, validation, or readiness.
6. For cross-boundary work, identify only the unresolved contract questions that can change readiness or acceptance.
7. Note whether a durable technical decision may need a separate architecture decision note, but keep the feature spec as the source of product/workflow truth.

3. Choose The Target

• Default to features/feature-slug/spec.md.
• Use a short lowercase hyphenated slug that describes the capability, not an internal ticket number.
• Update an existing relevant spec instead of creating a duplicate.
• Preserve useful existing content and history when updating.
• Create parent directories only when writing the spec is part of the user's request.

4. Draft The Spec

Read references/spec-template.md before creating or substantially restructuring a Vibe spec.

Apply these rules:

• Set a new spec to Draft.
• Use the current ISO date for Last Updated.
• If producing a complete chat-only draft, still use the current ISO date when available; use placeholders only for examples, not deliverable specs.
• Keep required Vibe metadata as Field: Value lines, not tables.
• Replace every brace placeholder before validation.
• Express goals as user or business outcomes, not implementation tasks.
• Put goal, in-scope, and out-of-scope boundaries together in Goal.
• Define time windows, limits, and retry/repair boundaries when they affect acceptance or feasibility.
• Put all required behavior, constraints, permissions, state semantics, and contract decisions in Rules.
• Put Open Questions after Rules and before Acceptance so unresolved decisions are visible before completion criteria.
• Make Acceptance observable and include the evidence needed to prove each item. Reference rule IDs instead of restating rules.
• Mention implementation only when it is a real constraint or dependency.
• Mark whether each open question blocks development planning.
• Put clarified goals, terms, boundaries, current behavior, constraints, and validation consensus into Problem, Goal, Rules, Acceptance, or Open Questions; do not create a separate resolved-context section.
• Preserve an existing artifact's primary language unless the user asks to switch.

5. Handle Missing Information

Proceed with a draft when missing information does not prevent useful structure.

• Use TBD for missing scalar values.
• Use Open Questions for missing decisions.
• Label assumptions explicitly.
• Ask the user only when the missing answer changes the problem, repository, or intended output.
• Do not mark a spec Ready For Development while blocking questions remain.

6. Update Existing Specs Carefully

When updating a spec:

1. Re-read the current document and related implementation evidence.
2. Update Last Updated.
3. Reconcile Status, Rules, Acceptance, and Open Questions with current facts.
4. Do not rewrite settled content merely for style.
5. Do not claim progress or completion without evidence.

When updating any spec, remove or rewrite stale statements instead of leaving old decisions in multiple sections. If the same rule appears in more than one place, keep it in Rules and make other sections reference it.

7. Validate The Result

Run the Vibe validator for delivered specs:

python3 <skill-dir>/scripts/validate_spec.py features/feature-slug/spec.md

If the target repository has an additional local validator, run it after the Vibe validator and report both results. Local validators can add project checks, but they do not replace the Vibe spec structure.

When a test draft is intentionally saved outside the target repository, still validate it with this skill's Vibe validator. If the target repository has extra checks that require in-repo paths, state that those extra checks were not run.

Fix structural errors before finishing. Review warnings and either resolve them or explain why the draft intentionally retains them.

Then perform a semantic check:

• Problem, goal, rules, acceptance evidence, and open questions are present in the Vibe structure.
• Rules are the single source of truth and are not repeated in other sections.
• Existing mechanisms are reused when reasonable.
• New protocol surface is justified.
• Rules name the source of truth for decisions that would otherwise be repeated in multiple artifacts or implementation locations.
• Ambiguous terms that affect readiness are resolved or marked as blocking open questions.
• Any separate long-term architecture decision document recommendation is scoped to durable technical direction and does not replace the feature spec.
• Acceptance items are testable and include credible evidence.
• Another engineer can begin planning without reconstructing hidden context.

Output

When file creation or editing is requested:

1. Create or update the target spec.md.
2. Validate it with scripts/validate_spec.py; then run any applicable local validator as an additional check.
3. Report the path, status, unresolved blocking questions, validation result, and the recommended next workflow step such as vibe-review or vibe-plan.

When the user asks only for a draft in chat, return the complete spec in the same structure without writing files.

Skill Signature

Always end the final response with:

Vibe Skill Signature
Skill: vibe-spec
Status: Completed | Passed | Failed | Blocked | Partial
Next: concise next workflow step