Leanspec

LeanSpec — Spec Coding Skill

Teach agents spec coding: the practice of treating specs as durable artifacts that drive development, not ephemeral planning notes. LeanSpec provides the methodology and the leanspec CLI; each adapter (markdown, GitHub Issues, ADO, Jira, …) speaks its backend's native language. The skill is deliberately adapter-agnostic — never hard-code a status value, priority name, or field key here.

Start every session with capability discovery

Before reading, writing, or linking any specs, run:

leanspec capabilities -o json

The output is your source of truth. It tells you:

• The active adapter's name (markdown, github, ado, …).
• Which metadata fields exist and their types/enum values.
• Which field plays each semantic role (status, priority, tags, assignee, due_date) on this adapter.
• Which link types the backend understands (parent, depends_on, …).

Use the returned enum values as the only valid vocabulary. If you want to move a spec into the "working" state, look up the semantic status field, pick the value the adapter calls "work is underway," and send that — don't assume it's called in-progress.

Core principles

1. Specs are durable artifacts. They persist beyond the session, they are reviewable, and they link to code. They are not plan-mode scratch pads.
2. Methodology, not mechanics. The five phases below apply whether your backend is a markdown folder, a GitHub repo, or a Jira project.
3. Discovery first. Always read what exists before writing anything new.
4. Intent before implementation. Capture why first, how second.
5. Verify against reality. Never trust a status field alone — check code, commits, tests, CI.
6. Use the adapter's vocabulary. No hard-coded field names or values.

The five phases

1. Discover

Understand the current state of the project before touching anything.

1. Run leanspec capabilities -o json (session start).
2. Run leanspec board to see the current shape of the project.
3. Run leanspec search "<keywords>" to find related items.
4. If a close match exists, consider extending or linking to it rather than creating a new item.

2. Create

Capture intent as a new, durable artifact.

1. Run leanspec create <short-name> with every known field in a single call (title, body, semantic fields like status/priority, tags, parent, dependencies). Never create an empty item and then patch it.
2. Write the body with:
   • Overview — what problem this solves and why it matters.
   • Requirements — a checklist of independently verifiable items.
   • Non-goals — what's explicitly out of scope.
   • Acceptance criteria — measurable definition of done.
3. Link relationships as they emerge. Use the adapter's declared link types (typically parent for hierarchy and depends_on for blockers — confirm via capabilities).

3. Refine

Make the spec implementation-ready before coding starts.

1. Locate files, modules, and APIs referenced in the spec; verify they exist.
2. Find existing patterns to reuse; note concrete paths and function signatures in the spec.
3. Validate dependencies are available.
4. Gate: no blocking unknowns; every checklist item is specific and actionable.

4. Implement

Execute against the refined spec.

1. Read the spec (leanspec view <id>), including parent, children, and dependencies.
2. Transition the spec into its "work underway" state via leanspec update <id> using the adapter's declared status value.
3. Work the checklist in order; stay inside the scope boundaries; document decisions and discoveries inside the spec as they happen.
4. If you find out-of-scope work, create a new spec and link it rather than expanding the current one.