feat: examples/quickstart/ — 10-minute zero-cost ruff cleanup demo#30
Merged
Conversation
…loses #29) Drops a turn-key example a stranger can run from a fresh clone: `bash setup.sh && evolution-kernel --config ... --loop`. End-to-end wall-clock on a developer laptop: 1.4 seconds. Cost: $0. The mission is small on purpose — drive ruff to zero violations on `src/messy.py` — so the whole closed loop (worktree sandbox, scope enforcement, ledger writes, `evolution/accepted` branch advancing) fits in one terminal scroll. There is no LLM in this example. The planner/executor/evaluator are short deterministic Python scripts checked into the demo target itself, so the example never depends on an API key, a paid subscription, or network access. For the LLM-driven version, see `examples/oss_fix_demo/` (PR coming next in this v1.1 series). Files added under `examples/quickstart/`: - `target/src/messy.py` — autofixable ruff violations - `target/pyproject.toml` — pins ruff lint rule families (E/F/I/W) - `target/bots/{planner,executor,evaluator}.py` — deterministic roles - `evolution.yml` — references the in-target bots, allowed_paths src/ - `setup.sh` — init fresh repo, commit bots, print next-step command - `README.md` — measured wall-clock, cost, ledger forensics Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a zero-cost quickstart example that demonstrates the evolution loop using deterministic local Ruff cleanup bots instead of an LLM.
Changes:
- Adds a deliberately messy Python target plus Ruff configuration.
- Adds planner/executor/evaluator scripts committed into the demo target.
- Adds quickstart setup script, README, and evolution config.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
examples/quickstart/target/src/messy.py |
Demo source file with intentional Ruff violations. |
examples/quickstart/target/pyproject.toml |
Ruff lint configuration for the demo target. |
examples/quickstart/target/bots/planner.py |
Deterministic planner that emits Ruff cleanup steps. |
examples/quickstart/target/bots/executor.py |
Runs Ruff fix/format commands in the worktree. |
examples/quickstart/target/bots/evaluator.py |
Evaluates success by running Ruff check. |
examples/quickstart/setup.sh |
Bootstraps a fresh demo target Git repository. |
examples/quickstart/README.md |
Documents how to run and inspect the quickstart. |
examples/quickstart/evolution.yml |
Configures mission, evidence, scope, hard stops, and roles. |
Comments suppressed due to low confidence (1)
examples/quickstart/README.md:68
- This references
examples/oss_fix_demo/, but that example directory is not included in the repository, leaving this call-to-action as a broken link/path.
See `examples/oss_fix_demo/` — same shape, real OSS target, `claude` CLI as executor.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+24
to
+32
| Expected output (last 8 lines): | ||
|
|
||
| ``` | ||
| { | ||
| "accepted": true, | ||
| "candidate_commit": "<sha>", | ||
| "reason": "hard gates passed and evaluator recommended promotion", | ||
| ... | ||
| } |
|
|
||
| This example exists for one reason: prove that a stranger can clone the repo and watch a real `evolution/accepted` commit appear in under a minute. The mission is deliberately small — *drive ruff to zero violations on `src/messy.py`* — so the whole closed loop fits in one terminal scroll. | ||
|
|
||
| There is **no LLM** in this example. The planner / executor / evaluator are 30-line Python scripts checked into the demo target itself. The point is to demonstrate the *runtime*: worktree sandboxing, scope enforcement, ledger writes, the `evolution/accepted` branch advancing — not LLM smarts. When you want LLM-driven evolution, see `examples/oss_fix_demo/` (separate example, requires `claude` CLI or an API key). |
Comment on lines
+14
to
+15
| pip install -e . | ||
| pip install ruff # only test dep beyond the runtime |
Comment on lines
+35
to
+39
| echo " evolution-kernel \\" | ||
| echo " --config examples/quickstart/evolution.yml \\" | ||
| echo " --repo $TARGET \\" | ||
| echo " --ledger /tmp/ek-quickstart-ledger \\" | ||
| echo " --loop" |
Comment on lines
+3
to
+4
| Every violation in this file is autofixable by `ruff check --fix` and | ||
| `ruff format`. The quickstart proves the closed loop by watching ruff |
|
|
||
| evidence_sources: | ||
| - type: shell | ||
| command: "python3 -m ruff check src/ || true" # `|| true` so observer never fails the run |
Comment on lines
+17
to
+21
| evolution-kernel \ | ||
| --config examples/quickstart/evolution.yml \ | ||
| --repo /tmp/ek-quickstart-target \ | ||
| --ledger /tmp/ek-quickstart-ledger \ | ||
| --loop |
| "ruff_clean": float(clean), | ||
| "fitness": 1.0 if clean else 0.0, | ||
| }, | ||
| "ruff_output_tail": proc.stdout[-400:], |
Comment on lines
+23
to
+31
| proc = subprocess.run(cmd, cwd=worktree, capture_output=True, text=True) | ||
| steps.append( | ||
| { | ||
| "cmd": " ".join(cmd), | ||
| "exit": proc.returncode, | ||
| "stdout_tail": proc.stdout[-400:], | ||
| "stderr_tail": proc.stderr[-400:], | ||
| } | ||
| ) |
Comment on lines
+20
to
+21
| [sys.executable, "-m", "ruff", "check", "--fix", "--unsafe-fixes", "src/"], | ||
| [sys.executable, "-m", "ruff", "format", "src/"], |
This was referenced May 17, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #29.
Summary
Measured (2026-05-17, dev laptop)
Test plan
🤖 Generated with Claude Code