orch-agents

Summary — for non-technical readers

A team had a lot of knowledge about which task each AI should handle — but that knowledge lived only in a few developers’ heads. The moment one of those people went on vacation, the system stopped working well.

We built a text file that captures that criteria — and a system that reads it to decide what to do with each new task. Today any new person (or any new AI) can read it in five minutes and get up to speed. The knowledge stopped being fragile.

The diagnosis

“Every team has knowledge about which AI should handle which task. It lives in a single head — and breaks the moment work grows beyond that head.”

A GitHub repo with issues, code reviews, CI, and a Linear board generates dozens of decisions a day: review this change, fix this bug, investigate this failure, audit this security request. For most teams, that criteria lives in Slack threads and muscle memory. AI tools made it worse — now everyone has more decisions, not fewer, and nobody can describe why a given AI was the right one for a given task.

What we structured

A single text file anyone can read and review: WORKFLOW.md.

A text block that makes the criteria legible for both humans and machines:

templates:
  tdd-workflow:   [coder, tester]
  feature-build:  [architect, coder, reviewer]
  security-audit: [security-architect]

github:
  events:
    pull_request.opened:     github-ops
    issues.labeled.bug:      tdd-workflow
    workflow_run.failure:    quick-fix

agents:
  routing:
    bug:      tdd-workflow
    feature:  feature-build
    security: security-audit
    default:  quick-fix

Everything the organization knows about “which AI handles each situation” now lives in a file anyone can read, review, and compare version against version. The knowledge from one head, now in a file.

What we shipped

• 18+ AI roles ready — coder, reviewer, architect, security specialist, tester, and more
• Each AI in its own workspace — no stepping on each other’s work, no cross-contamination
• Human review before every important change — every change passes automated review (code, tests, security) before approval
• Works on the tools you already use — GitHub and Linear, not a separate platform
• Designed with safety in mind — visible permissions system, smart handling of long conversations, automatic retries, and a stop command accessible from any issue or review
• Ships two ways — as a ready-to-use service or as a library your team can integrate

Evidence

From v0.2.0 to v0.4.0 in four weeks. Milestones include:

• The system learns to use new tools as it needs them — replacing hard rules that were in the code
• A single entry point consolidated three paths into one — zero dead code
• WORKFLOW.md became the only source of truth, no config shortcuts
• Typed identifiers (PlanId, WorkItemId, ExecId, AgentSessionId) with audit findings applied

Changelog and commits are public — you don’t have to take our word for it.

What this proves

If you’ve already built something with Cursor, Bolt, or Lovable and you’re one “what did each AI do and why?” incident away from losing confidence in your code, this is what written knowledge, not lost actually means. Not a methodology — a file anyone can read.