Claude-Code-Workflow/.ccw/workflows/cli-templates/schemas/explore-json-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Exploration Context Schema",
  "description": "Code exploration results from cli-explore-agent for task context gathering. Every file MUST include selection rationale.",
  "type": "object",
  "required": [
    "project_structure",
    "relevant_files",
    "patterns",
    "dependencies",
    "integration_points",
    "constraints",
    "clarification_needs",
    "_metadata"
  ],
  "properties": {
    "project_structure": {
      "type": "string",
      "description": "Overall architecture description: module organization, layer structure, component relationships"
    },
    "relevant_files": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["path", "relevance", "rationale", "role"],
        "properties": {
          "path": {
            "type": "string",
            "description": "File path relative to project root"
          },
          "relevance": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"
          },
          "rationale": {
            "type": "string",
            "minLength": 10,
            "description": "REQUIRED: Selection rationale explaining why this file is relevant to the exploration topic. Must be specific (not generic). Example: 'Contains AuthService.login() which is the entry point for JWT token generation' rather than 'Related to auth'"
          },
          "role": {
            "type": "string",
            "enum": [
              "modify_target",
              "dependency",
              "pattern_reference",
              "test_target",
              "type_definition",
              "integration_point",
              "config",
              "context_only"
            ],
            "description": "File's role relative to the task: modify_target=needs changes, dependency=imported by targets, pattern_reference=demonstrates patterns to follow, test_target=tests needing update, type_definition=types/interfaces used, integration_point=where new code connects, config=configuration, context_only=understanding only"
          },
          "discovery_source": {
            "type": "string",
            "enum": ["bash-scan", "cli-analysis", "ace-search", "dependency-trace", "manual"],
            "description": "How the file was discovered: bash-scan=structural scan (rg/find/tree), cli-analysis=Gemini/Qwen semantic analysis, ace-search=ACE context engine, dependency-trace=import/export graph traversal, manual=directly specified in task"
          },
          "key_symbols": {
            "type": "array",
            "items": {"type": "string"},
            "description": "Key symbols (functions, classes, types) in this file relevant to the task. Example: ['AuthService', 'login', 'TokenPayload']"
          },
          "key_code": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["symbol", "description"],
              "properties": {
                "symbol": {
                  "type": "string",
                  "description": "Symbol identifier (function, class, method, type). Example: 'AuthService.login()'"
                },
                "location": {
                  "type": "string",
                  "description": "Line range in file. Example: 'L45-L78'"
                },
                "description": {
                  "type": "string",
                  "minLength": 10,
                  "description": "What this code does and why it matters. Example: 'JWT token generation with bcrypt verification, returns {token, refreshToken} pair'"
                }
              },
              "additionalProperties": false
            },
            "description": "Key code constructs with descriptions. Richer complement to key_symbols. Populate for files with relevance >= 0.7."
          },
          "topic_relation": {
            "type": "string",
            "minLength": 15,
            "description": "How this file relates to the exploration ANGLE/TOPIC. Must reference the angle explicitly. Example: 'Security exploration targets this file because JWT generation lacks token rotation'. Distinct from rationale (WHY selected) - topic_relation explains the CONNECTION to the exploration perspective."
          }
        },
        "additionalProperties": false
      },
      "description": "Files relevant to the task. Every file MUST have structured rationale explaining its selection basis and role classification."
    },
    "patterns": {
      "type": "string",
      "description": "Existing code patterns, conventions, and styles found in the codebase"
    },
    "dependencies": {
      "type": "string",
      "description": "External and internal module dependencies relevant to the task"
    },
    "integration_points": {
      "type": "string",
      "description": "Where this task connects with existing code: APIs, hooks, events, shared state"
    },
    "constraints": {
      "type": "string",
      "description": "Technical constraints and limitations affecting implementation"
    },
    "clarification_needs": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["question", "context", "options"],
        "properties": {
          "question": {
            "type": "string",
            "description": "The clarification question to ask user"
          },
          "context": {
            "type": "string",
            "description": "Background context explaining why this clarification is needed"
          },
          "options": {
            "type": "array",
            "items": {"type": "string"},
            "description": "Available options for user to choose from (2-4 options)"
          },
          "recommended": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based index of recommended option in the options array. Based on codebase patterns and best practices analysis."
          }
        }
      },
      "description": "Ambiguities requiring user input before planning"
    },
    "_metadata": {
      "type": "object",
      "required": ["timestamp", "task_description", "source"],
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of exploration"
        },
        "task_description": {
          "type": "string",
          "description": "Original task description that triggered exploration"
        },
        "source": {
          "type": "string",
          "const": "cli-explore-agent",
          "description": "Agent that performed exploration"
        },
        "exploration_angle": {
          "type": "string",
          "description": "Agent-chosen exploration angle (e.g., 'architecture', 'security', 'dataflow')"
        },
        "exploration_index": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "description": "Exploration index (1-4) in parallel exploration set"
        },
        "total_explorations": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "description": "Total number of parallel explorations"
        },
        "duration_seconds": {
          "type": "integer",
          "description": "Exploration duration in seconds"
        }
      }
    }
  }
}