lite-spec

lite-spec

Status: experimental — interfaces may change before v1.

A toolkit of four Claude Code skills (the spec- family) for the AI-era spec workflow. Enough structure for a solo developer or small team to think clearly and capture intent, without the ceremony of GitHub Spec Kit, OpenSpec, or BMAD-METHOD.

Mental model

Four artifacts, and one rule: you write intents, Claude writes code, /spec-check grades the code against each intent and derives the status — you never set it by hand.

Artifact	What it holds	Who owns it
specs/CONSTITUTION.md	Project-wide principles every intent must respect (optional)	You — via /spec-constitution
specs/INTENT/I-N-<slug>/intent.md	One feature's problem + EARS outcomes	You — via /spec-intent (author it, or accept the agent's proposal)
specs/INTENT/I-N-<slug>/plan.md	Optional, regenerable implementation plan	The agent — via /plan
CLAUDE.md pointer block	Wiring that tells Claude which files are which	/spec-init

An intent climbs a status ladder as more of its EARS outcomes pass:

draft → in_progress → complete     (drops back if a passing outcome later breaks;
                                    superseded = retired for a successor)

Everything else below is detail on those four files.

Quickstart

Requires Claude Code. Skills are modular agent capabilities Claude Code loads from ./.claude/skills/ (per-project) or ~/.claude/skills/ (global).

Install the skills

Pick one route. Both pull from the same repo.

Plugin marketplace (Claude Code v2.1+) — installs into Claude Code's plugin cache, supports /plugin update, namespaces skills as /lite-spec:spec-*:

/plugin marketplace add JasonLo/lite-spec
/plugin install lite-spec@lite-spec

Curl installer — copies skill folders into ./.claude/skills/ (per-project) or ~/.claude/skills/ (global), keeps bare skill names (/spec-init, /spec-intent, …):

curl -LsSf https://raw.githubusercontent.com/JasonLo/lite-spec/main/scripts/install.sh | sh

The two routes differ only in slash-command naming; natural-language triggers ("set up lite-spec", "check for drift", etc.) work either way. The rest of this README uses the bare names — prefix with lite-spec: if you installed via the plugin route.

Bootstrap the repo

/spec-init

Creates specs/ and wires the CLAUDE.md pointer block so future Claude sessions know which spec files are human-owned vs. agent-writable.

Basic flow

1. /spec-intent new "<title>" # open an intent: problem, EARS outcomes, non-goals
2. ... plan (optional) ... # /spec-intent offers to hand the intent to /plan
3. ... write code ...
4. /spec-check # verify the code still satisfies your open intents

Two ways to open an intent. /spec-intent new "<title>" interviews you section by section — you author it. /spec-intent propose flips that: the agent drafts the whole intent from context (problem, EARS outcomes, non-goals, constraints) and you just accept or refine it — a fast, capture-first path for when you'd rather build than answer a questionnaire. Either way nothing lands in specs/INTENT/ until you approve, and Claude may proactively offer propose when it's about to build something no open intent covers.

Optional, once you have a couple of intents: /spec-constitution locks in project-wide rules (test runner, linter, architecture) that every intent is then checked against. Intents work fine without it — add it when you want the guardrails.

Each /spec-intent new creates specs/INTENT/I-N-<slug>/intent.md (the experiments/ and checks/ subfolders are added only when something needs them). After writing the intent, /spec-intent (in any of new/propose/refine/supersede) offers to hand it to /plan; on yes, the resulting implementation plan is written to specs/INTENT/I-N-<slug>/plan.md — an agent-writable, regenerable sibling. Multiple intents may be open at once; /spec-check iterates every non-terminal intent and derives each one's status from outcome pass-counts.

Writing outcomes: EARS in 60 seconds

/spec-intent asks you to phrase each success criterion as an EARS statement:

WHEN <trigger> THE SYSTEM SHALL <response>.

• trigger — an observable event, state, or input ("when a client exceeds 5 attempts").
• response — externally observable behavior with a concrete threshold ("respond 429"), not "should feel fast".

Two other forms count too: IF <condition> THEN THE SYSTEM SHALL <response> for invariants, and WHILE <state> THE SYSTEM SHALL <response> for continuous behavior. One outcome per line. That's the whole notation — the structure is what lets /spec-check grade each SHALL individually instead of vibe-checking the feature as a whole.

Context-only intents: test citations are opt-in