What files does this skill generate?

It generates three specific documents in the .agents/ directory: a spec.md for requirements, a todo.md with verification steps, and a decisions.md for tracking architecture tradeoffs.

When should I use the Spec-First skill?

Use it for any non-trivial task, such as building new features, implementing complex logic, or changes involving three or more files where requirements are not yet frozen.

How does this prevent AI 'over-confidence' issues?

The workflow includes an 'Adversarial Mode' where the model acts as a hostile reviewer to find correctness bugs and proposes tests that would fail if the implementation were wrong.

Does this work for simple bug fixes or typos?

No, it is recommended to skip this workflow for single-file changes under 50 lines, simple configuration tweaks, or minor typo fixes where a full spec would be overkill.

Spec-First Development

Name: Spec-First Development
Author: shipshitdev

byshipshitdev

•

Productivity & Workflow

Enforces a structured spec-to-verification workflow to ensure technical rigor and prevent failures in non-trivial AI coding tasks.

Spec-First Development provides a disciplined framework for LLM-assisted coding, replacing haphazard prompting with a rigorous engineering loop. By mandating the creation of specification, task, and decision artifacts before code is generated, it ensures that technical tradeoffs are evaluated upfront and that every implementation step is backed by a verification command. This skill is essential for complex feature development where maintaining architectural integrity and avoiding 'looks right' failures are critical for long-term project health.

Key Features

0110 GitHub stars

02Six-stage workflow covering problem framing, spec freezing, and adversarial verification.

03Automated creation of SPEC, TODO, and DECISION artifacts in a dedicated .agents folder.

04Strategic architectural guidance focusing on small modules, minimal coupling, and strong test boundaries.

05Enforced verification loop requiring successful command output after every implementation step.

06Context-aware planning that keeps AI focus on specific interfaces rather than bloated file contexts.

Use Cases

01Architecting new features or projects requiring multi-file changes and complex logic.

02Refactoring legacy code where explicit trade-off documentation and edge-case handling are required.

03Providing high-speed 'junior engineer' style assistance with senior-level architectural oversight.

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