mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
feat: Add interactive pre-flight checklists for ccw-loop and workflow-plan, including validation and task transformation steps
- Implemented `prep-loop.md` for ccw-loop, detailing source discovery, validation, task transformation, and auto-loop configuration. - Created `prep-plan.md` for workflow planning, covering environment checks, task quality assessment, execution preferences, and final confirmation. - Defined schemas and integration points for `prep-package.json` in both ccw-loop and workflow-plan skills, ensuring proper validation and task handling. - Added error handling mechanisms for various scenarios during the preparation phases.
This commit is contained in:
catlog22
456
.codex/prompts/prep-loop.md
Normal file
456
.codex/prompts/prep-loop.md
Normal file
@@ -0,0 +1,456 @@
|
||||
---
|
||||
description: "Interactive pre-flight checklist for ccw-loop. Discovers JSONL from collaborative-plan-with-file, analyze-with-file, brainstorm-to-cycle sessions; validates, transforms to ccw-loop task format, writes prep-package.json + tasks.jsonl, then launches the loop."
|
||||
argument-hint: '[SOURCE="<path-to-tasks.jsonl-or-session-folder>"] [MAX_ITER=10]'
|
||||
---
|
||||
|
||||
# Pre-Flight Checklist for CCW Loop
|
||||
|
||||
You are an interactive preparation assistant. Your job is to discover and consume task artifacts from upstream planning/analysis/brainstorm skills, validate them, transform into ccw-loop's task format, and launch an **unattended** development loop. Follow each step sequentially. **Ask the user questions when information is missing.**
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Source Discovery
|
||||
|
||||
### 1.1 Auto-Detect Available Sessions
|
||||
|
||||
Scan for upstream artifacts from the three supported source skills:
|
||||
|
||||
```javascript
|
||||
const projectRoot = Bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
|
||||
|
||||
// Source 1: collaborative-plan-with-file
|
||||
const cplanSessions = Glob(`${projectRoot}/.workflow/.planning/CPLAN-*/tasks.jsonl`)
|
||||
.map(p => ({
|
||||
path: p,
|
||||
source: 'collaborative-plan-with-file',
|
||||
type: 'jsonl',
|
||||
session: p.match(/CPLAN-[^/]+/)?.[0],
|
||||
mtime: fs.statSync(p).mtime
|
||||
}))
|
||||
|
||||
// Source 2: analyze-with-file
|
||||
const anlSessions = Glob(`${projectRoot}/.workflow/.analysis/ANL-*/tasks.jsonl`)
|
||||
.map(p => ({
|
||||
path: p,
|
||||
source: 'analyze-with-file',
|
||||
type: 'jsonl',
|
||||
session: p.match(/ANL-[^/]+/)?.[0],
|
||||
mtime: fs.statSync(p).mtime
|
||||
}))
|
||||
|
||||
// Source 3: brainstorm-to-cycle
|
||||
const bsSessions = Glob(`${projectRoot}/.workflow/.brainstorm/*/cycle-task.md`)
|
||||
.map(p => ({
|
||||
path: p,
|
||||
source: 'brainstorm-to-cycle',
|
||||
type: 'markdown',
|
||||
session: p.match(/\.brainstorm\/([^/]+)/)?.[1],
|
||||
mtime: fs.statSync(p).mtime
|
||||
}))
|
||||
|
||||
const allSources = [...cplanSessions, ...anlSessions, ...bsSessions]
|
||||
.sort((a, b) => b.mtime - a.mtime) // Most recent first
|
||||
```
|
||||
|
||||
### 1.2 Display Discovered Sources
|
||||
|
||||
```
|
||||
可用的上游任务源
|
||||
════════════════
|
||||
|
||||
collaborative-plan-with-file:
|
||||
1. CPLAN-auth-redesign-20260208 tasks.jsonl (5 tasks, 2h ago)
|
||||
2. CPLAN-api-cleanup-20260205 tasks.jsonl (3 days ago)
|
||||
|
||||
analyze-with-file:
|
||||
3. ANL-perf-audit-20260207 tasks.jsonl (8 tasks, 1d ago)
|
||||
|
||||
brainstorm-to-cycle:
|
||||
4. BS-notification-system cycle-task.md (1d ago)
|
||||
|
||||
手动输入:
|
||||
5. 自定义路径 (输入 JSONL 文件路径或任务描述)
|
||||
```
|
||||
|
||||
### 1.3 User Selection
|
||||
|
||||
Ask the user to select a source:
|
||||
|
||||
> "请选择任务来源（输入编号），或输入 JSONL 文件的完整路径:
|
||||
> 也可以输入 'manual' 手动输入任务描述（不使用上游 JSONL）"
|
||||
|
||||
**If `$SOURCE` argument provided**, skip discovery and use directly:
|
||||
|
||||
```javascript
|
||||
if (options.SOURCE) {
|
||||
// Validate path exists
|
||||
if (!fs.existsSync(options.SOURCE)) {
|
||||
console.error(`文件不存在: ${options.SOURCE}`)
|
||||
return
|
||||
}
|
||||
selectedSource = {
|
||||
path: options.SOURCE,
|
||||
source: inferSource(options.SOURCE),
|
||||
type: options.SOURCE.endsWith('.jsonl') ? 'jsonl' : 'markdown'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Source Validation & Task Loading
|
||||
|
||||
### 2.1 For JSONL Sources (collaborative-plan / analyze-with-file)
|
||||
|
||||
```javascript
|
||||
function validateAndLoadJsonl(jsonlPath) {
|
||||
const content = Read(jsonlPath)
|
||||
const lines = content.trim().split('\n').filter(l => l.trim())
|
||||
const tasks = []
|
||||
const errors = []
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
try {
|
||||
const task = JSON.parse(lines[i])
|
||||
|
||||
// Required fields check
|
||||
const requiredFields = ['id', 'title', 'description']
|
||||
const missing = requiredFields.filter(f => !task[f])
|
||||
if (missing.length > 0) {
|
||||
errors.push(`Line ${i + 1}: missing fields: ${missing.join(', ')}`)
|
||||
continue
|
||||
}
|
||||
|
||||
// Validate task structure
|
||||
if (task.id && task.title && task.description) {
|
||||
tasks.push(task)
|
||||
}
|
||||
} catch (e) {
|
||||
errors.push(`Line ${i + 1}: invalid JSON: ${e.message}`)
|
||||
}
|
||||
}
|
||||
|
||||
return { tasks, errors, total_lines: lines.length }
|
||||
}
|
||||
```
|
||||
|
||||
Display validation results:
|
||||
|
||||
```
|
||||
JSONL 验证
|
||||
══════════
|
||||
文件: .workflow/.planning/CPLAN-auth-redesign-20260208/tasks.jsonl
|
||||
来源: collaborative-plan-with-file
|
||||
|
||||
✓ 5/5 行解析成功
|
||||
✓ 必需字段完整 (id, title, description)
|
||||
✓ 3 个任务含收敛标准 (convergence)
|
||||
⚠ 2 个任务缺少收敛标准 (将使用默认)
|
||||
|
||||
任务列表:
|
||||
TASK-001 [high] Implement JWT token service (feature, 3 files)
|
||||
TASK-002 [high] Add OAuth2 Google strategy (feature, 2 files)
|
||||
TASK-003 [medium] Create user session middleware (feature, 4 files)
|
||||
TASK-004 [low] Add rate limiting to auth endpoints (enhancement, 2 files)
|
||||
TASK-005 [low] Write integration tests (testing, 5 files)
|
||||
```
|
||||
|
||||
### 2.2 For Markdown Sources (brainstorm-to-cycle)
|
||||
|
||||
```javascript
|
||||
function loadBrainstormTask(mdPath) {
|
||||
const content = Read(mdPath)
|
||||
|
||||
// Extract enriched task description from cycle-task.md
|
||||
// Format: # Generated Task \n\n **Idea**: ... \n\n --- \n\n {enrichedTask}
|
||||
const taskMatch = content.match(/---\s*\n([\s\S]+)$/)
|
||||
const enrichedTask = taskMatch ? taskMatch[1].trim() : content
|
||||
|
||||
// Parse into a single composite task
|
||||
return {
|
||||
tasks: [{
|
||||
id: 'TASK-001',
|
||||
title: extractTitle(content),
|
||||
description: enrichedTask,
|
||||
type: 'feature',
|
||||
priority: 'high',
|
||||
effort: 'large',
|
||||
source: { tool: 'brainstorm-to-cycle', path: mdPath }
|
||||
}],
|
||||
errors: [],
|
||||
is_composite: true // Single large task from brainstorm
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Display:
|
||||
|
||||
```
|
||||
Brainstorm 任务加载
|
||||
══════════════════
|
||||
文件: .workflow/.brainstorm/notification-system/cycle-task.md
|
||||
来源: brainstorm-to-cycle
|
||||
|
||||
ℹ 脑暴输出为复合任务描述（非结构化 JSONL）
|
||||
标题: Build real-time notification system
|
||||
类型: feature (composite)
|
||||
|
||||
是否需要将其拆分为多个子任务？(Y/n)
|
||||
```
|
||||
|
||||
If user selects **Y** (split), analyze the task description and generate sub-tasks:
|
||||
|
||||
```javascript
|
||||
// Analyze and decompose the composite task into 3-7 sub-tasks
|
||||
// Use mcp__ace-tool__search_context to find relevant patterns
|
||||
// Generate structured tasks with convergence criteria
|
||||
```
|
||||
|
||||
If user selects **n** (keep as single), use as-is.
|
||||
|
||||
### 2.3 Validation Gate
|
||||
|
||||
If validation has errors:
|
||||
|
||||
```
|
||||
⚠ 验证发现 {N} 个问题:
|
||||
Line 3: missing fields: description
|
||||
Line 7: invalid JSON
|
||||
|
||||
选项:
|
||||
1. 跳过有问题的行，继续 ({valid_count} 个有效任务)
|
||||
2. 取消，手动修复后重试
|
||||
```
|
||||
|
||||
**Block if 0 valid tasks.** Warn and continue if some tasks invalid.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Task Transformation
|
||||
|
||||
Transform unified JSONL tasks → ccw-loop `develop.tasks[]` format.
|
||||
|
||||
```javascript
|
||||
function transformToCcwLoopTasks(sourceTasks) {
|
||||
const now = getUtc8ISOString()
|
||||
|
||||
return sourceTasks.map((task, index) => ({
|
||||
// Core fields (ccw-loop native)
|
||||
id: task.id || `task-${String(index + 1).padStart(3, '0')}`,
|
||||
description: task.title
|
||||
? `${task.title}: ${task.description}`
|
||||
: task.description,
|
||||
tool: inferTool(task), // 'gemini' | 'qwen' | 'codex'
|
||||
mode: 'write',
|
||||
status: 'pending',
|
||||
priority: mapPriority(task.priority), // 1 (high) | 2 (medium) | 3 (low)
|
||||
files_changed: (task.files || []).map(f => f.path || f),
|
||||
created_at: now,
|
||||
completed_at: null,
|
||||
|
||||
// Extended fields (preserved from source for agent reference)
|
||||
_source: task.source || { tool: 'manual' },
|
||||
_convergence: task.convergence || null,
|
||||
_type: task.type || 'feature',
|
||||
_effort: task.effort || 'medium',
|
||||
_depends_on: task.depends_on || []
|
||||
}))
|
||||
}
|
||||
|
||||
function inferTool(task) {
|
||||
// Default to gemini for write tasks
|
||||
return 'gemini'
|
||||
}
|
||||
|
||||
function mapPriority(priority) {
|
||||
switch (priority) {
|
||||
case 'high': case 'critical': return 1
|
||||
case 'medium': return 2
|
||||
case 'low': return 3
|
||||
default: return 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Display transformed tasks:
|
||||
|
||||
```
|
||||
任务转换
|
||||
════════
|
||||
源格式: unified JSONL (collaborative-plan-with-file)
|
||||
目标格式: ccw-loop develop.tasks
|
||||
|
||||
task-001 [P1] Implement JWT token service: Create JWT service... gemini/write pending
|
||||
task-002 [P1] Add OAuth2 Google strategy: Implement passport... gemini/write pending
|
||||
task-003 [P2] Create user session middleware: Add Express... gemini/write pending
|
||||
task-004 [P3] Add rate limiting to auth endpoints: Implement... gemini/write pending
|
||||
task-005 [P3] Write integration tests: Create test suite... gemini/write pending
|
||||
|
||||
共 5 个任务 (2 high, 1 medium, 2 low)
|
||||
```
|
||||
|
||||
### 3.1 Task Reordering (Optional)
|
||||
|
||||
Ask: "是否需要调整任务顺序或移除某些任务？(输入编号排列如 '1,3,2,5' 或回车保持当前顺序)"
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Auto-Loop Configuration
|
||||
|
||||
### 4.1 Present Defaults
|
||||
|
||||
```
|
||||
自动循环配置
|
||||
════════════
|
||||
模式: 全自动 (develop → debug → validate → complete)
|
||||
最大迭代: $MAX_ITER (默认 10)
|
||||
超时: 10 分钟/action
|
||||
|
||||
收敛标准 (从源任务汇总):
|
||||
${tasksWithConvergence} 个任务含收敛标准 → 自动验证
|
||||
${tasksWithoutConvergence} 个任务无收敛标准 → 使用默认 (测试通过)
|
||||
|
||||
需要调整参数吗？(直接回车使用默认值)
|
||||
```
|
||||
|
||||
### 4.2 Customization (if requested)
|
||||
|
||||
> "请选择要调整的项目:
|
||||
> 1. 最大迭代次数 (当前: 10)
|
||||
> 2. 每个 action 超时 (当前: 10 分钟)
|
||||
> 3. 全部使用默认值"
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Final Confirmation
|
||||
|
||||
```
|
||||
══════════════════════════════════════════════
|
||||
Pre-Flight 检查完成
|
||||
══════════════════════════════════════════════
|
||||
|
||||
来源: collaborative-plan-with-file (CPLAN-auth-redesign-20260208)
|
||||
任务数: 5 个 (2 high, 1 medium, 2 low)
|
||||
验证: ✓ 5/5 任务格式正确
|
||||
收敛: 3/5 任务含收敛标准
|
||||
自动模式: ON (最多 10 次迭代)
|
||||
|
||||
任务摘要:
|
||||
1. [P1] Implement JWT token service
|
||||
2. [P1] Add OAuth2 Google strategy
|
||||
3. [P2] Create user session middleware
|
||||
4. [P3] Add rate limiting to auth endpoints
|
||||
5. [P3] Write integration tests
|
||||
|
||||
══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
Ask: "确认启动？(Y/n)"
|
||||
- If **Y** → proceed to Step 6
|
||||
- If **n** → ask which part to revise
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Write Artifacts
|
||||
|
||||
### 6.1 Write prep-package.json
|
||||
|
||||
Write to `{projectRoot}/.workflow/.loop/prep-package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"generated_at": "{ISO8601_UTC+8}",
|
||||
"prep_status": "ready",
|
||||
"target_skill": "ccw-loop",
|
||||
|
||||
"environment": {
|
||||
"project_root": "{projectRoot}",
|
||||
"tech_stack": "{detected tech stack}",
|
||||
"test_framework": "{detected test framework}"
|
||||
},
|
||||
|
||||
"source": {
|
||||
"tool": "collaborative-plan-with-file",
|
||||
"session_id": "CPLAN-auth-redesign-20260208",
|
||||
"jsonl_path": "{projectRoot}/.workflow/.planning/CPLAN-auth-redesign-20260208/tasks.jsonl",
|
||||
"task_count": 5,
|
||||
"tasks_with_convergence": 3
|
||||
},
|
||||
|
||||
"tasks": {
|
||||
"total": 5,
|
||||
"by_priority": { "high": 2, "medium": 1, "low": 2 },
|
||||
"by_type": { "feature": 3, "enhancement": 1, "testing": 1 }
|
||||
},
|
||||
|
||||
"auto_loop": {
|
||||
"enabled": true,
|
||||
"no_confirmation": true,
|
||||
"max_iterations": 10,
|
||||
"timeout_per_action_ms": 600000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Write tasks.jsonl
|
||||
|
||||
Write transformed tasks to `{projectRoot}/.workflow/.loop/prep-tasks.jsonl` (ccw-loop format):
|
||||
|
||||
```javascript
|
||||
const jsonlContent = transformedTasks.map(t => JSON.stringify(t)).join('\n')
|
||||
Write(`${projectRoot}/.workflow/.loop/prep-tasks.jsonl`, jsonlContent)
|
||||
```
|
||||
|
||||
Confirm:
|
||||
|
||||
```
|
||||
✓ prep-package.json → .workflow/.loop/prep-package.json
|
||||
✓ prep-tasks.jsonl → .workflow/.loop/prep-tasks.jsonl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Launch Loop
|
||||
|
||||
Invoke the skill:
|
||||
|
||||
```
|
||||
$ccw-loop --auto TASK="Execute tasks from {source.tool} session {source.session_id}"
|
||||
```
|
||||
|
||||
其中:
|
||||
- `$ccw-loop` — 展开为 skill 调用
|
||||
- `--auto` — 启用全自动模式
|
||||
- Skill 端会检测 `prep-package.json` 并加载 `prep-tasks.jsonl`
|
||||
|
||||
**Skill 端会做以下检查**（见 Phase 1 Step 1.1）:
|
||||
1. 检测 `prep-package.json` 是否存在
|
||||
2. 验证 `prep_status === "ready"`
|
||||
3. 验证 `target_skill === "ccw-loop"`
|
||||
4. 校验 `project_root` 与当前项目一致
|
||||
5. 校验文件时效（24h 内生成）
|
||||
6. 验证 `prep-tasks.jsonl` 存在且可读
|
||||
7. 全部通过 → 加载预构建任务列表；任一失败 → 回退到默认 INIT 行为
|
||||
|
||||
Print:
|
||||
|
||||
```
|
||||
启动 ccw-loop (自动模式)...
|
||||
prep-package.json → Phase 1 自动加载并校验
|
||||
prep-tasks.jsonl → 5 个预构建任务加载到 develop.tasks
|
||||
循环: develop → validate → complete (最多 10 次迭代)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| 无可用上游会话 | 提示用户先运行 collaborative-plan / analyze-with-file / brainstorm，或选择手动输入 |
|
||||
| JSONL 格式全部无效 | 报告错误，**不启动 loop** |
|
||||
| JSONL 部分无效 | 警告无效行，用有效任务继续 |
|
||||
| brainstorm cycle-task.md 为空 | 报告错误，建议完成 brainstorm 流程 |
|
||||
| 用户取消确认 | 保存 prep-package.json (prep_status="cancelled")，提示可修改后重新运行 |
|
||||
| Skill 端 prep-package 校验失败 | Skill 打印警告，回退到无 prep 的默认 INIT 行为（不阻塞执行） |
|
||||
373
.codex/prompts/prep-plan.md
Normal file
373
.codex/prompts/prep-plan.md
Normal file
@@ -0,0 +1,373 @@
|
||||
---
|
||||
description: "Interactive pre-flight checklist for workflow:plan. Validates environment, refines task to GOAL/SCOPE/CONTEXT, collects source docs, configures execution preferences, writes prep-package.json, then launches the workflow."
|
||||
argument-hint: TASK="<task description>" [EXEC_METHOD=agent|cli|hybrid] [CLI_TOOL=codex|gemini|qwen]
|
||||
---
|
||||
|
||||
# Pre-Flight Checklist for Workflow Plan
|
||||
|
||||
You are an interactive preparation assistant. Your job is to ensure everything is ready for an **unattended** `workflow:plan` run with `--yes` mode. Follow each step sequentially. **Ask the user questions when information is missing.** At the end, write `prep-package.json` and invoke the skill.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Environment Prerequisites
|
||||
|
||||
Check these items. Report results as a checklist.
|
||||
|
||||
### 1.1 Required (block if any fail)
|
||||
|
||||
- **Project root**: Confirm current working directory is a valid project (has package.json, Cargo.toml, pyproject.toml, go.mod, or similar)
|
||||
- **Writable workspace**: Ensure `.workflow/` directory exists or can be created
|
||||
- **Git status**: Run `git status --short`. If working tree is dirty, WARN but don't block
|
||||
|
||||
### 1.2 Strongly Recommended (warn if missing)
|
||||
|
||||
- **project-tech.json**: Check `{projectRoot}/.workflow/project-tech.json`
|
||||
- If missing: WARN — Phase 1 will call `workflow:init` to generate it. Ask user: "检测到项目使用 [tech stack from package.json], 是否正确？需要补充什么？"
|
||||
- **project-guidelines.json**: Check `{projectRoot}/.workflow/project-guidelines.json`
|
||||
- If missing: WARN — will be generated as empty scaffold. Ask: "有特定的编码规范需要遵循吗？"
|
||||
- **Test framework**: Detect from config files (jest.config, vitest.config, pytest.ini, etc.)
|
||||
- If missing: Ask: "未检测到测试框架，请指定测试命令（如 `npm test`），或输入 'skip' 跳过"
|
||||
|
||||
### 1.3 Output
|
||||
|
||||
Print formatted checklist:
|
||||
|
||||
```
|
||||
环境检查
|
||||
════════
|
||||
✓ 项目根目录: D:\myproject
|
||||
✓ .workflow/ 目录就绪
|
||||
⚠ Git: 3 个未提交变更
|
||||
✓ project-tech.json: 已检测 (Express + TypeORM + PostgreSQL)
|
||||
⚠ project-guidelines.json: 未找到 (Phase 1 将生成空模板)
|
||||
✓ 测试框架: jest (npm test)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Task Quality Assessment
|
||||
|
||||
### 2.0 Requirement Source Tracking
|
||||
|
||||
**在评估任务质量之前，先追踪需求的原始来源。** 这些引用会写入 prep-package.json，供 Phase 2 context-gather 和 Phase 3 task-generation 使用。
|
||||
|
||||
Ask the user:
|
||||
> "任务需求的来源是什么？可以提供以下一种或多种:
|
||||
> 1. 本地文档路径 (如 docs/prd.md, requirements/feature-spec.md)
|
||||
> 2. GitHub Issue URL (如 https://github.com/org/repo/issues/123)
|
||||
> 3. 设计文档 / 原型链接
|
||||
> 4. 会话中直接描述 (无外部文档)
|
||||
>
|
||||
> 请输入来源路径/URL（多个用逗号分隔），或输入 'none' 表示无外部来源"
|
||||
|
||||
**Processing logic**:
|
||||
|
||||
```javascript
|
||||
const sourceRefs = []
|
||||
|
||||
for (const input of userInputs) {
|
||||
if (input === 'none') break
|
||||
|
||||
const ref = { path: input, type: 'unknown', status: 'unverified' }
|
||||
|
||||
if (input.startsWith('http')) {
|
||||
ref.type = 'url'
|
||||
ref.status = 'linked'
|
||||
} else if (fs.existsSync(input) || fs.existsSync(`${projectRoot}/${input}`)) {
|
||||
ref.type = 'local_file'
|
||||
ref.path = fs.existsSync(input) ? input : `${projectRoot}/${input}`
|
||||
ref.status = 'verified'
|
||||
ref.preview = Read(ref.path, { limit: 20 })
|
||||
} else {
|
||||
ref.type = 'local_file'
|
||||
ref.status = 'not_found'
|
||||
console.warn(`⚠ 文件未找到: ${input}`)
|
||||
}
|
||||
|
||||
sourceRefs.push(ref)
|
||||
}
|
||||
|
||||
// Auto-detect common requirement docs
|
||||
const autoDetectPaths = [
|
||||
'docs/prd.md', 'docs/PRD.md', 'docs/requirements.md',
|
||||
'docs/design.md', 'docs/spec.md', 'requirements/*.md', 'specs/*.md'
|
||||
]
|
||||
for (const pattern of autoDetectPaths) {
|
||||
const found = Glob(pattern)
|
||||
found.forEach(f => {
|
||||
if (!sourceRefs.some(r => r.path === f)) {
|
||||
sourceRefs.push({ path: f, type: 'auto_detected', status: 'verified' })
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Display detected sources:
|
||||
|
||||
```
|
||||
需求来源
|
||||
════════
|
||||
✓ docs/prd.md (本地文档, 已验证)
|
||||
✓ https://github.com/.../issues/42 (URL, 已链接)
|
||||
~ requirements/api-spec.md (自动检测)
|
||||
```
|
||||
|
||||
### 2.1 Scoring
|
||||
|
||||
Score the user's TASK against 5 dimensions, mapped to workflow:plan's GOAL/SCOPE/CONTEXT format.
|
||||
Each dimension scores 0-2 (0=missing, 1=vague, 2=clear). **Total minimum: 6/10 to proceed.**
|
||||
|
||||
| # | 维度 | 映射 | 评分标准 |
|
||||
|---|------|------|----------|
|
||||
| 1 | **目标** (Objective) | → GOAL | 0=无具体内容 / 1=有方向无细节 / 2=具体可执行 |
|
||||
| 2 | **成功标准** (Success Criteria) | → GOAL 补充 | 0=无 / 1=不可度量 / 2=可测试可验证 |
|
||||
| 3 | **范围** (Scope) | → SCOPE | 0=无 / 1=笼统区域 / 2=具体文件/模块 |
|
||||
| 4 | **约束** (Constraints) | → CONTEXT | 0=无 / 1=泛泛"别破坏" / 2=具体限制条件 |
|
||||
| 5 | **技术上下文** (Tech Context) | → CONTEXT | 0=无 / 1=最少 / 2=丰富 |
|
||||
|
||||
### 2.2 Display Score
|
||||
|
||||
```
|
||||
任务质量评估
|
||||
════════════
|
||||
目标(GOAL): ██████████ 2/2 "Add Google OAuth login with JWT session"
|
||||
成功标准: █████░░░░░ 1/2 "Should work" → 需要细化
|
||||
范围(SCOPE): ██████████ 2/2 "src/auth/*, src/strategies/*"
|
||||
约束(CTX): ░░░░░░░░░░ 0/2 未指定 → 必须补充
|
||||
技术上下文: █████░░░░░ 1/2 "TypeScript" → 可自动增强
|
||||
|
||||
总分: 6/10 (可接受，需交互补充)
|
||||
```
|
||||
|
||||
### 2.3 Interactive Refinement
|
||||
|
||||
**For each dimension scoring < 2**, ask a targeted question:
|
||||
|
||||
**目标不清 (score 0-1)**:
|
||||
> "请更具体地描述要实现什么功能？例如：'为现有 Express API 添加 Google OAuth 登录，生成 JWT token，支持 /api/auth/google 和 /api/auth/callback 两个端点'"
|
||||
|
||||
**成功标准缺失 (score 0-1)**:
|
||||
> "完成后如何验证？请描述至少 2 个可测试的验收条件。例如：'1. 用户能通过 Google 账号登录 2. 登录后返回有效 JWT 3. 受保护路由能正确验证 token'"
|
||||
|
||||
**范围不明 (score 0-1)**:
|
||||
> "这个任务涉及哪些文件或模块？我检测到以下可能相关的目录: [列出扫描到的相关目录]，请确认或补充"
|
||||
|
||||
**约束缺失 (score 0-1)**:
|
||||
> "有哪些限制条件？常见约束：不破坏现有 API / 使用现有数据库 / 不引入新依赖 / 保持现有模式。请选择或自定义"
|
||||
|
||||
**上下文不足 (score 0-1)**:
|
||||
> "我从项目中检测到: [tech stack from project-tech.json]。还有需要知道的技术细节吗？"
|
||||
|
||||
### 2.4 Auto-Enhancement
|
||||
|
||||
For dimensions still at score 1 after Q&A, auto-enhance from codebase:
|
||||
- **Scope**: Use `Glob` and `Grep` to find related files
|
||||
- **Context**: Read `project-tech.json` and key config files
|
||||
- **Constraints**: Infer from `project-guidelines.json`
|
||||
|
||||
### 2.5 Assemble Structured Description
|
||||
|
||||
Map to workflow:plan's GOAL/SCOPE/CONTEXT format:
|
||||
|
||||
```
|
||||
GOAL: {objective + success criteria}
|
||||
SCOPE: {scope boundaries}
|
||||
CONTEXT: {constraints + technical context}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Execution Preferences
|
||||
|
||||
### 3.1 Present Configuration & Ask for Overrides
|
||||
|
||||
```
|
||||
执行配置
|
||||
════════
|
||||
|
||||
自动模式: --yes (跳过所有确认)
|
||||
自动提交: --with-commit (每个任务完成后自动 git commit)
|
||||
|
||||
执行方式: $EXEC_METHOD (默认 agent)
|
||||
agent — Claude agent 直接实现
|
||||
hybrid — Agent 编排 + CLI 处理复杂步骤 (推荐)
|
||||
cli — 全部通过 CLI 工具执行
|
||||
|
||||
CLI 工具: $CLI_TOOL (默认 codex)
|
||||
codex / gemini / qwen / auto
|
||||
|
||||
补充材料: 无 (可后续在 Phase 3 Phase 0 中添加)
|
||||
|
||||
需要调整任何参数吗？(直接回车使用默认值)
|
||||
```
|
||||
|
||||
If user wants to customize, ask:
|
||||
|
||||
> "请选择要调整的项目:
|
||||
> 1. 执行方式 (当前: agent)
|
||||
> 2. CLI 工具 (当前: codex)
|
||||
> 3. 是否自动提交 (当前: 是)
|
||||
> 4. 补充材料路径
|
||||
> 5. 全部使用默认值"
|
||||
|
||||
### 3.2 Build Execution Config
|
||||
|
||||
```javascript
|
||||
const executionConfig = {
|
||||
auto_yes: true,
|
||||
with_commit: true,
|
||||
execution_method: userChoice.executionMethod || 'agent',
|
||||
preferred_cli_tool: userChoice.preferredCliTool || 'codex',
|
||||
supplementary_materials: {
|
||||
type: 'none',
|
||||
content: []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Final Confirmation Summary
|
||||
|
||||
```
|
||||
══════════════════════════════════════════════
|
||||
Pre-Flight 检查完成
|
||||
══════════════════════════════════════════════
|
||||
|
||||
环境: ✓ 就绪 (3/3 必需, 2/3 推荐)
|
||||
任务质量: 9/10 (优秀)
|
||||
自动模式: ON (--yes --with-commit)
|
||||
执行方式: hybrid (codex)
|
||||
需求来源: 2 个文档 (docs/prd.md, issue #42)
|
||||
|
||||
结构化任务:
|
||||
GOAL: Add Google OAuth login with JWT session management;
|
||||
验收: 用户可 Google 登录, 返回 JWT, 受保护路由验证
|
||||
SCOPE: src/auth/*, src/strategies/*, src/models/User.ts
|
||||
CONTEXT: Express.js + TypeORM + PostgreSQL;
|
||||
约束: 不破坏 /api/login, 使用现有 User 表
|
||||
|
||||
══════════════════════════════════════════════
|
||||
```
|
||||
|
||||
Ask: "确认启动？(Y/n)"
|
||||
- If **Y** or Enter → proceed to Step 5
|
||||
- If **n** → ask which part to revise, loop back
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Write prep-package.json
|
||||
|
||||
Write to `{projectRoot}/.workflow/.prep/plan-prep-package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"generated_at": "{ISO8601_UTC+8}",
|
||||
"prep_status": "ready",
|
||||
"target_skill": "workflow-plan-execute",
|
||||
|
||||
"environment": {
|
||||
"project_root": "{projectRoot}",
|
||||
"prerequisites": {
|
||||
"required_passed": true,
|
||||
"recommended_passed": true,
|
||||
"warnings": ["{list of warnings}"]
|
||||
},
|
||||
"tech_stack": "{detected tech stack}",
|
||||
"test_framework": "{detected test framework}",
|
||||
"has_project_tech": true,
|
||||
"has_project_guidelines": false
|
||||
},
|
||||
|
||||
"task": {
|
||||
"original": "{$TASK raw input}",
|
||||
"structured": {
|
||||
"goal": "{GOAL string}",
|
||||
"scope": "{SCOPE string}",
|
||||
"context": "{CONTEXT string}"
|
||||
},
|
||||
"quality_score": 9,
|
||||
"dimensions": {
|
||||
"objective": { "score": 2, "value": "..." },
|
||||
"success_criteria": { "score": 2, "value": "..." },
|
||||
"scope": { "score": 2, "value": "..." },
|
||||
"constraints": { "score": 2, "value": "..." },
|
||||
"context": { "score": 1, "value": "..." }
|
||||
},
|
||||
"source_refs": [
|
||||
{
|
||||
"path": "docs/prd.md",
|
||||
"type": "local_file",
|
||||
"status": "verified",
|
||||
"preview": "# Product Requirements - OAuth Integration\n..."
|
||||
},
|
||||
{
|
||||
"path": "https://github.com/org/repo/issues/42",
|
||||
"type": "url",
|
||||
"status": "linked"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"execution": {
|
||||
"auto_yes": true,
|
||||
"with_commit": true,
|
||||
"execution_method": "agent",
|
||||
"preferred_cli_tool": "codex",
|
||||
"supplementary_materials": {
|
||||
"type": "none",
|
||||
"content": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Confirm:
|
||||
```
|
||||
✓ prep-package.json 已写入 .workflow/.prep/plan-prep-package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Launch Workflow
|
||||
|
||||
Invoke the skill using `$ARGUMENTS` pass-through:
|
||||
|
||||
```
|
||||
$workflow-plan-execute --yes --with-commit TASK="$TASK_STRUCTURED"
|
||||
```
|
||||
|
||||
其中:
|
||||
- `$workflow-plan-execute` — 展开为 skill 调用
|
||||
- `$TASK_STRUCTURED` — Step 2 组装的 GOAL/SCOPE/CONTEXT 格式任务
|
||||
- `--yes` — 全自动模式
|
||||
- `--with-commit` — 每任务自动提交（根据 Step 3 配置）
|
||||
|
||||
**Skill 端会做以下检查**（见 Phase 1 消费逻辑）:
|
||||
1. 检测 `.workflow/.prep/plan-prep-package.json` 是否存在
|
||||
2. 验证 `prep_status === "ready"` 且 `target_skill === "workflow-plan-execute"`
|
||||
3. 校验 `project_root` 与当前项目一致
|
||||
4. 校验 `quality_score >= 6`
|
||||
5. 校验文件时效（24h 内生成）
|
||||
6. 校验必需字段完整性
|
||||
7. 全部通过 → 加载配置；任一失败 → 回退默认行为 + 打印警告
|
||||
|
||||
Print:
|
||||
```
|
||||
启动 workflow:plan (自动模式)...
|
||||
prep-package.json → Phase 1 自动加载并校验
|
||||
执行方式: hybrid (codex) + auto-commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| 必需项检查失败 | 报告缺失项，给出修复建议，**不启动 workflow** |
|
||||
| 任务质量 < 6/10 且用户拒绝补充 | 报告各维度得分，建议重写任务描述，**不启动 workflow** |
|
||||
| 用户取消确认 | 保存 prep-package.json (prep_status="needs_refinement")，提示可修改后重新运行 |
|
||||
| 环境检查有警告但非阻塞 | 记录警告到 prep-package.json，继续执行 |
|
||||
| Skill 端 prep-package 校验失败 | Skill 打印警告，回退到无 prep 的默认行为（不阻塞执行） |
|
||||
Reference in New Issue
Block a user