agent-foreman
Long Task Harness providing external memory, feature-driven workflow, and clean agent handoffs
View on GitHubTable of content
Long Task Harness providing external memory, feature-driven workflow, and clean agent handoffs
Installation
npx claude-plugins install @mylukin/agent-foreman-plugins/agent-foreman
Contents
Folders: agents, commands, skills
Included Skills
This plugin includes 5 skill definitions:
feature-next
Implements a single task following the next → implement → check → done workflow with TDD support. Use when working on one specific task, implementing a single feature from the backlog, or following TDD red-green-refactor cycle. Triggers on ’next task’, ’next feature’, ‘implement feature’, ‘work on feature’, ‘single task mode’, ‘what should I work on’.
View skill definition
Task Next
One command: agent-foreman next
⚠️ STRICT WORKFLOW - NO IMPROVISATION
You MUST follow this exact sequence. Do NOT skip or reorder steps.
next → implement → check → done
| ❌ FORBIDDEN | ✅ REQUIRED |
|---|---|
Skip check step | Run agent-foreman check before done |
| Go straight to implementation | Run agent-foreman next first |
| Invent extra steps | Use only the 4 steps above |
⛔ CLI-ONLY ENFORCEMENT
NEVER bypass CLI for workflow decisions:
| ❌ FORBIDDEN | ✅ REQUIRED |
|---|---|
Read ai/tasks/index.json to select task | Use agent-foreman next |
Read index.json to check status | Use agent-foreman status |
Read index.json for TDD mode | Check CLI output for !!! TDD ENFORCEMENT ACTIVE !!! |
| Edit task files to change status | Use agent-foreman done/fail |
Allowed: Reading task .md files for acceptance criteria AFTER running agent-foreman next.
Quick Start
agent-foreman next # Auto-select next priority
agent-foreman next auth.login # Specific task
Workflow
next → implement → check → done
agent-foreman next # 1. Get task + acceptance criteria
# ... implement the task ... # 2. Write code
agent-foreman check <id> # 3. Verify implementation
agent-foreman done <id> # 4. Mark complete + commit
Check TDD Mode First
Look for “!!! TDD ENFORCEMENT ACTIVE !!!” in `agen
…(truncated)
feature-run
Executes unattended batch processing of all pending tasks with autonomous decision-making. Use when running all tasks automatically, batch processing without supervision, completing entire feature backlog, or working on a specific task by ID. Triggers on ‘run all tasks’, ‘complete all features’, ‘batch processing’, ‘unattended mode’, ‘auto-complete tasks’, ‘run feature’.
View skill definition
Task Run
Mode: Work on all tasks or a specific one
⚠️ STRICT WORKFLOW - NO IMPROVISATION
You MUST follow this exact sequence for EVERY task. Do NOT skip or reorder steps.
next → implement → check → done
| ❌ FORBIDDEN | ✅ REQUIRED |
|---|---|
Skip check step | Run agent-foreman check before done |
| Go straight to implementation | Run agent-foreman next first |
| Invent extra steps | Use only the 4 steps above |
| Reorder the workflow | Execute in exact sequence |
⛔ CLI-ONLY ENFORCEMENT
NEVER bypass CLI for workflow decisions:
| ❌ FORBIDDEN | ✅ REQUIRED |
|---|---|
Read ai/tasks/index.json to select task | Use agent-foreman next |
Read index.json to check status | Use agent-foreman status |
| Read task files to check status | Use CLI commands |
| Edit task files to change status | Use agent-foreman done/fail |
This applies to ALL iterations in the loop.
⚡ UNATTENDED MODE (when no task_id provided)
- NO questions allowed
- NO stopping for errors
- MUST complete all tasks
Mode Detection
If task_id provided (e.g., feature-run auth.login):
- Work on that specific task only
- Complete it and stop
If no task_id (e.g., feature-run):
- Auto-complete all pending tasks
- Loop until all done
- UNATTENDED MODE ACTIVE - see rules below
Single Task Mode
When task_id is provided:
# STEP 1: Delegate to implementer agent
Task(
subagent_
...(truncated)
</details>
### foreman-spec
> Multi-role requirement analysis and task breakdown workflow using 4 specialized AI agents (PM, UX, Tech, QA). Each agent conducts web research before analysis to gather industry best practices, case studies, and current trends. Supports Quick Mode (parallel, ~3 min, one Q&A session) and Deep Mode (serial, ~8 min, Q&A after EACH agent so answers inform subsequent analysis). Triggers on 'foreman-spec', 'spec feature', 'break down requirement', 'define tasks', 'spec this'.
<details>
<summary>View skill definition</summary>
# Spec Workflow (V8 - Research-Enhanced)
Multi-role requirement analysis using 4 specialized AI agents, each equipped with web research capabilities.
## Overview
Transform a high-level requirement into fine-grained, implementable tasks through multi-perspective analysis.
**Key Feature: Research-First Approach**
Each agent conducts web research BEFORE analysis to:
- Gather industry best practices and standards
- Find case studies and competitor implementations
- Discover current trends and proven patterns
- Ground recommendations in real-world data
**Agents** (all equipped with WebSearch):
- agent-foreman:pm (Product Manager) - Clarifies WHAT and WHY, researches market/industry
- agent-foreman:ux (UX/UI Designer) - Designs HOW users interact, researches UX patterns
- agent-foreman:tech (Technical Architect) - Architects HOW to build, researches frameworks/security
- agent-foreman:qa (QA Manager) - Plans HOW to verify, researches testing strategies
**Modes**:
- Quick Mode (parallel) - ~3-4 min, includes research, one combined Q&A session at the end
- Deep Mode (serial) - ~8-10 min, comprehensive research, Q&A after EACH agent (4 sessions, each answer informs subsequent agents)
---
## Phase 0: Mode Selection
Before any analysis, detect project state and ask user to choose mode.
### Step 1: Scan Codebase
Use Glob to detect project state:
Check if ai/tasks/ exists → EXISTING_PROJECT Check if package.json or pyproject.toml exists → EXISTING_PROJECT Otherwise → NEW_
…(truncated)
init-harness
Creates AI agent task management structure with feature backlog (ai/tasks/), TDD enforcement, and progress tracking. Use when setting up agent-foreman, initializing feature-driven development, creating task backlog, or enabling TDD mode. Triggers on ‘init harness’, ‘setup feature tracking’, ‘create feature backlog’, ’enable strict TDD’, ‘initialize agent-foreman’.
View skill definition
⚡ Init Harness
One command: agent-foreman init
Quick Start
agent-foreman init
Creates: ai/tasks/, ai/progress.log, ai/init.sh, CLAUDE.md
TDD Mode (Default: Recommended)
During init, you’ll be prompted for TDD mode. Recommended is the default (tests suggested but not required).
| User Says | TDD Mode | Effect |
|---|---|---|
| “strict TDD” / “require tests” | strict | Tests REQUIRED - check/done fail without tests |
| “recommended” / “optional tests” / (default) | recommended | Tests suggested but not enforced |
| “disable TDD” / “no TDD” | disabled | No TDD guidance |
The prompt auto-skips after 10 seconds with recommended mode.
Modes
| Mode | Command | Effect |
|---|---|---|
| Merge (default) | agent-foreman init | Keep existing + add new features |
| Fresh | agent-foreman init --mode new | Replace all features |
| Preview | agent-foreman init --mode scan | Show without changes |
Task Types
| Type | Command | Use Case |
|---|---|---|
| Code (default) | agent-foreman init | Software development |
| Ops | agent-foreman init --task-type ops | Operational tasks, runbooks |
| Data | agent-foreman init --task-type data | ETL, data pipelines |
| Infra | agent-foreman init --task-type infra | Infrastructure provisioning |
| Manual | agent-foreman init --task-type manual | Manual-only verification |
Auto-Detection
ARCHITECTURE.mdexists → use it (f
…(truncated)
project-analyze
Scans codebases to generate architecture documentation (ARCHITECTURE.md). Use when joining an existing project, understanding codebase structure, exploring project architecture, or preparing for agent-foreman init. Triggers on ‘analyze project’, ‘understand codebase’, ’explore architecture’, ‘scan project structure’, ‘survey project’.
View skill definition
🔍 Project Analyze
One command: agent-foreman init --analyze
Quick Start
agent-foreman init --analyze
Output: docs/ARCHITECTURE.md
Options
| Flag | Effect |
|---|---|
--analyze-output ./path/FILE.md | Custom output path |
--verbose | Show detailed progress |
Use When
- Joining existing project → understand before changing
- Before
agent-foreman init→ faster initialization
Skip When
- New/empty project → use
agent-foreman initdirectly
Read-Only
No code changes. No commits. Safe to run anytime.