AGENTS.md

The repo-level operating policy that governs how Codex should work here.

Agent Behavior · /home/jonas/social-carousel-codex/AGENTS.md

Last modified: 2026-03-29T12:50:52.837Z

# AGENTS.md

## Purpose

This repository is the Codex-native replacement environment for a standardized social media carousel workflow.

The repo now contains a Phase 3 local runtime skeleton:

- Phase 1 audited and documented the live OpenClaw environment
- Phase 2 reconstructed the current workflow and translated it into a Codex-native design
- Phase 3 implemented the first repo-local control plane, dry run, and preview app skeleton

The live OpenClaw system remains the production reference. This repo is still side-by-side migration work, not cutover.

## Non-Negotiables

- Treat `/home/openclaw/workspace` and `/home/openclaw/.openclaw/*` as reference-only unless the user explicitly authorizes live changes there.
- Do not delete, move, overwrite, or "clean up" anything in the existing OpenClaw workspace.
- Do not implement Slack integration in this repository until a later approved phase.
- Do not commit secrets. Keep real values in untracked local env files only.
- Prefer deterministic file state over hidden memory, implicit defaults, or one-off shell mutations.

## Working Model

- Default to one main Codex agent or thread for real workflow execution.
- Use planning mode for architectural work, migrations, or schema changes.
- Use parallel threads only for bounded tasks with disjoint write scopes.
- Prefer Git worktrees over multiple agents editing the same checkout.
- Keep the current plan, assumptions, and migration notes in tracked files under `docs/`.

## Source Of Truth Rules

- Human intent, migration decisions, and architecture notes belong in `docs/`.
- Runtime control state belongs in `state/`.
- Generated previews and exports belong in `artifacts/`.
- Each idea uses one ledger file at `state/ideas/<idea_id>/ledger.json`.
- Material stage transitions write immutable checkpoints under `state/checkpoints/<idea_id>/`.
- Operational events append to `state/logs/<idea_id>.ndjson`.
- Scripts must be restart-safe, explicit about inputs and outputs, and safe to run more than once when practical.
- Any future externally visible route or service change must include a documented rollback path before rollout.

## Workflow Defaults

- Default the social-carousel workflow to benchmark-first intake when a benchmark screenshot and short operator context are available.
- Persist benchmark context durably and diagnose the benchmark explicitly before angle generation.
- Treat the benchmark as inspiration for a stronger replacement, not as copy to paraphrase.
- In this workflow, `10x better` means a stronger hook, more insight, better clarity, better evidence quality, and better practical usefulness.
- Default carousel copy to one concise cover promise rather than a long multi-idea headline.
- When it helps engagement, the cover may be more curiosity-led than the full research framing as long as later slides add the missing nuance inside the approved lock.
- Default to at least 4 content slides unless the brief or template explicitly justifies a shorter format.
- Each content slide should carry a complete thought on its own, serve one distinct editorial role, and advance a logical story.
- Avoid repetitive paraphrases of the same claim across adjacent content slides.
- Translate evidence caveats into natural consumer language instead of academic-sounding disclaimers in body slides.
- Feedback such as shorter cover copy, clearer consumer phrasing, stronger standalone readability, better story flow, or a higher content-slide count inside the same evidence boundary should default to `copy_within_lock`.

## Reusable Rule Flow

- When human feedback looks reusable beyond the current idea, persist it first in `docs/rule-candidates.md` as a proposed candidate.
- Do not update `AGENTS.md`, `SKILL.md`, workflow docs, or QC docs from that feedback until approval is explicit.
- After approval, promote only the smallest durable rule change that solves the recurring problem and mark the candidate as promoted.

## Build And Exposure Rules

- Keep the future Codex app side-by-side with the existing OpenClaw app until an explicit cutover phase.
- Do not reuse the live `/c/*` or `/api/carousel/*` routes during early migration work.
- Prefer a dedicated localhost port for the new app such as `127.0.0.1:3101`.
- Reuse Caddy patterns where sensible, but with distinct prefixes or a distinct hostname for the Codex app.
- Avoid Docker-bridge-only assumptions such as `172.17.0.1` in the new design unless a later requirement proves they are necessary.

## Before Major Changes

1. Read `docs/README.md`, `docs/plan.md`, `docs/current-state-audit.md`, and `docs/target-architecture.md`.
2. Confirm the change does not touch the live OpenClaw workspace or routes by accident.
3. Update docs when decisions or assumptions change.
4. Keep rollback steps explicit whenever changing service, routing, or state layout behavior.

## Current Runtime Entry Points

- `scripts/runtime_state.py` is the runtime helper surface for intake, angle approval, research persistence, draft commit, QC, preview binding, park, and DLQ operations.
- `scripts/run_local_dry_run.py` is the deterministic fixture-driven proof path for the local control plane.
- `apps/carousel-web/` is the local preview app skeleton and must stay separate from the live OpenClaw app and routes.
- `.codex/skills/carousel-workflow/` is the main repo-local Codex skill for the business workflow.
- `.codex/skills/carousel-literature-review/` is the supporting research-synthesis skill and should remain subordinate to the main workflow and repo-local state.

Ready