mylukin/agent-foreman/foreman-spec

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)

1. Read project configuration to detect:

• Language and framework
• Testing patterns
• Existing conventions

1. 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:

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 WebSearch to research framework best practices before architecture.")
 
Task(subagent_type="agent-foreman:qa", prompt="Define QA strategy for: {requirement}. Project context: {codebase_context}. Research context: {research_context}. IMPORTANT: Use WebSearch to research testing strategies before planning.")

Wait for all to complete (~30-60 seconds).

Then: Merge questions from all 4 agents:

• Remove duplicates (similar questions from different roles)
• Group by topic
• Prioritize: blocking questions first
• Limit: max 10-12 questions total

Then: Present merged questions to user in one AskUserQuestion call.

Deep Mode (Serial with Immediate Q&A)

Launch agents ONE AT A TIME. CRITICAL: After each agent completes, immediately collect their questions, ask the user, and write answers to the spec file BEFORE launching the next agent.

This ensures:

• Each agent's questions are answered immediately
• Subsequent agents can see previous answers in the spec files
• User maintains focus on one perspective at a time

Step 2A: Product Manager

Task(subagent_type="agent-foreman:pm", prompt="Analyze requirement: {requirement}. Project context: {codebase_context}. Research context: {research_context}. CRITICAL: Use WebSearch FIRST to research industry best practices, market trends, and competitor approaches before starting your analysis.")

Wait for completion. PM will:

1. Conduct web research on industry/market
2. Write analysis to ai/tasks/spec/PM.md
3. Output questions using ---QUESTIONS FOR USER--- format

→ SKILL Orchestrator Actions (MANDATORY):

1. Parse PM's ---QUESTIONS FOR USER--- output
2. Use AskUserQuestion to present PM's questions to user
3. Write Q&A section to ai/tasks/spec/PM.md
4. Only then proceed to Step 2B

Step 2B: UX Designer

Task(subagent_type="agent-foreman:ux", prompt="Design UX for: {requirement}. IMPORTANT: First read ai/tasks/spec/PM.md to see PM's analysis AND user's answers to PM questions. Research context: {research_context}. CRITICAL: Use WebSearch FIRST to research UX patterns before starting your design.")

Wait for completion. UX will:

1. Read PM.md (including Q&A section with user answers)
2. Conduct UX-specific research
3. Write analysis to ai/tasks/spec/UX.md
4. Output questions using ---QUESTIONS FOR USER--- format

→ SKILL Orchestrator Actions (MANDATORY):

1. Parse UX's ---QUESTIONS FOR USER--- output
2. Use AskUserQuestion to present UX's questions to user
3. Write Q&A section to ai/tasks/spec/UX.md
4. Only then proceed to Step 2C

Step 2C: Technical Architect

Task(subagent_type="agent-foreman:tech", prompt="Design architecture for: {requirement}. IMPORTANT: First read ai/tasks/spec/PM.md and ai/tasks/spec/UX.md to see previous analyses AND user's answers. Research context: {research_context}. CRITICAL: Use WebSearch FIRST to research framework best practices before starting your design.")

Wait for completion. Tech will:

1. Read PM.md and UX.md (including Q&A sections)
2. Conduct tech-specific research
3. Write analysis to ai/tasks/spec/TECH.md
4. Output questions using ---QUESTIONS FOR USER--- format

→ SKILL Orchestrator Actions (MANDATORY):

1. Parse Tech's ---QUESTIONS FOR USER--- output
2. Use AskUserQuestion to present Tech's questions to user
3. Write Q&A section to ai/tasks/spec/TECH.md
4. Only then proceed to Step 2D

Step 2D: QA Manager

Task(subagent_type="agent-foreman:qa", prompt="Define QA strategy for: {requirement}. IMPORTANT: First read all spec files (PM.md, UX.md, TECH.md) including their Q&A sections. Research context: {research_context}. CRITICAL: Use WebSearch FIRST to research testing strategies before defining your strategy.")

Wait for completion. QA will:

1. Read all previous spec files (including Q&A sections)
2. Conduct QA-specific research
3. Write analysis to ai/tasks/spec/QA.md
4. Output questions using ---QUESTIONS FOR USER--- format

→ SKILL Orchestrator Actions (MANDATORY):

1. Parse QA's ---QUESTIONS FOR USER--- output
2. Use AskUserQuestion to present QA's questions to user (if any)
3. Write Q&A section to ai/tasks/spec/QA.md
4. Proceed to Phase 3 (Create Overview)

Phase 2.5: Question Collection & User Interaction

This phase applies ONLY to Quick Mode. In Deep Mode, questions are handled inline after each agent (see above).

Quick Mode Question Flow

After all 4 agents complete in parallel, handle questions:

Step 1: Extract Questions

Each agent outputs questions using this format (NOT written to file):

---QUESTIONS FOR USER---
1. **[Question text]**
   - Why: [reason]
   - Options: A) ... B) ... C) ...
   - Recommend: [option] because [rationale]
---END QUESTIONS---

Parse each agent's output and extract questions from the ---QUESTIONS FOR USER--- section.

Step 2: Merge and Deduplicate

1. Remove duplicates - Similar questions from different roles (e.g., both PM and Tech asking about auth method)
2. Group by topic - Organize related questions together
3. Prioritize blocking questions first - Questions that block other roles' work
4. Limit total - Max 10-12 questions to avoid overwhelming user

Step 3: Ask User

Use AskUserQuestion tool to present merged questions interactively:

{
  "questions": [
    {
      "question": "[Merged question text]",
      "header": "[Topic - max 12 chars]",
      "options": [
        {"label": "[Option A] (Recommended)", "description": "[Why recommended]"},
        {"label": "[Option B]", "description": "[What this means]"}
      ],
      "multiSelect": false
    }
  ]
}

Step 4: Write Answers to Files

After user answers, append Q&A section to EACH relevant spec file:

## Questions & Answers
 
### Q1: [Question text]
**Answer**: [User's selected option]
**Impact**: [How this affects this role's analysis]
 
### Q2: [Question text]
**Answer**: [User's selected option]
**Impact**: [How this affects this role's analysis]

For each file, only include questions relevant to that role:

• PM.md: Business/scope questions
• UX.md: Design/flow questions
• TECH.md: Architecture/implementation questions
• QA.md: Testing/quality questions

Phase 3: Create Overview & Breakdown Tasks (DELEGATED)

After Phase 2.5 (Q&A) completes, delegate to breakdown-writer agent.

Phase 3 requires significant context (reading 4 spec files, creating N+2 task files). Delegating to a subagent preserves main session context for subsequent interactions.

Step 1: Compile Q&A Decisions