$workflow-req-plan "Implement user authentication system with OAuth and 2FA"

**Context Source**: cli-explore-agent (optional) + requirement analysis
**Output Directory**: `.workflow/.req-plan/{session-id}/`
**Core Innovation**: Requirement decomposition → issue creation via `ccw issue create`. Issues stored in `.workflow/issues/issues.jsonl` (single source of truth); wave and dependency info embedded in issue tags and `extended_context.notes`. team-planex consumes issues directly by ID or tag query.

Phase 0: Initialization
   ├─ Parse arguments (--yes, --continue, --mode)
   ├─ Generate session ID (RPLAN-{slug}-{date})
   └─ Create session folder

Phase 1: Requirement Understanding & Strategy Selection
   ├─ Parse requirement: goal / constraints / stakeholders
   ├─ Assess uncertainty level
   │   ├─ High uncertainty → recommend progressive
   │   └─ Low uncertainty  → recommend direct
   ├─ ASK_USER: Confirm strategy (-m skips, -y auto-selects)
   └─ Write strategy-assessment.json + roadmap.md skeleton

Phase 2: Context Collection (Optional, Subagent)
   ├─ Detect codebase: package.json / go.mod / src / ...
   ├─ Has codebase → spawn_agent cli-explore-agent
   │   ├─ Explore relevant modules and patterns
   │   ├─ wait for completion
   │   └─ close_agent
   └─ No codebase → skip, pure requirement decomposition

Phase 3: Decomposition & Issue Creation (Inlined Agent)
   ├─ Step 3.1: CLI-Assisted Decomposition
   │   ├─ Construct CLI prompt with requirement + context + mode
   │   ├─ Execute Gemini (fallback: Qwen → manual decomposition)
   │   └─ Parse CLI output into structured records
   ├─ Step 3.2: Record Enhancement & Validation
   │   ├─ Validate each record against schema
   │   ├─ Enhance convergence criteria quality
   │   ├─ Validate dependency graph (no cycles)
   │   └─ Progressive: verify scope; Direct: verify inputs/outputs
   ├─ Step 3.3: Issue Creation & Output Generation
   │   ├─ Internal records → issue data mapping
   │   ├─ ccw issue create for each item (get ISS-xxx IDs)
   │   └─ Generate roadmap.md with issue ID references
   └─ Step 3.4: Decomposition Quality Check (MANDATORY)
       ├─ Execute CLI quality check (Gemini, Qwen fallback)
       └─ Decision: PASS / AUTO_FIX / NEEDS_REVIEW

Phase 4: Validation & team-planex Handoff
   ├─ Display decomposition results (tabular + convergence criteria)
   ├─ ASK_USER: Feedback loop (up to 5 rounds)
   └─ ASK_USER: Next steps (team-planex / wave-by-wave / view / done)

.workflow/.req-plan/RPLAN-{slug}-{YYYY-MM-DD}/
├── roadmap.md                    # Human-readable roadmap with issue ID references
├── strategy-assessment.json      # Strategy assessment result
└── exploration-codebase.json     # Codebase context (optional)

const agentId = spawn_agent({
  message: `

undefined

const result = wait({
  ids: [agentId],
  timeout_ms: 600000  // 10 minutes
})

if (result.timed_out) {
  // Handle timeout - can send_input to prompt completion
}

close_agent({ id: agentId })

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

// Parse arguments
const args = "$ARGUMENTS"
const AUTO_YES = args.includes('--yes') || args.includes('-y')
const continueMode = args.includes('--continue') || args.includes('-c')
const modeMatch = args.match(/(?:--mode|-m)\s+(progressive|direct|auto)/)
const requestedMode = modeMatch ? modeMatch[1] : 'auto'

// Clean requirement text (remove flags)
const requirement = args
  .replace(/--yes|-y|--continue|-c|--mode\s+\w+|-m\s+\w+/g, '')
  .trim()

const slug = requirement.toLowerCase()
  .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
  .substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = `RPLAN-${slug}-${dateStr}`
const sessionFolder = `${projectRoot}/.workflow/.req-plan/${sessionId}`

bash(`mkdir -p ${sessionFolder}`)

// Utility functions
function fileExists(p) {
  try { return bash(`test -f "${p}" && echo "yes"`).includes('yes') } catch { return false }
}

// 1. Parse Requirement
// - Extract core goal (what to achieve)
// - Identify constraints (tech stack, timeline, compatibility, etc.)
// - Identify stakeholders (users, admins, developers, etc.)
// - Identify keywords to determine domain

// 2. Assess Uncertainty Level
const uncertaintyFactors = {
  scope_clarity: 'low|medium|high',
  technical_risk: 'low|medium|high',
  dependency_unknown: 'low|medium|high',
  domain_familiarity: 'low|medium|high',
  requirement_stability: 'low|medium|high'
}
// high uncertainty (>=3 high) → progressive
// low uncertainty (>=3 low)  → direct
// otherwise → ask user preference

// 3. Strategy Selection
let selectedMode
if (requestedMode !== 'auto') {
  selectedMode = requestedMode
} else if (AUTO_YES) {
  selectedMode = recommendedMode  // use defaults
} else {
  const strategyAnswer = ASK_USER([
    {
      id: "strategy", type: "select",
      prompt: `Decomposition strategy selection:\n\nUncertainty: ${uncertaintyLevel}\nRecommended: ${recommendedMode}\n\nSelect:`,
      options: [
        { label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive",
          description: "Layered MVP→iterations, validate core first" },
        { label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct",
          description: "Topologically-sorted task sequence" }
      ]
    }
  ])  // BLOCKS (wait for user response)
  selectedMode = strategyAnswer.strategy.toLowerCase().includes('progressive') ? 'progressive' : 'direct'
}

// 4. Generate strategy-assessment.json
const strategyAssessment = {
  session_id: sessionId,
  requirement: requirement,
  timestamp: getUtc8ISOString(),
  uncertainty_factors: uncertaintyFactors,
  uncertainty_level: uncertaintyLevel,
  recommended_mode: recommendedMode,
  selected_mode: selectedMode,
  goal: extractedGoal,
  constraints: extractedConstraints,
  stakeholders: extractedStakeholders,
  domain_keywords: extractedKeywords
}
Write(`${sessionFolder}/strategy-assessment.json`, JSON.stringify(strategyAssessment, null, 2))

// 5. Initialize roadmap.md skeleton
const roadmapMdSkeleton = `# Requirement Roadmap

**Session**: ${sessionId}
**Requirement**: ${requirement}
**Strategy**: ${selectedMode}
**Status**: Planning
**Created**: ${getUtc8ISOString()}

**Success Criteria**:
- Requirement goal, constraints, stakeholders identified
- Uncertainty level assessed
- Strategy selected (progressive or direct)
- strategy-assessment.json generated
- roadmap.md skeleton initialized

---

// 1. Detect Codebase
const hasCodebase = bash(`
  test -f package.json && echo "nodejs" ||
  test -f go.mod && echo "golang" ||
  test -f Cargo.toml && echo "rust" ||
  test -f pyproject.toml && echo "python" ||
  test -f pom.xml && echo "java" ||
  test -d src && echo "generic" ||
  echo "none"
`).trim()

// 2. Codebase Exploration (only when hasCodebase !== 'none')
let exploreAgent = null

if (hasCodebase !== 'none') {
  try {
    exploreAgent = spawn_agent({
      message: `

// Wait with timeout handling
let result = wait({ ids: [exploreAgent], timeout_ms: 600000 })

if (result.timed_out) {
  send_input({ id: exploreAgent, message: 'Complete now and write exploration-codebase.json.' })
  result = wait({ ids: [exploreAgent], timeout_ms: 300000 })
  if (result.timed_out) throw new Error('Agent timeout')
}

---

const strategy = JSON.parse(Read(`${sessionFolder}/strategy-assessment.json`))
let explorationContext = null
if (fileExists(`${sessionFolder}/exploration-codebase.json`)) {
  explorationContext = JSON.parse(Read(`${sessionFolder}/exploration-codebase.json`))
}

{
  id: "L{n}",               // L0, L1, L2, L3
  name: string,              // Layer name: MVP / 可用 / 完善 / 优化
  goal: string,              // Layer goal (one sentence)
  scope: [string],           // Features included
  excludes: [string],        // Features explicitly excluded
  convergence: {
    criteria: [string],         // Testable conditions
    verification: string,       // How to verify
    definition_of_done: string  // Business-language completion definition
  },
  risks: [{description, probability, impact, mitigation}],
  effort: "small" | "medium" | "large",
  depends_on: ["L{n}"]
}

{
  id: "T{n}",                // T1, T2, T3, ...
  title: string,
  type: "infrastructure" | "feature" | "enhancement" | "testing",
  scope: string,
  inputs: [string],
  outputs: [string],
  convergence: { criteria, verification, definition_of_done },
  depends_on: ["T{n}"],
  parallel_group: number      // Same group = parallelizable
}

ccw cli -p "
PURPOSE: Decompose requirement into progressive layers (MVP→iterations) with convergence criteria
Success: 2-4 self-contained layers, each with testable convergence, no scope overlap

REQUIREMENT:
${requirement}

STRATEGY CONTEXT:
- Uncertainty: ${strategy.uncertainty_level}
- Goal: ${strategy.goal}
- Constraints: ${strategy.constraints.join(', ')}
- Stakeholders: ${strategy.stakeholders.join(', ')}

${explorationContext ? `CODEBASE CONTEXT:
- Relevant modules: ${explorationContext.relevant_modules.map(m => m.name).join(', ')}
- Existing patterns: ${explorationContext.existing_patterns.map(p => p.pattern).join(', ')}
- Architecture constraints: ${explorationContext.architecture_constraints.join(', ')}
- Tech stack: ${JSON.stringify(explorationContext.tech_stack)}` : 'NO CODEBASE (pure requirement decomposition)'}

TASK:
• Define 2-4 progressive layers from MVP to full implementation
• L0 (MVP): Minimum viable closed loop - core path works end-to-end
• L1 (Usable): Critical user paths, basic error handling
• L2 (Complete): Edge cases, performance, security hardening
• L3 (Optimized): Advanced features, observability, operations support
• Each layer: explicit scope (included) and excludes (not included)
• Each layer: convergence with testable criteria, executable verification, business-language DoD
• Risk items per layer

MODE: analysis
CONTEXT: @**/*
EXPECTED:
For each layer output:

undefined

ccw cli -p "
PURPOSE: Decompose requirement into topologically-sorted task sequence with convergence criteria
Success: Self-contained tasks with clear inputs/outputs, testable convergence, correct dependency order

REQUIREMENT:
${requirement}

STRATEGY CONTEXT:
- Goal: ${strategy.goal}
- Constraints: ${strategy.constraints.join(', ')}

${explorationContext ? `CODEBASE CONTEXT:
- Relevant modules: ${explorationContext.relevant_modules.map(m => m.name).join(', ')}
- Existing patterns: ${explorationContext.existing_patterns.map(p => p.pattern).join(', ')}
- Tech stack: ${JSON.stringify(explorationContext.tech_stack)}` : 'NO CODEBASE (pure requirement decomposition)'}

TASK:
• Decompose into vertical slices with clear boundaries
• Each task: type (infrastructure|feature|enhancement|testing)
• Each task: explicit inputs (what it needs) and outputs (what it produces)
• Each task: convergence with testable criteria, executable verification, business-language DoD
• Topological sort: respect dependency order
• Assign parallel_group numbers (same group = can run in parallel)

MODE: analysis
CONTEXT: @**/*
EXPECTED:
For each task output:

undefined

// Fallback chain: Gemini → Qwen → manual decomposition
try {
  cliOutput = executeCLI('gemini', prompt)
} catch (error) {
  try {
    cliOutput = executeCLI('qwen', prompt)
  } catch {
    // Manual fallback (see Fallback Decomposition below)
    records = selectedMode === 'progressive'
      ? manualProgressiveDecomposition(requirement, explorationContext)
      : manualDirectDecomposition(requirement, explorationContext)
  }
}

// Parse progressive layers from CLI output
function parseProgressiveLayers(cliOutput) {
  const layers = []
  const layerBlocks = cliOutput.split(/## L(\d+):/).slice(1)

  for (let i = 0; i < layerBlocks.length; i += 2) {
    const layerId = `L${layerBlocks[i].trim()}`
    const text = layerBlocks[i + 1]

    const nameMatch = /^(.+?)(?=\n)/.exec(text)
    const goalMatch = /\*\*Goal\*\*:\s*(.+?)(?=\n)/.exec(text)
    const scopeMatch = /\*\*Scope\*\*:\s*(.+?)(?=\n)/.exec(text)
    const excludesMatch = /\*\*Excludes\*\*:\s*(.+?)(?=\n)/.exec(text)
    const effortMatch = /\*\*Effort\*\*:\s*(.+?)(?=\n)/.exec(text)
    const dependsMatch = /\*\*Depends On\*\*:\s*(.+?)(?=\n|$)/.exec(text)
    const riskMatch = /\*\*Risk Items\*\*:\n((?:- .+?\n)*)/.exec(text)

    const convergence = parseConvergence(text)

    layers.push({
      id: layerId,
      name: nameMatch?.[1].trim() || `Layer ${layerId}`,
      goal: goalMatch?.[1].trim() || "",
      scope: scopeMatch?.[1].split(/[,，]/).map(s => s.trim()).filter(Boolean) || [],
      excludes: excludesMatch?.[1].split(/[,，]/).map(s => s.trim()).filter(Boolean) || [],
      convergence,
      risks: riskMatch
        ? riskMatch[1].split('\n').map(s => s.replace(/^- /, '').trim()).filter(Boolean)
            .map(desc => ({description: desc, probability: "Medium", impact: "Medium", mitigation: "N/A"}))
        : [],
      effort: normalizeEffort(effortMatch?.[1].trim()),
      depends_on: parseDependsOn(dependsMatch?.[1], 'L')
    })
  }

  return layers
}

// Parse direct tasks from CLI output
function parseDirectTasks(cliOutput) {
  const tasks = []
  const taskBlocks = cliOutput.split(/## T(\d+):/).slice(1)

  for (let i = 0; i < taskBlocks.length; i += 2) {
    const taskId = `T${taskBlocks[i].trim()}`
    const text = taskBlocks[i + 1]

    const titleMatch = /^(.+?)(?=\n)/.exec(text)
    const typeMatch = /\*\*Type\*\*:\s*(.+?)(?=\n)/.exec(text)
    const scopeMatch = /\*\*Scope\*\*:\s*(.+?)(?=\n)/.exec(text)
    const inputsMatch = /\*\*Inputs\*\*:\s*(.+?)(?=\n)/.exec(text)
    const outputsMatch = /\*\*Outputs\*\*:\s*(.+?)(?=\n)/.exec(text)
    const dependsMatch = /\*\*Depends On\*\*:\s*(.+?)(?=\n|$)/.exec(text)
    const groupMatch = /\*\*Parallel Group\*\*:\s*(\d+)/.exec(text)

    const convergence = parseConvergence(text)

    tasks.push({
      id: taskId,
      title: titleMatch?.[1].trim() || `Task ${taskId}`,
      type: normalizeType(typeMatch?.[1].trim()),
      scope: scopeMatch?.[1].trim() || "",
      inputs: parseList(inputsMatch?.[1]),
      outputs: parseList(outputsMatch?.[1]),
      convergence,
      depends_on: parseDependsOn(dependsMatch?.[1], 'T'),
      parallel_group: parseInt(groupMatch?.[1]) || 1
    })
  }

  return tasks
}

// Parse convergence section from a record block
function parseConvergence(text) {
  const criteriaMatch = /- Criteria:\s*((?:.+\n?)+?)(?=- Verification:)/.exec(text)
  const verificationMatch = /- Verification:\s*(.+?)(?=\n- Definition)/.exec(text)
  const dodMatch = /- Definition of Done:\s*(.+?)(?=\n\*\*|$)/.exec(text)

  const criteria = criteriaMatch
    ? criteriaMatch[1].split('\n')
        .map(s => s.replace(/^\s*[-•]\s*/, '').trim())
        .filter(s => s && !s.startsWith('Verification') && !s.startsWith('Definition'))
    : []

  return {
    criteria: criteria.length > 0 ? criteria : ["Task completed successfully"],
    verification: verificationMatch?.[1].trim() || "Manual verification",
    definition_of_done: dodMatch?.[1].trim() || "Feature works as expected"
  }
}

// Helpers
function normalizeEffort(effort) {
  if (!effort) return "medium"
  const lower = effort.toLowerCase()
  if (lower.includes('small') || lower.includes('low')) return "small"
  if (lower.includes('large') || lower.includes('high')) return "large"
  return "medium"
}

function normalizeType(type) {
  if (!type) return "feature"
  const lower = type.toLowerCase()
  if (lower.includes('infra')) return "infrastructure"
  if (lower.includes('enhance')) return "enhancement"
  if (lower.includes('test')) return "testing"
  return "feature"
}

function parseList(text) {
  if (!text || text.toLowerCase() === 'none') return []
  return text.split(/[,，]/).map(s => s.trim()).filter(Boolean)
}

function parseDependsOn(text, prefix) {
  if (!text || text.toLowerCase() === 'none' || text === '[]') return []
  const pattern = new RegExp(`${prefix}\\d+`, 'g')
  return (text.match(pattern) || [])
}

// Manual decomposition when CLI fails
function manualProgressiveDecomposition(requirement, context) {
  return [
    {
      id: "L0", name: "MVP", goal: "最小可用闭环",
      scope: ["核心功能"], excludes: ["高级功能", "优化"],
      convergence: {
        criteria: ["核心路径端到端可跑通"],
        verification: "手动测试核心流程",
        definition_of_done: "用户可完成一次核心操作的完整流程"
      },
      risks: [{description: "技术选型待验证", probability: "Medium", impact: "Medium", mitigation: "待评估"}],
      effort: "medium", depends_on: []
    },
    {
      id: "L1", name: "可用", goal: "关键用户路径完善",
      scope: ["错误处理", "输入校验"], excludes: ["性能优化", "监控"],
      convergence: {
        criteria: ["所有用户输入有校验", "错误场景有提示"],
        verification: "单元测试 + 手动测试错误场景",
        definition_of_done: "用户遇到问题时有清晰的引导和恢复路径"
      },
      risks: [], effort: "medium", depends_on: ["L0"]
    }
  ]
}

function manualDirectDecomposition(requirement, context) {
  return [
    {
      id: "T1", title: "基础设施搭建", type: "infrastructure",
      scope: "项目骨架和基础配置",
      inputs: [], outputs: ["project-structure"],
      convergence: {
        criteria: ["项目可构建无报错", "基础配置完成"],
        verification: "npm run build (或对应构建命令)",
        definition_of_done: "项目基础框架就绪，可开始功能开发"
      },
      depends_on: [], parallel_group: 1
    },
    {
      id: "T2", title: "核心功能实现", type: "feature",
      scope: "核心业务逻辑",
      inputs: ["project-structure"], outputs: ["core-module"],
      convergence: {
        criteria: ["核心 API/功能可调用", "返回预期结果"],
        verification: "运行核心功能测试",
        definition_of_done: "核心业务功能可正常使用"
      },
      depends_on: ["T1"], parallel_group: 2
    }
  ]
}