oh-my-freebuff

Workflow skills for Freebuff, with an optional multi-agent pack for Codebuff or a BYOK connection. The full pack includes specialists and orchestrators for a research → plan → build → review pipeline. Inspired by oh-my-claudecode, built for the Codebuff agent runtime.

Freebuff's free sessions accept only its first-party agent/model pairs. OMF's custom agents cannot run under that server policy. The default install places /skill:omf-workflow in .agents/skills/ and no executable OMF agent files in .agents/oh-my-freebuff/. A Freebuff base agent can follow the workflow without changing its model. Full multi-agent routing remains opt-in.

Install

npx oh-my-freebuff install     # Freebuff-safe skill-only install

Or install the CLI:

npm i -g oh-my-freebuff
omf setup                      # install + write config + a knowledge.md stub

Run Freebuff in the project and invoke the workflow skill:

freebuff
> /skill:omf-workflow add pagination to the users API and cover it with tests

omf update migrates earlier full-agent installs to skill-only. To opt into custom agents with Codebuff or BYOK, run omf update --agents, then call omf-team as before. omf doctor checks your setup.

Orchestrators

Pick one by the shape of the task. Full guide in docs/MODES.md.

Agent	For
omf-team	The default. Research, design, plan, implement, test, review, looping on review findings.
omf-autopilot	A defined task, less overhead. One agent drives and calls helpers when it needs them.
omf-pipeline	Strict sequential stages. The coarse research → design → plan → implement → test → review order is enforced by handleSteps; an optional verifyCommand is a deterministic final gate.
omf-ultrawork	Many independent edits in parallel: rename everywhere, apply a rule across the repo.
omf-ultraqa	Drive the whole quality gate to zero failures. Optional gateCommands are re-run by the harness on every completion attempt.
omf-ralph	Loop on one check command. With verifyCommand, the harness machine-enforces exit 0 before success.
omf-ralplan	Generate competing plans, critique them against each other, merge into one.
omf-advisor	A second opinion: the same question sent to three different models, reconciled.
omf-deep-interview	Turn a vague request into a spec with a few pointed questions.

Specialists

Orchestrators spawn these. You can also call one directly for a focused job.

Agent	Role
file-picker	Shortlist the files that matter for a task.
researcher	Read-only context gathering across the code and web.
architect	Technical design before a large change.
designer	UI and API-surface design.
planner	Turn a goal into an ordered, checkable task list.
implementer	Write the code for one scoped task.
refactorer	Restructure without changing behavior, checked against tests.
reviewer	Capability-level read-only review: no edit tools and no unrestricted terminal.
security-reviewer	Look for exploitable issues with concrete attack scenarios.
critic	Push back on the approach, not the syntax.
tester	Write and run tests, report the real result.
debugger	Find the root cause before changing code.
data-scientist	Data exploration, queries, and metrics grounded in the data.
docs-writer	READMEs, comments, changelogs.
advisor-a/b/c	Three voices of the advisor panel, each on a different model.

Model presets

In --agents mode, each agent has a tier. A preset maps tiers to real OpenRouter models. Switch the whole pack's cost profile in one command:

omf preset budget      # open models only, cheapest
omf preset balanced    # default
omf preset premium     # Claude / GPT / Gemini, most expensive

omf preset rewrites each installed agent's model: line by tier and records the choice, so install and update re-apply it. The tier→model table lives in docs/MODEL-COMPATIBILITY.md. In skill-only mode the preset is saved but no agent model is changed.

Custom presets are partial overlays: omitted tiers inherit from balanced by default, or from an explicit extends preset. That prevents mixed old/new model state when a custom preset only overrides one tier:

{
  "customPresets": {
    "my-premium": {
      "extends": "premium",
      "strong": "some-provider/some-model"
    }
  }
}

Per-agent modelOverrides still win over the selected preset. Unknown override agent ids and broken/cyclic preset inheritance are rejected instead of silently being ignored.

CLI

Setup
  omf setup                 Install skill, write config, add a knowledge.md stub
  omf install               Install the Freebuff-compatible workflow skill
  omf update                Refresh and migrate previous installs to skill-only
  omf update --agents       Enable custom agents for Codebuff or BYOK
  omf uninstall             Remove the pack
  omf doctor                Check setup, config parsing and routing integrity

Agents & models
  omf list                  List the agents
  omf preset [name]         Show or apply a model preset

Config
  omf config                Print the effective config
  omf config get <key>      Read a value
  omf config set <k> <v>    Write a value (--global for user scope)

Skills
  omf skill list            List skills
  omf skill add <name>      Scaffold a new skill
  omf skill remove <name>   Delete a skill
  omf skill search <q>      Search skills

Notifications
  omf notify setup <ch>     Configure telegram | discord | slack | file
  omf notify test           Send a test message
  omf notify status         Show configured channels

Options
  -g, --global              Target ~/.agents and user-scope config
  -d, --dir <path>          Operate on <path>/.agents
  -f, --force               Overwrite an existing install

Notifications

Get a ping when a long run finishes. Configure a channel, then call hooks/notify.mjs from wherever your workflow signals completion.

Prefer keeping the secret in an environment variable rather than shell history:

export SLACK_WEBHOOK=https://hooks.slack.com/services/...
omf notify setup slack '${SLACK_WEBHOOK}'      # stored as a reference, resolved at send
omf notify test

Passing the value directly also works (omf notify setup slack <url>), but it lands in your shell history. Literal Slack/Discord URLs are validated at setup, and environment-backed URLs are validated when sent. Only HTTPS provider webhook hosts/paths are accepted.

The file notification channel is project-root confined by default, including symlink checks. If you intentionally need to write outside the project, opt in explicitly with allowExternalNotificationFile: true in config.

Secrets are stored 0600 and redacted in omf config. Messages support {{projectName}} and other variables.

Skills

Skills are reusable, named instructions an agent can invoke. They install to the Codebuff-native location and are discovered as /skill:<name>:

.agents/skills/<name>/SKILL.md

omf skill add my-check      # scaffolds .agents/skills/my-check/SKILL.md
omf skill list
omf skill search verify
omf skill remove my-check

Config & secrets

Config lives in .freebuff/omf.jsonc (project) or ~/.config/freebuff-omf/config.jsonc (--global). Notification tokens and webhooks are secrets, so:

• omf config redacts them by default; pass --show-secrets to reveal.
• Config files are written with 0600 permissions.
• Existing config is parsed strictly: malformed JSONC is reported, not silently replaced with an empty effective config.
• A value can reference the environment instead of storing the secret inline: omf notify setup slack '${SLACK_WEBHOOK}'.
• omf doctor warns if a project config holding secrets isn't git-ignored and reports malformed config/routing errors as failed checks.

How orchestration works

In --agents mode, orchestrators spawn specialists with Codebuff's spawn_agents tool. Each specialist starts with only the brief it's handed, so the orchestrator passes down the files, constraints, and definition of done. Independent work runs in parallel; edits to the same file are serialized.

omf-team
  ├─ file-picker / researcher   shortlist and read the relevant code
  ├─ architect / designer       decide the approach
  ├─ planner                    ordered task list
  ├─ implementer × N            the edits (parallel where independent)
  ├─ tester / debugger          make it work
  └─ reviewer                   must-fix loop, then done

omf-ralph, omf-ultraqa, and omf-pipeline also use programmatic handleSteps logic for guarantees that should not depend only on prompt obedience. Ralph re-runs a real command before allowing success when verifyCommand is supplied; UltraQA does the same for gateCommands. Without those explicit parameters, their discovered-check loops remain prompt-driven. Pipeline always enforces its coarse stage order and can optionally enforce a final verifyCommand.

What goes where

After the default install:

• The workflow skill lives under .agents/skills/omf-workflow/SKILL.md.
• The pack directory .agents/oh-my-freebuff/ holds metadata only. It has no loadable agent files until you opt in with --agents.
• Other skills install to the shared .agents/skills/<name>/SKILL.md.
• The type shim goes to .agents/types/agent-definition.ts — only if you don't already have one; an existing (or Codebuff-generated) one is left alone.

Customize

• In --agents mode, change a model durably: set modelOverrides (per agent) or customPresets in .freebuff/omf.jsonc — these survive install/update/preset. Custom presets inherit balanced unless extends says otherwise. See docs/MODEL-COMPATIBILITY.md.
• Change behavior: edit the agent's instructionsPrompt.
• Add an agent: drop a .ts file that exports an AgentDefinition and add its id to an orchestrator's spawnableAgents.

Note on omf update: the namespaced pack replacement is staged first and swapped into place atomically. Invalid config/routing or a staging failure does not delete the working pack. By default it removes the old custom agents from the live .agents directory. A successful update still replaces direct edits made under .agents/oh-my-freebuff/; keep durable routing changes in config or copy an agent to a new id. Your skills are safe — update and uninstall only touch skills the pack installed and you haven't modified (tracked in .freebuff/omf-managed.json).

Requirements

• Node.js ≥ 20 for the omf CLI.
• The Freebuff or Codebuff CLI to run the agents (npm i -g freebuff).

Develop

npm install       # dev only: TypeScript for typechecking
npm run typecheck
npm test

Normal CI smoke-tests the optional agent mode against a pinned Codebuff SDK. A separate scheduled canary runs weekly against @codebuff/sdk@latest, so upstream runtime breakage is caught even when this repository has no new commits.

Docs

• docs/MODES.md — the orchestration modes
• docs/MODEL-COMPATIBILITY.md — tiers, presets, model table
• docs/PARITY.md — what's ported from oh-my-claudecode and what isn't
• CHANGELOG.md — release notes

License

MIT. Not affiliated with Freebuff or Codebuff; it builds on their .agents extension point.