Is it compatible with other agent tools?

Yes, it is designed to work seamlessly with tasks like task-prd-creator and general AI dev loops by providing a shared, durable context via the .agents/ folder.

What files does this skill create?

It creates three core artifacts in a .agents/ directory: spec.md (requirements), todo.md (step-by-step plan with verification), and decisions.md (trade-offs and logic).

When should I use the Spec-First skill?

Use it for any non-trivial task, such as building new features, implementing logic across multiple files, or any project where requirements are complex enough to need clear documentation.

How does this improve AI code quality?

By separating planning from execution, it prevents the AI from 'hallucinating' architecture and ensures every code change is verified against acceptance criteria before moving forward.

Does this work for quick bug fixes?

No, it is designed to be skipped for single-file changes under 50 lines, typo fixes, or simple configuration tweaks where a full spec process would be inefficient.

Spec-First Development Workflow

Name: Spec-First Development Workflow
Author: shipshitdev

byshipshitdev

•

Productivity & Workflow

Enforces a rigorous specification-driven development cycle to prevent architectural drift and errors in AI-assisted coding.

Spec-First is a structured workflow for LLM-assisted coding that mandates a documentation-first approach before any code is written. By requiring the creation of specification, task, and decision artifacts (spec.md, todo.md, and decisions.md), it forces explicit trade-off analysis and clear requirement definition. This skill is essential for building non-trivial features or multi-file systems where 'looks right' failures are common, ensuring that the AI agent follows a verifiable roadmap rather than improvising complex logic.

Key Features

0110 GitHub stars

02Six-stage structured workflow: Frame, Spec, Todo, Execute, Verify, and Decide

03Automated creation of .agents/ folder for durable project artifacts

04Explicit trade-off analysis during the 'Stage A - Framing' decision loop

05Enforcement of verification commands for every task in the generated TODO list

06Adversarial review mode to pressure-test implementations against requirements

Use Cases

01Refactoring complex legacy logic where requirements are implicit or unclear

02Building new features requiring changes across three or more files

03Architecting new systems that require documented trade-offs and Architecture Decision Records (ADRs)

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add shipshitdev/library spec-first

For use in Claude.ai and ChatGPT

Download Skill