FORGE Automation

FORGE (Forge Orchestrates Resolved GitHub Execution) is a strategic planner workflow that transforms GitHub epics into structured tasks, assembles them into prompts, and delegates execution via Claude API, SSH, or manual review. It powers the SO1 automation council’s ability to resolve large, multi-block engineering challenges.

Quick Identity

Field	Value
Workflow ID	`mSJmBzpIcuCKz1WT`
Webhook	`/webhook/forge-resolve-next-ticket`
n8n Instance	`https://hab.so1.io`
Execution Modes	Manual, API (Claude), TOMMY (SSH + Claude)
Timeout	120s (manual/api), 1800s (TOMMY)
Phases	Phase 4–7 + ZOID Phase A (Discord telemetry)

How FORGE Works

1. Receive Webhook

You trigger FORGE from the Rover console by selecting:

GitHub org (e.g., traceo-ai)
Repository (e.g., traceo-mcp-server)
Epic issue number (e.g., 22)
Execution mode (manual, api, or tommy)

2. Parse Epic & Blocks

FORGE fetches the epic issue and extracts block references from its GitHub checklist. It then:

Iterates through each block to find the next open one (or uses an override if you specify one)
Parses that block for task items
Fetches metadata for each task (title, description, acceptance criteria)

3. Assemble Prompt

FORGE combines the epic context, block details, and task list into a structured prompt ready for execution.

4. Execute (3 Modes)

Manual (No execution)

Returns the assembled prompt for human review. You can read it, copy it, and decide whether to proceed manually.

Use case: One-off work, high-stakes changes, proof-of-concept
Timeout: 120 seconds

API (Direct Claude)

FORGE calls the Claude API directly (Anthropic), executes the prompt, and auto-closes GitHub issues on success. - Use case: Automated, low-risk tasks (refactoring, docs, simple bug fixes) - Timeout: 120 seconds - Requirements: CLAUDE_API_KEY from webhook or env

TOMMY (SSH + Delegation)

FORGE delegates to TOMMY — a companion workflow that SSH’s into a target server, checks out code, runs Claude CLI, and commits changes. TOMMY handles complex multi-step changes with automatic rollback if anything fails.

Use case: Production deployments, code writes that touch multiple files, critical infrastructure
Timeout: 1800 seconds (30 minutes)
Requirements: SSH host, project path, git credentials on target server

5. Auto-Closure

On success (api or tommy modes), FORGE:

Posts a completion comment on each task issue
Closes each task issue
Posts a summary comment on the block issue
Closes the block issue
Returns execution result to Rover

Webhook Input

When you trigger FORGE, you provide these fields:

{
  "gh_org": "traceo-ai",
  "gh_repo": "traceo-mcp-server",
  "epic_issue_number": 22,
  "block_issue_number": null,
  "execution_mode": "manual|api|tommy",
  "dry_run": false,
  "ssh_host": "root@vps.devarno.cloud",
  "project_path": "/root/projects/so1-platform",
  "claude_api_key": "sk-..."
}

The BFF automatically injects discord_webhook_forge (server-side secret) — you never see it in the browser.

Key Features

Dry-Run Mode (Phase 4)

Set dry_run: true and TOMMY will assemble a plan without writing to git. Useful for testing FORGE → TOMMY integration without side effects.

Block Override

Normally FORGE finds the next open block automatically. Use block_issue_number to override and target a specific block.

Discord Telemetry (ZOID Phase A)

FORGE posts event notifications to Discord:

Execution Started — when the workflow begins
Block Selected — which block was chosen
Execution Result — success/failure summary
Block Closed — confirmation block was resolved

These 4 HTTP nodes are disabled by default until Phase A burn-in is complete (5+ successful runs).

Configuration Fields

FORGE uses 12 configuration fields internally:

#	Field	Source	Default
a1	`gh_org`	Webhook	(required)
a2	`gh_repo`	Webhook	(required)
a3	`epic_issue`	Webhook	(required)
a4	`override_block`	Webhook	`""`
a5	`exec_mode`	Webhook	`"manual"`
a6	`target_repo`	Webhook	`""`
a7	`api_base`	Hardcoded	`https://api.github.com`
a8	`claude_key`	Webhook	`""`
a9	`ssh_host`	Webhook	`root@vps.devarno.cloud`
a10	`project_path`	Webhook	`/root/projects/so1-platform`
a11	`dry_run`	Webhook	`false`
a12	`discord_webhook_forge`	BFF-injected	`""`

a12 is special: The BFF injects this at trigger time from Vercel env. It’s never exposed to the browser, making Discord notifications secure by default.

TOMMY Integration

When execution_mode: "tommy", FORGE packages a payload for the TOMMY workflow and POSTs to https://hab.so1.io/webhook/atomiser. TOMMY’s 1800s timeout absorbs the full FORGE → plan → execute → verify loop. TOMMY payload includes:

Repository name and SSH host
List of tasks with file targets and acceptance criteria
Epic + block context
Dry-run flag (for safe-mode delegations)

Triggering FORGE

From Rover Console

Go to Agents → select an agent
Find FORGE in the “Linked Workflows” section
Click Run → fill in the form → submit
Monitor in Jobs to see execution

Via Direct Webhook

curl -X POST https://hab.so1.io/webhook/forge-resolve-next-ticket \
  -H "Content-Type: application/json" \
  -d '{
    "gh_org": "traceo-ai",
    "gh_repo": "traceo-mcp-server",
    "epic_issue_number": 22,
    "execution_mode": "manual"
  }'

Common Issues

GitHub issue structure required: FORGE expects epics to have markdown checklists referencing block issues, and blocks to have checklists referencing task issues. If your epic body doesn’t follow this pattern, FORGE won’t find any blocks or tasks.

Credentials Detach After Updates

After editing the workflow via the n8n API, credential bindings detach. You must manually re-select GitHub and Claude credentials in the n8n UI and save.

Vercel Proxy Timeout

The Rover UI routes through Vercel, which has a 300-second (5-minute) serverless function limit. Tommy-mode executions longer than 5 minutes timeout at the Vercel layer (but the n8n execution continues).

Learn More

For detailed phase verification procedures, replication patterns, and the full architecture:

Architecture

Full FORGE design: Set Configuration, TOMMY integration, BFF secret injection, Discord telemetry, issue closure chain.

Verification Runbook

Step-by-step procedures for Phases 4–7 + ZOID Phase A with curl examples and expected behavior.

Patterns & Scalability

Dry-run + BFF injection patterns, replication roadmap (TOMMY, social-engine, MCP-deployer), Q2–Q3 implementation phases.

Getting Started

Zoid Council Skills

FORGE Automation

FORGE Automation

Quick Identity

How FORGE Works

1. Receive Webhook

2. Parse Epic & Blocks

3. Assemble Prompt

4. Execute (3 Modes)

5. Auto-Closure

Webhook Input

Key Features

Dry-Run Mode (Phase 4)

Block Override

Discord Telemetry (ZOID Phase A)

Configuration Fields

TOMMY Integration

Triggering FORGE

From Rover Console

Via Direct Webhook

Common Issues

Credentials Detach After Updates

Vercel Proxy Timeout

Learn More

Architecture

Verification Runbook

Patterns & Scalability

Getting Started

Zoid Council Skills

​FORGE Automation

​Quick Identity

​How FORGE Works

​1. Receive Webhook

​2. Parse Epic & Blocks

​3. Assemble Prompt

​4. Execute (3 Modes)

​5. Auto-Closure

​Webhook Input

​Key Features

​Dry-Run Mode (Phase 4)

​Block Override

​Discord Telemetry (ZOID Phase A)

​Configuration Fields

​TOMMY Integration

​Triggering FORGE

​From Rover Console

​Via Direct Webhook

​Common Issues

​Credentials Detach After Updates

​Vercel Proxy Timeout

​Learn More

Architecture

Verification Runbook

Patterns & Scalability

FORGE Automation

Quick Identity

How FORGE Works

1. Receive Webhook

2. Parse Epic & Blocks

3. Assemble Prompt

4. Execute (3 Modes)

5. Auto-Closure

Webhook Input

Key Features

Dry-Run Mode (Phase 4)

Block Override

Discord Telemetry (ZOID Phase A)

Configuration Fields

TOMMY Integration

Triggering FORGE

From Rover Console

Via Direct Webhook

Common Issues

Credentials Detach After Updates

Vercel Proxy Timeout

Learn More