Skip to content

btmoriarty/algol / skills/algol

Govern code review for a project instead of performing it. Triggers when setting up or running Algol, defining or compiling review policy in .algol/policy.toml, routing a change to the right review engine by policy and undo-cost, reconciling findings from the deterministic collectors, SARIF scanners, policy-review, gauntlet, or the composed verifiers into one record, or recording a review decision with reopens-if conditions. Not a reviewer itself.

Algol

Govern what gets reviewed and record what was decided. Algol reviews nothing itself.

Algol reads a project's versioned review standards, routes each change to the right engine per policy and undo-cost, reconciles every engine's findings into one record, never upgrading a heuristic to verified without notice, and preserves each human decision with the conditions that would reopen it.

v0.16.0, local scope. See docs/DESIGN.md for the full design and each references/ file for a component's protocol.

The pieces

  • Policy model: versioned, path-scoped standards in .algol/policy.toml, compiled into review instructions, scanner rules, routing criteria, and a catalog. tools/compile_policy.py, references/policy-model.md.
  • Starter policy + init: tools/init.py drops the shipped strong default (starter-policy.toml), which routes the high-undo-cost surfaces (auth, migrations, money, public API, infra, CI) out of the box, so a cold first run is useful before any tuning. references/policy-model.md.
  • Evidence collectors: seclint (security) and brevlint (style and brevity), deterministic, emitting structured evidence rows. They are the silent floor: a finding from collectors alone is labeled floor and demoted in presentation, never shown as a peer of a real engine's finding. tools/seclint.py, tools/brevlint.py, references/collectors.md.
  • policy-review: a model-pass harness that checks a change against the project's own standards, not a general bug hunt. tools/policy_review.py, references/policy-review.md.
  • router: recommends skip, a collector, policy-review, /code-review, or ultra from policy and undo-cost, and escalates to the deep tier on undo-cost. --format commands emits a copy-pasteable command per recommendation and stays silent on a low-risk change. Recommends, never auto-launches. tools/router.py, references/router.md.
  • reconcile and the record: merges findings into one governed record, keeps verified distinct from heuristic, never upgrades without notice, carries reopens-if on each disposition. It reads collector and SARIF rows, policy-review output, a gauntlet run record, and evidence-locked-uat and applying-formal-rigor results. /code-review and ultra have no adapter yet; their findings enter as hand-written evidence rows (rule_id code-review/<slug>) at heuristic. tools/reconcile.py, tools/record.py, references/reconcile-and-record.md.
  • decide: records a human disposition on a finding by id, requires one to three reopens-if conditions (or an explicit --no-reopens), and appends a timestamped event to events.jsonl. tools/decide.py, references/reconcile-and-record.md.
  • verify: a targeted, one-finding loop to raise a finding's tier through the verifying engine (uat FAIL reaches verified; gauntlet reaches model_corroborated). prompt assembles the request; ingest folds it in and reports the tier change. tools/verify.py, references/verify.md.
  • SARIF ingest: converts any standard tool's SARIF output (CodeQL, Semgrep, bandit, gitleaks, ruff) into evidence rows reconcile takes through --collector, with the tool name as the finding's source. tools/sarif_adapter.py, references/sarif-ingest.md.
  • The per-change gate: changed.py names a change's files from git; gate.py routes the change, runs the collectors on just those files, and reconciles into the record so prior dispositions survive and only new findings surface. tools/changed.py, tools/gate.py, references/pr-gate.md.
  • Deep tier: routes to gauntlet and consumes its run record. tools/gauntlet_adapter.py, references/deep-tier.md.
  • Composed axes: testing to evidence-locked-uat, efficiency to applying-formal-rigor. tools/compose_adapter.py, references/composition.md.
  • Hooks: a non-modifying reversibility guard and a collector reporter. tools/hooks.py, references/hooks.md.

The floor

The tool proposes; a human decides and runs the engine. No finding originates in Algol except the deterministic collector rows. A heuristic is never upgraded to verified without notice.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall