Blueprint Core Schema Definition

[mathaix]

User Story

As a developer
I want a well-defined Interview Blueprint schema
So that all Clara components can reliably consume blueprint data

Acceptance Criteria

Core Schema Structure

• Pydantic models for all blueprint components
• Top-level InterviewBlueprint model:

class InterviewBlueprint(BaseModel):
    metadata: BlueprintMetadata
    project: ProjectContext
    shared_rubric: RubricSpec          # NEW: Shared across all agents
    agents: list[AgentBlueprint]       # 1..N agents
    execution_plan: ExecutionPlan      # NEW: Agent-to-interviewee mapping
    synthesis: SynthesisBlueprint
    quality: QualitySpec

BlueprintMetadata

• id: Blueprint ID (bp_{ulid})
• version: Semver string
• status: draft | active | deprecated
• created_at, updated_at: Timestamps
• created_by: User ID
• designed_by: "adaptive_architect" | "manual"
• project_id: Reference to project

ProjectContext Schema

• Business context fields:
  • name, type, description
  • business_context: Why this project exists
  • decision_to_inform: What decisions this informs
  • stakeholders: Who uses results
  • timeline, constraints
• Source context (from MCP - Phase 2):
  • jira_projects, confluence_spaces
  • key_documents, org_context

NEW: ExecutionPlan Schema

class ExecutionPlan(BaseModel):
    mappings: list[AgentIntervieweeMapping]

class AgentIntervieweeMapping(BaseModel):
    agent_id: str
    agent_name: str
    target_roles: list[str]
    target_departments: list[str]

Validation Requirements

• All required fields enforced
• At least 1 agent required
• Shared rubric must have at least 1 field
• Cross-field validation (e.g., agent IDs in execution plan match agents list)
• Nested model validation recursive

Serialization

• JSON serialization for API responses
• JSONB compatible for PostgreSQL storage
• Schema export for documentation

Technical Notes

• Use Pydantic v2 with strict mode
• Blueprint ID format: bp_{ulid}
• Migration path from old schema (if blueprints exist)

Definition of Done

• All Pydantic models defined
• Validation tests passing
• JSON serialization working
• Schema documentation generated
• Code reviewed and merged

---

🤖 Generated with Claude Code