spec-plan

Convert ambiguous software requests into BDD-style implementation specifications.

3|Updated Apr 14, 2026
One-click install
npx skills add https://github.com/H2Sxxa/spec-coding-skills --skill spec-plan-h2sxxa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-plan
Source: https://github.com/H2Sxxa/spec-coding-skills/tree/main/skills/spec-plan
Command: npx skills add https://github.com/H2Sxxa/spec-coding-skills --skill spec-plan-h2sxxa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Many software requests are ambiguous or incomplete, which leads to implementation rework, failing checks, and unclear acceptance criteria. This Skill makes "done" explicit by converting fuzzy requirements into concrete, observable, and testable specifications so implementation can proceed with minimal guesswork.

Core Features & Use Cases

  • BDD-style Acceptance Criteria: Translate goals into observable behavior and optional Gherkin scenarios for validation.
  • Context-aware Planning: Retrieve repository preferences and prior decisions from SPEC.md and spec-index to avoid repeating mistakes.
  • Validation & Guardrails: Identify edge cases, setup prerequisites, execution guardrails, and run a self-check before handoff or persistence.
  • Persisted and Conversation Modes: Produce lightweight conversation plans for small tasks or structured persisted specs for multi-turn, risky, or review-heavy work.

Quick Start

Turn this feature idea into a persisted spec with clear scope, acceptance criteria, edge cases, and an ordered execution plan.

Frequently Asked Questions about spec-plan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn fuzzy software requests into testable specs?

To turn fuzzy requests into testable specs, convert ambiguous software goals into concrete BDD-style implementation specifications with observable acceptance criteria, edge cases, and execution plans. This minimizes implementation guesswork by making 'done' explicit.

How do I write BDD acceptance criteria for ambiguous requirements?

Writing BDD acceptance criteria for ambiguous requirements involves translating goals into observable behaviors and optional Gherkin scenarios for validation. This process identifies edge cases, setup prerequisites, and execution guardrails to ensure clear scope.

What is the best way to plan software features before coding?

The best way to plan features before coding is context-aware planning that retrieves repository preferences and prior decisions from SPEC.md and spec-index. This prevents repeating past mistakes and produces an ordered execution plan with a self-check.

Can I use conversation mode for small task specs instead of persisted specs?

Yes, you can use lightweight conversation mode for small tasks instead of structured persisted specs. Persisted specs are reserved for multi-turn, risky, or review-heavy work requiring clear scope and validation steps.

Does planning with BDD specs require a SPEC.md file in the repository?

Context-aware planning consults SPEC.md and spec-index if they exist in the repository to retrieve prior decisions and preferences. If absent, the Skill still generates BDD-style specifications, edge cases, and execution plans from the fuzzy request.

Why does implementation rework happen with unclear acceptance criteria?

Implementation rework happens with unclear acceptance criteria because ambiguous software requests lead to guesswork and failing checks. Converting fuzzy requirements into concrete, observable specifications with validation steps prevents this rework.