oowl

OpenCode Opinionated Workflow Layer

oowl brings structured software engineering process to AI-assisted development on OpenCode. Instead of a single agent designing, coding, and reviewing in one session, it routes work through specialized roles with file locks, mandatory verification, and durable design artifacts.

Why oowl

oowl treats AI coding less like one heroic chat session and more like a small engineering process. Four benefits, each with what you gain and what you skip:

Six features that ship those benefits:

How it works

A dispatcher reads your request, picks a tier, and routes to the right agent. Substantial work goes through design, plan, and review gates that you sign off on before any code ships.

Get started · How it works in detail · GitHub · npm

Quick start

Install the framework, open OpenCode, tell dispatcher what to build. Three steps to your first feature.

Prerequisites: OpenCode installed, Node.js 18+.

npx @jimzandueta/oowl install

opencode

You: "Add a login page with email/password and Google OAuth."

Dispatcher → Architect → [you approve design]
          → Planner → Plan-reviewer → [you approve plan]
          → Builder schedules → agents implement
          → Reviewer → [merge to main?]

Commands

What you get

The full feature list at a glance: file locks, approval gates, persistent artifacts, 23 agents, model profiles, and more.

How it works

The full workflow from request to design to implementation to review. Read this to understand what oowl actually does — every other section references it.

Artifacts

Every substantial feature produces files under docs/specs/<feature>/:

docs/specs/login-page/
├── design.md           # architect: approach, tradeoffs, risks
├── ui-spec.md          # designer: layout, interactions (if UI involved)
├── implementation.md   # planner: task breakdown, file locks, verification
└── review.md           # reviewer: what shipped, test results, risks

Each artifact is owned by a specific agent. Non-owners can read them but cannot edit, delete, or overwrite them.

Tasks

Planner decomposes the feature into tasks. Each task declares exactly which files it touches:

Task: Add login form component
Agent: frontend-engineer
Files: src/components/LoginForm.tsx, src/components/LoginForm.test.tsx
Verification: npm run typecheck && npm test -- --testPathPattern=LoginForm

Parallel tasks are checked for file collisions. If two tasks touch the same file, they run sequentially.

Tiers

Agents map to three model cost levels:

Switch between bundled profiles (low default, balanced, high, free) or build a custom one with oowl profile.

Review

After implementation, reviewer writes a review covering what was built, test results, verification evidence, risks, and readiness. It can also route to security-reviewer for sensitive areas or security-auditor for deep dives — threat modeling, auth flows, IAM, compliance.

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
• No new feature behavior or test-writing work required

You can also tell dispatcher explicitly: "this is a trivial fix, skip the design phase."

Security model

Sensitive areas that require explicit user approval:

• Secrets, credentials, API keys, certificates, signing keys
• PII and customer data
• Payment processing and regulated financial flows
• Authentication and authorization logic
• IAM policies and access-control configuration
• Production infrastructure and production configuration
• Destructive database migrations on production-shaped data
• Compliance-bound data (HIPAA, GDPR, PCI, SOC 2)
• Cryptography, sessions, tokens, signing

If a task touches any of these, the agent stops with NEEDS_USER_INPUT. Low-tier agents also return ESCALATION_REQUEST so a capable model handles the sensitive work.

What oowl does not guarantee

• File locks are workflow contracts, not OS-level ACLs — agents can still make mistakes
• Model profiles are defaults, not pricing guarantees or benchmarks
• oowl does not replace CI, branch protection, code owners, secret scanning, or human review

Guardrails

Task-class assignment

Not every task needs a senior implementer. oowl classifies each implementation.md task as mechanical or behavior-changing and routes accordingly.

Protocol signals

The structured handoffs between agents. Every signal has a name, required fields, and a clear sender/receiver. Click any signal below to see its full format.

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.

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, with permission boundaries and Superpowers usage rules. Use this as a reference when customizing prompts or adding new agents.

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

Orchestration

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

Permission boundaries

All agents can read, list, and search files for context. Artifact owners can write only their owned files under docs/specs/. Implementation and escalation agents can ask to edit scoped work files but cannot modify docs/specs/** or AGENTS.md. Dispatcher's protected-file denies stay narrow so implementation agents launched through Task keep their edit tools.

Artifact owners

Implementation

Review

Escalation

Low-tier bounded

Model profiles

Profiles assign models to cost tiers. The default profile is low. Switch anytime with oowl profile. Use bundled profiles for OpenCode Go, use free for free OpenCode models, or build a custom one from your connected models.

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

Bundled profiles

Custom profile (no OpenCode Go needed)

oowl install 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.

Plugins

OpenCode plugins oowl loads by default: Superpowers (TDD, brainstorming, debugging) and Caveman (signal-dense compression).

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

Three install paths: interactive walkthrough, scripted shell for CI/CD, and npm + npx for one-off use. Pick what fits your environment.

Primary: npm + walkthrough

npm install -g @jimzandueta/oowl
oowl install

The walkthrough asks: local vs global install, model profile, and overwrite confirmation. The default profile is low. Local installs write framework files under .opencode/, plus AGENTS.md and .oowl.json to the project root.

Prefer not to install the CLI permanently?

npx @jimzandueta/oowl install

Scripted: install.sh

For CI/CD, Dockerfiles, or automation:

bash install.sh --global
bash install.sh --project /path/to/project --force
bash install.sh --project /path/to/project --dry-run

oowl init

See the Optional skills section below — it covers the full oowl init flow, skill sources, and commands.

oowl profile

oowl profile
oowl profile free
oowl profile low
oowl profile balanced
oowl profile high

The free profile uses free OpenCode models. free-data will be used in training, so do not use it for private, proprietary, regulated, customer, or confidential data.

oowl update

oowl update

Updates framework files to the latest package version. Modified files show a unified diff — keep yours or accept the update. Old files no longer shipped are removed. Reapplies active profile and saved Optional skills.

Uninstall

# local
bash uninstall.sh --project
bash uninstall.sh --project /path/to/project

# global
bash uninstall.sh --global

Add --dry-run to preview. Add --keep-project-files to keep AGENTS.md, .oowl.json, and legacy opencode.jsonc.

Optional skills

Beyond the required skills bundled with oowl, add Optional skills via oowl init. Three community repos, quality-gated, configurable per project.

Required skills (TDD, brainstorming, writing-plans, verification) ship with oowl. Optional skills are community-built workflows that agents load at session start — design taste, deployment pipelines, architecture patterns, and more.

How it works

oowl init

Skill sources

Optional skills come from three community repositories:

Each skill in the registry passes a quality gate (star count threshold) before it's eligible for recommendation. The wizard only suggests gated skills.

Commands

Customizing

How to edit agents, add new agents, change workflow rules, add slash commands, set project conventions, and adjust model profiles.

Edit an agent prompt

Agent files live in .opencode/agents/ (local) or ~/.config/opencode/agents/ (global). Edit directly for immediate effect. When oowl update 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

Add a slash command

Add a .md file under the appropriate class in framework/commands/. Installed commands are flattened into .opencode/commands/.

Add project conventions

Engineering prompt files define project conventions that implementation agents load:

framework/prompts/engineering/code-conventions.md  — naming, imports, formatting
framework/prompts/engineering/file-structure.md    — directory layout, file naming
framework/prompts/engineering/tool-preferences.md  — preferred libraries, banned tools
framework/prompts/engineering/error-handling.md    — error envelopes, logging, retry

Edit these files with your project's conventions. Implementation agents load them automatically.

Repository layout

bin/
  oowl.js                       CLI entry point

src/
  cli.ts                        command router
  commands/
    install.ts                  oowl install walkthrough
    init.ts                     Optional skills configuration
    profile.ts                  oowl profile wizard
    update.ts                   oowl update with checksum diffing
  lib/
    installer.ts                file copy and .oowl.json
    frontmatter.ts              update model: lines in agent files
    profiles.ts                 apply JSON profile to install
    checksum.ts                 SHA-256 tracking
    opencode-config-writer.ts   write installed opencode.jsonc permissions
    opencode-scanner.ts         detect connected OpenCode models
    paths.ts                    framework and install dir resolution
    skill-recommender.ts        Optional skill recommendations

framework/                      bundled files shipped with the package
  agents/                       23 agents in 6 classes
  commands/                     23 slash commands
  prompts/
    workflow/                   routing, protocols, protected-artifacts, git-workflow
    execution/                  sensitive-data, implementation-safety
    engineering/                code-conventions, file-structure, tool-preferences, error-handling
    runtime/                    model-strategy
    review/                     review policy
    methodology/                test-first, caveman
  model-profiles/               free.json, low.json, balanced.json, high.json
  profile-models.json           bundled default active profile
  AGENTS.md                     workflow definition template
  opencode.jsonc                runtime config template

scripts/
  apply-profile-models.sh       legacy shell script (power users)

install.sh                      shell installer for scripted installs
uninstall.sh                    shell uninstaller

After oowl install, files from framework/ are copied to .opencode/. Edit the .opencode/ copies directly — they take effect immediately and oowl update will diff them against the shipped versions.

Common issues

Common questions and how to fix them. Click any item to expand.

ls .opencode/agents
ls .opencode/opencode.jsonc

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 the checks, keep the workflow rules intact, and commit design artifacts.

# Tests
npm test

# CLI smoke test
node bin/oowl.js --help

# Framework invariants
npm test -- --testPathPattern=invariants

# 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