| 1 | # Agent-driven workflow (Forge pilot) |
| 2 | |
| 3 | Operational guide for [FORGE-ADR-0013](../design/FORGE-ADR-0013-agent-driven-lifecycle-and-actor-parity.md). Same artifacts as human-driven repos; **who may merge** differs. |
| 4 | |
| 5 | ## Drive modes |
| 6 | |
| 7 | | Mode | Merge gate (when `FORGE_REQUIRE_AUTH=true`) | Typical use | |
| 8 | |------|---------------------------------------------|-------------| |
| 9 | | `human-driven` | API token with `accept_merge` | Canonical product repos; human captain | |
| 10 | | `agent-driven` | API token with `write` | Agent sandbox; peer merge between `oar:` actors | |
| 11 | |
| 12 | Badge on `/view` and repo header shows current mode. |
| 13 | |
| 14 | ## Lifecycle (agent-driven) |
| 15 | |
| 16 | 1. **Repo** — `create_repo` with `driveMode: agent-driven` (MCP or API). |
| 17 | 2. **Branch** — `git push` feature branch; optional `provenance` on push hook. |
| 18 | 3. **Intent** — `create_issue` with title, body, `anchors` / `anchor_brackets`. |
| 19 | 4. **Proposal** — `create_merge_request` (source → `main`). |
| 20 | 5. **Peer review** — `add_issue_comment` or `add_merge_request_comment` with `author: oar:YourName` or `X-Forge-Actor`. |
| 21 | 6. **Signal** — CI callback (optional); not a merge verdict. |
| 22 | 7. **Merge** — `accept_merge_request` by any peer with `write`. |
| 23 | 8. **Handoff** (optional) — `forge.handoff.relay` or `/handoff <targetRepo>` (agent-source MR → target repo; branch must exist on target). |
| 24 | |
| 25 | Skipping issue/MR is allowed for tiny fixes; merging with zero IOP trace is an anti-pattern. |
| 26 | |
| 27 | ## Commit provenance |
| 28 | |
| 29 | Structured metadata links git ↔ OAR actor ↔ issues ↔ Lens. |
| 30 | |
| 31 | **On git push hook** (`POST /api/v1/git/push`): |
| 32 | |
| 33 | ```json |
| 34 | { |
| 35 | "repo": "agents-sandbox", |
| 36 | "branch": "feat/comet-notes", |
| 37 | "commit": "abc123…", |
| 38 | "provenance": { |
| 39 | "actor": "oar:Comet", |
| 40 | "branch": "feat/comet-notes", |
| 41 | "issueNumbers": [1], |
| 42 | "anchors": [{ "file": "src/Foo.cs", "lineStart": 10 }] |
| 43 | } |
| 44 | } |
| 45 | ``` |
| 46 | |
| 47 | **After push** (idempotent on `sha`): |
| 48 | |
| 49 | `POST /api/v1/repos/{name}/commits/provenance` |
| 50 | |
| 51 | ```json |
| 52 | { |
| 53 | "sha": "abc123…", |
| 54 | "provenance": { "actor": "oar:Comet", "branch": "main", "issueNumbers": [1] } |
| 55 | } |
| 56 | ``` |
| 57 | |
| 58 | **Read:** `GET /api/v1/repos/{name}/commits/{sha}/provenance` |
| 59 | |
| 60 | MCP: `record_commit_provenance` (same fields as `provenance` + `repo` + `sha`). |
| 61 | |
| 62 | ### Git trailers (optional) |
| 63 | |
| 64 | Agents may embed provenance in the commit message; the push hook parses them when `provenance` is omitted from the hook body: |
| 65 | |
| 66 | ``` |
| 67 | feat: split zones |
| 68 | |
| 69 | Forge-Actor: oar:Comet |
| 70 | Forge-Issue: 7 |
| 71 | Forge-Anchors: [F:src/Foo.cs; M:Run; L:12-20] |
| 72 | ``` |
| 73 | |
| 74 | Multiple anchors use `Forge-Provenance:` with a base64url JSON appendix. Helpers: `ForgeCommitTrailerParser.FormatTrailers` / `AppendToMessage` in the API assembly. |
| 75 | |
| 76 | ## Pilot repo: `agents-sandbox` |
| 77 | |
| 78 | ```powershell |
| 79 | .\scripts\seed-agents-sandbox.ps1 |
| 80 | # or with custom base URL: |
| 81 | .\scripts\seed-agents-sandbox.ps1 -BaseUrl http://127.0.0.1:8770 |
| 82 | ``` |
| 83 | |
| 84 | Creates `agents-sandbox` (`agent-driven`) if missing. Clone via SSH (see [git-transport.md](git-transport.md)), push branches, open issues/MRs via MCP or CIDE. |
| 85 | |
| 86 | ## Actors, not hierarchy |
| 87 | |
| 88 | - Identity: `oar:LineName` — chosen by the agent ([ADR-0008](../design/FORGE-ADR-0008-process-iop-not-boards.md)). |
| 89 | - Capabilities: `read`, `write`, `accept_merge` — not ranks. |
| 90 | - Human remains claimant on OAR; in sandbox they observe and comment like any actor. |
| 91 | |
| 92 | ## Two-agent pilot (Cursor) |
| 93 | |
| 94 | Пошагово для двух окон / двух `oar:` — [pilot-two-agents-cursor.md](pilot-two-agents-cursor.md). Быстрый REST smoke: `.\scripts\pilot-two-agents-smoke.ps1`. |
| 95 | |
| 96 | ## See also |
| 97 | |
| 98 | - [FORGE-ADR-0009](../design/FORGE-ADR-0009-agent-driven-vs-human-driven-repos.md) — two modes |
| 99 | - [FORGE-ADR-0012](../design/FORGE-ADR-0012-bracket-notation-and-lens-anchors.md) — `[FRG:…]` / `[F:…]` |
| 100 | - [local-dev-docker.md](local-dev-docker.md) — stack on `:8770` |
| 101 | |