{
  "markdown": "# software-leverage-points\n\nA 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.\n\n> **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.\"\n\n## Mental model: a mixture of experts on software design\n\nMost 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).\n\nThis 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:\n\n- **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.\n- **PR-time gate.** After implementation, fan out against the diff. Each lens flags issues that should block, warn, or inform.\n- **Codebase audit.** Run periodically against the whole repo to surface drift and accumulated debt.\n\nThis 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.\n\n### L1 to L2 to L3 flow\n\nThe 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.\n\n```mermaid\nflowchart TD\n    subgraph L1[L1: Plugin generic skills]\n        M[SLPs + operator skills]\n        R[lens reference docs]\n    end\n\n    subgraph L2[L2: Repo-specific skills, generated]\n        L2S[L2 SKILL.md with<br/>Maturity Assessment +<br/>Growth Direction +<br/>Calibrated checks]\n    end\n\n    subgraph L3[L3: Active reviews]\n        SLR[software-leverage-review<br/>fans out N subagents]\n        SUB[Subagent: applies L2 skill,<br/>severity-calibrated to maturity]\n    end\n\n    M -->|skill-builder reads L1,<br/>inspects target repo| L2S\n    L2S -->|invoked by| SLR\n    SLR --> SUB\n    SUB --> Findings\n    Findings -->|skill-auditor detects drift,<br/>updates Maturity Assessment| L2S\n```\n\n### What lives in each layer\n\nThe three layers do three distinct jobs. Keeping the boundary clean is what makes the orchestrator's output trustworthy.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\"\n\nWho owns what:\n\n- **L1:** principles, red flags, citations. Repo-agnostic. Hand-authored.\n- **L2:** repo context, maturity rating, growth direction, local conventions, known gaps. Generated by `skill-builder`. No severity.\n- **Orchestrator (L3 runtime):** findings with severity. Generated per review.\n- **`skill-auditor`:** drift detection between L2 and the repo's current state. No severity.\n\n## Credit\n\nMulti-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.\n\n## Install\n\nThis 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.\n\n### Claude Code\n\n**From GitHub (marketplace):**\n\n```bash\nclaude plugin marketplace add syntropic137/software-leverage-points && claude plugin install software-leverage-points\n```\n\n**From local clone (development):**\n\n```bash\nclaude plugin install /absolute/path/to/software-leverage-points --scope project\n```\n\nSee [`docs/local-testing.md`](docs/local-testing.md) for the full local-development loop (persistent install, ephemeral install, `/reload-plugins`).\n\n### Other vendors\n\n- Codex: [`docs/README.codex.md`](docs/README.codex.md)\n- OpenCode: [`docs/README.opencode.md`](docs/README.opencode.md)\n- Cursor: `.cursor-plugin/plugin.json` describes the plugin to Cursor's plugin loader\n- Gemini: `gemini-extension.json` registers the extension\n\n### Updating\n\n```bash\nclaude plugin marketplace update software-leverage-points\nclaude plugin update software-leverage-points@syntropic137\n```\n\nRefreshing the marketplace catalog before the plugin update ensures the cache has the latest release before the install runs.\n\n## Skills\n\nThe 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`).\n\n### Leverage-point skills\n\nEach 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`.\n\n<!-- begin:readme-slp-catalog -->\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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\n- **[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)\n- **[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\n- **[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\n- **[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\n- **[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)\n<!-- end:readme-slp-catalog -->\n\n### Layers\n\n- **L1 (meta-skills):** generic skills that ship in this plugin. Repo-agnostic.\n- **L2 (repo skills):** skills that `skill-builder` generates inside a target repo's `.claude/skills/`, customized for that repo's stack and conventions.\n- **L3 (active reviews):** the orchestrator's runtime: parallel subagents reviewing a target through every lens.\n\n## Authoring style\n\nEach 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.\n\nExamples:\n- The `testing` skill cites Beck (Test-Driven Development), Khorikov (Unit Testing Principles), and surfaces the integration-vs-mock discipline distinction.\n- The `architecture` skill cites Brooks (No Silver Bullet), Fowler (Patterns of Enterprise Application Architecture), and asks for ADRs.\n- The `types` skill cites Hejlsberg, Ousterhout (A Philosophy of Software Design), and asks how the type system is being used as documentation.\n\n## Local development\n\n```bash\ngit clone https://github.com/syntropic137/software-leverage-points\ncd software-leverage-points\nclaude plugin install $(pwd) --scope project\n```\n\nSee [`docs/local-testing.md`](docs/local-testing.md) for the full development loop.\n\n## Project rules\n\nSee `CLAUDE.md` for the rules contributors and agents should follow when editing this plugin.\n\n## License\n\nMIT. See `LICENSE`. Scaffolding patterns adapted from `obra/superpowers` (also MIT).\n",
  "bytes": 14195,
  "sha": "d75f36c2c4be8299d933a6cc8e527aa215ab8eb8424acd1463bb14fba6797d9f",
  "repo_slug": "syntropic137/software-leverage-points",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_syntropic137_software_leverage_points_7273e44c/readme"
}