Forge Platform

Handbook

ADR-0007: Forge Campaign is always backed by a ForgeRun

Accepted (documentation phase, 2026-05-20). Implementation and formal forge.campaign.v1 schema follow external research.

Status

Accepted (documentation phase, 2026-05-20). Implementation and formal forge.campaign.v1 schema follow external research.

Context

Operators need multi-repo automation (for example UX remediation via Fleet) with visible governance, evidence, and human decision. Informal orchestrator scripts risk parallel state outside Lenses.

Forge Platform already defines ForgeRun as the lifecycle container and AgentRun for bounded agent sessions.

Decision

  1. A Forge Campaign is always represented by exactly one ForgeRun (frun_*), stored under .forge/runs/<frun_id>/ and reviewable in Lenses.
  2. Campaign parameters live in a manifest (campaign.yaml), referenced from the run directory or forge/campaigns/<id>.yaml before import.
  3. Forge Agents participating in the campaign are AgentRuns with explicit workcell ids (campaign_orchestrator, fleet_ux_worker, …).
  4. Fleet provides execution only; git branch, PR, and integrate steps are owned by the campaign_orchestrator workcell unless repo policy forbids automation.

Consequences

  • Positive: Single spine for intent → evidence; no duplicate “campaign database” in Fleet v1.
  • Positive: Self-Host and future Lenses UI can reuse ForgeRun list/detail.
  • Negative: Opening a campaign requires ForgeRun discipline even for small jobs.
  • Follow-up: Define forge.campaign.v1 JSON Schema after integrate/PR research; add samples to scripts/check_foundation.py when stable.

Alternatives considered

Alternative Why not (for now)
Manifest-only, no ForgeRun until M2 Rejected — Lenses visibility required from day one
Fleet DB table for campaigns Rejected — orchestration stays client-side like certificator bank jobs
campaign/* Git branches Rejected — conflicts with Charge branch rule; use feature/*

References

  • Handbook: docs/forge-campaign.md, docs/forge-agent.md
  • schemas/forge_run.v1.schema.json, schemas/agent_run.v1.schema.json