# Prep Package Schema & Integration Spec

Schema definition for `plan-prep-package.json` and integration points with the workflow-plan-execute skill.

## File Location

```
{projectRoot}/.workflow/.prep/plan-prep-package.json
```

Generated by: `/prompts:prep-plan` (interactive prompt)
Consumed by: Phase 1 (Session Discovery) → feeds into Phase 2, 3, 4

## JSON Schema

```json
{
  "version": "1.0.0",
  "generated_at": "ISO8601",
  "prep_status": "ready | needs_refinement | blocked",
  "target_skill": "workflow-plan-execute",

  "environment": {
    "project_root": "/path/to/project",
    "prerequisites": {
      "required_passed": true,
      "recommended_passed": true,
      "warnings": ["string"]
    },
    "tech_stack": "string",
    "test_framework": "string",
    "has_project_tech": true,
    "has_project_guidelines": true
  },

  "task": {
    "original": "raw user input",
    "structured": {
      "goal": "GOAL string (objective + success criteria)",
      "scope": "SCOPE string (boundaries)",
      "context": "CONTEXT string (constraints + tech context)"
    },
    "quality_score": 8,
    "dimensions": {
      "objective":        { "score": 2, "value": "..." },
      "success_criteria": { "score": 2, "value": "..." },
      "scope":            { "score": 2, "value": "..." },
      "constraints":      { "score": 1, "value": "..." },
      "context":          { "score": 1, "value": "..." }
    },
    "source_refs": [
      {
        "path": "docs/prd.md",
        "type": "local_file | url | auto_detected",
        "status": "verified | linked | not_found",
        "preview": "first ~20 lines (local_file only)"
      }
    ]
  },

  "execution": {
    "auto_yes": true,
    "with_commit": true,
    "execution_method": "agent | cli | hybrid",
    "preferred_cli_tool": "codex | gemini | qwen | auto",
    "supplementary_materials": {
      "type": "none | paths | inline",
      "content": []
    }
  }
}
```

## Validation Rules (6 checks)

Phase 1 对 plan-prep-package.json 执行 **6 项验证**，全部通过才加载：

| # | 检查项 | 条件 | 失败处理 |
|---|--------|------|----------|
| 1 | prep_status | `=== "ready"` | 跳过 prep |
| 2 | target_skill | `=== "workflow-plan-execute"` | 跳过 prep（防错误 skill） |
| 3 | project_root | 与当前 projectRoot 一致 | 跳过 prep（防错误项目） |
| 4 | quality_score | `>= 6` | 跳过 prep（任务质量不达标） |
| 5 | 时效性 | generated_at 在 24h 以内 | 跳过 prep（可能过期） |
| 6 | 必需字段 | task.structured.goal, execution 全部存在 | 跳过 prep |

## Phase 1 Integration (Session Discovery)

After session creation, enrich planning-notes.md with prep data:

```javascript
const prepPath = `${projectRoot}/.workflow/.prep/plan-prep-package.json`
let prepPackage = null

if (fs.existsSync(prepPath)) {
  const raw = JSON.parse(Read(prepPath))
  const checks = validatePlanPrepPackage(raw, projectRoot)

  if (checks.valid) {
    prepPackage = raw
    // Use structured task for session creation
    structuredDescription = {
      goal: prepPackage.task.structured.goal,
      scope: prepPackage.task.structured.scope,
      context: prepPackage.task.structured.context
    }
    console.log(`✓ Prep package loaded: score=${prepPackage.task.quality_score}/10`)
  } else {
    console.warn(`⚠ Prep package validation failed, using defaults`)
  }
}

// After session created, enrich planning-notes.md:
if (prepPackage) {
  // 1. Add source refs section
  const sourceRefsSection = prepPackage.task.source_refs
    ?.filter(r => r.status === 'verified' || r.status === 'linked')
    .map(r => `- **${r.type}**: ${r.path}`)
    .join('\n') || 'None'

  // 2. Add quality dimensions
  const dimensionsSection = Object.entries(prepPackage.task.dimensions)
    .map(([k, v]) => `- **${k}**: ${v.value} (score: ${v.score}/2)`)
    .join('\n')

  // Append to planning-notes.md under User Intent
  Edit(planningNotesPath, {
    old: `- **KEY_CONSTRAINTS**: ${userConstraints}`,
    new: `- **KEY_CONSTRAINTS**: ${userConstraints}

### Requirement Sources (from prep)
${sourceRefsSection}

### Quality Dimensions (from prep)
${dimensionsSection}`
  })
}
```

## Phase 3 Integration (Task Generation - Phase 0 User Config)

Prep package auto-populates Phase 0 user configuration:

```javascript
// In Phase 3, Phase 0 (User Configuration):
if (prepPackage) {
  // Auto-answer all Phase 0 questions from prep
  userConfig = {
    supplementaryMaterials: prepPackage.execution.supplementary_materials,
    executionMethod: prepPackage.execution.execution_method,
    preferredCliTool: prepPackage.execution.preferred_cli_tool,
    enableResume: true
  }
  console.log(`✓ Phase 0 auto-configured from prep: ${userConfig.executionMethod} (${userConfig.preferredCliTool})`)
  // Skip interactive questions, proceed to Phase 1 (Context Prep)
}
```

## Phase 2 Integration (Context Gathering)

Source refs from prep feed into exploration context:

```javascript
// In Phase 2, Step 2 (spawn explore agents):
// Add source_refs as supplementary context for exploration
if (prepPackage?.task?.source_refs?.length > 0) {
  const verifiedRefs = prepPackage.task.source_refs.filter(r => r.status === 'verified')
  // Include verified local docs in exploration agent prompt
  explorationAgentPrompt += `\n## SUPPLEMENTARY REQUIREMENT DOCUMENTS\n`
  explorationAgentPrompt += verifiedRefs.map(r => `Read and analyze: ${r.path}`).join('\n')
}
```

## Phase 4 Integration (Execution)

Commit flag from prep:

```javascript
// In Phase 4:
const withCommit = prepPackage?.execution?.with_commit || $ARGUMENTS.includes('--with-commit')
```