{"id":50965350,"url":"https://github.com/fmind/agent-levers","last_synced_at":"2026-06-18T19:33:22.139Z","repository":{"id":354509393,"uuid":"1223462694","full_name":"fmind/agent-levers","owner":"fmind","description":"Levers for AI coding agents (Claude Code, Gemini CLI, GitHub Copilot, OpenCode) — multiply the agent's force, divide the human's effort.","archived":false,"fork":false,"pushed_at":"2026-05-31T17:32:59.000Z","size":483,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T15:41:45.510Z","etag":null,"topics":["agent-skills","agentic-coding","agy","antigravity","antigravity-cli","claude-code","gemini-cli","gemini-cli-extension","github-copilot","levers","opencode","workflow"],"latest_commit_sha":null,"homepage":"https://fmind.github.io/agent-levers/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-28T10:51:28.000Z","updated_at":"2026-05-31T17:33:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fmind/agent-levers","commit_stats":null,"previous_names":["fmind/fgate","fmind/agent-levers"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fmind/agent-levers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-levers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-levers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-levers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-levers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmind","download_url":"https://codeload.github.com/fmind/agent-levers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-levers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34505420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agentic-coding","agy","antigravity","antigravity-cli","claude-code","gemini-cli","gemini-cli-extension","github-copilot","levers","opencode","workflow"],"created_at":"2026-06-18T19:33:21.144Z","updated_at":"2026-06-18T19:33:22.115Z","avatar_url":"https://github.com/fmind.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Levers\n\n[![CI](https://github.com/fmind/agent-levers/actions/workflows/ci.yml/badge.svg)](https://github.com/fmind/agent-levers/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Claude Code](https://img.shields.io/badge/Claude%20Code-supported-D97706)](https://github.com/anthropics/claude-code) [![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-supported-4285F4)](https://github.com/google-gemini/gemini-cli) [![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-supported-181717)](https://github.com/features/copilot) [![OpenCode](https://img.shields.io/badge/OpenCode-supported-059669)](https://opencode.ai)\n\n\u003e **Multiply the agent's force, divide the human's effort.**\n\u003e\n\u003e ![A small human leans on one end of a lever, easily lifting a towering AI agent and stacks of code panels on the other end.](./hero.jpg)\n\nAgent Levers is a workflow toolkit for AI coding agents. It ships as a small set of Agent Skills — file-based, harness-agnostic — that bring structure (plan → do → check → act) to any non-trivial coding task. The same `skills/` tree runs in Claude Code, Gemini CLI, GitHub Copilot, and OpenCode.\n\n## Why this exists\n\nA coding agent is only as useful as the spec you give it.\n\n- Type too little → the agent hallucinates intent, drifts, ships the wrong thing.\n- Type too much → you become the bottleneck, doing the agent's homework.\n\nAgent Levers flips the balance. You put in the minimum; the agent carries the weight — clarifying, planning, executing, verifying, learning.\n\n## What you get\n\n- **Pass means it actually works.** Every criterion ships a typed `verify:` (shell / visual / manual). `check` re-runs them from a fresh shell as ground truth — exit-zero, not \"the agent said so.\"\n- **Scope you can audit before code lands.** A one-line ask becomes a numbered acceptance list (`C1 … Cn`), each with its own verifier. `check`'s chain audit catches drift between brief, plan, and diff — beyond what unit tests can see.\n- **Runaway loops, bounded.** `do` runs inside an explicit `budget:` (iterations, minutes, failed-streak). When it hits the wall, it pauses with `pause: blocked` and full state on disk — raise the cap, hand off, or resume; prior passes stay green.\n- **One artifact, the whole story.** `LEVER.md` opens with a `TL;DR` rewritten on every step — outcome, coverage, decisions, what's next. Half a day of agent work, audited in 20 lines.\n- **Resume across sessions.** State lives in `lever.yaml` + `LEVER.md`, not the agent's context. Close the laptop mid-`do`, re-run `/lever \u003cid\u003e` tomorrow — the chain reads the files and picks up.\n- **Lessons compound, lever to lever.** When `act` spots a recurring gap, it stages a reviewable diff to your `AGENTS.md` or recommends a follow-up `/lever-new`. The next lever inherits the rule, not the mistake.\n- **Install once, use anywhere.** The same `skills/` tree drives Claude Code, Gemini CLI, and GitHub Copilot. No fork, no port.\n\n## The four commands\n\n- **`/lever-init`** — Bootstrap a fresh repo. Creates `.agents/levers/`, wires `CLAUDE.md` / `GEMINI.md` to import `AGENTS.md`, prints an `AGENTS.md` skeleton if one is missing.\n- **`/lever-new \u003ctitle\u003e`** — Start a new lever. First turn is chat-only — clarifying questions, proposed enhancements, draft brief inline. On agreement, captures `LEVER.md` §Brief and seeds `lever.yaml` with `step: plan`.\n- **`/lever \u003cid-or-slug\u003e`** — Advance the lever chain. Default: runs autonomously until paused (`pause` set) or finished (`step: done`). The chain steps themselves (`plan`, `do`, `check`, `act`) aren't user-facing — the dispatcher loads the matching `skills/lever/references/\u003cstep\u003e.md` on demand.\n- **`/lever-status [\u003cid-or-slug\u003e]`** — List levers (no args), inspect one (TL;DR + criteria summary + per-criterion events timeline), or cancel one with `\u003cid\u003e cancel [\u003creason\u003e]`. Read-only by default — never advances the chain.\n\nTwo contracts hold the framework together:\n\n- **Checklist contract** — every criterion in `lever.yaml.criteria` carries a stable `id`, a typed `verify:` block (shell / visual / manual), and a `passes: false` flag. Do flips it on success; check re-runs it as ground truth. Do runs inside `lever.yaml.budget` (iterations, minutes, streak) so runaways stop cleanly.\n- **Chaining contract** — `lever.yaml.step` is the single state pointer (`plan | do | check | act | done | cancel`); the optional `lever.yaml.pause` (`ask | blocked`) is set only when the chain is halted at `step` waiting for the user, and only ever at `step: plan` or `step: do`. Check and act always advance, route back, or finish — they never pause. The dispatcher reads `(step, pause)` to route the next action; the chat reply communicates the same state in plain language.\n\n## Walkthrough\n\nTwo human inputs drive a complete lever, in two separate sessions.\n\n**Session 1 — capture intent.**\n\n```text\n$ /lever-new add password sign-in\n  → first turn: chat-only — clarifying questions, proposed enhancements, draft brief inline\n  → on agreement: creates .agents/levers/1-add_password_sign_in/\n  → writes LEVER.md (TL;DR + §Brief) and lever.yaml seed (lever_id, slug, step: plan)\n  → \"Brief captured; lever.yaml + LEVER.md written. In a new session, run /lever 1 to start the chain.\"\n```\n\n`/lever-new` doesn't invoke `/lever` itself — brief-time conversation is high-context and human-driven; chain execution is mechanical and reads from files. Each session does one thing well.\n\n**Session 2 — run the chain.**\n\n```text\n$ /lever 1\n  → fresh session. dispatcher reads lever.yaml.step (plan), runs the chain autonomously\n  → plan: investigates codebase, populates lever.yaml.criteria + budget, appends LEVER.md §Plan; advances to step: do\n  → do: executes the plan inside lever.yaml.budget; appends per-event rows to lever.yaml.criteria[i].events; flips per-criterion passes; on green appends LEVER.md §Do; advances to step: check\n  → check: re-runs verifiers from a fresh shell, audits the chain, edits §Do §Coverage in place, lifts hints into lever.yaml.hints; advances to step: act (if hints non-empty) or step: done (if empty)\n  → act (only if hints surfaced): investigates each hint, edits AGENTS.md / skills, recommends follow-up /lever-new; appends §Act; advances to step: done\n  → \"Ran: plan → do → check → act. All 4/4 verifiers passed. 2 hints landed (AGENTS.md +5/-0). Optional follow-up: /lever-new enforce_route_middleware_lint.\"\n```\n\nThe chain stops on a pause (`pause: ask` or `pause: blocked`) at plan or do, or on a terminal state (`step: done` or `step: cancel`). If do hits a `type: visual` or `type: manual` criterion, it halts with `pause: ask`; the user confirms in chat and re-invokes `/lever 1` to resume.\n\nInspect a lever any time:\n\n```text\n$ /lever-status 1\n  → prints TL;DR + criteria summary + per-criterion events timeline (inline when events exist)\n  → \"4 criteria · 6 events total · 1 cap-fold at C3.\"\n```\n\nSee [`examples/levers/1-add_password_sign_in/`](./examples/levers/1-add_password_sign_in/) for a full happy-path walkthrough, and [`examples/levers/2-fix_dropdown_ios_close/`](./examples/levers/2-fix_dropdown_ios_close/) for a scenario where check routes back to do.\n\n## Install\n\n### Claude Code\n\n```text\n/plugin marketplace add fmind/agent-levers\n/plugin install agent-levers@agent-levers\n```\n\nFor local development, point the marketplace at a clone:\n\n```text\n/plugin marketplace add /path/to/agent-levers\n/plugin install agent-levers@agent-levers\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install fmind/agent-levers\n```\n\nFor local development (live-link, edits reload on next session):\n\n```bash\ngemini extensions link /path/to/agent-levers\n```\n\n### Antigravity CLI\n\n```bash\nagy plugin install https://github.com/fmind/agent-levers\n```\n\nFor local development (live-link, edits reload on next session):\n\n```bash\nagy plugin install /path/to/agent-levers\n```\n\n### OpenCode\n\nTo use these skills in OpenCode, place or clone the skill directories under `.agents/skills/` (for project scope) or `~/.agents/skills/` (for global scope). OpenCode automatically discovers and loads them.\n\n### GitHub Copilot\n\nCopilot CLI:\n\n```bash\ncopilot plugin marketplace add fmind/agent-levers\ncopilot plugin install agent-levers@agent-levers\n```\n\nFor local development, point the marketplace at a clone:\n\n```bash\ncopilot plugin marketplace add /path/to/agent-levers\ncopilot plugin install agent-levers@agent-levers\n```\n\nVS Code — point `chat.pluginLocations` at a local clone:\n\n```jsonc\n// settings.json\n\"chat.pluginLocations\": {\n  \"/path/to/agent-levers\": true\n}\n```\n\n## Reference\n\n### Layout\n\n```text\nagent-levers/\n├── AGENTS.md                          # canonical context — read by Copilot; @-included by CLAUDE.md / GEMINI.md\n├── lever.schema.json                  # JSONSchema for end-user lever.yaml files\n├── skills/                            # Agent Skills (open standard)\n│   ├── lever-init/SKILL.md            # user-facing: bootstrap a repo\n│   ├── lever-new/SKILL.md             # user-facing: start a new lever (writes §Brief)\n│   ├── lever-status/SKILL.md          # user-facing: list / detail / cancel levers\n│   └── lever/                                            # user-facing: dispatcher\n│       ├── SKILL.md                                      # auto-chains\n│       └── references/{plan,do,check,act}.md             # step procedures (loaded on demand)\n├── .claude-plugin/                    # Claude Code plugin manifest + bundled marketplace\n├── gemini-extension.json              # Gemini CLI extension manifest\n├── plugin.json                        # GitHub Copilot manifest\n└── .github/workflows/ci.yml           # lint + lever.yaml schema validation\n```\n\nIn an end-user project after `/lever-init`:\n\n```text\n.agents/levers/\u003cid\u003e-\u003cslug\u003e/\n├── lever.yaml          # machine state (step, optional pause, criteria with per-criterion events log, budget, decisions, hints); validated against lever.schema.json\n└── LEVER.md            # single narrative — opens with `## TL;DR`, then §Brief, §Plan, §Do, §Check, §Act (each appears when its step runs)\n```\n\nThe per-event do audit lives in `lever.yaml.criteria[i].events`; render it inline via `/lever-status \u003cid\u003e`. Cross-task project knowledge (auth flow, schema, shared notes) belongs in whatever docs/memory skill the project already uses — install one alongside agent-levers if you need that surface.\n\n### State machine\n\n`lever.yaml.step` is the single state pointer (`plan | do | check | act | done | cancel`). `lever.yaml.pause` is optional and present only when the chain is halted at `step` waiting for the user (`ask` = open question or fork; `blocked` = external blocker like auth, env, budget) — and only ever at `step: plan` or `step: do`. The pair `(step, pause)` is the full state. Check and act always advance, route back, or finish — they never pause.\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e init\n    init --\u003e new\n    new --\u003e plan\n\n    plan --\u003e do\n    do --\u003e check\n\n    check --\u003e done: pass · no hints\n    check --\u003e act: pass · hints\n    check --\u003e do: failing\n    check --\u003e plan: replan\n\n    act --\u003e done\n    done --\u003e [*]\n\n    note right of plan\n      may pause: ask · blocked\n    end note\n    note right of do\n      may pause: ask · blocked\n    end note\n```\n\n`init` and `new` are user-typed entries (`/lever-init`, `/lever-new`); the chain steps `plan → do → check → act → done` advance via the dispatcher (`/lever \u003cid\u003e`). `done` is terminal — the diff hands off to the user. `cancel` is a terminal state set via `/lever-status \u003cid\u003e cancel [\u003creason\u003e]` (see \"Cancelling a lever\" below); no transition leads to it from the procedures.\n\nThe chain reply communicates `(step, pause)` in plain English; no fixed line format. When referencing a criterion, name it by `id` (e.g., `C3`) so the reference stays stable across edits. Examples:\n\n```text\n\"Brief captured; ready to plan. Run /lever 1 next.\"\n\"Plan written; 4 acceptance criteria defined. Run /lever 1 next.\"\n\"Every criterion passes (4/4). Run /lever 1 next.\"\n\"Failing on C3 (rate-limit verifier exit 1; 3/4 passing). Run /lever 1 to resume do.\"\n\"All 4/4 verifiers passed. 2 hints surfaced. Continuing into act.\"\n\"All 4/4 verifiers passed. No hints. Done — diff is staged.\"\n\"Proposals staged across AGENTS.md (+5/-0). Optional follow-up: /lever-new enforce_route_middleware_lint.\"\n\"Paused at plan (ask): rate-limit policy for the public endpoint? Project conventions don't dictate.\"\n\"Paused at plan (ask): persist sessions in Postgres or Redis?\n   - Postgres — already in stack; adds load to primary DB\n   - Redis — fast, but new ops surface to maintain\"\n\"Paused at do (ask): confirm visual on C7? Screenshot at docs/visual/login-mobile.png.\"\n\"Paused at do (blocked): budget exhausted (max_streak; 5/6 passing). Raise the limit or narrow scope, then re-invoke /lever 1.\"\n\"Blocked: levers directory (.agents/levers/) is gitignored. Remove the entry from .gitignore and re-run /lever-init.\"\n```\n\nPer-step shapes live in each `skills/lever/references/\u003cstep\u003e.md` §Hand off — that's the source of truth.\n\n### Cancelling a lever\n\n```text\n$ /lever-status 1 cancel out of scope after replanning\n  → writes lever.yaml: step: cancel, drops any pause, bumps updated_at\n  → rewrites LEVER.md ## TL;DR with the cancellation block (incl. the reason if you provided one)\n  → \"Lever 1 cancelled. Directory stays at .agents/levers/1-add_password_sign_in/ for archival.\"\n```\n\nThe reason is optional — pass everything after `cancel`, or omit it entirely. After cancellation, the lever shows up under `/lever-status` as cancelled and the directory stays intact for archival. `/lever \u003cid\u003e` won't run further procedures on it.\n\n## Contributing\n\nIssues and PRs welcome. Two house rules to keep the framework lean:\n\n- **Skill files have line caps** (see `AGENTS.md` §Conventions) — they load into agent context on every run, so verbosity costs budget.\n- **Examples are CI-validated.** Every `examples/levers/*/lever.yaml` is checked against `lever.schema.json` on every push.\n\nFor non-trivial changes, the repo dogfoods its own framework: `/lever-new \u003ctitle\u003e` to capture intent, `/lever \u003cid\u003e` to drive the chain.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmind%2Fagent-levers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmind%2Fagent-levers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmind%2Fagent-levers/lists"}