Smithy: A Workflow Orchestration Framework for AI Programming Agents

Smithy is a workflow orchestration framework for AI programming agents, forked from OpenAI Symphony, with the core metaphor of a 'workshop'—Smithy as the workshop, AI agents as craftsmen, and work orders as tasks to be completed. Its core positioning is clear: Smithy itself does not carry intelligence; intelligence resides in the agents that process work orders. Currently, the project is evolving from v1 to v2; v2 will be rebuilt using the Elixir language and Phoenix framework to improve scalability. Key features of the framework include dual runtime support, cross-model adversarial review, Linear OAuth integration, and tag-driven automatic merging.

Smithy's architecture has evolved from v1 to v2. v1 used a single Rust binary, ran via the launchd daemon, and periodically polled the Linear platform to assign tasks to Claude Code or Codex, but its features were basic and it is now disabled. v2 is a deep fork of OpenAI Symphony, inheriting Symphony's advantages such as the Phoenix LiveView dashboard, supervised polling mechanism, and Codex application server integration, while adding innovative features like dual runtime scheduling, cross-model adversarial review, and Linear OAuth authentication. The relationship between Smithy and Symphony is 'inheritance rather than repetition'; they share the Apache-2.0 license, and the team commits to keeping in sync with the upstream main branch, with the view layer implemented via additional files and patches.

The core functions of Smithy v2 include: 1. Dual runtime support: Compatible with both OpenAI Codex and Anthropic Claude Code; work orders can specify a runtime via tags, or use the default configuration if not specified. 2. Cross-model adversarial review: After Claude completes a task, it is reviewed by Codex, and vice versa; reviewers cannot see the construction reasoning process, and results are divided into three states: pass, fail, and block. 3. Specification quality gating: Pre-check whether the specifications are sufficient before a work order enters the queue; if insufficient, it is returned with a list of missing items. 4. Work order state machine: Starts from 'Ready for Dev', then goes through specification gating, runtime selection, processing, adversarial review, manual review/automatic merging, and finally completes or is returned. Linear OAuth integration ensures operations are performed as a service account, guaranteeing security and auditability.

Technical highlights of Smithy v2 include: SQLite history dashboard provides model summary logs, supports cost summary statistics by day, tenant, and runtime, and can link to original stream JSON data; Maximum retry circuit breaker mechanism: After a task fails N times, the 'harness-blocked' tag is automatically added, and it is transferred to manual review with a failure summary to prevent infinite retries; Bootstrap PR mode: The smithy bootstrap <repo> command clones the repository, generates configuration files such as AGENTS.md and .codex/skills, and automatically submits a pull request; after merging, the repository is managed by Smithy.

Smithy belongs to a larger tool family: Anvil is an independent encapsulation of adversarial review states and review agents, which can be used independently by Symphony users; Whetstone is a Rust-based wave-protocol agent executor; Salazar is an autonomous code generation orchestrator based on the Claude Agent SDK, using a planner/generator/evaluator loop architecture with hard validator gating. These tools share the 'forging' theme metaphor: Smithy (workshop), Anvil (anvil tool), Whetstone (whetstone), Elixir (programming language and alchemical elixir), forming a unique cultural color.

Currently, Smithy v2 is under active development; v1 installation instructions are retained in docs/DEPLOY.md for reference, but the v1 daemon has been disabled. The official release of v2 requires the completion of Phase 0-10 (see v2/SPEC.md for details), after which it will be marked as version v2.0.0. Developers can follow the repository and keep an eye on the release of v2.0.0-alpha-* tags; the v2 installation guide will be provided after development is completed.