convez.ai
Skill
aldianriski

lean-flow

aldianriski/lean-flow

Ver no GitHub
InicialPluginScore · de 0 a 100

Lean agentic dev loop for Claude Code: prime → lean-doc → orchestrate → repeat. Eleven standalone skills + an opt-in /flow conductor + a /council decision aid. No hooks, agent-free core — drop in and adapt.

Instalação

$npx convez-ai aldianriski/lean-flow

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

lean-flow

A lean agentic dev loop for Claude Code — eleven standalone skills, a one-command conductor, and an opt-in decision council. No hooks · no scaffold · agent-free core. Drop it into any repo and adapt.

MIT License Claude Code Skills Website

Quickstart · The skills · How it works · Architecture · Report a bug

[!NOTE] Why this exists. dev-flow was a brutal implementation — every reference bulk-imported, docs bloated past managing. lean-flow is the answer: curated, not copied — each component reviewed against "genuinely useful · important · actually used" and approved before adding. The point isn't fewer features by rule; it's that nothing gets in unreviewed.


Why lean-flow

Coding agents fail in recognizable ways. Each skill is the fix for one of them.

1 · It built the wrong thing. You assumed it understood you; it didn't. → /task-decomposer grills ambiguous intent at intake — one question at a time, presents interpretations, never picks silently — and its assumption registry surfaces what it's guessing; G1 Scope restates the task as one verifiable sentence; G2 re-grills anything still open (an unconfirmed assumption blocks the gate). Align before building.

2 · We keep reworking it. Scope and design problems surface only after the code exists. → The gates run before any commit; /task-decomposer cuts work into tracer-bullet vertical slices; /prototype answers a shaky design with throwaway code before you commit to it.

3 · The code doesn't work. The agent flies blind without feedback. → /tdd writes the failing test first (red-green-refactor); /diagnose builds a fast, deterministic feedback loop before hypothesising — the loop is the skill.

4 · It became a ball of mud. Agents accelerate coding, so they accelerate entropy. → /refactor-advisor finds shallow modules (the deletion test) and designs the deepening into small interfaces over deep implementations. Run it every few days.

5 · The docs rotted; the thread vanished between sessions. → /lean-doc-generator keeps docs WHY/WHERE-only against locked templates; /prime reloads context in a fixed order; /handoff carries the live thread to the next session.

6 · The backlog is chaos. Priorities drift, duplicates pile up, rejected ideas keep returning. → /triage re-ranks, states each task (ready / needs-info / blocked), and routes rejects to an .out-of-scope/ memory so they aren't re-litigated.


Quickstart

Install (Claude Code):

claude plugin install lean-flow@lean-flow

Or via marketplace URL:

claude plugin marketplace add https://github.com/aldianriski/lean-flow

Two ways to run it — conducted or à la carte.

Conducted — the whole disciplined loop in one command (gates + governance enforced, never auto-approved):

/flow "add OAuth login"     # drives: prime → feed → gated build → governed close

À la carte — the same loop, your hand on each step:

/prime                               # load context + health check
/task-decomposer "add OAuth login"   # intent → TASK-NNN backlog entries
/lean-doc-generator promote          # form a sprint from the backlog
/orchestrator sprint-bulk            # build it through the G1 / G2 gates
/lean-doc-generator close            # retro → CHANGELOG · TD · LEARNINGS, then /release-patch

The rest — /triage · /diagnose · /tdd · /refactor-advisor · /prototype · /handoff — is invoked as the work needs it. Every skill also runs alone; /flow just conducts them in order.


The loop

  /prime ──▶ /lean-doc-generator ──▶ /orchestrator ──┐
   load          plan & document         build, gated │
     ▲           (promote / close)       (G1 → G2 → ship)
     │                                                 │
     └──────────────────── repeat ◀────────────────────┘

  session end → /handoff  ──▶  temp-dir doc  ──▶  next session: /prime reads it
  1. /prime — load project context in a fixed order, emit a health check.
  2. /lean-doc-generator — capture WHY/WHERE (never HOW); run the sprint lifecycle.
  3. /orchestrator — execute through the G1 Scope and G2 Design gates, then commit.
  4. Repeat. When a session ends mid-work, /handoff compacts it so /prime can resume next time.

Run it conducted (/flow drives every stage in order, gates enforced) or à la carte (each skill by hand) — same artifacts either way.


The skills

One conductor + eleven standalone stages + an opt-in decision council. /flow conducts; the eleven stage-skills each also run standalone (none require another); /council is for hard forks.

StageSkillUse it for
conduct/flowopt-in — run the whole loop in order; enforces gates + governance, never auto-approves
orient/primesession start — ordered context load + health check
plan/lean-doc-generatordocs / ADRs / sprint promote + close (WHY & WHERE only) — ships its own templates + standard
/task-decomposerintent / ticket / PRD → TASK-NNN backlog entries (tracer-bullet slices)
/triagere-prioritise + state the backlog; route rejects to .out-of-scope/
build/orchestratorgate-driven execution — quick · mvp · sprint-bulk
/prototypethrowaway code to answer one design question (logic TUI / web UI variants)
/tddbuild NEW behaviour test-first — vertical-slice red-green-refactor
maintain/diagnose6-phase systematic debugging with a regression test
/refactor-advisorfind shallow→deep refactors (seams · deletion test) and design them
ship/release-patchmanifest-detect PATCH bump + changelog; stops before push
continuity/handoffcompact the conversation → temp-dir doc for the next session
decide/councilopt-in — pressure-test a hard/ambiguous call via 5 advisors → verdict-<slug>.md → feed an ADR (uses sub-agents)

The feed side is a pipeline: /task-decomposer (intake) → /triage (groom) → /lean-doc-generator promote (form sprint) → /orchestrator (build). Canonical roster · gates · modes → .claude/CONTEXT.md.

[!NOTE] Standalone, not isolated. Skills cross-reference each other only as routing/handoff suggestions (→ try /X next), never as requirements — invoke any one cold and it completes its own job. The pipeline and routing are the optimal composition, not a dependency graph. The only inherent ordering is the sprint lifecycle (you can't close a sprint you didn't promote).


How it works

A gated loop: you give intent → it becomes tasks → executes with human checkpoints → ships. The gates are inline checklists (lean-flow ships no agents of its own), and the loop dispatches Claude's built-in agents where they help — recon → Explore, review → /code-review, verify → /verify, security → /security-review. /council is the one skill that orchestrates sub-agents internally.

Gates — humans approve; the skill never self-approves:

  • G1 Scope (all modes) — goal restated as one verifiable sentence · size S/M/L (an L splits) · files / blast-radius · out-of-scope named · assumptions confirmed.
  • G2 Design (mvp · sprint-bulk) — approach + one-line WHY · verifiable micro-tasks · an ADR only if the decision is hard-to-reverse and surprising and a real trade-off · residual grill until the goal is unambiguous (the detailed grill already ran at intake, in /task-decomposer).

Modes (/orchestrator <mode>):

ModeGatesUse when
quickG1single small low-risk task
mvpG1 + G2feature work, medium+, multi-step
sprint-bulkG1+G2 onceauto-loop the Active Sprint task list

Implement routing — at the build step, orchestrator routes by work type: new testable behaviour → /tdd · a bug or failing test → /diagnose · hard-to-change code → /refactor-advisor · docs / config / spikes implement directly. It also wires Claude's built-in commands — /goal (drive-until-DoD) · /plan (G2) · /batch (parallel sprint) · /run + /verify (Review).

Documentation discipline — /lean-doc-generator follows the LEAN DOCUMENTATION STANDARD: WHY and WHERE only, never HOW. It bundles its own canonical templates and reads the matching one before generating any core doc, so output matches a fixed format instead of free-improvising. Standard → skills/lean-doc-generator/references/DOCS_Guide.md.

Continuous learning — every iteration feeds the next. At Sprint Close the Retro auto-files four buckets to durable homes — shipped → CHANGELOG, tech debt → TD-NNN, follow-ups → TASK-NNN backlog, learnings → LEARNINGS.md. At Sprint Promote a governance checkpoint promotes any learning that recurs (count ≥ 2) into a durable rule and ages tech debt. Learning and debt can't silently rot. Governance → DOCS_Guide §10.


What you get

The skills write durable, human-readable state into your repo — plain markdown, no database, no lock-in:

ArtifactWritten byHolds
TODO.md/task-decomposer · /triagebacklog (P0–P3) · tech debt · active-sprint pointer(s)
docs/sprint/SPRINT-NNN-*.md/lean-doc-generatoractive sprint plan · execution log · retro
docs/DECISIONS.md / docs/adr//lean-doc-generatorADRs — the WHY behind hard-to-reverse choices
docs/CHANGELOG.md/release-patch · sprint closewhat shipped, per release
docs/LEARNINGS.mdsprint closeconfirmed learnings; recurring → durable rules
.out-of-scope//triagerejected ideas, so they aren't re-litigated
CLAUDE.md · CONTEXT.md · ARCHITECTURE.md/lean-doc-generatorproject shape · vocab · where-things-live

Commit them, and your team — and their agents — start from the same map.


Adapting to your repo

Skills auto-discover at the repo root after install. There is nothing to scaffold — the skills read whatever context files your project already has (CLAUDE.md, README.md, TODO.md, docs/CHANGELOG.md, docs/ARCHITECTURE.md — legacy root locations still matched) and degrade gracefully when one is missing. /prime aborts on nothing. No code-graph dependency — if you happen to run graphify (graphify-out/), /prime will use it for orientation, but it's never required.

Already have docs (or ran dev-flow / adlc-flow)? /lean-doc-generator migrate aligns them to lean-flow's placement · format · wiring — plan → approve → apply, surgically (never deletes your content), so you're not hand-reconciling or lost in existing code.

Requirements: Claude Code CLI. (Node / language toolchains matter only for whatever your own project needs — lean-flow itself is Markdown.)


What lean-flow does NOT do

  • No app-code generation, CI/CD pipeline, or automated coverage tooling.
  • No background hooks, and no agent definitions of its own — the loop leans on Claude's built-in agents (Explore, /code-review, /verify, /security-review) rather than re-shipping them. The one skill that orchestrates sub-agents internally is the opt-in /council.
  • No project scaffold written into your repo (that was dev-flow's /orchestrator init).
  • No telemetry. Nothing is sent anywhere.

If you want the richer agent roster, gated init scaffold, and ADLC modes, use dev-flow / adlc-flow instead. lean-flow is the lean cut.


Architecture

Full map — composition rule, the loop, integration points, boundaries → docs/ARCHITECTURE.md.

.claude-plugin/   plugin.json · marketplace.json        (lockstep versions)
skills/           13 skills — /flow conductor + 11 stages + /council (auto-discovered)
  lean-doc-generator/
    references/   DOCS_Guide.md · migration-map.md · ADR-example.md
    templates/    11 canonical doc templates (incl. SPRINT · ADR · CONTEXT)
  tdd/references/             testability.md
  diagnose/references/        feedback-loops.md
  task-decomposer/references/ prd-and-slices.md
  refactor-advisor/references/ deepening.md
  prototype/references/       logic.md · ui.md
  council/                    opt-in agent decision aid
.claude/          CLAUDE.md (shape) · CONTEXT.md (vocab · loop · gates · roster — SSOT)
docs/             ARCHITECTURE.md · CHANGELOG.md · DECISIONS.md · LEARNINGS.md · adr/ · sprint/
TODO.md · README.md

Design principles

  • Curated, not copied — the core discipline. Every component was reviewed against "genuinely useful · important · actually used" and approved before adding — the opposite of bulk-importing from every reference. The bar is review, not a feature ban.
  • Standalone, conducted when you want — the eleven stage-skills each run alone (none require another); the opt-in /flow conductor sequences them through the full loop without bypassing a gate.
  • Ships no agents; leverages the built-in ones — no agent definitions of its own; the loop dispatches Claude's built-in agents (Explore · /code-review · /verify · /security-review) in isolated passes. /council is the one skill that orchestrates sub-agents internally.
  • Lean — most SKILL.md ≤ ~110 lines; the one skill that needs a canonical format (lean-doc-generator) bundles its own templates + standard and stays self-contained.
  • Adaptable — no required scaffold; skills detect the host project's layout and degrade gracefully.
  • Human-gated — G1 Scope and G2 Design need explicit sign-off; /release-patch never pushes.

Provenance

Distilled from dev-flow. Techniques adapted from mattpocock/skills: the ADR "offer sparingly" test + glossary discipline + grilling moves (grill-with-docs) · /handoff · /triage + .out-of-scope/ · /tdd · /diagnose's feedback-loop discipline · /refactor-advisor's deep-module vocabulary (improve-codebase-architecture) · /prototype · this README's failure-mode framing. Behavioral Guidelines borrow Karpathy's LLM-coding guidelines; /council adapts the LLM Council method; this README's layout follows the Best-README-Template. All re-cut for lean-flow's markdown-first, agent-free-core, stack-agnostic constraints.

Further reading: .claude/CONTEXT.md (SSOT) · .claude/CLAUDE.md · DOCS_Guide.md (the standard).


License

MIT — see LICENSE. Built and maintained by Aldian Rizki.

Doc owner: Maintainer · last updated 2026-06-12 · status: current · v1.0.0

Ver o original no GitHub

Bom para

Relacionados