leanspec
Skill296 starsChanged 6 months agoMITView on GitHub
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.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- codervisor/leanspecword for word, first seen May 20, 2026
Other versions1 project uses a version of this.
Word for word · 1
- codervisor/leanspec★ 294100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs-site/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- leanspec-developmentSkill
- leanspec-dev-processSkill
- leanspec-pre-pushSkill
- leanspec-pr-lifecycleSkill
- watch-ciSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. About 0 are common, 12 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Before reading, writing, or linking any specs, run:
- Very specific: line 31
Use the returned enum values as the only valid vocabulary.
- Distinctive: line 42
Discovery first: Always read what exists before writing anything new.
- Distinctive: line 44
Verify against reality: Never trust a status field alone — check code, commits, tests, CI.
- Distinctive: line 46
Use the adapter's vocabulary: No hard-coded field names or values.
- Very specific: line 54
Run leanspec capabilities -o json (session start).
- Very specific: line 55
Run leanspec board to see the current shape of the project.
- Very specific: line 56
Run leanspec search "<keywords>" to find related items.
- Distinctive: line 57
If a close match exists, consider extending or linking to it rather than creating a new item.
- Very specific: line 64
Run leanspec create <short-name> with every known field in a single call (title, body, semantic fields like status/priority, tags, parent, …
- Distinctive: line 67
Write the body with:
- Very specific: line 90
Read the spec (leanspec view <id>), including parent, children, and dependencies.
- Distinctive: line 96
If you find out-of-scope work, create a new spec and link it rather than expanding the current one.
- Distinctive: line 103
Run the project's quality gates (tests, typecheck, lint, build).
- Distinctive: line 108
If anything failed, stay in-progress, fix the cause, and re-run.
- Distinctive: line 125
Never use both for the same pair.
- Distinctive: line 144
Keep each item under ~2000 tokens.
- Distinctive: line 146
Use references to external docs rather than copying them.
- Very specific: line 151
Never create items manually: Always use leanspec create.
- Very specific: line 152
Never edit raw metadata: Use leanspec update.
- Very specific: line 153
Always discover first: Run board / search before create.
- Very specific: line 154
Always pass every known field to
create: No empty-then-patch.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 jsonThe 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 boardto 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
parentfor hierarchy anddepends_onfor blockers — confirm viacapabilities).
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 --contentor edit the item body. - Metadata changes — use the supported
leanspec updateflags (--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/searchbeforecreate. - 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
capabilitiesif anything feels ambiguous.
References
- references/adapters.md — how adapters work and how to write your SOP on top of them.
- references/workflow.md — the five-phase workflow with examples.
- references/commands.md — CLI reference.
- references/best-practices.md — detailed patterns and anti-patterns.
- references/examples.md — end-to-end scenarios on markdown, GitHub Issues, and Azure DevOps backends.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

