← Back to file list
Carousel Workflow Skill
The main skill that drives the end-to-end carousel workflow.
Agent Behavior · /home/jonas/social-carousel-codex/.codex/skills/carousel-workflow/SKILL.md
Last modified: 2026-03-29T12:51:09.492Z
--- name: carousel-workflow description: Run the Codex-native social carousel workflow in this repository from intake through preview, revision classification, and final approval using repo-local state, deterministic helpers, and the carousel-web preview app. Use when the user wants to execute or continue a carousel idea inside /home/jonas/social-carousel-codex. --- # Carousel Workflow Use this skill for the end-to-end carousel workflow in this repository. ## What This Skill Owns - one main coordinating Codex thread - stage-by-stage workflow control - explicit approval gates - revision classification - deterministic use of repo-local state, helpers, and preview artifacts This skill does not replace the execution layer. It orchestrates: - `state/ideas/<idea_id>/` - `state/checkpoints/<idea_id>/` - `state/logs/<idea_id>.ndjson` - `artifacts/previews/<idea-slug>-<draft-version>/` - `scripts/runtime_state.py` - `apps/carousel-web/` ## Before You Act 1. Read the current repo guidance in `AGENTS.md`. 2. Read the live run state first if the idea already exists. 3. Treat repo-local files as the source of truth, not chat memory. 4. Keep the live OpenClaw workspace reference-only. Read these references when needed: - `references/execution-layer.md` for state paths and exact helper commands - `references/revision-rules.md` for feedback classification and research-rerun rules ## Workflow ### 1. Intake - Normalize the brief into `state/ideas/<idea_id>/intake.json` with `record-intake`. - When a benchmark screenshot and short operator context are available, treat benchmark-first intake as the default start mode. - Persist the benchmark as reference material, not as copy to paraphrase. - Do not generate angles before the intake is persisted. ### 2. Benchmark Diagnosis - Diagnose the benchmark explicitly before angle generation for benchmark-first runs. - Persist what the benchmark hook is doing, why it may be engaging, what feels weak, and how the new post should improve on it. - Use the benchmark as inspiration for a stronger replacement, not as copy to rephrase. - In this workflow, `10x better` means a stronger hook, more insight, better clarity, better evidence quality, and better practical usefulness. ### 3. Angle Generation - Produce exactly three distinct angles. - For benchmark-first runs, generate the three angles from the saved benchmark diagnosis plus the operator context. - The goal is to produce stronger versions of the benchmark idea, not benchmark paraphrases. - Persist them to `state/ideas/<idea_id>/angle-set.json` with `record-angle-set`. - Stop for explicit human selection. ### 4. Angle Approval - Accept only an explicit selected option, selected option plus remix notes, retry request, or abandon decision. - Record the selected angle durably with `approve-angle` before any research begins. - If the user rejects all angles, write the new angle set as a new material step instead of mutating memory-only notes. ### 5. Research - Treat research as an evidence package, not free-form browsing notes. - The research step is a supporting capability, not a second workflow owner. - When literature search is required, invoke `$carousel-literature-review`. - For human-gated runs, prefer `scripts/literature_review_wrapper.py build-package <spec.json> --summary-only`. - Persist the synthesized result through `scripts/literature_review_wrapper.py` or, when needed, `record-research-summary`. - In `--summary-only` mode, the wrapper now writes a pre-approval `research-lock-proposal.json` artifact instead of a helper-ready approved lock input. - Do not create `research-lock.json` until the human approves the research package. ### 6. Research Approval - Human approval creates the research lock. - For approval-gated runs, prefer `approve-research-proposal` so the lock can be approved directly from the stored proposal without hand-authoring approval JSON. - Keep `approve-research` only for explicit override cases where a custom approval payload is actually needed. - Update the ledger to show drafting may start. - If research is rejected, revise research first; do not draft against an unapproved evidence boundary. ### 7. Draft Creation - Write one canonical authoring JSON draft under `state/ideas/<idea_id>/drafts/` with `commit-draft`. - Keep version lineage explicit. - Stay inside the approved angle and research lock. - Prefer the frozen `fact` template for v1. - Default to a concise cover headline with one clear promise. - The cover may be more curiosity-driven than the full research framing when needed for engagement, as long as later slides add the missing nuance and the full sequence stays inside the approved lock. - Default to at least 4 content slides unless the brief or template explicitly justifies a shorter format. - Make each content slide readable on its own, give it one distinct editorial role, and use the sequence of slides to build a logical story. - Avoid adjacent slides that merely paraphrase the same claim. - Translate evidence caveats into natural consumer language instead of academic-sounding disclaimers in body slides. ### 8. QC And Validation - Run deterministic draft QC with `run-qc` before preview. - Use `scripts/runtime_state.py build-preview-payload` for payload generation. - Use helper-backed verification and checkpoints for material validation boundaries. - Any revision that changes meaning-bearing text, claim interpretation, certainty, or health implications must rerun QC. - Treat contract and character-limit violations as deterministic revise-and-retry failures, not soft style comments. ### 9. Preview Generation - Materialize preview artifacts under a version-specific folder such as `artifacts/previews/<idea-slug>-v2/`. - Verify the preview artifacts with `scripts/runtime_state.py verify-preview`. - Bind the verified preview back to the idea ledger. - Use the current preview app and public host already configured for this repo. ### 10. Preview Verification - A preview is not complete until the artifact write is verified. - Persist the preview record in `state/ideas/<idea_id>/preview.json` with `record-preview`. - Check that the viewer route exists at `/preview/<folder_name>` and, when relevant, the public URL on `agent.jonaswilbert.com`. - `verify-preview` now includes bounded HTTP checks for the viewer route and preview API route, not just artifact existence. - When public verification succeeds, the preferred recorded preview URL should be the public verified URL rather than the local `127.0.0.1:3101` URL. ### 11. Feedback Classification Classify every post-preview request into one of: - design-only revision - copy-within-lock revision - research-required revision - concept restart - final approval Do not skip classification. Do not treat vague feedback as an automatic restart. Default to `copy_within_lock` for feedback such as: - shorten the cover without changing the claim - make the cover more curiosity-driven without widening the approved claim envelope - rewrite slides into clearer consumer-facing language - translate evidence caveats into more natural consumer language without changing the evidence boundary - make content slides stand on their own - expand to more content slides without adding a new claim - reduce repetition or improve story flow inside the same approved evidence boundary ### 12. Design-Only Revision - Keep the same research lock. - Regenerate preview artifacts. - Skip research rerun. - Rerun QC only when the wording actually changes meaning. ### 13. Copy-Within-Lock Revision - Keep the same research lock. - Update the draft version. - Rerun QC when meaning-bearing text changes. - Regenerate the preview and verification artifacts. ### 14. Research-Required Revision - Reopen the workflow at research. - Replace or revise the research package and research lock. - Do not keep drafting from the old lock after the evidence boundary changes. ### 15. Concept Restart - Treat it as a new angle/concept lane. - Preserve the old run state for traceability. - Do not silently mutate the current concept into a different one. ### 16. Final Approval - Bind approval to one concrete verified preview version. - Mark the ledger complete. - Keep later edits on a new revision lane, not by mutating the approved base in place. ## Execution Rules - Use `scripts/runtime_state.py` stage helpers whenever they already cover the state mutation you need. - Use the read-only `show-*` helper commands at human gates before improvising with raw file reads. - Use `scripts/run_local_dry_run.py` as the concrete example of the intended helper sequencing. - Keep preview generation tied to `apps/carousel-web/` and repo-local artifacts. - Keep one main thread. Do not reintroduce OpenClaw-style multi-agent handoffs. - Keep Airtable optional and out of the core runtime. - Keep Slack deferred. - When feedback may become reusable repo guidance, write it first to `docs/rule-candidates.md` and wait for explicit approval before changing durable repo rules. ## When To Invoke Supporting Literature Review Invoke `$carousel-literature-review` when: - the research package does not exist yet - the user asks for new evidence or new sources - a revision introduces a new claim, interpretation, intervention, mechanism, or comparison - a health implication changes and needs new evidence support Do not invoke it for pure presentation or within-lock wording cleanup.
Save
Ready