LeanPowers

A lightweight workflow microkernel that keeps coding agents rigorous without making every task heavy.

Essential workflows. Less ceremony.

简体中文 · Install · How it works · Superpowers comparison · Benchmark · Contributing

LeanPowers gives Codex and Claude Code six focused engineering workflows plus two small control Skills. It selects the lowest-safe path for the task, requires current evidence before completion, and can optionally learn narrow project rules from explicit feedback—all without an MCP server, daemon, telemetry, or always-on orchestration layer.

If that is the kind of agent workflow you want to see grow, Star LeanPowers and share what should stay lightweight.

Release status: 0.2.0 is a technical preview with dynamic risk routing and opt-in project learning. Paired live benchmark reports and audits are published transparently; see the latest scored result, post-run audit, V8 unscored audit, and benchmark protocol.

Lineage and thanks: Superpowers is the upstream reference and principal engineering foundation for this independent project. Its evidence-first engineering discipline, TDD, systematic debugging, review, verification, and safe-delivery ideas made LeanPowers possible. LeanPowers carries those principles into a smaller, risk-adaptive control surface; the comparison is a lineage-and-tradeoff study. See Acknowledgments.

Why LeanPowers

• Learns from explicit follow-up feedback and applies only the most relevant project lessons next time.
• Selects one lowest-safe workflow dynamically instead of preloading a long mandatory chain.
• Six focused engineering workflows, coordinated by the small route and adapt control Skills.
• lean, standard, and strict paths selected by observable risk.
• Single-agent execution by default; bounded subagents only for independent work.
• Current evidence required before completion or delivery claims.
• Static installed packages with no MCP server, daemon, telemetry, or third-party dependency installation.
• Native packages for both Codex and Claude Code, plus portable Agent Skills.

Install in 60 seconds

The repository is its own marketplace. Install directly from GitHub—no clone is required.

Codex

codex plugin marketplace add LAwLi3tCoding/LeanPowers
codex plugin add leanpowers@leanpowers

Codex uses native Skill discovery and receives no startup prompt injection.

Claude Code

claude plugin marketplace add LAwLi3tCoding/LeanPowers
claude plugin install leanpowers@leanpowers

Inside an interactive Claude Code session, use:

/plugin marketplace add LAwLi3tCoding/LeanPowers
/plugin install leanpowers@leanpowers

Claude Code receives one compact, read-only SessionStart routing charter. The hook does not scan or write the repository, access the network, or dispatch agents.

Learn and evolve with your project

LeanPowers has an opt-in, project-local feedback loop. When a later message explicitly says that a previous result worked or failed, corrects an earlier conclusion, or states a durable project preference, adapt turns that feedback into one narrow reusable lesson. A future relevant workflow can then retrieve up to three lessons matched by workflow, path, and tags, incorporating relevant project context without loading a growing conversation history.

Enable LeanPowers learning for this project.

"The earlier cache fix failed because tenant scope was checked too late."
→ adapt records a scoped correction for the relevant code and workflow.

"That retry policy worked in production. Keep it for this client."
→ adapt records or reinforces a durable project rule.

Additional distinct support reinforces an existing lesson; an explicit correction can supersede an obsolete one. Lessons may expire, and you can inspect, forget, clear, disable, or permanently delete them. Silence, thanks, ordinary continuation, one-time authorization, and the Agent's own self-assessment are never treated as learning evidence.

Learning is disabled by default. When enabled, the bundled Node.js helper stores a project-local .leanpowers/ ledger and adds it only to Git's local info/exclude; it never edits the tracked .gitignore. The ledger contains normalized rules and bounded evidence summaries—not raw chats, full prompts, command logs, stack traces, secrets, credentials, or unrelated repository content.

Retrieved lessons are advisory and can never lower authorization, scope, risk, root-cause, regression-evidence, independent-review, or completion-evidence gates. There is no background activity, network access, telemetry, global user profile, or cross-project sharing. Node.js 20+ is needed only after learning is explicitly enabled.

How LeanPowers works

LeanPowers is dynamic, not a fixed pipeline. route reads the task and observable risk, then activates exactly one owning workflow. It transitions only when new evidence requires it: an unknown cause moves work to debug, strict risk adds independent review, and stale or delivery-bound evidence moves through verify before ship. The full chain is never loaded by default.

flowchart LR
    T["Engineering task"] --> R["route"]
    R --> W["One lowest-safe workflow"]
    W --> E{"Evidence changes?"}
    E -->|"No"| C["Complete"]
    E -->|"Unknown cause"| D["debug"]
    E -->|"Strict risk"| V["independent review"]
    E -->|"Stale or delivery-bound"| S["verify → ship"]
    F["Explicit later feedback"] --> A["adapt"]
    A --> L["Project-local lessons"]
    L -. "up to 3 relevant rules" .-> W

Loading

Quick start

LeanPowers can route from the task, or you can invoke a skill explicitly.

# Codex
$leanpowers:route Choose the lightest safe workflow for this engineering task.
$leanpowers:build mode=lean Add the missing validation and its regression test.
$leanpowers:debug The integration test is intermittently returning an empty result.
$leanpowers:verify Prove this branch is ready to deliver.
$leanpowers:adapt Enable LeanPowers learning for this project.

# Claude Code
/leanpowers:route Choose the lightest safe workflow for this engineering task.
/leanpowers:shape mode=standard Design a backward-compatible pagination change.
/leanpowers:review Review this diff against the stated acceptance criteria.
/leanpowers:ship Push the verified branch and open the requested pull request.
/leanpowers:adapt What has LeanPowers learned in this project?

mode=auto is the default. mode=lean, mode=standard, and mode=strict request a workflow preference; safety, authorization, scope, and evidence gates can still raise the rigor.

Who LeanPowers is for

LeanPowers is a good fit when you:

• use Codex, Claude Code, or another Agent Skills-compatible runtime for real repository work;
• want proportionate regression checks, root-cause debugging, review, verification, and safe delivery without a mandatory long chain;
• prefer one risk-appropriate workflow over an always-on multi-agent framework;
• want project learning to be explicit, local, inspectable, and off by default.

It is probably not the right fit if you want a fully autonomous orchestration service, mandatory multi-agent execution for every task, or cloud-hosted cross-project memory.

The six engineering workflows

Skill	Use it for	Primary output
shape	Material ambiguity, scope, architecture, acceptance criteria	Executable brief; delivery slices when needed
build	Features, known-cause fixes, refactors, config, docs	Implemented slices with targeted evidence
debug	Unknown, intermittent, or disputed failures	Reproduction, falsifiable hypothesis, root cause, repair proof
review	Independent correctness and risk assessment	Findings-first verdict with evidence and severity
verify	Completion, safety, installability, or readiness claims	Claim-to-command evidence and explicit gaps
ship	Commit, push, PR, package, release, or handoff	Destination readback for the delivered revision

route and adapt are control-plane Skills, not extra engineering stages. route chooses the current workflow; adapt changes future behavior from verified feedback. Together they keep the engineering path dynamic without turning learning into another mandatory ceremony.

Routing and modes

LeanPowers starts with one workflow and transitions only when evidence requires it.

Mode	Typical signals	Default path
lean	Clear, local, reversible, established validation	build → complete with current applicable evidence; otherwise verify
standard	Normal feature, multi-file behavior, bounded uncertainty	shape(light, if unclear) → build/debug → complete with current applicable evidence; otherwise verify
strict	Security—including authentication, credentials/secrets, cryptography, or signature verification—authorization, payment, privacy, migration, concurrency, production, irreversible change	shape(full, if unclear) → build/debug → independent review → complete with unchanged current evidence; otherwise verify → ship(if requested)

When signals disagree, the highest-risk signal wins. Unknown classification falls back to standard. A failed check, widened scope, unknown cause, public boundary change, or high-severity review finding upgrades the workflow.

Examples:

• Rename a private helper with an existing test path: lean.
• Add a normal multi-file feature: standard, with review when the boundary warrants it.
• Fix an unexplained production authorization failure: strict, starting in debug.
• Review only: start and stop in review unless the user requests repairs.
• Deliver a pull request: current verify evidence, then ship and remote readback.

Quality without ritual

These gates never disappear, regardless of mode:

1. No completion claim without current evidence.
2. Unknown failures require root-cause diagnosis before a repair claim.
3. Behavior changes require appropriate regression evidence.
4. Work stays inside the declared scope.
5. High-risk changes receive an independent review.
6. Destructive, irreversible, credential-gated, or production actions require authorization.
7. New contradictory evidence triggers re-evaluation.
8. Material validation gaps are reported explicitly.

Evidence is keyed to the relevant revision and scope. Unchanged evidence may be reused; affected evidence is invalidated after code, configuration, dependency, generated-output, or environment changes.

Runtime behavior

Capability	Codex	Claude Code	Generic Agent Skills runtime
Six engineering workflows + route/adapt control Skills	Yes	Yes	Yes
Startup injection	None	Compact routing charter	None assumed
Optional reviewer/verifier agents	Runtime-native task prompts	Packaged agents	Single-agent execution; strict review must come from an external perspective
Core quality gates	Yes	Yes	Yes

Codex retains zero startup injection and discovers the 167-word route Skill through native metadata. Claude Code receives one 98-word, read-only routing hint that is restored after startup, clear, or compaction; it does not inspect .leanpowers/, scan or write the repository, access the network, or dispatch agents. The six engineering workflows require no Node.js runtime. The optional learning helper requires Node.js 20+ only when learning is explicitly enabled.

Privacy and security

• No telemetry or analytics.
• No repository scan or network access from the Claude startup hook.
• Learning is off by default and state never leaves the current project.
• Enabled learning stores normalized rules and bounded evidence summaries, never raw chats, secrets, environment values, or full logs.
• Full command output stays local; bounded summaries enter the model context.

Agent instructions are not a security boundary. Review commands and diffs before authorizing destructive, production, or credential-sensitive actions. See SECURITY.md.

Compared with Superpowers 6.1.1

LeanPowers carries forward Superpowers' evidence-first engineering principles while consolidating 13 engineering-workflow concerns into six risk-activated workflows. The six engineering SKILL.md files total 2,189 words—88.2% fewer than the 14-file Superpowers 6.1.1 comparison set. Adding route (167 words) and adapt (329 words) brings all eight LeanPowers Skills to 2,685 words, still 85.5% smaller.

This is a lineage-and-tradeoff comparison, not a winner ranking. Superpowers remains the upstream inspiration and a comprehensive workflow reference; LeanPowers tests whether the outcome-critical safeguards can be retained with a smaller, risk-adaptive control surface. The retained safeguards, different optimization choices, evidence limits, and balanced conclusion are documented in docs/comparison-superpowers.md. If you are migrating, read docs/migration.md—do not enable both systems as automatic workflow routers in the same session.

Evidence and benchmark

LeanPowers publishes paired live coding runs, preregistrations, post-run audits, neutral and workflow-home model/tool compatibility preflights, sanitized pre-task failure records, and a reproducible comparator. Structural reduction is verified; live development results remain bounded evidence rather than a universal parity or speed claim. Detailed commands, scores, limitations, and every frozen historical conclusion stay in the benchmark protocol instead of the product overview.

The latest scored evidence remains V7. The authorized V8 attempt failed before any task run with a model/tool preflight error, so it is UNSCORED and ineligible for comparative decisions; see the V8 unscored audit.

The comparator accepts paired result documents conforming to schemas/benchmark-result.schema.json:

node scripts/benchmark.mjs compare \
  --baseline path/to/superpowers-live.json \
  --candidate path/to/leanpowers-live.json \
  --out path/to/report

A release-eligible result must use complete, live, blind, identically paired runs. For the full evidence record, see the benchmark method and status, latest v7 scored result, v7 post-run audit, and complete Superpowers comparison.

Project map

Path	What you will find
skills/	Canonical route, shape, build, debug, review, verify, ship, and adapt Skills
references/	Shared risk, evidence, learning, transition, and strict-review policies
plugins/	Generated Codex and Claude Code packages; do not edit by hand
docs/	Architecture, migration, comparison, benchmarks, and implementation records
tests/	Structural, behavioral, generator, packaging, and learning tests

Start with the architecture, see the latest usage-driven optimization plan, read the migration guide if you use Superpowers, and see CONTRIBUTING.md for local development and pull requests. Security and privacy boundaries are documented in SECURITY.md.

Development

Development prerequisites: Git and Node.js 20 or 22. Installed engineering workflows have no runtime dependencies; Node.js 20+ is used only by explicitly enabled project learning.

npm run generate         # rebuild both committed runtime packages
npm run generate:check   # fail if generated packages drift
npm run validate:quick   # fast inner loop: package checks and core regressions
npm test                 # run every Node test
npm run validate         # full release gate: sync, structure, budgets, and all tests
npm run build            # create validated release artifacts in dist/

Canonical sources live in metadata/, skills/, references/, agent-specs/, and adapters/. Do not edit plugins/ by hand; regenerate it. Contribution rules are in CONTRIBUTING.md.

Questions and concrete failure cases are welcome in GitHub Issues. If LeanPowers makes your agent workflow clearer without making it heavier, Star LeanPowers so more builders can find it.

License

MIT