TinySpec

A tiny framework for writing specs for use with language models. Tinyspec integrates with Claude Code to provide a structured workflow for planning, refining, and implementing features.

Install

From crates.io:

cargo install tinyspec

From source:

git clone https://github.com/nmcdaines/tinyspec.git
cd tinyspec
cargo install --path .

Usage

Tinyspec follows a spec-driven workflow: create a spec, refine it with Claude, then work through the implementation plan.

1. Initialize

Run tinyspec init in your project directory to install Claude Code skills and set up shell completions:

cd your-project
tinyspec init

This creates three skills in .claude/skills/:

• /tinyspec:refine — Collaborate with Claude to define the problem and build an implementation plan
• /tinyspec:work — Work through the implementation plan task by task
• /tinyspec:task — Complete a specific task from the plan

To update the skills after upgrading tinyspec:

tinyspec init --force

2. Create a spec

tinyspec new my-feature

This creates a timestamped Markdown file in .specs/ with sections for Background, Proposal, Implementation Plan, and Test Plan. Open it in your editor to fill in the Background and Proposal:

tinyspec edit my-feature

3. Refine with Claude

In Claude Code, run:

/tinyspec:refine my-feature

Claude will read your spec, ask clarifying questions, and help you build out the Implementation Plan with task groups (A, B, C) and subtasks (A.1, A.2, etc.).

4. Implement

Once the plan is ready, run:

/tinyspec:work my-feature

Claude will work through each task group in order, checking off subtasks as they're completed and committing progress after each group.

To work on a specific task:

/tinyspec:task my-feature A.1

5. Track progress

tinyspec status my-feature
tinyspec status  # all specs

Configure

When a spec references multiple repositories, tinyspec resolves application names to folder paths using ~/.tinyspec/config.yaml.

Map a repository name to a path:

tinyspec config set my-app /path/to/my-app

List configured repositories:

tinyspec config list

Remove a mapping:

tinyspec config remove my-app

Then in your spec front matter, reference applications by name:

---
tinySpec: v0
title: My Feature
applications:
  - my-app
---

Develop

Build from source:

cargo build

Run tests:

cargo test

Install your local build:

cargo install --path .

Install git hooks (runs cargo fmt, cargo clippy --fix, and cargo test before each commit):

./scripts/install-hooks.sh