https://github.com/lueurxax/chainworks-forge

Local macOS control plane for agent-driven engineering workflows with YAML runs, artifacts, and approval gates.
https://github.com/lueurxax/chainworks-forge

agent-control-plane chainworks claude-code codex goose macos swiftdata swiftui workflow-orchestration yaml

Last synced: about 1 month ago
JSON representation

Local macOS control plane for agent-driven engineering workflows with YAML runs, artifacts, and approval gates.

• Host: GitHub
• URL: https://github.com/lueurxax/chainworks-forge
• Owner: lueurxax
• Created: 2026-03-22T06:37:41.000Z (3 months ago)
• Default Branch: main
• Last Pushed: 2026-05-23T21:03:44.000Z (about 1 month ago)
• Last Synced: 2026-05-23T21:20:15.480Z (about 1 month ago)
• Topics: agent-control-plane, chainworks, claude-code, codex, goose, macos, swiftdata, swiftui, workflow-orchestration, yaml
• Language: Rust
• Size: 1.32 GB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Roadmap: ROADMAP.md
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# Chainworks Forge



  



Chainworks Forge is a macOS SwiftUI control plane for agent-driven engineering workflows.

It is built around one idea: the primary object is not a chat thread. It is a **Run**.

A run takes one idea, compiles a frozen workflow snapshot, routes work through specialized agents, pauses at explicit approval gates, stores durable artifacts, and leaves behind a truthful report of what happened.

## Why This Project Exists

Chainworks Forge did not start as a generic AI chat app.

It started from a practical frustration: too much engineering work was still happening through repetitive manual steps.

The first version of the idea was much closer to "a workflow orchestrator on top of `goosed`."

After experimenting with Goose and seeing how interesting multi-agent coordination could become when different agents had different roles, parameters, and responsibilities, the project expanded from a thin wrapper into a real operator-facing workflow system.

The turning point was simple: once the workflows became useful, too many important actions still depended on manual coordination.

That pushed the project toward a stricter model:

- workflows instead of ad hoc prompt chains

- explicit agent roles instead of one general-purpose assistant

- durable artifacts and reports instead of ephemeral chat history

- approval gates instead of invisible autonomous continuation

- runtime abstraction instead of hard-coding one backend forever

That is why the runtime story changed as well.

The project originally leaned on Goose and `goosed` as the practical execution substrate.

Today, the product is moving away from Goose as the canonical transport model and toward a set of ACP-backed runtimes such as Codex, Claude Code, and Gemini.

Goose still matters as legacy and compatibility infrastructure, but it is no longer the long-term center of the design.

## What The App Does

- captures ideas as units of engineering work

- executes YAML-defined workflows instead of hardcoded chat flows

- routes proposal reviews deterministically based on evidence and a specialist catalog

- binds specialized agents to providers, models, permissions, and output contracts

- preserves run state, stage history, approvals, and artifact metadata in the backend (read by the UI via GraphQL projections)

- stores generated artifacts on disk instead of hiding execution inside chat history

- supports recovery, comparison, reporting, and approval-driven continuation

- keeps repo-backed delivery and release work behind explicit gates

In practice, Chainworks Forge sits between ad hoc AI chats and heavyweight orchestration systems: local-first, inspectable, and built for one engineer running governed multi-agent workflows from a desktop app.

## Product Direction

The current direction is:

- ACP-first runtime transport

- thin GraphQL-only operator UI over server-owned projections

- frozen run truth and operator-visible recovery

- backend-specific agent tuning through catalog-defined workflows

- local-first execution with explicit provider/runtime diagnostics

- compatibility retained where useful, but not treated as the long-term architecture

The project is intentionally opinionated.

It assumes that workflow truth, artifacts, approvals, and recovery matter more than "just keep chatting," especially once multiple agents, repos, and delivery steps are involved.

## Core Concepts

| Concept | Meaning |

|---|---|

| `Idea` | A user-entered piece of work, optionally tied to files or a workspace. |

| `Workflow` | A YAML-defined execution graph with stages, approvals, transitions, and agent references. |

| `Run` | One execution instance of a workflow for one idea. This is the main operational object in the system. |

| `RunPlanSnapshot` | The frozen workflow, catalog, provider binding, and path snapshot compiled at run start. |

| `Agent` | A specialized worker with explicit role, provider binding, tool access, and output contract. |

| `Artifact` | Durable output such as a proposal, review report, diff, transcript, receipt, or run report. |

| `Approval gate` | A workflow-defined pause where the engineer must explicitly continue. |

## Current Product Shape

Today the app exposes these top-level operator surfaces through the thin GraphQL read boundary:

- `Runs` for active, blocked, running, and completed runs, with inline approval context and an attention badge (GraphQL-only)

- `Ideas` for browsing idea context with compact run status strips that deep-link into Runs (read-first; non-approval writes remain outside the governed thin UI write path)

- `Definitions` for browsing the resolved Agent Catalog and Workflow Inspector through a segmented surface

- `Settings` for provider configuration, diagnostics, remediation, and System Readiness (formerly Pilot Readiness)

The current MVP provider set is:

- `Codex`

- `Claude Code`

- `Gemini`

## Current Status

The repository is past the scaffold stage. The implemented system now includes:

- lead-mediated workflow conflict resolution and mandatory lead validation

- GraphQL-only thin UI boundary ensuring governed SwiftUI workflow truth is read from server projections

- frozen run snapshots, YAML validation, provenance, and deterministic execution truth

- declarative workflow authority, typed workflow conflicts, and advisory rejection history

- operator-facing run, approval, report, recovery, and comparison surfaces

- provider configuration, remediation, ACP-backed execution slices, and legacy Goose compatibility paths

- local Rust daemon lifecycle, supervision, packaged-mode health/readiness, diagnostics, and release-host packaging proof lanes

- repo-backed delivery, release gating, benchmark/sign-off, and export flows

- provider toolchain cache mapping ensuring isolated writable roots for Xcode and Go

- Run Worktree Main Sync and Cross-Run Knowledge Transfer (Proposal 064 Phase 0 contract freeze)

- implementation completeness and handoff contract with structured status and verification truth

- bounded implementation closeout readiness gates ensuring proposal proof, audit coverage, evidence freshness, and handoff settlement before release

- durable side-effect ledger, release settlement, and reconciliation

- fail-closed server parity harness with generation-scoped storage and runtime publication

- deterministic reviewer routing and expanded proposal reviewer catalog

- stable reference documentation under [`docs/reference`](docs/reference)

- proof artifacts under [`docs/evidence`](docs/evidence)

- stable proposal-loop feedback-fidelity documentation and proof under [`docs/reference`](docs/reference) and [`docs/evidence`](docs/evidence)

- Local Persistence Write Budget and Evidence Spooling — DbWriter lanes/coalescing/shutdown primitives, evidence_spool_refs and storage_write_pressure_snapshots schemas, failed-stage evidence spooling, transcript spooling, storageHealth/MCP diagnostics with live heartbeat/drain/lock/WAL readback, diagnostics-bundle storage snapshots, and fail-closed write-bypass/raw-evidence gate coverage are implemented. Temporary rollout bypasses are retired; the remaining allowlist is limited to migrations, tests, startup repair, and evidence-spool orphan repair.

- Agent work continuation and lead-directed same-session resumption — `agents.continue_work`, `agents.continuation_status`, and `agents.continuation_candidates` MCP commands for eligible stage-owned `code_writer` agent executions, with persisted continuation/side-effect ledger/supervised-worker/provider-process tables, durable metric events, materialized Draft 2020-12 JSON Schemas, and guarded admission for `live_handle_continuation`. `lead_auto` may be requested by Agent principals only with a validated lead decision artifact; `operator_mcp` remains Operator-only. Per-adapter `provider_session_resurrection` remains explicit and fail-closed for adapters that do not declare attach/resume support. The worker drives the `accepted → … → succeeded | no_progress | failed | cancelled` state machine with durable runtime/worktree/provider-send ledger rows, a live-handle attach receipt, heartbeat-backed supervised-worker ownership, cancellation cascade handling, duplicate-send reconciliation that requires provider-send evidence, worktree readback, evidence bundle, response snapshot, result/no-progress, operator report artifacts, passive GraphQL history/metrics readback, and a read-only macOS Overview card. `P086` names remain only as retained gate/schema/evidence aliases.

Active proposal work is currently concentrated in:

- [`docs/proposals/032-polish-stabilization-and-productization-backlog.md`](docs/proposals/032-polish-stabilization-and-productization-backlog.md)

- [`docs/proposals/020-dynamic-cycle-addition.md`](docs/proposals/020-dynamic-cycle-addition.md)

The canonical thin UI contract is [`docs/reference/query-projections-and-client-consumption-contract.md`](docs/reference/query-projections-and-client-consumption-contract.md). The consolidated macOS operator navigation contract is [`docs/reference/macos-operator-navigation.md`](docs/reference/macos-operator-navigation.md), and the specific contract for GraphQL-driven UI states, actionability, and fallback copy is [`docs/reference/thin-client-read-model-affordance-contract.md`](docs/reference/thin-client-read-model-affordance-contract.md). New UI proposals should build on these references rather than historical proposal text. The docs index at [`docs/README.md`](docs/README.md) is the canonical map of implemented references, active proposals, evidence, and historical review material.

## Implemented Today

The repository is no longer a scaffold. It already contains the core control-plane and runtime slices:

- SwiftUI macOS app shell with operator-facing tabs and recovery/report surfaces

- SwiftData models for ideas, runs, stages, approvals, artifacts, benchmark/sign-off state, and provider state

- YAML parsing, validation, normalization, and frozen provenance snapshotting

- run compilation and execution services:

  - `RunPlanCompiler`

  - `TransitionEvaluator`

  - `ExecutionService`

  - `WorkflowOrchestrator`

  - `ResumeManager`

  - Capacity-aware scheduling, fairness, executor backpressure, SQLite write serialization, and host interruption recovery (Rust daemon)

- artifact persistence and retrieval:

  - `ArtifactStorage`

  - `ArtifactManager`

  - `bounded artifact discovery and settlement optimization`

  - report/export surfaces

- provider platform slices:

  - provider settings

  - System Readiness (formerly Pilot Readiness; now a Settings section in the consolidated operator shell)

  - ACP-oriented runtime dispatch and provider bindings

  - Goose compatibility diagnostics and remediation

  - frozen provider/model provenance truth

- local daemon lifecycle slice:

  - typed health/readiness and `daemonStatus` readback

  - packaged app/helper supervision with PID lock and crash budget

  - SQLite migration preflight, failed-serve status, diagnostics export, and packaged daemon proof lanes

- repo-backed delivery slice:

  - worktree provisioning

  - delivery configuration freezing

  - release gate UI

  - evidence/export paths

- MVP sign-off layer:

  - persisted benchmark/sign-off state

  - completed-run export hub

  - replayable `GO/HOLD` decision snapshots

  - approved-host current-head proof gates

- layered test gates for fast runtime validation, remote UI smoke, and full sign-off

- consolidated macOS operator shell: four-surface navigation, old-route compatibility, `RunsWorkbenchPresentationModel` and shared deferred-state types, Definitions segmented surface over Agent Catalog and Workflow Inspector, System Readiness/provider diagnostics inside Settings, active-agent Timeline projection in Runs, dogfood evidence, remote UI/accessibility proof, and rollout readback

## Repository Layout

```text

Chainworks Forge/

  Chainworks Forge.xcodeproj/   Xcode project

  Chainworks Forge/             SwiftUI app sources

    DSL/                        YAML parsing, validation, normalization

    Engine/                     Compiler, orchestration, execution, recovery, export

    Models/                     SwiftData models and repositories

    Views/                      Operator UI surfaces

    Support/                    Policies, design tokens, app configuration

  Chainworks ForgeTests/        Unit and integration tests

  Chainworks ForgeUITests/      macOS UI tests

  TestPlans/                    Xcode test-plan metadata

  docs/                         reference docs, proposals, research, evidence

  examples/                     agent catalogs and workflow examples

  scripts/                      operational helpers, including test gates

```

## Installation And Local Setup

### Requirements

- macOS compatible with the app target (`MACOSX_DEPLOYMENT_TARGET = 26.2`)

- Xcode `26.3` or newer

- a configured provider runtime if you want live agent execution (`Codex`, `Claude Code`, or `Gemini`)

- provider CLIs and ACP-capable runtimes where required by the selected backend profiles

- optional: an approved remote UI host if you need canonical UI smoke or full sign-off gates

### Clone The Repository

```bash

git clone  "Chainworks Forge"

cd "Chainworks Forge"

```

### Open The Project

```bash

open "Chainworks Forge.xcodeproj"

```

### Build And Launch

```bash

./scripts/test-gate.sh build

```

Then run the app from Xcode. On first launch, use `Settings` to configure providers, diagnostics, and remediation. If you want live execution, make sure the selected ACP/provider runtime is installed and authenticated, and that any compatibility services you still rely on are running.

### Default Engineering Gate

```bash

./scripts/test-gate.sh fast

```

The repository uses layered test gates. The canonical proving path is the gate runner, not raw `xcodebuild -testPlan ...` commands.

### Optional Remote UI Host

Remote UI execution is still repo-policy-bound. If you need canonical UI proof lanes, use the approved remote host configuration documented in [`docs/reference/agent-ui-test-execution.md`](docs/reference/agent-ui-test-execution.md).

## Test Gates

List available gates:

```bash

./scripts/test-gate.sh list

```

Most common gates:

- `./scripts/test-gate.sh build` — compile-only sanity check

- `./scripts/test-gate.sh fast` — default inner-loop runtime/unit gate

- Focused implementation completeness and handoff proof gate — see `docs/reference/test-gates.md`

- `ssh test@SMacBook.local "cd '/Users/test/chainworks-remote' && ./scripts/test-gate.sh ui-smoke"` — remote-only UI smoke gate

- `ssh test@SMacBook.local "cd '/Users/test/chainworks-remote' && ./scripts/test-gate.sh proposal-022"` — remote-only Proposal 022 proof gate

- `ssh test@SMacBook.local "cd '/Users/test/chainworks-remote' && ./scripts/test-gate.sh full"` — remote-only full sign-off gate

Important:

- UI tests are remote-only by repo policy

- the remote UI host path is documented in [`docs/reference/agent-ui-test-execution.md`](docs/reference/agent-ui-test-execution.md)

- gate behavior and intended usage are documented in [`docs/reference/test-gates.md`](docs/reference/test-gates.md)

## Key Docs

Start here:

- [`docs/README.md`](docs/README.md) — documentation index and reading order

- [`docs/reference/current-system-baseline.md`](docs/reference/current-system-baseline.md) — current-head subsystem map and baseline

- [`docs/ps/chainworks-forge-mvp.md`](docs/ps/chainworks-forge-mvp.md) — MVP scope and requirements

- [`docs/research/chainworks_core_idea.md`](docs/research/chainworks_core_idea.md) — product vision and positioning

- [`docs/reference/acp-runtime-transport.md`](docs/reference/acp-runtime-transport.md) — ACP runtime transport and adapter-family contract

Implemented-system references:

- [`docs/reference/workflow-execution-engine.md`](docs/reference/workflow-execution-engine.md)

- [`docs/reference/artifact-discovery-and-settlement-optimization.md`](docs/reference/artifact-discovery-and-settlement-optimization.md)

- [`docs/reference/runtime-contract.md`](docs/reference/runtime-contract.md)

- [`docs/reference/execution-truth-and-recovery.md`](docs/reference/execution-truth-and-recovery.md)

- [`docs/reference/output-contracts-failure-evidence-and-recovery.md`](docs/reference/output-contracts-failure-evidence-and-recovery.md)

- [`docs/reference/session-lineage-reuse-and-operator-reset.md`](docs/reference/session-lineage-reuse-and-operator-reset.md)

- [`docs/reference/context-strategy-and-experiment-framework.md`](docs/reference/context-strategy-and-experiment-framework.md)

- [`docs/reference/proposal-loop-feedback-fidelity-and-rereview.md`](docs/reference/proposal-loop-feedback-fidelity-and-rereview.md)

- [`docs/reference/operator-experience.md`](docs/reference/operator-experience.md)

- [`docs/reference/provider-platform.md`](docs/reference/provider-platform.md)

- [`docs/reference/ui-quality-and-polish.md`](docs/reference/ui-quality-and-polish.md)

- [`docs/reference/design-system-and-brand-application.md`](docs/reference/design-system-and-brand-application.md)

- [`docs/reference/full-mvp-delivery.md`](docs/reference/full-mvp-delivery.md)

- [`docs/reference/mvp-sign-off.md`](docs/reference/mvp-sign-off.md)

- [`docs/reference/test-gates.md`](docs/reference/test-gates.md)

- [`docs/reference/agent-work-continuation.md`](docs/reference/agent-work-continuation.md)

Examples:

- [`examples/README.md`](examples/README.md)

- [`examples/agents/agents.yaml`](examples/agents/agents.yaml)

- [`examples/workflows/workflow.yaml`](examples/workflows/workflow.yaml)

- [`examples/workflows/proposal-loop-live.yaml`](examples/workflows/proposal-loop-live.yaml)

- [`examples/workflows/full-mvp-live.yaml`](examples/workflows/full-mvp-live.yaml)

- [`examples/workflows/proposal-to-release.yaml`](examples/workflows/proposal-to-release.yaml)

## Brand Assets

Brand sources and rendered assets live under [`docs/brand`](docs/brand). The app icon set used by the macOS target lives under [`Chainworks Forge/Assets.xcassets/AppIcon.appiconset`]().