oowl

Overview

The backstory

Claude Code and its proprietary models are great tools. They unblock developers and accelerate real work. But they've become expensive and increasingly restricted. Token limits. Session limits. Rate limits.

I started looking for alternatives. A lot of open-weight models match proprietary ones on SWE-Bench. DeepSeek Pro at 1M tokens costs $0.10. GPT-4 costs $10. Two orders of magnitude.

Then I found OpenCode. It's model-agnostic, connects to anything. OpenCode Go gives you roughly 16,000 requests/month for $5 on request-based pricing. GitHub Copilot caps at 1,500 for more money. The math was obvious.

Once model-switching was available, the real problem came into focus: same model for everything. You're paying Opus rates to write a test scaffold or a routing comment. The solution was to route different agents to different cost tiers: cheap models for cheap work, stronger models only where the quality delta matters.

oowl is the workflow layer that makes that practical. Role-specific agents, cost-tiered profiles, a structured design → plan → review process built on top of Superpowers, with Caveman-Lite keeping inter-agent chatter token-efficient.

Quick start

Prerequisites: OpenCode installed and configured, Node.js 18+.

npx @jimzandueta/oowl init

opencode

The three commands

npx @jimzandueta/oowl init      # first-time setup wizard
npx @jimzandueta/oowl profile   # switch model profiles interactively
npx @jimzandueta/oowl update    # update framework files with conflict detection

What you get

How it works

Why this instead of one big agent

Trivial-fix fast path

A request skips the full workflow when all of these are true:

• Under ~20 lines, under 3 files
• No auth, IAM, payments, PII, secrets, or production config touched
• No new dependency introduced
• No architectural decision required

Trivial work goes directly to one implementation agent with a complete task prompt and verification requirements. You can also tell dispatcher explicitly: "this is a trivial fix, skip the design phase."

Protocol signals

Agents don't pass work through freeform chat. Every handoff is a named, structured block with required fields. That's what keeps the workflow machine-readable and stops agents from going off-script.

How signals flow

Signal reference

TRIVIAL_FIX_DISPATCH
Justification:
- under ~20 lines and under 3 files
- no sensitive area touched
- no new dependencies
- no architectural decision required
Target agent: <agent-name>
Task prompt: |
  <complete prompt>
Files: <expected files>
Verification: <required checks>

PHASE_COMPLETE
Phase: <design | implementation-spec | build | review | ui-spec>
Summary: <summary>
Artifacts:
- <file created or modified>
Next phase: <user-design-approval | user-implementation-approval | plan-reviewer | build | review | done>
Risks: <remaining risks>
Verification:
- <checks performed or required>

PLAN_APPROVED
Summary: <why this plan is executable>
Next phase: user-implementation-approval
Risks: <remaining risks>
Verification: <expected verification>

PLAN_REJECTED
Issues:
- <BLOCKER or WARNING>: <issue>
Required changes:
- <specific fix>
Return to: planner

REQUEST_CONSULT
Target agent: <agent-name>
Task ID: <task id, if any>
File locks:
- <path>
Task prompt: |
  <complete prompt dispatcher should send directly>
Expected output: <expected result>
Verification requirements:
- <check>
Subagent summary: <current state>

REQUEST_CONSULT_BATCH
Max parallel: 3
Wave: <wave id>
Parallel group: <group id>
Atomic dispatch required: yes
Tasks:
- Target agent: <agent-name>
  Task ID: <task id>
  File locks:
    - <path>
  Task prompt: |
    <complete prompt>
  Expected output: <expected result>
  Verification requirements:
    - <check>
  Reason parallel-safe: <reason>
Subagent summary: <why this batch is safe>

TASK_COMPLETE
Task ID: <task id>
Files changed:
- <file>
Verification:
- <command/result>
Risks:
- <risk or none>
Notes:
- <brief note>
Protected artifacts:
- confirmed docs/specs/** unchanged and present

NEEDS_USER_INPUT
Question: <one clear question>
Why needed: <brief reason>
Default if unanswered: <safe default>
Subagent summary: <brief summary>

ESCALATION_REQUEST
Target agent: <high-engineer | high-architect | high-designer | security-auditor>
Why cheaper agents are insufficient: <reason>
What was attempted: <summary>
Specific output needed: <decision or deliverable>
Risk if wrong: <impact>

ESCALATION_COMPLETE
Reason escalation was justified: <reason>
Result: <summary>
Files changed or decisions made:
- <item>
Verification:
- <command/result or recommended check>
Remaining risks:
- <risk or none>

REVIEW_COMPLETE
Summary: <summary>
Findings:
- <finding count by severity>
Blocking issues: <yes/no>
Verification gaps:
- <gap or none>

PARALLEL_DISPATCH_FAILED
Reason: <why concurrent dispatch was not possible>
Fallback proposed: <serial execution | smaller batch | user decision>

PROTECTED_ARTIFACT_MISSING
Missing:
- <path>
Last task or batch: <summary>
Required action: restore from git or snapshot before continuing

git checkout -- docs/specs/<feature>/design.md

Agents

23 agents across 6 classes. All files live in framework/agents/ and are copied to .opencode/agents/ on install.

Orchestration

dispatcher classifies requests and routes them. Only dispatcher may invoke implementation agents via Task. builder is scheduler-only: no file edits, no shell, no Task calls.

Artifact owners

Implementation

Review

Escalation

Low-tier bounded

Model profiles

Profiles assign models to agent tiers. Switch anytime with oowl profile.

Bundled profiles (OpenCode Go)

Custom profile (no OpenCode Go needed)

oowl init and oowl profile → custom scan your connected OpenCode models and let you assign them to cheap/mid/premium tiers. If fewer than 3 models are detected, you can enter model IDs manually.

Balanced profile: current mapping

Model availability changes. Profiles are editable defaults, not permanent benchmarks.

Plugins

opencode.jsonc loads two plugins out of the box:

"plugin": [
  "superpowers@git+https://github.com/obra/superpowers.git",
  "caveman@git+https://github.com/juliusbrussee/caveman.git"
]

Install

oowl init

npx @jimzandueta/oowl init

Prompts for install location, model setup, and conflict handling. Local installs write opencode.jsonc and AGENTS.md to your project root. Global installs use ~/.config/opencode/.

oowl profile

oowl profile

Updates model assignments across all 23 agent files, opencode.jsonc, and profile-models.json.

oowl update

oowl update

Updates framework files to the latest package version. Files you haven't modified update silently. Modified files show a unified diff. Keep yours or accept the update, per file.

Uninstall

# local install
rm -rf .opencode opencode.jsonc AGENTS.md .oowl.json

# global install
rm -rf ~/.config/opencode ~/.oowl.json

Customizing

Edit an agent prompt

Agent files live in .opencode/agents/ (local) or ~/.config/opencode/agents/ (global). Edit directly for immediate effect. When oowl update runs and detects the change, choose "keep mine" to preserve it.

Add an agent

1. Add a .md file under the right class in framework/agents/
2. Add the agent to every profile JSON under agent_order and agents
3. Update framework/agents/README.md
4. Add a command file in framework/commands/ if needed
5. Run oowl profile to verify it appears in the model strategy

Change workflow rules

Add a custom profile

cp framework/model-profiles/balanced.json framework/model-profiles/my-profile.json
# edit my-profile.json with your model assignments
bash scripts/apply-profile-models.sh framework/model-profiles/my-profile.json

Common issues

ls .opencode/agents   # should list agent subdirs
ls opencode.jsonc     # should exist

npm bin -g   # shows the path to add

git checkout -- docs/specs/<feature>/design.md

git add docs/specs
git commit -m "chore: preserve approved specs for <feature>"

Contributing

Before opening a PR, run:

# Node tests
npm test

# CLI smoke tests
node bin/oowl.js --help
node bin/oowl.js foobar; echo "exit: $?"   # should exit 1

# Profile JSON validation
for f in framework/model-profiles/*.json framework/profile-models.json; do
  node -e "JSON.parse(require('fs').readFileSync('$f','utf8'))" && echo "OK: $f"
done

# npm pack check
npm pack --dry-run

Keep these intact:

• dispatcher owns dispatch: only it invokes Task
• builder schedules only: no file edits, no shell, no Task
• Protected artifacts remain owner-controlled
• Implementation tasks require file locks
• Verification evidence required before TASK_COMPLETE
• Sensitive flows require explicit approval and stricter routing
• Caveman-Lite stays limited to runtime communication, not artifacts or code

See CONTRIBUTING.md for the full process.