Claude-Code-Workflow/.codex/prompts/prep-plan.md

---
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 的默认行为（不阻塞执行） |