OpenSpec + OMC: Uniting Two Tools to Transform AI Coding from Ad‑hoc to Planned Execution

Why AI Coding Often Fails

When using AI coding assistants, developers commonly encounter three problems: the assistant forgets requirements after repeated explanations, generated code ignores project conventions, and task progress cannot be automatically tracked. The root cause is the missing closed‑loop between planning and execution.

OpenSpec: Specification‑First Alignment

Core Idea

OpenSpec inserts a lightweight specification layer between the AI assistant and the codebase. Before writing code, developers write a clear “what to do” document that both humans and AI can understand.

Directory Structure (Specs + Changes)

openspec/
├── specs/          # Current system behavior (source of truth)
│   ├── auth/spec.md
│   └── payments/spec.md
└── changes/         # Lifecycle of a change
    ├── add-dark-mode/
    │   ├── proposal.md   # Why & what
    │   ├── design.md     # How (technical solution)
    │   ├── tasks.md      # Implementation checklist
    │   ├── .openspec.yaml# Change metadata
    │   └── specs/        # Delta spec
    └── archive/          # Archived changes

The specs/ directory is the immutable source of truth, while each change lives in its own sub‑directory under changes/, allowing incremental updates without disturbing the main spec.

DAG Dependency Engine

proposal (root)
   │
   ├─────┐
   │     ▼
   │   specs   design   (both depend on proposal)
   │     │       │
   └─────┬───────┘
         ▼
       tasks (depends on specs and design)

OpenSpec tracks artifact status via the file system: BLOCKED → READY → DONE, eliminating the need for an external state service.

Delta Specification

ADDED Requirements

: new behavior appended to the main spec MODIFIED Requirements: replace existing behavior REMOVED Requirements: delete behavior RENAMED Requirements: rename using FROM:/TO: syntax

Delta specs make the impact of each change explicit and reduce merge conflicts.

OPSX Workflow

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

Example: /opsx:propose add-dark-mode creates a change directory with all planning artifacts; /opsx:apply runs the implementation; /opsx:sync merges the delta back into specs/; /opsx:archive archives the completed change.

Project‑Level Configuration

schema: spec-driven
context: |
  Tech stack: TypeScript, React, Node.js
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format

The context field supplies the tech stack to the AI, while rules enforce additional constraints that are automatically injected into the AI’s context.

OMC: Multi‑Agent Orchestration

Four Interlocking Systems

OMC works as a Claude Code plugin that processes user input through four stages:

User Input → Hooks (event detection) → Skills (behavior injection) → Agents (task execution) → State (progress tracking)

Hooks

Detects 11 lifecycle events such as UserPromptSubmit (keyword detection), PreCompact (save key info before context compression), and Stop (force Claude to continue).

Skills

Provides 38 skills organized in three layers:

Guarantee Layer (optional): ralph – "no‑stop until done"
Enhancement Layer (0‑N): ultrawork (parallel) | git-master (commit)
Execution Layer (main): default | orchestrate | planner

Skill composition follows

[execution skill] + [0‑N enhancement] + [optional guarantee]

, e.g., orchestrate + ultrawork + ralph.

Agents

Build/Analysis : explore, analyst, planner, architect, executor – from code exploration to implementation.

Review : code‑reviewer, security‑reviewer – quality and security checks.

Domain : test‑engineer, designer, writer, qa‑tester – specialized domain tasks.

Coordination : critic – plan review and quality gating.

Each agent is bound to a model tier: haiku (fast, cheap) for exploration, opus (high‑quality) for architecture and review, sonnet (balanced) for everyday coding and testing.

State System

To survive Claude’s limited context window, OMC stores persistent data under .omc/:

.omc/
├── state/          # Runtime state files
│   ├── autopilot-state.json
│   ├── team/
│   └── sessions/
├── notepad.md      # Compression‑resistant memo
├── project-memory.json # Project knowledge base
├── plans/          # Execution plans
└── logs/           # Execution logs

The notepad is written during PreCompact events and re‑injected after compression, providing a “compression‑resistant” memory.

Team Mode (Five‑Stage Pipeline)

team-plan → team-prd → team-exec → team-verify → team-fix (loop)

This mirrors OpenSpec’s propose → apply → verify but focuses on execution.

Magic Keywords

autopilot

– full autonomous run ralph – persistent loop (no‑stop until done) ultrawork or ulw – parallel execution team – enter Team orchestration mode

These are detected by the Hooks system during UserPromptSubmit.

CLI Extensions (v4.4.0+)

/omc-teams 2:codex   "security review"
/omc-teams 2:gemini  "redesign UI"

The ccg keyword can schedule Claude, Codex, and Gemini together.

Custom Skills

Project‑scoped skills live in .omc/skills/ (version‑controlled), while user‑scoped skills reside in ~/.omc/skills/. The /skillify command extracts reusable patterns from the current session, enabling the AI to “auto‑learn” the developer’s habits.

Integration: OpenSpec + OMC

OpenSpec generates specification files and a tasks.md checklist. OMC discovers the generated skills (e.g., .claude/skills/openspec‑*/SKILL.md) and loads them automatically. When an executor agent runs, it already knows the project’s tech stack, design constraints, and required tasks—no glue code or API wiring is needed.

Task Flow Example: Adding Authentication to a Node.js Project

Phase 1 – OpenSpec Planning

# Install OpenSpec
npm install -g @fission-ai/openspec@latest

# Initialize for Claude Code
cd your-project
openspec init --tools claude

# Create a change
/opsx:propose add-auth

The command creates openspec/changes/add-auth/ with:

# .openspec.yaml
name: add-auth
status: planning

# proposal.md
## Motivation
System lacks authentication, all endpoints are open.
## Goal
Add JWT auth with login, register, token refresh.

# design.md
## Architecture
Use JWT + bcrypt, middleware intercepts requests.
## API
POST /auth/register, POST /auth/login, POST /auth/refresh

# tasks.md
- [ ] 1.1 Create User model & migration
- [ ] 1.2 Implement password hashing
- [ ] 1.3 Create auth middleware
- [ ] 1.4 Implement register endpoint
- [ ] 1.5 Implement login endpoint
- [ ] 1.6 Implement token refresh
- [ ] 1.7 Write unit tests

OpenSpec also creates corresponding skill files under .claude/skills/ for OMC.

Phase 2 – OMC Execution

# Install OMC (Claude Code plugin)
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode
/omc-setup

# Run in ralph mode (no‑stop until done)
ralph: follow openspec/changes/add-auth/tasks.md to implement auth

OMC orchestrates the following agents:

Explore agent (haiku) scans project structure.

Architect agent (opus) validates the design in design.md.

Executor agent (sonnet) processes each checkbox in tasks.md, marking them complete.

Test‑engineer agent (sonnet) writes unit tests.

Code‑reviewer agent (opus) performs security and quality review.

Ralph’s “no‑stop” guarantee ensures that if verification fails, the system loops back to fixing.

Phase 3 – Dual‑Layer Verification

# OpenSpec verification
/opsx:verify

Checks Completeness (all checkboxes), Correctness (implementation matches proposal), and Coherence (code follows design).

# OMC engineering verification
ultrawork: run all tests, ensure BUILD, TEST, LINT, ARCHITECT pass

Only when both verification layers succeed does the workflow proceed to merge and archive:

/opsx:sync
/opsx:archive

Best Practices & Recommendations

When to Use Only OpenSpec

Team already has mature CI/CD and code‑review pipelines.

Goal is to give AI assistants clear, structured context without needing execution orchestration.

Toolchain includes many AI coders (Cursor, Copilot, etc.) – OpenSpec supports 25+ tools.

When to Add OMC

Project complexity exceeds a single AI session’s context window.

Multiple roles (code‑reviewer, security‑reviewer) are required.

Large‑scale refactoring, multi‑module changes, or strict quality gates (BUILD/TEST/LINT/ARCHITECT) are needed.

Team‑Size Guidance

Solo developer : OpenSpec alone; use /opsx:propose then any preferred AI assistant.

2‑5 developers : OpenSpec + OMC autopilot mode – aligns intent and automates execution.

5+ developers : OpenSpec + OMC Team mode – parallel agents, double verification, and Delta specs reduce merge conflicts.

Common Pitfalls

OpenSpec requires Node 20.19+; verify runtime version.

OMC Team mode needs the experimental flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

OpenSpec’s context injection is limited to ~50 KB; keep spec files concise for large projects.

The correct npm package name for OMC is oh-my-claude-sisyphus, not oh-my-claudecode.

Low‑tier models may produce low‑quality specs; high‑tier models (e.g., Codex 5.5, Opus 4.7) are recommended for planning.

Conclusion

The bottleneck in AI‑assisted development has shifted from "can AI write code?" to "how can humans and AI collaborate effectively?" OpenSpec solves the alignment problem by making the "what" explicit, while OMC solves the execution problem through multi‑agent orchestration and rigorous verification. Together they close the loop from planning to delivery, turning AI coding from a fragmented experiment into a reliable development workflow.