{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "autocode-features-v1",
  "title": "Autocode Features Schema",
  "description": "Schema for FEATURES.json - Multi-feature project tracking for agent-first engineering workflows",
  "type": "object",
  "required": ["$schema", "project", "description", "created", "updated", "features"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Relative path to this schema file (e.g., './schemas/autocode-features-v1.schema.json')"
    },
    "project": {
      "type": "string",
      "description": "Project name",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "description": "High-level project description",
      "minLength": 1
    },
    "created": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when FEATURES.json was created"
    },
    "updated": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of last update"
    },
    "features": {
      "type": "array",
      "description": "List of features in this project",
      "items": {
        "$ref": "#/definitions/feature"
      }
    }
  },
  "additionalProperties": true,
  "definitions": {
    "feature": {
      "type": "object",
      "required": ["id", "name", "description", "complexity", "verification_mode", "status", "priority"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^F\\d{3}$",
          "description": "Feature ID (e.g., F001, F042)"
        },
        "name": {
          "type": "string",
          "description": "Short feature name",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "Detailed feature description",
          "minLength": 1
        },
        "complexity": {
          "type": "string",
          "enum": ["simple", "standard", "complex"],
          "description": "Feature complexity level. Determined by predictability, not just size: simple = known files, existing pattern, no new interfaces; standard = some unknowns, 4-6 files; complex = significant unknowns, 6+ files. Simple features get an inline_spec planning hint."
        },
        "verification_mode": {
          "type": "string",
          "enum": ["mvp", "standard", "production"],
          "description": "Verification rigor level"
        },
        "status": {
          "type": "string",
          "enum": [
            "not_started",
            "planning",
            "verification_planning",
            "ready",
            "in_progress",
            "verifying",
            "complete",
            "blocked",
            "paused"
          ],
          "description": "Current feature status"
        },
        "priority": {
          "type": "integer",
          "minimum": 1,
          "description": "Feature priority (lower number = higher priority)"
        },
        "dependencies": {
          "type": "array",
          "description": "List of feature IDs this feature depends on",
          "items": {
            "type": "string",
            "pattern": "^F\\d{3}$"
          },
          "default": []
        },
        "docs": {
          "type": "object",
          "description": "Links to durable planning docs that inform this feature slice",
          "properties": {
            "delegation_brief": {
              "type": ["string", "null"],
              "description": "Path to Delegation Brief (recommended): docs/delegation-briefs/<slug>.md"
            },
            "discovery_json": {
              "type": ["string", "null"],
              "description": "Path to discovery JSON (taste/system boundary): docs/discovery/<slug>.json"
            },
            "discovery_md": {
              "type": ["string", "null"],
              "description": "Path to discovery markdown: docs/discovery/<slug>.md"
            },
            "delivery_spec": {
              "type": ["string", "null"],
              "description": "Path to delivery spec: docs/delivery-specs/<slug>.md"
            },
            "design_doc": {
              "type": ["string", "null"],
              "description": "Path to design doc/ADR: docs/design-docs/<slug>.md"
            }
          },
          "additionalProperties": true
        },
        "progress": {
          "type": "object",
          "description": "Implementation and verification progress tracking",
          "required": ["implementation_steps", "verification_tests"],
          "properties": {
            "implementation_steps": {
              "type": "object",
              "required": ["total", "completed"],
              "properties": {
                "total": {
                  "type": "integer",
                  "minimum": 0
                },
                "completed": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "verification_tests": {
              "type": "object",
              "required": ["total", "passed"],
              "properties": {
                "total": {
                  "type": "integer",
                  "minimum": 0
                },
                "passed": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          }
        },
        "specs": {
          "type": "object",
          "description": "Paths to implementation and verification spec files",
          "properties": {
            "implementation": {
              "type": ["string", "null"],
              "description": "Path to implementation spec (e.g., specs/F001-IMPLEMENTATION_SPEC.md)"
            },
            "verification": {
              "type": ["string", "null"],
              "description": "Path to verification spec (e.g., specs/F001-VERIFICATION_SPEC.md)"
            },
            "review": {
              "type": ["string", "null"],
              "description": "Path to spec review report (optional)"
            }
          }
        },
        "inline_spec": {
          "type": "object",
          "description": "Planning-phase hint for simple features. Provides file paths for early /parallel-plan overlap analysis and pre-seeds context for the implementation planner. Not an execution plan — a lightweight spec via autocode-implementation-planner is still required before /autocode-next-step.",
          "properties": {
            "files": {
              "type": "array",
              "description": "File paths this feature will touch. Used by /parallel-plan for overlap analysis (Source 2) and by the implementation planner as pre-seeded entry points.",
              "items": {
                "type": "string"
              }
            },
            "description": {
              "type": "string",
              "description": "Brief description of the change. Used by the implementation planner as the feature description when none is provided by the user."
            },
            "verification": {
              "type": "string",
              "description": "How to verify this feature works (e.g., 'Visual inspection', 'Manual review'). Informational — the implementation planner generates a proper VERIFICATION_SPEC.md."
            }
          }
        },
        "timestamps": {
          "type": "object",
          "description": "Feature lifecycle timestamps",
          "properties": {
            "planned": {
              "type": ["string", "null"],
              "format": "date-time"
            },
            "verification_planned": {
              "type": ["string", "null"],
              "format": "date-time"
            },
            "started": {
              "type": ["string", "null"],
              "format": "date-time"
            },
            "completed": {
              "type": ["string", "null"],
              "format": "date-time"
            }
          }
        },
        "verification_evidence": {
          "type": ["object", "null"],
          "description": "Evidence that verification passed",
          "properties": {
            "mode": {
              "type": "string",
              "enum": ["mvp", "standard", "production", "manual"]
            },
            "tests_run": {
              "type": "integer",
              "minimum": 0
            },
            "tests_passed": {
              "type": "integer",
              "minimum": 0
            },
            "timestamp": {
              "type": "string",
              "format": "date-time"
            },
            "command": {
              "type": "string"
            },
            "verifier_result": {
              "type": "string",
              "enum": ["approved", "rejected", "needs_revision"]
            },
            "notes": {
              "type": "string"
            }
          }
        },
        "user_interview": {
          "type": "object",
          "description": "User interview responses for discovery phase",
          "properties": {
            "conducted": {
              "type": "string",
              "format": "date-time"
            },
            "skipped": {
              "type": "boolean"
            },
            "skip_reason": {
              "type": ["string", "null"]
            },
            "value": {
              "type": "object",
              "properties": {
                "question": {
                  "type": "string"
                },
                "response": {
                  "type": "string"
                }
              }
            },
            "experience": {
              "type": "object",
              "properties": {
                "question": {
                  "type": "string"
                },
                "delights": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "frustrations": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            },
            "maturity": {
              "type": "object",
              "properties": {
                "question": {
                  "type": "string"
                },
                "response": {
                  "type": "string"
                },
                "rationale": {
                  "type": "string"
                }
              }
            }
          }
        },
        "user_value": {
          "type": ["object", "null"],
          "description": "User-facing value proposition",
          "properties": {
            "summary": {
              "type": "string"
            },
            "how_to_access": {
              "type": "string"
            },
            "demo_url": {
              "type": ["string", "null"]
            },
            "demo_command": {
              "type": ["string", "null"]
            }
          }
        },
        "demo": {
          "type": ["object", "null"],
          "description": "Executable demo metadata and proof-boundary status. Used by /feature-demo to distinguish what was verified in the demo run vs what still needs user verification.",
          "properties": {
            "path": {
              "type": ["string", "null"],
              "description": "Path to generated demo markdown (e.g., specs/F001-DEMO.md)"
            },
            "generated_at": {
              "type": ["string", "null"],
              "format": "date-time",
              "description": "When the demo document was last generated"
            },
            "mode": {
              "type": "string",
              "enum": [
                "local_cli",
                "interactive_ui",
                "artifact_build",
                "infra_release",
                "manual_external"
              ],
              "description": "Primary demo surface. local_cli = direct local command; interactive_ui = local server/browser flow; artifact_build = local artifact/build proof; infra_release = release/CI/CD with local proxy proof + external checks; manual_external = mostly user-run/manual verification"
            },
            "status": {
              "type": "string",
              "enum": ["generated", "partial", "manual_only", "failed"],
              "description": "Outcome of the most recent demo generation attempt"
            },
            "requires_user_verification": {
              "type": "boolean",
              "description": "Whether the feature still needs user-run verification outside the demo run"
            },
            "verification_surfaces": {
              "type": "array",
              "description": "Named proof surfaces the demo should cover or explicitly hand off (e.g., local_build, github_actions, pypi, clean_machine_upgrade)",
              "items": {
                "type": "string"
              }
            },
            "evidence_refs": {
              "type": "array",
              "description": "Paths or doc refs pointing to prior verification evidence the demo may cite as already verified",
              "items": {
                "type": "string"
              }
            },
            "note": {
              "type": "string",
              "description": "Optional concise note explaining partial/manual proof boundaries"
            }
          }
        }
      },
      "additionalProperties": true
    }
  }
}