Skip to content
Skills Library
Programming · Planning

leanspec-dev-process

/leanspec-dev-process

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

Repository
leanspec ↗
Licence
MIT
Last repository change
20.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 20.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

how do I start workwhatSDD loopspec-driven developmenthow do we ship a change on lean-specfrom scratch what do I do
Original author description

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

How it works

  1. The loop
  2. Stages
  3. The trivial escape hatch
  4. Issue progress is the source of truth
  5. Anti-patterns (don't)
  6. Delegation map
  7. Relationship to Onsager / Duhem dev process
Original SKILL.md headings · 173 lines, 1,624 words
SKILL.md preview
---
name: leanspec-dev-process
description: 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).
metadata:
  internal: true
---

# 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 impact` when the change touches the provider seam
- Open questions live under `## Alignment` as a `### Open questions` subsection (omit if none) — `leanspec-pre-push` blocks on unresolved items there.
- Labels: `spec`, one type (`feat` / `fix` / `refactor` / `perf`), one or more `area:*`, one `priority:*`. The full area taxonomy lives in `issue-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](../leanspec-development/references/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>` or `claude/<descriptor>`. The harness enforces the `claude/` 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:

1. Sync `origin/main` into the branch (CI tests a merge preview, not the branch alone). Resolve conflicts locally, never on the PR web editor.
2. `pnpm typecheck` (never skip before marking complete).
3. `pnpm pre-push` (typecheck + clippy).
4. `pnpm test` for the affected packages.
5. `pnpm format:rust:check` for Rust changes.
6. Verify a spec issue is linked, or that the PR will be labeled `trivial`.
7. If the spec is labeled `provider-impact` or `i18n`, 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 #N` PRs auto-close the spec on merge.
- `Part of #N` / `Refs #N` PRs 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. See `leanspec-pr-lifecycle`.
- For PRs labeled `provider-impact`, append the change to `CHANGELOG.md` under the next-version heading. The `leanspec-development` skill'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 `trivial` label.** Reviewers will ask; the PR should not merge until the author either adds a spec link or the `trivial` label.
- **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 impact` callout.** 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 `en` and `zh-CN` ship 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`](https://github.com/onsager-ai/dev-skills/blob/main/skills/issue-spec/SKILL.md) (installed globally from `onsager-ai/dev-skills`) |
| Commands, CI, publishing, i18n              | [`leanspec-development`](../leanspec-development/SKILL.md)      |
| Pre-push checks                             | [`leanspec-pre-push`](../leanspec-pre-push/SKILL.md)            |
| CI triage, review, iterate                  | [`leanspec-pr-lifecycle`](../leanspec-pr-lifecycle/SKILL.md)    |
| On PR merge → tick Plan items               | [`leanspec-pr-lifecycle`](../leanspec-pr-lifecycle/SKILL.md) (manual) |
| GitHub CLI / cloud auth                     | [`github-integration`](https://github.com/onsager-ai/dev-skills/blob/main/skills/github-integration/SKILL.md) (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.

Versions

The database has no other skills named leanspec-dev-process.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 14e548512903 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100leanspec-development
    Development workflows, commands, publishing, CI/CD, changelog management, and contribution guidelines for LeanSpec. Use when contributing code, fixing bugs, setting up dev environment, running tests or linting, working with the monorepo structure, looking up…
  • 100leanspec
    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…
  • 90spec-driven
    Guide spec-driven development workflow (Requirements → Design → Tasks → Implementation) with approval gates between phases. Use when user wants structured feature planning or says "use spec-driven" or "follow the spec process".
  • 100dev-spec-driven-implementation
    Use to implement a scoped multi-step change from an existing spec, handoff, issue, or explicit delivery request. Do not trigger for read-only analysis, planning, or a trivial localized edit.
  • 100workflow-build-feature
    Build a feature end to end: spec and TDD, implement, unit tests, Playwright check, PR. Use when "build a feature" or "implement this end-to-end". Spec/TDD loop only → workflow-spec-tdd. One bug → workflow-fix-and-ship.
  • 100spec-driven-dev
    Use when starting any non-trivial feature, refactor, or new project that will touch more than one file. Drives an AI coding agent through a gated Spec → Plan → Build → Test → Review → Ship lifecycle so work is specified before it is built, verified before it is reviewed, and…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.