Vibe Plan

Create an implementation and validation plan that turns a ready spec into a reviewable development path. The plan should explain how the change will be made and how correctness will be proven before coding begins.

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.

• Treat the feature spec and spec review as the source of product truth.
• Plan implementation and validation together; do not bolt tests on afterward.
• For each acceptance or material risk, choose the lowest effective test layer;

do not use a repository-wide coverage percentage as a substitute for a plan.

• Treat spec Goal Target Platforms as the sole UI platform scope. Read the

coverage reference only when it is needed for UI scope, thresholds, or an automation gap; do not repeat its platform rules in the plan.

• Plan by vertical slices when the change has multiple steps. Avoid defaulting

to horizontal phases such as schema, API, UI, tests.

• Prefer the repository's existing architecture, conventions, and test tools.
• Keep the plan concrete enough for another engineer or agent to execute.
• Name the implementation SSOT, reused mechanism, and ownership boundary.
• Include docstrings, API docs, README usage, examples, or generated docs when

changed contracts can make them stale.

• For user-facing API errors, name the local i18n/copy owner and plan evidence

that status and fallback states never expose raw server error text or codes.

• Production code fallback or reflection-style access is discouraged by

default. If proposed, mark Human Review: Yes (HITL) unless a spec already approves its boundary, SSOT, validation evidence, and removal condition.

• Use design-quality checks only when they explain real implementation risk.
• Mark whether each slice needs human review when that affects execution.
• Include a Progress section only when the plan is also tracking active

execution across multiple slices, turns, agents, or reviews.

• Put Open Questions after Summary and before Implementation Approach so

unresolved decisions are visible before the plan describes how to build.

• Mark a question as blocking when the answer can change architecture, files,

APIs, data, permissions, pricing/entitlement, privacy, security, validation, rollout, or whether implementation should start.

• Use Assumptions only for facts that are safe to proceed with. If an

assumption can invalidate acceptance, correctness, public/private access, privacy, security, entitlement, data limits, or test evidence, move it to Open Questions and mark it blocking unless the spec or review explicitly resolves it.

• Do not rewrite the spec, implement code, or claim validation that has not run.
• Use TBD only when a missing fact does not block useful planning.

Workflow

1. Load Inputs

Before planning:

1. Read applicable AGENTS.md, CLAUDE.md, or repo instructions.
2. Read the target spec completely.
3. Read the latest spec review when available.
4. Inspect relevant code, tests, configs, APIs, schemas, and existing patterns.
5. Identify whether the spec is Ready For Development, conditionally ready,

or still blocked.

Do not produce a confident implementation plan from a blocked spec. Instead, name the blocker and the minimum information needed to continue.

If the spec review is conditional, keep the plan Draft or Blocked until the condition is resolved. Put each condition in Open Questions and mark it blocking when it can change whether the plan should be implemented.

2. Define The Implementation Approach

Plan:

• Target behavior and non-goals inherited from the spec.
• Affected files, modules, services, routes, schemas, tests, docs, or config.
• Key decisions and rejected alternatives, especially when reusing existing

contracts instead of adding new surfaces.

• Docstrings, API docs, README usage, examples, or generated docs that must

change when behavior, parameters, return values, errors, or side effects change.

• Proposed change sequence.
• Data, API, migration, security, privacy, and compatibility concerns.
• Alternatives considered when multiple approaches are plausible.
• Rollback or recovery notes when the change has release or data risk.

Keep the plan implementation-focused. Do not restate the entire spec.

Run a concise architecture fit check:

• Does the plan preserve clear module boundaries and local ownership?
• Does the plan name the implementation SSOT and reuse existing mechanisms when

they fit?

• Is any new interface or boundary responsible for simplifying the caller, not

just forwarding work?

• Are tests aimed at public behavior instead of private implementation details?
• Will the next agent or engineer know where to look from names, boundaries, and

tests?

• Is a small prerequisite refactor needed to reduce slice risk?
• Does a long-lived architecture decision need a separate document outside the spec?
• Do the design-quality checks reveal real risk: 改动扩散, 规则重复,

理解成本, 边界不清, 空壳接口, or 绕路补丁?

3. Slice The Work

Create vertical slices for substantial changes. Each slice should state:

• Outcome: the user-visible or workflow-observable behavior it delivers.
• Touches: the minimal code, data, UI, docs, config, or generated outputs.
• Validation: the test, command, evidence, screenshot, or manual check that

proves the slice.

• Dependencies: prior slices or external decisions.
• Human Review: No (agent-only) when the agent can proceed alone, or

Yes (HITL) when human review changes the result.

• Recovery: how to roll back, shrink, or defer the slice if it fails.

Prefer slices that close a thin end-to-end path over slices grouped by layer.

4. Plan TDD And Validation Before Development

For each meaningful acceptance criterion or risk, define how it will be proven:

• Unit, integration, end-to-end, snapshot, accessibility, localization, or

manual checks as appropriate.

• Existing tests to run.
• New tests or test fixtures to add.
• Docstring, API docs, README, example, or generated-doc review when public or

reusable contracts change.

• Slices that should use TDD: one public behavior, red first, green with the

smallest implementation, then refactor.

• Coverage expectations when coverage tooling exists.
• A Coverage Plan: layer, target coverage, platform/device scope, evidence,

and any automation gap for each meaningful acceptance or risk. Use [references/coverage-plan.md](references/coverage-plan.md) for compact defaults when the repository has no policy.

• Required evidence paths, screenshots, logs, CI runs, or manual notes.
• What can remain unverified and why.

When a required path lacks automation, plan the smallest enabling slice (such as a fixture, mock, stable locator, launch path, or test runner) before using a manual exception. In a plan-only or read-only task, record that slice and the blocking condition; do not invent a command or treat ordinary UI work as a manual pass. Reserve manual exceptions for real hardware, external systems, or non-simulatable behavior.

5. Produce The Plan Artifact

Use [references/plan-template.md](references/plan-template.md) as the required structure for new plan artifacts unless the user explicitly asks for another format. Repository-local docs and plans can add context, but should not replace the Vibe plan information model.

Default path:

features/{feature-slug}/plan.md

If the repository already keeps implementation plans elsewhere, use that path convention and link the spec. In OpenSpec mode, use the user-specified change/path or the source spec directory as the current change directory. If neither identifies it, ask before writing. Save plan.md there; if it exists, update it only when explicitly requested. Preserve the Vibe plan sections in every location.

6. Validate The Plan

If you save a plan artifact, run:

python3 skills/vibe-plan/scripts/validate_dev_plan.py path/to/plan.md

Fix structural errors before finishing. Review warnings and either resolve them or explain why they remain.

Output

When editing files, report:

• Plan path.
• Source spec and spec review status.
• Implementation approach summary.
• Validation plan summary.
• Blockers, assumptions, and residual risks.
• Validation result.

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

Skill Signature

Always end the final response with:

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