🔄 Omega Protocol - Execution protocol for AI agents

---

👤 For Humans

This section explains what the Omega (Ω) Protocol is, how it works, and what your role is as the human invoking it.

Overview

The Omega Protocol is a recursive execution framework for AI agents. You provide a problem specification — a prompt, a single file, or a folder of documents — and the agent autonomously decomposes, solves, validates, and delivers the result.

graph TD
    Parent["Ω Stage<br><i>Receives problem. Judges solution against validation.</i>"]
    Solution["Solution Stage"]
    Validation["Validation Stage"]
    RecurseS(["Becomes Ω Stage"])
    RecurseV(["Becomes Ω Stage"])

    Parent -- "spawns simultaneously" --> Solution
    Parent -- "spawns simultaneously" --> Validation
    Solution -. "results flow back up" .-> Parent
    Validation -. "results flow back up" .-> Parent
    Solution -- "if complex" --> RecurseS
    RecurseS -. "results flow back up" .-> Solution
    Validation -- "if complex" --> RecurseV
    RecurseV -. "results flow back up" .-> Validation

    style Parent fill:#4a90d9,color:#fff
    style Solution fill:#50c878,color:#fff
    style Validation fill:#50c878,color:#fff
    style RecurseS fill:#f0ad4e,color:#fff
    style RecurseV fill:#f0ad4e,color:#fff

Loading

How it works

1. Ω Stage — Receives your problem, writes omega/problem.md, then spawns two independent subagents simultaneously.
2. Solution Stage — Designs and builds the solution artifact following a top-down design process (conceptual model → architecture → components → classes → code).
3. Validation Stage — Independently derives acceptance criteria from the problem, documents its approach in concept.md, and produces a validation artifact.
4. Judgment — The Ω Stage runs validation against the solution, captures all outputs, and writes omega/results.md. If it fails, the relevant stage is restarted automatically.
5. Recursion — If any stage is too complex for one pass, it becomes its own Ω Stage with a nested omega/ folder, applying the same protocol recursively.

Solution and Validation are independent — no shared context. Either stage can itself become an Omega Stage.

Your role

⚠️ Autopilot notice: This protocol is designed to run in autopilot mode (e.g. GitHub Copilot CLI's agent mode). This means the agent will execute autonomously — spawning subagents, running validation, and iterating on failures — without asking for confirmation. Each action may consume tokens and incur costs automatically. Use with care.

• Provide a precise, complete problem specification (prompt, file, or folder).
• Receive the final verdict, solution artifact path, design summary, and results from omega/results.md.
• In the normal case, you are contacted twice: once to give the problem, once to receive the delivery. The agent will only contact you again if it encounters ambiguity that cannot be resolved by inference, domain defaults, or documented assumptions.
• You are not asked to validate, run, or verify anything — the protocol handles that autonomously.

Example prompt

The following is a real example of invoking the Omega Protocol on a Problem.md file:

Execute the Problem.md using the Omega Protocol

Where Problem.md contained:

- Red background window as output
- Green triangle on the given background
- C++20
- Use open source libraries
- Windows platform
- OpenGL for rendering

The agent autonomously wrote omega/problem.md, spawned a Solution Stage (C++20/OpenGL app) and a Validation Stage (Python static-analysis + build check) in parallel, judged the result by running the validator and taking a screenshot of the live application window, discovered and fixed a rendering bug (GL_STATIC_DRAW wrong constant), and delivered a passing verdict with screenshot evidence — all without human involvement.

Folder structure

Every problem gets its own omega/ folder:

omega/
├── problem.md          ← problem statement, written before spawning
├── solution/           ← Solution Stage working folder
│   ├── design.md       ← conceptual model → architecture → components → classes, written before code
│   └── <solution artifact>
├── validation/         ← Validation Stage working folder
│   ├── concept.md      ← acceptance criteria, validation approach, entry point command
│   └── <validation artifact>
├── validation-output.txt ← stdout/stderr from validation artifact run
├── <captures>          ← saved during judgment (screenshots, stdout, files, etc.)
└── results.md          ← verdict and permanent record, written after judgment

On recursion, a nested omega/ appears inside the stage's working folder. Nesting depth is unlimited.

Key files

File	Written by	Purpose
problem.md	Ω Stage	Self-contained problem statement with goal, constraints, success criteria, and technology stack. The ONLY input subagents receive.
design.md	Solution Stage	Top-down design document (conceptual model → architecture → components → classes). Written before any code.
concept.md	Validation Stage	Documents the acceptance criteria, chosen validation approach, and entry point command to run the validation artifact.
validation-output.txt	Ω Stage	Full stdout/stderr from running the validation artifact at judgment time.
results.md	Ω Stage	Permanent record: problem summary, solution design, test results, captures, and pass/fail verdict.

---

🤖 For AI Agents

Everything below is your executable specification. Follow it exactly.

Terminology: "Omega Stage" and "Ω Stage" are synonymous throughout this document.

Agent Operating Contract

You are an autonomous agent.

Read the provided problem specification — a prompt, a single file, or a folder with multiple documents (requirements, design elements, constraints, acceptance criteria, or any combination) — and synthesize omega/problem.md from it.

Solution artifact: the primary deliverable produced by the Solution Stage — typically built code, a compiled binary, generated files, or any other output that directly fulfills the problem specification. Its exact form depends on the problem.

• You are the Omega Stage unless explicitly spawned as a Solution Stage or Validation Stage.
• MUST write omega/problem.md before spawning any subagents.
• MUST spawn exactly two isolated subagents simultaneously: Solution Stage → omega/solution/, Validation Stage → omega/validation/.
• MUST pass each subagent exactly four things: the problem statement from omega/problem.md, its working folder, its role, and the absolute path to this protocol document (required so the stage can recurse if needed). Nothing else.
• MUST NOT let Solution and Validation share context, communicate, or reference each other.
• MUST NOT ask the human to validate, run, or verify anything.
• MUST judge by executing the validation artifact entry point declared in omega/validation/concept.md against omega/solution/, then producing and saving all applicable mandatory captures to omega/ (see Mandatory captures), and verifying captures match expectations.
• MUST write omega/results.md after final judgment (pass or escalation — not after every restart iteration).
• IF a stage determines it is too complex for one pass (see Recursion criteria) → that stage MUST recurse on its own: it creates omega/ inside its own working folder, writes omega/problem.md, and spawns Solution + Validation. The parent Ω Stage does not intervene — the recursing stage handles everything internally and returns its result to the parent.

Rules

Spawning

• MUST spawn exactly one Solution Stage and one Validation Stage.
• MUST define both simultaneously — MUST NOT define Validation after seeing the Solution.
• Both stages are independent agents: no shared context, no communication, no awareness of each other.
• Both receive ONLY these four inputs: the problem statement from omega/problem.md, their working folder, their role, and the absolute path to this protocol document.
• Each stage MUST NOT create, modify, or delete files outside its designated working folder.
• Solution Stage output: a solution artifact and design.md in omega/solution/.
• Validation Stage output: concept.md and a validation artifact in omega/validation/. The Validation Stage derives its acceptance criteria from problem.md — independent of how the solution is built.
  • concept.md MUST document: the acceptance criteria being verified, the chosen validation approach, and the entry point command to run the validation artifact.
  • The validation artifact MUST be fully automated, exit non-zero on any failure, and be runnable by the Ω Stage using only the entry point declared in concept.md. Choose the approach in this priority order:
    1. Native language — unit tests and component tests in the solution's own language and framework (e.g. Jest, JUnit, NUnit, Google Test, RSpec).
    2. Python — if native testing is not possible or insufficient (e.g. cross-language component testing, language-agnostic output assertion).
    3. Any other tool — native scripts, shell commands, or other tooling, if neither above is viable.

Solution design process

The Solution Stage MUST follow a top-down design process. MUST NOT write implementation code before completing the design levels that apply to the problem. Document the design in omega/solution/design.md before writing any implementation code. All five levels MUST be considered; levels that do not apply (e.g. no domain model for a pure utility script) MUST be explicitly marked as skipped with rationale in design.md.

Level	What to define	Recurse IF…
1. Conceptual model	Define domain entities, their responsibilities, and relationships. No implementation details yet.	Domain spans multiple bounded contexts each solvable independently.
2. Architecture	Choose architecture pattern based on the conceptual model. Define major subsystems, services, and boundaries.	Multiple independent subsystems each requiring separate implementation.
3. Components	Map architecture and conceptual model to concrete modules, packages, or services. Define interfaces between components.	Any component is itself a multi-pass problem.
4. Classes / interfaces	For each component, define types, classes, function signatures, and contracts.	A class hierarchy or interface set is itself too large for one pass.
5. Implementation	Write the code following the defined structure.	A single module or class is too large for one pass.

• IF any design level reveals the stage is too complex for one pass → MUST recurse at that level, using the current design as the sub-problem statement in omega/problem.md.
• design.md MUST be updated at each level before proceeding to the next.
• The Validation Stage derives its acceptance criteria from problem.md, NOT from design.md — ensuring validation remains independent of implementation choices.

Diagrams

• General diagrams (flowcharts, ER diagrams, git graphs, mind maps) → Mermaid. Renders natively on GitHub in README, issues, PRs, and wikis.
• UML diagrams (class, component, package, deployment, sequence, state machine, activity, use case, timing, interaction overview) → PlantUML.
• Mathematical notation (formulas, equations, matrices, integrals) in HTML output or web documentation → MathJax (default) or KaTeX (speed-critical). Use the math-documentation skill.
• MUST NOT use PlantUML for non-UML diagrams, and MUST NOT use Mermaid for UML diagrams.

Judgment

• Validation is fully automated. MUST execute the validation artifact entry point declared in omega/validation/concept.md against omega/solution/. MUST NOT involve the human.
• Bridging validation to solution: The Validation Stage has no awareness of the solution, so the Ω Stage is responsible for connecting them at judgment time.
  • MUST execute the validation entry point with the working directory set to omega/.
  • MUST pass the absolute path to omega/solution/ as the first command-line argument.
  • IF the validation artifact does not use that argument, this is acceptable ONLY IF concept.md makes that behavior explicit and the artifact still locates omega/solution/ correctly via the established working directory.
• The Omega Stage is the ONLY place Solution and Validation outputs meet.
• The Omega Stage execution is not complete until validation confirms the solution satisfies all acceptance criteria.
• Process cleanup is mandatory. Any process launched for validation, capture production, or observation MUST be shut down deterministically after its output has been recorded. MUST use a target-specific mechanism (such as a window handle, process handle, or PID). MUST NOT rely on name-based process termination.
• IF validation appears to require subjective judgment, MUST exhaust options in this order:
  1. Observe — execute the artifact, capture all runtime outputs, analyze them. Observable output is data. Code inspection is not observation.
  2. Proxy — define an automated proxy that approximates the criteria.
  3. Escalate — ONLY IF neither works, escalate to the launcher with a clear explanation.

Mandatory captures

The Ω Stage is responsible for producing and saving all applicable captures to omega/ during judgment. This is a separate obligation from running the validation artifact — the Ω Stage MUST actively generate each capture by executing the solution and recording its output. No produced and saved capture = no passing verdict.

Determine which capture types apply from the Expected capture types declared in omega/problem.md, then produce every applicable one. If a capture type is obviously required by the solution's behaviour but was not declared in problem.md, treat the omission as an error and add it before proceeding:

Type	Applies when	What the Ω Stage MUST do	Save as
Visual	Solution produces a window or any graphical output	On Windows: use the visual-capture skill — run capture.py with the executable path and omega/screenshot.png as the output path. The script launches the executable, waits for the window, captures the client area via PrintWindow (not screen coordinates), verifies the capture is non-uniform, then shuts the process down by PID. See .github/skills/visual-capture/SKILL.md for full usage. On other platforms: produce an equivalent screenshot using platform-appropriate tooling (e.g. xdotool/import on X11, screencapture on macOS) and verify it is non-uniform before acceptance.	screenshot.png
Text output	stdout/stderr is the primary deliverable (e.g. a CLI tool, a data processor, a code generator) — not incidental build or diagnostic output	Execute the solution and record complete stdout/stderr	Text file
File-producing	Solution writes output files	Execute the solution and collect the produced files	The files themselves
Networked	Solution communicates over the network	Execute the solution with network logging and record actual requests and responses	Log file
Audio	Solution produces audio output	Execute the solution and record the actual audio output (waveform, spectrogram, or transcript)	Audio/text file

• Assumed, mocked, partial, summarized, or described output MUST NOT be substituted for a produced capture.
• A passing build or passing static analysis alone is not sufficient when a capture type applies — the Ω Stage MUST still produce the capture by executing the solution.
• Visual captures MUST be verified as non-uniform before acceptance. A capture that is a single solid colour means the application did not render — treat this as a solution failure regardless of exit code or lack of error output.
• Text output captures MUST be verified as non-empty and matching the expected content described in problem.md. An empty or near-empty stdout when the solution's deliverable is text output is a solution failure regardless of exit code.
• The Ω Stage MUST verify that each produced capture matches the expected output described in problem.md before recording a passing verdict.
• Name capture files descriptively and consistently: screenshot.png for visual, stdout.txt for text output, the solution's own output filenames for file-producing, network.log for networked, audio.wav or audio-transcript.txt for audio.

Recursion

• IF a single agent can complete the stage in one pass → MUST NOT recurse.
• IF it cannot → the stage becomes an Omega Stage, creates omega/ inside its working folder, writes omega/problem.md, and spawns Solution + Validation.
• Sub-problems MUST be genuinely simpler and independently solvable.
• MUST NOT decompose into a single sub-problem — that is not recursion.
• Results MUST feed back to the stage that recursed, not to the root.

Recursion criteria

A stage is too complex for one pass IF it meets any of the following:

General complexity signals:

• It requires multiple independent deliverables that don't naturally emerge from a single execution.
• It spans multiple distinct technical domains, each requiring separate expertise or tooling.
• Its success criteria cannot all be verified by a single validation artifact.
• Completing it would require abandoning partial work and restarting mid-execution.

Development design pattern signals:

These patterns are dual-purpose: they signal when a stage is too complex for one pass, and they are implementation blueprints — if a pattern applies, the Solution Stage SHOULD structure its implementation accordingly.

Object-level patterns (GoF):

• It requires step-by-step construction where each step produces a distinct intermediate artifact consumed by the next. (Builder)
• The abstraction (interface/contract) must be defined and validated independently from the implementation. (Bridge)
• It involves distinct subsystems unified behind one interface, each subsystem independently buildable and validatable. (Facade)
• It requires multiple interchangeable algorithms or implementations that each need independent build and validation. (Strategy, Abstract Factory)
• The solution has a recursive tree structure where each node is itself a complete, independently solvable sub-problem. (Composite)

System-level architecture patterns:

• It involves distinct architectural layers that can be built and validated independently (e.g. presentation, business logic, data access). (Layered / N-Tier)
• It requires a client and a server with separate responsibilities, each independently implementable and validatable. (Client-Server)
• It requires multiple independent services with separate lifecycles communicating via APIs (e.g. backend service + frontend app + worker). (Microservices, SOA)
• Components react to events from independent producers — producers and consumers must be built and validated independently. (Event-Driven)
• Data flows through a sequence of independent processing stages, each transforming and passing output to the next. (Pipe-and-Filter)
• A broker component decouples independently built clients and services — broker and each service are separate sub-problems. (Broker)
• It requires a minimal core system extended by independently developed and deployable plugins or modules. (Microkernel)
• It crosses technology boundaries where each part requires a different runtime, language, or toolchain.
• It requires infrastructure provisioning separate from application logic (e.g. network setup, then deployment).
• It contains a build → test → deploy pipeline where each stage is a meaningful sub-problem.

When a design pattern signal applies, the Solution Stage SHOULD use that pattern to structure its solution — not only as a recursion boundary, but as the intended architecture of the deliverable. Object-level patterns govern how code is structured; system-level architecture patterns govern how components are deployed and communicate.

Subtask decomposition

A stage (Solution or Validation) MAY decompose its own work into subtasks — parallel sub-agents that each handle a narrowly scoped unit of work — when those units are independent and do not individually need their own Solution + Validation cycle.

Subtask decomposition is not recursion. The distinction:

	Subtask decomposition	Recursion
When	Work units are independent and simple enough to implement or validate in one pass each	A unit is itself a complex problem that requires its own design → build → validate cycle
What spawns	N parallel worker sub-agents, all inside the same stage's working folder	A full Omega Stage with Solution + Validation + Judgment
Validation	Parent stage integrates all subtask outputs and is validated as a whole by the parent Omega cycle	Each recursed sub-problem has its own Validation Stage and results.md
Failure handling	Parent retries only the failed subtask(s)	Parent restarts the recursed sub-problem as a whole

When to decompose into subtasks

A stage SHOULD decompose into subtasks IF it meets all of the following:

• There are two or more clearly independent work units (e.g., implement component A, implement component B, implement component C — each independent).
• Each unit can be completed and its output verified by the parent in one pass.
• The units do not need to share context or intermediate results — they can work from the problem statement and their designated scope alone.
• Decomposing will meaningfully reduce total execution time (because units run in parallel).

A stage MUST NOT decompose into subtasks IF:

• There is only one real unit of work (decomposition provides no benefit).
• Units have sequential dependencies (output of one is input of the next — use sequential steps instead).
• The problem is simple enough that a single agent can handle it comfortably in one pass.

Subtask mechanics

1. The parent stage plans the decomposition before spawning any sub-agents: write a brief decomposition plan to subtasks.md in the stage's working folder listing each subtask's scope, designated path, and expected output.
2. Spawn all subtasks simultaneously. Each subtask receives: its scope, its designated working path (a subfolder inside the parent's working folder), and any shared context it needs (e.g., shared type definitions, a common interface header). Nothing else.
3. Each subtask MUST NOT create, modify, or delete files outside its designated path, except for explicitly shared files listed in the decomposition plan (e.g., a shared header that all subtasks must write to — in that case, the plan MUST specify which subtask owns the file and which only read it).
4. Wait for all subtasks to complete, then integrate: merge all produced artifacts, verify consistency (e.g., compile the whole project, check that all interfaces align), and proceed.
5. If a subtask fails: retry only that subtask (with failure context), not all subtasks. A subtask may be retried up to 2 times. After 2 retries without success, the parent stage escalates to its launcher — treating it as a stage failure.
6. Delete subtasks.md after successful integration — it is a working file, not a permanent artifact.

Subtask prompt template

Role: Subtask worker
Parent stage: <Solution Stage | Validation Stage>
Working path: <absolute path to designated subfolder>
Scope: <precise description of what this subtask must produce>
Shared context: <any shared definitions, interfaces, or constraints the subtask needs>
Expected output: <exact files or results the parent stage expects back>
Constraints:
- MUST NOT create, modify, or delete files outside your working path<, except: list any shared files>
- MUST NOT ask the human for anything.
- Return a brief summary of what you produced when done.

When the human provides an updated problem specification and omega/ already exists from a previous run, the Ω Stage MUST NOT blindly start from scratch. Instead:

1. Read omega/problem.md (previous run's problem statement) and compare it against the new problem specification. Compute the delta: what was added, removed, or changed.

2. Classify the update as one of two modes:

   Mode	Criteria	Action
   INCREMENTAL	Same domain, same tech stack, same architecture pattern, same language. New requirements are additive (new features, refinements, constraints, or bug fixes). The existing solution can be evolved to satisfy the new requirements without architectural replacement.	Preserve existing omega/solution/ and omega/validation/ artifacts. Write the updated omega/problem.md. Spawn only the stages whose scope changed, passing them the delta and the existing artifacts to refactor from.
   FRESH-START	Different primary language, different OS/platform, different rendering or framework API (e.g. OpenGL → Vulkan), incompatible architecture, or a domain shift that would require replacing the solution wholesale. The existing solution cannot be evolved — it must be discarded.	Clear omega/ entirely. Proceed as a new first-run execution.

3. When INCREMENTAL, apply the refactoring skill: the Solution Stage receives the existing code as-is and evolves it to satisfy the delta. It MUST treat the existing design.md as the starting point and update only the levels that are affected by the delta. It MUST NOT rewrite artifacts that are unchanged by the new requirements.

4. When INCREMENTAL, spawn only the stages that need work:

   • IF solution requirements changed → restart Solution Stage with the delta and existing artifacts.
   • IF acceptance criteria changed → restart Validation Stage with updated criteria.
   • IF both changed → restart both simultaneously.
   • Unchanged stages retain their existing artifacts unchanged.

5. Document the delta in the updated omega/problem.md: add a ## Problem Delta section listing what changed relative to the prior run, the update mode (INCREMENTAL or FRESH-START), and the rationale.

Default is INCREMENTAL. Only classify as FRESH-START when the incompatibility is clear and unavoidable. When in doubt, attempt incremental evolution — if the Solution Stage determines the existing code cannot be evolved, it escalates back to the Ω Stage, which then reclassifies as FRESH-START and restarts.

Failure handling

1. MUST identify the gap: solution, validation definition, or problem statement.
2. Solution wrong → MUST restart Solution Stage with failure context. Restart means: delete or clear the stage's working folder, then spawn a new subagent with the original prompt plus a description of what failed and why. The new subagent starts fresh — it does not inherit partial work.
3. Validation definition wrong → MUST restart Validation Stage with corrected criteria. Same restart mechanics as above.
4. MUST NOT restart a given stage more than 3 times in a single Omega Stage invocation. After 3 restarts of the same stage without a passing result, MUST escalate to the launcher with a summary of all failure contexts and restart attempts.
5. Problem ambiguous or underspecified → MUST attempt to resolve from available context (infer from constraints, apply domain defaults, make reasonable assumptions, and document them in the stage's own artifacts; if you are the Omega Stage before spawning, document them in problem.md). ONLY IF it cannot be resolved → escalate to launcher (the stage that spawned you, or the human if you are the root Omega Stage). MUST NOT proceed with unresolved ambiguity.
6. MUST NOT block. MUST either restart the relevant stage or escalate to launcher, according to items 2-5.

Human escalation

Every stage MUST escalate to its launcher — the stage that spawned it. The human is the launcher of the root Omega Stage.

• ONLY the root-level Omega Stage may contact the human.
• All other stages MUST escalate to their launcher.
• In the normal case, the root-level Omega Stage contacts the human twice:
  1. Receive — receive the problem. IF underspecified, MUST first attempt to resolve from context (infer, apply defaults, document assumptions). ONLY IF unresolvable → escalate back to the human. MUST NOT proceed until resolved.
  2. Deliver — once verdict is passed: deliver the verdict, the path to the solution artifact in omega/solution/, and a summary from omega/results.md.
• ONLY IF unresolved ambiguity remains after all self-resolution attempts may the root-level Omega Stage contact the human again during execution.

Folder Structure

Every problem gets its own omega/ folder:

omega/
├── problem.md          ← MUST exist before spawning
├── solution/           ← Solution Stage working folder
│   ├── design.md       ← conceptual model → architecture → components → classes, written before code
│   └── <solution artifact>
├── validation/         ← Validation Stage working folder
│   ├── concept.md      ← acceptance criteria, validation approach, and entry point command
│   └── <validation artifact>
├── validation-output.txt ← stdout/stderr from validation artifact run
├── <captures>          ← saved during judgment
└── results.md          ← MUST exist after judgment

On recursion, create omega/ inside the stage's working folder:

omega/
├── problem.md
├── solution/
│   ├── omega/                ← recursed sub-problem
│   │   ├── problem.md
│   │   ├── solution/
│   │   │   ├── design.md
│   │   │   └── <solution artifact>
│   │   ├── validation/
│   │   │   ├── concept.md
│   │   │   └── <validation artifact>
│   │   ├── validation-output.txt
│   │   ├── <captures>
│   │   └── results.md
│   ├── design.md             ← conceptual model → architecture → components → classes
│   └── <solution artifact>
├── validation/
│   ├── omega/                ← recursed sub-problem
│   │   ├── problem.md
│   │   ├── solution/
│   │   │   ├── design.md
│   │   │   └── <solution artifact>
│   │   ├── validation/
│   │   │   ├── concept.md
│   │   │   └── <validation artifact>
│   │   ├── validation-output.txt
│   │   ├── <captures>
│   │   └── results.md
│   ├── concept.md
│   └── <validation artifact>
├── validation-output.txt
├── <captures>
└── results.md

Each omega/ folder is self-contained. Nesting depth is unlimited.

problem.md

Written by the Omega Stage before spawning. At the root level, synthesized from whatever the human provided (prompt, file, or folder). At recursed levels, synthesized from the stage's own context. Required contents:

• The problem as received — verbatim or summarized from the source (human input at root level, Omega Stage context at recursed levels)
• Restatement as a self-contained task: goal, constraints, success criteria
• All context needed for subagents to work independently (extracted from requirements docs, design elements, etc.)
• Technology stack: language, runtime, and framework MUST be specified so the Validation Stage can design an appropriate validation approach without needing to inspect the solution
• Execution environment: operating system, shell, and available tools MUST be specified so both stages can make platform-appropriate implementation choices
• Expected capture types: MUST list which mandatory capture types apply (Visual, Text output, File-producing, Networked, Audio) based on what the solution will produce. This is declared upfront so it cannot be missed during judgment.
• Expected output per capture type: for each expected capture type, MUST describe what the correct output looks like (e.g. "window shows a dark grey background with a white house outline", "stdout contains the sorted list of names, one per line"). This is what the Ω Stage verifies captured output against.
• Applicable Skills (optional, added by step 4): an ## Applicable Skills section listing each matched skill agent's name, path to its SKILL.md, and a one-line note on when/how to invoke it. Both subagents are required to read and apply these. Omitted if no skills match.

This is the ONLY problem statement subagents receive.

results.md

Written by the Omega Stage once judgment is final. The Omega Stage writes omega/results.md only when the result is passed or when escalation terminates the loop — not on every restart iteration. The final write is the permanent record and MUST include all prior failure contexts and restart counts. Required contents:

• Problem statement
• Summary of solution design (architecture, components, key classes)
• Summary of solution artifact
• Summary of acceptance criteria (from concept.md)
• Validation approach and artifact description
• Validation results (pass/fail counts, output)
• Validation output log (validation-output.txt), referenced by filename
• All captures, referenced by filename
• Pass/fail verdict with rationale
• Failure context and restarts, if applicable

Shell output is ephemeral. results.md is the permanent record.

Omega Stage Checklist

Steps 6-10 form an iteration loop. On the first pass, execute steps 1-11 in order. After any restart in step 10, return to step 6. Step 11 runs only when step 10 determines the result is passed or requires escalation. Do not restart the same stage more than 3 times.

1. Read the problem specification (prompt, file, or folder at root level; Omega Stage context at recursed levels).

2. Check for an existing run. IF omega/problem.md exists from a prior run, read it, compute the delta against the new problem specification, and classify the update as INCREMENTAL or FRESH-START (see Problem updates). IF FRESH-START, delete omega/ entirely and continue to step 3 as a new first run. IF INCREMENTAL, preserve existing omega/solution/ and omega/validation/, skip to step 3. IF no prior omega/ exists, skip this step.

3. Create omega/ if it does not exist. Write omega/problem.md — include a ## Problem Delta section if this is an INCREMENTAL update.

4. Identify applicable skill agents. Scan .github/skills/ (repository-level skills) and ~/.copilot/skills/ (user-global skills; scan if the folder exists). For each skill whose description field matches the problem domain, language, or task, add an ## Applicable Skills section to omega/problem.md listing: skill name, path to its SKILL.md, and a one-line note on when/how to invoke it. This list is passed to both subagents. If no skills match, omit the section.

   Design-process skills fire for every implementation problem. Five skills are anchored to the mandatory design process and apply to any problem where the Solution Stage will write code: software-architecture (design.md level 2), architecture-documentation (design.md structure), uml (design.md diagrams), design-patterns (any multi-class code), refactoring (design.md level 5). Always include them when the problem involves producing a software artifact.

5. Create omega/solution/ and omega/validation/ if they do not exist.

6. Spawn the stages that need work:

   • FRESH-START or first run: spawn both Solution Stage and Validation Stage simultaneously.
   • INCREMENTAL — both scopes changed: spawn both stages simultaneously, passing each the delta and a reference to existing artifacts.
   • INCREMENTAL — solution only: spawn Solution Stage only; Validation Stage artifacts remain in place.
   • INCREMENTAL — validation only: spawn Validation Stage only; Solution Stage artifacts remain in place.
   • Each spawned stage MAY internally decompose its own work into subtasks (see Subtask decomposition) — that is the stage's decision and is invisible to the Ω Stage.

7. Wait for the running stage(s) to finish. On the first pass, both are running. On restart iterations, only the restarted stage is running — the other stage's artifacts remain in place.

8. Execute the validation artifact entry point (declared in omega/validation/concept.md) against omega/solution/, applying the bridging rules: set the working directory to omega/ and pass the absolute path to omega/solution/ as the first command-line argument (see Judgment). Record all output (pass/fail counts, stdout/stderr) from the validation artifact run. Save this validation output as omega/validation-output.txt.

9. Produce and verify all mandatory captures. MUST execute this step even if step 8 reported failures. Determine which capture types apply (see Mandatory captures). For each applicable type, launch/execute the solution and actively produce the capture. Save all produced captures to omega/. For visual captures: if the visual-capture skill was matched at step 4 (Windows), use it (capture.py) — it handles window detection, PrintWindow capture, uniformity check, and deterministic process cleanup; otherwise, use platform-appropriate tooling to capture and verify the screenshot. Then compare each produced capture against the expected output described in problem.md; for visual captures, verify the image is non-uniform (not a single solid colour). If any capture does not match expectations or fails verification, treat this as a solution failure.

10. Evaluate result — exactly one of:

    • IF solution wrong → restart Solution Stage with failure context (see Failure handling for restart mechanics). Solution is wrong when the validation criteria are reasonable but the solution fails to satisfy them, or when captures do not match the expected output.
    • IF validation wrong → restart Validation Stage with corrected criteria (see Failure handling for restart mechanics). Validation is wrong when the acceptance criteria are unreasonable, the validation artifact has bugs unrelated to the solution, or concept.md contradicts problem.md.
    • IF both appear wrong → fix validation first. Correct acceptance criteria are a prerequisite to meaningful solution evaluation.
    • IF ambiguous or underspecified and it cannot be resolved from context → escalate to launcher.
    • IF passed → continue to step 11.
    • After any restart, return to step 6.

11. Write omega/results.md as the permanent record. If the result passed, done. If the result escalated, include the escalation rationale and stop.

GitHub Copilot CLI Execution

Implementation-specific. This section maps the protocol to GitHub Copilot CLI commands. If you are a different agent, adapt the mechanics to your own tooling — the normative rules above still apply.

Execute in order:

Checklist step(s)	Situation	Action
1-2	Check for prior run	Read new problem spec → IF omega/problem.md exists, compute delta and classify INCREMENTAL or FRESH-START; IF FRESH-START delete omega/ entirely
3-5	Prepare the run	Write omega/problem.md (with ## Problem Delta if INCREMENTAL) → scan .github/skills/ and ~/.copilot/skills/ (if present) for matching skills and append ## Applicable Skills → create omega/solution/ and omega/validation/ if absent
6-7	Spawn stage(s) and wait	/fleet — enable fleet mode. Spawn only the stages that need work (see checklist step 6): both for FRESH-START or both-changed INCREMENTAL; one for single-scope INCREMENTAL. For INCREMENTAL stages, include ## Prior Work in the prompt (see template below). Each stage may internally spawn subtasks — monitor them with /tasks; they are the stage's internal concern. Monitor with /tasks until all stages finish.
8-9	Judge	Execute the validation artifact entry point (from omega/validation/concept.md) against omega/solution/ → save validation output as omega/validation-output.txt → produce and verify all applicable mandatory captures by launching/executing the solution even if validation failed
10-11	Resolve outcome	If solution wrong, restart Solution Stage with failure context (return to step 6); if validation wrong, restart Validation Stage with corrected criteria (return to step 6); if ambiguity is unresolvable, escalate; otherwise write omega/results.md and deliver
—	Inspect a subagent	/resume <task-id>
—	Recurse a stage	Create omega/ inside working folder, /fleet again

Subagent prompt template

Role: <Solution Stage | Validation Stage>
Working folder: <platform-appropriate absolute path, e.g. C:\repo\omega\solution\ or /workspace/omega/solution/>
Problem: <paste contents of omega/problem.md>
Task: <produce a solution artifact following the design process | follow the Validation Stage constraints below exactly>
Constraints:
- You have no access to the other stage.
- MUST NOT create, modify, or delete files outside your working folder.
- MUST NOT ask the human for validation.
- IF omega/problem.md contains an "## Applicable Skills" section: read each listed SKILL.md before starting work and apply each skill at the stage appropriate to its purpose, as described in the skill's SKILL.md.
- IF your role is Solution Stage: MUST follow the top-down design process (conceptual model → architecture → components → classes → implementation). Write `design.md` before writing any implementation code. IF any design level is too complex for one pass, recurse at that level.
- IF your role is Validation Stage:
  - derive acceptance criteria from `problem.md` independently of the solution.
  - write `concept.md` documenting: the acceptance criteria, your chosen validation approach, and the entry point command to run your validation artifact.
  - choose the validation approach in this priority order: (1) unit and component tests in the solution's native language and framework; (2) Python, if native testing is not possible or insufficient; (3) any other tool or script if neither is viable.
  - produce a validation artifact that is fully automated and exits non-zero on any failure.
  - assume the Ω Stage will execute your entry point with the working directory set to `omega/` and pass the absolute path to `omega/solution/` as the first command-line argument. If your artifact relies only on the working directory instead, document that explicitly in `concept.md`.
- IF too complex for one pass, MUST recurse: create `omega/` in your working folder and follow the Omega Protocol as defined in <absolute path to this README>.
  Complexity signals (any one is sufficient):
  - General signals: multiple independent deliverables; multiple distinct technical domains; success criteria that cannot be verified by one artifact; or completion would require abandoning partial work mid-execution.
  - Design-pattern or architecture signals: Builder, Bridge, Facade, Strategy, Abstract Factory, Composite, Layered, Client-Server, Microservices/SOA, Event-Driven, Pipe-and-Filter, Broker, Microkernel, cross-technology-boundary, infrastructure-before-application, or build-test-deploy pipeline.
- IF the work contains multiple independent parallel units that do NOT each require their own validation cycle, MUST decompose into subtasks instead of recursing: see the Subtask decomposition section of <absolute path to this README>.

## Prior Work (INCREMENTAL updates only — omit for FRESH-START)
Update mode: INCREMENTAL
Problem delta:
<paste the ## Problem Delta section from omega/problem.md>
Existing artifacts to evolve (do not rewrite what the delta does not affect):
- design.md: <path>
- Source files: <list key files>
- Build system: <CMakeLists.txt / package.json / etc.>
Apply the refactoring skill throughout — treat every changed requirement as a refactoring task on the existing code.

Every subagent receives ONLY: the problem statement, working folder, role, the absolute path to this protocol document, and (for INCREMENTAL updates) the ## Prior Work section. Nothing else beyond those inputs. Environmental context such as OS, shell, runtime, and available tools MUST be captured in omega/problem.md, not passed separately.

---

Skill Agents

Normative once matched. The Ω Stage scans this catalogue at step 4 of the checklist and writes matching skills into omega/problem.md. Once listed there, both subagents are required to read and apply them. This section grows over time as new skills are added.

General

⚠️ These are always-applicable rules for the Ω Stage. They are not discoverable skill agents — they apply to every execution regardless of which skills are matched at step 4.

• Exit code 0 and empty stderr do not prove the solution worked. A process can complete silently while having produced no meaningful output — a failed buffer upload, a skipped render call, or a misconfigured pipeline all exit cleanly. Always verify output against expected content, not just process exit status.
• When a visual capture looks unexpectedly uniform, suspect a silent upstream failure. Check the full pipeline: did the loader initialize? Did the shader compile? Did the buffer upload succeed? Add diagnostic output (e.g. print library version, check return values) to locate the silent failure before concluding the solution is wrong.

Language: C++

• Use the cpp-lint skill for static analysis of C++ solutions. It runs cppcheck and clang-tidy if available, skips gracefully if a tool is missing, and exits non-zero on any error. Invoke from the Validation Stage or as a pre-judgment gate. See .github/skills/cpp-lint/SKILL.md.

• Use the cpp-format skill to format C++ source files with clang-format. Run without --check in the Solution Stage after generating code; run with --check in the Validation Stage to verify compliance. Uses .clang-format config if present, falls back to --style=LLVM. Skips gracefully (exit 3) if clang-format is not on PATH. See .github/skills/cpp-format/SKILL.md.

• Use the cpp-packages skill to install C++ open-source dependencies via vcpkg. Supports manifest mode (vcpkg.json) and classic mode (explicit package list). Covers CMake integration (CMAKE_TOOLCHAIN_FILE, find_package with CONFIG), triplets, and a curated table of common packages (SDL2, GLFW, GLM, GLAD, nlohmann-json, fmt, spdlog, Catch2, etc.). Skips gracefully (exit 0) if vcpkg is not found. See .github/skills/cpp-packages/SKILL.md.

Software Architecture

• Use the software-architecture skill whenever the Solution Stage is writing design.md — specifically at level 2 (Architecture), which is a required step for every problem. Even simple systems benefit from a conscious architecture choice (e.g. confirming a single-layer approach is appropriate rather than assuming it). The skill covers all 9 core patterns (Layered, Client-Server, Event-Driven, Microservices, Microkernel, Space-Based, Pipe-Filter, Broker, Peer-to-Peer) with applicability guides, pros/cons, critical rules, and a common anti-pattern table. Source: geeksforgeeks.org. See .github/skills/software-architecture/SKILL.md.

• Use the architecture-documentation skill whenever the Solution Stage is writing design.md. arc42 provides the structure for that document — context, building blocks, runtime view, deployment view, decisions, quality requirements. Even simple problems use arc42 lean mode, which documents which sections are not applicable rather than omitting structure entirely. Also applies when ADRs must be produced or when multiple architectural views are required. The skill covers all 12 arc42 sections with lean vs thorough guidance, ADR format, quality scenario templates, and a section-to-Omega-Protocol mapping table. Source: docs.arc42.org. See .github/skills/architecture-documentation/SKILL.md.

• Use the uml skill whenever the Solution Stage is writing design.md. Class diagrams at level 4, component diagrams at level 3, and sequence or state diagrams for behaviour are the norm. Even simple systems benefit from a conscious choice of which diagram type to use — or a documented decision to omit them. Also applies when arc42 sections need visual models. The skill covers all 14 UML 2.5 diagram types with purpose, key elements, notation rules, and an arc42 section mapping. Includes PlantUML text-based snippets for use in design.md. Source: uml-diagrams.org. See .github/skills/uml/SKILL.md.

Code Quality

• Use the refactoring skill whenever the Solution Stage is in the implementation phase (design.md level 5). Code smells can emerge during active development, not just in pre-existing code — the skill must be available before smells are spotted, not after. Also applies explicitly when a problem requires refactoring existing code. The skill contains the full code smell catalogue (Bloaters, Change Preventers, OO Abusers, Dispensables, Couplers), maps each smell to its refactoring technique, and enforces the rule: one smell → one technique → verify. Source: refactoring.guru. See .github/skills/refactoring/SKILL.md.

• Use the design-patterns skill whenever the Solution Stage is writing code with more than one class, module, or component. Any non-trivial implementation benefits from conscious pattern selection — even if only to confirm a simpler approach is appropriate. Also applies when a recursion criterion pattern signal fires, or when the Solution Stage is designing architecture or components. The skill covers all 22 patterns (Creational, Structural, Behavioural) with intent, applicability, structure, and pattern relationships. Source: refactoring.guru/design-patterns. See .github/skills/design-patterns/SKILL.md.

Operating System: Windows

• Visual capture — use the visual-capture skill. It encapsulates the correct Win32 approach (PrintWindow with PW_CLIENTONLY), uniformity verification, and deterministic process cleanup (WM_CLOSE → wait → force-kill by PID). See .github/skills/visual-capture/SKILL.md.

Validation

• Image comparison — use the image-comparison skill when the Validation Stage must verify that a produced image matches a reference, or that image quality meets a threshold. The skill provides MSE, PSNR, and SSIM definitions and formulas, quality threshold tables (PSNR: ≥40 dB excellent; SSIM: ≥0.95 excellent), and a ready-to-use Python script (image_compare.py) that computes all three metrics with --psnr-threshold, --ssim-threshold, and --require-identical flags. Sources: MSE, PSNR, SSIM. See .github/skills/image-comparison/SKILL.md.

Graphics API: OpenGL

• Use the opengl skill when the problem specifies OpenGL. It covers loader setup (vcpkg glad package preferred, CMake FetchContent as fallback — never hand-craft), mandatory glGetError and shader compilation checking, initialization order, diagnostic output, and common silent failure patterns. See .github/skills/opengl/SKILL.md.
• Hand-crafted GLAD loaders are error-prone. A single wrong hex value (e.g. GL_STATIC_DRAW = 0x88B4 instead of 0x88E4) causes glBufferData to silently fail with GL_INVALID_ENUM, leaving the VBO empty with no visible error and no stderr output.

Graphics API: Vulkan

• Use the vulkan skill when the problem specifies Vulkan. It covers SDK setup, mandatory validation layers (VK_LAYER_KHRONOS_validation), VkResult checking, initialization order, SPIR-V shader compilation via glslc, diagnostic output, and common silent failure patterns. See .github/skills/vulkan/SKILL.md.
• Vulkan is completely silent without validation layers. Invalid usage produces no error, no crash, and no visible output. Always enable VK_LAYER_KHRONOS_validation during development.

Math Documentation

• Use the math-documentation skill when the solution or documentation requires mathematical notation rendered in a browser — formulas, equations, matrices, integrals, sums, or any LaTeX math. The skill covers MathJax (full LaTeX, accessible) and KaTeX (fast, lighter subset) with setup, delimiters, essential LaTeX notation, aligned equation environments, and common mistakes. Use MathJax by default; use KaTeX when load speed is critical. Sources: mathjax.org, katex.org. See .github/skills/math-documentation/SKILL.md.