oh-my-antigravity (OmA)

OmA is a context-engineering-driven multi-agent workflow pack for Gemini CLI. It transforms Gemini CLI from a single-session assistant into a structured engineering workflow with separated roles.

Core Structure

• Core Files: GEMINI.md, agents/, commands/, skills/, context/
• Primary Use Case: Complex implementation tasks requiring a plan -> execute -> review loop.
• Interface: Controlled via /oma:* slash-commands, 8 deep-work $skills (including oma-plan alias), and sub-agent delegation.
• Model Strategy: Configurable via /oma:model. The default balanced lane split uses pro / flash / flash-lite aliases, which can be overridden with auto or custom.

OmA uses a 5-layer Context Layer Model to manage information flow and maintain stability during long AI sessions. This model ensures that the agent stays aligned with platform constraints while maintaining focus on active tasks without being overwhelmed by raw history.

The learn skill operates as a SessionEnd hook, meaning it automatically triggers at the conclusion of an OmA session. The lifecycle follows these steps:

1. Session Evaluation: The skill checks if the session meets the minimum message requirement (default is 10+ messages).
2. Pattern Detection: The system scans for extractable patterns, specifically focusing on:
   • Common Error Resolutions: Recurring error fixes.
   • Environment Workarounds: Fixes for tool or framework quirks.
   • Style/Conventions: Project-specific rules.
   • Corrected Behaviors: Mistakes the agent should avoid.
3. Skill Extraction: Useful patterns are saved as new rules in the .omg/rules/learned/ directory.

The OmA project structure organizes state, commands, and context as follows:

oh-my-antigravity/
|- GEMINI.md
|- gemini-extension.json
|- .omg/
|  `- state/
|     |- session-lock.json
|     `- interviews/
|     |  |- active.json
|     |  `- [slug]/
|     |     |- context.json
|     |     `- prd.md
|     `- sessions/
|        `- [session-slug]/
|           |- workspace.json
|           |- taskboard.md
|           |- workflow.md
|           `- checkpoint.md
|- agents/
|- commands/
|  `- omg/
|- skills/
|- context/
|- docs/
`- LICENSE

Key directories:

• .omg/state/: Stores session locks, interview contexts, and workspace/taskboard states.
• agents/: Contains agent definitions.
• commands/omg/: Contains OmA specific commands.
• skills/: Contains reusable skills.
• context/: Contains shared context files.

To ensure stability and avoid duplicate outputs or outdated behavior, follow these rules regarding the OmA extension boundary:

• Installation/Updates: Always use gemini extensions ... in the terminal. Do not treat the copied command/skill folders as your primary runtime path.
• Hook Registration: Ensure there is only one authoritative path for OmA hook registration per event. Mixing extension management hooks with manual duplicates can cause AfterAgent output duplication.
• Troubleshooting Updates: If OmA appears outdated after an update, check gemini extensions list and perform a refresh or reinstall before manually editing any shipped files.
• Preflight Check: For long-running or multi-lane tasks, use /oma:workspace audit as a default preflight check before running review, automation, or team-exec.

OmA uses a single-writer lock mechanism to manage shared workflow and operating-profile state to prevent corruption during parallel tasks.

• The Lock: .omg/state/session-lock.json acts as the single-writer lock for the project.
• Orchestrator Role: Only the orchestration session holding the lock is permitted to write to shared files such as workspace.json, taskboard.md, workflow.md, checkpoint.md, mode.json, hud.json, approval.json, reasoning.json, hooks.json, and notify.json.
• Parallel Sessions: Parallel top-level sessions that do not hold the lock should write to session-local drafts in .omg/state/sessions/[session-slug]/ and then return them to the orchestrator for merging.
• Sub-agents: Delegated worker or sub-agent turns should remain 'read-mostly' and must not directly mutate shared workflow state.

OmA addresses several limitations of standard single-session LLM workflows:

OmA uses a structured state management system to prevent conflicts in multi-agent or parallel workflows.

• Authoritative Writer Lock: .omg/state/session-lock.json acts as a lock. Only the orchestration session holding this lock is permitted to update shared files like workspace.json, taskboard.md, workflow.md, checkpoint.md, mode.json, hud.json, approval.json, reasoning.json, hooks.json, and notify.json.
• Parallel Sessions: Parallel top-level sessions should not overwrite shared state. Instead, they should create session-local drafts under .omg/state/sessions/[session-slug]/ and pass them to the orchestrator for merging.
• Delegated Workers: Sub-agents or delegated workers should not modify the shared workflow state directly.

OmA manages /oma:interview session states within the .omg/state/interviews/[slug]/ directory rather than using a single shared interview file.

• Tracking: The file .omg/state/interviews/active.json tracks the current interview.
• Purpose: This structure allows for deterministic resume/status behavior and enables the distinction and archiving of multiple requirements discovery passes within the same project.