agent-workloops

agent-workloops is a portable durable work-loop schemas plus optional hosted packages for plan approval, leasing, UI review, and Codex execution.

Quick Orientation

• Portable durable work-loop schemas and deterministic state transitions for agent-run work that should survive beyond a single agent session.
• Optional hosted packages add plan submission, manual approval, client-token execution leases, completion archive, and a review UI.
• Host systems keep their own tracker adapters, review engines, notification routing, and private deployment policy.
• The public package provides a generic Codex launch envelope for writing bounded slice prompts and outcome contracts.
• Adopted portfolio repos should feed public-safe generic workflow friction back into this core instead of accumulating downstream prompt caveats.

Normal Use

• Verify meaningful changes with pnpm test to run repository test suite.

What This Repo Does

• Defines public WorkLoop and WorkLoopSlice contracts.
• Selects the next safe slice from durable loop state.
• Adjudicates outcome plus peer-review evidence into controller decisions.
• Applies controller decisions without depending on a specific tracker or agent runtime.
• Provides optional server, shared API, CLI, and web UI packages around the public core.

Non-Goals

• No Linear, Jira, GitHub, or Slack adapter.
• No bundled peer-review engine.
• No private orchestration policy.

Where Things Live

• .agent-atlas/ - Canonical Atlas metadata and overlays.
• packages/ - Workspace packages and implementation surfaces.
• apps/ - Application and CLI entrypoint surfaces.
• docs/ - Human-authored documentation.
• examples/ - Examples and sample fixtures.

Key Docs

• Agent Atlas
• Operating Model
• Contributor Safety

Domains

• domain:durable-agent-workflows - Durable Agent Workflows: State contracts and deterministic transitions for multi-step agent work that must not be marked done after one incomplete run.

Key Implementation Surfaces

• component:ai-quality-loops-adapter - AI Quality Loops Adapter: Dependency-free adapter shape that maps WorkLoop slice outcome context into an ai-quality-loops review request and returns WorkLoop peer-review evidence.
• component:workloop-adjudication - WorkLoop Adjudication: Pure helpers for converting outcome and peer-review evidence into controller decisions and applying those decisions to loop state.
• component:workloop-codex-launcher - WorkLoop Codex Launcher: Generic Codex execution envelope for durable WorkLoop slices, including bounded prompts, fresh or same-session launch records, and required outcome paths.
• component:workloop-schema - WorkLoop Schema: Zod schemas and TypeScript types for durable loops, slices, policies, decisions, and current-state envelopes.
• component:workloop-selection - WorkLoop Selection: Pure helpers for choosing the next executable slice, finding active work, and incrementing slice attempts.

Drill Down

• Atlas overview: docs/agents/atlas.md.
• Task-scoped Atlas navigation: atlas context-pack "<task>" --path . --budget 4000 or atlas resolve-path <path> --path ..
• Entity indexes: docs/agents/domains/, docs/agents/workflows/, docs/agents/components/, and docs/agents/capabilities/.
• Source-derived inventory: docs/generated/source-derived-reference.md.
• Documentation map: Agent Workloops.

Verification

• pnpm test - Run repository test suite.
• pnpm check - Verify TypeScript, tests, and Atlas drift.
• Scoped verification map: docs/agents/verification.md.

Commands

• pnpm test - Run repository test suite.
• pnpm check - Verify TypeScript, tests, and Atlas drift.

Generated Source

• This README is generated from Agent Atlas metadata. Update .agent-atlas/** or the referenced canonical docs, then regenerate it.