# Local Claude/Codex Issue Flow

This example shows how to use Anteroom workflows as a durable wrapper around
local GitHub and git operations while running Claude and Codex through native
workflow agent steps.

Use this when your flow is:

- Claude handles planning, implementation, and PR fixes
- Codex handles senior review
- GitHub issue comments and PR discussion are the source of truth
- GitHub, git, checks, and PR bookkeeping still happen through local CLI tools

## What It Runs

The example workflow lives at:

- `examples/workflows/local_claude_codex_issue_delivery.yaml`

It uses the helper script at:

- `scripts/workflows/local_cli_issue_flow.py`

The flow is:

1. Validate the issue is still open
2. Create or recover a dedicated worktree for the issue
3. Run a plan/review loop with native Claude and Codex agent steps
4. Block unless the issue receives the `senior-approved` label
5. Have Claude implement the issue in the prepared worktree
6. Run repo checks, commit, push, and open a draft PR
7. Run a PR review/fix loop with native Codex and Claude agent steps
8. Fail unless the PR ends with the `senior-approved` label

The helper is now responsible only for worktree and GitHub bookkeeping
(`prepare`, `checks`, `sync`, `open-pr`, `assert-pr-approved`). The agent work
happens in native workflow runner steps, so transcript streaming, approvals, and
pause/resume go through the workflow engine instead of a nested subprocess.

## Prerequisites

The workflow requires these tools:

| Tool | Purpose | Verify |
|------|---------|--------|
| `gh` | GitHub issue/PR management | `gh auth status` |
| `git` | Branch, worktree, and commit operations | `git --version` |

For Claude/Codex runner steps, use your normal Anteroom AI configuration.
Those steps are not launched through local `claude` / `codex` binaries.

Git also needs a configured author identity for automated commits:

```bash
git config user.name
git config user.email
```

## Running It

Use the workflow by path:

```bash
aroom workflow run ./examples/workflows/local_claude_codex_issue_delivery.yaml --issue 123
```

Inspect the resolved steps first:

```bash
aroom workflow run ./examples/workflows/local_claude_codex_issue_delivery.yaml --issue 123 --dry-run
```

If a review loop stops before approval, inspect the run and resume it after
adjustments:

```bash
aroom workflow status <run_id>
aroom workflow history <run_id>
aroom workflow resume <run_id> --definition ./examples/workflows/local_claude_codex_issue_delivery.yaml
```

## Checks

By default the helper uses:

```bash
ruff check src/ tests/ && python -m pytest tests/unit/ -x -q --tb=short
```

You can change that by editing the `ANTEROOM_LOCAL_CHECKS` environment values in
the workflow YAML.

## Notes

- The helper stores per-issue workflow state under the repository git-dir's
  `anteroom-workflows/` directory, which works for linked worktrees too.
- The issue body gets an `Implementation Plan` section managed between
  `<!-- anteroom:plan:start -->` and `<!-- anteroom:plan:end -->`.
- Plan and PR gating both use the `senior-approved` label.
- If the same GitHub user both authors the PR and runs the review, GitHub may
  not count that as an independent approval. The workflow still uses the label
  gate consistently.
