story-engine

Files (54)

• SKILL.md
• W1-story-design.md · docs/en/
• W2-synopsis.md · docs/en/
• W3-writing.md · docs/en/
• W4-production.md · docs/en/
• W5-tts-sfx.md · docs/en/
• W6-storyboard.md · docs/en/
• W7-image-production.md · docs/en/
• W8-assembly.md · docs/en/
• W9-upload-info.md · docs/en/
• W1-story-design.md · docs/ko/
• W2-synopsis.md · docs/ko/
• W3-writing.md · docs/ko/
• W4-production.md · docs/ko/
• W5-tts-sfx.md · docs/ko/
• W6-storyboard.md · docs/ko/
• W7-image-production.md · docs/ko/
• W8-assembly.md · docs/ko/
• W9-upload-info.md · docs/ko/
• hook_principles.md · meta-prompts/_common/
• _translation_review.md · meta-prompts/bespoke/
• narrative_techniques.md · meta-prompts/bespoke/en/
• preflight.md · meta-prompts/bespoke/en/
• screenplay_guidelines.md · meta-prompts/bespoke/en/
• suspense_techniques.md · meta-prompts/bespoke/en/
• synopsis_guidelines.md · meta-prompts/bespoke/en/
• narrative_techniques.md · meta-prompts/bespoke/ko/
• preflight.md · meta-prompts/bespoke/ko/
• screenplay_guidelines.md · meta-prompts/bespoke/ko/
• suspense_techniques.md · meta-prompts/bespoke/ko/
• synopsis_guidelines.md · meta-prompts/bespoke/ko/
• narrative_techniques.md · meta-prompts/dark-history/
• preflight.md · meta-prompts/dark-history/
• screenplay_guidelines.md · meta-prompts/dark-history/
• suspense_techniques.md · meta-prompts/dark-history/
• synopsis_guidelines.md · meta-prompts/dark-history/
• yadam-narrative-guide.md · meta-prompts/yadam/
• yadam-preflight.md · meta-prompts/yadam/
• yadam-scenario-guide.md · meta-prompts/yadam/
• yadam-suspense-techniques.md · meta-prompts/yadam/
• yadam-synopsis-guide.md · meta-prompts/yadam/
• metadata.json
• build_srt.cjs · scripts/
• draft_subtitles.cjs · scripts/
• generate_sfx.cjs · scripts/
• generate_tts_elevenlabs.cjs · scripts/
• generate_tts_typecast.cjs · scripts/
• lib_afc.cjs · scripts/
• merge_audio.cjs · scripts/
• execute-pipeline.md · workflows/
• new-episode.md · workflows/
• resume.md · workflows/
• rewrite-episode.md · workflows/
• step.md · workflows/

SKILL.md (first lines)

# Story Engine v2

9-Wave 자동 파이프라인으로 YouTube 스토리 채널 대본을 작성하고, TTS/SFX 생성, 이미지 생성, 어셈블리(오디오 임포트/CapCut), 업로드 정보까지 자동화한다.

## 스킬 구조

| 스킬 | 역할 | 트리거 |
|------|------|--------|
| `/story-new` | 에피소드 초기화 + 주제 논의 | "새 에피소드", "start ep5" |
| `/story-execute` | W1~W9 자동 파이프라인 | "파이프라인 실행", "execute" |
| `/story-next` | 중단 후 재개 | "이어서 해줘", "continue" |
| `/story-rewrite` | 기존 에피소드 개선 (몰입도 진단 → fork → 개선판) | "rewrite my", "ep03 개선", "다시 써줘" |

## 9-Wave 파이프라인

| Wave | 내용 | 리뷰 |
|------|------|------|
| **W1** | 스토리 설계 (신규/리라이팅 분기) | — |
| **W2** | 시놉시스 + 프리플라이트 | 최대 5회 |
| **W3** | 대본 작성 + 검토 | 최대 5회 (목표 9.5점) |
| | 🛑 **사용자 확인** | |
| **W4** | 프로덕션 추출 + 검증 (W4-0 production-scope 사용자 게이트 — dialogue/sfx 켜기/끄기 선택) | 최대 5회 |
| **W5** | TTS/SFX + mechanic 타임코드 검증 + W5-0-prep API key preflight (provider별 cheap GET 검증 → miss/stale 시 manual-assisted remediation) (`production_scope.dialogue: false` → 5-1f 스킵; `production_scope.sfx: false` → 5-2/5-3 SFX 변환 no-op/5-4 SFX 검사 vacuous) | 리뷰 |
| **W6** | 스토리보드 CSV + 검토 (batch QA, 3그룹 병렬) | 최대 5회 |
| **W7** | 이미지 프로덕션 (ref + 씬 + 에러 fix + image QA, batch QA) | 최대 5회 |
| | 🛑 **사용자 확인** | |
| **W8** | 어셈블리 (SFX 씬 매칭 + 오디오 임포트 + CapCut export + 영상 선택) | 최대 5회 |
| **W9** | 업로드 정보 (제목/설명/태그/썸네일) | — |

## 장르

| 트리거 | 장르 | 메타프롬프트 |
|--------|------|-------------|
| 한국어 + 야담/민담/조선/설화/전설 키워드 | **yadam** (야담) | `meta-prompts/yadam/` (한국어 5개 파일) |
| English + dark/gothic/medieval/witch/folklore/colonial 키워드 | **dark-history** | `meta-prompts/dark-history/` (영문 5개 파일) |
| 어느 장르도 명확하지 않음 (또는 `--genre bespoke`) | **bespoke** (맞춤형) | `meta-prompts/bespoke/{lang}/` (한국어 출력 시 `ko/`, 영문 출력 시 `en/` — 각 5개) + 에피소드별 `_story_source/_meta_supplement.md` (W1-5에서 user reference 3~5개로 합성). `{lang}`은 `STATE.md` "Output language:" 필드에서 해석. |

`--genre yadam`, `--genre dark-history`, 또는 `--genre bespoke`로 오버라이드 가능.

**Bespoke 장르 추가 요건:** `/story-new` 시 사용자에게 **3~5개 성공 대본 reference**를 받아야 함 (URL / 텍스트 / 로컬 파일). reference가 ≤ 2개 → escalation (다른 장르로 전환 권장).

## Review discipline (W2–W7)
- Every substep runs a review loop: subagent self-review → list issues → revise.
- Max 5 rounds. 0 issues → proceed immediately.
- 5 rounds exceeded → escalate to user.
- W1 (research) and W8 (upload info) are exceptions with no review loop.

## 리뷰 원칙 (W2–W8)
- 모든 서브스텝은 리뷰 루프를 실행한다: 서브에이전트 자가검토 → 이슈 목록 → 수정.
- 최대 5회. 0 이슈 시 즉시 진행.
- 5회 초과 시 사용자에게 에스컬레이션.
- W1(리서치)과 W9(업로드 정보)은 리뷰 루프 없는 예외 단계이다.

## Batch QA discipline (parallel subagent reviewers, checklist > 5 items)

When a review checklist exceeds 5 items, a single subagent skims rather than audits. Split into focused groups and spawn ONE subagent per group, in parallel.

- **Group size**: 3–4 items per group (target 3, max 4).
- **QA is subagent + Read tool, NOT scripts.** Even if a scene/CSV check could in principle be automated by a Python script, the QA step itself is performed by a subagent reading the artifacts via the Read tool and reporting findings. Pre-check scripts (running BEFORE QA as a fast sanity gate) are allowed and separate; they do not replace subagent inspection. "Script passed, so QA passes" is forbidden.
- **Parallelism**: spawn all groups in a single message with multiple `Agent` tool uses → concurrent execution.
- **Recommended concurrency**: 3 (sweet spot). Max useful: 5. Beyond 5 = diminishing returns; token cost still scales N×.
- **Each subagent receives**: only its group's items + the read-only inputs it needs + an exclusive output file path (e.g., `{wave}_review_group{X}.md`).
- **Subagent prohibitions during batch**: do NOT touch `STATE.md`, `W_progress.json`, or any other shared state. The orchestrator merges all group results AFTER every subagent returns.
- **Heartbeat prefix**: every `_progress.log` line written by a batch subagent MUST be prefixed with `[Group {X}]` to allow interleaved-line forwarding without ambiguity.
- **Sequential fallback**: if a group must call external APIs (TTS, image gen, app-state mutation), run that group sequentially or extract the API work out of QA. Read-only QA stays parallel.

## Batch QA 원칙 (병렬 서브에이전트 리뷰어, 체크리스트 > 5 항목)

체크리스트가 5개를 넘기면 한 서브에이전트는 형식적 통과만 함. focused 그룹으로 쪼개서 그룹마다 별도 서브에이전트를 **병렬로** 호출한다.

- **그룹 크기**: 3~4 항목 (목표 3, 최대 4).
- **QA는 subagent + Read 도구, 스크립트 아님.** 어떤 검사 항목이 Python 스크립트로 자동화 가능하더라도, QA 자체는 subagent가 Read 도구로 산출물을 직접 읽고 점검한다. Pre-check 스크립트 (QA 직전에 빠른 sanity gate로 돌리는 자동 검사)는 허용되고 별개이다 — subagent 점검을 대체할 수 없음. "스크립트 통과했으니 QA 통과"는 금지.
- **병렬성**: 한 메시지에 여러 `Agent` 호출을 동시에 보내면 동시 실행됨.
- **권장 동시 N**: 3 (sweet spot). 최대 유용 N: 5. 5 넘으면 한계 효용 빠르게 감소, 토큰 비용은 N배 그대로.
- **각 서브에이전트가 받는 것**: 자기 그룹 항목만 + 필요한 read-only 입력만 + 전용 출력 파일 경로 (`{wave}_review_group{X}.md`).
- **batch 중 서브에이전트 금지**: `STATE.md`, `W_progress.json`, 기타 공유 상태 절대 안 건드림. 오케스트레이터가 모든 그룹 반환 후 1회 합산 update.
- **하트비트 prefix**: batch 서브에이전트가 `_progress.log`에 쓰는 모든 라인은 `[Group {X}]` prefix 필수 (interleaved 라인 forwarding 시 모호성 제거).
- **Sequential 폴백**: 외부 API 호출 (TTS, 이미지 생성, 앱 상태 변경) 필요한 그룹은 sequential로. read-only QA만 병렬 유지.

## Progress reporting discipline (orchestrator — wave AND sub-step level)

**The user must always know what is currently happening.** Wave-level START/DONE banners (see `workflows/execute-pipeline.md`) cover wave boundaries; this discipline covers EVERYTHING inside a wave.

- **Every new sub-step announces itself in one line BEFORE work begins.** Format: `▸ Starting <step name>…`
- **Every sub-step completion announces its result with elapsed time.** Format: `✅ <step name> done (mm:ss). Next: <next step>.`
- **Sub-step ≠ wave.** A wave has multiple sub-steps. Example W5 sub-steps: W5-0 voice-pick, W5-1 narration-TTS, W5-2 dialogue-TTS, W5-3 SRT, W5-4 SFX (batched), W5-5 merge. Each sub-step MUST emit its own status line. See the canonical sub-step decomposition table in `workflows/execute-pipeline.md`.
- **No silent block longer than 3 minutes.** Any operation expected to run >3 min MUST be split into 1–3 minute chunks at the orchestrator level, with a status line between chunks.
- **Repeated calls batch.** When a sub-step does N similar API calls (e.g. 55 SFX cues, 20 scene images), group into batches of 10–15 with one status line per batch: `▸ SFX batch 2/4 (cues 16–30)…` then `✅ batch 2/4 done (M:SS), N/N succeeded.`
- **Heartbeat fallback.** If a sub-step genuinely cannot be split, the subagent writes `_progress.log` per state change. The orchestrator polls every 30–60 s and forwards the latest line.
- **Trigger:** any time the action changes — reading docs → spawning subagent → calling API → writing files → reviewing — announce it.
- **Subagent invocations are the highest-risk silence point. Always over-announce them:**
  - **BEFORE every `Agent` tool call:** `▸ Spawning <type> subagent for <task> (est. <X> min, prompt ~<N> tokens)…`
  - **AFTER every `Agent` tool call returns:** `✅ <task> subagent returned in <mm:ss>. Result: <one-line summary>.`
  - **For `SendMessage` to an existing agent:** `▸ Sending message to agent <id> (<reason>)…` then `✅ Agent <id> response in <mm:ss>.`
  - The user MUST NEVER see a silent `Agent` or `SendMessage` tool call. These are the exact moments where multi-minute silence happens — bracket every one with announcements.
- **Subagents must self-report during execution (heartbeat).** Every wave subagent MUST append a one-line heartbeat to `_story_source/_progress.log` at every sub-step transition. Format: `<ISO-8601 UTC> <wave-label> <event>: <description> [<metrics>]`. Events: `START`, `END`, `API`, `SPAWN`, `WRITE`, `ERROR`, `WAIT`. Triggers: sub-step start/end, before every external API call, before every file write, entering/exiting review rounds, before spawning child agents, on errors/retries. The orchestrator polls this file (every 30–60 s for `run_in_background: true` calls; once after return for foreground) and forwards new lines to the user as `📡 [<wave>]: <line>`. See `workflows/execute-pipeline.md` "Subagent heartbeat protocol" for full spec.
- **Default to over-reporting.** Silence is the failure mode; verbosity is recoverable.

## 진행 상황 보고 원칙 (오케스트레이터 — Wave 및 서브스텝 단위 공통)

**사용자는 항상 지금 무엇이 진행되고 있는지 알아야 한다.** Wave 경계의 START/DONE 배너(`workflows/execute-pipeline.md` 참조)는 Wave 경계만 다룬다. 이 원칙은 Wave 내부의 모든 것을 다룬다.

- **새 서브스텝 시작 시 무조건 1줄 알림 (작업 시작 전).** 형식: `▸ <단계명> 시작…`
- **서브스텝 완료 시 1줄 알림 (소요시간 포함).** 형식: `✅ <단계명> 완료 (mm:ss). 다음: <다음 단계>.`
- **서브스텝 ≠ Wave.** 한 Wave는 여러 서브스텝으로 구성. 예시 W5: W5-0(음성 선택), W5-1(나레이션 TTS), W5-2(대화 TTS), W5-3(SRT), W5-4(SFX 배치), W5-5(머지). 각 서브스텝마다 상태 라인 필수. 캐노니컬 서브스텝 분해 표는 `workflows/execute-pipeline.md` 참조.
- **3분 이상의 침묵 금지.** 3분 초과 예상되는 작업은 오케스트레이터 레벨에서 1~3분 단위 청크로 분할, 청크 사이에 상태 보고.
- **반복 호출은 배치로 묶기.** 한 서브스텝이 N개의 유사 호출(SFX 55개, 씬 이미지 20개 등)을 할 때 10~15개 배치로 묶고, 배치당 상태 1줄.
- **하트비트 대체.** 분할이 정말 불가능한 경우, 서브에이전트가 매 상태 변화마다 `_progress.log`에 1줄 기록 → 오케스트레이터가 30~60초마다 폴링.
- **트리거:** 무엇을 하고 있는가가 바뀔 때 — 문서 읽기 → 서브에이전트 스폰 → API 호출 → 파일 쓰기 → 검토 — 매번 알림.
- **서브에이전트 호출은 침묵 위험 최고치. 과보고 필수:**
  - **모든 `Agent` 도구 호출 전:** `▸ <type> 서브에이전트 스폰 — <태스크명> (예상 <X>분, 프롬프트 ~<N> 토큰)…`
  - **모든 `Agent` 호출 반환 후:** `✅ <태스크명> 서브에이전트 반환 (<mm:ss>). 결과: <한 줄 요약>.`
  - **기존 에이전트에 `SendMessage`:** `▸ 에이전트 <id>에 메시지 송신 (<이유>)…` 그리고 `✅ 에이전트 <id> 응답 (<mm:ss>).`
  - `Agent`나 `SendMessage` 호출이 조용히 일어나면 절대 안 됨 — 다분 침묵이 발생하는 정확한 지점이므로 매번 알림으로 감싸기.
- **서브에이전트는 실행 중 자가 보고 필수 (하트비트).** 모든 Wave 서브에이전트는 `_story_source/_progress.log`에 서브스텝 전환마다 1줄 append 필수. 형식: `<ISO-8601 UTC> <wave-label> <event>: <설명> [<메트릭>]`. 이벤트: `START`, `END`, `API`, `SPAWN`, `WRITE`, `ERROR`, `WAIT`. 트리거: 서브스텝 시작/종료, 외부 API 호출 전, 파일 쓰기 전, 리뷰 라운드 진입/종료, 자식 에이전트 스폰 전, 에러/재시도 시. 오케스트레이터는 이 파일을 폴링(`run_in_background: true` 시 30~60초마다, foreground 시 반환 후 1회)하고 새 줄을 사용자에게 `📡 [<wave>]: <줄>` 형식으로 전달. 전체 스펙은 `workflows/execute-pipeline.md` "Subagent heartbeat protocol" 참조.
- **과보고가 디폴트.** 침묵이 실패 모드, 장황함은 복구 가능.

## Subagent transparency contract (orchestrator MUST verify, never trust blindly)

From touchizen/AutoFlowCut, AGPL-3.0.

More from touchizen/AutoFlowCut