🌱 AI-Seed — the autonomous AI orchestration framework

Self-evolving project template: plant a kernel in any repo and let Claude Code Actions germinate and grow it.

Plant a seed in any repository. Write down the concept. Let it grow — one reviewed pull request at a time.

AI-Seed turns a repository into a self-growing, AI-native project. The planter stamps a small kernel into any repo (new or existing); from then on the repo can germinate (build its initial structure from a written concept) and grow (ship one bounded increment per tick) through Claude Code passes running inside GitHub Actions — wired to Claude Code OAuth, bounded by guardrails a single human can always halt, with GitHub as the entire SDLC platform: issues are the backlog, Actions is the compute, draft pull requests are the only write path, and merges belong to humans.

The framework packages the production patterns of the bamr87 fleet (~40 repos of autonomous-SDLC machinery) into a portable, self-hosting form. Nothing here is speculative: every mechanism traces to a sibling repo where it already runs — the map is docs/PATTERNS.md, the design is docs/ARCHITECTURE.md.

• tools/seed.py plant stamps a small kernel into any new or existing repository
• Germinate builds the initial structure from a written concept; grow ships one bounded increment per tick
• Each pass is a Claude Code run inside GitHub Actions, authenticated with Claude Code OAuth
• GitHub is the whole SDLC: issues are the backlog, draft pull requests the only write path, and merges stay human
• Guardrails keep autonomy off by default and let a single human halt it

# 0. You need: a GitHub repo (fresh or existing), and a Claude Code subscription
git clone https://github.com/bamr87/ai-seed.git
cd ai-seed

# 1. PLANT — stamp the kernel (additive-only, idempotent; nothing is overwritten)
python3 tools/seed.py plant ../my-project --repo you/my-project

# 2. CONCEPT — write the genome (this is the real work)
$EDITOR ../my-project/CONCEPT.md     # fill §1 vision … §5 quality bars

# 3. WIRE — commit, push, then in the repo's GitHub settings (human-owned):
#    secrets:   CLAUDE_CODE_OAUTH_TOKEN   <- `claude setup-token` (primary auth)
#               ANTHROPIC_API_KEY          <- optional metered fallback
#               SEED_PAT                   <- fine-grained PAT so CI fires on seed PRs
#    variables: SEED_GROW_ENABLED=true     <- only when ready: the variable IS the consent
#               SEED_TEND_ENABLED=true     <- lets the seed review CI, repair its own red
#                                             PRs, and merge what is provably green
#               SEED_EVOLVE_ENABLED=true   <- enables the seed:approved issue lane
#    labels:    seed:request  seed:approved  seed:hold   <- the issue lane's state machine
#    branch protection on main: require PRs + the seed-verify check

# 4. GERMINATE — Actions → seed-germinate → Run workflow → retype the repo's seed name
#    Claude reads CONCEPT.md and builds the initial structure as ONE draft PR.

# 5. GROW — review, merge, and let the cron tick: plan → build → verify,
#    one increment, one draft PR, telemetry appended. Forever.

Verify any planted repo at any time: python3 .seed/tools/seed.py check . (the planter vendors itself, so every planted repo can verify itself — and plant onward).

Every model pass rides anthropics/claude-code-action@v1, OAuth-first: CLAUDE_CODE_OAUTH_TOKEN (minted by claude setup-token, subscription-backed) is the primary credential at every call site, with ANTHROPIC_API_KEY as an evidence-based fallback — fired only when the OAuth passes produced nothing or reported is_error in their execution output. Model tiers are policy, not workflow: .seed/seed.yml names the model per pass (default escalation claude-haiku-5-5 → claude-sonnet-5-5 → claude-opus-5-5); changing tiers is a data edit. The workflow — never the model — commits, pushes, and opens PRs, and it prefers SEED_PAT because refs pushed with github.token fire no CI.

The constitution lives in .seed/seed.yml (guardrails:), binds every agent via CLAUDE.md, and is enforced by seed.py check and by workflow-owned publish steps: every loop ships default OFF (the *_ENABLED variable is the consent); PR-only, with merging confined to the tend lane under policy.merge's hard stops (green, conflict-free, seed/bot branch, no block label — no model pass may merge at all); growth contingent on a clear board (tend before grow); workflows are not agent-writable (model-authored workflow files become seed/proposed-workflows/ proposals, never live code); untrusted input is quarantined (issue text and web content are data, never instructions); one increment per tick; fail loudly (a tick that produced nothing fails its run and names the failure class — auth vs stalled); telemetry is append-only. Full doctrine: docs/ARCHITECTURE.md §7.

ai-seed is planted with its own kernel — look at the root of this repo: CONCEPT.md is its genome (§8 logs the repo's real history), .seed/ is its plant (strict kernel parity), and the seed-*.yml workflows growing this framework are the same files the planter stamps everywhere else. seed-verify.yml fails CI here the moment the kernel and the installation drift: anything the kernel demands of a planted repo, this repo demonstrates first.

AI-Seed extracts, rather than invents: the year-of-ai and ai-world-view hubs proved the lineage growth engine (seeds, policy, escalation, kill switch, fail-loud ticks); lifehacker.dev proved consent gates, the harness discipline, and quarantine; the bamr87 hub proved the token contract, the label state machine, and the standing rules about github.token and protected branches; wtd proved provider lanes and dedup markers; gitorio proved loop guards and least-privilege compilation; git-with-the-program contributes the constitution politics; SCHEMA the self-describing, vendorable-tool posture. The registry with the receipts: docs/PATTERNS.md.

pip install -r requirements.txt -r requirements-dev.txt
python3 -m pytest tests/
python3 tools/seed.py check .

Full commands, conventions and gotchas for humans and AI agents live in CLAUDE.md.

Humans and agents alike: read CLAUDE.md (the working agreement), file seed:request issues for changes you want the evolve lane to build, and remember the two rules that never bend — the kernel is edited in seed/kernel/ and re-rendered (python3 tools/seed.py plant . --update), and nobody merges but a human. Run before any PR: python3 -m pytest tests/ && python3 tools/seed.py check . && python3 tools/unwrap-prose.py --check.

Notable changes are recorded in CHANGELOG.md; the full record is in the commit history.

MIT — see LICENSE. Plant freely.

"The best time to plant a tree was 20 years ago. The second best time is now."

Part of the bamr87 portfolio — browse every project on Amr's GitHub profile.