{"id":50160955,"url":"https://github.com/lueurxax/chainworks-forge","last_synced_at":"2026-05-24T15:05:01.284Z","repository":{"id":350241429,"uuid":"1188493879","full_name":"lueurxax/chainworks-forge","owner":"lueurxax","description":"Local macOS control plane for agent-driven engineering workflows with YAML runs, artifacts, and approval gates.","archived":false,"fork":false,"pushed_at":"2026-05-23T21:03:44.000Z","size":1418999,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T21:20:15.480Z","etag":null,"topics":["agent-control-plane","chainworks","claude-code","codex","goose","macos","swiftdata","swiftui","workflow-orchestration","yaml"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lueurxax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-22T06:37:41.000Z","updated_at":"2026-05-23T16:40:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lueurxax/chainworks-forge","commit_stats":null,"previous_names":["lueurxax/chainworks-forge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lueurxax/chainworks-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lueurxax%2Fchainworks-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lueurxax%2Fchainworks-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lueurxax%2Fchainworks-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lueurxax%2Fchainworks-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lueurxax","download_url":"https://codeload.github.com/lueurxax/chainworks-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lueurxax%2Fchainworks-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33438560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T13:13:05.286Z","status":"ssl_error","status_checked_at":"2026-05-24T13:13:03.728Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-control-plane","chainworks","claude-code","codex","goose","macos","swiftdata","swiftui","workflow-orchestration","yaml"],"created_at":"2026-05-24T15:04:51.923Z","updated_at":"2026-05-24T15:05:01.259Z","avatar_url":"https://github.com/lueurxax.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chainworks Forge\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/brand/render/chainworks-forge-readme-hero.png\" alt=\"Chainworks Forge brand hero\" width=\"920\" /\u003e\n\u003c/p\u003e\n\nChainworks Forge is a macOS SwiftUI control plane for agent-driven engineering workflows.\n\nIt is built around one idea: the primary object is not a chat thread. It is a **Run**.\nA 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.\n\n## Why This Project Exists\n\nChainworks Forge did not start as a generic AI chat app.\nIt started from a practical frustration: too much engineering work was still happening through repetitive manual steps.\n\nThe first version of the idea was much closer to \"a workflow orchestrator on top of `goosed`.\"\nAfter 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.\n\nThe turning point was simple: once the workflows became useful, too many important actions still depended on manual coordination.\nThat pushed the project toward a stricter model:\n\n- workflows instead of ad hoc prompt chains\n- explicit agent roles instead of one general-purpose assistant\n- durable artifacts and reports instead of ephemeral chat history\n- approval gates instead of invisible autonomous continuation\n- runtime abstraction instead of hard-coding one backend forever\n\nThat is why the runtime story changed as well.\nThe project originally leaned on Goose and `goosed` as the practical execution substrate.\nToday, 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.\nGoose still matters as legacy and compatibility infrastructure, but it is no longer the long-term center of the design.\n\n## What The App Does\n\n- captures ideas as units of engineering work\n- executes YAML-defined workflows instead of hardcoded chat flows\n- routes proposal reviews deterministically based on evidence and a specialist catalog\n- binds specialized agents to providers, models, permissions, and output contracts\n- preserves run state, stage history, approvals, and artifact metadata in the backend (read by the UI via GraphQL projections)\n- stores generated artifacts on disk instead of hiding execution inside chat history\n- supports recovery, comparison, reporting, and approval-driven continuation\n- keeps repo-backed delivery and release work behind explicit gates\n\nIn 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.\n\n## Product Direction\n\nThe current direction is:\n\n- ACP-first runtime transport\n- thin GraphQL-only operator UI over server-owned projections\n- frozen run truth and operator-visible recovery\n- backend-specific agent tuning through catalog-defined workflows\n- local-first execution with explicit provider/runtime diagnostics\n- compatibility retained where useful, but not treated as the long-term architecture\n\nThe project is intentionally opinionated.\nIt assumes that workflow truth, artifacts, approvals, and recovery matter more than \"just keep chatting,\" especially once multiple agents, repos, and delivery steps are involved.\n\n## Core Concepts\n\n| Concept | Meaning |\n|---|---|\n| `Idea` | A user-entered piece of work, optionally tied to files or a workspace. |\n| `Workflow` | A YAML-defined execution graph with stages, approvals, transitions, and agent references. |\n| `Run` | One execution instance of a workflow for one idea. This is the main operational object in the system. |\n| `RunPlanSnapshot` | The frozen workflow, catalog, provider binding, and path snapshot compiled at run start. |\n| `Agent` | A specialized worker with explicit role, provider binding, tool access, and output contract. |\n| `Artifact` | Durable output such as a proposal, review report, diff, transcript, receipt, or run report. |\n| `Approval gate` | A workflow-defined pause where the engineer must explicitly continue. |\n\n## Current Product Shape\n\nToday the app exposes these top-level operator surfaces through the thin GraphQL read boundary:\n\n- `Runs` for active, blocked, running, and completed runs, with inline approval context and an attention badge (GraphQL-only)\n- `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)\n- `Definitions` for browsing the resolved Agent Catalog and Workflow Inspector through a segmented surface\n- `Settings` for provider configuration, diagnostics, remediation, and System Readiness (formerly Pilot Readiness)\n\nThe current MVP provider set is:\n\n- `Codex`\n- `Claude Code`\n- `Gemini`\n\n## Current Status\n\nThe repository is past the scaffold stage. The implemented system now includes:\n\n- lead-mediated workflow conflict resolution and mandatory lead validation\n- GraphQL-only thin UI boundary ensuring governed SwiftUI workflow truth is read from server projections\n- frozen run snapshots, YAML validation, provenance, and deterministic execution truth\n- declarative workflow authority, typed workflow conflicts, and advisory rejection history\n- operator-facing run, approval, report, recovery, and comparison surfaces\n- provider configuration, remediation, ACP-backed execution slices, and legacy Goose compatibility paths\n- local Rust daemon lifecycle, supervision, packaged-mode health/readiness, diagnostics, and release-host packaging proof lanes\n- repo-backed delivery, release gating, benchmark/sign-off, and export flows\n- provider toolchain cache mapping ensuring isolated writable roots for Xcode and Go\n- Run Worktree Main Sync and Cross-Run Knowledge Transfer (Proposal 064 Phase 0 contract freeze)\n- implementation completeness and handoff contract with structured status and verification truth\n- bounded implementation closeout readiness gates ensuring proposal proof, audit coverage, evidence freshness, and handoff settlement before release\n- durable side-effect ledger, release settlement, and reconciliation\n- fail-closed server parity harness with generation-scoped storage and runtime publication\n- deterministic reviewer routing and expanded proposal reviewer catalog\n- stable reference documentation under [`docs/reference`](docs/reference)\n- proof artifacts under [`docs/evidence`](docs/evidence)\n- stable proposal-loop feedback-fidelity documentation and proof under [`docs/reference`](docs/reference) and [`docs/evidence`](docs/evidence)\n- 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.\n- 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.\n\nActive proposal work is currently concentrated in:\n\n- [`docs/proposals/032-polish-stabilization-and-productization-backlog.md`](docs/proposals/032-polish-stabilization-and-productization-backlog.md)\n- [`docs/proposals/020-dynamic-cycle-addition.md`](docs/proposals/020-dynamic-cycle-addition.md)\n\nThe 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.\n\n## Implemented Today\n\nThe repository is no longer a scaffold. It already contains the core control-plane and runtime slices:\n\n- SwiftUI macOS app shell with operator-facing tabs and recovery/report surfaces\n- SwiftData models for ideas, runs, stages, approvals, artifacts, benchmark/sign-off state, and provider state\n- YAML parsing, validation, normalization, and frozen provenance snapshotting\n- run compilation and execution services:\n  - `RunPlanCompiler`\n  - `TransitionEvaluator`\n  - `ExecutionService`\n  - `WorkflowOrchestrator`\n  - `ResumeManager`\n  - Capacity-aware scheduling, fairness, executor backpressure, SQLite write serialization, and host interruption recovery (Rust daemon)\n- artifact persistence and retrieval:\n  - `ArtifactStorage`\n  - `ArtifactManager`\n  - `bounded artifact discovery and settlement optimization`\n  - report/export surfaces\n- provider platform slices:\n  - provider settings\n  - System Readiness (formerly Pilot Readiness; now a Settings section in the consolidated operator shell)\n  - ACP-oriented runtime dispatch and provider bindings\n  - Goose compatibility diagnostics and remediation\n  - frozen provider/model provenance truth\n- local daemon lifecycle slice:\n  - typed health/readiness and `daemonStatus` readback\n  - packaged app/helper supervision with PID lock and crash budget\n  - SQLite migration preflight, failed-serve status, diagnostics export, and packaged daemon proof lanes\n- repo-backed delivery slice:\n  - worktree provisioning\n  - delivery configuration freezing\n  - release gate UI\n  - evidence/export paths\n- MVP sign-off layer:\n  - persisted benchmark/sign-off state\n  - completed-run export hub\n  - replayable `GO/HOLD` decision snapshots\n  - approved-host current-head proof gates\n- layered test gates for fast runtime validation, remote UI smoke, and full sign-off\n- 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\n\n## Repository Layout\n\n```text\nChainworks Forge/\n  Chainworks Forge.xcodeproj/   Xcode project\n  Chainworks Forge/             SwiftUI app sources\n    DSL/                        YAML parsing, validation, normalization\n    Engine/                     Compiler, orchestration, execution, recovery, export\n    Models/                     SwiftData models and repositories\n    Views/                      Operator UI surfaces\n    Support/                    Policies, design tokens, app configuration\n  Chainworks ForgeTests/        Unit and integration tests\n  Chainworks ForgeUITests/      macOS UI tests\n  TestPlans/                    Xcode test-plan metadata\n  docs/                         reference docs, proposals, research, evidence\n  examples/                     agent catalogs and workflow examples\n  scripts/                      operational helpers, including test gates\n```\n\n## Installation And Local Setup\n\n### Requirements\n\n- macOS compatible with the app target (`MACOSX_DEPLOYMENT_TARGET = 26.2`)\n- Xcode `26.3` or newer\n- a configured provider runtime if you want live agent execution (`Codex`, `Claude Code`, or `Gemini`)\n- provider CLIs and ACP-capable runtimes where required by the selected backend profiles\n- optional: an approved remote UI host if you need canonical UI smoke or full sign-off gates\n\n### Clone The Repository\n\n```bash\ngit clone \u003cyour-remote-url\u003e \"Chainworks Forge\"\ncd \"Chainworks Forge\"\n```\n\n### Open The Project\n\n```bash\nopen \"Chainworks Forge.xcodeproj\"\n```\n\n### Build And Launch\n\n```bash\n./scripts/test-gate.sh build\n```\n\nThen 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.\n\n### Default Engineering Gate\n\n```bash\n./scripts/test-gate.sh fast\n```\n\nThe repository uses layered test gates. The canonical proving path is the gate runner, not raw `xcodebuild -testPlan ...` commands.\n\n### Optional Remote UI Host\n\nRemote 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).\n\n## Test Gates\n\nList available gates:\n\n```bash\n./scripts/test-gate.sh list\n```\n\nMost common gates:\n\n- `./scripts/test-gate.sh build` — compile-only sanity check\n- `./scripts/test-gate.sh fast` — default inner-loop runtime/unit gate\n- Focused implementation completeness and handoff proof gate — see `docs/reference/test-gates.md`\n- `ssh test@SMacBook.local \"cd '/Users/test/chainworks-remote' \u0026\u0026 ./scripts/test-gate.sh ui-smoke\"` — remote-only UI smoke gate\n- `ssh test@SMacBook.local \"cd '/Users/test/chainworks-remote' \u0026\u0026 ./scripts/test-gate.sh proposal-022\"` — remote-only Proposal 022 proof gate\n- `ssh test@SMacBook.local \"cd '/Users/test/chainworks-remote' \u0026\u0026 ./scripts/test-gate.sh full\"` — remote-only full sign-off gate\n\nImportant:\n\n- UI tests are remote-only by repo policy\n- the remote UI host path is documented in [`docs/reference/agent-ui-test-execution.md`](docs/reference/agent-ui-test-execution.md)\n- gate behavior and intended usage are documented in [`docs/reference/test-gates.md`](docs/reference/test-gates.md)\n\n## Key Docs\n\nStart here:\n\n- [`docs/README.md`](docs/README.md) — documentation index and reading order\n- [`docs/reference/current-system-baseline.md`](docs/reference/current-system-baseline.md) — current-head subsystem map and baseline\n- [`docs/ps/chainworks-forge-mvp.md`](docs/ps/chainworks-forge-mvp.md) — MVP scope and requirements\n- [`docs/research/chainworks_core_idea.md`](docs/research/chainworks_core_idea.md) — product vision and positioning\n- [`docs/reference/acp-runtime-transport.md`](docs/reference/acp-runtime-transport.md) — ACP runtime transport and adapter-family contract\n\nImplemented-system references:\n\n- [`docs/reference/workflow-execution-engine.md`](docs/reference/workflow-execution-engine.md)\n- [`docs/reference/artifact-discovery-and-settlement-optimization.md`](docs/reference/artifact-discovery-and-settlement-optimization.md)\n- [`docs/reference/runtime-contract.md`](docs/reference/runtime-contract.md)\n- [`docs/reference/execution-truth-and-recovery.md`](docs/reference/execution-truth-and-recovery.md)\n- [`docs/reference/output-contracts-failure-evidence-and-recovery.md`](docs/reference/output-contracts-failure-evidence-and-recovery.md)\n- [`docs/reference/session-lineage-reuse-and-operator-reset.md`](docs/reference/session-lineage-reuse-and-operator-reset.md)\n- [`docs/reference/context-strategy-and-experiment-framework.md`](docs/reference/context-strategy-and-experiment-framework.md)\n- [`docs/reference/proposal-loop-feedback-fidelity-and-rereview.md`](docs/reference/proposal-loop-feedback-fidelity-and-rereview.md)\n- [`docs/reference/operator-experience.md`](docs/reference/operator-experience.md)\n- [`docs/reference/provider-platform.md`](docs/reference/provider-platform.md)\n- [`docs/reference/ui-quality-and-polish.md`](docs/reference/ui-quality-and-polish.md)\n- [`docs/reference/design-system-and-brand-application.md`](docs/reference/design-system-and-brand-application.md)\n- [`docs/reference/full-mvp-delivery.md`](docs/reference/full-mvp-delivery.md)\n- [`docs/reference/mvp-sign-off.md`](docs/reference/mvp-sign-off.md)\n- [`docs/reference/test-gates.md`](docs/reference/test-gates.md)\n- [`docs/reference/agent-work-continuation.md`](docs/reference/agent-work-continuation.md)\n\nExamples:\n\n- [`examples/README.md`](examples/README.md)\n- [`examples/agents/agents.yaml`](examples/agents/agents.yaml)\n- [`examples/workflows/workflow.yaml`](examples/workflows/workflow.yaml)\n- [`examples/workflows/proposal-loop-live.yaml`](examples/workflows/proposal-loop-live.yaml)\n- [`examples/workflows/full-mvp-live.yaml`](examples/workflows/full-mvp-live.yaml)\n- [`examples/workflows/proposal-to-release.yaml`](examples/workflows/proposal-to-release.yaml)\n\n## Brand Assets\n\nBrand 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`](\u003cChainworks Forge/Assets.xcassets/AppIcon.appiconset\u003e).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flueurxax%2Fchainworks-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flueurxax%2Fchainworks-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flueurxax%2Fchainworks-forge/lists"}