Skip to content

Fix cartoon agent instructions to emit app-compatible cuts.json #231

@realproject7

Description

@realproject7

Context

During the #211 pilot, Claude created a good cartoon story plan but wrote plot-01.cuts.json in a custom planning schema instead of the schema the app actually reads.

Example failure pattern from the pilot:

  • top-level $schema, story, workflow, promptDefaults
  • cut ids like "c01"
  • shot instead of shotType
  • nested image.prompt, image.clean, image.final
  • nested text.narration, dialogue[].line, sfx: []

The current app expects the app/lib/cuts.ts schema:

  • version: 1
  • plotFile: "plot-01"
  • numeric cut.id
  • cut.shotType
  • cut.description
  • cut.dialogue[].speaker + cut.dialogue[].text
  • cut.narration, cut.sfx
  • cleanImagePath, finalImagePath, exportedAt, uploadedCid, uploadedUrl
  • overlays: []

Parent epic: #197. Blocks #211 pilot approval.

Task

Update the generated cartoon story instructions so agents create the exact app-compatible plot-NN.cuts.json format.

Files to inspect/update:

  • app/lib/generate-story-instructions.ts
  • app/lib/generate-story-instructions.test.ts
  • app/lib/cuts.ts
  • ~/z-docs/PROPOSAL-plotlink-ows-webtoon-pivot.md only as planning reference if available

Requirements

  • Add a concrete valid JSON example for plot-01.cuts.json using the real schema from app/lib/cuts.ts.
  • Make clear that agents must not invent alternate schemas or nested planning structures.
  • Include explicit field naming guidance:
    • use shotType, not shot
    • use numeric id, not c01
    • use description, not image.prompt
    • use dialogue[].text, not dialogue[].line
    • use string sfx, not array sfx
    • use cleanImagePath / finalImagePath, not nested image paths
  • Keep the clean-image-first and no-baked-text rules intact.
  • Do not change fiction instructions.

Acceptance Criteria

  • New cartoon CLAUDE.md contains a valid cuts.json example matching validateCutsFile.
  • Tests assert the cartoon instructions include the required schema fields and do not encourage the invalid pilot schema.
  • Existing fiction instruction tests still pass.
  • npm run typecheck and relevant tests pass.

Public Safety

Do not include private story draft content, local paths, secrets, wallet data, auth tokens, or Claude session IDs in the issue, tests, or docs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent/T3Assigned to T3 builder agent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions