Skip to content
BranchesTags

Repository files navigation

oh-see-flow

Custom workflow configuration for AI coding agents.

oh-see-flow /ˌoʊ.siː.floʊ/ — Originally "OC Flow" (OpenCode Flow), pronounced as one word. The name stuck.

⚠️ Project Status

This project is not finished. It was created to fulfill my personal needs as a developer who works with AI coding agents daily. I'm building this to develop my personal projects, and I'm not an AI expert — I'm learning with this project too.

I'm sharing it publicly because I believe others might find it useful, but expect rough edges, missing features, and evolving design.

You are welcome to:

  • Clone it and customize it for your own workflow
  • Fork it and make it your own
  • Open issues or suggest improvements
  • Reach out if you have questions or want to collaborate

Contact: Feel free to reach out via GitHub issues or discussions.

Supported Harnesses

oh-see-flow works with multiple AI coding agent platforms:

Harness Status Config Docs
OpenCode Stable opencode.json docs/harnesses/opencode.md
MiMo Code Stable mimocode.json docs/harnesses/mimocode.md

The installer lets you choose which harness to configure. Skills are installed to .agents/skills/ — a universal compatibility directory read by both harnesses and third-party skill libraries (npx skills, autoskills, etc.).

Why oh-see-flow?

Most AI coding sessions fail for operational reasons, not model reasons:

  • The agent jumps into code before requirements are clear
  • Architectural decisions disappear into chat history
  • One request quietly becomes a huge multi-area diff
  • Tests run late, or not at all
  • Reviewers get handed a wall of changes
  • Subagents are available, but the parent session has no orchestration discipline
  • Project skills exist, but the model forgets to load them

oh-see-flow fixes the workflow around the agent.

It provides:

  • An orchestrator that plans before acting
  • Specialized subagents for each type of work
  • Persistent memory — Engram for OpenCode, built-in for MiMo Code
  • Capability-based routing for handling images, large context, and code execution
  • Verification gates that catch mistakes before they compound

Design Philosophy

Why TDD?

Test-Driven Development (RED-GREEN-REFACTOR) is the foundation of reliable code:

  1. RED: Write a failing test that describes expected behavior
  2. GREEN: Write the minimum code to make it pass
  3. REFACTOR: Improve without changing behavior

Why this matters for AI agents:

  • Tests define "done" — the agent knows exactly when it's complete
  • Tests prevent regressions — changes that break things are caught immediately
  • Tests document intent — future sessions understand what the code does
  • Tests enable confidence — the agent can refactor without fear

Why Hybrid (TDD + OpenSpecs)?

Pure TDD works for implementation, but doesn't address planning. Pure OpenSpecs works for contracts, but doesn't enforce implementation quality.

oh-see-flow combines both:

Phase Approach What it provides
Planning OpenSpecs-style Requirements, interfaces, contracts, acceptance criteria
Implementation TDD Failing tests first, minimal code, refactoring
Verification Both Spec compliance + test passing

The orchestrator decides which approach per task:

  • Simple fixes → TDD directly
  • Multi-service features → Spec first, then TDD
  • Architecture decisions → Spec only (no code yet)

Why an Orchestrator?

Without orchestration, agents:

  • Jump into coding without understanding the problem
  • Create monolithic changes that are hard to review
  • Miss dependencies between tasks
  • Forget to verify their work

The orchestrator:

  1. Plans before any work begins
  2. Decomposes into independent subtasks
  3. Routes each subtask to the right specialist
  4. Chains results between subagents
  5. Verifies each step before moving on

Model Configuration

oh-see-flow supports different models for different roles:

Role Model Reason
Orchestrator xiaomi/mimo-v2.5 Supports image input — can see screenshots, diagrams, pasted images
Subagents xiaomi/mimo-v2.5-pro Best reasoning for code generation, review, debugging

The orchestrator handles image input and planning, while subagents use the Pro model for implementation tasks requiring deep reasoning.

Configuration is stored in .osf/models.json:

{
  "orchestrator": {
    "model": "xiaomi/mimo-v2.5",
    "reason": "Supports image input"
  },
  "agents": {
    "coder": { "model": "xiaomi/mimo-v2.5-pro" },
    "frontend-coder": { "model": "xiaomi/mimo-v2.5-pro" },
    "backend-coder": { "model": "xiaomi/mimo-v2.5-pro" },
    "tester": { "model": "xiaomi/mimo-v2.5-pro" },
    "researcher": { "model": "xiaomi/mimo-v2.5-pro" },
    "reviewer": { "model": "xiaomi/mimo-v2.5-pro" },
    "debugger": { "model": "xiaomi/mimo-v2.5-pro" }
  }
}

Why Capability-Based Subagents?

Different tasks need different capabilities:

Capability Problem Solution
Images Model can't see screenshots Orchestrator (MiMo-V2.5) handles directly
Large context Model hits context limits context-builder subagent with larger context
Code execution Model can't run code code-runner subagent with execution tools

The user configures which model handles each capability. When the main model encounters something it can't handle, the orchestrator automatically dispatches the right subagent.

Memory

oh-see-flow adapts its memory strategy to the harness:

OpenCode uses Engram for persistent memory:

  • Persistent memory across sessions
  • Full-text search of past decisions
  • Topic-based organization (bug patterns, design decisions, gotchas)

MiMo Code uses its built-in 4-layer memory system:

  • Session checkpoints (automatic context preservation)
  • Project memory (MEMORY.md — persistent across sessions)
  • Global memory (user-level preferences)
  • Full SQLite history (raw trace of every session)

No Engram needed for MiMo Code — the harness handles memory natively.

What's Installed

oh-see-flow installs agents, skills, and configuration. The structure depends on your chosen harness.

Skills (shared across harnesses)

Skills are installed to .agents/skills/ — a universal directory read by both OpenCode and MiMo Code, as well as third-party libraries like npx skills and autoskills.

.agents/skills/
├── osf-debug/         # Systematic debugging workflow
├── osf-review/        # Code review workflow
├── osf-tdd/           # Test-driven development
├── osf-spark/         # Brainstorming and exploration
├── osf-blueprint/     # Implementation planning
├── osf-ui-designer/   # UI design best practices
├── osf-ux-expert/     # UX best practices
├── osf-tester/        # Testing strategy
├── osf-backend/       # API/backend patterns
├── osf-frontend/      # Frontend patterns
├── osf-devops/        # CI/CD and infrastructure
├── osf-data/          # Data modeling and queries
├── osf-design-system/ # Design systems and DESIGN.md
├── osf-memory/        # Memory protocol (Engram for OpenCode, native for MiMo Code)
├── osf-convert/       # File conversion via MarkItDown
└── ...                # 24 skills total

Why .agents/skills/?

Both OpenCode and MiMo Code scan .agents/skills/ as a compatibility directory. This means:

  • Skills work for both harnesses without duplication
  • Third-party libraries (npx skills, autoskills) install to the same location
  • One directory to manage all skills

Agents (harness-specific)

Agents are installed to the harness-specific directory:

Harness Agents Path
OpenCode .opencode/agents/
MiMo Code .mimocode/agents/ 
agents/
├── orchestrator.md    # Primary agent — plans and delegates (MiMo-V2.5)
├── coder.md           # Implements code changes (fallback) (MiMo-V2.5-Pro)
├── frontend-coder.md  # UI components, styling, client-side (MiMo-V2.5-Pro)
├── backend-coder.md   # APIs, server logic, data layer (MiMo-V2.5-Pro)
├── tester.md          # Writes and runs tests (MiMo-V2.5-Pro)
├── researcher.md      # Explores codebase, docs, web (MiMo-V2.5-Pro)
├── reviewer.md        # Reviews code quality (MiMo-V2.5-Pro)
├── debugger.md        # Systematic debugging (MiMo-V2.5-Pro)
├── context-builder.md # Large context handling (MiMo-V2.5-Pro)
└── code-runner.md     # Code execution (MiMo-V2.5-Pro)

Config (harness-specific)

Harness Config File Memory
OpenCode opencode.json Engram MCP
MiMo Code mimocode.json Built-in (no Engram)

Quick Start

Prerequisites

  • OpenCode or MiMo Code installed
  • Node.js 18+ (for npm-based MCPs)
  • Engram — only needed for OpenCode: 
    brew install gentleman-programming/tap/engram

Install

Option 1: Download and run (recommended — TUI works)

curl -fsSL https://raw.githubusercontent.com/yanotoma/oh-see-flow/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

Option 2: Quick install (no TUI, uses defaults)

curl -fsSL https://raw.githubusercontent.com/yanotoma/oh-see-flow/main/install.sh | bash -s -- --project

The interactive installer will:

  1. Choose your harness (OpenCode or MiMo Code)
  2. Ask where to install (project or global)
  3. Enable optional dependencies (graphify)
  4. Check prerequisites
  5. Generate your harness-specific config

Configure MCPs

MCPs (Model Context Protocol servers) are configured after installation. Add them to your harness config file (opencode.json or mimocode.json):

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      },
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true
    }
  }
}

Verify

npm run validate

Start

# Restart your agent harness (opencode or mimo), then:
osf:grill

Commands

All commands prefixed with osf:

Command Description
osf:grill Ask clarifying questions before planning
osf:plan Orchestrator creates a plan for a task
osf:execute Execute the plan via subagents
osf:review Review current changes
osf:test Run tests and report
osf:debug Start systematic debugging
osf:deploy Deploy (requires explicit user confirmation)
osf:spec Generate a spec from requirements
osf:ship Full flow: test → review → merge → deploy
osf:finish Finish branch — merge/PR/keep/discard
osf:refresh-registry Refresh skill discovery registry

Workflow

osf:grill → osf:plan → osf:execute → osf:ship
   ↓           ↓           ↓            ↓
Questions    Plan      Subagents    Deploy
  & Ideas   & Spec     & Verify    (with confirmation)

Execution Modes

When you run osf:execute, you choose how much control you want:

Mode Behavior
auto Orchestrator plans and executes automatically
review-plan You review the plan, then execution proceeds
step-by-step You approve each subtask before it runs
dry-run Plan only, no execution
direct Skip orchestrator, pick subagent manually

Two-Stage Review

Every code change goes through:

  1. Spec compliance — Does the output match what was planned?
  2. Code quality — Is the code clean, correct, and maintainable?

Failure Handling

When a subagent fails:

  1. First attempt fails → retry with error feedback
  2. Second attempt fails → escalate to orchestrator to re-plan
  3. Orchestrator stuck → ask the user

Skills

Workflow Skills (Core)

  • osf-debug — Systematic debugging
  • osf-review — Code review
  • osf-tdd — Test-driven development
  • osf-spark — Brainstorming
  • osf-blueprint — Implementation planning
  • osf-forge — Skill creation
  • osf-ask-review — Request review
  • osf-handle-review — Process feedback
  • osf-preflight — Pre-completion checks
  • osf-swarm — Parallel subagents
  • osf-isolate — Git worktree isolation

All skills are installed to .agents/skills/ for universal compatibility.

Role Skills (Domain Expertise)

  • osf-ui-designer — UI and component design
  • osf-ux-expert — User experience
  • osf-tester — Testing strategy
  • osf-backend — API/backend patterns
  • osf-frontend — Frontend patterns
  • osf-devops — CI/CD and infrastructure
  • osf-data — Data modeling
  • osf-design-system — Design systems
  • osf-engram — Memory protocol

Commands

osf:init

Scan the codebase and create initial project memories.

What it does:

  • Analyzes project structure and patterns
  • If graphify is enabled: builds a knowledge graph for token-efficient queries
  • Saves key information for future sessions
    • OpenCode: saves to Engram
    • MiMo Code: saves to built-in project memory (MEMORY.md)

Usage: Run osf:init after cloning or when starting work on a new project.

Note: Re-running the installer (install.sh) will preserve existing MCP configurations in your harness config files.

Configuration: Graphify integration can be enabled during installation or by setting .osf/config.json:

{
  "graphify": {
    "enabled": true,
    "query_budget": 1500
  }
}

Credits

oh-see-flow is inspired by and builds on the work of these open source projects:

License

MIT

About

Custom workflow configuration for opencode — agents, skills, MCPs, plugins, and rules. Pronounced oh-see-flow.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages