leanspec-dev-process
Skill296 starsChanged 6 months agoMITView on GitHub
The end-to-end spec-issue-driven dev loop for lean-spec — spec → branch → implement → PR → merge → closure. Use when asked "how do I start work", "what's the process", "SDD loop", "spec-driven development", "how do we ship a change on lean-spec", "from scratch what do I do", or when you're about to begin a non-trivial change on `codervisor/leanspec` and haven't yet decided how to split spec/PR. Delegates to `issue-spec` (spec writing), `leanspec-pre-push` (pre-push checks), `leanspec-pr-lifecycle` (post-push), and `leanspec-development` (commands, CI, publishing, i18n).
- Commits and pushes
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-pre-pushSkill
- leanspec-pr-lifecycleSkill
- watch-ciSkill
- leanspecSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 3 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 63
If the spec adds or changes user-visible strings, the Plan must include locale updates for both en and zh-CN, and the i18n label is applied.
- Very specific: line 67
Before opening a PR, resolve any open questions on the spec issue thread.
- Very specific: line 80
i18n discipline: No user-visible string ships in only one locale.
- Very specific: line 82
Rust discipline: All Rust code must pass cargo clippy -- -D warnings.
- Very specific: line 93
Verify a spec issue is linked, or that the PR will be labeled trivial.
- Very specific: line 94
If the spec is labeled provider-impact or i18n, confirm the corresponding evidence is in the PR.
- Very specific: line 96
Don't paper over warnings with --no-verify.
- Very specific: line 111
If the PR is genuinely trivial (typo, doc-only, one-line obvious fix), apply the trivial label and skip the spec-linking requirement.
- Distinctive: line 131
If you close a PR without merging (e.g.
- Very specific: line 135
Not every change needs a spec.
- Distinctive: line 142
Do NOT use for:
- Distinctive: line 149
When in doubt, write the spec.
≈ “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-dev-process
The spec-issue-driven development (SDD) loop on lean-spec. Every non-trivial change starts as a GitHub spec issue on codervisor/leanspec, proceeds through a PR that references it, and closes when the PR merges.
Lean-spec is its own dogfood: we use the SDD loop we ship. The historical specs/ directory is frozen as a snapshot of pre-migration work; new specs are GitHub issues. This is the same shape as Onsager's and Duhem's loops — the area taxonomy and toolchain checks are lean-spec-specific.
The loop
┌─────────────────────────────────────────────────────────────────┐
│ │
│ idea/request │
│ ↓ │
│ spec(<area>): ... ← issue-spec skill │
│ │ │
│ ↓ │
│ branch + implement │
│ │ │
│ ↓ │
│ leanspec-pre-push ← merge preview, typecheck, test, clippy │
│ │ │
│ ↓ │
│ git push → open PR (body: "Closes #N" or "Part of #N") │
│ │ │
│ ↓ │
│ leanspec-pr-lifecycle ← CI triage, review, iterate │
│ │ │
│ ↓ │
│ merge │
│ │ │
│ │ Closes #N → GitHub auto-closes spec │
│ │ Part of #N → tick Plan items manually (pr-lifecycle) │
│ ↓ │
│ spec closed (Closes) OR Plan items ticked (Part of) │
│ │
└─────────────────────────────────────────────────────────────────┘Stages
1. Write the spec
Trigger issue-spec (or say "spec this"). It creates a GitHub issue on codervisor/leanspec with:
## Overview,## Design,## Plan,## Test,## Alignment,## Notes## Provider impactwhen the change touches the provider seam- Open questions live under
## Alignmentas a### Open questionssubsection (omit if none) —leanspec-pre-pushblocks on unresolved items there. - Labels:
spec, one type (feat/fix/refactor/perf), one or morearea:*, onepriority:*. The full area taxonomy lives inissue-spec's SKILL.md.
Hard rule: no spec → no PR, unless the PR is labeled trivial (typos, doc-only fixes, one-line obvious bug repair).
Body size: <~2000 tokens. Larger features split into parent + sub-issues via mcp__github__sub_issue_write. The SDD loop runs independently on each sub-issue; the parent tracks overall progress.
If the spec touches the provider abstraction — types in packages/ui/src/types/specs.ts, the provider trait in rust/leanspec-core/, or anything else that crosses the markdown/github backend seam — it must include ## Provider impact. This is lean-spec's analogue of Duhem's schema-impact rule: the provider seam is the central product promise (CLI/MCP/UI behave identically across backends), so changes to it are tracked explicitly.
If the spec adds or changes user-visible strings, the Plan must include locale updates for both en and zh-CN, and the i18n label is applied. The leanspec-development skill's I18N.md is canonical.
2. Resolve open questions
Before opening a PR, resolve any open questions on the spec issue thread. A spec with unanswered ### Open questions is not ready to implement — its design isn't pinned yet.
3. Branch and implement
Branch naming convention:
- Human-owned branches: any name following
<type>/<short-description>(e.g.feat/github-provider,fix/cli-help-text). - Claude-owned branches:
claude/spec-<N>-<slug>orclaude/<descriptor>. The harness enforces theclaude/prefix on cloud sessions.
Implement the spec's Plan items in order. Keep commits small and focused. Commit messages: imperative mood, <72 chars, types feat / fix / refactor / test / docs / chore / ci / perf (matches codervisor/CLAUDE.md).
Provider-agnostic core discipline. When working in area:provider or area:core, the lean-spec invariant is that backend-specific concerns don't leak upward. Markdown-specific frontmatter parsing belongs in the markdown provider; github-specific issue mapping belongs in the github provider; both expose the same LightweightSpec / Spec shape upward. A change that adds a backend-typed field to a shared type is a regression of this invariant and must be called out in ## Provider impact.
i18n discipline. No user-visible string ships in only one locale. The leanspec-development skill's RULES.md lists this as a mandatory rule; CI enforces parity for the locale files it knows about.
Rust discipline. All Rust code must pass cargo clippy -- -D warnings. Functions with >7 args use a params struct (enforced by clippy.toml). Don't #[allow(dead_code)] or #[allow(unused)] past a clippy warning — fix the root cause.
4. Pre-push
Trigger leanspec-pre-push (or say "ready to push"). The full checklist is in that skill; in summary:
- Sync
origin/maininto the branch (CI tests a merge preview, not the branch alone). Resolve conflicts locally, never on the PR web editor. pnpm typecheck(never skip before marking complete).pnpm pre-push(typecheck + clippy).pnpm testfor the affected packages.pnpm format:rust:checkfor Rust changes.- Verify a spec issue is linked, or that the PR will be labeled
trivial. - If the spec is labeled
provider-impactori18n, confirm the corresponding evidence is in the PR.
Don't paper over warnings with --no-verify. If a hook fails, investigate.
5. Open the PR
PR body must begin with a linking line:
| PR delivers | Use |
| The full spec / acceptance test / vertical slice | Closes #N |
| A bug fix for a specific defect | Fixes #N |
| Scaffolding / one phase of a multi-phase spec | Part of #N |
| Related work that shouldn't close the spec | Refs #N |
Under ## Delivers, list the Plan items this PR ticks (exact text from the spec's Plan). After merge, tick those checkboxes manually on the parent spec — see leanspec-pr-lifecycle.
If the PR is genuinely trivial (typo, doc-only, one-line obvious fix), apply the trivial label and skip the spec-linking requirement. Use sparingly — if reviewers flag it as needing context, escalate to a spec.
Decide before opening, not after. Answer the spec-vs-trivial gate at PR creation: pass Closes #N / Part of #N in the PR body, or pass labels: ["trivial"] to mcp__github__create_pull_request. Don't push and let a reviewer ask.
6. During review
Trigger leanspec-pr-lifecycle (or say "triage PR" / "CI is failing" / respond to a webhook). It covers:
- CI triage: build / test / lint / i18n-parity failures.
- Review-comment discipline: fix the code, don't reply per comment.
- Webhook subscription to stream CI + review events.
7. Merge
Closes #NPRs auto-close the spec on merge.Part of #N/Refs #NPRs leave the spec open; tick the delivered Plan items manually on the parent spec, and if all sub-issues of a parent are closed, ping the parent. Seeleanspec-pr-lifecycle.- For PRs labeled
provider-impact, append the change toCHANGELOG.mdunder the next-version heading. Theleanspec-developmentskill's "Changelog" section is the format reference.
8. Closed-unmerged path
If you close a PR without merging (e.g. abandoned approach), the spec issue stays open as-is — the next implementer can pick it up from there.
The trivial escape hatch
Not every change needs a spec. The trivial label on a PR explicitly opts out. Use for:
- Typos in comments, docs, commit messages.
- One-line obvious bug fixes where the repro is in the diff itself.
- Formatting-only changes.
- Dependency version bumps (unless they break APIs).
Do NOT use for:
- Anything touching multiple files.
- Anything that changes the provider abstraction.
- Anything adding or changing a user-visible string (i18n parity is mandatory).
- Anything that could plausibly merit a follow-up.
When in doubt, write the spec.
Issue progress is the source of truth
A spec issue's open/closed state plus its Plan checkboxes are the source of truth. Use Closes #N only on a PR that delivers the final unticked Plan items, so GitHub's auto-close fires once the spec is actually complete; use Part of #N for partial slices that leave items behind, then tick the delivered checkboxes manually on merge. If a multi-PR spec finishes via Part of PRs only, a human closes the parent once the last Plan item ticks. Plan-item ticks on merge are manual; leanspec-pr-lifecycle covers the mechanics.
Anti-patterns (don't)
- PR without a spec and no
triviallabel. Reviewers will ask; the PR should not merge until the author either adds a spec link or thetriviallabel. - Closing a spec manually when you meant
Closes #N. Let GitHub do it via the PR merge so the timeline has the auditable link. - Editing Plan checkboxes to mark items done before the PR merges. Tick them on merge, not before.
- Provider change without
## Provider impactcallout. The provider seam is the central product promise; mis-tracking a change to it corrupts the signal for users adopting different backends. - User-visible string in only one locale. Both
enandzh-CNship together, every time. - Skipping
leanspec-pre-push. Even a thin checklist catches the cheap mistakes; the typecheck/clippy gate exists because CI re-runs these and slow CI cycles cost more than local cycles. - Authoring a new
specs/NNN-slug/directory. The file-based corpus is frozen post-migration. New work is GitHub issues.
Delegation map
| Stage | Skill / workflow |
| Write the spec | issue-spec (installed globally from onsager-ai/dev-skills) |
| Commands, CI, publishing, i18n | leanspec-development |
| Pre-push checks | leanspec-pre-push |
| CI triage, review, iterate | leanspec-pr-lifecycle |
| On PR merge → tick Plan items | leanspec-pr-lifecycle (manual) |
| GitHub CLI / cloud auth | github-integration (installed globally from onsager-ai/dev-skills) |
Relationship to Onsager / Duhem dev process
Lean-spec, Onsager, and Duhem share the SDD shape but live in separate repos with separate skills. When working on lean-spec, use this loop. The methodology itself comes from lean-spec — Onsager and Duhem are downstream adopters of the framework lean-spec defines. That's another reason to dogfood it here: if the SDD loop is awkward on lean-spec's own repo, that's a signal for the next iteration of the product.
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.

