codex-orchestra

English

Overview

codex-orchestra is a global Antigravity skill for orchestration between Antigravity and Codex.

It prepares external artifact folders, generates compact review packs, and produces a ready-to-paste handoff prompt for Codex.

Why Use It

If you already work with Antigravity and Codex, the painful part is rarely "thinking of one more prompt". The painful part is handoff quality:

• important context is scattered across chat history
• review prompts become too long or too vague
• absolute paths and artifact locations are lost
• planning and implementation review mix together
• the AI jumps into fixing code before the problem is framed properly

codex-orchestra solves that by turning messy chat context into a compact, structured review handoff.

Who It Is For

• solo builders who want repeatable AI review workflows
• developers who move between planning in one tool and execution/review in another
• teams experimenting with agent orchestration but wanting a lightweight skill instead of a full platform

What You Get

• a reusable skill instead of rewriting long prompts every time
• a stable folder structure for review artifacts
• a compact handoff file for Codex instead of dumping raw context
• a clearer boundary between planning and fixing

Features

• Two user-facing entry points: /codex-plan and /codex-work
• External artifact storage outside Antigravity and outside the target project
• Compact review packs for Codex reviewers such as plan-critic, phase-audit, and merge-gate
• Absolute-path handoff for reproducible review context
• Deterministic /codex-plan override behavior on mixed prompts
• Density-aware review-pack generation with Low and Max modes

Typical Before / After

Before:

• "Here is the bug, here is the old plan, here are the files, here is the screenshot, please review"
• too much chat context, weak structure, inconsistent results

After:

• /codex-plan
• codex-orchestra creates the artifact set and a compact current-plan-pack.md
• Codex gets a tighter, cleaner, more reviewable handoff

Review Density

The skill chooses one of two internal review densities before generating current-plan-pack.md.

• Low: for local, narrow, low-ambiguity tasks
• Max: for multi-layer or system-level tasks that need a broader evidence-first review pack

The goal is not to produce longer documents. The goal is to preserve compactness while widening the review surface only when needed.

Install

Copy SKILL.md to your Antigravity global skills folder:

%USERPROFILE%\.gemini\antigravity\skills\codex-orchestra\SKILL.md

Recommended layout:

%USERPROFILE%\.gemini\antigravity\skills\
  codex-orchestra\
    SKILL.md

Usage

Use /codex-plan when you want planning, plan review preparation, or a clean handoff package before implementation.

Use /codex-work when work already happened and you want a retrospective review pack based on changed files, context, and current state.

Typical /codex-plan message:

Я нашёл критический баг при тесте:
не показывается страница «Настройки» (пустая). Смотри приложенный скрин.

/codex-plan

More examples:

• examples/basic-plan.md
• examples/mixed-prompt-plan.md
• examples/work-review.md

Artifact Policy

Artifacts are stored under:

%USERPROFILE%\Documents\AI-Orchestra\<ProjectFolderName>\

The skill keeps:

• _meta/
• state/
• runs/
• review-packs/
• reviews/
• index/

It should not write service artifacts into the Antigravity runtime folder or into the target project source tree unless the user explicitly asks for that.

Validation Status

Current validation summary is tracked in docs/smoke-test-status.md.

Short version:

• /codex-plan passed a real mixed-prompt smoke test
• deterministic override behavior for /codex-plan is proven on a real bug-report flow
• Low / Max density logic is implemented in the skill
• /codex-work is not yet proven by a real smoke test

Repository Layout

codex-orchestra/
  SKILL.md
  README.md
  CHANGELOG.md
  LICENSE
  LICENSE.ru.md
  examples/
  docs/

Known Limitations

• Antigravity does not expose native slash-command registration for skills
• Activation still depends on Antigravity selecting the skill from prompt relevance and description matching
• /codex-work still needs a real end-to-end validation run

Publishing Workflow

This folder is intended to be the canonical source for GitHub publishing.

Recommended workflow:

1. Edit the canonical copy in this folder.
2. Copy SKILL.md into the Antigravity runtime skills directory.
3. Run smoke tests.
4. Update CHANGELOG.md.
5. Commit and publish this folder to GitHub.

Русский

Обзор

codex-orchestra — это глобальный skill для Antigravity, который организует handoff между Antigravity и Codex.

Он создаёт внешние папки артефактов, собирает компактные review-pack файлы и выдаёт готовую строку для передачи задачи в Codex.

Зачем это нужно

Если ты уже работаешь с Antigravity и Codex, проблема обычно не в том, чтобы “написать ещё один промт”. Проблема в качестве handoff:

• важный контекст размазан по истории чата
• review-промты получаются либо слишком длинными, либо слишком слабыми
• absolute paths и пути к артефактам теряются
• планирование и исправление кода смешиваются
• ИИ прыгает в фикс до того, как задача нормально оформлена

codex-orchestra решает это, превращая хаотичный чат-контекст в компактный и структурированный review handoff.

Для кого это

• для соло-разработчиков, которым нужен повторяемый AI review workflow
• для разработчиков, которые планируют в одном инструменте, а ревьюят/исполняют в другом
• для команд, которые пробуют agent orchestration, но не хотят сразу строить тяжёлую платформу

Что ты получаешь

• переиспользуемый skill вместо постоянного переписывания длинных промтов
• стабильную структуру папок для review-артефактов
• компактный handoff-файл для Codex вместо сырого дампа контекста
• более чёткую границу между планированием и фиксом

Возможности

• Две пользовательские точки входа: /codex-plan и /codex-work
• Хранение артефактов вне Antigravity и вне целевого проекта
• Компактные review-pack файлы для ревьюеров Codex: plan-critic, phase-audit, merge-gate
• Absolute paths для воспроизводимого handoff
• Детерминированный override для /codex-plan в mixed prompt
• Генерация review-pack с режимами плотности Low и Max

Типичный сценарий: до и после

До:

• «Вот баг, вот старый план, вот файлы, вот скрин, проверь всё это»
• слишком много chat-контекста, слабая структура, нестабильный результат

После:

• /codex-plan
• codex-orchestra создаёт набор артефактов и компактный current-plan-pack.md
• Codex получает более чистый и удобный для ревизии handoff

Режимы плотности

Перед генерацией current-plan-pack.md skill выбирает один из двух внутренних режимов плотности.

• Low: для локальных и относительно узких задач
• Max: для многослойных или системных задач, где нужен чуть более широкий evidence-first пакет

Цель не в том, чтобы писать длиннее. Цель — сохранить компактность и расширять поверхность ревизии только тогда, когда это действительно нужно.

Установка

Скопируйте SKILL.md в папку глобальных skills Antigravity:

%USERPROFILE%\.gemini\antigravity\skills\codex-orchestra\SKILL.md

Рекомендуемая структура:

%USERPROFILE%\.gemini\antigravity\skills\
  codex-orchestra\
    SKILL.md

Использование

Используйте /codex-plan, когда нужен план, подготовка review-pack перед реализацией или чистый handoff для ревизии.

Используйте /codex-work, когда работа уже сделана и нужно собрать retrospective review pack по изменённым файлам, текущему состоянию и контексту.

Типичный пример /codex-plan:

Я нашёл критический баг при тесте:
не показывается страница «Настройки» (пустая). Смотри приложенный скрин.

/codex-plan

Больше примеров:

• examples/basic-plan.md
• examples/mixed-prompt-plan.md
• examples/work-review.md

Политика артефактов

Артефакты хранятся по пути:

%USERPROFILE%\Documents\AI-Orchestra\<ProjectFolderName>\

Skill использует:

• _meta/
• state/
• runs/
• review-packs/
• reviews/
• index/

Служебные артефакты не должны писаться в runtime-папку Antigravity или в исходники проекта, если пользователь явно этого не попросил.

Статус валидации

Актуальный статус валидации находится в docs/smoke-test-status.md.

Коротко:

• /codex-plan прошёл реальный mixed-prompt smoke test
• deterministic override для /codex-plan подтверждён на реальном баг-репорте
• логика плотности Low / Max уже реализована в skill
• /codex-work пока не подтверждён реальным smoke test

Структура репозитория

codex-orchestra/
  SKILL.md
  README.md
  CHANGELOG.md
  LICENSE
  LICENSE.ru.md
  examples/
  docs/

Известные ограничения

• В Antigravity нет нативной регистрации slash-команд для skills
• Активация всё ещё зависит от того, выберет ли Antigravity skill по релевантности и description matching
• /codex-work всё ещё требует реального end-to-end smoke test

Workflow публикации

Эта папка является каноническим исходником для GitHub.

Рекомендуемый процесс:

1. Редактировать каноническую копию в этой папке.
2. Копировать SKILL.md в runtime-папку skills Antigravity.
3. Запускать smoke test.
4. Обновлять CHANGELOG.md.
5. Коммитить и публиковать эту папку в GitHub.