Claude-Code-Workflow/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "plan-overview-base-schema.json",
  "title": "Plan Overview Base Schema",
  "description": "计划概览基础 schema — 所有计划类型共享字段。Feature 类型直接使用此 schema，其他类型 (fix/tdd/review) 通过 allOf 继承并扩展。",
  "type": "object",
  "required": ["summary", "approach", "task_ids", "task_count", "_metadata"],

  "properties": {
    "summary": {
      "type": "string",
      "description": "2-3 句计划概述"
    },
    "approach": {
      "type": "string",
      "description": "高层实施策略和方法论"
    },
    "task_ids": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "description": "引用 .task/ 下的任务 ID 列表 (如 ['TASK-001', 'TASK-002'])"
    },
    "task_count": {
      "type": "integer",
      "minimum": 1,
      "description": "任务数量 (应等于 task_ids.length)"
    },

    "complexity": {
      "type": "string",
      "enum": ["Low", "Medium", "High"],
      "description": "计划复杂度"
    },
    "estimated_time": {
      "type": "string",
      "description": "总估算时间 (如 '30 minutes', '2 hours')"
    },
    "recommended_execution": {
      "type": "string",
      "enum": ["Agent", "Codex"],
      "description": "推荐执行方式"
    },

    "data_flow": {
      "type": "object",
      "properties": {
        "diagram": {
          "type": "string",
          "description": "ASCII/文本形式的数据流图 (如 'A → B → C')"
        },
        "stages": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["stage", "input", "output", "component"],
            "properties": {
              "stage": {
                "type": "string",
                "description": "阶段名称"
              },
              "input": {
                "type": "string",
                "description": "输入数据格式/类型"
              },
              "output": {
                "type": "string",
                "description": "输出数据格式/类型"
              },
              "component": {
                "type": "string",
                "description": "处理该阶段的组件/模块"
              },
              "transformations": {
                "type": "array",
                "items": { "type": "string" },
                "description": "该阶段的数据转换"
              }
            }
          },
          "description": "详细数据流阶段"
        },
        "dependencies": {
          "type": "array",
          "items": { "type": "string" },
          "description": "外部依赖或数据源"
        }
      },
      "description": "全局数据流设计"
    },

    "design_decisions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["decision", "rationale"],
        "properties": {
          "decision": {
            "type": "string",
            "description": "设计决策"
          },
          "rationale": {
            "type": "string",
            "description": "决策原因"
          },
          "tradeoff": {
            "type": "string",
            "description": "权衡取舍"
          },
          "alternatives": {
            "type": "array",
            "items": { "type": "string" },
            "description": "考虑过的替代方案"
          }
        }
      },
      "description": "影响整个计划的全局设计决策"
    },


    "shared_context": {
      "type": "object",
      "description": "Project-level shared context (tech stack, conventions).",
      "properties": {
        "tech_stack": {
          "type": "array",
          "items": { "type": "string" },
          "description": "技术栈列表"
        },
        "conventions": {
          "type": "array",
          "items": { "type": "string" },
          "description": "编码约定"
        },
        "auth_strategy": {
          "type": "string",
          "description": "认证策略"
        }
      },
      "additionalProperties": true
    },

    "_metadata": {
      "type": "object",
      "required": ["timestamp", "source", "plan_type"],
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 规划时间戳"
        },
        "source": {
          "type": "string",
          "enum": ["cli-lite-planning-agent", "direct-planning", "action-planning-agent", "review-cycle-agent", "issue-plan-agent", "tdd-planning-agent"],
          "description": "规划来源 — 标识产生此 plan 的实际规划引擎"
        },
        "planning_mode": {
          "type": "string",
          "enum": ["direct", "agent-based"],
          "description": "规划执行模式"
        },
        "plan_type": {
          "type": "string",
          "enum": ["feature", "fix", "tdd", "review", "collaborative", "requirement"],
          "description": "计划类型 — 消费端据此选择对应的扩展 schema 校验"
        },
        "schema_version": {
          "type": "string",
          "default": "2.0",
          "description": "Schema 版本"
        },
        "exploration_angles": {
          "type": "array",
          "items": { "type": "string" },
          "description": "用于上下文的探索角度"
        },
        "duration_seconds": {
          "type": "integer",
          "description": "规划耗时 (秒)"
        }
      }
    }
  },

  "additionalProperties": true,

  "_extension_guide": {
    "description": "扩展指南 — 通过 allOf + $ref 继承此 base schema",
    "available_extensions": {
      "fix": "plan-overview-fix-schema.json — fix_context, test_strategy, rollback_plan",
      "tdd": "(未来) plan-overview-tdd-schema.json — tdd_cycles, coverage_targets, phase_requirements",
      "review": "(未来) plan-overview-review-schema.json — review_dimensions, finding_summary"
    },
    "feature_note": "feature 类型直接使用此 base schema，无需额外扩展"
  },

  "_field_migration_from_plan_json": {
    "summary": "直接迁移",
    "approach": "直接迁移",
    "tasks": "→ task_ids[] (引用 .task/ 下的独立文件)",
    "complexity": "直接迁移",
    "estimated_time": "直接迁移",
    "recommended_execution": "直接迁移",
    "data_flow": "直接迁移",
    "design_decisions": "直接迁移",
    "flow_control": "→ 删除 (由引擎从 task depends_on + parallel_group 自动推断)",
    "focus_paths": "→ 删除 (由引擎从 task focus_paths / files[].path 聚合)",
    "_metadata": "扩展 (新增 plan_type, schema_version)"
  }
}