SpecFirst

SpecFirst is a Go CLI for specification-driven workflows that focuses on prompt quality, clarity, and human judgment.

Why SpecFirst? Ambiguity is the enemy of automated coding. SpecFirst exists to bridge the gap between vague human intent and precise AI execution. It provides a structured, file-centric protocol for communicating with LLMs, ensuring that requirements are clear, context is substantial, and humans remain in control of the creative process.

What SpecFirst Is

• Protocol-Driven: Workflows are defined in protocol.yaml files, making them versionable and reproducible.
• Staged Execution: Complex tasks are broken down into logical stages (e.g., Scope -> Spec -> Implementation -> Review).
• Template-Based: Prompts are rendered from declarative Markdown templates, ensuring consistency.
• Artifact-Centric: Every stage produces tangible artifacts (files) that serve as the input for the next stage.
• Human-in-the-Loop: Designed to augment human reasoning, not replace it. You review and approve artifacts at each step.

What SpecFirst Is Not

• Not an Agent: It does not execute code, run terminals, or make decisions for you. It prepares the context for you (or an agent) to act.
• Not a Sandbox: It runs in your shell. It does not provide an isolated execution environment.
• Not a Test Framework: While it can help write tests, it replaces neither unit tests nor integration tests.
• Not Magic: It requires you to articulate your intent clearly in the templates and inputs.

Quick Start

Get up and running with a single copy/paste flow:

# 1. Install & Initialize
specfirst init

# 2. Run the "requirements" example
# Generates a prompt, pipes it to your clipboard (macos pbcopy)
specfirst requirements | pbcopy

# 3. Paste into your LLM to get requirements.md content
# ... (User Action: Paste result into requirements.md) ...

# 4. Complete the stage
specfirst complete requirements ./requirements.md

# 5. See your result
ls -l .specfirst/artifacts/

Repository Layout

A standard SpecFirst project looks like this:

• .specfirst/
  • artifacts/: Stored outputs from completed stages (hashed and versioned).
  • protocols/: Your workflow definitions (e.g., feature.yaml, bugfix.yaml).
• templates/: Markdown templates for your prompts (e.g., requirements.md, plan.md).
• protocol.yaml: The default workflow definition for the project.
• inputs/: (Optional) Context files or static inputs for your workflows.

Security

See SECURITY.md for guidance on data handling, credential safety, and using third-party models.

Documentation

• User Guide: Detailed "how-to" and workflow examples.
• CLI Reference: Commands, flags, and options.
• Protocol Reference: YAML schema and stage definitions.
• Template Reference: Guide to authoring stage templates.
• Template Context: Variables and runner guarantees.
• AI Integration: Patterns for using SpecFirst with AI tools.
• Philosophy: The "why" behind SpecFirst.

Canonical Examples

Complete, runnable examples with protocols and templates:

• Todo CLI: Full workflow walkthrough for a simple CLI application
• Bug Fix: Minimal 2-stage workflow for systematic bug fixes
• API Feature: Complete feature development with approvals and task decomposition
• Spec Review: Using cognitive scaffold commands to improve specification quality
• Refactoring: Structured code improvement with risk mitigation and verification
• Code Review: Staged, gated review workflow designed to converge
• Database Migration: Safe schema changes with approval gates and rollback planning
• Product Design: Design flow from product vision to implementation handoff

Install

From Source

make build
# Or
go build .

From GitHub Releases

Download the pre-built binary for your platform from Releases.