longrun-prd-runner

PRD → manifest → long-running coding agent execution

Run large tasklists continuously using coding agents with validation, review, retries, and human gates.

---

What this is

longrun-prd-runner is a control layer for coding agents.

It takes a PRD or task document, converts it into a structured manifest, and executes it as a sequence of agent-driven jobs that can run for hours or days.

Instead of babysitting prompts, you define the work once and let the system:

• execute tasks sequentially
• validate outputs
• run automated reviews
• attempt fixes when things fail
• escalate when needed
• pause for human approval when required
• log everything

---

Why this exists

Most coding agents are great at individual tasks.

But real work looks like:

• 20 to 200 tasks, sequentially
• dependencies between them
• failures that need fixing
• validation requirements
• long runtimes

This tool handles that layer.

---

Key features

• PRD → manifest pipeline
  Convert a PRD into executable tasks

• Sequential long-running execution
  Run tasks continuously across hours or days

• Validator-first workflow
  Tasks only advance when checks pass

• Bounded auto-remediation
  Automatically fix failures and retry

• Risk-based review routing
  Cheap review first, escalate when needed

• Human gates
  Stop for approval on critical steps

• Resumable runs
  Restart from any task

• Runtime isolation
  Worktrees + external state (.runtime/)

• Full observability
  Structured logs, summaries, notifications

• Automatic model routing
  Uses cheaper models for low-risk tasks and escalates to stronger models for:

  • validation failures
  • high-risk reviews
  • critical execution paths

  This keeps runs cost-efficient without sacrificing correctness.

---

Real usage

Built from running coding-agent workflows continuously for 24+ hours or more, with:

• sequential execution
• validator-driven progression
• automatic retry and repair
• review escalation
• resumable runs

---

Architecture

PRD
↓
Manifest (structured tasks)
↓
Task execution loop
↓
Validator → Review → Repair → Retry
↓
Next task

Components:

• planner: PRD → manifest
• policy layer: enforces safety rules
• executor: runs tasks
• validator: proves completion
• reviewer: checks correctness
• operator: attempts repairs
• sequencer: runs long multi-stage workflows

---

Repository layout

repo-root/
README.md
AGENTS.md
.codex/config.toml
.agents/skills/
automation/prd_runner/
docs/
policy/
engine/
examples/

---

Prerequisites

• Git
• Python 3.11+
• Codex CLI available in PATH
• Codex authenticated

Recommended:

• Linux / macOS / WSL
• dedicated worktree for runs
• repo-specific validators

---

First-time setup

bash automation/prd_runner/engine/scripts/install_git_hooks.sh

---

Runtime state

All runtime artifacts go to:

.runtime/prd_runner/

This includes:

• manifests
• logs
• sequences
• worktrees
• approvals
• notifier config

This directory is ignored by Git.

---

Safe quick start

1. Plan only

python3 automation/prd_runner/engine/scripts/run_prd.py \
  --prd automation/prd_runner/examples/prd/toy_release_prd.md \
  --plan-only

2. Dry run

python3 automation/prd_runner/engine/scripts/run_queue.py \
  --manifest automation/prd_runner/examples/manifests/toy_release_manifest.json \
  --dry-run

3. Run one task

python3 automation/prd_runner/engine/scripts/run_queue.py \
  --manifest automation/prd_runner/examples/manifests/toy_release_manifest.json \
  --task-id T1.1

---

Unattended execution (advanced)

python3 automation/prd_runner/engine/scripts/run_queue.py \
  --manifest .runtime/prd_runner/manifests/my_program.json \
  --auto-remediate \
  --allow-review-blockers \
  --allow-partial-tasks \
  --max-auto-remediation-attempts 1

Only use this after validating:

• manifest correctness
• validators
• review policy

---

Sequence multiple runs

python3 automation/prd_runner/engine/scripts/run_sequence.py \
  --sequence automation/prd_runner/examples/sequences/example_milestone8_by_phase.json

---

Safety model

Validators fail closed

Missing validators = failure by default.

Use only for demos:

--allow-missing-project-validators

Manifest policy enforced

All manifests are checked against repo policy before execution.

---

Logs

Single run:

.runtime/prd_runner/runs/<run_id>/

Sequences:

.runtime/prd_runner/sequences/<sequence_id>/

---

Cleanup

python3 automation/prd_runner/engine/scripts/runtime_cleanup.py --max-age-days 14

---

Not another agent

This is not a model.

It is an orchestration layer for long-running work on top of coding agents.

---

Status

Alpha / experimental

Useful now, evolving quickly.

---

License

Apache License 2.0

See LICENSE file.

---

Contributing

Feedback is highly welcome, especially on:

• validator design
• review routing
• backend adapters
• CI integration
• real-world use cases

---

Summary

longrun-prd-runner = control plane for long-running coding agent workflows

PRD in → tasks executed → validated → reviewed → fixed → continued