agentleFS
codervisorcodervisor/lean-spec/skills/leanspec/SKILL.md

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

  • Other versions1 project uses a version of this.

    Word for word · 1

    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.

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
  1. Distinctive:

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

    line 17
  2. Very specific:

    Use the returned enum values as the only valid vocabulary.

    line 31
  3. Distinctive:

    Discovery first: Always read what exists before writing anything new.

    line 42
  4. Distinctive:

    Verify against reality: Never trust a status field alone — check code, commits, tests, CI.

    line 44
  5. Distinctive:

    Use the adapter's vocabulary: No hard-coded field names or values.

    line 46
  6. Very specific:

    Run leanspec capabilities -o json (session start).

    line 54
  7. Very specific:

    Run leanspec board to see the current shape of the project.

    line 55
  8. Very specific:

    Run leanspec search "<keywords>" to find related items.

    line 56
  9. Distinctive:

    If a close match exists, consider extending or linking to it rather than creating a new item.

    line 57
  10. Very specific:

    Run leanspec create <short-name> with every known field in a single call (title, body, semantic fields like status/priority, tags, parent, …

    line 64
  11. Distinctive:

    Write the body with:

    line 67
  12. Very specific:

    Read the spec (leanspec view <id>), including parent, children, and dependencies.

    line 90
  13. Distinctive:

    If you find out-of-scope work, create a new spec and link it rather than expanding the current one.

    line 96
  14. Distinctive:

    Run the project's quality gates (tests, typecheck, lint, build).

    line 103
  15. Distinctive:

    If anything failed, stay in-progress, fix the cause, and re-run.

    line 108
  16. Distinctive:

    Never use both for the same pair.

    line 125
  17. Distinctive:

    Keep each item under ~2000 tokens.

    line 144
  18. Distinctive:

    Use references to external docs rather than copying them.

    line 146
  19. Very specific:

    Never create items manually: Always use leanspec create.

    line 151
  20. Very specific:

    Never edit raw metadata: Use leanspec update.

    line 152
  21. Very specific:

    Always discover first: Run board / search before create.

    line 153
  22. Very specific:

    Always pass every known field to create: No empty-then-patch.

    line 154

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

5. Verify

Close the loop against reality, not status.

  1. Run the project's quality gates (tests, typecheck, lint, build).
  2. 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.
  3. Transition the spec to its adapter-declared "done" state, and append a short implementation note.
  4. 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:

  1. Is item B part of item A's scope? → parent/child.
  2. Does item B just need item A finished first? → depends-on.
  3. 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

  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.