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](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 a new or substantially updated spec, declare Target Platforms in

Goal before prototype work or planning. List only in-scope user platforms; use Not applicable for non-UI work.

• Treat the platform declaration as the source of truth for UI prototype scope.

If it is missing or unresolved and could change the interaction, validation, or readiness decision, add a blocking open question instead of guessing.

• 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 feature specs for local style. In the default mode, check

features//spec.md; in OpenSpec mode, check active changes under openspec/changes//spec.md.

1. Read related issues, prototypes, screenshots, code, tests, contracts, and

prior decisions.

1. Identify affected users, current behavior, desired outcome, constraints,

dependencies, evidence, and existing mechanisms that may already fit.

1. Identify ambiguous domain terms and clarify only the ones that can change

scope, rules, acceptance, validation, or readiness.

1. For cross-boundary work, identify only the unresolved contract questions that

can change readiness or acceptance.

1. 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

• Keep the repository root as the working directory. Artifact mode changes the

output path, not the current working directory.

• Resolve the initial artifact root in this order: explicit user direction,

mode declared in root instructions, root openspec/config.yaml, both openspec/changes/ and openspec/specs/, then the default Vibe mode. A lone openspec/ directory is not sufficient.

• In the default mode, use features/<feature-slug>/spec.md.
• In OpenSpec mode, use openspec/changes/<change>/spec.md.
• The selected spec parent is the current change directory.
• 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.
• Reuse an existing active change only after confirming its identity. If a

same-name change is archived or ambiguous, ask before writing.

• If the target file exists, update it only when the user explicitly requests

that file; otherwise ask before writing.

• Use the same Vibe template and validator in both modes. OpenSpec mode changes

only the artifact path.

4. Draft The Spec

Read [references/spec-template.md](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.
• For UI work, name in-scope user platforms such as Desktop Web, iOS,

Android, or WeChat Mini Program; do not substitute an implementation framework for a user platform.

• 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 path/to/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.

1. 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