Skip to main content

Loops Overview

Current status​

Loop automation is an opt-in workflow for broad, intentionally repeated work. It is not the default process for an ordinary documentation or code edit.

The repository currently tracks the documentation-update PRD surface:

  • .agents/tasks/prd-doc-update.json
  • .agents/tasks/templates/prd-doc-update.template.json
  • .agents/tasks/prd-active.json (convenience copy used by loop examples)

Repo-local skills provide intake, guideline compilation, PRD bootstrap, documentation bootstrap, and documentation-update bootstrap behavior under .codex/skills/**. Several pages in this section retain designs for other loop types whose templates/prompts are not currently checked in; those pages are reference designs, not runnable inventory claims.

Intended pipeline​

The exact engine installation is local/operator state; .agents/ralph is not tracked in this repository. Verify the engine and agent command before starting a run.

Safety boundaries​

  • Use loop skills only when intentionally running a loop flow.
  • Keep prototypes and transient run state out of commits.
  • Do not commit .ralph/.tmp/**, .ralph/.runs/**, activity/error logs, or generated dry-run output.
  • A loop does not broaden deployment, production, messaging, or external-write authority.
  • Preserve unrelated work and follow the repository's small-checkpoint commit discipline.
  • For documentation maintenance, prefer doc-update-scope → doc-update-targeted → doc-update-validate when a bounded source change already defines the scope.

Available pages​

  • Documentation update loop: current tracked PRD contract.
  • Documentation bootstrap loop: bootstrap design for a deliberately full regeneration.
  • Run guide: prerequisites and safe execution checks.
  • Code-quality, release, Bruno, and post-commit pages: retained design references; restore their named templates/prompts before treating them as runnable.

Before running​

  1. Confirm the applicable skill exists and read its SKILL.md completely.
  2. Confirm every referenced template, prompt, script, and engine path exists.
  3. Define scope, prohibited files, validation, commit policy, and external-write boundaries.
  4. Run in a clean/isolated worktree when automation will commit.
  5. Remove transient artifacts after the result has been reviewed or absorbed.