orange-dot · orange-dot · Apr 16, 2026
diff --git a/README.md b/README.md
@@ -1,28 +1,29 @@
 # Cooperations
 
-Local-first research toolkit for orchestrating specialized AI agents in software workflows.
+Local-first configurable flow runner for inspectable AI, shell, and human-in-the-loop workflows.
 
-Cooperations explores a role-based workflow built around explicit handoffs between `architect`, `implementer`, `reviewer`, and `navigator` agents. The implemented runtime is intentionally narrow and truthful: it is **Codex CLI-first**, **Linux/bash-oriented**, and stores task history, handoffs, generated artifacts, sandbox mode, and activated task capabilities on disk.
+Cooperations is intentionally narrow and truthful. It is **Codex CLI-first**, **Linux/bash-oriented**, and built around explicit workflow state instead of opaque autonomous runs. Every task resolves to a declarative `flow`, an `execution profile`, and a `project policy`, then records handoffs, artifacts, sandbox posture, and task-scoped capabilities on disk.
 
-## Why Inspectable Workflow
+## Why Inspectable Flows
 
-Cooperations is not trying to hide orchestration behind a single opaque agent run. The core idea is that software work is easier to trust when the execution contract stays visible:
+The core idea is that software and operator work becomes easier to trust when the execution contract stays visible:
 
-- each task declares its sandbox up front
-- capabilities are explicit and task-scoped
-- handoffs and artifacts are stored locally
-- the TUI shows live workflow state and ends in a completion/error view
-- when an interactive TTY is unavailable, `coop tui` falls back to plain workflow output instead of crashing
+- the selected flow is explicit before execution starts
+- sandbox, capabilities, and runtime posture are part of the task input
+- project-local policy decides which roles can use which providers and models
+- approvals, reports, and artifacts are stored locally
+- `run --dry-run` and `flows validate` show what will happen before model tooling runs
+- `coop tui` falls back to plain workflow output instead of crashing when no real TTY is available
 
 This keeps the runtime honest about what happened, what was allowed, and where the result ended up.
 
 ## Status
 
 See [docs/STATUS.md](docs/STATUS.md) for the source-of-truth status matrix. In short:
 
-- Implemented core: Codex CLI orchestration, heuristic routing, per-task sandbox contract, optional task-scoped capabilities, local task/handoff storage
+- Implemented core: configurable flow engine, built-in flows/profiles/policies, `flows list|show|validate|generate-task`, Codex CLI execution, local task/handoff/artifact storage
 - Secondary interfaces: Bubble Tea TUI and an opt-in Gio GUI build
-- Experimental/reference: RVR, meta-cognitive reasoning notes, benchmark and planning documents
+- Experimental/reference: RVR, long-form planning documents, benchmark/research notes
 
 ## Quick Start
 
@@ -31,7 +32,7 @@ Requirements:
 - Linux with bash
 - Go 1.24+
 - Installed `codex` CLI
-- Optional local overrides from `.env.example`
+- Optional `.env` overrides copied from `.env.example`
 
 The repository does not use the OpenAI API directly. Authenticate `codex` through its own CLI flow before running real tasks.
 
@@ -42,117 +43,138 @@ cp .env.example .env
 go build -o coop ./cmd/coop
 ```
 
-Inspect routing without running model tooling:
+Inspect built-ins and resolve a flow without executing anything:
 
 ```bash
-./coop run --dry-run "implement a health check endpoint"
-./coop history
+./coop flows list
+./coop flows show software_patch
+./coop flows validate --task-file examples/configurable-flows/software_patch.task.yaml
+./coop run --dry-run --task-file examples/configurable-flows/software_patch.task.yaml
 ```
 
-Run a real task with an explicit sandbox:
+Generate or run a real task:
 
 ```bash
+./coop flows generate-task --workflow software_patch > /tmp/software_patch.task.yaml
+./coop run --task-file examples/configurable-flows/software_patch.task.yaml
 ./coop run --sandbox workspace-write "implement a health check endpoint"
-./coop run --task-file examples/feature-request.json
-./coop run --task-file examples/feature-request.yaml --capability skill:playwright
 ```
 
 Optional interfaces:
 
 ```bash
-./coop tui --sandbox workspace-write "implement a health check endpoint"
+./coop tui --task-file examples/configurable-flows/software_patch.task.yaml
 go build -tags gio -o coop ./cmd/coop
 ./coop gui --demo "review the workflow"
 ```
 
-`coop tui` is the first-class interactive path when a real TTY is available. In non-interactive environments it automatically falls back to plain workflow output and still runs the task instead of failing with a terminal panic.
+## Built-In Presets
 
-## What Works Now
+Cooperations currently ships three built-in flows:
 
-- Keyword/heuristic routing into specialized roles
-- Task-scoped sandbox enforcement for real runs
-- Optional task-scoped capability references:
-  - `plugin:<name>`
-  - `plugin_skill:<plugin>:<skill>`
-  - `skill:<name>`
-- Local task persistence under `.cooperations/`
-- Generated artifacts and task summaries under `generated/`
-- Shared workflow event model used by the orchestrator, TUI, and GUI
-- TUI completion/error views with summary-first result rendering
-- Plain CLI fallback for `coop tui` when no controlling TTY is available
+- `software_patch`: plan, implement, review, approval, and final report
+- `recon_assessment`: validate targets, run an `mcp`-typed recon step, wait/review, and report
+- `incident_triage`: classify, gather context in parallel, approval gate, dispatch artifact, and report
 
-## Runtime Contract
+Built-in execution profiles:
 
-- Real workflow execution requires an explicit sandbox on every task.
-- Supported sandbox modes are `read-only`, `workspace-write`, and `danger-full-access`.
-- Capability references are optional; when omitted, the task runs as a regular Codex model task.
-- If a capability is explicitly requested but not available locally, the task fails before execution.
-- `run --dry-run`, `status`, and `history` do not require Codex CLI initialization.
-- `tui` uses the same task contract as `run`; when interactive terminal startup fails, it falls back to plain workflow output with progress, summary, and artifact paths.
+- `default_workspace_write`
+- `recon_conservative`
+- `incident_conservative`
 
-## Example Transcript
+Built-in project policy:
 
-The intended proof shape is a real `read-only` repository task, not a polished screenshot. This is a real non-interactive `tui` fallback run from this repository:
+- `default_local`
 
-```text
-$ ./coop tui --sandbox read-only "Read this repository and summarize what it does in one short paragraph. Do not modify any files."
-[fallback] interactive TUI unavailable: interactive TUI requires a controlling TTY: stdin and stdout must be interactive terminals
-[fallback] continuing with plain workflow output
-[workflow] plain fallback mode
-Task: Read this repository and summarize what it does in one short paragraph. Do not modify any files.
-Sandbox: read-only
-Capabilities: none
+`recon_assessment` is intentionally truthful today: its config can be inspected and validated, but default CLI runs still fail closed unless an MCP executor is wired into the runtime.
 
--> [  0%] Starting: Running task: Read this repository and summarize what it does in one short paragraph. Do not modify any files.
--> Task completed successfully!
+## Config Model
 
-[COMPLETE] Read this repository and summarize what it does in one short paragraph. Do not modify any files.
-Task ID: 1776299534231852928
-Status: completed
-Sandbox: read-only
-Capabilities: none
-Summary: generated/1776299534231852928/README.md
-```
+Every task resolves through four pieces:
 
-The exact roles, progress lines, and artifacts vary by task, but the contract stays the same: progress is visible, the result is inspectable, and the generated summary path is printed at the end.
+- `flow`: the workflow graph and step types
+- `execution profile`: sandbox posture, capabilities, retry/parallel policy, and runtime defaults
+- `project policy`: role-to-provider/model rules and privileged execution policy
+- `task file`: the concrete task description, inputs, and optional seeded approvals
 
-## Stability Tiers
+Local overrides are discovered in both of these roots:
 
-### Implemented Core
+- `cooperations/`
+- `.cooperations/`
 
-- `coop run`, `coop status`, `coop history`
-- Codex-only role/profile runtime wiring
-- Per-task sandbox and capability contract
-- Local handoff and artifact persistence
-- TUI stream/event model
+Supported local override paths:
 
-### Secondary Interfaces
+- `cooperations/flows/<id>.yaml`
+- `cooperations/profiles/<id>.yaml`
+- `cooperations/project-policy.yaml`
+- `.cooperations/flows/<id>.yaml`
+- `.cooperations/profiles/<id>.yaml`
+- `.cooperations/project-policy.yaml`
 
-- `coop tui` for interactive workflow execution
-- `coop gui` as an exploratory interface for demo and playback flows when built with `-tags gio`
+## Examples
 
-### Experimental / Reference
+Runnable examples live under [examples/configurable-flows](examples/configurable-flows):
 
-- RVR and confidence-scoring documents in `docs/`
-- Long-form planning and design documents
-- Historical evaluation notes in `docs/WORK_JOURNAL.md`
+- `software_patch.task.yaml`
+- `software_patch.seeded-approval.task.yaml`
+- `recon_assessment.task.yaml`
+- `incident_triage.task.yaml`
+- `incident_triage.seeded-approval.task.yaml`
+- `local-overrides/` cookbook showing project-local config overrides
+
+These files are meant to pair with the new CLI surface:
+
+```bash
+./coop flows validate --task-file examples/configurable-flows/incident_triage.task.yaml
+./coop flows generate-task --workflow incident_triage --seed-approval approve
+./coop run --task-file examples/configurable-flows/software_patch.seeded-approval.task.yaml
+```
+
+## Runtime Contract
+
+- Real workflow execution requires an explicit sandbox on every task, either in the task file or via `--sandbox`.
+- Supported sandbox modes are `read-only`, `workspace-write`, and `danger-full-access`.
+- Capability references are optional; when omitted, the task runs with the selected flow/profile/policy defaults.
+- If a capability is explicitly requested but not available locally, validation and execution fail closed.
+- `run --dry-run`, `flows list`, `flows show`, `flows validate`, `status`, and `history` do not require Codex CLI initialization.
+- `flows validate --probe` performs deeper local executor checks, but it does not fake backend readiness when no executor is wired.
+- `tui` uses the same task contract as `run`; when interactive terminal startup fails, it falls back to plain workflow output with progress, summary, and artifact paths.
+
+## What Works Now
+
+- Declarative flows with typed states such as `agent`, `shell`, `mcp`, `approval`, `choice`, `wait`, `parallel`, `report`, `artifact`, `succeed`, and `fail`
+- Flow/profile/policy discovery through `coop flows list`
+- Resolved config inspection through `coop flows show`
+- Safe preflight validation through `coop flows validate`
+- Starter task-file generation through `coop flows generate-task`
+- Task-scoped sandbox enforcement for real runs
+- Optional task-scoped capability references:
+  - `plugin:<name>`
+  - `plugin_skill:<plugin>:<skill>`
+  - `skill:<name>`
+- Local task persistence under `.cooperations/`
+- Generated artifacts and task summaries under `generated/`
+- Shared workflow event model used by the orchestrator, TUI, and GUI
+- Plain CLI fallback for `coop tui` when no controlling TTY is available
 
 ## Project Layout
 
-- `cmd/coop/`: CLI entrypoint
-- `internal/orchestrator/`: workflow engine, task parsing, config, hooks, and routing
+- `cmd/coop/`: CLI entrypoint and flow-oriented command surface
+- `internal/orchestrator/`: flow engine, config loading, validation, and execution
 - `internal/agents/`: role-specific agent wrappers
 - `internal/adapters/`: Codex CLI adapter and legacy/reference adapters
 - `internal/capabilities/`: local capability resolution for plugins and skills
 - `internal/context/`: local task, handoff, and artifact storage
 - `internal/tui/`: Bubble Tea interface and shared workflow stream types
 - `internal/gui/`: Gio-based exploratory interface
+- `examples/configurable-flows/`: runnable task files and local override cookbook
 - `docs/`: status, usage, plans, and research/reference material
 
 ## Documentation
 
 - [docs/STATUS.md](docs/STATUS.md): current implemented vs experimental behavior
 - [docs/USAGE.md](docs/USAGE.md): command usage and runtime expectations
+- [examples/configurable-flows](examples/configurable-flows): runnable task-file cookbook
 - [docs/STRATEGY.md](docs/STRATEGY.md): research/strategy direction
 - [docs/WORK_JOURNAL.md](docs/WORK_JOURNAL.md): historical evaluation notes