Agent Foreman

Name: Agent Foreman
Author: Lukin

mylukin/agent-foreman

247 repo stars
Updated January 23, 2026
mylukin/agent-foreman

Provide a long-task harness with external memory, feature-driven workflow, and clean agent handoffs.

About

agent-foreman is a long-task harness that gives Claude Code external memory, a feature-driven workflow, and clean agent handoffs. A developer uses it to keep long-running agent work coherent across context resets and handoffs.

Long-task harness
External agent memory
Feature-driven workflow
Clean agent handoffs

Agent Foreman by the numbers

Data as of Jul 24, 2026 (Skillselion catalog sync)

/plugin marketplace add mylukin/agent-foreman

/plugin install agent-foreman@agent-foreman-plugins

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/mylukin/agent-foreman/plugins/agent-foreman.svg)](https://skillselion.com/skills/mylukin/agent-foreman/plugins/agent-foreman)

repo stars	★ 247
Last updated	January 23, 2026
Repository	mylukin/agent-foreman ↗

What it does

Provide a long-task harness with external memory, feature-driven workflow, and clean agent handoffs.

README.md

agent-foreman

⚠️ DEPRECATED: This project is no longer maintained. Please migrate to ralph-dev - a simplified and improved version.

🚨 Migration Notice

This project has been deprecated due to its complexity. A new, simplified version is now available:

👉 https://github.com/mylukin/ralph-dev

Please migrate to ralph-dev for continued support and updates.

Legacy Documentation (archived)

Stop AI agents from half-building features. Ship complete code in one session.

Chinese | Detailed Guide

Problem

AI coding agents face three common failure modes:

Doing too much at once - Trying to complete everything in one session
Premature completion - Declaring victory before features actually work
Superficial testing - Not thoroughly validating implementations

Solution

agent-foreman provides a structured harness that enables AI agents to:

Maintain external memory via structured files
Work on one feature at a time with clear acceptance criteria
Hand off cleanly between sessions via progress logs
Track impact of changes on other features

Quick Start

/plugin install agent-foreman        # 1. Install
/agent-foreman:init Build auth API   # 2. Initialize
/agent-foreman:run                   # 3. Let AI work

Installation

# Quick install (binary)
curl -fsSL https://raw.githubusercontent.com/mylukin/agent-foreman/main/scripts/install.sh | bash

# Via npm
npm install -g agent-foreman

# Or use npx directly
npx agent-foreman --help

Manual download: GitHub Releases

Usage

Plugin Commands (Recommended)

/plugin marketplace add mylukin/agent-foreman
/plugin install agent-foreman

Command	Description
`/agent-foreman:status`	View project status and progress
`/agent-foreman:init`	Initialize harness with project goal
`/agent-foreman:analyze`	Analyze existing project structure
`/agent-foreman:spec`	Transform requirements into tasks
`/agent-foreman:next`	Get next priority task
`/agent-foreman:run`	Auto-complete all pending tasks

Transform requirements into tasks:

/agent-foreman:spec Build a user authentication system

Requirement → [PM→UX→Tech→QA] → Spec Files → BREAKDOWN Tasks → /run → Implementation

CLI Commands (standalone)

For standalone CLI usage without Claude Code:

Command	Description
`init [goal]`	Initialize or upgrade the harness
`next [feature_id]`	Show next feature to work on
`status`	Show current project status
`check [feature_id]`	Verify code changes or task completion
`done <feature_id>`	Verify, mark complete, and auto-commit
`fail <feature_id>`	Mark a task as failed
`impact <feature_id>`	Analyze impact of changes
`tdd [mode]`	View or set TDD mode
`agents`	Show available AI agents
`install`	Install Claude Code plugin
`uninstall`	Uninstall Claude Code plugin

Workflow

next → implement → check → done → repeat

Step	Command	What Happens
1	`next`	Get task with acceptance criteria
2	implement	Write code to satisfy criteria
3	`check`	Verify implementation
4	`done`	Mark complete, auto-commit

Best Practices

One feature at a time - Complete before switching
Update status promptly - Mark passing when criteria met
Review impact - Run impact analysis after changes
Clean commits - One feature = one atomic commit
Read first - Always check feature list and progress log

Reference

Core Files

File	Purpose
`ai/tasks/index.json`	Task index with status summary
`ai/tasks/{module}/{id}.md`	Individual task definitions
`ai/progress.log`	Session handoff audit log
`ai/init.sh`	Environment bootstrap script
`CLAUDE.md`	AI agent instructions

Status Values

Status	Meaning
`failing`	Not yet implemented
`passing`	Acceptance criteria met
`blocked`	External dependency blocking
`needs_review`	May be affected by changes
`failed`	Verification failed
`deprecated`	No longer needed