mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-28 09:23:08 +08:00

Files

catlog22 02250bd4dc Refactor code structure for improved readability and maintainability

2026-02-16 13:09:47 +08:00

26 KiB

Raw Blame History

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
req-plan-with-file	Requirement-level progressive roadmap planning with issue creation. Decomposes requirements into convergent layers or task sequences, creates issues via ccw issue create, and generates execution-plan.json for team-planex consumption.	[-y\|--yes] [-c\|--continue] [-m\|--mode progressive\|direct\|auto] "requirement description"	TodoWrite(), Task(), AskUserQuestion(), Read(), Grep(), Glob(), Bash(), Edit(), Write(*)

Auto Mode

When --yes or -y: Auto-confirm strategy selection, use recommended mode, skip interactive validation rounds.

Workflow Req-Plan Command (/workflow:req-plan-with-file)

Quick Start

# Basic usage
/workflow:req-plan-with-file "Implement user authentication system with OAuth and 2FA"

# With mode selection
/workflow:req-plan-with-file -m progressive "Build real-time notification system"   # Layered MVP→iterations
/workflow:req-plan-with-file -m direct "Refactor payment module"                   # Topologically-sorted task sequence
/workflow:req-plan-with-file -m auto "Add data export feature"                     # Auto-select strategy

# Continue existing session
/workflow:req-plan-with-file --continue "user authentication system"

# Auto mode
/workflow:req-plan-with-file -y "Implement caching layer"

Context Source: cli-explore-agent (optional) + requirement analysis Output Directory: .workflow/.req-plan/{session-id}/ Core Innovation: Requirement decomposition → issue creation → execution-plan.json for team-planex consumption. Each issue is standard issues-jsonl-schema format, bridging req-plan to team-planex execution pipeline.

Overview

Requirement-level layered roadmap planning command. Decomposes a requirement into convergent layers or task sequences, creates issues via ccw issue create, and generates execution-plan.json for team-planex consumption.

Dual Modes:

Progressive: Layered MVP→iterations, suitable for high-uncertainty requirements (validate first, then refine)
Direct: Topologically-sorted task sequence, suitable for low-uncertainty requirements (clear tasks, directly ordered)
Auto: Automatically selects based on uncertainty level

Core Workflow: Requirement Understanding → Strategy Selection → Context Collection (optional) → Decomposition + Issue Creation → Validation → team-planex Handoff

┌─────────────────────────────────────────────────────────────────────────┐
│                    REQ-PLAN ROADMAP WORKFLOW                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 1: Requirement Understanding & Strategy Selection                 │
│     ├─ Parse requirement: goal / constraints / stakeholders              │
│     ├─ Assess uncertainty level                                          │
│     │   ├─ High uncertainty → recommend progressive                      │
│     │   └─ Low uncertainty  → recommend direct                           │
│     ├─ User confirms strategy (-m skips, -y auto-selects recommended)    │
│     └─ Initialize strategy-assessment.json + roadmap.md skeleton         │
│                                                                          │
│  Phase 2: Context Collection (Optional)                                  │
│     ├─ Detect codebase: package.json / go.mod / src / ...                │
│     ├─ Has codebase → cli-explore-agent explores relevant modules        │
│     └─ No codebase  → skip, pure requirement decomposition               │
│                                                                          │
│  Phase 3: Decomposition & Issue Creation (cli-roadmap-plan-agent)        │
│     ├─ Progressive: define 2-4 layers, each with full convergence        │
│     ├─ Direct: vertical slicing + topological sort, each with convergence│
│     ├─ Create issues via ccw issue create (ISS-xxx IDs)                  │
│     ├─ Generate execution-plan.json (waves + dependencies)               │
│     ├─ Generate issues.jsonl (session copy)                              │
│     └─ Generate roadmap.md (with issue ID references)                    │
│                                                                          │
│  Phase 4: Validation & team-planex Handoff                               │
│     ├─ Display decomposition results (tabular + convergence criteria)    │
│     ├─ User feedback loop (up to 5 rounds)                               │
│     └─ Next steps: team-planex full execution / wave-by-wave / view      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Output

.workflow/.req-plan/RPLAN-{slug}-{YYYY-MM-DD}/
├── roadmap.md                    # Human-readable roadmap with issue ID references
├── issues.jsonl                  # Standard issues-jsonl-schema format (session copy)
├── execution-plan.json           # Wave grouping + issue dependencies (team-planex bridge)
├── strategy-assessment.json      # Strategy assessment result
└── exploration-codebase.json     # Codebase context (optional)

File	Phase	Description
`strategy-assessment.json`	1	Uncertainty analysis + mode recommendation + extracted goal/constraints/stakeholders
`roadmap.md` (skeleton)	1	Initial skeleton with placeholders, finalized in Phase 3
`exploration-codebase.json`	2	Codebase context: relevant modules, patterns, integration points (only when codebase exists)
`issues.jsonl`	3	Standard issues-jsonl-schema records, one per line (session copy of created issues)
`execution-plan.json`	3	Wave grouping with issue dependencies for team-planex consumption
`roadmap.md` (final)	3	Human-readable roadmap with issue ID references, convergence details, team-planex execution guide

roadmap.md template:

# Requirement Roadmap

**Session**: RPLAN-{slug}-{date}
**Requirement**: {requirement}
**Strategy**: {progressive|direct}
**Generated**: {timestamp}

## Strategy Assessment
- Uncertainty level: {high|medium|low}
- Decomposition mode: {progressive|direct}
- Assessment basis: {factors summary}

## Roadmap
{Tabular display of layers/tasks}

## Convergence Criteria Details
{Expanded convergence for each layer/task}

## Risks
{Aggregated risks}

## Next Steps
{Execution guidance}

Configuration

Flag	Default	Description
`-y, --yes`	false	Auto-confirm all decisions
`-c, --continue`	false	Continue existing session
`-m, --mode`	auto	Decomposition strategy: progressive / direct / auto

Session ID format: RPLAN-{slug}-{YYYY-MM-DD}

slug: lowercase, alphanumeric + CJK characters, max 40 chars
date: YYYY-MM-DD (UTC+8)
Auto-detect continue: session folder + roadmap.jsonl exists → continue mode

JSONL Schema Design

Issue Format (issues.jsonl)

Each line in issues.jsonl follows the standard issues-jsonl-schema.json (see .ccw/workflows/cli-templates/schemas/issues-jsonl-schema.json).

Key fields per issue:

Field	Source	Description
`id`	`ccw issue create`	Formal ISS-YYYYMMDD-NNN ID
`title`	Layer/task mapping	`[LayerName] goal` or `[TaskType] title`
`context`	Convergence fields	Markdown with goal, scope, convergence criteria, verification, DoD
`priority`	Effort mapping	small→4, medium→3, large→2
`source`	Fixed	`"text"`
`tags`	Auto-generated	`["req-plan", mode, name/type, "wave-N"]`
`extended_context.notes`	Metadata JSON	session, strategy, original_id, wave, depends_on_issues
`lifecycle_requirements`	Fixed	test_strategy, regression_scope, acceptance_type, commit_strategy

Execution Plan Format (execution-plan.json)

{
  "session_id": "RPLAN-{slug}-{date}",
  "requirement": "Original requirement description",
  "strategy": "progressive|direct",
  "created_at": "ISO 8601",
  "issue_ids": ["ISS-xxx", "ISS-yyy"],
  "waves": [
    {
      "wave": 1,
      "label": "MVP",
      "issue_ids": ["ISS-xxx"],
      "depends_on_waves": []
    },
    {
      "wave": 2,
      "label": "Usable",
      "issue_ids": ["ISS-yyy"],
      "depends_on_waves": [1]
    }
  ],
  "issue_dependencies": {
    "ISS-yyy": ["ISS-xxx"]
  }
}

Wave mapping:

Progressive mode: each layer → one wave (L0→Wave 1, L1→Wave 2, ...)
Direct mode: each parallel_group → one wave (group 1→Wave 1, group 2→Wave 2, ...)

Convergence Criteria (in issue context)

Each issue's context field contains convergence information:

Section	Purpose	Requirement
`## Convergence Criteria`	List of checkable specific conditions	Testable (can be written as assertions or manual steps)
`## Verification`	How to verify these conditions	Executable (command, script, or explicit steps)
`## Definition of Done`	One-sentence completion definition	Business language (non-technical person can judge)

Implementation

Session Initialization

Objective: Create session context and directory structure.

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

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

// Clean requirement text (remove flags)
const requirement = $ARGUMENTS
  .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 = `.workflow/.req-plan/${sessionId}`

// Auto-detect continue: session folder + roadmap.jsonl exists → continue mode
Bash(`mkdir -p ${sessionFolder}`)

Phase 1: Requirement Understanding & Strategy Selection

Objective: Parse requirement, assess uncertainty, select decomposition strategy.

Prerequisites: Session initialized, requirement description available.

Steps:

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

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

Strategy Selection (skip if -m already specified)

if (requestedMode !== 'auto') {
  selectedMode = requestedMode
} else if (autoYes) {
  selectedMode = recommendedMode
} else {
  AskUserQuestion({
    questions: [{
      question: `Decomposition strategy selection:\n\nUncertainty assessment: ${uncertaintyLevel}\nRecommended strategy: ${recommendedMode}\n\nSelect decomposition strategy:`,
      header: "Strategy",
      multiSelect: false,
      options: [
        {
          label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive",
          description: "Layered MVP→iterations, validate core first then refine progressively. Suitable for high-uncertainty requirements needing quick validation"
        },
        {
          label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct",
          description: "Topologically-sorted task sequence with explicit dependencies. Suitable for clear requirements with confirmed technical approach"
        }
      ]
    }]
  })
}

Generate strategy-assessment.json

const strategyAssessment = {
  session_id: sessionId,
  requirement: requirement,
  timestamp: getUtc8ISOString(),
  uncertainty_factors: uncertaintyFactors,
  uncertainty_level: uncertaintyLevel,  // 'high' | 'medium' | 'low'
  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))

Initialize roadmap.md skeleton (placeholder sections, finalized in Phase 4)
```
const roadmapMdSkeleton = `# Requirement Roadmap
```

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

Strategy Assessment

Uncertainty level: ${uncertaintyLevel}
Decomposition mode: ${selectedMode}

Roadmap

To be populated after Phase 3 decomposition

Convergence Criteria Details

To be populated after Phase 3 decomposition

Risk Items

To be populated after Phase 3 decomposition

Next Steps

To be populated after Phase 4 validation Write(${sessionFolder}/roadmap.md`, roadmapMdSkeleton)


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

### Phase 2: Context Collection (Optional)

**Objective**: If a codebase exists, collect relevant context to enhance decomposition quality.

**Prerequisites**: Phase 1 complete.

**Steps**:

1. **Detect Codebase**

```javascript
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()

Codebase Exploration (only when hasCodebase !== 'none')

if (hasCodebase !== 'none') {
  Task({
    subagent_type: "cli-explore-agent",
    run_in_background: false,
    description: `Explore codebase: ${slug}`,
    prompt: `
## Exploration Context
Requirement: ${requirement}
Strategy: ${selectedMode}
Project Type: ${hasCodebase}
Session: ${sessionFolder}

## MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Execute relevant searches based on requirement keywords
3. Read: .workflow/project-tech.json (if exists)
4. Read: .workflow/project-guidelines.json (if exists)

## Exploration Focus
- Identify modules/components related to the requirement
- Find existing patterns that should be followed
- Locate integration points for new functionality
- Assess current architecture constraints

## Output
Write findings to: ${sessionFolder}/exploration-codebase.json

Schema: {
  project_type: "${hasCodebase}",
  relevant_modules: [{name, path, relevance}],
  existing_patterns: [{pattern, files, description}],
  integration_points: [{location, description, risk}],
  architecture_constraints: [string],
  tech_stack: {languages, frameworks, tools},
  _metadata: {timestamp, exploration_scope}
}
`
  })
}
// No codebase → skip, proceed directly to Phase 3

Success Criteria:

Codebase detection complete
When codebase exists, exploration-codebase.json generated
When no codebase, skipped and logged

Phase 3: Decomposition & Issue Creation

Objective: Execute requirement decomposition via cli-roadmap-plan-agent, creating issues and generating execution-plan.json + issues.jsonl + roadmap.md.

Prerequisites: Phase 1, Phase 2 complete. Strategy selected. Context collected (if applicable).

Agent: cli-roadmap-plan-agent (dedicated requirement roadmap planning agent, supports CLI-assisted decomposition + issue creation + built-in quality checks)

Steps:

Prepare Context

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

Invoke cli-roadmap-plan-agent

The agent internally executes a 5-phase flow:

Phase 1: Context loading + requirement analysis
Phase 2: CLI-assisted decomposition (Gemini → Qwen → manual fallback)
Phase 3: Record enhancement + validation (schema compliance, dependency checks, convergence quality)
Phase 4: Issue creation + output generation (ccw issue create → execution-plan.json → issues.jsonl → roadmap.md)
Phase 5: CLI decomposition quality check (MANDATORY - requirement coverage, convergence criteria quality, dependency correctness)

Task({
  subagent_type: "cli-roadmap-plan-agent",
  run_in_background: false,
  description: `Roadmap decomposition: ${slug}`,
  prompt: `
## Roadmap Decomposition Task

### Input Context
- **Requirement**: ${requirement}
- **Selected Mode**: ${selectedMode}
- **Session ID**: ${sessionId}
- **Session Folder**: ${sessionFolder}

### Strategy Assessment
${JSON.stringify(strategy, null, 2)}

### Codebase Context
${explorationContext
  ? `File: ${sessionFolder}/exploration-codebase.json\n${JSON.stringify(explorationContext, null, 2)}`
  : 'No codebase detected - pure requirement decomposition'}

### Issue Creation
- Use \`ccw issue create\` for each decomposed item
- Issue format: issues-jsonl-schema (id, title, status, priority, context, source, tags, extended_context)
- Write \`execution-plan.json\` with wave groupings + issue dependencies
- Write \`issues.jsonl\` session copy
- Update \`roadmap.md\` with issue ID references

### CLI Configuration
- Primary tool: gemini
- Fallback: qwen
- Timeout: 60000ms

### Expected Output
1. **${sessionFolder}/issues.jsonl** - Session copy of created issues (standard issues-jsonl-schema)
2. **${sessionFolder}/execution-plan.json** - Wave grouping + issue dependencies
3. **${sessionFolder}/roadmap.md** - Human-readable roadmap with issue references
4. Issues created in \`.workflow/issues/issues.jsonl\` via ccw issue create

### Mode-Specific Requirements

${selectedMode === 'progressive' ? `**Progressive Mode**:
- 2-4 layers from MVP to full implementation
- Each layer: id (L0-L3), name, goal, scope, excludes, convergence, risks, effort, depends_on
- L0 (MVP) must be a self-contained closed loop with no dependencies
- Scope: each feature belongs to exactly ONE layer (no overlap)
- Layer names: MVP / Usable / Refined / Optimized` :

`**Direct Mode**:
- Topologically-sorted task sequence
- Each task: id (T1-Tn), title, type, scope, inputs, outputs, convergence, depends_on, parallel_group
- Inputs must come from preceding task outputs or existing resources
- Tasks in same parallel_group must be truly independent`}

### Convergence Quality Requirements
- criteria[]: MUST be testable (can write assertions or manual verification steps)
- verification: MUST be executable (command, script, or explicit steps)
- definition_of_done: MUST use business language (non-technical person can judge)

### Execution
1. Analyze requirement and build decomposition context
2. Execute CLI-assisted decomposition (Gemini, fallback Qwen)
3. Parse output, validate records, enhance convergence quality
4. Create issues via ccw issue create, generate execution-plan.json + issues.jsonl + roadmap.md
5. Execute mandatory quality check (Phase 5)
6. Return brief completion summary
`
})

Success Criteria:

Issues created via ccw issue create, each with formal ISS-xxx ID
issues.jsonl generated, each line independently JSON.parse-able, conforms to issues-jsonl-schema
execution-plan.json generated with correct wave groupings and issue dependencies
roadmap.md generated with issue ID references
Agent's internal quality check passed
No circular dependencies
Progressive: 2-4 layers, no scope overlap
Direct: tasks have explicit inputs/outputs, parallel_group assigned

Phase 4: Validation & team-planex Handoff

Objective: Display decomposition results, collect user feedback, provide team-planex execution options.

Prerequisites: Phase 3 complete, issues created, execution-plan.json generated.

Steps:

Display Decomposition Results (tabular format)

// Read execution plan for display
const executionPlan = JSON.parse(Read(`${sessionFolder}/execution-plan.json`))
const issueIds = executionPlan.issue_ids
const waves = executionPlan.waves

Progressive Mode:

## Roadmap Overview

| Wave | Issue ID | Name | Goal | Priority |
|------|----------|------|------|----------|
| 1 | ISS-xxx | MVP | ... | 2 |
| 2 | ISS-yyy | Usable | ... | 3 |

### Convergence Criteria
**Wave 1 - MVP (ISS-xxx)**:
- Criteria: [criteria list]
- Verification: [verification]
- Definition of Done: [definition_of_done]

Direct Mode:

## Task Sequence

| Wave | Issue ID | Title | Type | Dependencies |
|------|----------|-------|------|--------------|
| 1 | ISS-xxx | ... | infrastructure | - |
| 2 | ISS-yyy | ... | feature | ISS-xxx |

### Convergence Criteria
**Wave 1 - ISS-xxx**:
- Criteria: [criteria list]
- Verification: [verification]
- Definition of Done: [definition_of_done]

User Feedback Loop (up to 5 rounds, skipped when autoYes)

if (!autoYes) {
  let round = 0
  let continueLoop = true

  while (continueLoop && round < 5) {
    round++
    const feedback = AskUserQuestion({
      questions: [{
        question: `Roadmap validation (round ${round}):\nAny feedback on the current decomposition?`,
        header: "Feedback",
        multiSelect: false,
        options: [
          { label: "Approve", description: "Decomposition is reasonable, proceed to next steps" },
          { label: "Adjust Scope", description: "Some issue scopes need adjustment" },
          { label: "Modify Convergence", description: "Convergence criteria are not specific or testable enough" },
          { label: "Re-decompose", description: "Overall strategy or layering approach needs change" }
        ]
      }]
    })

    if (feedback === 'Approve') {
      continueLoop = false
    } else {
      // Handle adjustment based on feedback type
      // After adjustment, re-display and return to loop top
    }
  }
}

Post-Completion Options

if (!autoYes) {
  AskUserQuestion({
    questions: [{
      question: `路线图已生成，${issueIds.length} 个 issues 已创建。下一步：`,
      header: "Next Step",
      multiSelect: false,
      options: [
        { label: "Execute with team-planex", description: `启动 team-planex 执行全部 ${issueIds.length} 个 issues（${waves.length} 个波次）` },
        { label: "Execute first wave", description: `仅执行 Wave 1: ${waves[0].label}` },
        { label: "View issues", description: "查看已创建的 issue 详情" },
        { label: "Done", description: "保存路线图，稍后执行" }
      ]
    }]
  })
}

Selection	Action
Execute with team-planex	`Skill(skill="team-planex", args="--plan ${sessionFolder}/execution-plan.json")`
Execute first wave	`Skill(skill="team-planex", args="${waves[0].issue_ids.join(' ')}")`
View issues	Display issues summary table from issues.jsonl
Done	Display file paths, end

Success Criteria:

User feedback processed (or skipped via autoYes)
Post-completion options provided
team-planex handoff available via execution-plan.json

Error Handling

Error	Resolution
cli-explore-agent failure	Skip code exploration, proceed with pure requirement decomposition
No codebase	Normal flow, skip Phase 2
Circular dependency detected	Prompt user to adjust dependencies, re-decompose
User feedback timeout	Save current state, display `--continue` recovery command
Max feedback rounds reached	Use current version to generate final artifacts
Session folder conflict	Append timestamp suffix
JSONL format error	Validate line by line, report problematic lines and fix

Best Practices

Clear requirement description: Detailed description → more accurate uncertainty assessment and decomposition
Validate MVP first: In progressive mode, L0 should be the minimum verifiable closed loop
Testable convergence: criteria must be writable as assertions or manual steps; definition_of_done should be judgeable by non-technical stakeholders (see Convergence Criteria in JSONL Schema Design)
Agent-First for Exploration: Delegate codebase exploration to cli-explore-agent, do not analyze directly in main flow
Incremental validation: Use --continue to iterate on existing roadmaps
team-planex integration: Issues created follow standard issues-jsonl-schema, directly consumable by team-planex via execution-plan.json

Now execute req-plan-with-file for: $ARGUMENTS

26 KiB Raw Blame History Unescape Escape

Auto Mode

Workflow Req-Plan Command (/workflow:req-plan-with-file)

Quick Start

Overview

Output

Configuration

JSONL Schema Design

Issue Format (issues.jsonl)

Execution Plan Format (execution-plan.json)

Convergence Criteria (in issue context)

Implementation

Session Initialization

Phase 1: Requirement Understanding & Strategy Selection

Strategy Assessment

Roadmap

Convergence Criteria Details

Risk Items

Next Steps

Phase 3: Decomposition & Issue Creation

Phase 4: Validation & team-planex Handoff

Error Handling

Best Practices

26 KiB

Raw Blame History