Long-Running Agent Framework

Framework for enabling AI agents to work effectively across many context windows on complex tasks.

Core Problem

Long-running agents must work in discrete sessions where each new session begins with no memory of previous work. Without proper scaffolding, agents tend to:

1. •One-shot attempts - Try to complete everything at once, running out of context mid-implementation
2. •Premature completion - See partial progress and declare the job done
3. •Undocumented states - Leave code in broken or undocumented states between sessions

Two-Agent Solution

1. Initializer Agent (First Session Only)

Sets up the environment with all context future agents need:

• •Create init.sh script for environment setup
• •Generate comprehensive feature_list.json with all requirements
• •Initialize claude-progress.txt for session logging
• •Make initial git commit

See references/initializer-prompt.md for the full prompt template.

2. Coding Agent (Every Subsequent Session)

Makes incremental progress while maintaining clean state:

• •Read progress files and git logs to get bearings
• •Run basic tests to verify working state
• •Work on ONE feature at a time
• •Test end-to-end before marking complete
• •Commit progress with descriptive messages
• •Update progress file

See references/coding-prompt.md for the full prompt template.

Session Startup Sequence

Every coding agent session should begin:

1. pwd                              # Understand working directory
2. cat claude-progress.txt          # Read recent progress
3. cat feature_list.json            # Check feature status
4. git log --oneline -20            # Review recent commits
5. ./init.sh                        # Start dev environment
6. <run basic test>                 # Verify app works
7. <select next feature>            # Choose one failing feature

Key Files

feature_list.json

Comprehensive list of all features with pass/fail status. Use JSON format to prevent inappropriate edits.

{
  "features": [
    {
      "category": "functional",
      "description": "User can create new chat",
      "steps": ["Navigate to main", "Click New Chat", "Verify creation"],
      "passes": false
    }
  ]
}

Template: assets/feature_list_template.json

claude-progress.txt

Session-by-session log of work completed. Each entry includes:

• •Session timestamp
• •Features worked on
• •Changes made
• •Current state
• •Next steps

Template: assets/progress_template.md

init.sh

Environment setup script that:

• •Installs dependencies
• •Starts development servers
• •Sets up any required services

Critical Rules

For Feature List

• •Never remove or edit test descriptions
• •Only change passes field status
• •Mark as passing ONLY after end-to-end verification

For Progress Tracking

• •Always commit before session end
• •Write descriptive commit messages
• •Update progress file with summary
• •Leave environment in mergeable state

For Testing

• •Use browser automation for web apps (Puppeteer MCP)
• •Test as a human user would
• •Verify end-to-end, not just unit tests
• •Document any known limitations

Common Failure Modes & Solutions

Adapting to Other Domains

This framework generalizes beyond web development. Key principles:

1. •Comprehensive task decomposition - Break work into testable units
2. •Progress persistence - Maintain state across sessions
3. •Incremental verification - Test after each change
4. •Clean handoffs - Leave work in resumable state