Handbook

Forge Campaign

A Forge Campaign is a multi-repo, branch-aware automation effort governed under a single ForgeRun (frun_*). The campaign is described by a manifest and executed by one or more Forge Agents (AgentRuns), with human review…

Updated

Definition

A Forge Campaign is a multi-repo, branch-aware automation effort governed under a single ForgeRun (frun_*). The campaign is described by a manifest and executed by one or more Forge Agents (AgentRuns), with human review and decision in Lenses.

What a Forge Campaign is not

Term Distinction
Marketing campaign GTM/channel activity — not a Forge Campaign
Git charge/* branch Charge is a daily Spark view only — never a branch (Forge branching)
Fleet job alone A job is execution; the campaign is the full run including intent, evidence, and decision
Ungoverned agent loop Must attach to frun_* and produce reviewable evidence
DecisionPack DAG Campaign uses manifest phases, not LCDL graph nodes — see Governed workflows and rules

ForgeRun-backed (day one)

Every campaign opens or extends one ForgeRun:

ForgeRun campaign lifecycle

How a governed multi-repo campaign opens a ForgeRun, executes agents, and returns reviewable evidence to Lenses.

  1. 1. Open ForgeRun (frun_*) — intent, workspace, governance modeOpens the run spine that owns campaign intent and governance mode.
  2. 2. Attach campaign manifest — campaign.yaml under .forge/runs/<frun_id>/Binds the campaign manifest to the run store for this frun.
  3. 3. Record AgentRuns — campaign_orchestrator, fleet_ux_worker, …Registers AgentRun workcells that will execute campaign phases.
  4. 4. Fleet execution — optional docker_argv + workspace uploadSubmits bounded container jobs with the packed workspace when required.
  5. 5. EvidencePacket — audit results, quality gate, artifactsCollects audit output, gate results, and artifacts into one evidence bundle.
  6. 6. Lenses review — human approves, rejects, or defersHuman decision closes or defers the campaign in Lenses.

Lenses remains the system of record for run state. See Product boundaries.

Campaign manifest (informal v0)

Authoritative path (pick one convention per workspace):

  • Repo template: forge/campaigns/<campaign-id>.yaml
  • Run store: .forge/runs/<frun_id>/campaign.yaml (copy or symlink from template when the run starts)

Illustrative fields (schema forge.campaign.v1 is post-research):

schema_version: 1
campaign_id: ux-20260520-ffw-nav
forge_run_id: frun_ux_20260520_ffw_nav   # set when run opens
trunk: main

repos:
  - path: forgesdlc-kitchensink
    role: upstream
    branch: feature/ux-20260520-ffw-nav-ks
  - path: forge-fleet-website
    role: consumer
    branch: feature/ux-20260520-ffw-nav-ffw
    depends_on: [forgesdlc-kitchensink]
    submodules:
      kitchensink: { track_branch: feature/ux-20260520-ffw-nav-ks }

fleet:
  requirement_ids: [ux_remediation_worker]
  workspace_profile: large_workspace

worker_steps:
  - id: audit
    skip_cursor_agent: true
  - id: remediate
    requires_secret: [CURSOR_API_KEY]

integration:
  pr_stack_order: [forgesdlc-kitchensink, forge-fleet-website]
  auto_merge: false
  wait_for_ci: true

# Vision (informal): autonomy level informs assay expectations — not in schema v1 yet
governance:
  target_autonomy_level: L2
  acceptance_criteria_ref: forge/campaigns/ac/example.yaml

Commit trailers: Forge-Campaign: <campaign-id> on campaign-related commits.

Branching policy: Forge SDLC branching — one commit per repo; submodule bumps as chore(kitchensink): … only.

Lifecycle states (orchestrator)

The campaign orchestrator workcell (campaign_orchestrator) tracks coarse state (local state.json or Lenses projection):

State Meaning
draft Manifest written; ForgeRun not yet opened
branched Topic branches exist on origin
submitted Fleet job created
running Job non-terminal
collected worker_result parsed
integrating Applying diffs, commits, pushes
pr_open Stacked PRs created
verifying Build, re-audit, CI
done / failed Terminal; decision updated in ForgeRun

Agent roles in a campaign

AgentRun workcell Where it runs Role
campaign_orchestrator Laptop or CI Branch, pack tarball, POST/PUT Fleet, watch, integrate, gh pr
fleet_ux_worker Fleet container Scorer, auditor, remediation sub-agents; workspace_worker_progress

Fleet does not open pull requests or own git credentials by default. The orchestrator workcell owns git integration policy when explicitly enabled in forge/branching.yml.

Example flow (UX remediation — reference)

UX remediation campaign flow

Reference path from operator intent through Fleet remediation, git integration, and a Lenses decision.

  1. Operator → open frun_* + campaign.yamlOperator opens the ForgeRun and attaches the campaign manifest.
  2. campaign_orchestrator: create feature/* branches (KS then consumer)Orchestrator creates topic branches upstream first, then the consumer.
  3. pack workspace → POST /v1/jobs + PUT workspacePacks the workspace tarball and submits the Fleet job with upload.
  4. watch GET /v1/jobs/{id}Polls Fleet until the job reaches a terminal state.
  5. fleet_ux_worker: remediation loop → worker_resultContainer worker runs scorer, auditor, and remediation sub-agents.
  6. campaign_orchestrator: integrate → PR stack → verifyApplies diffs, opens stacked PRs, and runs build and re-audit verification.
  7. EvidencePacket + Lenses decisionPublishes evidence and records human approve, reject, or defer.

Boundary table

Concern Owner
Run spine, approvals, evidence UI Lenses
Container jobs, workspace extract Fleet
Campaign manifest, AgentRun contracts Forge Platform
Branch/PR policy Blueprints + repo forge/branching.yml
Building blocks (e.g. kitchensink) forgesdlc-kitchensink first, consumers bump submodule

Anti-patterns

  • Hermes or Fleet owning canonical campaign state instead of Lenses + ForgeRun.
  • Auto-merge handbook or product sites without human review.
  • One git commit spanning multiple repos.
  • Naming Git branches campaign/* (use feature/<campaign-slug>-<repo-abbrev>).

MVP vs later

Phase Deliverable
M0 Terminology, manifest sketch, samples, ADR
M1 Orchestrator CLI + audit-only Fleet worker
M2 Headless agent in container or hybrid
M3 Multi-repo integrate + stacked PRs
M4 CI gate before campaign done