/foreman-spec

name: foreman-spec
description: 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'.
allowed-tools: [Read, Write, Glob, Grep, AskUserQuestion, Bash, Task]
user-invocable: true

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_PROJECT

Step 2: Analyze Requirement Complexity

• Count features mentioned in requirement
• Detect uncertainty words ("maybe", "or", "not sure", "possibly")
• If >3 features OR uncertainty words → COMPLEX
• Otherwise → SIMPLE

Step 3: Determine Recommendation

IF NEW_PROJECT OR COMPLEX:
  recommendation = "Deep Mode"
ELSE:
  recommendation = "Quick Mode"

Step 4: Ask User

Use AskUserQuestion tool:

{
  "question": "How would you like to analyze this requirement?",
  "header": "Mode",
  "options": [
    {
      "label": "Quick Mode (Recommended)" or "Quick Mode",
      "description": "4 experts analyze in parallel, ~3 min, one combined Q&A at the end. Best for clear requirements."
    },
    {
      "label": "Deep Mode (Recommended)" or "Deep Mode",
      "description": "4 experts analyze sequentially, ~8 min, Q&A after EACH expert (answers inform next expert). Best for complex/new projects."
    }
  ],
  "multiSelect": false
}

Place "(Recommended)" on the recommended mode based on Step 3.

---

Phase 1: Codebase Scan

Scan the project to understand existing patterns.

Actions

1. Use Glob to find key files:

• `README.md`, `ARCHITECTURE.md`, `CLAUDE.md`
• `package.json`, `pyproject.toml`, `go.mod`
• `src/**/*.ts`, `src/**/*.py`, `src/**/*.go` (sample files)

2. Read project configuration to detect:

• Language and framework
• Testing patterns
• Existing conventions

3. Create context summary for agents:

• Project type (web app, CLI, API, etc.)
• Tech stack (language, framework, database)
• Existing patterns to follow

---

Phase 1.5: Research Context (NEW)

Before launching agents, prepare research context based on the requirement.

Research Domains

Identify which areas need research based on the requirement:

| Requirement Type | Research Focus | |-----------------|----------------| | New product | Market analysis, competitor products, industry trends | | New feature | Similar implementations, UX patterns, technical approaches | | Integration | API documentation, security best practices, compatibility | | Performance | Benchmarks, optimization techniques, scalability patterns |

Generate Research Keywords

Extract keywords from the requirement for targeted searches:

Requirement: "Build a real-time chat application with end-to-end encryption"

Research keywords:
- "real-time chat architecture 2024 2025"
- "WebSocket vs Server-Sent Events comparison"
- "end-to-end encryption implementation best practices"
- "chat application UX patterns"
- "Signal Protocol implementation guide"

Pass Research Context to Agents

Include research keywords in agent prompts:

research_context = {
  "domain": "[product domain]",
  "keywords": ["keyword1", "keyword2", "keyword3"],
  "tech_stack": "[detected or proposed stack]",
  "competitors": ["competitor1", "competitor2"]
}

**IMPORTANT**: Each agent will conduct its own targeted research using these keywords. The research phase is built into each agent's workflow, not a separate step.

---

Phase 2: Analysis (Mode-Dependent)

Quick Mode (Parallel)

Launch all 4 agents IN PARALLEL using Task tool. Each agent will conduct web research before analysis:

Task(subagent_type="agent-foreman:pm", prompt="Analyze requirement: {requirement}. Project context: {codebase_context}. Research context: {research_context}. IMPORTANT: Use WebSearch to research industry best practices before analysis.")

Task(subagent_type="agent-foreman:ux", prompt="Design UX for: {requirement}. Project context: {codebase_context}. Research context: {research_context}. IMPORTANT: Use WebSearch to research UX patterns before design.")

Task(subagent_type="agent-foreman:tech", prompt="Design architecture for: {requirement}. Project context: {codebase_context}. Research context: {research_context}. IMPORTANT: Use Web