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)

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 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

Collect all Q&A from Phase 2/2.5 into a formatted summary:

qa_decisions = """
### Scope Decisions
- Q: [Question from PM] → A: [User answer]
- Q: [Question from PM] → A: [User answer]

### UX Decisions
- Q: [Question from UX] → A: [User answer]

### Technical Decisions
- Q: [Question from Tech] → A: [User answer]

### Quality Decisions
- Q: [Question from QA] → A: [User answer]
"""

Step 2: Delegate to Breakdown Writer

Launch the breakdown-writer agent:

Task(
  subagent_type="agent-foreman:breakdown-writer",
  prompt="""
SPEC BREAKDOWN TASK

## Context
- Requirement: {requirement}
- Mode: {quick|deep}
- Date: {YYYY-MM-DD}
- Project: {codebase_context}

## Q&A Decisions
{qa_decisions}

## Your Mission
1. Read all spec files (PM.md, UX.md, TECH.md, QA.md)
2. Create OVERVIEW.md with executive summaries
3. Create BREAKDOWN tasks for all modules (devops first, integration last)
4. Run `agent-foreman status` to verify index update
5. Return structured result

## Output Format
Return result block at END:
---BREAKDOWN RESULT---
overview_created: true|false
modules_created: [devops, module1, ..., integration]
tasks_created: N
index_updated: true|false
status: success|partial|failed
errors: []
notes: "summary"
---END BREAKDOWN RESULT---
"""
)

Step 3: Parse Result

Parse ---BREAKDOWN RESULT--- from agent output:

If status == "success":
  → Display success message with modules_created
  → Continue to Phase 4

If status == "partial":
  → Display warning with errors
  → Continue to Phase 4 (partial results may be usable)

If status == "failed":
  → Display error message
  → Show errors list
  → Stop workflow, user must investigate

Step 4: Confirm to User

After successful delegation, output:

Spec breakdown complete!

Created:
- ai/tasks/spec/OVERVIEW.md (executive summaries)
- ai/tasks/devops/BREAKDOWN.md (priority: 0)
- ai/tasks/{module}/BREAKDOWN.md (priority: N)
- ...
- ai/tasks/integration/BREAKDOWN.md (priority: 999999)

Total: {tasks_created} BREAKDOWN tasks registered.

Why Delegate?

1. Context preservation - Main session only sees prompt + result (~1.5KB vs ~20KB)
2. File reading isolated - Agent reads 4 large spec files in its own context
3. Error handling - Agent handles errors autonomously, returns structured result
4. Files are persistent - Agent writes directly, files survive context limits

Fallback: Manual Execution

If delegation fails, you can manually execute Phase 3 by:

1. Reading spec files (PM.md, UX.md, TECH.md, QA.md)
2. Creating OVERVIEW.md with the template from breakdown-writer agent
3. Creating BREAKDOWN files for each module
4. Running agent-foreman status to verify index update

---

Phase 4: Module Breakdown (User-Driven)

After spec generation, guide the user to process all BREAKDOWN tasks.

Next Steps Output (CONSOLE ONLY - NOT IN OVERVIEW.md)

⚠️ IMPORTANT: This output is displayed to the user in the console/terminal. It is NOT written to any file.

Display the following guidance to the user:

## Next Steps

To process all BREAKDOWN tasks and create fine-grained implementation tasks:

/agent-foreman:run

Alternatively, to process a specific module:

/agent-foreman:run {module}.BREAKDOWN

What Happens During Run

The /agent-foreman:run command uses the standard Bash workflow for each task:

# For each BREAKDOWN task, executes:
agent-foreman next <task_id>    # 1. Get task details
# ... implement task ...         # 2. Create implementation tasks
agent-foreman check <task_id>   # 3. Verify
agent-foreman done <task_id>    # 4. Complete + commit
# Loop to next BREAKDOWN

For each BREAKDOWN task, the AI will:

1. Run agent-foreman next to get task details and spec context
2. Read all spec documents from ai/tasks/spec/ (PM.md, UX.md, TECH.md, QA.md, OVERVIEW.md)
3. Create fine-grained implementation tasks in ai/tasks/{module}/
4. Run agent-foreman check and agent-foreman done to verify and complete
5. Automatically continue to the next BREAKDOWN

---

Phase 5: Validation

Note: The done command automatically triggers validation instructions when all BREAKDOWNs complete.

After all BREAKDOWN tasks are complete, run validation:

agent-foreman validate

This spawns 4 validators in parallel to check task quality.

---

Task Output Conventions

All generated tasks MUST follow agent-foreman format.

Task ID Patterns

• BREAKDOWN tasks: {module}.BREAKDOWN (e.g., auth.BREAKDOWN)
• Implementation tasks: {module}.{task-name} (e.g., auth.oauth-google)

Task Markdown Format

---
id: module.task-name
module: module-name
priority: N
status: failing
version: 1
origin: spec-workflow
dependsOn: []
tags: []
testRequirements:
  unit:
    required: false
    pattern: "tests/{module}/**/*.test.*"
---
# Task Title

## Context
[Brief context from spec documents]

## Acceptance Criteria
1. [Specific, testable criterion]
2. [Specific, testable criterion]
3. [Error handling criterion]

## Technical Notes
- Reference: [From spec/OVERVIEW.md]
- UX: [From spec/UX.md]
- Test: [From spec/QA.md]

Markdown Formatting Rules

CRITICAL: Always include blank lines:

• Before EVERY ## heading (blank line required)
• After EVERY ## heading (blank line required)
• Between list items and headings

Granularity

Break into SMALLEST implementable units. Each task should be:

• Atomic: One focused piece of work
• Independent: Can be implemented without waiting (except explicit deps)
• Testable: Has clear, verifiable acceptance criteria
• Completable: 1-3 hours of work

---

Rules

1. Agents write their own files - Each agent writes directly to ai/tasks/spec/{ROLE}.md
2. Agents read previous files - UX reads PM.md, Tech reads PM.md+UX.md, QA reads all
3. No conversation context reliance - Always read files explicitly
4. Research first - Every agent conducts web research before analysis
5. Mode first - Ask user to choose Quick/Deep mode
6. Bookend modules - Always create devops (first) and integration (last)
7. OVERVIEW is summary only - Don't duplicate detailed analysis in OVERVIEW.md
8. Questions output separately - Agents write analysis to file, but output questions directly using ---QUESTIONS FOR USER--- format
9. Q&A timing differs by mode:
   • Quick Mode: Collect all questions after all agents complete, merge duplicates, ask once
   • Deep Mode: Ask questions IMMEDIATELY after each agent completes (PM→Q&A→UX→Q&A→Tech→Q&A→QA→Q&A), so subsequent agents can use answers
10. Deep Mode sequential dependency - In Deep Mode, NEVER launch the next agent until the previous agent's Q&A is complete and written to file
11. No "Next Steps" in OVERVIEW.md - OVERVIEW.md is a reference document that ends with "Module Roadmap". The "Next Steps" guidance is console output ONLY (Phase 4), never written to OVERVIEW.md or any spec file

---

Research Best Practices

Effective Search Queries

Use specific, targeted queries:

Agent	Good Query Examples
PM	"[industry] product metrics KPIs 2024", "[product type] market size trends"
UX	"[component] UX pattern best practices", "WCAG 2.2 [element] accessibility"
Tech	"[framework] architecture patterns", "OWASP [vulnerability] prevention"
QA	"[framework] testing best practices", "[tool] performance benchmarks"

Research Synthesis

Each agent should:

1. Conduct 2-4 targeted web searches
2. Extract key findings with sources
3. Apply findings to the specific requirement
4. Include citations in the Research Findings section

When to Research More

• New/unfamiliar domain → More PM research
• Complex UI requirements → More UX research
• Novel tech stack → More Tech research
• High-risk project → More QA research