Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/glav/teamautobot

A revision built from learnings from teambot and other agent TUI's that suit my workflow
https://github.com/glav/teamautobot

Last synced: about 1 month ago
JSON representation

A revision built from learnings from teambot and other agent TUI's that suit my workflow

Awesome Lists containing this project

README 

          
# TeamAutobot



**TeamAutobot** is an AI agent orchestration system for goal-driven software work. It is being built as an evolution of TeamBot v1's linear pipeline into a planner-led, multi-agent system with stateful agents, a task graph, an event log, and file-backed observability.



For the full design, see [`docs/teamautobot-design.md`](docs/teamautobot-design.md).



## Start here



### 1) Set up the repo



Requires [uv](https://docs.astral.sh/uv/) for dependency management.



```bash

uv sync

cp .env-sample .env  # fill in values if you plan to use Azure OpenAI

```



### 2) Sanity-check the CLI



```bash

uv run python -m teamautobot.cli status --json

```



Expected output shape:



```json

{

  "env_loaded": true,

  "name": "TeamAutobot",

  "python": "3.12.x",

  "runtime": "ready",

  "version": ""

}

```



The main success signal is `"runtime": "ready"`. `env_loaded` tells you whether

TeamAutobot found and loaded a `.env` file; it can still be `false` if you are

only using deterministic/local flows and have not configured Azure OpenAI yet.



### 3) Run the fastest first demos



```bash

uv run python -m teamautobot.cli demo --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --json

```



- `demo` is the narrow **single-agent** path.

- `planner full-team-demo` is the broader **planner + multi-agent** path.

- Runs write artifacts under `.teamautobot/demo-runs/` and `.teamautobot/planner-runs/`.



### 4) Inspect a recorded planner run



```bash

uv run python -m teamautobot.cli planner replay --run-dir .teamautobot/planner-runs/

```



Use the `run_dir` returned by a previous planner command.



## Working demo MVP



The locked `working-demo-todo-summary` demo proves that TeamAutobot can take a

repo-owned objective, mutate only the intended source and test files in a copied

scratch workspace, pass review, run acceptance, and publish replayable final

summary artifacts.



The ship-blocking verifier for this MVP is the deterministic smoke test:



```bash

uv run pytest tests/test_planner.py::test_run_full_team_demo_working_demo_todo_summary_smoke_path -q

```



That smoke path uses the scripted/fake live harness and is the required

validation surface. The live walkthrough below is optional and additive.



### Reset the scratch workspace



```bash

uv run python -m teamautobot.cli planner prepare-working-demo \

  --fixture working-demo-todo-summary \

  --json

```



By default this creates or resets:



```text

.teamautobot/working-demo-workspaces/working-demo-todo-summary

```



### Run the optional live walkthrough



```bash

uv run python -m teamautobot.cli planner full-team-demo \

  --provider azure_openai \

  --objective-file objectives/working-demo-todo-summary.md \

  --workspace-dir .teamautobot/working-demo-workspaces/working-demo-todo-summary \

  --json

```



### Inspect the resulting run



```bash

uv run python -m teamautobot.cli planner replay \

  --run-dir .teamautobot/planner-runs/ \

  --json

```



## First real repo objective



The working demo above proves the end-to-end planner flow against a tiny fixture. When you want to

run TeamAutobot against the **actual TeamAutobot repo**, use a dedicated git-backed scratch

workspace instead of pointing the live run at your primary checkout.



The objective file for this flow should be a tracked, clean repo artifact under the repo-owned

`objectives/` directory. `objectives/real-repo-workspace-metadata.md` is the current proven

example for this safe scratch-workspace path.



### Create from an objective



```bash

uv run python -m teamautobot.cli planner create \

  --objective-file objectives/real-repo-workspace-metadata.md \

  --json

```



`planner create` is the first-class safe path for asking TeamAutobot to produce repo changes from

an objective. It preflights the live provider, prepares a detached git worktree, runs the live

full-team workflow with `azure_openai` by default, validates any captured `live_commit_candidate`

against your target checkout, and reports next commands for harvesting or approval-gated committing.

It does not copy candidate files into your primary checkout or create a commit by itself. Use

`--skip-provider-preflight` only after manually confirming the provider deployment is reachable. If

the live run fails, the response includes a compact `failure_summary` with failed task messages and

targeted troubleshooting commands for common provider-configuration failures; other `planner create`

responses keep `failure_summary: null` so JSON consumers can handle the field consistently.



When Azure OpenAI preflight fails, inspect `provider_preflight.effective_model` and

`provider_preflight.model_source` to see whether the deployment came from `--model` or

the `AZURE_OPENAI_MODEL_DEPLOYMENT` environment variable; verify alternatives with

`uv run python -m teamautobot.cli azure-openai complete --model  --input "Reply with OK." --json`,

then rerun `planner create --model ` with the working deployment.



### Prepare a safe git-backed scratch workspace



```bash

uv run python -m teamautobot.cli planner prepare-repo-workspace \

  --objective-file objectives/real-repo-workspace-metadata.md \

  --json

```



By default this creates or resets a collision-safe workspace path derived from the repo-relative

objective path:



```text

.teamautobot/live-workspaces/real-repo-workspace-metadata

```



The prepared workspace is a detached `git worktree` at the current `HEAD`, so live review tools

such as `git_status` and `show_file_diff` still work while your main checkout stays untouched.



### Run the first real repo objective



```bash

uv run python -m teamautobot.cli planner full-team-demo \

  --provider azure_openai \

  --objective-file objectives/real-repo-workspace-metadata.md \

  --workspace-dir .teamautobot/live-workspaces/real-repo-workspace-metadata \

  --json

```



Use `planner replay` or `planner dashboard` with the returned `run_dir` to inspect the result the

same way you would for the working-demo fixture flow.



## What to read next



| Need | Go here |

|------|---------|

| Architecture and current design | [`docs/teamautobot-design.md`](docs/teamautobot-design.md) |

| Repo map, conventions, workflow pointers | [`AGENTS.md`](AGENTS.md) |

| Objective template for planner/full-team runs | [`docs/sdd-objective-template.md`](docs/sdd-objective-template.md) |

| ADRs and implementation plans | [`docs/decision-records/`](docs/decision-records/) and [`docs/plans/`](docs/plans/) |



## Core concepts



- **Goal Planner** decomposes objectives into a task graph, assigns work, and can re-plan after milestones.

- **Agent Pool** treats roles as templates rather than fixed slots, so builders can fan out when the graph allows it.

- Runtime ids such as `builder-1` and `builder-2` should be treated as instances of the `builder` template rather than as separate long-term roles.

- **Event Bus** records typed activity across planning, execution, review, and observability surfaces.

- **Context Store** is intended to prefer summaries first, then deeper artifacts and retrieval on demand.



## Command guide



Use `uv run python -m teamautobot.cli --help` or

`uv run python -m teamautobot.cli  --help` when you want the full

flag surface without keeping every option expanded inline in this README.



### Everyday commands



| Use case | Command |

|----------|---------|

| Prepare a real repo scratch workspace | `uv run python -m teamautobot.cli planner prepare-repo-workspace --objective-file objectives/real-repo-workspace-metadata.md --json` |

| Create from a real repo objective | `uv run python -m teamautobot.cli planner create --objective-file objectives/real-repo-workspace-metadata.md --json` |

| CLI status | `uv run python -m teamautobot.cli status --json` |

| Single-agent deterministic demo | `uv run python -m teamautobot.cli demo --json` |

| Planner-only demo | `uv run python -m teamautobot.cli planner demo --json` |

| Builder-reviewer gate demo | `uv run python -m teamautobot.cli planner review-demo --json` |

| Full-team deterministic happy path | `uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --json` |



### Observability and operator commands



| Use case | Command |

|----------|---------|

| Replay one run | `uv run python -m teamautobot.cli planner replay --run-dir .teamautobot/planner-runs/` |

| Compare two runs | `uv run python -m teamautobot.cli planner replay-compare --left-run-dir .teamautobot/planner-runs/ --right-run-dir .teamautobot/planner-runs/` |

| Follow latest run state | `uv run python -m teamautobot.cli planner follow --run-dir .teamautobot/planner-runs/` |

| Tail live run snapshots | `uv run python -m teamautobot.cli planner follow --run-dir .teamautobot/planner-runs/ --tail` |

| Stream operator dashboard | `uv run python -m teamautobot.cli planner dashboard --run-dir .teamautobot/planner-runs/` |

| Request a pause between tasks | `uv run python -m teamautobot.cli planner intervene --run-dir .teamautobot/planner-runs/ --action pause --json` |

| Answer a paused human clarification | `uv run python -m teamautobot.cli planner respond --run-dir .teamautobot/planner-runs/ --answer "..." --json` |

| Redirect a paused live work task | `uv run python -m teamautobot.cli planner redirect --run-dir .teamautobot/planner-runs/ --task-id implement-feature-slice --message "Use notes/live-implementation.md only" --json` |

| Resume a paused run | `uv run python -m teamautobot.cli planner resume --run-dir .teamautobot/planner-runs/ --json` |

| Request durable-guidance promotion approval | `uv run python -m teamautobot.cli planner promote-feedback --run-dir .teamautobot/planner-runs/ --review-task-id review-implementation --feedback-index 1 --rule-id implementation-evidence --title "Require implementation evidence" --json` |

| Request live git commit approval | `uv run python -m teamautobot.cli planner request-live-commit --run-dir .teamautobot/planner-runs/ --message "Ship the live workspace changes" --json` |

| Request a policy-bypass override to continue a blocked full-team run | `uv run python -m teamautobot.cli planner request-policy-override --run-dir .teamautobot/planner-runs/ --json` |

| Approve a pending planner approval request | `uv run python -m teamautobot.cli planner approve --run-dir .teamautobot/planner-runs/ --approval-id  --json` |

| Deny a pending planner approval request | `uv run python -m teamautobot.cli planner deny --run-dir .teamautobot/planner-runs/ --approval-id  --reason "Keep this guidance local for now" --json` |



### Quality commands



```bash

uv sync --group dev

uv run pytest

uv run ruff check .

uv run ruff format .

```



## Detailed usage



Single-agent demo and Azure OpenAI live demo



The default `demo` path is deterministic. A narrow live slice is available with Azure OpenAI:



```bash

uv run python -m teamautobot.cli demo --json

uv run python -m teamautobot.cli demo --provider azure_openai --workspace-dir . --task "Summarize README changes into notes/live-demo.md" --json

uv run python -m teamautobot.cli demo --provider azure_openai --workspace-dir . --objective-file docs/sdd-objective-template.md --json

```



Current live-demo scope is intentionally limited: the agent only gets bounded

workspace and repo-inspection tools (`list_files`, `read_file`, `search_text`,

`git_status`, `show_file_diff`, `run_pytest`, `write_file`, and

`replace_in_file`). No shell or network tools are exposed through this path.

Repo-aware inspection covers bounded UTF-8 content search across workspace

files (honoring `.gitignore` rules via `search_text`), bounded repo status

summaries (`git_status`), git-backed per-file diffs for both tracked and

untracked files (`show_file_diff`), and targeted pytest validation with cache

writes disabled (`run_pytest`). None of these tools expose shell execution,

network access, or operations outside the configured workspace.



Planner and full-team flows



```bash

uv run python -m teamautobot.cli planner demo --json

uv run python -m teamautobot.cli planner review-demo --json

uv run python -m teamautobot.cli planner review-demo --json --review-decision rejected

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --json

uv run python -m teamautobot.cli planner full-team-demo --objective-file objectives/my-feature.md --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --review-decision rejected --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --acceptance-status failed --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --dynamic-replanning --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --dynamic-replanning --builder-count 3 --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --review-decision rejected --dynamic-replanning --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --checkpoint-policy record-only --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --durable-guidance-path .agent/standards/durable-guidance.json --json

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a deterministic feature slice" --task-additional-capability-categories implement-feature-slice=testing --task-allowed-capability-categories implement-feature-slice=implementation,testing --json

uv run python -m teamautobot.cli planner create --objective-file objectives/my-feature.md --json

uv run python -m teamautobot.cli planner promote-feedback --run-dir .teamautobot/planner-runs/ --review-task-id review-implementation --feedback-index 1 --rule-id implementation-evidence --title "Require implementation evidence" --json

uv run python -m teamautobot.cli planner validate-live-candidate --run-dir .teamautobot/planner-runs/ --target-dir . --json

uv run python -m teamautobot.cli planner harvest-live-candidate --run-dir .teamautobot/planner-runs/ --target-dir . --json

uv run python -m teamautobot.cli planner request-live-commit --run-dir .teamautobot/planner-runs/ --message "Ship the live workspace changes" --json

uv run python -m teamautobot.cli planner request-policy-override --run-dir .teamautobot/planner-runs/ --json

uv run python -m teamautobot.cli planner approve --run-dir .teamautobot/planner-runs/ --approval-id  --json

uv run python -m teamautobot.cli planner deny --run-dir .teamautobot/planner-runs/ --approval-id  --reason "Keep this guidance local for now" --json

```



Important current behavior:



- `planner full-team-demo` is still deterministic by default.

- With `--dynamic-replanning`, the planner can insert additional tasks such as acceptance and summary work after milestones.

- With `--builder-count N`, a run builds a per-run runtime roster with `builder-1` through `builder-N` instead of relying only on the default two builders. Extra builders are used for the optional research slice and later acceptance work when the plan shape allows it.

- With `--checkpoint-policy record-only`, the run records checkpoint metadata artifacts without creating git commits.

- `planner create` wraps the safe real-repo path: preflight the live provider, prepare a detached worktree, run the live full-team workflow with `azure_openai` by default, validate any live commit candidate, and return harvest/approval next actions without mutating the primary checkout.

- When `--objective-file` contains structured objective text, the run output includes parsed objective fields, uses `success_criteria` when present, and accepts an optional `## Task Capability Overrides` section with per-task `### ` subsections. That section should contain only those subsections plus HTML comments, and each task subsection must use only `**Additional Capability Categories**:` and/or `**Allowed Capability Categories**:` labels with capability list items; freeform prose or unknown labels are rejected by the parser.

- `--task-additional-capability-categories TASK_ID=CATEGORY[,CATEGORY...]` widens one task's default capability categories, while `--task-allowed-capability-categories TASK_ID=CATEGORY[,CATEGORY...]` narrows them. Repeat each flag for different task ids using capability values from `analysis`, `coordination`, `documentation`, `implementation`, `planning`, `review`, and `testing`.

- Objective-file capability overrides use the same category values and planner task ids as those CLI flags. When both surfaces specify the same task field, the CLI value wins.

- Unknown task ids supplied through objective-file or CLI capability overrides are rejected after the planner builds the current task graph, not during CLI argument parsing.

- Full-team demo JSON payloads include `runtime_agents`, `runtime_agent_ids`, `builder_count`, and `runtime_allocation`. Replay, follow, and dashboard views project the compact runtime roster via `runtime_agent_ids`, `persona_template_ids`, `builder_count`, and `runtime_allocation` so operators can distinguish concrete run-local agents from their persona templates.

- The `draft-execution-plan` task artifact now exposes `task_breakdown`, `runtime_agent_ids`, `persona_template_ids`, and `runtime_allocation`; downstream consumers that previously read `team_template_ids` should switch to those explicit runtime/persona fields.

- Full-team runs load repo-owned durable guidance from `.agent/standards/durable-guidance.json` by default (or `--durable-guidance-path`), capture promotable structured review feedback into run-scoped planner artifacts, and surface loaded rule provenance in run payloads, replay, follow, and dashboard views.

- Completed hybrid-live full-team runs in a git workspace capture a `live_commit_candidate` artifact that records the proposed commit message and the exact run-written paths; no git commit is created automatically.

- Static full-team runs that stop at a rejected review or failed acceptance gate now persist a resumable `policy_override_candidate`; continuing past that gate stays fail-closed and requires `planner request-policy-override`, `planner approve`, and then `planner resume`.

- `planner promote-feedback` now records a pending approval request for one captured review feedback item instead of mutating durable guidance immediately.

- `planner request-live-commit` turns the captured live commit candidate into a pending approval request, optionally overriding the proposed commit message.

- `planner request-policy-override` turns that persisted gate-failure candidate into a pending approval request so an operator can explicitly authorize continuing a blocked full-team run.

- `planner approve` resolves the pending request and either writes the durable-guidance update, creates the approved live git commit, or authorizes a matching policy-bypass resume; `planner deny` records a fail-closed outcome without changing repo guidance, creating a repo commit, or unblocking a gated run.

- Unedited placeholder text from the objective template is rejected before planning.



Checkpoint-aware JSON output includes fields such as `checkpoint_policy`, `checkpoint_count`, `checkpoint_paths`, and structured `checkpoint_steps`.



Hybrid-live full-team slice



```bash

uv run python -m teamautobot.cli planner full-team-demo --objective "Add a narrow live feature slice" --provider azure_openai --workspace-dir . --json

```



This is still a thin hybrid-live slice, not a fully live planner runtime. `implement-feature-slice`, `implement-acceptance-tests`, and live review tasks now run against the configured `--workspace-dir`: implementation, acceptance-test, and remediation tasks get bounded repo-aware search, status inspection, per-file diff inspection, targeted pytest validation, prerequisite-agent clarification via `request_clarification`, first-class human clarification via `request_human_clarification`, operator redirect context via `planner redirect`, and UTF-8 workspace writes; agent clarifications trigger a bounded target-agent sub-run that emits `agent.question` / `agent.answer` events and persists its own clarification artifact before the requesting task continues, while human clarifications emit `intervention.requested`, pause the planner run, and wait for an operator response. Review tasks get the same bounded inspection and validation tools in read-only mode plus structured review submission; and `run-acceptance-validation` runs a bounded real verification command that prefers explicit `acceptance_test_paths` from the live acceptance artifact, otherwise falls back to inferred pytest-style `test_*.py` / `*_test.py` writes, and finally falls back to `uv run pytest -q`. Planning, replay, follow, dashboard, and intervention stay on the planner-managed path.



When that live workspace is also a git repository and the run finishes successfully with run-written paths, TeamAutobot records a `live_commit_candidate` artifact for those paths. Use `planner validate-live-candidate` to verify content IDs, run the pre-harvest quality gate, and report which paths would be copied without mutating the target checkout. Use `planner harvest-live-candidate` after validation to copy the candidate files into another checkout for review, or keep creating an actual git commit approval-gated through `planner request-live-commit` followed by `planner approve`; the approval path re-runs the same candidate validation before recording a request and again before creating the git commit.



For live acceptance validation, `--workspace-dir` should generally point at the repository root so the bounded pytest command runs against the intended workspace.



Replay, compare, follow, dashboard, and intervene



```bash

uv run python -m teamautobot.cli planner replay --run-dir .teamautobot/planner-runs/

uv run python -m teamautobot.cli planner replay --run-dir .teamautobot/planner-runs/ --event-type replan.triggered --json

uv run python -m teamautobot.cli planner replay-compare --left-run-dir .teamautobot/planner-runs/ --right-run-dir .teamautobot/planner-runs/

uv run python -m teamautobot.cli planner replay-compare --left-run-dir .teamautobot/planner-runs/ --right-run-dir .teamautobot/planner-runs/ --json

uv run python -m teamautobot.cli planner follow --run-dir .teamautobot/planner-runs/

uv run python -m teamautobot.cli planner follow --run-dir .teamautobot/planner-runs/ --tail

uv run python -m teamautobot.cli planner follow --run-dir .teamautobot/planner-runs/ --tail --json

uv run python -m teamautobot.cli planner dashboard --run-dir .teamautobot/planner-runs/

uv run python -m teamautobot.cli planner dashboard --run-dir .teamautobot/planner-runs/ --json

uv run python -m teamautobot.cli planner intervene --run-dir .teamautobot/planner-runs/ --action pause

uv run python -m teamautobot.cli planner intervene --run-dir .teamautobot/planner-runs/ --action pause --json

uv run python -m teamautobot.cli planner respond --run-dir .teamautobot/planner-runs/ --answer "Use notes/live-implementation.md only" --json

uv run python -m teamautobot.cli planner redirect --run-dir .teamautobot/planner-runs/ --task-id implement-feature-slice --message "Use notes/live-implementation.md only" --json

uv run python -m teamautobot.cli planner resume --run-dir .teamautobot/planner-runs/ --json

uv run python -m teamautobot.cli planner promote-feedback --run-dir .teamautobot/planner-runs/ --review-task-id review-implementation --feedback-index 1 --rule-id implementation-evidence --title "Require implementation evidence" --json

uv run python -m teamautobot.cli planner request-live-commit --run-dir .teamautobot/planner-runs/ --message "Ship the live workspace changes" --json

uv run python -m teamautobot.cli planner request-policy-override --run-dir .teamautobot/planner-runs/ --json

uv run python -m teamautobot.cli planner approve --run-dir .teamautobot/planner-runs/ --approval-id  --json

uv run python -m teamautobot.cli planner deny --run-dir .teamautobot/planner-runs/ --approval-id  --reason "Keep this guidance local for now" --json

```



Current behavior summary:



- **Replay** reads recorded planner artifacts and `events.jsonl` and can emit either text or JSON views.

- **Replay compare** compares two full recorded runs; deltas are always computed as **right minus left**.

- **Follow** is the first live-observability surface. By default it emits one snapshot; with `--tail`, it polls until the run reaches `completed`, `error`, or `paused`.

- **Dashboard** builds on the same file-backed follow model, but presents an operator-oriented frame stream.

- Full-team run payloads, replay, follow, and dashboard surface the durable guidance session artifact path, loaded durable rule ids/rules, captured review feedback candidates, `live_commit_candidate`, `policy_override_candidate`, `pending_approval_request`, and `latest_approval_outcome` so later runs can replay the full operator decision path.

- Replay, follow, and dashboard also summarize persisted tool invocation records from `artifacts/tool-invocations/`, including status/adapter counts and recent calls.

- **Intervene --action pause** records a pause request that takes effect after the current task finishes; it does not interrupt in-flight work.

- **Respond** records the human answer for a paused full-team run that is waiting on `request_human_clarification`; it does not resume the run by itself.

- **Redirect** records a bounded operator redirect for a paused live `full-team-demo` work task (`implement-feature-slice`, `implement-acceptance-tests`, or live remediation work). It intentionally rejects runs that are not paused live full-team runs, non-work-task ids, and paused runs that already have a pending human clarification cycle.

- **Promote feedback** records a pending approval request to promote one captured review feedback item into durable repo guidance stored in `.agent/standards/durable-guidance.json` (or a caller-specified `--durable-guidance-path`).

- **Harvest live candidate** verifies the captured `live_commit_candidate` content IDs, runs a fail-closed quality gate for high-confidence generated-content problems, and copies only those recorded paths from the live workspace into a target git checkout, without creating a commit.

- **Request live commit** records a pending approval request for the captured `live_commit_candidate` and can override the proposed commit message for the eventual git commit.

- **Request policy override** records a pending approval request for a persisted `policy_override_candidate` when a static full-team run stopped at a rejected review or failed acceptance gate.

- **Approve** resolves the pending request and applies the durable-guidance change, live git commit, or policy-bypass resume authorization, depending on the approval kind; **Deny** resolves it without applying repo state.

- **Resume** continues a paused planner run in the same run directory when a persisted paused-run state artifact is available. It currently supports paused `demo`, `review-demo`, and `full-team-demo` runs; full-team runs with a pending human clarification must be answered with `planner respond` first, and full-team runs paused for a persisted gate-failure `policy_override_candidate` must be approved before resume will continue them.

- While a run is still `in_progress`, **Follow** and **Dashboard** surface a `pending_intervention_request` when a pause request has been written but not yet consumed by the runtime.

- While a full-team run is paused for human input, **Follow** and **Dashboard** surface a `pending_human_intervention_request` describing the outstanding clarification.

- While a paused or resumed live full-team run has a recorded redirect that has not yet been consumed, **Follow** and **Dashboard** surface `pending_operator_redirect`.

- When a completed live git-backed run has captured run-written paths, **Replay**, **Follow**, and **Dashboard** surface `live_commit_candidate` even before approval is requested.

- When a static full-team run stops at a rejected review or failed acceptance gate, **Replay**, **Follow**, and **Dashboard** surface `policy_override_candidate` until the authorized resume consumes it.

- While a run has a pending planner approval, **Replay**, **Follow**, and **Dashboard** surface `pending_approval_request`; after resolution they surface `latest_approval_outcome`.

- After a paused run is resumed, **Follow** and **Dashboard** treat the latest `system.resumed` event as returning the run to `in_progress` until the next terminal event arrives.



When hybrid-live task artifacts exist, `replay`, `replay-compare`, `follow`,

and `dashboard` also surface live metadata such as `live_mode`,

`workspace_dir`, `implementation_written_paths`,

`acceptance_test_written_paths`, and `acceptance_test_paths`.



Azure OpenAI configuration



Azure OpenAI uses the v1 Responses API via the standard `openai.OpenAI` client.



Configure:



- `AZURE_OPENAI_ENDPOINT`

- `AZURE_OPENAI_MODEL_DEPLOYMENT`

- `AZURE_OPENAI_AUTH_MODE` as `auto`, `api_key`, or `rbac`

- `AZURE_OPENAI_API_KEY` when using API-key auth



Useful commands:



```bash

uv run python -m teamautobot.cli azure-openai status --json

uv run python -m teamautobot.cli azure-openai complete --input "Say hello" --model gpt-4.1-nano --json

```



In `auto` mode, TeamAutobot prefers API-key auth when a key is present and otherwise falls back to Microsoft Entra ID / RBAC via `DefaultAzureCredential`.



Use `azure-openai status` to verify local configuration without making a live API call.



## Notes on recorded runs



- `planner replay`, `follow`, `dashboard`, and `intervene` all expect a real recorded planner run directory.

- `planner resume` expects a planner run directory that contains a persisted paused-run state artifact from an earlier paused planner run (`demo`, `review-demo`, or `full-team-demo`). Static full-team runs that stopped at a rejected review or failed acceptance gate now also persist that resume state, but resume stays blocked until a matching `planner request-policy-override` request is approved.

- `planner replay` reads existing run artifacts such as `events.jsonl`, `artifacts/planner/plan.json`, `artifacts/planner/execution-summary.json`, and `artifacts/tool-invocations/*.json` when present.

- If `execution-summary.json` is not present yet, `planner follow` can still succeed when the run directory already contains a valid plan snapshot and readable event log.



For deeper architecture, workflow, and repository guidance, see [`AGENTS.md`](AGENTS.md) and [`docs/teamautobot-design.md`](docs/teamautobot-design.md).