Skip to main content

Run Guide

Prerequisites​

  • The applicable loop/bootstrap skill exists under .codex/skills and its SKILL.md has been read completely.
  • Every template, prompt, script, and engine path referenced by that skill exists locally.
  • A loop engine/agent command is installed. This repository does not currently track .agents/ralph, so do not copy commands that assume it exists.
  • The worktree status, branch, scope, write authority, validation, and commit policy are understood.

Bootstrap​

Use the repo-local skills in this order when their contracts apply:

  1. loop-intake captures intent and constraints.
  2. loop-guideline-compiler produces strict guidelines.
  3. loop-prd-bootstrap builds the task PRD.
  4. A domain bootstrap such as docs-update-loop-bootstrap performs any workflow-specific setup.

For documentation updates, the checked-in convenience state is .agents/tasks/prd-active.json; the canonical maintained PRD is .agents/tasks/prd-doc-update.json. Confirm the selected skill's expected path before changing either file.

Execute​

The actual command depends on the locally installed loop engine. Do not invent a generic shell invocation. Configure the engine to:

  • process one independently verifiable story at a time;
  • stop on missing authority, ambiguous destructive work, or failed safety gates;
  • preserve unrelated changes;
  • make small checkpoint commits only when the user authorized commits;
  • record validation and unresolved gaps.

Monitor and recover​

Inspect the active PRD, worktree diff, test output, and engine-owned logs. A story should not remain in_progress without a live process or evidence. On failure, identify whether the blocker is source ambiguity, missing setup, validation failure, external state, or authority before retrying.

Do not mark a story complete because a command ran; its acceptance criteria and evidence must pass.

Cleanup​

Retain intentional source/docs changes and reviewed task artifacts. Remove local dry runs, generated reports, engine caches, and transient .ralph/.tmp/**, .ralph/.runs/**, activity, and error logs. Never commit tokens, local data drops, or production evidence that has not been sanitized.

See Loops overview and the root AGENTS.md loop policy.