Orch

Orch is a local-first control plane for deterministic AI coding.

Instead of treating the model as the owner of the development workflow, Orch treats the model as a bounded execution engine inside a runtime that Orch controls.

In one line:

Orch standardizes the coding workflow around the model, instead of trusting the model to invent the workflow.

That means:

• Orch owns planning
• Orch owns validation
• Orch owns testing
• Orch owns review
• Orch owns completion policy
• the LLM remains swappable

Core pipeline:

Task -> Task Brief -> Plan -> Execution Contract -> Code -> Validate -> Test -> Review -> Confidence -> Patch

The goal is not “let the model do whatever it wants”. The goal is to make AI coding structured, auditable, fail-closed, and less model-fragile.

GitHub one-screen pitch

• Structured planning before coding
• Explicit quality gates before completion
• Explainable runs with persisted artifacts

Why Orch?

Most AI coding tools still behave like this:

• the model decides the plan
• the model decides scope
• the model decides what to test
• the model decides whether the result is “good enough”

That creates inconsistent quality. Different models, prompts, or context windows can produce very different behavior for the same task.

Orch exists to reduce that variance.

It pushes the workflow into a runtime with:

• structured artifacts
• named validation gates
• bounded retries
• review rubric enforcement
• confidence-based completion decisions
• persistent run history for audit and explanation

So the product promise is not “magic autonomous coding”. It is more disciplined AI coding with clearer quality control.

Product Positioning

Orch = control plane

Orch is responsible for:

• normalizing the task
• compiling a structured plan
• building an execution contract
• enforcing scope boundaries
• running validation gates
• running tests
• scoring review quality
• computing confidence
• deciding whether a run can complete
• persisting artifacts for audit and explanation

LLM = replaceable execution engine

The model is responsible for:

• producing a patch inside Orch’s constraints
• responding to retry directives
• contributing review text signals

But the model is not the workflow owner.

That distinction is the whole product thesis.

How Orch differs from agentic coding tools

| Topic | Typical agentic coding tool | Orch | |---|---|---| | Workflow owner | Usually the model | Orch runtime | | Planning | Often prompt-shaped, model-led | Structured, Orch-owned artifact | | Scope control | Soft guidance | Explicit execution contract + scope guard | | Validation | Often ad hoc | Named validation gates | | Testing | Best effort | Required test-stage gates | | Review | Free-form model opinion | Rubric + Orch decision layer | | Completion | “Patch exists” is often enough | Review + confidence policy must pass | | Explainability | Mostly chat transcript | Persisted run artifacts + orch explain | | Telemetry | Limited | orch stats over run artifacts | | Model swap impact | Can significantly change behavior | Process stays more stable by design |

What Orch Does Today

Current implemented foundations include:

• structured task brief generation
• structured planning
• orch plan --json
• execution contract generation
• scope guard / allowed-file enforcement
• patch hygiene + plan compliance validation
• test-stage gates
• review rubric engine
• confidence scoring
• confidence enforcement policy
• test failure classification
• bounded retry directives
• SQLite-backed project / session / run persistence
• explainability via orch explain
• telemetry via orch stats

This means Orch already behaves more like a quality-enforcing runtime than a simple prompt wrapper.

Best fit for

Orch is a better fit when you want:

• a repeatable CLI workflow instead of agent improvisation
• explicit quality gates before completion
• persistent run artifacts for audit/debugging
• a system that can keep its process discipline even if the model changes

It is a worse fit if your main goal is fully free-form, conversational, unconstrained agent behavior.

How Orch Works

A run is not considered successful just because a patch exists.

A healthy run should look like this:

1. Orch normalizes the task into a structured brief
2. Orch compiles a plan with acceptance criteria and constraints
3. Orch builds an execution contract for the coder
4. The coder produces a bounded patch
5. Orch validates patch integrity and scope compliance
6. Orch runs required tests
7. Orch evaluates the result with a review scorecard
8. Orch computes confidence from objective signals
9. Orch either:
   • completes,
   • requests revision, or
   • fails closed

This is the core difference between Orch and “agent just edited some files”.

Key Concepts

Structured planning

Orch generates and persists a structured TaskBrief and Plan instead of relying only on raw model text.

Execution contract

The coder works inside an explicit contract:

• allowed files
• inspect files
• required edits
• prohibited actions
• acceptance criteria
• invariants
• patch budget

Validation gates

Each important quality check becomes a named gate, such as:

• patch_parse_valid
• patch_hygiene
• scope_compliance
• plan_compliance
• required_tests_executed
• required_tests_passed
• review_scorecard_valid
• review_decision_threshold_met

Review rubric

Review is not just free-form commentary. Orch computes a structured scorecard over:

• requirement coverage
• scope control
• regression risk
• readability
• maintainability
• test adequacy

Confidence enforcement

Confidence is not only displayed. It can actively affect completion behavior.

Default policy:

• score >= 0.70 -> completion can proceed
• 0.50 <= score < 0.70 -> revise
• score < 0.50 -> fail

Installation

Global install via npm:

npm i -g orch-code

Installer behavior:

• first tries to download a prebuilt release binary for your platform
• falls back to go build if no release asset is available and Go is installed locally

Published release assets are expected to look like this:

• orch-darwin-arm64
• orch-darwin-x64
• orch-linux-arm64
• orch-linux-x64
• orch-windows-arm64.exe
• orch-windows-x64.exe

Requirements for source-build fallback:

• Go 1.25+

Build:

go build -o orch .

Run without building:

go run . <command>

Release Flow

npm i -g orch-code becomes zero-Go for end users once GitHub Releases and npm publish are both live.

Canonical GitHub repo:

• https://github.com/beydemirfurkan/orch

Repo automation now expects:

• GitHub Actions secret: NPM_TOKEN
• a git tag in the form vX.Y.Z
• package.json, package-lock.json, and cmd/version.go to already match that version

Release steps:

# update versions first
npm run release:prepare -- 0.1.0

# or bump semver automatically
npm run release:patch
npm run release:minor
npm run release:major

# or also create the git tag locally
npm run release:prepare -- 0.1.0 --tag

# push when ready
git tag v0.1.0
git push origin v0.1.0

The release workflow will:

• run go test ./...
• verify the tag matches package metadata
• build darwin/linux/windows binaries with GoReleaser
• publish a GitHub Release with raw binary assets
• publish the npm package if that version is not already on npm
• run clean install smoke tests on macOS and Linux using npm install -g orch-code

Recommended publish path:

• treat tag push as the canonical release path
• avoid manual npm publish during normal releases
• keep manual npm publish only as a recovery path if CI is unavailable

release:prepare updates these files together:

• package.json
• package-lock.json
• cmd/version.go

By default it also refreshes CHANGELOG.md from git commit subjects since the last tag.

If you prefer make targets:

make release-patch
make release-minor
make release-major
make release-prepare VERSION=0.1.1
make release-prepare VERSION=0.1.1 TAG=--tag
make changelog VERSION=0.1.1

Quick Start

Initialize Orch in a repository:

./orch init

Set up provider auth. API key mode:

export OPENAI_API_KEY="your_api_key"
./orch auth login openai --method api

Or account mode (OAuth):

./orch auth login openai --method account --flow auto
./orch auth login openai --method account --flow auto   # add another account
./orch auth list
./orch auth use <credential-id>
./orch auth remove <credential-id>

When multiple OpenAI OAuth accounts are stored, Orch keeps one active account and can fail over to the next local account when the active one is rate-limited or rejected.

Validate runtime readiness:

./orch doctor
./orch doctor --probe

--probe runs a small live OpenAI chat check, which is useful for validating account-mode OAuth auth beyond local token shape checks.

Generate a structured plan only:

./orch plan "add redis caching to user service"
./orch plan "add redis caching to user service" --json

Run the full pipeline:

./orch run "add redis caching to user service"

Explain the latest run:

./orch explain

Show quality stats across recent runs:

./orch stats
./orch stats --limit 100

Inspect and apply the latest patch:

./orch diff
./orch apply
./orch apply --force --approve-destructive

Interactive Mode

Start interactive mode:

./orch

Important behavior:

• plain text goes to chat mode
• /plan ... runs structured planning
• /run ... runs the full pipeline

So typing something like:

selam

does not start the coding pipeline. It is treated as chat.

Useful interactive commands:

/help
/plan add health endpoint
/run fix auth timeout bug
/logs
/explain
/stats
/session current

Command Surface

Core workflow

./orch init
./orch plan "task"
./orch run "task"
./orch diff
./orch apply
./orch logs [run-id]
./orch explain [run-id]
./orch stats --limit 50

Sessions

./orch session list
./orch session create feature-auth
./orch session create feature-auth --worktree-path ../orch-feature-auth
./orch session select feature-auth
./orch session current
./orch session runs feature-auth --status completed --contains auth --limit 20
./orch session close feature-auth

Provider and auth

./orch auth login openai --method api
./orch auth login openai --method account --flow auto
./orch auth list
./orch auth status
./orch auth logout openai
./orch provider
./orch provider list
./orch provider list --json
./orch provider set openai
./orch model
./orch model set coder gpt-5.3-codex
./orch doctor

Persistence and Auditability

Orch persists runtime state under .orch/.

Important files:

• .orch/config.json
• .orch/repo-map.json
• .orch/orch.db
• .orch/runs/<run-id>.state
• .orch/latest.patch
• .orch/latest-run-id

Artifacts stored per run can include:

• task
• task brief
• plan
• execution contract
• patch
• validation results
• retry directive
• review result
• review scorecard
• confidence report
• test failure classifications
• logs

This persistence is what powers orch explain and orch stats.

Safety and Quality Model

Orch is designed to be fail-closed by default.

Safety / quality behaviors include:

• read-only planning behavior
• destructive apply approval
• repository lock per execution root
• bounded retries
• structured validation gates
• explicit review decisioning
• confidence-based completion policy

Example safety config:

{
  "safety": {
    "dryRun": true,
    "requireDestructiveApproval": true,
    "lockStaleAfterSeconds": 3600,
    "retry": {
      "validationMax": 2,
      "testMax": 2,
      "reviewMax": 2
    },
    "confidence": {
      "completeMin": 0.70,
      "failBelow": 0.50
    },
    "featureFlags": {
      "permissionMode": true,
      "repoLock": true,
      "retryLimits": true,
      "patchConflictReporting": true,
      "confidenceEnforcement": true
    }
  }
}

Architecture

Runtime at a glance

User Task
   |
   v
Task Brief / Normalizer
   |
   v
Structured Plan
   |
   v
Execution Contract
   |
   v
LLM Worker (planner/coder/reviewer as bounded roles)
   |
   v
Validation Gates -> Test Gates -> Review Rubric -> Confidence Policy
   |
   v
Run Decision: complete / revise / fail
   |
   v
Persistence + Explainability + Telemetry
(.orch/orch.db, .orch/runs/*.state, orch explain, orch stats)

Main runtime areas:

• cmd/ - CLI surface
• internal/orchestrator/ - run state machine and pipeline enforcement
• internal/planning/ - task normalization and structured planning helpers
• internal/execution/ - execution contracts, scope guard, plan compliance, retry directives
• internal/review/ - rubric-based review engine
• internal/confidence/ - scoring and enforcement policy
• internal/testing/ - test failure classification
• internal/patch/ - patch parse, validate, apply
• internal/tools/ - guarded tool execution policies
• internal/storage/ - SQLite-backed persistence
• internal/runstore/ - persisted run-state files for explainability/telemetry

Product Direction

The long-term direction is:

Orch should standardize the software delivery workflow around the model. The model should not define the workflow.

Put differently:

• Orch should own planning
• Orch should own validation
• Orch should own testing
• Orch should own review
• Orch should own completion policy
• the LLM should remain swappable

This is why the project is better described as:

Control Plane for Deterministic AI Coding

not simply “an AI coding agent”.

Roadmap and Specs

Key docs:

• Product requirements: docs/PRD.md
• System roadmap: docs/SYSTEMATIC_CODING_ROADMAP.md
• Implementation tasks: docs/IMPLEMENTATION_TASK_LIST.md
• Quality system: docs/QUALITY_SYSTEM_SPEC.md
• Planning engine: docs/PLANNING_ENGINE_SPEC.md
• Execution contract: docs/EXECUTION_CONTRACT_SPEC.md
• Confidence policy: docs/CONFIDENCE_ENFORCEMENT_POLICY.md
• Explain command: docs/EXPLAIN_COMMAND_SPEC.md
• Stats command: docs/STATS_COMMAND_SPEC.md
• Progress log: docs/IMPLEMENTATION_PROGRESS.md
• Sprint board: docs/SPRINT_BOARD_90_DAY_PLAN.md

Development

Run tests:

go test ./...

Contributing

Please read CONTRIBUTING.md before opening a pull request.

License

This project is licensed under the MIT License. See LICENSE.