Use the supervised backend
Forge is served at http://127.0.0.1:8787/. On the primary Mac, launchd owns com.zynga.gotm.unity-pipeline-dashboard with RunAtLoad and KeepAlive. Do not start a second backend.py in another terminal.
How to · Operator handbook
Run Forge safely.
Teach Fabric deliberately.
The practical guide for a workstation installation: bring Forge up, verify dependencies, run one or many tickets, inspect evidence, make a useful human decision, publish the exact approved artifacts, and recover without corrupting runtime state.
1
Basic setup
Bring up a workstation cleanly
Verify the page and service
Open the URL and confirm the dashboard renders. If it does not, inspect dashboard/dashboard.log and the launchd service before changing code. “Address already in use” means another backend already owns port 8787.
Check Connections
Confirm Jira, Perforce, Git, Fabric AI and the native tool required by the chosen agent. Green is evidence from the latest probe, not a permanent guarantee. A degraded dependency should block before mutation.
Pick the correct workspace and agent
Workspaces isolate agents, runs and knowledge. Select Tech Art, Design, QA, Product, Production or Dev first; then choose a commissioned agent whose routing and runtime match the ticket.
Safe restart.
Use launchctl kickstart -k gui/$(id -u)/com.zynga.gotm.unity-pipeline-dashboard, then reload the browser. A hard refresh is enough for HTML/JavaScript changes because the backend serves the repository files directly.
Installing without the source repository?
Use the separate, digest-verified Local server and browser-client packages. Runtime settings are parsed and validated before startup, and no remote worker is required. Open Local packages & setup →
2
Connector checklist
Give agents real sources and real tools
Jira + Perforce + Git
Use personal credentials and the correct P4 client/root. Forge reads the ticket and exact depot paths, syncs sources, and binds publication to the files produced by that run. Git publication uses a sealed plan, not whatever happens to be dirty.
Photoshop + Unity
Open the native application when its agent requires a live bridge. Unity project and editor version must match the configured project. Native tools are execution dependencies; “installed” does not mean “ready.”
Fabric AI — local + cloud, per lane
Settings → Fabric AI routes a capability lane, never a single provider. Seven lanes — fast · reason · code · review · vision · plan · embed — are routed under a min_cap floor. Private/low-latency lanes (fast, vision, embed) stay on the local Ollama pool; only reason and code burst to the cloud specialist (Anthropic Claude) when configured. Set the cloud key only in the protected password field, then Save & test; a monthly USD budget bounds cloud spend and Fabric degrades to local when the budget is exhausted or the provider is unhealthy, so runs are never blocked. Cloud models run remotely and are not downloaded; grounded task context may leave the machine, so cloud use is explicit. Model confidence remains advisory and deterministic validators remain authoritative.
Optional downstream systems
Sheets, Content Bundles, artifact stores and deployment services are separate capabilities. They are required only when the compiled agent selects them. Every writer uses stable identity or an idempotency key so a replay does not duplicate a row, object or delivery.
Slack
Install the Forge Slack app, grant only required bot scopes, then store the xoxb-… bot token in Settings → Connectors. Use a channel ID for channels or an organization email for direct messages. Never paste the client secret into Forge.
Datadog + Bugsnag
Datadog supplies bounded monitor, fleet and impact facts; Bugsnag supplies application errors, releases and affected users. Incident & Reliability correlates strong matches, coordinates response, routes governed fixes and verifies recovery without copying raw provider data.
CredentialsStore secrets only in the connector credential store or protected environment. Never put tokens in agent JSON, RAG, Git, screenshots, Jira comments, logs or wiki pages. Rotate any credential accidentally exposed.
3
How to run
One ticket or a batch
Begin with dry run
Select tickets, confirm the routed agent, and leave finalization off. Each selected ticket becomes an independent job with its own ticket, target paths, artifact manifest, validation evidence and terminal result.
Watch Processes and stages
The Processes flyout lists running and queued work. Selecting a process returns to its workspace, agent and run; Stop requests cooperative cancellation. Stage nodes turn active, pass, fail or skipped from authoritative events.
Inspect visual analysis
For image-producing agents, the current asset is marked Analyzing. Vision compares dimensions, size and appearance with relevant nearby/shipped peers discovered from the folder hierarchy. Every asset receives a rating and an explanation.
Make the human decision
Dry runs also reach human sign-off. Approve/accept teaches positive evidence; deny or request changes teaches a correction; Ignore is neutral and should be used for broken or irrelevant evidence that must not train Fabric.
Continue to publication
After approving a dry run, choose Continue/Prepare publication. Forge prepares a separate sealed approval for the exact artifact manifest and advances source-control publication, destination verification, optional downstream delivery and ticket mutations as individually evidenced stages.
Batch isolation.
One failed job must not poison the next job. Forge tracks produced files per job, and publication selects only the approved job’s manifest. A dirty path owned by another failed job is reported and excluded; it is never silently committed with the successful ticket.
Destination evidence is adapter-defined.
Do not require a direct API probe when a project’s governed adapter defines another authoritative, versioned handoff. Conversely, do not treat a local mirror or an unpushed commit as delivered unless that adapter’s immutable remote evidence is present.
Forge Pet is a status companion, not a scheduler.
Its message follows the highest-priority authoritative activity: active building or validation takes precedence over approval reminders, and the message names the agent, ticket or current asset when known. Approval notifications rotate periodically instead of trapping the Pet in one waiting loop. Use Processes and the run journal for control and audit.
4
Approvals & learning
Feedback that makes Fabric better
Approve / Accept and teach
Use when the exact result is usable. Rate output quality and agent helpfulness, select what went right, rate individual validator findings, and add a concise reason. Positive visual feedback is keyed to the reviewed asset evidence and can be reused for an unchanged file.
Deny / Request changes
Use when the result is wrong or incomplete. Identify wrong result, missed requirement, wrong context, weak visual quality, unsafe action, slowness, explanation quality or false confidence. State the desired correction.
Ignore review
Use for corrupted assets, obsolete test runs, duplicate cards or evidence that should not affect learning. Ignore resolves that exact approval as neutral and records no positive or negative training signal.
Confidence
Confidence explains evidence quality and past outcomes. It can improve from matching approved artifacts, but it cannot override missing source coverage, failed validators, an unsupported executor, unsafe change or missing human authority.
What Fabric learns.
Fabric retains scoped facts, success/failure outcomes, human corrections, visual approvals, validator calibration and agent track records. Learning changes later retrieval and confidence; it never edits production directly or turns approval into a bypass.
5
Agent authors
Create, certify and mature an agent
Draft from evidence
Start blank, clone a proven agent, or use Agent Fabricator. Set the workspace vertical, runtime, routing, sources, path rules, stage configuration, artifact contract and approval policy. A fabricated agent is a reviewable candidate—not a published agent.
Separate routing intent
Use representative keywords, issue types and path rules that distinguish this agent from similar agents. Keep “Eligible for ticket auto-selection” off until a routing test set demonstrates reliable separation.
Lint, preview and certify
Check graph connectivity, JSON round-trip, required configuration, executor support, source coverage and runtime compatibility. Preview proposed reads/writes; simulate and certify through the Harness.
Publish the definition
Moving a node changes presentation only and must not enable Publish. Publish becomes meaningful only when semantic agent values, stages, routing, policy or configuration differ from the live version.
Mature carefully
Run representative dry tickets, collect operator feedback, inspect failures and false confidence, then expand auto-routing or optional sign-off only when measured evidence supports it.
6
Engineering & PR review
Fix bugs without weakening the gates
Governed Engineering
Bugsnag/SmartBear evidence is normalized into Observe → Ground → Plan → Patch → Independent Review → deterministic validation → approval → sealed draft PR → release verification → learning. Missing reproduction or patch contracts block; independent review fails closed.
Focused test controls
Configure DEV_FOCUSED_TEST_CMD, DEV_FOCUSED_TEST_EXPECT and a bounded timeout before patch generation. The reproduction must fail before the patch and pass after it; otherwise the change cannot be called a fix.
Permanent run log
Search and copy the Engineering log to understand planning, model failover, patch controls and validation. A blocked run is a governed outcome—not permission to bypass the missing control.
Pull Request Review
The workspace PR view lists open PRs, CI/review state, change size, files and unified diffs. Fabric’s domain reviewer recommends ready, wait or needs-fix. Review/approval actions remain explicit and policy-gated; no CI evidence is never inferred as a pass.
7
Recovery
When something stops or looks stuck
| Symptom | Safe response |
|---|---|
| Dashboard unavailable | Check the launchd service, port 8787 and dashboard/dashboard.log; restart the supervised service once. Do not launch duplicates. |
| Run appears active after completion | Refresh Processes and inspect the durable run/job state. Use the UI Stop control only if it is still authoritative; startup recovery marks orphaned work interrupted. |
| Visual validation is slow | Read the current asset counter. Vision is per asset and may be model-bound; unchanged, previously approved content can use the evidence cache. Do not repeatedly click Run. |
| Publication reports dirty checkout | Inspect which job owns each path. Publish the approved manifest only, or explicitly commit/stash/discard unrelated work after review. Never use a broad cleanup command. |
| Connector unavailable | Re-probe it, verify VPN/credential/native app, and retry only the idempotent step. Never replace unavailable source data with a guess. |
| Approval keeps returning | Resolve the exact approval ID. The durable worker resumes that same job at its checkpoint after revalidating the plan and current evidence. Ignore is neutral and idempotent. A new card must represent a distinct operation, changed plan or new publication effect. |
| Destination cannot be verified | Inspect the selected delivery adapter and its required evidence. Confirm the immutable remote reference, artifact digest or deployment receipt it declares. Do not substitute a different connector or mark a local file as published. |
8
Operational guardrails
What not to do
Do not kill an agent process abruptly
Use Processes → Stop. A hard kill can leave Photoshop, Unity, Git, Perforce, Sheets or Jira partially changed while the journal still shows an open attempt. Force-kill only after cooperative cancellation fails and you have captured the run ID and reconciled external state.
Do not run duplicate backends
One supervised backend owns port 8787. Multiple servers can race on job state, show alternating authorization results and make the UI look inconsistent.
Do not repeatedly click Run, Retry or Publish
Wait for the visible process and terminal result. Repeated clicks create distinct attempts, duplicate expensive validation and complicate approval evidence.
Do not approve by confidence alone
Open the evidence, validation findings, file list and diff. A high score is not proof; a hard failure remains blocking.
Do not teach Fabric with broken evidence
Ignore corrupted, placeholder or irrelevant artifacts. Approving them as “good” makes later similarity and confidence less useful.
Do not delete or reset shared work blindly
Never use destructive Git cleanup, discard another ticket’s assets, guess depot paths, or submit Perforce without explicit authorization. Each job owns only its recorded manifest.
Do not put secrets in knowledge
RAG, skills, logs and screenshots are readable evidence stores. Use the credential store and rotate anything exposed.
Do not disable governance to make a demo pass
Missing source coverage, reproduction, contracts, validators, CI or approval should remain visible. Fix the precondition; never relabel skipped work as passed.
Do not encode one project’s delivery rule globally
Keep project repositories, deployment handoffs, ticket conventions and optional connectors in workspace-scoped skills and typed adapters. Shared Forge policy defines the evidence contract and safety boundary, not a project-specific destination.