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
- Specs are durable artifacts. They persist beyond the session, they are
reviewable, and they link to code. They are not plan-mode scratch pads.
- Methodology, not mechanics. The five phases below apply whether your
backend is a markdown folder, a GitHub repo, or a Jira project.
- Discovery first. Always read what exists before writing anything new.
- Intent before implementation. Capture why first, how second.
- Verify against reality. Never trust a status field alone — check code,
commits, tests, CI.
- 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.
- Run
leanspec capabilities -o json (session start).
- Run
leanspec board to see the current shape of the project.
- Run
leanspec search "<keywords>" to find related items.
- 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.
- 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.
- 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.
- 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.
- Locate files, modules, and APIs referenced in the spec; verify they exist.
- Find existing patterns to reuse; note concrete paths and function signatures
in the spec.
- Validate dependencies are available.
- Gate: no blocking unknowns; every checklist item is specific and actionable.
4. Implement
Execute against the refined spec.
- Read the spec (
leanspec view <id>), including parent, children, and
dependencies.
- Transition the spec into its "work underway" state via
leanspec update <id> using the adapter's declared status value.
- Work the checklist in order; stay inside the scope boundaries; document
decisions and discoveries inside the spec as they happen.
- If you find out-of-scope work, create a new spec and link it rather
than expanding the current one.
5. Verify
Close the loop against reality, not status.
- Run the project's quality gates (tests, typecheck, lint, build).
- Re-read the spec's acceptance criteria and tick each one only if you can
point to the commit, test, or file that proves it.
- Transition the spec to its adapter-declared "done" state, and append a
short implementation note.
- If anything failed, stay in-progress, fix the cause, and re-run.
Relationship types
Relationships are adapter-declared. Check capabilities.link_types. The two
most common shapes:
- Parent / child — an umbrella decomposed into child items. A child
doesn't make sense without its parent; the parent completes when all its
children do.
- Depends on — a blocker. Both items are independent work; one just has
to ship first.
Decision flowchart:
- Is item B part of item A's scope? → parent/child.
- Does item B just need item A finished first? → depends-on.
- Never use both for the same pair.
Litmus test: "If item A didn't exist, would item B still make sense?"
No → B is A's child. Yes → B depends on A.
Managing evolving work
- Content changes — use
leanspec update --content or edit the item body.
- Metadata changes — use the supported
leanspec update flags
(--status, --priority, --assignee, --add-tags, --remove-tags,
etc.) for adapter-declared fields. Each flag accepts values from the
adapter's capabilities. The skill never writes raw frontmatter or YAML.
- Scope creep — split. Create a sibling spec and link it; update the
original's non-goals to reference the split.
- Obsolete work — transition to the adapter's "closed/archived" state
rather than deleting; history matters.
Context economy
- Keep each item under ~2000 tokens. Split if larger.
- Favour bullet lists over prose.
- Use references to external docs rather than copying them.
- Checklists are for actionable items only — plain lists for everything else.
Best practices — at a glance
- Never create items manually. Always use
leanspec create.
- Never edit raw metadata. Use
leanspec update.
- Always discover first. Run
board / search before create.
- Always pass every known field to
create. No empty-then-patch.
- Always verify before closing. Tests, typecheck, lint, build.
- Trust the adapter's vocabulary. Re-run
capabilities if anything feels
ambiguous.
References
1---2name: leanspec3description: The spec-coding methodology for AI-assisted development. Use when planning features, creating/refining/implementing/verifying specs, or organising a project. Works with whatever spec backend your team already uses — local markdown, GitHub Issues, Azure DevOps, Jira — by delegating platform-specific details to a LeanSpec adapter.4metadata:5 source: https://skillmd.com/skills/codervisor/leanspec6---78# LeanSpec — Spec Coding Skill910Teach agents **spec coding**: the practice of treating specs as durable11artifacts that drive development, not ephemeral planning notes. LeanSpec12provides the methodology and the `leanspec` CLI; each **adapter** (markdown,13GitHub Issues, ADO, Jira, …) speaks its backend's native language. The skill14is deliberately adapter-agnostic — never hard-code a status value, priority15name, or field key here.1617## Start every session with capability discovery1819Before reading, writing, or linking any specs, run:2021```bash22leanspec capabilities -o json23```2425The output is your source of truth. It tells you:2627- The active adapter's name (`markdown`, `github`, `ado`, …).28- Which metadata fields exist and their types/enum values.29- Which field plays each **semantic role** (`status`, `priority`, `tags`,30 `assignee`, `due_date`) on this adapter.31- Which link types the backend understands (`parent`, `depends_on`, …).3233Use the returned enum values as the only valid vocabulary. If you want to move34a spec into the "working" state, look up the semantic `status` field, pick the35value the adapter calls "work is underway," and send that — don't assume it's36called `in-progress`.3738## Core principles39401. **Specs are durable artifacts.** They persist beyond the session, they are41 reviewable, and they link to code. They are not plan-mode scratch pads.422. **Methodology, not mechanics.** The five phases below apply whether your43 backend is a markdown folder, a GitHub repo, or a Jira project.443. **Discovery first.** Always read what exists before writing anything new.454. **Intent before implementation.** Capture *why* first, *how* second.465. **Verify against reality.** Never trust a status field alone — check code,47 commits, tests, CI.486. **Use the adapter's vocabulary.** No hard-coded field names or values.4950## The five phases5152### 1. Discover5354Understand the current state of the project before touching anything.55561. Run `leanspec capabilities -o json` (session start).572. Run `leanspec board` to see the current shape of the project.583. Run `leanspec search "<keywords>"` to find related items.594. If a close match exists, consider extending or linking to it rather than60 creating a new item.6162### 2. Create6364Capture intent as a new, durable artifact.65661. Run `leanspec create <short-name>` with every known field in a single call67 (title, body, semantic fields like status/priority, tags, parent,68 dependencies). Never create an empty item and then patch it.692. Write the body with:70 - **Overview** — what problem this solves and why it matters.71 - **Requirements** — a checklist of independently verifiable items.72 - **Non-goals** — what's explicitly out of scope.73 - **Acceptance criteria** — measurable definition of done.743. Link relationships as they emerge. Use the adapter's declared link types75 (typically `parent` for hierarchy and `depends_on` for blockers — confirm76 via `capabilities`).7778### 3. Refine7980Make the spec implementation-ready before coding starts.81821. Locate files, modules, and APIs referenced in the spec; verify they exist.832. Find existing patterns to reuse; note concrete paths and function signatures84 in the spec.853. Validate dependencies are available.864. Gate: no blocking unknowns; every checklist item is specific and actionable.8788### 4. Implement8990Execute against the refined spec.91921. Read the spec (`leanspec view <id>`), including parent, children, and93 dependencies.942. Transition the spec into its "work underway" state via95 `leanspec update <id>` using the adapter's declared status value.963. Work the checklist in order; stay inside the scope boundaries; document97 decisions and discoveries inside the spec as they happen.984. If you find out-of-scope work, create a **new** spec and link it rather99 than expanding the current one.100101### 5. Verify102103Close the loop against reality, not status.1041051. Run the project's quality gates (tests, typecheck, lint, build).1062. Re-read the spec's acceptance criteria and tick each one only if you can107 point to the commit, test, or file that proves it.1083. Transition the spec to its adapter-declared "done" state, and append a109 short implementation note.1104. If anything failed, stay in-progress, fix the cause, and re-run.111112## Relationship types113114Relationships are adapter-declared. Check `capabilities.link_types`. The two115most common shapes:116117- **Parent / child** — an umbrella decomposed into child items. A child118 doesn't make sense without its parent; the parent completes when all its119 children do.120- **Depends on** — a blocker. Both items are independent work; one just has121 to ship first.122123**Decision flowchart:**1241251. Is item B part of item A's scope? → parent/child.1262. Does item B just need item A finished first? → depends-on.1273. Never use both for the same pair.128129**Litmus test:** "If item A didn't exist, would item B still make sense?"130**No** → B is A's child. **Yes** → B depends on A.131132## Managing evolving work133134- **Content changes** — use `leanspec update --content` or edit the item body.135- **Metadata changes** — use the supported `leanspec update` flags136 (`--status`, `--priority`, `--assignee`, `--add-tags`, `--remove-tags`,137 etc.) for adapter-declared fields. Each flag accepts values from the138 adapter's capabilities. The skill never writes raw frontmatter or YAML.139- **Scope creep** — split. Create a sibling spec and link it; update the140 original's non-goals to reference the split.141- **Obsolete work** — transition to the adapter's "closed/archived" state142 rather than deleting; history matters.143144## Context economy145146- Keep each item under ~2000 tokens. Split if larger.147- Favour bullet lists over prose.148- Use references to external docs rather than copying them.149- Checklists are for actionable items only — plain lists for everything else.150151## Best practices — at a glance152153- **Never create items manually.** Always use `leanspec create`.154- **Never edit raw metadata.** Use `leanspec update`.155- **Always discover first.** Run `board` / `search` before `create`.156- **Always pass every known field to `create`.** No empty-then-patch.157- **Always verify before closing.** Tests, typecheck, lint, build.158- **Trust the adapter's vocabulary.** Re-run `capabilities` if anything feels159 ambiguous.160161## References162163- [references/adapters.md](./references/adapters.md) — how adapters work and164 how to write your SOP on top of them.165- [references/workflow.md](./references/workflow.md) — the five-phase workflow166 with examples.167- [references/commands.md](./references/commands.md) — CLI reference.168- [references/best-practices.md](./references/best-practices.md) — detailed169 patterns and anti-patterns.170- [references/examples.md](./references/examples.md) — end-to-end scenarios171 on markdown, GitHub Issues, and Azure DevOps backends.