rig-seed

A template for building autonomously-evolving software projects with Gas Town.

Inspired By

yoyo-evolve — a self-evolving coding agent that grows one commit at a time.

What Is This?

rig-seed is a scaffold you fork to create a new project that evolves itself. Every day (or on your configured schedule), an AI agent:

1. Reads the project's specs, roadmap, and recent journal
2. Self-assesses the current state of the code
3. Picks 1-3 improvements to make
4. Implements them with tests
5. Journals what happened
6. Submits for automated merge (build-gated)

The agent is coordinated by Gas Town's Mayor, executed as a Polecat (worker), and quality-gated by the Refinery (merge queue).

Quick Start

1. Create your project

Fork this repo or use it as a GitHub template. This gives you all the evolution state files with sensible defaults.

2. Write your specs

Open SPECS.md and describe what you want this project to become. Be specific — the agent uses this to guide its work. If you leave it empty, the agent will read specs from the bead description on its first run.

3. Add it as a Gas Town rig

gt rig add myproject <your-git-url>

4. Enable evolution

Add an evolve section to your rig's config:

{ "evolve": { "enabled": true, "github_repo": "you/your-repo" } }

5. Start evolving

gt rig undock myproject && gt rig start myproject

The Deacon's evolve plugin triggers daily cycles automatically. Or trigger one manually by creating a bead with the mol-evolve formula.

6. Guide the agent

• Check JOURNAL.md to see what the agent did each session
• File GitHub issues with the agent-input label to steer priorities
• Review ROADMAP.md for upcoming work
• Adjust .evolve/config.toml for schedule and limits

Template Files

File	Purpose	Mutable?
IDENTITY.md	Project constitution and rules	No (immutable)
PERSONALITY.md	Agent voice and communication style	Yes (rarely)
SPECS.md	What we're building (filled on first run)	Yes
ROADMAP.md	Priorities, milestones, future work	Yes
JOURNAL.md	Session log (append-only, never delete)	Append only
LEARNINGS.md	Accumulated technical insights	Yes
NEXT_STEPS.md	Structured planning intent for next session	Overwritten each session
SESSION_COUNT	Current evolution session number	Auto-incremented
.evolve/config.toml	Evolution settings (frequency, limits)	Yes
.evolve/IMMUTABLE.txt	Files the agent cannot modify	Human only
formulas/mol-evolve.formula.toml	Evolution workflow formula	Yes (rarely)
.claude/CLAUDE.md	Instructions for evolution workers	Yes

Validation

Run the template validation script to check that all required files are present:

./validate.sh

This is also available as an example CI workflow you can add to your forked repo.

Metrics

View a summary of your project's evolution history:

./metrics.sh

Shows session count, commits per session, velocity, roadmap progress, and more. Use ./metrics.sh -q for machine-readable key=value output, or ./metrics.sh --format=json for JSON, --format=csv for spreadsheet-friendly CSV.

Session Recap

Quickly see what the last evolution session did:

scripts/recap.sh              # Full latest journal entry
scripts/recap.sh --short      # Just Goal and Next Steps
scripts/recap.sh --json       # JSON output for tooling

Multi-Project Dashboard

Compare evolution metrics across multiple rig-seed projects:

scripts/dashboard.sh ~/projects/my-cli ~/projects/my-api ~/projects/my-lib

Outputs a table with day count, sessions, commits, roadmap progress, learnings, and velocity for each project. Supports --summary for one-line-per-project output, --json for dashboard integrations, and -q for machine-readable key=value output.

Health Check

Monitor whether your forked project is actively evolving:

./health-check.sh

Checks SESSION_COUNT progression, journal freshness, recent git activity, and template validity. Configure thresholds via MAX_COMMIT_AGE_DAYS and MAX_JOURNAL_AGE_DAYS environment variables (default: 7 days).

Fork Quickstart

After forking, run the quickstart script to reset evolution state and get your project ready:

./quickstart.sh

This resets SESSION_COUNT, clears the journal/roadmap/learnings, and walks you through writing your specs. See example specs for starter templates (CLI tool, web API, library).

Build Check

Run all build/test/lint checks across all detected build systems:

scripts/check.sh

Auto-detects Go, Node.js, Rust, Python, and Makefile projects (including subdirectories like frontend/). Also runs any commands configured in the [build] section of .evolve/config.toml. This is the same script the evolution agent runs during Step 7 (Build Check) — a broken build is never submitted.

Evolution State Check

Verify that a mol-evolve session updated all required state files before submitting:

scripts/check-evolve-state.sh

Checks that JOURNAL.md, NEXT_STEPS.md, and SESSION_COUNT were modified. Warns if ROADMAP.md, DAY_COUNT, or DAY_DATE are missing from the diff. Run this before gt done to catch missing updates early.

Upstream Sync

Stay up to date with the latest rig-seed template improvements:

scripts/sync-upstream.sh --dry-run   # Preview changes
scripts/sync-upstream.sh             # Apply updates

Merges infrastructure files (scripts, docs, examples) from upstream while preserving your project-specific state. Configure in .evolve/config.toml:

[template]
upstream = "https://github.com/totalslacker/rig-seed.git"
sync = "manual"

Workflow Lint

Validate your GitHub Actions workflow files for common issues:

scripts/lint-workflows.sh

Checks YAML syntax, deprecated action versions, missing required fields, security anti-patterns (hardcoded secrets, unsafe pull_request_target), and best practices. Use -q for quiet CI output.

Rollback

If a broken merge reaches main, revert it safely:

scripts/rollback.sh --dry-run    # Preview what will be reverted
scripts/rollback.sh              # Revert and verify the build passes

Creates a revert commit (non-destructive). Handles both merge commits and regular commits. Automatically runs the build check after reverting to confirm the fix.

Migration

If you forked rig-seed a while ago and want to pick up new features:

scripts/migrate.sh --dry-run   # See what's missing
scripts/migrate.sh             # Add missing files

The script detects which rig-seed features are present and copies missing ones from upstream. It never overwrites files you've customized.

Community & Onboarding

If you're contributing to a project that was forked from rig-seed, here's how to get oriented quickly:

Understand the project

1. Read SPECS.md — what the project is building
2. Read JOURNAL.md (top entries) — what happened recently
3. Check ROADMAP.md — what's planned next
4. Run ./health-check.sh — see the project's current health

Steer the agent

File a GitHub issue with the agent-input label. The evolution agent prioritizes community issues above its own roadmap. Be specific — "the CLI crashes when given an empty file" works better than "improve error handling."

Contribute directly

Pull requests are welcome. Before you start:

• Run ./validate.sh to confirm the template is intact
• Run scripts/check.sh to verify all builds pass
• Don't modify IDENTITY.md or files in .evolve/IMMUTABLE.txt
• Don't delete journal entries — JOURNAL.md is append-only
• See CONTRIBUTING.md for full guidelines

Set up your own fork

Want your own self-evolving project? See Quick Start above or run the /rig-spawn wizard in Claude Code for interactive setup. The Day Zero Walkthrough covers everything from fork to first evolution session.

Documentation

• Architecture — How state files, scripts, and evolution flow connect
• Forking Guide — What to do after you fork rig-seed
• The Evolution Process — How mol-evolve works step by step
• Example Specs — Starter SPECS.md files for common project types
• Example Configs — .evolve/config.toml variants for different strategies
• Example Roadmaps — Starter ROADMAP.md files for common project types
• Example CI Workflows — GitHub Actions you can copy
• Example Personalities — PERSONALITY.md variants (formal, casual, minimal)
• Example Git Hooks — Pre-commit hook for validation and immutable file protection
• Formula Customization — How to customize mol-evolve for your project
• Day Zero Walkthrough — Step-by-step tutorial for your first evolution session
• Upgrading Your Fork — How to pull new rig-seed features into an existing fork
• External Integrations — Sync beads to Linear, Jira, or other project trackers
• Monitoring with Prometheus + Grafana — Expose evolution metrics for long-running monitoring
• Script Conventions — Output markers, color, flags, and patterns used by all scripts
• Merge Strategy Guide — Choosing between Refinery, PR-based, and hybrid merging
• Planning Investigation — How evolution sessions choose work and how to improve it
• Troubleshooting — Common problems and how to fix them
• Project Plan — Architecture and design decisions

License

MIT