Goal Forge

Goal Forge is a small project scaffold for building a Codex Goal style, critique-led subagent workflow.

The idea is not to make agents chat freely. The useful part is a strict review protocol:

• every artifact has an explicit contract;
• every field and naming choice can be challenged;
• objections are tracked until accepted, revised, or marked out of scope;
• evidence and comparable references are separated from opinions;
• the final document is compact, but the decision ledger remains auditable.

Current Shape

This repository starts as a TypeScript workflow skeleton. The default path is offline and deterministic, while the optional OpenAI adapter can call the OpenAI Agents SDK when OPENAI_API_KEY is set.

Included:

• src/index.ts: CLI for creating and validating a review run.
• src/adapters/local.ts: deterministic adapter used by smoke tests.
• src/adapters/openai-agents.ts: optional OpenAI Agents SDK adapter with structured output.
• src/adapters/codex-cli.ts: optional Codex CLI adapter for repository-aware verification.
• src/config.ts: file-backed workflow config loader and validator.
• templates/: artifact and ledger templates plus audited agent prompt examples.
• src/adapters/prompt-builder.ts: runtime prompt builder; templates/agents/*.md are checked reference examples, not the adapter prompt source.
• docs/research.md: current references and implementation options.
• docs/deep-reference.md: deeper reference analysis and implementation decisions.
• docs/workflow-spec.md: the intended debate/review protocol.
• docs/product-guide.md: end-to-end usage, blocked run handling, and milestone gates.
• docs/production-readiness.md: production gate, supported production paths, and release boundary.
• docs/evaluation-protocol.md: external validation protocol for comparing free-form AI output with Goal Forge output.
• examples/concept-design.md: the type of artifact this project optimizes for.
• examples/evaluation-cases/: seed cases for external validation runs.

Quick Start

Source Checkout

The repository remains source-checkout usable:

cd /Volumes/Data/workspace/goal-forge
npm ci
npm run production:check

Create a new run:

npm run init-run -- --goal "Design the v1 schema for a Codex Goal review workflow"

npm CLI

Install the published CLI with:

npm install -g @goalforge/cli
goalforge init --goal "Design the v1 schema for a Codex Goal review workflow" --out runs/demo
goalforge run runs/demo --rounds 1 --adapter local
goalforge validate runs/demo --strict

You can also run it without a global install:

npx @goalforge/cli init --goal "Design a compact task contract schema" --out runs/demo
npx @goalforge/cli run runs/demo --rounds 1 --adapter local
npx @goalforge/cli validate runs/demo --strict

The package exposes both command names:

• goalforge: primary command.
• goal-forge: compatibility alias.

The binary release targets:

• @goalforge/darwin-arm64 for macOS arm64.
• @goalforge/linux-x64 for Linux x64.

@goalforge/cli is a small wrapper package. npm installs the matching optional platform package for the current OS/CPU, then the wrapper runs its bin/goalforge binary.

Build and verify the local Bun binary candidate:

npm run binary:bun:check
./dist/goal-forge init --goal "Design a local binary smoke" --out runs/local-binary
./dist/goal-forge run runs/local-binary --rounds 1 --adapter local
./dist/goal-forge validate runs/local-binary --strict

Create a run from a file-backed workflow config:

npx tsx src/index.ts init --goal "Design a configured workflow" --config templates/goal-forge.config.json --out runs/configured

Validate a run:

npx tsx src/index.ts validate runs/<run-id>

validate has two modes:

• default mode checks required files and reports stop-condition failures as an advisory report; [error] labels inside that report are stop-check severity, not the command exit status;
• --strict fails when stop conditions do not pass, and is the mode intended for CI and release gates.

npx tsx src/index.ts validate runs/<run-id> --strict

Show the role model:

npm run explain

Run with the local adapter:

npx tsx src/index.ts run runs/<run-id> --rounds 1 --adapter local

Resume a blocked run after inspecting lastError and the ledger:

npx tsx src/index.ts status runs/<run-id>
npx tsx src/index.ts run runs/<run-id> --rounds 1 --resume

status includes a stop-condition summary. --resume is also required to intentionally add another round to a run that is already complete.

Run with the OpenAI Agents SDK adapter:

export OPENAI_API_KEY=sk-...
npx tsx src/index.ts run runs/<run-id> --rounds 1 --adapter openai

Optional settings:

• GOAL_FORGE_OPENAI_MODEL or --model <model> selects the SDK model.
• --max-turns <n> raises the SDK turn budget for complex structured-output runs; the default is 3.
• --role-timeout-ms <ms> aborts an individual role call.
• SDK traces are available in the OpenAI Traces dashboard; the adapter records provider, model, and trace ID in ledger/rounds.md.
• The adapter uses compact ledger context in prompts: open objections, accepted decisions, recent evidence, and summary counts.

Run with the Codex CLI adapter for repository-aware verification. --repo must resolve to an existing directory; absolute paths outside this checkout are supported:

npx tsx src/index.ts run runs/<run-id> --rounds 1 --adapter codex --repo /path/to/repo --model gpt-5.3-codex

The Codex adapter uses codex exec, read-only sandboxing, a JSON output schema, and --output-last-message. Default smoke tests use a fake command runner, so CI stays deterministic and does not require a logged-in Codex session. GOAL_FORGE_CODEX_MODEL or --model <model> selects the Codex model; if neither is set, the Codex CLI default is used.

Distribution Status

The npm distribution uses a wrapper package plus platform binary packages:

• @goalforge/cli exposes goalforge and goal-forge, and its bin points to scripts/npm-cli-wrapper.js;
• @goalforge/cli has a narrow files list so npm does not package source files, local runs, or coordination state;
• @goalforge/darwin-arm64 and @goalforge/linux-x64 each publish only bin/goalforge plus package metadata;
• @goalforge/cli depends on the platform packages through optionalDependencies;
• scripts/npm-cli-wrapper.js resolves the installed platform package first, with a source-checkout fallback to packages/<platform>/bin/goalforge for release smoke tests;
• npm run production:check builds both platform binaries, smokes the current-platform binary and wrapper, and checks package dry-run contents.

The npm naming plan is:

• @goalforge/cli: user-facing CLI package.
• goalforge: primary command name.
• goal-forge: compatibility command alias.
• @goalforge/core: future shared workflow/runtime library package.
• @goalforge/protocol: future shared protocol/template package.
• @goalforge/darwin-arm64: macOS arm64 prebuilt binary package.
• @goalforge/linux-x64: Linux x64 prebuilt binary package.

The scoped packages should be published in this order: platform binary packages first, then @goalforge/cli.

Build and verify the local Bun binary candidate:

npm run binary:bun:check

The binary smoke runs from a temporary directory and verifies init, validate, run --adapter local, strict validation, and status. Built-in templates are embedded for the default workflow so the binary does not require the source checkout's templates/ directory.

Why This Exists

Generic multi-agent systems usually focus on orchestration. This project focuses on the narrower thing that produced the quality gain: adversarial review pressure, traceable decisions, and artifact acceptance gates.

Future implementation work should deepen the same protocol rather than replace it: richer OpenAI guardrails/handoffs, per-role checkpoint resume, alternate storage backends, and UI surfaces are all downstream of the artifact/ledger contract.

Quality Gates

Role outputs support an explicit pass flag. A role should set pass: true when it found no actionable change and should omit empty role-specific arrays instead of inventing low-value objections, decisions, or evidence.

validate --strict includes deterministic quality metrics:

• artifact density and section coverage;
• ambiguity marker count;
• unresolved risk count by severity;
• accepted decision alignment;
• evidence confidence distribution.

Workflow config can override constrained section names and quality thresholds through constrainedSections and qualityThresholds in workflow.json / templates/goal-forge.config.json.

npm run smoke includes local run validation, adapter boundary checks, config validation, template/schema validation, a three-round deterministic workflow smoke, and evaluation:smoke.

npm run evaluation:smoke verifies the external validation protocol, scorecard, seed case pack, required task types, and external-domain case coverage without calling a model. It is part of npm run smoke.

npm run production:check is the release gate used by CI. It runs validate, typecheck, the full smoke chain, and the Bun binary smoke.

Additional focused checks:

npm run openai-adapter:smoke
npm run codex-adapter:smoke
npm run config:smoke
npm run agent-template:smoke
npm run evaluation:smoke

TypeScript

The project intentionally uses TypeScript source files instead of .mjs so the workflow contract can grow into typed adapters, schemas, evaluators, and trace metadata.

npm run typecheck

Agent Team

This project can be coordinated with agent-team-config. By default, deployed coordination files such as progress.md, tasks.md, .mailbox/, and .agents/state/ are local workspace state and are ignored by git.

For single-developer experimentation, keep that default. For multi-developer or CI-backed collaboration, decide explicitly which coordination files should be committed before relying on them across machines.