| 1 | # Agent Forge — skill (agents) |
| 2 | |
| 3 | You operate against **Agent Forge**: git repos, issues, merge requests, code anchors — **from chat**, not a web maze. |
| 4 | |
| 5 | ## Base URL |
| 6 | |
| 7 | - Local: `http://127.0.0.1:8770` |
| 8 | - Deployed: set by ops (`FORGE_PUBLIC_BASE_URL`) |
| 9 | |
| 10 | MCP tools cover full issue/MR lifecycle + Forge Lens anchors. |
| 11 | |
| 12 | ## MCP architecture (server-driven, ADR-0014 B) |
| 13 | |
| 14 | The MCP process is a **thin bridge**: |
| 15 | |
| 16 | 1. `GET /api/v1/capabilities` → `tools[]` with name, description, `inputSchema` |
| 17 | 2. `POST /api/v1/mcp/invoke` → `{ tool, arguments }` — all execution on forge host |
| 18 | |
| 19 | **Always call `get_forge_capabilities` first** on an unknown host (via invoke or REST). |
| 20 | |
| 21 | - Agents write via **MCP → `/api/v1`** — not via `/view`. |
| 22 | - `issueUrl` / `mrUrl` in API responses may point at `/view/...`; on `minimal` treat them as human-only links. |
| 23 | - Future plugins may add tools; **`capabilities.tools`** is authoritative (MCP ListTools mirrors it). |
| 24 | |
| 25 | ## Plugin bundles |
| 26 | |
| 27 | | Bundle | Agent impact | |
| 28 | |--------|----------------| |
| 29 | | **standard** | Full kernel invoke tools + `human_view` (`/view` for humans); `get_human_view_url` | |
| 30 | | **minimal** | Kernel invoke tools only; no `/view` or `get_human_view_url` | |
| 31 | |
| 32 | ## Workflow |
| 33 | |
| 34 | 1. **Discover** — `get_forge_capabilities` (optional on known standard deploys). |
| 35 | 2. **Repo** — `create_repo` with slug (`a-z`, `0-9`, hyphens). For org repos pass `org` (e.g. `ai-guiders`) and optional `group` path; `name` is repo slug only, not `org/repo`. Response includes `cloneUrl`. |
| 36 | 3. **Issue** — `create_issue` with optional `anchors[]` when work maps to code lines. |
| 37 | 4. **After edits** — `link_issue_anchors` or `get_forge_lens` to see cross-links. |
| 38 | 5. **MR** — `create_merge_request` after branch work; check `get_ci_status` before merge. |
| 39 | 6. **Thread** — `add_issue_comment` for investigation notes; `update_issue` to close. |
| 40 | 7. **Git push** — clone/push via SSH git transport on forge host (ADR-0004). Forge stores metadata. |
| 41 | |
| 42 | ## MCP tools (summary) |
| 43 | |
| 44 | | Area | Tools | |
| 45 | |------|--------| |
| 46 | | Host | `get_forge_capabilities` | |
| 47 | | Repos | `list_repos`, `create_repo`, `get_repo` | |
| 48 | | Issues | `create_issue`, `get_issue`, `list_issues`, `search_issues`, `update_issue`, `add_issue_comment` | |
| 49 | | Lens | `link_issue_anchors`, `get_forge_lens` | |
| 50 | | MR | `create_merge_request`, `get_merge_request`, `list_merge_requests`, `get_ci_status`, `get_merge_request_diff`, `accept_merge_request`, `reject_merge_request`, `add_merge_request_comment`, `forge.handoff.relay` | |
| 51 | | Provenance | `record_commit_provenance` | |
| 52 | |
| 53 | Exact list on this host: `get_forge_capabilities` → `mcpTools`. |
| 54 | |
| 55 | ## Principles |
| 56 | |
| 57 | - **Chat-first** — no Jira². |
| 58 | - **Anchors** — tie issues to `file:line` (CIDE-compatible); use `issueUrl` for humans when `human_view` feature is present. |
| 59 | - **CI** — external runner posts to `/api/v1/ci/callback`; agent reads `get_ci_status`. |
| 60 | |
| 61 | ## Non-goals (v0.2) |
| 62 | |
| 63 | - Full GitLab parity |
| 64 | - Built-in CI runner |
| 65 | - PAT settings UI (auth: SSH + `forge auth login` later, ADR-0006) |
| 66 | |
| 67 | ## Related |
| 68 | |
| 69 | - [FORGE-ADR-0014](../design/FORGE-ADR-0014-microkernel-and-standard-bundle.md) — plugins + bundles |
| 70 | - [FORGE-ADR-0002](../design/FORGE-ADR-0002-mcp-first-web-view-only.md) — MCP-first, view = Human-layer |
| 71 | |