Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (108 loc) · 9.61 KB

AGENTS.md

File metadata and controls

124 lines (108 loc) · 9.61 KB
Raw

Flow Kit — Codex CLI Instructions

Base URL: http://127.0.0.1:8100

Pre-flight

Before ANY workflow:

curl -s http://127.0.0.1:8100/health
# Flow mode must return: {"extension_connected": true}
# Assistant mode (MEDIA_PROVIDER=assistant or provider=assistant per request):
# extension_connected may be false — no Chrome extension needed.
# Check provider status instead: GET /api/providers/status

Critical Rules (MUST follow)

  1. Media ID is always UUID — format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Never use CAMS... / base64 strings.
  2. Scene prompts = ACTION only — never describe character appearance. Reference images handle visual consistency via imageInputs.
  3. All reference images must exist before scene images — verify every entity has media_id before generating scene images.
  4. No throwaway scripts — NEVER write Python, shell, or any script file to loop over API requests. Use POST /api/requests/batch to submit all requests at once, then poll GET /api/requests/batch-status. The server throttles automatically.
  5. Locations use landscape, characters use portrait — reference image orientation depends on entity type.
  6. UUID extraction — if a response gives CAMS... instead of UUID, extract UUID from the fifeUrl in the response URL: /image/{UUID}?....
  7. Cascade on regen — regenerating an image auto-clears downstream video + upscale.
  8. REGENERATE vs GENERATE — GENERATE_* skips if already COMPLETED. REGENERATE_* always runs (clears + regenerates).
  9. Image Material required — every project needs a material field (e.g. realistic, 3d_pixar, anime). List available: GET /api/materials.
  10. Server handles throttling (per provider) — each media provider declares its own limits (Flow: max 5 concurrent + 10s cooldown; assistant: max 2 concurrent, no cooldown). Submit ALL requests via /batch; do NOT manually stagger or loop. Check effective limits: GET /api/providers/status.
  11. Video prompts use sub-clip timing — structure 8s video as time segments: 0-3s: [action]. 3-6s: [action]. 6-8s: [action].
  12. Character dialogue in sub-clips — embed speech in quotes: Luna says "Goodnight." Max 10-15 words per character per 2-3s segment.
  13. Scenes are mutable — use PATCH /api/scenes/{sid} to update prompt, video_prompt, narrator_text, character_names after creation. Don't delete and recreate — patch instead.
  14. Fact-check before scripting — ALWAYS research events via web search before writing project stories, scene prompts, or narrator text. Facts (events, dates, names, operations, outcomes) MUST match real sources. Editorial opinion and analysis are allowed but must be framed as such. Never invent events, operation names, or statistics.
  15. Real-people bypass — when characters are based on real famous people (politicians, celebrities, military leaders), NEVER use their real name as entity name or anywhere in description, image_prompt, prompt, or video_prompt. AI image generators reject known public figures. Instead: (a) use a role-based alias as entity name (e.g. "Tổng Tư Lệnh" not "Trump", "Thủ Tướng Sắt" not "Netanyahu"), (b) describe physical appearance only — distinctive hair, face shape, build, clothing style — without naming who it is, (c) narrator_text may use real titles/roles for storytelling but real names never flow into image/video generation. Keep a real_reference mapping in the project plan file (.omc/research/) for internal tracking.
  16. Review before upscale — ALWAYS run /fk-review-video (light mode) after video generation, before upscaling. Scenes scoring < 7.5 get video_prompt updated from review errors, then regen video. Max 2 review-regen cycles.

Pipeline Order

0. Research          /fk-research "topic" (fact-check via web search, save to .omc/research/)
1. Health check      GET  /health → extension_connected: true
2. Create project    POST /api/projects (with entities + material, story from research)
3. Create video      POST /api/videos
4. Create scenes     POST /api/scenes (with character_names, chain_type)
5. Gen ref images    POST /api/requests/batch → poll /batch-status?project_id=<PID>
                     Wait for done=true, verify all entities have media_id
6. Gen scene images  POST /api/requests/batch → poll /batch-status?video_id=<VID>
                     Wait for done=true, verify image_media_id = UUID
7. Gen videos        POST /api/requests/batch → poll /batch-status?video_id=<VID>
                     Wait for done=true (videos take 2-5 min each)
7.5 Review videos    POST /api/videos/{vid}/review?mode=light (AI vision quality check)
                     Pass: score >= 7.5 | Fail: update video_prompt → regen → re-review (max 2 cycles)
8. (Optional) 4K     POST /api/requests/batch (TIER_TWO only)
9. (Optional) TTS    Create voice template → POST /api/videos/{vid}/narrate
10. Concat           ffmpeg normalize + concat

Batch API

Submit N requests at once (server throttles automatically — max 5 concurrent, 10s cooldown):

curl -X POST http://127.0.0.1:8100/api/requests/batch \
  -H "Content-Type: application/json" \
  -d '{"requests": [{"type": "...", "scene_id": "...", "project_id": "...", "video_id": "...", "orientation": "VERTICAL"}, ...]}'

Poll aggregate status:

curl -s "http://127.0.0.1:8100/api/requests/batch-status?video_id=<VID>&type=GENERATE_IMAGE"
# Returns: {"total": 40, "pending": 30, "processing": 5, "completed": 5, "failed": 0, "done": false}
# When "done": true → all requests have left the queue (completed or failed)
# When "all_succeeded": true → every request completed successfully

For full API reference, workflow recipes, and video prompt guidelines, see CLAUDE.md.

Skills

This project has reusable skills in skills/. When the user says /fk-<name>, read skills/fk-<name>.md and follow the instructions inside.

Skill Purpose
/fk-action-choreography Action Choreography — AI Cinematic Combat & Motion Direction
/fk-add-material fk-add-material — Image Material System
/fk-brand-logo fk-brand-logo — Apply Channel Branding (Intro + Outro + Logo + 4K Badge)
/fk-camera-guide Camera Guide — Cinematic Video Prompts (Veo 3)
/fk-change-model fk-change-model — View & Change Video/Image Model Keys
/fk-change-provider fk-change-provider — View & Switch the Reviewer for a Role
/fk-character-bible Character Bible & Visual Consistency — AI Film Production
/fk-cinematic-transitions Cinematic Transitions & Chapter Bumpers — AI Film Direction
/fk-concat-fit-narrator Trim each scene video to fit its TTS narrator duration, burn text overlays, then concatenate into a final video.
/fk-concat Download and concatenate all scene videos into a single video with optional TTS narration.
/fk-create-project Create a new Google Flow video project. Ask the user for:
/fk-creative-mix Creative video mixing — combine techniques for cinematic results.
/fk-dashboard Show live GLA status in Claude Code statusline.
/fk-doctor Diagnose any FlowKit error and prescribe a fix. Knows the full error taxonomy across Google Flow, the Chrome extension, the FastAPI layer, the worker, and the YouTube upload pipeline.
/fk-fix-uuids Find and fix any non-UUID media_ids (CAMS... format) across all scenes and entities.
/fk-gen-chain-videos Generate videos with automatic scene chaining (start+end frame transitions).
/fk-gen-images Generate scene images for all scenes in a video.
/fk-gen-music fk-gen-music — Generate Music via Suno
/fk-gen-narrator fk-gen-narrator — Generate Narrator Text + TTS for All Scenes
/fk-gen-refs Generate reference images for all entities in a project.
/fk-gen-text-overlays fk-gen-text-overlays — Generate Text Overlays from Narrator Text
/fk-gen-tts-template fk-gen-tts-template — Generate Voice Template
/fk-gen-videos Generate videos for all scenes in a video.
/fk-import-voice fk-import-voice — Import Existing Voice as Template
/fk-insert-scene Insert new scene(s) into an existing video chain — for multi-angle shots, cutaways, or close-ups.
/fk-monitor fk-monitor — Full Pipeline Monitor
/fk-pipeline fk-pipeline — Smart Full-Pipeline Orchestrator
/fk-provider fk-provider — Media providers: choose the generation backend
/fk-refresh-urls Re-sign expired media URLs for all scenes in a video (images, videos, upscale videos) and character reference images.
/fk-research fk-research — Fact-Check & Research Before Scripting
/fk-review-board Start the Scene Review Board web app for visual feedback on scene chains.
/fk-review-video Review AI-generated scene videos for quality.
/fk-scriptwriter The Ultimate AI Screenplay Bible — Google Flow & Veo 3
/fk-sound-design Sound Design & Audio Mastering — AI Cinematic Soundscapes
/fk-status Show full status dashboard for a project.
/fk-switch-project fk-switch-project — Switch Active Project
/fk-thumbnail-guide YouTube Thumbnail Guide — Hook-Worthy Design Rules
/fk-thumbnail Generate 4 YouTube-optimized thumbnail variants for a project video.
/fk-upload-image Upload a local image file to Google Flow and get a media_id (UUID).
/fk-youtube-seo fk-youtube-seo — Generate YouTube Metadata (SEO-Optimized)
/fk-youtube-upload fk-youtube-upload — Upload Video to YouTube (Shorts + Long-form)