What is speclet-spec?

The Speclet Spec skill automates the transition from conceptual drafts to structured, executable technical specifications. By converting markdown drafts into a standardized `spec.json` format, it enables developers to generate trackable stories, define numbered functional requirements, and establish verifiable acceptance criteria, ensuring a clear and manageable roadmap for software implementation.

When should I use speclet-spec?

speclet-spec is useful in the following scenarios: • Feature Planning: Automatically transform a rough `.speclet/draft.md` into a comprehensive `spec.json` with a clear feature summary and defined non-goals. • Task Decomposition: Break down complex software requirements into atomic, right-sized stories that are small enough to be implemented and verified independently. • Requirement Traceability: Generate numbered functional requirements (FR-1, FR-2, etc.) to ensure every project goal is mapped to specific implementation tasks. • Rapid Prototyping & Hotfixes: Use the 'Spec-Lite' mode to quickly document and track small fixes or minor enhancements that require a 15-60 minute turnaround. • Workflow Standardization: Enforce consistent project structures and dependency-first story ordering (e.g., migrations before UI) across development teams.

name	speclet-spec
description	Convert a draft document into an executable spec.json with trackable stories
license	MIT
compatibility	opencode
workflow	speclet
phase	planning

Speclet Spec Skill

Convert a draft document into an executable spec.json.

What I Do

Convert .speclet/draft.md into .speclet/spec.json
Create atomic stories with verifiable acceptance criteria
Number functional requirements (FR-1, FR-2, etc.)
Set up passes: true/false tracking for each story

When to Use Me

Use this after creating a draft with speclet-draft skill, or for quick fixes:

Convert draft to executable spec
Create spec-lite for quick fixes (Tier 2)

Your Task

Convert .speclet/draft.md into .speclet/spec.json.

Step 1: Read the Draft

Read .speclet/draft.md and extract:

Feature name and summary
Non-goals
Proposed stories
Files to modify

Step 2: Create spec.json

Generate .speclet/spec.json:

{
  "feature": "[Feature Name]",
  "branch": "feature/branch-name",
  "date": "YYYY-MM-DD",
  "summary": "[1-2 sentences of the goal]",
  "nonGoals": [
    "[What this feature will NOT do]"
  ],
  "functionalRequirements": [
    "FR-1: The system must [specific requirement]",
    "FR-2: When user does X, the system must [response]"
  ],
  "stories": [
    {
      "id": "STORY-1",
      "title": "[Short title - 2-3 words]",
      "description": "[2-3 sentences max]",
      "files": ["path/to/file.ts"],
      "acceptanceCriteria": [
        "[Specific verifiable criterion]",
        "Build/typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Critical Rules

Story Sizing

If you cannot describe the change in 2-3 sentences, it's too big. Split it.

✅ Right-sized:

Add a database column and migration
Add a UI component to an existing page
Update a server action with new logic

❌ Too big (split these):

"Build the entire dashboard"
"Add authentication"

Story Order: Dependencies First

Schema/database changes (migrations)
Server actions / backend logic
UI components that use the backend
Dashboard/summary views

Acceptance Criteria: Must Be Verifiable

✅ Good:

"Add status column with default 'pending'"
"Filter dropdown has options: All, Active, Completed"

❌ Bad:

"Works correctly"
"Good UX"

Always include:

Build/typecheck passes (every story)
Verify in browser (UI stories)

Spec-Lite (Tier 2)

For quick fixes (15-60 min), create .speclet/spec-lite.json:

{
  "feature": "[Title]",
  "branch": "fix/branch-name",
  "date": "YYYY-MM-DD",
  "problem": "[1-2 sentences]",
  "solution": "[Description]",
  "files": ["path/file.ts"],
  "acceptanceCriteria": ["Build passes", "[Criterion]"],
  "passes": false,
  "notes": ""
}

Global Rules

Always Show Recommendation + Reason

When asking questions with options, ALWAYS:

Mark the recommended option with ⭐
Add **Reason for recommendation:** explaining why

Example format:

1. [Question]?
   A. Option A
   B. Option B ⭐ Recommended — [brief reason]
   C. Option C

   **Reason for recommendation:** [Detailed explanation of why B is best]

Output

Full spec: .speclet/spec.json
Quick fix: .speclet/spec-lite.json

When complete:

"Spec saved. Ready to implement? Use the speclet-loop skill."

speclet-spec

When & Why to Use This Skill

Use Cases