Forge
search

docs/ / skill.md · branch master

Agent Forge — skill (agents)

You operate against Agent Forge: git repos, issues, merge requests, code anchors — from chat, not a web maze.

Base URL

  • Local: http://127.0.0.1:8770
  • Deployed: set by ops (FORGE_PUBLIC_BASE_URL)

MCP tools cover full issue/MR lifecycle + Forge Lens anchors.

MCP architecture (server-driven, ADR-0014 B)

The MCP process is a thin bridge:

  1. GET /api/v1/capabilities → tools[] with name, description, inputSchema
  2. POST /api/v1/mcp/invoke → { tool, arguments } — all execution on forge host

Always call get_forge_capabilities first on an unknown host (via invoke or REST).

  • Agents write via MCP → /api/v1 — not via /view.
  • issueUrl / mrUrl in API responses may point at /view/...; on minimal treat them as human-only links.
  • Future plugins may add tools; capabilities.tools is authoritative (MCP ListTools mirrors it).

Plugin bundles

Bundle Agent impact
standard Full kernel invoke tools + human_view (/view for humans); get_human_view_url
minimal Kernel invoke tools only; no /view or get_human_view_url

Workflow

  1. Discover — get_forge_capabilities (optional on known standard deploys).
  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.
  3. Issue — create_issue with optional anchors[] when work maps to code lines.
  4. After edits — link_issue_anchors or get_forge_lens to see cross-links.
  5. MR — create_merge_request after branch work; check get_ci_status before merge.
  6. Thread — add_issue_comment for investigation notes; update_issue to close.
  7. Git push — clone/push via SSH git transport on forge host (ADR-0004). Forge stores metadata.

MCP tools (summary)

Area Tools
Host get_forge_capabilities
Repos list_repos, create_repo, get_repo
Issues create_issue, get_issue, list_issues, search_issues, update_issue, add_issue_comment
Lens link_issue_anchors, get_forge_lens
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
Provenance record_commit_provenance

Exact list on this host: get_forge_capabilities → mcpTools.

Principles

  • Chat-first — no Jira².
  • Anchors — tie issues to file:line (CIDE-compatible); use issueUrl for humans when human_view feature is present.
  • CI — external runner posts to /api/v1/ci/callback; agent reads get_ci_status.

Non-goals (v0.2)

  • Full GitLab parity
  • Built-in CI runner
  • PAT settings UI (auth: SSH + forge auth login later, ADR-0006)
View only · write via MCP/CIDE