Simple Overseer

A streamlined system for processing brain dumps into organized, actionable project tasks that are automatically executed by Claude agents.

Overview

Simple Overseer consists of two main scripts:

1. ingest.py - Converts brain dump markdown files into prioritized, categorized project tasks
2. simple-overseer.py - Sequentially executes project tasks and tests using Claude agents

The system supports two types of items:

• Project files (.md) - Development tasks executed by Claude
• Test files (.yaml) - Automated tests with configurable failure handling strategies

Prerequisites

• Python 3.x
• PyYAML package (pip install pyyaml)
• Claude CLI installed and available in PATH

Recommended Setup: Integrate into Your Project

Best practice: Move the simple-overseer/ folder INTO your target project directory. This gives Claude access to your full codebase context when executing tasks and tests.

# Example: Move into the overseer project
mv simple-overseer/ ~/overseer/simple-overseer/

# Now Claude runs with full project context
cd ~/overseer/simple-overseer/
./simple-overseer.py

Benefits:

• Claude can read/edit your entire project when fixing issues
• Test working directories become simpler (. or .. instead of ../overseer)
• All context in one place for better code understanding
• Tests can validate changes in the same context where code was written

Update test paths: After moving, update working_directory in test files to match new location (e.g., "." or ".." instead of "../overseer")

Directory Structure

Standalone (default)

simple-overseer/
├── ingest/                          # Brain dump input files
│   └── default.md                   # Main brain dump file
├── projects/                        # Generated project tasks and tests
│   ├── 00-project-name-READY_TO_DEVELOP.md
│   ├── 01-another-project-READY_TO_DEVELOP.md
│   ├── 99-test-build-READY_TO_TEST.yaml
│   └── ...
├── project-logs/                    # Execution logs for each project/test
│   ├── 00-project-name-COMPLETE.log
│   ├── 01-another-project-FAILED.log
│   └── ...
├── ingest.py                        # Brain dump processor
├── simple-overseer.py               # Project executor
├── prompt-ingesting-braindump.md    # Ingest instructions for Claude
├── test-template.yaml               # Template for creating tests
└── README.md                        # This file

Integrated (recommended)

your-project/
├── src/
├── tests/
├── simple-overseer/                 # Move entire folder here
│   ├── ingest/
│   ├── projects/                    # Generated tasks for THIS project
│   ├── project-logs/                # Execution logs
│   ├── ingest.py
│   ├── simple-overseer.py
│   └── ...
└── package.json

When integrated, Claude has full access to your project files when executing tasks and fixing test failures.

Usage

Step 1: Create Brain Dump Files

Add your brain dump content to markdown files in the ingest/ folder:

# Edit the default brain dump file
nano ingest/default.md

# Or add additional brain dump files
nano ingest/feature-ideas.md
nano ingest/bug-fixes.md

Brain dumps can contain:

• Feature ideas
• Bug descriptions
• Architectural thoughts
• Implementation notes
• Any technical thoughts or tasks

Step 2: Run the Ingest Script

Process your brain dumps into organized project tasks:

./ingest.py

This will:

1. Load all .md files from ingest/
2. Load the brainstorming prompt and test template
3. Invoke Claude to analyze, categorize, and prioritize tasks
4. Generate both project files (.md) and test files (.yaml) in projects/

The agent will:

• Categorize tasks by topic/feature area
• Filter out irrelevant or out-of-scope items
• Prioritize as HIGH/MEDIUM/LOW
• Create project files (.md) for development tasks
• Create test files (.yaml) for validation (builds, unit tests, integration tests)
• Order by priority and dependencies with tests after their related projects
• Note whether server restart is required

Step 3: Review Generated Projects and Tests

Check the projects/ folder for generated files:

ls -la projects/*.md    # Project files
ls -la projects/*.yaml  # Test files

Project files (.md) contain:

• Priority level
• Category
• Description
• Detailed instructions (≤500 words)
• Dependencies
• Server restart requirement

Test files (.yaml) contain:

• Bash command(s) to run
• Working directory and timeout
• Success criteria
• Failure handling strategy

Step 4: Run the Simple Overseer

Execute the project tasks sequentially:

./simple-overseer.py

This will:

1. Scan for project files in projects/
2. Filter out completed projects
3. Process projects sequentially starting from 00
4. Update status during execution:
   • READY_TO_DEVELOP → IN_PROGRESS → COMPLETE
   • Or READY_TO_DEVELOP → IN_PROGRESS → FAILED (on error)

The script will:

• Process one project at a time
• Write execution logs to project-logs/NN-project-name-STATUS.log
• Stop on the first failure
• Allow you to fix issues and resume

Step 5: Handle Failures

If a project fails:

1. Check the error output from simple-overseer
2. Review the detailed log in project-logs/NN-project-name-FAILED.log
3. Fix the issue manually or adjust the project file
4. Run ./simple-overseer.py again to resume

The overseer will automatically skip completed projects and continue from where it stopped.

Execution Logs

Every project and test execution creates a log file in project-logs/:

Log filename format: NN-project-name-STATUS.log

Examples:

• project-logs/00-yaml-config-COMPLETE.log - Successful project
• project-logs/01-safeguard-system-FAILED.log - Failed project
• project-logs/99-test-build-PASSED_TEST.log - Successful test

Log contents:

• Timestamp
• Execution status (SUCCESS/FAILED)
• Claude output or test output
• Error details (if failed)

Use logs to:

• Debug failures
• Review what Claude changed
• Track execution history
• Audit completed work

Logs are gitignored by default but kept in the repository structure.

Project File Naming Convention

Format: NN-project-name-STATUS.md

• NN: Two-digit number (00, 01, 02, ...)
• project-name: Kebab-case descriptive name
• STATUS: Current state of the project
  • READY_TO_DEVELOP: Not started
  • IN_PROGRESS: Currently being processed
  • COMPLETE: Successfully finished
  • FAILED: Encountered an error

Examples:

• 00-librarian-agent-READY_TO_DEVELOP.md
• 01-safeguard-system-IN_PROGRESS.md
• 02-yaml-config-COMPLETE.md
• 03-gate-association-FAILED.md

Project File Structure

Each generated project file follows this structure:

# Project Title

## Priority
HIGH | MEDIUM | LOW

## Category
Topic/feature area

## Description
Brief description of what this accomplishes

## Instructions
Detailed implementation instructions (500 words or less)

## Context
Relevant context from the brain dump

## Dependencies
- Project XX: dependency-name

## Server Restart Required
YES | NO

Test Projects

In addition to regular project files (.md), you can create test files (.yaml) that run bash commands and handle failures with configurable strategies.

Test File Format

Test files use the same numbering scheme as projects: NN-test-name-STATUS.yaml

Examples:

• 99-test-build-READY_TO_TEST.yaml
• 50-test-integration-PASSED_TEST.yaml

Test File Structure

Test files are simple YAML configurations with just two sections:

# Optional comment describing the test

test:
  # Bash command - single line
  command: "npm run build"

  # OR multiple commands (runs sequentially, joined with &&)
  # command:
  #   - "cd ../overseer"
  #   - "npm install"
  #   - "npm run build"

  working_directory: "../overseer"
  timeout: 300

  success_criteria:
    - exit_code: 0
    - output_not_contains:
        - "error"
        - "FAILED"

on_failure:
  strategy: recycle  # stop | recycle | pause_and_notify
  max_retries: 2  # For recycle strategy only

  agent_instructions: |
    Instructions for Claude on how to fix the issue

  telegram:  # For pause_and_notify only
    enabled: false
    message_template: "Test failed"

A template is available at test-template.yaml in the root directory.

Failure Handling Strategies

Tests support three failure handling strategies:

1. stop - Stop execution and mark as FAILED (default)

   • Use for: Critical tests that must pass before continuing
   • Behavior: Stops the overseer immediately, no retry
   • No Claude involvement

2. recycle - Auto-fix and retry with configurable attempts

   • Use for: Any issue Claude can potentially fix (builds, tests, linting, type errors)
   • Behavior: Claude analyzes failure → fixes code → re-runs test (repeats up to max_retries)
   • Configure max_retries: 1 for single attempt, max_retries: 3 for multiple attempts
   • Best for: Most fixable issues

3. pause_and_notify - Pause and optionally send Telegram notification

   • Use for: Tests requiring human intervention (API credentials, network issues, environment setup)
   • Behavior: Marks as FAILED, optionally sends Telegram notification, stops overseer
   • No auto-fix, requires manual intervention
   • Telegram notification is optional

Test Status Values

Tests use different status values than projects:

• READY_TO_TEST - Not yet run (initial status)
• IN_PROGRESS - Currently running
• PASSED_TEST - Test succeeded
• FAILED - Test failed and cannot continue

Command Formats

Single bash command:

test:
  command: "npm run build"

Multiple bash commands (executed sequentially):

test:
  command:
    - "cd ../overseer"
    - "npm install"
    - "npm run build"

Note: Multiple commands are joined with &&, so execution stops on the first failure.

Success Criteria

Tests can specify multiple success criteria:

success_criteria:
  - exit_code: 0                     # Bash command must exit with code 0
  - output_contains:                  # Output must contain these strings
      - "All tests passed"
      - "Build successful"
  - output_not_contains:              # Output must NOT contain these
      - "error"
      - "FAILED"

All criteria must be met for the test to pass.

Examples

See the example test files in the projects/ directory:

• 97-test-unit-tests-READY_TO_TEST.yaml - Recycle strategy with max_retries=3
• 98-test-telegram-notify-READY_TO_TEST.yaml - Pause and notify strategy
• 99-test-build-READY_TO_TEST.yaml - Recycle strategy with max_retries=2

Tips

Organizing Brain Dumps

• Use separate .md files for different topics or sessions
• Be as detailed or as rough as you want - the agent will organize it
• Include context about priorities or urgency in your brain dump
• Mention dependencies or relationships between tasks

Managing Projects

• Review generated projects before running the overseer
• Edit project files if the agent misunderstood something
• Delete or move out-of-scope projects
• Manually adjust numbering if you want to change execution order

Working with Project Context

When simple-overseer is inside your project directory:

• Claude can read all your source files
• Test fixes happen with full codebase context
• Set working_directory: "." or ".." in test files
• Brain dumps can reference specific files/modules in your project

Resuming Work

The system is designed to be interruptible:

• Stop the overseer anytime with Ctrl+C
• Fix any issues
• Run ./simple-overseer.py again - it skips completed projects

Categorization and Filtering

The ingest agent will:

• Group related tasks together
• Identify tasks belonging to different projects
• Exclude irrelevant topics
• Provide a summary of excluded items

Review the agent's categorization decisions in the output and adjust as needed.

Workflow Example

# 1. Write your brain dump
echo "I need a librarian agent that accesses Google Docs..." > ingest/ideas.md

# 2. Process the brain dump
./ingest.py

# Output:
# Found 1 markdown file(s)
# Invoking Claude to process brain dump...
# SUCCESS: Claude completed processing
# Created project files:
#   - 00-librarian-agent-READY_TO_DEVELOP.md
#   - 01-google-docs-integration-READY_TO_DEVELOP.md
#   - 02-telegram-notification-READY_TO_DEVELOP.md

# 3. Review the generated projects
cat projects/00-librarian-agent-READY_TO_DEVELOP.md

# 4. Execute the projects
./simple-overseer.py

# Output:
# Found 3 project file(s)
# 3 project(s) pending processing
# Processing: 00-librarian-agent-READY_TO_DEVELOP.md
# SUCCESS: Project 00 completed
# Processing: 01-google-docs-integration-READY_TO_DEVELOP.md
# SUCCESS: Project 01 completed
# Processing: 02-telegram-notification-READY_TO_DEVELOP.md
# SUCCESS: Project 02 completed
# ALL PROJECTS COMPLETED!

Troubleshooting

Claude CLI not found

Error: Claude CLI is not installed or not in PATH

Solution: Install Claude CLI and ensure it's in your PATH

Cannot import claude_helper

Error: Could not import claude_helper

Solution: Ensure claude_helper.py exists in the simple-overseer directory

No markdown files found

Warning: No markdown files found in ingest directory

Solution: Add at least one .md file to the ingest/ folder

Project file naming issues

Warning: Could not parse filename: my-project.md

Solution: Ensure project files follow the format NN-project-name-status.md

Advanced Usage

Custom Working Directory

By default, Claude runs in the projects/ directory. To run in a different directory, modify the working_dir parameter in the scripts.

Timeout Adjustment

Both scripts use a 600-second (10-minute) timeout. Adjust the timeout parameter if you need more time:

success, output = run_claude_prompt(
    prompt=instructions,
    working_dir=working_dir,
    timeout=1200,  # 20 minutes
    ...
)

Manual Project Creation

You can manually create project files following the naming convention and structure. The overseer will process them along with auto-generated ones.

License

This project is part of the overseer ecosystem.