foreman-spec

What this skill does

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

```json
{
  "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 Architec