software-leverage-points
Skills for reviewing software through leverage-point lenses (testing, logging, architecture, dependencies, security, and more). Includes an
Open source Open in the app JSON README (API)
About
Skills for reviewing software through leverage-point lenses (testing, logging, architecture, dependencies, security, and more). Includes an orchestrator that fans out parallel subagents per leverage point during planning, code review, and codebase audit.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- syntropic137
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.4
- Open pull requests
- 2
- Last push
- 2026-08-29T20:26:27Z
- Repository state
- ativo
- Language
- Python
- License
- NOASSERTION
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
syntropic137/software-leverage-points
README
# software-leverage-points
A Claude Code plugin that ships a library of skills for reviewing software through high-leverage lenses: testing, logging, architecture, dependencies, security, configuration, types, documentation, and more. Each lens is its own skill, and an orchestrator (`software-leverage-review`) fans out parallel subagents (one per lens) to review a plan, a PR, or a whole codebase.
> **Read first:** [`VISION.md`](VISION.md) - canonical statement of what this plugin is for, the end state, the severity-action policy, and the acceptance tests that define "done."
## Mental model: a mixture of experts on software design
Most software-quality reviews are single-pass: one agent reads a plan or a diff and tries to weigh every concern at once. That is where issues slip through. Cross-cutting concerns (DRY, complexity, separation of scope) get washed out by domain ones (a missing test, an over-mocked integration, an unpinned dependency).
This plugin treats each high-leverage concern as its own meta-skill, so an autonomous agent can invoke a *committee of experts* in parallel and synthesize the findings:
- **Plan-time gate.** Before implementation begins, fan out the lenses against the plan document. Each lens flags issues from its perspective. The author either revises the plan or proceeds with the issues acknowledged.
- **PR-time gate.** After implementation, fan out against the diff. Each lens flags issues that should block, warn, or inform.
- **Codebase audit.** Run periodically against the whole repo to surface drift and accumulated debt.
This plugin is self-contained and has no runtime dependency on other plugins. It focuses purely on the *what to review*: each leverage point is its own lens, and the orchestrator fans them out in parallel.
### L1 to L2 to L3 flow
The plugin separates generic principles (L1) from repo-specific calibration (L2) from active reviews (L3). `skill-builder` is the bridge that reads L1 and inspects the target to produce L2; `software-leverage-review` runs L3 by fanning subagents against L2; `skill-auditor` watches L2 for drift and feeds updates back.
```mermaid
flowchart TD
subgraph L1[L1: Plugin generic skills]
M[SLPs + operator skills]
R[lens reference docs]
end
subgraph L2[L2: Repo-specific skills, generated]
L2S[L2 SKILL.md with<br/>Maturity Assessment +<br/>Growth Direction +<br/>Calibrated checks]
end
subgraph L3[L3: Active reviews]
SLR[software-leverage-review<br/>fans out N subagents]
SUB[Subagent: applies L2 skill,<br/>severity-calibrated to maturity]
end
M -->|skill-builder reads L1,<br/>inspects target repo| L2S
L2S -->|invoked by| SLR
SLR --> SUB
SUB --> Findings
Findings -->|skill-auditor detects drift,<br/>updates Maturity Assessment| L2S
```
### What lives in each layer
The three layers do three distinct jobs. Keeping the boundary clean is what makes the orchestrator's output trustworthy.
**L1 (meta-skill).** Ships in this plugin under `skills/<lp>/SKILL.md`. Repo-agnostic statements of "what good looks like" for one leverage point: principles, red flags, references. L1 cites books and named practitioners; it does not know about any specific repo.
**L2 (repo-specific skill).** `skill-builder` reads an L1 and inspects a target repo, then writes an L2 to that repo's `.claude/skills/<lp>/SKILL.md`. The L2 is a *context document about this repo's stance on this leverage point*: what conventions are in place, what the maturity rating is, what is deliberately deferred, what gaps are known. The L2 is NOT a self-contained reviewer; it does not emit findings or assign severity.
**Orchestrator (L3 runtime).** `software-leverage-review` is the only thing that emits review findings. At review time it composes L1 (principles) + L2 (repo context) + a target (plan, PR, or diff), fans out parallel subagents, and produces severity-tagged findings (`error` / `warn` / `info`). Severity is assigned by the orchestrator, using the maturity rating from L2 as a calibration input.
**Why this division matters.** Severity language belongs only in orchestrator output. The same observation in an L2 may yield `error` against a production codebase and `info` against a POC; the L2 records the observation, the orchestrator picks the severity. An L2 SKILL.md that contains `error` / `warn` / `info` bullets is a category error: it confuses "the conditions under which severity applies" with "the act of assigning severity to a specific change."
Who owns what:
- **L1:** principles, red flags, citations. Repo-agnostic. Hand-authored.
- **L2:** repo context, maturity rating, growth direction, local conventions, known gaps. Generated by `skill-builder`. No severity.
- **Orchestrator (L3 runtime):** findings with severity. Generated per review.
- **`skill-auditor`:** drift detection between L2 and the repo's current state. No severity.
## Credit
Multi-vendor scaffolding patterns (directory layout, manifest mirroring across Claude Code, Codex, Cursor, OpenCode, and Gemini) adapted from [obra/superpowers](https://github.com/obra/superpowers). We track superpowers as a git `upstream` remote so we can selectively pull scaffolding improvements over time. Skills, agents, and commands are entirely our own, and there is no runtime dependency on superpowers.
## Install
This README is the explanation layer: mental model, rationale, and install instructions. The reference inventory of all shipped skills lives in `docs/leverage-points.md`. How-to guides for individual skills live in each skill's own `SKILL.md`. The split follows Diátaxis (explanation, how-to, reference) so each document has one job.
### Claude Code
**From GitHub (marketplace):**
```bash
claude plugin marketplace add syntropic137/software-leverage-points && claude plugin install software-leverage-points
```
**From local clone (development):**
```bash
claude plugin install /absolute/path/to/software-leverage-points --scope project
```
See [`docs/local-testing.md`](docs/local-testing.md) for the full local-development loop (persistent install, ephemeral install, `/reload-plugins`).
### Other vendors
- Codex: [`docs/README.codex.md`](docs/README.codex.md)
- OpenCode: [`docs/README.opencode.md`](docs/README.opencode.md)
- Cursor: `.cursor-plugin/plugin.json` describes the plugin to Cursor's plugin loader
- Gemini: `gemini-extension.json` registers the extension
### Updating
```bash
claude plugin marketplace update software-leverage-points
claude plugin update software-leverage-points@syntropic137
```
Refreshing the marketplace catalog before the plugin update ensures the cache has the latest release before the install runs.
## Skills
The shipped skills are leverage-point skills, operator skills, and lens reference docs. Detailed status and file paths live in `docs/leverage-points.md`. When invoked through a vendor's plugin discovery, skills are namespaced (e.g., `/software-leverage-points:testing`).
### Leverage-point skills
Each leverage-point skill reviews a codebase, plan, or PR through one high-leverage lens. The list below is auto-generated; for the canonical reference doc with status flags and lens references, see `docs/leverage-points.md`.
<!-- begin:readme-slp-catalog -->
- **[architecture](skills/architecture/SKILL.md)**: Use when reviewing architectural concerns: module boundaries, dependency direction, layer discipline, bounded-context isolation, ADR coverage, premature abstraction, and structural fitness for change
- **[configuration](skills/configuration/SKILL.md)**: Use when reviewing configuration concerns: env-var layering, typed config objects, startup validation, secret/non-secret separation, schema discoverability, environment-dependent defaults, twelve-factor compliance, magic numbers
- **[continuous-delivery](skills/continuous-delivery/SKILL.md)**: Use when reviewing delivery concerns: DORA four key metrics, pre-merge gating, trunk-based development, fast feedback, single-artifact promotion, health-gated deploys, automated rollback, deploy/release decoupling via feature flags, deploy frequency, runbook freshness, deploy-credential scoping, pipeline bottleneck visibility, supply-chain attestation
- **[dependencies](skills/dependencies/SKILL.md)**: Use when reviewing dependency concerns: lockfile health, version pinning, immutable references, maintenance signals, transitive audit gates, monorepo version skew, reviewable lockfiles, license posture
- **[developer-experience](skills/developer-experience/SKILL.md)**: Use when reviewing developer-experience concerns: single-command onboarding (contributors and end-users), inner-loop speed, task-runner discoverability, recipe-as-thin-wrapper discipline, error-message actionability, formatter/linter automation, AI-agent ergonomics, reproducible local environment, parallel-worktree dev stacks
- **[documentation](skills/documentation/SKILL.md)**: Use when reviewing documentation concerns: README presence and quality, public API documentation, ADR coverage for non-obvious decisions, inline rationale comments, TBD/placeholder hygiene in shipped docs
- **[dry](skills/dry/SKILL.md)**: Use when reviewing DRY concerns: knowledge-vs-text duplication, repeated business rules across boundaries, magic constants, configuration duplication, copy-pasted test fixtures, premature abstraction risk, rule-of-three for extraction
- **[environments](skills/environments/SKILL.md)**: Use when reviewing environment concerns: dev/staging/prod parity, declarative environment manifests, build vs runtime separation, environment promotion path, secret-loader parity across environments, reproducible local setup, ephemeral / preview environments per PR with auto-teardown, data parity (shape-realistic seed and anonymized prod copies), mechanically enforced parity rules
- **[error-handling](skills/error-handling/SKILL.md)**: Use when reviewing error-handling concerns: error taxonomy, propagation discipline, swallow-vs-crash, retry semantics with backoff and idempotency, exit codes as API, error messages as contract, cause-chain preservation
- **[logging](skills/logging/SKILL.md)**: Use when reviewing logging concerns: structured-vs-unstructured logs, log-level policy, secret and PII redaction, correlation IDs in distributed systems, log/trace linkage, print statements in production code paths
- **[principles-and-patterns](skills/principles-and-patterns/SKILL.md)**: Use when reviewing cross-cutting design principles: SOLID applicability, separation of concerns, dependency direction, composition vs inheritance, coupling and cohesion, OO-vs-functional style consistency, pattern enforcement style, project-level bounded-context coupling
- **[purpose-and-scope](skills/purpose-and-scope/SKILL.md)**: Use when reviewing purpose-and-scope concerns: stated project purpose, declared in-scope and out-of-scope, non-goals, plan-purpose alignment, scope-creep within a single change, project-level bounded contexts, dependency-purpose linkage
- **[security](skills/security/SKILL.md)**: Use when reviewing security concerns: secrets in code, SAST coverage, input validation, authn/authz boundaries, sensitive-data handling, dependency CVEs, SSRF, hand-rolled escaping, threat modeling for high-stakes changes, defense in depth, agentic-AI / LLM tool-call attack surface (prompt injection, indirect injection, MCP abuse)
- **[software-complexity](skills/software-complexity/SKILL.md)**: Use when reviewing software complexity concerns: cognitive load, cyclomatic and cognitive complexity bounds, deep-vs-shallow modules, accidental coupling, premature abstraction, asymmetric simplicity, comments-explain-why
- **[testing](skills/testing/SKILL.md)**: Use when reviewing testing concerns: pyramid coverage (unit, integration, E2E), test code quality, TDD discipline, regression discipline, FIRST principles, feedback-loop speed
- **[types](skills/types/SKILL.md)**: Use when reviewing type-system concerns: type-coverage in public APIs, primitive obsession vs refinement, runtime validation at trust boundaries, soundness gaps and escape hatches, narrow vs wide types, strict-mode discipline
- **[versioning](skills/versioning/SKILL.md)**: Use when reviewing versioning concerns: declared scheme (semver/calver/ZeroVer), changelog hygiene, deprecation policy and migration paths, public-API stability classification, version-bump automation, manifest-drift across multiple files, release process (cut-a-release flow, release branches, release gates)
<!-- end:readme-slp-catalog -->
### Layers
- **L1 (meta-skills):** generic skills that ship in this plugin. Repo-agnostic.
- **L2 (repo skills):** skills that `skill-builder` generates inside a target repo's `.claude/skills/`, customized for that repo's stack and conventions.
- **L3 (active reviews):** the orchestrator's runtime: parallel subagents reviewing a target through every lens.
## Authoring style
Each leverage-point skill is more than a checklist. It cites the canonical references for the concern (books, ADR patterns, named thinkers) and explains *why* each red flag matters. The intent is for an agent reading the skill to operate with the same reasoning a senior engineer would, not just pattern-match.
Examples:
- The `testing` skill cites Beck (Test-Driven Development), Khorikov (Unit Testing Principles), and surfaces the integration-vs-mock discipline distinction.
- The `architecture` skill cites Brooks (No Silver Bullet), Fowler (Patterns of Enterprise Application Architecture), and asks for ADRs.
- The `types` skill cites Hejlsberg, Ousterhout (A Philosophy of Software Design), and asks how the type system is being used as documentation.
## Local development
```bash
git clone https://github.com/syntropic137/software-leverage-points
cd software-leverage-points
claude plugin install $(pwd) --scope project
```
See [`docs/local-testing.md`](docs/local-testing.md) for the full development loop.
## Project rules
See `CLAUDE.md` for the rules contributors and agents should follow when editing this plugin.
## License
MIT. See `LICENSE`. Scaffolding patterns adapted from `obra/superpowers` (also MIT).