Autonomous Agent Loop

A self-running AI coding assistant that works through your product requirements document until every task is complete. Each cycle starts fresh with a clean slate, while knowledge persists through version control history, a progress log, and a task tracking file.

What You Need

• Claude Code CLI installed and authenticated
• jq command-line JSON processor (brew install jq on macOS)
• A git-initialized project directory

Getting Started

Method 1: Add to Your Project

Copy the agent files directly into your project:

# From your project root
mkdir -p scripts/agent
cp /path/to/agent/agent.sh scripts/agent/
cp /path/to/agent/prompt.md scripts/agent/
chmod +x scripts/agent/agent.sh

Method 2: Global Skills Installation

Install the skills for use across multiple projects:

cp -r skills/prd ~/.claude/skills/
cp -r skills/agent ~/.claude/skills/

Claude Code Configuration

The agent runs with --dangerously-skip-permissions to allow autonomous operation. Make sure you trust the codebase before running.

How to Use

Step 1: Create Your Requirements Document

Use the PRD skill to generate a detailed requirements document:

Load the prd skill and create a PRD for [your feature description]

Answer the clarifying questions. Output saves to tasks/prd-[feature-name].md.

Step 2: Convert to Agent Format

Use the agent skill to convert the markdown PRD to JSON:

Load the agent skill and convert tasks/prd-[feature-name].md to prd.json

This creates prd.json with user stories structured for autonomous execution.

Step 3: Start the Agent

./scripts/agent/agent.sh [max_iterations]

Default is 10 iterations.

The agent will:

1. Create a feature branch (from PRD branchName)
2. Select the highest priority story where passes: false
3. Implement that single story
4. Run quality checks (typecheck, tests)
5. Commit if checks pass
6. Update prd.json to mark story as passes: true
7. Record learnings to progress.txt
8. Repeat until all stories pass or max iterations reached

Project Files

File	Purpose
agent.sh	Main loop that spawns fresh AI instances
prompt.md	Instructions provided to each AI instance
prd.json	User stories with completion status
prd.json.example	Example format for reference
progress.txt	Append-only log of learnings across iterations
skills/prd/	Skill for generating PRDs
skills/agent/	Skill for converting PRDs to JSON
flowchart/	Interactive visualization of the workflow

Flowchart

The flowchart/ directory contains an interactive diagram showing how the agent works. To run locally:

cd flowchart
npm install
npm run dev

Core Concepts

Fresh Context Each Cycle

Each iteration spawns a new AI instance with clean context. The only persistence between iterations is:

• Git history (commits from previous iterations)
• progress.txt (learnings and context)
• prd.json (which stories are done)

Keep Tasks Small

Each PRD item should be small enough to complete in one context window. If a task is too big, the AI runs out of context before finishing and produces poor code.

Well-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too large (split these):

• "Build the entire dashboard"
• "Add authentication"
• "Refactor the API"

AGENTS.md Updates Matter

After each iteration, the agent updates relevant AGENTS.md files with learnings. This is important because the AI automatically reads these files, so future iterations (and human developers) benefit from discovered patterns, gotchas, and conventions.

Examples of what to add to AGENTS.md:

• Patterns discovered ("this codebase uses X for Y")
• Gotchas ("do not forget to update Z when changing W")
• Useful context ("the settings panel is in component X")

Feedback Loops

The agent only works with proper feedback loops:

• Typecheck catches type errors
• Tests verify behavior
• CI must stay green (broken code compounds across iterations)

Browser Verification for UI Stories

Frontend stories must include "Verify in browser using dev-browser skill" in acceptance criteria. The agent will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

Completion Signal

When all stories have passes: true, the agent outputs <promise>COMPLETE</promise> and the loop exits.

Debugging

Check current state:

# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10

Customizing prompt.md

Edit prompt.md to customize the agent's behavior for your project:

• Add project-specific quality check commands
• Include codebase conventions
• Add common gotchas for your stack

Archiving

The agent automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/YYYY-MM-DD-feature-name/.