Main Skill Design

The rationale and structure behind the main Codex workflow skill.

Design Reference · /home/jonas/social-carousel-codex/docs/main-skill-design.md

Last modified: 2026-03-29T12:51:26.545Z

# Main Skill Design

## Purpose

Phase 5 introduces one repo-local Codex skill that carries the business workflow from intake through preview and revision handling, while keeping deterministic scripts, repo-local state, and the preview app as the execution layer.

Main skill path:

- `.codex/skills/carousel-workflow/`

Skill name:

- `carousel-workflow`

## Why A Main Skill

The skill is the right place for:

- stage order
- approval discipline
- revision classification
- research-rerun rules
- workflow guardrails

The skill is not the right place for:

- atomic writes
- preview artifact storage
- managed runtime behavior
- Caddy routing
- ad hoc hidden memory

Those remain in:

- `state/`
- `artifacts/`
- `scripts/runtime_state.py`
- `apps/carousel-web/`

## Operational Model

The skill assumes:

- one main coordinating Codex thread
- repo-local files as the source of truth
- explicit human approvals
- explicit classification before revisions move downstream

It encodes these stages:

- intake
- benchmark diagnosis
- angle generation
- angle approval
- research
- research approval
- draft creation
- QC and validation
- preview generation
- preview verification
- feedback classification
- design-only revision
- copy-within-lock revision
- research-required revision
- concept restart
- final approval

## Integration With The Current Execution Layer

The main skill does not duplicate existing runtime mechanics.

It relies on:

- `scripts/runtime_state.py` for helper-backed writes across intake, angle approval, research persistence, draft commit, QC, preview binding, parked runs, and DLQ behavior
- `scripts/literature_review_wrapper.py` for the repo-local adapter around the OpenClaw literature-review search capability, including pre-approval lock proposals for approval-gated runs
- `scripts/run_local_dry_run.py` as the concrete reference for the intended per-idea sequencing
- `apps/carousel-web/` for preview generation and rendering
- `state/ideas/<idea_id>/` for durable per-idea workflow artifacts
- `state/checkpoints/<idea_id>/` for immutable material transitions
- `state/logs/<idea_id>.ndjson` for append-only operational history

It now also relies on lightweight read-only operator helpers so human gates do not require opening multiple JSON files manually:

- `show-current-run-state`
- `show-angle-options`
- `show-research-package`
- `show-latest-preview`
- `show-version-history`

## Skill Structure

Main files:

- `.codex/skills/carousel-workflow/SKILL.md`
- `.codex/skills/carousel-workflow/agents/openai.yaml`
- `.codex/skills/carousel-workflow/references/execution-layer.md`
- `.codex/skills/carousel-workflow/references/revision-rules.md`

Design intent:

- keep `SKILL.md` concise and procedural
- move path and command details into `references/`
- keep invocation simple through `$carousel-workflow`

## Decision Rules Embedded In The Skill

The main skill hard-codes the Phase 2 and fixed Phase 3/5 decisions:

- one workflow owner thread
- repo-local state is authoritative
- Airtable is optional and not core runtime state
- Slack is deferred
- the `fact` contract is frozen for v1
- any meaning-bearing change requires QC rerun
- research reruns only when the evidence boundary changes

## Approved Workflow Defaults

The skill now carries these approved defaults for future runs:

- benchmark-first intake when a benchmark screenshot and short operator context are available
- explicit benchmark diagnosis before angle generation in benchmark-first runs
- benchmark-as-inspiration rather than benchmark-as-paraphrase
- `10x better` defined as a stronger hook, more insight, better clarity, better evidence quality, and better practical usefulness
- concise cover headlines by default
- curiosity-led covers are acceptable when later slides carry the missing nuance inside the approved lock
- at least 4 content slides by default unless a shorter format is explicitly justified
- standalone readability for each content slide
- one distinct editorial role per content slide
- logical story progression across the carousel
- evidence caveats translated into natural consumer language instead of academic-sounding body-slide disclaimers
- `copy_within_lock` as the default revision lane for cover-shortening, consumer-clarity, slide-expansion, non-repetition, and story-flow fixes that do not change the evidence boundary
- version-specific preview artifact folders so later revisions do not overwrite earlier preview bundles in place
- public verified preview URLs as the preferred surfaced review URL when public verification succeeds
- pre-approval research-lock proposal artifacts so approval-only fields are not required before research approval exists

These are workflow defaults, not a license to override the research lock or the frozen contract.

## Version Traceability

The workflow now treats QC and preview state as explicitly per-version, while keeping legacy latest files for compatibility:

- latest pointers remain:
  - `state/ideas/<idea_id>/qc-result.json`
  - `state/ideas/<idea_id>/preview.json`
- version history lives under:
  - `state/ideas/<idea_id>/qc-results/<draft_version>.json`
  - `state/ideas/<idea_id>/preview-records/<draft_version>.json`

This lets the skill reason about the active latest state without losing revision-by-revision traceability.

## Rule Candidate Promotion Flow

The skill now separates approved rules from still-pending generalizations:

1. capture reusable feedback in `docs/rule-candidates.md`
2. keep the candidate in `proposed` status until explicit approval
3. update `AGENTS.md`, `SKILL.md`, workflow docs, and QC docs only after approval
4. mark the candidate promoted after the durable docs are updated

## Current Limits

The skill intentionally sits above an incomplete but working execution layer.

What it can do now:

- guide the workflow consistently
- preserve deterministic state discipline
- use the preview app and preview artifact flow
- invoke the literature-review support path

What it still does not automate end to end:

- richer retry and replay helpers around failed revisions
- deeper preview render checks beyond bounded viewer/API HTTP verification

## Invocation

Primary invocation in Codex:

```text
Use $carousel-workflow to run or continue a carousel idea in /home/jonas/social-carousel-codex from intake through preview and revision handling.
```

Ready