pi-spec-kit

Specification-driven development skills for pi. A structured workflow for turning ideas into specs, plans, and implementations — with the AI agent following your lead, not the other way around.

Based on the spec-kit approach to requirements-first development, adapted for pi's skill system.

Install

# Global — available in all your projects
pi install git:github.com/Waveform-Analytics/pi-spec-kit

# Per-project — saved to .pi/settings.json, shared with collaborators
pi install -l git:github.com/Waveform-Analytics/pi-spec-kit

Skills

Skill	Description
speckit-init	Scaffold .specify/ in a new project — creates directories, copies templates, sets up roadmap. Replaces the old specify init CLI.
speckit-constitution	Create or update the project constitution at .specify/memory/constitution.md. Manages principles, versioning, and propagates changes.
speckit-roadmap	Create or update the project roadmap. Track features, priorities, and progress.
speckit-specify	Create or update a feature spec from a natural language description. Generates spec.md with user stories, requirements, success criteria, and a quality checklist.
speckit-clarify	Identify underspecified areas in a feature spec by asking up to 5 targeted clarification questions, then encoding answers back into the spec.
speckit-checklist	Generate a requirements quality checklist for a feature. Checklists are "unit tests for English" — they validate that requirements are complete, clear, and measurable.
speckit-plan	Generate an implementation plan from a feature spec. Produces research.md, data-model.md, contracts/, and quickstart.md.
speckit-tasks	Generate an actionable, dependency-ordered tasks.md from design artifacts. Organizes tasks by user story with phases.
speckit-analyze	Cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md. Finds inconsistencies, gaps, and constitution violations.
speckit-tests	Generate test plans from specs and implementation artifacts.
speckit-implement	Execute the implementation plan by processing tasks from tasks.md. Works phase-by-phase, pauses for review after each file.

Workflow

The typical flow looks like this. You don't have to follow every step — use what you need.

1. Initialize your project

/skill:speckit-init

This creates the .specify/ directory structure in your project, copies default templates, and sets up a roadmap. Run this once per project.

2. Write a spec

/skill:speckit-specify Python CLI that ingests hydrophone CSV data, detects whale calls using a bandpass filter, and outputs a summary plot

You describe the feature in plain language. The skill creates a structured spec with user stories, requirements, and success criteria. The spec lives at specs/<feature>/spec.md.

3. Clarify the spec

/skill:speckit-clarify specs/auth/spec.md

The agent reads your spec and asks up to 5 targeted questions about underspecified areas. Your answers get folded back into the spec. This is where you catch gaps before you're deep in implementation.

4. Generate a plan

/skill:speckit-plan specs/auth/spec.md

Produces implementation artifacts — research notes, data model, API contracts, and a quickstart guide. These live alongside the spec in specs/<feature>/plan/.

5. Generate tasks

/skill:speckit-tasks specs/auth

Turns the plan into a dependency-ordered task list organized by user story. Each task is concrete and actionable. Output goes to specs/<feature>/tasks.md.

6. Implement

/skill:speckit-implement specs/auth

The agent works through tasks phase by phase. After each file change, it pauses for you to review. Leave inline comments to give feedback, then say "ready" to continue. This keeps you in control of every change.

Supporting skills

Use these at any point in the process:

• speckit-analyze — Run after generating tasks to check for inconsistencies across your spec, plan, and tasks before you start coding.
• speckit-checklist — Generate a quality checklist for your requirements. Good to run after specifying, before planning.
• speckit-constitution — Set up project-wide principles that all specs should follow (e.g., "all APIs must be RESTful", "prefer composition over inheritance").
• speckit-roadmap — Track features and priorities across your project.
• speckit-tests — Generate test plans from your specs and implementation.

Template Customization

pi-spec-kit ships with default templates for specs, plans, tasks, checklists, roadmaps, tests, and constitutions.

When you run speckit-init, these templates are copied into your project at .specify/templates/. Skills check for project templates first, falling back to the package defaults if none are found.

To customize templates for a specific project, edit the copies in .specify/templates/. Your changes won't be overwritten by package updates or re-running speckit-init.

To get fresh copies of updated package templates, delete the specific template file from .specify/templates/ and re-run /skill:speckit-init — it will only copy templates that are missing.

Version

Check your installed version:

pi list

Update to the latest:

pi update

Compatibility

Skills follow the Agent Skills standard. While pi-spec-kit is built for pi, the skills are plain markdown files — any harness that supports the standard can use them.

License

MIT