Cfn Epic Creator V2

CFN Epic Creator v2 (AISP Hybrid)

Supersedes cfn-epic-creator (v1, deprecated). For full tiered planning with the verifiable-done + haiku-executable gates, cfn-megaplan is the canonical entry point; use cfn-epic-creator-v2 directly when you specifically need AISP formal contracts in an epic doc. Output feeds cfn-epic-parser.

Overview

Epic Creator v2 integrates AISP (AI Symbolic Protocol) for formal API contracts while keeping natural language for user-facing content. This hybrid approach:

• Eliminates type drift between backend/frontend agents (97x improvement in multi-agent pipelines)
• Preserves human readability for user approval checkpoints
• Adds formal binding contracts for agent handoffs

What Changed from v1

Natural Language vs AISP

AISP Integration Points

1. Technical Requirements Types (MANDATORY)

The technicalRequirements.contracts section uses AISP format:

⟦Σ:Types⟧{
  ;; Enums with explicit variants
  FamilyType≜⟨Core|Extended|Chosen⟩
  Privacy≜⟨public|private⟩
  MemberRole≜⟨owner|member|editor⟩

  ;; Constrained primitives
  UUID≜𝕊:len(36)
  InviteCode≜𝕊:len(6)∧uppercase
  FamilyName≜𝕊:len(n)∧3≤n≤50

  ;; Request/Response pairs
  CreateFamilyRequest≜⟨
    name:FamilyName,
    type:FamilyType,
    privacy:Privacy
  ⟩

  CreateFamilyResponse≜⟨
    id:UUID,
    name:FamilyName,
    type:FamilyType,      ;; Same enum - no string drift
    privacy:Privacy,
    inviteCode:InviteCode,
    createdAt:ISO8601
  ⟩
}

⟦Γ:Rules⟧{
  ;; Validation constraints
  ∀req:CreateFamilyRequest:
    len(req.name)≥3∧len(req.name)≤50

  ;; Response guarantees
  ∀res:CreateFamilyResponse:
    res.type∈FamilyType∧res.privacy∈Privacy
}

⟦Λ:Funcs⟧{
  createFamily:CreateFamilyRequest→CreateFamilyResponse
  POST /api/family
  auth:JWT

  getMyFamilies:Unit→List⟨FamilyWithCount⟩
  GET /api/family/my-families
  auth:JWT
}

2. Agent Binding Contracts (NEW)

Each persona handoff has formal pre/post conditions:

⟦Γ:Binding⟧{
  ;; Architect → Backend handoff
  Δ⊗λ(Architect,Backend)≜case[
    Post(Architect.interfaces)⊆Pre(Backend.implementation) → 3,  ;; zero-cost
    Type(Architect.types)≠Type(Backend.types) → 2,               ;; adapt needed
    _ → 1                                                         ;; null - fail
  ]

  ;; Backend → Frontend handoff
  Δ⊗λ(Backend,Frontend)≜case[
    Post(Backend.api)⊆Pre(Frontend.calls) → 3,
    _ → 2  ;; Frontend must adapt to backend contract
  ]

  ;; Invariant: exactly one binding state
  ∀A,B:|{Δ⊗λ(A,B)}|≡1
}

3. Database Schema Contracts (HIGH VALUE)

Formal schema definitions eliminate interpretation variance:

⟦Σ:Tables⟧{
  families≜⟨
    id:UUID:primary_key:default(gen_random_uuid()),
    name:VARCHAR(100):not_null:check(len(name)≥3),
    type:family_type_enum:not_null:default('core'),
    invite_code:VARCHAR(6):unique:not_null,
    created_by:UUID:not_null:references(auth.users.id)
  ⟩
}

⟦Γ:RLS⟧{
  policy_families_select≜
    ∀user,f:families:
      canSelect(user,f)⇔
        ∃m:family_members:m.family_id≡f.id∧m.user_id≡user.id
}

Template: templates/database-schema.aisp

4. Error Handling Contracts (HIGH VALUE)

Type-safe errors with consistent messaging:

⟦Σ:Errors⟧{
  FAMILY_NOT_FOUND≜⟨
    code:1001,
    status:404,
    technical:"Family with ID {id} not found",
    user_friendly:"We couldn't find that family.",
    senior_friendly:"The family you're looking for doesn't exist. Try checking your family list.",
    retryable:false
  ⟩
}

⟦Γ:Precedence⟧{
  priority:[AUTHENTICATION,AUTHORIZATION,NOT_FOUND,VALIDATION,SERVER]
}

Template: templates/error-handling.aisp

5. State Machine / UI Flows (HIGH VALUE)

Formal navigation flows with guards and actions:

⟦Γ:Transitions⟧{
  Dashboard→FamilyCreate:onClick("Create Family")
  FamilyCreate→FamilyShowInvite:onSuccess(createFamily)
  FamilyCreate→FamilyCreate:onError(validation)

  ;; Auth-triggered transitions
  ∀s:ViewState:s→Login:onAuthExpired
}

⟦Γ:Guards⟧{
  canEnter(FamilySettings)⇔
    AuthState≡authenticated∧
    ∃m:family_members:m.user_id≡currentUser.id∧m.role≡'owner'
}

Template: templates/state-machine.aisp

6. Acceptance Criteria as Predicates (HIGH VALUE)

Testable acceptance criteria with auto-generated tests:

⟦Σ:Criteria⟧{
  AC_FAMILY_001≜⟨
    feature:FamilyCreate,
    scenario:"User creates family with valid name",
    given:⟨AuthState≡authenticated, FamilyName.valid⟩,
    when:submit(CreateFamilyRequest),
    then:⟨
      ∃f:families:f.name≡input.name,
      ∃m:family_members:m.user_id≡user.id∧m.role≡'owner',
      response.status≡201
    ⟩
  ⟩
}

⟦Λ:TestGen⟧{
  toVitest(AC_FAMILY_001)≜"
    test('creates family with valid name', async () => {
      await createFamily({ name: 'Test Family' });
      expect(response.status).toBe(201);
    })
  "
}

Template: templates/acceptance-criteria.aisp

7. Feature Flags / Configuration (MEDIUM VALUE)

Typed flags with dependency validation:

⟦Σ:Flags⟧{
  flag_family_invites≜⟨
    key:"ENABLE_FAMILY_INVITES",
    type:boolean,
    environments:{
      development → enabled:true,
      production → percentage:25
    },
    dependencies:["ENABLE_FAMILY_CREATION"]
  ⟩
}

⟦Γ:Rules⟧{
  ;; Dependencies must be enabled first
  ∀f:FeatureFlag:
    enabled(f)⇔∀d∈f.dependencies:enabled(d)

  ;; Rollout progression
  isEnabled(f,production)⇒isEnabled(f,staging)
}

Template: templates/config-feature-flags.aisp

8. Migration Ordering (MEDIUM VALUE)

Dependency-ordered migrations with rollback chains:

⟦Σ:Migrations⟧{
  m_002_families≜⟨
    id:"20240115_002_create_families",
    category:schema,
    dependencies:["20240115_001_create_enums"],
    rollback:auto,
    breaking:false
  ⟩
}

⟦Γ:Rules⟧{
  ;; All dependencies must complete first
  ∀m:Migration:
    canExecute(m)⇔∀d∈m.dependencies:state(d)≡completed

  ;; Rollback in reverse order
  canRollback(m)⇔∀d:Migration:
    m∈d.dependencies⇒state(d)∈{pending,rolledback}
}

Template: templates/migration-ordering.aisp

9. Evidence Block (REQUIRED)

Every epic must include validation evidence:

⟦Ε⟧⟨
  δ≜0.78              ;; Density score (≥0.75 for ◊⁺⁺)
  φ≜96                ;; Completeness %
  τ≜◊⁺⁺               ;; Quality tier
  ⊢Ambig(D)<0.02      ;; Ambiguity invariant
  ⊢Binding:all_zero   ;; All handoffs are zero-cost
⟩

Output Structure (v2)

{
  "epic": {
    "id": "EPIC-XXXXXX",
    "title": "Natural language title",
    "description": "Natural language description for user review",
    "status": "in-review",
    "contracts": {
      "aisp_version": "5.1",
      "types": "⟦Σ:Types⟧{...}",
      "rules": "⟦Γ:Rules⟧{...}",
      "functions": "⟦Λ:Funcs⟧{...}",
      "evidence": "⟦Ε⟧⟨...⟩"
    },
    "bindings": {
      "architect_to_backend": { "state": 3, "symbol": "⊤" },
      "backend_to_frontend": { "state": 3, "symbol": "⊤" },
      "frontend_to_tester": { "state": 3, "symbol": "⊤" }
    },
    "personas": [
      {
        "name": "architect",
        "reviewOrder": 3,
        "outputs": {
          "natural": "System uses modular architecture with...",
          "aisp": "⟦Σ:Types⟧{Module≜⟨Auth|Family|Stories⟩...}"
        }
      }
    ],
    "userStories": [
      "As a senior, I want to create a family so I can invite relatives"
    ],
    "riskAssessment": {
      "technical": [{"risk": "Natural language description", "mitigation": "Natural language"}]
    }
  }
}

Persona Review Order (v2)

AISP Symbol Quick Reference

Binding States

Main Chat Execution (v2)

Step 1: Create Base Epic with AISP Scaffold

{
  "epic_id": "unique-id",
  "description": "Natural language epic description",
  "contracts": {
    "aisp_version": "5.1",
    "types": "",
    "rules": "",
    "functions": "",
    "evidence": ""
  },
  "bindings": {},
  "personas": []
}

Step 2: Architect Persona Adds AISP Types

The Architect is the first persona to output AISP. Their task:

Read the epic description and existing codebase.

OUTPUT BOTH:
1. Natural language architecture description
2. AISP contracts block:

⟦Σ:Types⟧{
  ;; Define all domain types with explicit variants
  ;; Use enums instead of strings where values are constrained
  ;; Define request/response pairs for each API
}

⟦Γ:Rules⟧{
  ;; Add validation constraints
  ;; Add invariants that must hold
}

⟦Λ:Funcs⟧{
  ;; Define API signatures: Method Path
  ;; Include auth requirements
}

Write AISP to epic.contracts.types, .rules, .functions

Step 3: Backend Consumes Architect AISP

Backend developer reads the AISP contracts and implements:

Read epic.contracts (AISP types and functions).

Your implementation MUST:
1. Use exact types from ⟦Σ:Types⟧
2. Implement functions from ⟦Λ:Funcs⟧
3. Enforce rules from ⟦Γ:Rules⟧

Add your implementation details (natural language).
Validate binding: Δ⊗λ(Architect,Backend) should be 3 (⊤).

Step 4: Frontend Consumes Backend AISP

Frontend reads the same AISP contracts:

Read epic.contracts (AISP types and functions).

Your implementation MUST:
1. Use exact types from ⟦Σ:Types⟧ for API calls
2. Call functions defined in ⟦Λ:Funcs⟧
3. Handle errors per AISP contract

Binding state Δ⊗λ(Backend,Frontend) should be 3 (⊤).

Step 5: Validate All Bindings

Strategic Alignment Reviewer validates:

Check all binding states in epic.bindings:

∀(A,B)∈Handoffs: Δ⊗λ(A,B)≥2

If any binding is 0 (crash) or 1 (null):
- Flag as blocking issue
- Identify type mismatches
- Recommend fixes

Step 6: Add Evidence Block

Final step before completion:

⟦Ε⟧⟨
  δ≜<calculated_density>
  φ≜<completeness_percent>
  τ≜<quality_tier>
  ⊢Ambig(D)<0.02
  ⊢Binding:⟨arch_back:3,back_front:3,front_test:3⟩
⟩

Benefits Over v1

Files

When to Use v2

Use Epic Creator v2 when:

• Epic has API contracts between backend/frontend
• Multiple agents will implement from the same spec
• Type consistency is critical (TypeScript, Rust)
• You want compile-time detection of integration issues

Stick with v1 when:

• Simple single-domain epic
• No API boundaries
• Quick prototype without formal contracts