README · Architecture · Agents · Skills & Commands · Plugins

TypeScript + Bash orchestration that runs AI agents — Ollama for code generation, Claude for planning and triage — in parallel, in dependency order.

How it works

/implement triggers a multi-step pipeline. Claude handles triage and planning; the TypeScript orchestrator runs Ollama agents in dependency order; Claude applies the generated output.

Step 0   Triage      Claude reads graph.json (BFS depth=2), writes triage_ts.md
Step 1   Plan        Parallel Claude planners write task_context_<domain>.md
Step 1.5 Orchestrate npm start runs Ollama agents in dependency order,
                     writes ollama_output_<domain>.md
Step 2   Code        Parallel Claude coders apply ollama_output_<domain>.md,
                     write coder_output_<domain>.md
Step 2.5 Pre-review  Standards compliance check
Step 3   Build       npx tsc --noEmit
Step 4   Review      Fast review per file; deep review for flagged files
Step 5   Fix loop    Max 3 rounds, circuit breaker on repeat errors
Step 6   Finalize    git diff + track savings

scripts/run_pipeline.sh wraps steps 1–3 into a single non-interactive script. Pass a task description and it runs triage, parallel planning, and the TS orchestrator in sequence without any Claude interaction required.

Agents communicate through files in .claude/context/. Each step reads file paths from the previous step, not the full content.

Self-learning loop

After every pipeline run the orchestrator records what happened and uses it to improve future reviews automatically.

Pipeline run
  └─► capture-outcome.sh      ──► knowledge/outcomes.jsonl
        │  (task, verdict, reviewer_issues, model, duration)
        │
        ├─► embed-outcomes.sh  ──► knowledge/embeddings.jsonl
        │     (mxbai-embed-large via Ollama, runs in background)
        │
        └─► learn.sh --apply   ──► skills/discovered/<type>-<date>.md
              (auto-triggered every 10 outcomes)

Script	What it does
`capture-outcome.sh`	Appends one JSON record per run: task, verdict, files changed, reviewer issues, model, duration
`embed-outcomes.sh`	Generates Ollama vector embeddings for each outcome; skips already-embedded records
`semantic-search.sh`	Cosine-similarity search over `embeddings.jsonl`; returns top-k similar past outcomes
`learn.sh`	Finds recurring reviewer issues (≥ 3 occurrences), calls Ollama reviewer to draft a skill amendment, writes it to `skills/discovered/`

Every 10 captured outcomes learn.sh --apply fires automatically (background, no blocking). Discovered amendments land in skills/discovered/ and are picked up by the reviewer on the next run.

Run manually:

# Dry-run: print proposed amendments without writing files
bash scripts/learn.sh

# Apply: write amendments to skills/discovered/
bash scripts/learn.sh --apply

# Query: find issues similar to a specific task description
bash scripts/learn.sh --query "add authentication middleware"

# Semantic search standalone
bash scripts/semantic-search.sh --query "TypeScript type errors" --top-k 3

Source layout

src/
  types/index.ts          AgentDomain, KNOWN_DOMAINS, Role, AgentTask,
                          AgentResult (done|skipped|failed|blocked), TriageResult
  agents/
    AgentRunner.ts        Wraps call_ollama.sh via spawn; 5 min timeout; 10 MB output limit
    TriageAgent.ts        BFS depth=2 on graph.json; writes triage_ts.md; CLI via import.meta.url
  core/
    DependencyGraph.ts    Kahn topological sort; duplicate domain detection
    Orchestrator.ts       Reads task_context_<domain>.md; circuit breaker for failed deps;
                          reviews ollama_output_<domain>.md after all domains complete
    BuildChecker.ts       Runs npx tsc --noEmit; returns pass/fail with stderr
    DiffCompressor.ts     Strips lock files, collapses blanks, truncates long hunks
    FileWriter.ts         Parses %%FILE...%%ENDFILE blocks from Ollama output; writes to disk
    TriageRouter.ts       Reads triage_ts.md and extracts the chosen TriageRoute
  cli/
    commit.ts             npm run ao-commit — calls local-commit.sh via spawn
    review.ts             npm run ao-review — runs reviewer agent on current diff
    stats.ts              npm run ao-stats  — prints token savings summary
    update.ts             npm run ao-update — pulls latest orchestrator version
  mcp/
    server.ts             MCP HTTP server (default port 3456); exposes get_stats,
                          triage_task, and run_ollama tools to Claude
  index.ts                CLI entry point

Domain dependencies

Domain	Depends on
`coder`	(none)
`unit-tester`	`coder`
`doc-writer`	`coder`
`devops`	`coder`, `unit-tester`, `doc-writer`

Domains within the same dependency level run concurrently. If a domain fails, its dependents are marked blocked and skipped.

Requirements

Node.js 20+ with tsx
Claude Code CLI
Ollama installed and running
jq
Python 3 with graphify package (optional, for knowledge graph updates)

Installation

Two commands:

git clone https://github.com/Mybono/ai-orchestrator ~/Projects/ai-orchestrator
~/Projects/ai-orchestrator/scripts/install.sh

Or one:

curl -sSL https://raw.githubusercontent.com/Mybono/ai-orchestrator/main/scripts/install.sh | bash

install.sh:

installs Node.js, tsx, and Ollama
installs codebase-memory-mcp globally and registers it in ~/.claude/.mcp.json
creates symlinks from ~/.claude/ into the repo

A git pull in the repo directory updates all tooling immediately.

Index each client project once (run in the root of the target repo):

npx codebase-memory-mcp index --project <repo-name> --root .

After indexing, the planner uses the knowledge graph for structural queries instead of grep — ~500 tokens vs ~80K per lookup.

Configuration

Model routing is controlled by llm-config.json in the repo root:

{
  "models": {
    "coder":        "qwen3:32b-q4_K_M",
    "reviewer":     "qwen3:32b-q4_K_M",
    "pre-reviewer": "qwen3:8b",
    "debugger":     "qwen3:32b-q4_K_M",
    "devops":       "qwen3:8b",
    "quick-coder":  "qwen3:8b",
    "commit":       "qwen2.5-coder:7b",
    "triage":       "qwen3:8b",
    "embedding":    "mxbai-embed-large"
  },
  "free_api_url": "http://localhost:3001/v1/chat/completions",
  "free_api": {
    "planner":      "qwen/qwen3-32b",
    "coder":        "qwen3-coder-next",
    "reviewer":     "auto",
    "pre-reviewer": "auto",
    "debugger":     "qwen3-coder-next",
    "devops":       "auto",
    "quick-coder":  "qwen3-coder-next",
    "commit":       "auto",
    "triage":       "auto"
  },
  "cerebras_api": {
    "coder":        "gpt-oss-120b",
    "reviewer":     "gpt-oss-120b",
    "pre-reviewer": "gpt-oss-120b",
    "debugger":     "gpt-oss-120b",
    "devops":       "gpt-oss-120b",
    "quick-coder":  "gpt-oss-120b",
    "commit":       "gpt-oss-120b",
    "triage":       "gpt-oss-120b"
  },
  "fallback": {
    "coder":        "claude-sonnet-4-6",
    "reviewer":     "claude-sonnet-4-6",
    "pre-reviewer": "claude-haiku-4-5-20251001",
    "debugger":     "claude-sonnet-4-6",
    "devops":       "claude-haiku-4-5-20251001",
    "quick-coder":  "claude-haiku-4-5-20251001",
    "commit":       "claude-haiku-4-5-20251001",
    "triage":       "claude-haiku-4-5-20251001",
    "embedding":    ""
  },
  "cloud_first_roles": ["planner", "reviewer", "debugger"]
}

Routing follows a 4-tier provider chain. Roles listed in cloud_first_roles (planner, reviewer, debugger) try Cerebras first, then FreeLLM, then Ollama, then Claude. All other roles start with Ollama, then fall through FreeLLM, Cerebras, and finally Claude. Changing a model name takes effect immediately — no restart needed. See Architecture for details.

Development

npm run build                                    # compile TypeScript
npm run typecheck                                # tsc --noEmit, no output files
npm start "coder,unit-tester"                    # run TS orchestrator for given domains
npx tsx src/agents/TriageAgent.ts "<task>"       # run triage standalone

npm run ao-commit                                # generate commit message via Ollama and commit
npm run ao-review                                # review current diff with reviewer agent
npm run ao-stats                                 # print token savings (day/week/month)
npm run ao-update                                # pull latest orchestrator version
npm run ao-mcp                                   # start MCP server on port 3456

bash scripts/run_pipeline.sh "<task description>"  # run full pipeline autonomously

License

MIT