Agent Orchestrator by Brainoid™: An Opinionated Harness for More Reliable Coding Agents

Version: 0.3.2

Author: Pouya Baniasadi - https://pouya.ac

This Agent Orchestrator for coding agents is a portable AGENTS instruction system you copy into a repository so coding agents have clear startup rules, task-specific workflows, and optional project memory. It helps agents work for longer with fewer surprises by turning local expectations, risks, and decisions into instructions and records they can actually use.

It facilitates Agentic Engineering, as defined by Andrej Karpathy: not just having agents write code, but developing the expertise to orchestrate them toward high-quality, maintainable outcomes.

The central purpose of this harness is to keep coding agents inside workflows that make violations of the intended behavior much less likely.

Why Use This Harness

Use this harness when you want coding agents to make careful, maintainable changes instead of brittle, hard-to-review output. It is meant to make a repository easier to evolve under agent assistance, with clearer rules, better continuity, and less accidental damage.

What it improves:

• 🔁 Longer fully autonomous work: agent workflows are designed to plan and implement high-duration work. We have observed up to 500% longer autonomous runs when success is defined by objective feature requirements.
• ✅ Fewer AI mistakes: requirements, contracts, architecture maps, and high-level maps make intended behavior clearer, lowering the chance of unintended changes.
• 💸 Lower token costs: focused triggers direct agents to only the relevant areas. Architectural maps, high-level maps, saved architecture connections, and instructions that reduce unnecessary thinking without compromising thinking quality can reduce token cost by up to 85%.
• 🧱 Maintainable requirements context: project goals, setup choices, architecture expectations, and feature expectations can be written down and reused across sessions.
• 🛡️ Visible risks: vulnerabilities and security tradeoffs can be documented where future agents will see them.
• 🧪 Checkable architecture: architectural rules can become verifiable expectations instead of scattered tribal knowledge.
• 🧾 Traceable maintenance: issue, security, change, plan, and contract logs help agents trace previous mistakes and patch them more completely.

Set Up A Project

Copy the portable harness into the repository you want agents to work in:

cp -a AGENTS.md _AGENTS.d /path/to/your-project/

Then create the repo-local config from the example:

cd /path/to/your-project
cp _AGENTS.d/.env.AGENTS.example _AGENTS.d/.env.AGENTS

Edit _AGENTS.d/.env.AGENTS for that project. At minimum, set REPO_NAME. Then decide which optional systems should be active, such as _dev support, tracked issue/security/change records, contracts, multi-agent coordinator, or sanitized publishing.

You can also ask a coding agent to do this setup for you. A useful request is:

Install this AGENTS harness in this repository, create _AGENTS.d/.env.AGENTS
from the example, infer a safe REPO_NAME, and configure only the options that
fit this project.

Keep project-specific policy in _AGENTS.d/.env.AGENTS or below the marker in the target repository's AGENTS.md. The reusable instructions in _AGENTS.d/ should stay generic.

How It Guides Agents

At the start of a session, the agent reads AGENTS.md and runs:

./_AGENTS.d/agents-cli startup

That command tells the agent exactly which startup instructions to read. After startup, the agent does not load every workflow. It loads focused instruction topics only when the current request triggers them, keeping attention and token use tied to the work in front of it.

User-Triggered Capabilities

You can ask for these workflows directly. The agent will load the matching instructions and use the safer, more specific path for that kind of work.

Ask for	Capability	What it does	Why it helps
"Set up this AGENTS harness in this repo."	Project setup	Adds the portable AGENTS files, local config, and required ignores.	Starts a repo with the right startup and trigger behavior.
"Initialize or repair _dev folder."	Project memory setup	Creates or refreshes project requirements, high-level maps, plans, contracts, and record folders.	Gives agents durable context instead of making each session rediscover the repo.
"Build raw context" or "orient yourself first."	Raw Context Builder	Produces a fresh-start orientation and checks for branch or commit drift.	Helps a new session understand the repo before changing it.
"Use the proj-requirements to create a maximally autonomous dev-plan."	Autonomous Dev-plan creation	Assists in creating a _dev/dev-plan.md with clear phases and validation gates.	Uses proj requirements to create a concrete plan of maximally autonomous implementation and validation.
"Execute this dev-plan step."	Dev-plan execution	Follows an existing _dev/dev-plan.md step or range and records completed work.	Turns planned work into gated, auditable implementation.
"Create a tentative plan."	Raw Planning Helper planning work on a new branch	Converts rough brainstorming into a clear, verifiable plan. Or Makes risky or multi-step work easier to review before code changes.	Makes large or fuzzy work easier to execute without losing intent.
"Do this as shadow work" or "keep it untracked for now."	Untracked work	Uses an ignored temporary path before later integration.	Lets agents explore or prototype without dirtying tracked files.
"Set up sanitized publishing" or "explain sanitization.json."	Sanitization setup	Configures or explains clean public/exported publishing rules.	Helps publish safe output in a sanitized remote while keeping private/agentic (ex. in _dev or _AGENTS.d) development source-only material in an unsanitized remote .

More Detail

The root README is intentionally a user guide. For detailed module navigation, trigger registries, helper internals, and fallback files, see _AGENTS.d/README.md.

Current release: 0.3.2.