skills.rest
saffron-health
saffron-healthOFFICIAL
Explore all skills by this author →
WebsiteGitHub

generate-spec-v2

Generates phased implementation specs with Mermaid flows, call-stack diffs, and code previews.

883|68|Updated Mar 2, 2026
Search Tags:#Mermaid#Planning#REFACTOR#code diff#implementation spec#End-to-end testing#phased commits
One-click install
npx skills add https://github.com/saffron-health/libretto --skill generate-spec-v2
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: generate-spec-v2
Source: https://github.com/saffron-health/libretto/tree/main/.agents/skills/generate-spec-v2
Command: npx skills add https://github.com/saffron-health/libretto --skill generate-spec-v2

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Planning a significant feature, fix, or refactor often produces vague plans that force engineers to redo research during implementation. This Skill produces a grounded, commit-sized implementation spec in the specs/ directory that an engineer can follow without repeating the investigation.

Core Features & Use Cases

  • Research-grounded planning: Traces entry points, key types, callers, and tests in the current codebase before writing the plan.
  • Structured spec format: Produces Mermaid system-flow diagrams, goals and non-goals, per-phase important types, call-stack diffs, and code diff previews.
  • Commit-sized phases with checks: Breaks work into phases that each fit one commit, include four or five checklist steps, and use package-level end-to-end tests or uncommitted smoke checks.
  • Use Case: Ask the agent to plan a refactor of an API validation layer, and receive a specs/ file with phased diffs, exact file and symbol names, and the commands that prove each phase works.

Quick Start

Use the generate-spec-v2 skill to plan this feature as a phased implementation spec in the specs directory.

Frequently Asked Questions about generate-spec-v2

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

FAQPage Schema
How do I write an implementation spec for a new feature?▼

Describe the feature, fix, or refactor and ask for a phased implementation spec. The skill researches the codebase, then writes a specs/ file with Mermaid flow diagrams, goals, per-phase types, call-stack diffs, code diff previews, and verification steps.

What should a phased implementation plan include?▼

Each phase should fit one commit, leave the repository working, and include important types, a call-stack diff, a short code diff preview, and four or five checklist steps. Phases end with a command or smoke check that proves the phase works.

Does the spec include tests, and what kind?▼

Specs commit only package-level end-to-end tests that act through public APIs or a live UI, using Vitest fixtures for setup. Before a feature is end-to-end testable, phases use manual smoke checks that are not committed.

When should I not use a full implementation spec?▼

Skip the spec for small, self-explanatory changes that do not need phasing or upfront research. The skill targets significant features, fixes, or refactors where planning, scoping, and phased commits add value.

Can the spec use mocks or unit tests for verification?▼

No. The spec explicitly avoids mocks such as vi.fn or vi.mock and does not plan internal unit tests. Verification relies on package-level end-to-end tests through public APIs or live UI driven by Playwright.

Related Skills

Explore More Software Engineering Skills→
kileroppokileroppo

zoom-out

Map relevant modules and their callers using domain glossary vocabulary.

Community
Basic
ryan-mahoneyryan-mahoney

specops-run-spec

Execute SpecOps implementation specs via sequential subagents with conventional commits.

Community
Advanced
alvarovillalbaaalvarovillalbaa

review

Review plans and code diffs to produce ordered, actionable findings.

Community
Advanced
kennyth01kennyth01
1

Jira Ticket Estimator

Estimate Jira ticket development time across manual and AI-assisted workflows.

Community
Intermediate