mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-27 09:13:07 +08:00
feat(skill-hub): add refresh parameter to bypass cache in remote skills endpoint
This commit is contained in:
catlog22
@@ -1,682 +0,0 @@
|
||||
---
|
||||
name: req-plan-with-file
|
||||
description: Requirement-level progressive roadmap planning with issue creation. Decomposes requirements into convergent layers or task sequences, creates issues via ccw issue create, and generates roadmap.md for human review. Issues stored in .workflow/issues/issues.jsonl (single source of truth).
|
||||
argument-hint: "[-y|--yes] [-c|--continue] [-m|--mode progressive|direct|auto] \"requirement description\""
|
||||
---
|
||||
|
||||
# Codex Req-Plan-With-File Prompt
|
||||
|
||||
## Overview
|
||||
|
||||
Requirement-level layered roadmap planning command. Decomposes a requirement into **convergent layers or task sequences**, creates issues via `ccw issue create`. Issues are the single source of truth in `.workflow/issues/issues.jsonl`; wave and dependency info is embedded in issue tags and `extended_context.notes`.
|
||||
|
||||
**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/dependency info embedded in issue tags (`wave-N`) and `extended_context.notes.depends_on_issues`. issue-devpipeline consumes issues directly by ID or tag query.
|
||||
|
||||
**Core workflow**: Requirement Understanding → Strategy Selection → Context Collection (optional) → Decomposition + Issue Creation → Validation → issue-devpipeline Handoff
|
||||
|
||||
**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 assessment
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm strategy selection, use recommended mode, skip interactive validation rounds.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/codex:req-plan-with-file "Implement user authentication system with OAuth and 2FA"
|
||||
|
||||
# With mode selection
|
||||
/codex:req-plan-with-file -m progressive "Build real-time notification system"
|
||||
/codex:req-plan-with-file -m direct "Refactor payment module"
|
||||
/codex:req-plan-with-file -m auto "Add data export feature"
|
||||
|
||||
# Continue existing session
|
||||
/codex:req-plan-with-file --continue "user authentication system"
|
||||
|
||||
# Auto mode (skip all confirmations)
|
||||
/codex:req-plan-with-file -y "Implement caching layer"
|
||||
```
|
||||
|
||||
## Target Requirement
|
||||
|
||||
**$ARGUMENTS**
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 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 roadmap.md (with issue ID references) │
|
||||
│ │
|
||||
│ Phase 4: Validation & issue-devpipeline Handoff │
|
||||
│ ├─ Display decomposition results (tabular + convergence criteria) │
|
||||
│ ├─ User feedback loop (up to 5 rounds) │
|
||||
│ └─ Next steps: issue-devpipeline full execution / wave-by-wave / view│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 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.md exists → continue mode
|
||||
|
||||
## Output
|
||||
|
||||
```
|
||||
.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)
|
||||
```
|
||||
|
||||
| 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) |
|
||||
| `roadmap.md` (final) | 3 | Human-readable roadmap with issue ID references, convergence details, issue-devpipeline execution guide |
|
||||
|
||||
**roadmap.md template**:
|
||||
|
||||
```markdown
|
||||
# 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}
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Session Setup
|
||||
|
||||
##### Step 0: Initialize Session
|
||||
|
||||
```javascript
|
||||
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
|
||||
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.md 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**:
|
||||
|
||||
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**
|
||||
|
||||
```javascript
|
||||
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** (skip if `-m` already specified)
|
||||
|
||||
```javascript
|
||||
if (requestedMode !== 'auto') {
|
||||
selectedMode = requestedMode
|
||||
} else if (autoYes) {
|
||||
selectedMode = recommendedMode
|
||||
} else {
|
||||
Ask_question({
|
||||
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"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
4. **Generate strategy-assessment.json**
|
||||
|
||||
```javascript
|
||||
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))
|
||||
```
|
||||
|
||||
5. **Initialize roadmap.md skeleton** (placeholder sections, finalized in Phase 4)
|
||||
|
||||
```javascript
|
||||
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()
|
||||
```
|
||||
|
||||
2. **Codebase Exploration** (only when hasCodebase !== 'none')
|
||||
|
||||
```javascript
|
||||
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 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**:
|
||||
|
||||
1. **Prepare Context**
|
||||
|
||||
```javascript
|
||||
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`))
|
||||
}
|
||||
```
|
||||
|
||||
2. **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 + roadmap generation (ccw issue create → roadmap.md)
|
||||
- Phase 5: CLI decomposition quality check (**MANDATORY** - requirement coverage, convergence criteria quality, dependency correctness)
|
||||
|
||||
```javascript
|
||||
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)
|
||||
- Update \`roadmap.md\` with issue ID references
|
||||
|
||||
### CLI Configuration
|
||||
- Primary tool: gemini
|
||||
- Fallback: qwen
|
||||
- Timeout: 60000ms
|
||||
|
||||
### Expected Output
|
||||
1. **${sessionFolder}/roadmap.md** - Human-readable roadmap with issue references
|
||||
2. 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 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
|
||||
- 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 & issue-devpipeline Handoff
|
||||
|
||||
**Objective**: Display decomposition results, collect user feedback, provide issue-devpipeline execution options.
|
||||
|
||||
**Prerequisites**: Phase 3 complete, issues created, roadmap.md generated.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Display Decomposition Results** (tabular format)
|
||||
|
||||
```javascript
|
||||
// Use issueIdMap from Phase 3 for display
|
||||
const issueIds = Object.values(issueIdMap)
|
||||
```
|
||||
|
||||
**Progressive Mode**:
|
||||
```markdown
|
||||
## 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**:
|
||||
```markdown
|
||||
## 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]
|
||||
```
|
||||
|
||||
2. **User Feedback Loop** (up to 5 rounds, skipped when autoYes)
|
||||
|
||||
```javascript
|
||||
if (!autoYes) {
|
||||
let round = 0
|
||||
let continueLoop = true
|
||||
|
||||
while (continueLoop && round < 5) {
|
||||
round++
|
||||
const feedback = Ask_question({
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Post-Completion Options**
|
||||
|
||||
```javascript
|
||||
if (!autoYes) {
|
||||
Ask_question({
|
||||
questions: [{
|
||||
question: `路线图已生成，${issueIds.length} 个 issues 已创建。下一步：`,
|
||||
header: "Next Step",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Execute with issue-devpipeline", description: `启动 issue-devpipeline 执行全部 ${issueIds.length} 个 issues` },
|
||||
{ label: "Execute first wave", description: "仅执行 Wave 1（按 wave-1 tag 筛选）" },
|
||||
{ label: "View issues", description: "查看已创建的 issue 详情" },
|
||||
{ label: "Done", description: "保存路线图，稍后执行" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
| Selection | Action |
|
||||
|-----------|--------|
|
||||
| Execute with issue-devpipeline | `/codex:issue-devpipeline "${issueIds.join(' ')}"` |
|
||||
| Execute first wave | Filter issues by `wave-1` tag, pass to issue-devpipeline |
|
||||
| View issues | Display issues summary from `.workflow/issues/issues.jsonl` |
|
||||
| Done | Display file paths, end |
|
||||
|
||||
**Success Criteria**:
|
||||
- User feedback processed (or skipped via autoYes)
|
||||
- Post-completion options provided
|
||||
- issue-devpipeline handoff available via issue IDs
|
||||
|
||||
## JSONL Schema Design
|
||||
|
||||
### Issue Format
|
||||
|
||||
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 |
|
||||
|
||||
### 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) |
|
||||
|
||||
### Progressive Mode Layers
|
||||
|
||||
| Layer | Title | Typical Description |
|
||||
|-------|-------|---------------------|
|
||||
| L0 | MVP | Minimum viable closed loop, core path end-to-end |
|
||||
| L1 | Usable | Key user paths refined, basic error handling |
|
||||
| L2 | Refined | Edge cases, performance, security hardening |
|
||||
| L3 | Optimized | Advanced features, observability, operations |
|
||||
|
||||
**Constraints**: 2-4 layers, L0 must be a self-contained closed loop with no dependencies, each feature belongs to exactly ONE layer (no scope overlap).
|
||||
|
||||
### Direct Mode Tasks
|
||||
|
||||
| Type | Use Case |
|
||||
|------|----------|
|
||||
| infrastructure | Data models, configuration, scaffolding |
|
||||
| feature | API, UI, business logic implementation |
|
||||
| enhancement | Validation, error handling, edge cases |
|
||||
| testing | Unit tests, integration tests, E2E |
|
||||
|
||||
**Constraints**: Inputs must come from preceding task outputs or existing resources, tasks in same parallel_group must be truly independent, no circular dependencies.
|
||||
|
||||
## Convergence Quality Requirements
|
||||
|
||||
Every convergence field MUST satisfy these quality standards:
|
||||
|
||||
| Field | Requirement | Bad Example | Good Example |
|
||||
|-------|-------------|-------------|--------------|
|
||||
| `criteria[]` | **Testable** - can write assertions or manual steps | `"System works correctly"` | `"API returns 200 and response body contains user_id field"` |
|
||||
| `verification` | **Executable** - command, script, or clear steps | `"Check it"` | `"jest --testPathPattern=auth && curl -s localhost:3000/health"` |
|
||||
| `definition_of_done` | **Business language** - non-technical person can judge | `"Code compiles"` | `"New user can complete register→login→perform core operation flow"` |
|
||||
|
||||
**NEVER** output vague convergence criteria ("works correctly", "system is normal"). **ALWAYS** ensure:
|
||||
- criteria are testable (can be written as assertions or manual verification steps)
|
||||
- verification is executable (commands or explicit steps)
|
||||
- definition_of_done uses business language (non-technical stakeholders can judge)
|
||||
|
||||
## 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 |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear requirement description**: Detailed description → more accurate uncertainty assessment and decomposition
|
||||
2. **Validate MVP first**: In progressive mode, L0 should be the minimum verifiable closed loop
|
||||
3. **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)
|
||||
4. **Agent-First for Exploration**: Delegate codebase exploration to cli-explore-agent, do not analyze directly in main flow
|
||||
5. **Incremental validation**: Use `--continue` to iterate on existing roadmaps
|
||||
6. **issue-devpipeline integration**: Issues created follow standard issues-jsonl-schema, directly consumable by issue-devpipeline via issue IDs and tags
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use req-plan-with-file when:**
|
||||
- You need to decompose a large requirement into a progressively executable roadmap
|
||||
- Unsure where to start, need an MVP strategy
|
||||
- Need to generate a trackable task sequence for the team
|
||||
- Requirement involves multiple stages or iterations
|
||||
|
||||
**Use lite-plan when:**
|
||||
- You have a clear single task to execute
|
||||
- The requirement is already a layer/task from the roadmap
|
||||
- No layered planning needed
|
||||
|
||||
**Use collaborative-plan-with-file when:**
|
||||
- A single complex task needs multi-agent parallel planning
|
||||
- Need to analyze the same task from multiple domain perspectives
|
||||
|
||||
**Use analyze-with-file when:**
|
||||
- Need in-depth analysis of a technical problem
|
||||
- Not about planning execution, but understanding and discussion
|
||||
|
||||
---
|
||||
|
||||
**Now execute the req-plan-with-file workflow for**: $ARGUMENTS
|
||||
@@ -226,7 +226,7 @@ function getCategoryName(category: TemplateCategory, formatMessage: ReturnType<t
|
||||
export function HookQuickTemplates({
|
||||
onInstallTemplate,
|
||||
installedTemplates,
|
||||
isLoading = false,
|
||||
isLoading: _isLoading = false,
|
||||
installingTemplateId = null
|
||||
}: HookQuickTemplatesProps) {
|
||||
const { formatMessage } = useIntl();
|
||||
|
||||
@@ -893,6 +893,18 @@ export async function handleSkillHubRoutes(ctx: RouteContext): Promise<boolean>
|
||||
// GET /api/skill-hub/remote
|
||||
if (pathname === '/api/skill-hub/remote' && req.method === 'GET') {
|
||||
try {
|
||||
// Check for refresh parameter to bypass cache
|
||||
const refresh = ctx.url.searchParams.get('refresh') === 'true';
|
||||
if (refresh) {
|
||||
// Clear memory cache
|
||||
remoteSkillsCache = { data: null, timestamp: 0 };
|
||||
// Clear file cache
|
||||
const cachedPath = join(getSkillHubDir(), 'index.json');
|
||||
if (existsSync(cachedPath)) {
|
||||
rmSync(cachedPath, { force: true });
|
||||
}
|
||||
}
|
||||
|
||||
const index = await fetchRemoteSkillIndex();
|
||||
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
|
||||
Reference in New Issue
Block a user