Leanspec Dev Process

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 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:

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.