mylukin/agent-foreman

mylukin/agent-foreman · 1 plugin

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

Install

The repo has no one-line install. Follow its README.

Open the repo

Plugins 1

After adding the marketplace, install one with /plugin install <name>@agent-foreman-plugins.

1agent-foremanLong Task Harness providing external memory, feature-driven workflow, and clean agent handoffs/plugin install agent-foreman@agent-foreman-pluginsv0.2.1

Files

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

Why It Works

AI agents need the same tooling that makes human teams effective:

Human Practice	AI Equivalent
Scrum board	`ai/tasks/index.json`
Sprint notes	`progress.log`
CI/CD pipeline	`init.sh check`
Code review	Acceptance criteria

License

MIT

Author

Lukin (@mylukin)

Inspired by Anthropic's blog post: Effective harnesses for long-running agents

.claude-plugin/marketplace.json

{
  "name": "agent-foreman-plugins",
  "owner": {
    "name": "Lukin",
    "email": "mylukin@gmail.com",
    "url": "https://github.com/mylukin"
  },
  "metadata": {
    "description": "Long Task Harness for AI agents - feature-driven development with external memory",
    "version": "0.2.1"
  },
  "plugins": [
    {
      "name": "agent-foreman",
      "source": "./plugins/agent-foreman",
      "description": "Long Task Harness providing external memory, feature-driven workflow, and clean agent handoffs",
      "version": "0.2.1",
      "author": {
        "name": "Lukin",
        "url": "https://github.com/mylukin"
      },
      "homepage": "https://github.com/mylukin/agent-foreman",
      "repository": "https://github.com/mylukin/agent-foreman",
      "license": "MIT",
      "keywords": [
        "long-task",
        "harness",
        "feature-driven",
        "agent-memory",
        "handoff",
        "ai-agent",
        "claude-code"
      ],
      "agents": [
        "./agents/foreman.md",
        "./agents/pm.md",
        "./agents/ux.md",
        "./agents/tech.md",
        "./agents/qa.md",
        "./agents/breakdown-writer.md",
        "./agents/implementer.md"
      ],
      "skills": [
        "./skills/project-analyze",
        "./skills/init-harness",
        "./skills/foreman-spec",
        "./skills/feature-next",
        "./skills/feature-run"
      ]
    }
  ]
}

Facts

Kind: Marketplace
Repo: mylukin/agent-foreman
Group: Uncategorized
Marketplace name: agent-foreman-plugins
Owner: Lukin
Language: TypeScript
Created: 2025-11-28
Forks: 20
Plugins: 1