MANDATORY RULES: VIOLATION IS FORBIDDEN

July 23, 2026 · View on GitHub

  • Response language follows language setting in .agents/oma-config.yaml if configured.
  • NEVER skip steps. Execute from Step 0 in order. Explicitly report completion of each step to the user before proceeding to the next.
  • You MUST use MCP tools throughout the entire workflow. This is NOT optional.
    • Use code analysis tools (get_symbols_overview, find_symbol, find_referencing_symbols, search_for_pattern) for code exploration.
    • Use memory tools (read/write/edit) for progress tracking.
    • Memory path: configurable via memoryConfig.basePath (default: .agents/state/memories)
    • Tool names: configurable via memoryConfig.tools in .agents/mcp.json
    • Do NOT use raw file reads or grep as substitutes. MCP tools are the primary interface for code and memory operations.
  • Read the oma-coordination skill BEFORE starting. Read .agents/skills/oma-coordination/SKILL.md and follow its Core Rules.
  • Follow the context-loading guide. Read .agents/skills/_shared/core/context-loading.md and load only task-relevant resources.

Vendor Detection

Before starting, determine your runtime environment by following .agents/skills/_shared/core/vendor-detection.md. The detected runtime vendor and each agent's target vendor determine how agents are spawned (Step 4) and monitored (Step 5).

Step 0: Preparation (DO NOT SKIP)

  1. Read .agents/skills/oma-coordination/SKILL.md and confirm Core Rules.
  2. Read .agents/skills/_shared/core/context-loading.md for resource loading strategy.
  3. Read .agents/skills/_shared/runtime/memory-protocol.md for memory protocol.
  4. Read .agents/skills/_shared/runtime/event-spec.md for L1 event protocol.
  5. Emit required L1 decisions by calling oma state:emit directly, as documented in .agents/skills/_shared/runtime/event-spec.md.
  6. Generate a session ID (format: YYYYMMDD-HHmmss). It keys plan-{sessionId}.json and all session-scoped memory artifacts (progress-*-{sessionId}.md, result-*-{sessionId}.md).
  7. Record session start using memory write tool:
    • Create session-work.md in the memory base path
    • Include: session start time, session ID, user request summary.

Step 1: Analyze Requirements

Analyze the user's request and identify involved domains (frontend, backend, mobile, QA).

  • Single domain: suggest using the specific agent directly.
  • Multiple domains: proceed to Step 2.
  • Use MCP code analysis tools (get_symbols_overview or search_for_pattern) to understand the existing codebase structure relevant to the request.
  • Report analysis results to the user.

Step 2: Run PM Agent for Task Decomposition

// turbo Activate PM Agent to:

  1. Analyze requirements.
  2. Define API contracts.
  3. Create a prioritized task breakdown.
  4. Save plan to .agents/results/plan-{sessionId}.json.
  5. Use memory write tool to record plan completion.

Step 3: Review Plan with User

Present the PM Agent's task breakdown to the user:

  • Priority tiers (1, 2, 3 — lower runs first)
  • Agent assignments
  • Dependencies
  • You MUST get user confirmation before proceeding to Step 4. Do NOT proceed without confirmation.

Step 4: Spawn Agents by Priority Tier

// turbo Spawn agents for each task by priority tier (lowest first: tier 1, then tier 2, etc.). Spawn all same-priority tasks in parallel. Assign separate workspaces to avoid file conflicts.

Per-Agent Dispatch

Resolve the target vendor for each agent from .agents/oma-config.yaml. Use native subagents only when target_vendor === current_runtime_vendor and that runtime supports the vendor's role-subagent path. Otherwise use oma agent:spawn for that agent.

If Claude Code and target vendor is Claude

Use the Agent tool to spawn subagents:

  • Agent(subagent_type="backend-engineer", prompt="Implement backend tasks per plan.", run_in_background=true)
  • Agent(subagent_type="frontend-engineer", prompt="Implement frontend tasks per plan.", run_in_background=true)
  • Multiple Agent tool calls in the same message = true parallel execution
  • Agent definitions: .claude/agents/{agent}.md

If Codex CLI and target vendor is Codex

Spawn native Codex custom agents using .codex/agents/{agent}.toml when available. Native CLI executor path: codex exec "@{agent} ..." using the generated agent file. Pass each agent its task description, API contracts, and relevant context. If native dispatch is not verified in the current runtime, fall back to oma agent:spawn.

If Gemini CLI and target vendor is Gemini

Use native Gemini subagents when available, otherwise fall back to oma agent:spawn. Native CLI executor path: gemini -p "@{agent} ..." using .gemini/agents/{agent}.md.

If target vendor differs from current runtime, or native dispatch is unavailable

oma agent:spawn backend "task description" session-id -w ./backend &
oma agent:spawn frontend "task description" session-id -w ./frontend &
wait

Step 5: Monitor Agent Progress

  • Use memory read tool to poll progress-{agent}[-{sessionId}].md files
  • Use MCP code analysis tools (find_symbol and search_for_pattern) to verify API contract alignment between agents
  • Use memory edit tool to record monitoring results

Claude Code note: the Agent tool returns results synchronously (or notifies on background completion), so no file polling is needed. Check status, files changed, and issues directly in each agent's return value.

Step 6: Run QA Agent Review

After all implementation agents complete, spawn QA Agent to review all deliverables:

  • Security (OWASP Top 10)
  • Performance
  • Accessibility (WCAG 2.2 AA)
  • Code quality

Step 6.1: Measure Quality Score (Conditional)

If automated measurement is available:

  1. Load quality-score.md (conditional, per context-loading.md)
  2. Measure Quality Score based on QA findings
  3. Record as baseline in Experiment Ledger via memory tools

Step 7: Address Issues and Iterate

If QA finds CRITICAL or HIGH issues:

  1. Re-spawn the responsible agent with QA findings. The fix prompt MUST instruct root-cause remediation, not symptom suppression. Forbid tactical patches (try/catch swallowing, validation bypass, hardcoded values, feature flags hiding the bug, silencing the failing test) unless the agent can explicitly justify why a structural fix is out of scope for this iteration (e.g., upstream library bug, deprecated path, hotfix window). Bias toward the orthodox engineering fix even when it costs more lines or touches more files.

  2. Emit and verify the remediation decision before accepting any fix/ignore choice:

    oma state:emit "decision.made" '{"subject":"work.remediation-choice","decision":"Fix the responsible QA finding with root-cause remediation or explicitly defer it.","rationale":"QA identified a CRITICAL/HIGH issue requiring a recorded remediation choice."}'
oma state:verify --workflow work --checkpoint remediation-choice

  3. If Quality Score is active: measure after fix, apply Keep/Discard rule, record in Experiment Ledger.

  4. Before each new fix cycle, apply the loop termination check:

    Fix Loop termination conditions (OR, whichever fires first wins):

    1. Total fix cycles have reached the configured maximum (default: 5). Do not start another cycle; report the remaining CRITICAL/HIGH findings and stop.
    2. Session cost cap exceeded: if loadQuotaCap() from cli/io/session-cost.ts returns non-null, call checkCap(sessionId, cap) (no cap configured → skip this condition). If exceeded === true, print formatPromptMessage(result) to the user and stop the loop immediately. Save current results before stopping, then report early termination due to quota.

    If neither condition is met, repeat Steps 5-7.

  5. If same issue persists after 2 fix attempts: Activate Exploration Loop (load exploration-loop.md per context-loading.md):

    • Generate 2-3 alternative approaches via Exploration Decision template
    • Re-spawn the same agent type with different hypothesis prompts (separate workspaces)
    • QA scores each result
    • Best result adopted, others discarded
    • All experiments recorded in Experiment Ledger

  6. Continue until all critical issues are resolved or a termination condition fires.

  7. Use memory write tool to record final results.

  8. If Quality Score was measured: generate Experiment Ledger summary and auto-generate lessons from discarded experiments.

Step 8: Optional Doc Verify Hook

If oma-config.yaml has docs.auto_verify: true:

  1. Run oma docs verify --json from the repo root.
  2. Capture the JSON output.
  3. If broken.length === 0: print docs verified clean (N docs) summary to stdout and continue with workflow completion.
  4. If broken.length > 0: print a 1-3 line summary identifying which docs have drift, and a hint Run /oma-docs verify for the full report. Continue with workflow completion (warn-only, never block).
  5. If oma-docs is not available (CLI command missing): skip silently.

This hook is opt-in; the default auto_verify: false skips this step entirely.