meta-loop-template

A GitHub repo template that bootstraps any project — new or existing — with a project spec, agent harness, and autonomous development loops in one command.

Incorporates patterns from meta-harness-tbench2-artifact (environment bootstrapping, structured tool calling, double-confirmation completion), the autonomous-loops skill (sequential pipelines, NanoClaw REPL, infinite loops, Ralphinho DAG), and agent-harness-construction principles (action space design, observation format, error recovery contracts).

What It Does

./init.sh
    |
    |-- [1] Environment Bootstrap    (detects tools, languages, project state)
    |-- [2] Spec Generation          (PROJECT_SPEC.md — from codebase or description)
    |-- [3] Harness Generation       (HARNESS.md — tools, observations, error recovery, gates)
    |-- [4] Workspace Setup          (.claude/, .github/, git, labels, CI)
    |-- [5] Loop Selection           (sequential, continuous, nanoclaw, infinite, ralphinho)
    |
    v
    Ready to run: ./loops/run.sh

Quick Start

New Project

# Clone the template
gh repo create my-project --template ludoplex/meta-loop-template --clone
cd my-project

# Initialize with a description
./init.sh --new "A REST API for managing inventory with real-time stock tracking"

# Run autonomous development
./loops/run.sh

Existing Project

# Clone the template into your project
cd /path/to/your/project
curl -sL https://github.com/ludoplex/meta-loop-template/archive/main.tar.gz | tar xz --strip-components=1

# Initialize by analyzing the codebase
./init.sh --existing .

# Run autonomous development
./loops/run.sh

GitHub Template (Recommended)

1. Click "Use this template" on GitHub
2. Clone your new repo
3. Run ./init.sh

Loop Patterns

Pattern	Command	Best For
Sequential	./init.sh --loop sequential	Daily dev, scripted workflows
Continuous	./init.sh --loop continuous	Multi-day projects with CI gates
NanoClaw	./init.sh --loop nanoclaw	Interactive REPL with autonomous inner loops
Infinite	./init.sh --loop infinite	Parallel spec-driven generation
Ralphinho	./init.sh --loop ralphinho	RFC-driven DAG orchestration

NanoClaw as Greater Loop (Recommended)

The NanoClaw REPL wraps any inner loop, giving you human steering + autonomous execution:

$ ./loops/run.sh
meta-loop> next 3          # Run 3 sequential iterations
meta-loop> status          # Dashboard: progress, build, tests
meta-loop> desloppify      # Cleanup pass on current changes
meta-loop> gate            # Run quality gates
meta-loop> custom "..."    # Ad-hoc prompt
meta-loop> pr              # Create PR from current work
meta-loop> exit

What Gets Generated

PROJECT_SPEC.md

A comprehensive project specification covering:

• Architecture, tech stack, directory structure
• Build/test/lint commands
• Testing strategy and coverage targets
• Security boundaries and agent constraints
• Ordered work streams with complexity estimates

HARNESS.md

An agent harness configuration defining:

• Environment bootstrap command (pre-agent state capture)
• Tool definitions with JSON schemas
• Observation format (status, summary, next_actions, artifacts)
• Error recovery contracts (root cause, retry, stop conditions)
• Quality gates (build, test, lint, secrets, coverage)
• Double-confirmation completion pattern
• Cost controls (max iterations, cost, duration)

Workspace

• .claude/CLAUDE.md — project-specific agent instructions
• .claude/commands/ — slash commands for loop operations
• .claude/settings.json — default permissions
• .github/workflows/ci.yml — multi-language CI pipeline
• .github/ISSUE_TEMPLATE/ — bug report and feature request templates
• .github/PULL_REQUEST_TEMPLATE.md — PR template with loop context
• GitHub labels for agentic workflow tracking

Project Structure

your-project/
├── PROJECT_SPEC.md              # Generated project specification
├── HARNESS.md                   # Generated agent harness config
├── SHARED_TASK_NOTES.md         # Cross-iteration context bridge
├── .meta-loop/
│   ├── env-snapshot.txt         # Latest environment snapshot
│   ├── project-type.txt         # Detected project type
│   ├── iteration-count.txt      # Current iteration number
│   ├── active-loop.txt          # Active loop pattern
│   └── initialized-at.txt       # Init timestamp
├── loops/
│   ├── run.sh                   # Generated loop runner (pattern-specific)
│   ├── controller.sh            # Loop pattern selector
│   ├── sequential.sh            # Sequential pipeline
│   └── snapshot.sh              # Inter-iteration state capture
├── .claude/
│   ├── CLAUDE.md                # Project agent instructions
│   ├── commands/
│   │   ├── run-loop.md          # /project:run-loop command
│   │   ├── status.md            # /project:status command
│   │   └── desloppify.md        # /project:desloppify command
│   └── settings.json
├── .github/
│   ├── workflows/ci.yml
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
└── docs/
    └── LOOP_PATTERNS.md         # Pattern decision guide

Environment Variables

Variable	Default	Description
MAX_RUNS	5	Max iterations per loop session
MAX_COST	10.00	Max API cost per session
MAX_PASSES	3	Max Ralphinho DAG passes
BATCH_SIZE	3	Parallel agents in infinite mode
MERGE_STRATEGY	squash	PR merge strategy (squash/merge/rebase)
CI_RETRY_MAX	2	Auto-fix attempts on CI failure
CLAW_SESSION	meta-loop	NanoClaw session name

How It Works

1. Environment Bootstrap (from meta-harness)

Before any agent work, a compound shell command captures: platform, working directory, file listing, language versions, package managers, git state, CI/CD config, and available resources. This saves 2-5 exploratory turns per iteration.

2. Spec Generation

For existing projects: Claude analyzes the codebase — reads config files, entry points, tests, CI pipelines — and generates a structured spec.

For new projects: Claude expands a description into a full spec with architecture decisions, work streams, and acceptance criteria.

3. Harness Construction (from agent-harness-construction)

The harness defines the agent's operating contract:

• Action space: schema-first tool definitions (execute_task, verify_task, task_complete)
• Observations: every tool response includes status + summary + next_actions + artifacts
• Error recovery: each error type has root cause hint, retry instruction, and stop condition
• Quality gates: concrete checks that must pass before any commit
• Double-confirmation: agents must verify their own completion (prevents premature termination)

4. Autonomous Loops

Each loop pattern is a shell script that orchestrates claude -p calls:

• Sequential: implement -> de-sloppify -> quality gates -> commit (repeat)
• Continuous: create branch -> implement -> PR -> wait for CI -> merge (repeat)
• NanoClaw: interactive REPL that dispatches inner loops on command
• Infinite: parallel sub-agents, each with unique creative direction
• Ralphinho: decompose spec into DAG, run quality pipelines per unit, merge queue

5. Cross-Iteration Context

SHARED_TASK_NOTES.md bridges context between claude -p calls (each starts fresh). Every iteration reads the notes, does work, and updates them. The completion signal ALL_WORK_STREAMS_COMPLETE stops the loop.

Prerequisites

• Claude Code (claude CLI)
• GitHub CLI (gh) — for continuous loop and GitHub setup
• Git
• Bash 4+

Credits

• Environment bootstrapping: meta-harness-tbench2-artifact by ludoplex
• Ralphinho pattern: enitrat
• Infinite agentic loop: disler
• Continuous Claude: AnandChowdhary
• Agent harness principles: agent-harness-construction skill (ECC)
• NanoClaw REPL: Everything Claude Code (ECC)

License

MIT