Codex Orchestra

Используется, когда нужен план, ревизия плана или подготовка к плановой работе.

/codex-work

Используется, когда уже были изменения, фикс, рефакторинг, исследование, работа без плана или завершение задачи.

Больше внешних команд нет. Внутри skill может запускать любые внутренние сценарии.

2. ОБЛАСТЬ ДЕЙСТВИЯ И БЕЗОПАСНОСТЬ

Определение проекта

1. Определи текущий активный проект по рабочей директории / root workspace / root repository.
2. Получи ТОЧНОЕ имя папки текущего проекта (basename пути).
3. Определи PROJECT_ROOT — полный абсолютный путь к корню проекта.
4. Определи ARTIFACT_ROOT:

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

   Например: если проект в C:\Users\USER\Documents\My Apps\Win Server Manager, то артефакты будут в C:\Users\USER\Documents\AI-Orchestra\Win Server Manager\.

Правила безопасности

• НЕ хранить служебные артефакты в папке Antigravity (~/.gemini/antigravity/).
• НЕ хранить служебные артефакты в репозитории проекта (если пользователь явно не попросил).
• Работать только с папкой артефактов, чьё имя ТОЧНО совпадает с именем текущей папки проекта.
• Хранить _meta/project-root.txt с полным абсолютным путём проекта для защиты от коллизий.
• Если имя проекта совпадает, но путь в project-root.txt отличается — НЕ пиши ничего автоматически. Коротко спроси пользователя.
• НЕ выдумывай данные. Если данных не хватает — пиши Unknown.
• НЕ редактируй исходный код проекта в рамках этого skill (если пользователь явно не попросил).

3. ЛОГИКА /codex-plan

Когда пользователь вызывает /codex-plan, первое и обязательное поведение — это подготовка артефактов:

• определить пути (PROJECT_ROOT / ARTIFACT_ROOT),
• создать или обновить state/run/review-pack,
• выдать отчёт,
• дать готовую строку для Codex. Любые действия по фиксу до завершения этих шагов запрещены.

При вызове /codex-plan выполни алгоритм строго по шагам:

1. Определить проект — получить PROJECT_ROOT и ARTIFACT_ROOT (без чтения и анализа исходников для фикса).
2. Создать внешнюю папку артефактов, если её нет.
3. Создать базовую структуру артефактов (см. раздел 6), если её ещё нет.
4. Проверить конфликт project-root — если _meta/project-root.txt существует и путь отличается, спросить пользователя.
5. Понять, есть ли уже план:
   • в текущем чате
   • в ранее созданных документах
   • в заметках / контексте / истории работы
6. Если план уже есть → сохранить в структурированном виде.
7. Если плана нет, но задача понятна → предложить план самостоятельно и сохранить.
8. Если задача слишком расплывчата → задать короткий вопрос (см. раздел 6).
9. Если пользователь уже обсуждал задачу до вызова /codex-plan → использовать контекст из чата, а не требовать пересказ.
10. Создать run-папку вида YYYY-MM-DD_HH-mm-ss__plan__<slug> внутри runs/YYYY/.
11. Заполнить state-файлы: current-task.md, current-plan.md, current-run.md, current-risks.md, current-open-questions.md.
12. Заполнить run-файлы: request.md, context.md, plan.md, manifest.json.
13. Создать review-packs/current-plan-pack.md (формат — раздел 11A).
14. Выдать отчёт (формат — раздел 13).

4. ЛОГИКА /codex-work

Когда пользователь вызывает /codex-work:

1. Определить проект — получить PROJECT_ROOT и ARTIFACT_ROOT.
2. Найти или создать внешнюю папку артефактов.
3. Создать базовую структуру артефактов, если её ещё нет.
4. Восстановить актуальное состояние, даже если:
   • skill раньше не использовался
   • план был неформальный
   • плана вообще не было
   • изменения уже внесены
5. Собрать информацию из:
   • текущего чата
   • истории действий в рамках сессии
   • git diff / changed files (если доступно)
   • локальных файлов проекта (если безопасно)
   • ранее созданных артефактов
6. Если plan отсутствовал → Plan Status: absent or reconstructed.
7. Создать run-папку с подходящим kind (feature, fix, refactor, research, review, hotfix, ops).
8. Заполнить state-файлы: все current-*.md.
9. Заполнить run-файлы: все файлы run (request.md, context.md, plan.md, implementation.md, decisions.md, changed-files.md, checks.md, risks.md, questions.md, handoff.md, manifest.json).
10. Создать review-packs/current-phase-pack.md (формат — раздел 11B).
11. Если работа близка к завершению или это финальная проверка → дополнительно создать review-packs/current-merge-pack.md (формат — раздел 11C).
12. Выдать отчёт (формат — раздел 13).

Важно: /codex-work работает ретроспективно. Если пользователь уже сделал изменения — собери максимум контекста и подготовь пакет.

5. УТОЧНЯЮЩИЕ ВОПРОСЫ

Задавай вопрос только если без этого высок риск ошибки:

• Не удаётся понять корень проекта
• Найден конфликт project-root
• Задача неясна
• Непонятно, речь о плане или об уже сделанной работе
• Непонятно, нужен phase-review или финальный merge-gate

Формат вопросов:

• Коротко
• С 2–4 вариантами
• Чтобы пользователь мог ответить одним словом

Примеры:

• «Что готовить для Codex: план, реализация или финал?»
• «Использовать существующую папку артефактов или остановиться?»
• «Это новый run или продолжение текущего?»

После короткого ответа — продолжай автоматически.

6. БАЗОВАЯ СТРУКТУРА ПАПОК

Создавай и используй эту структуру в ARTIFACT_ROOT:

<ARTIFACT_ROOT>/
├── _meta/
│   ├── project.md
│   ├── project-root.txt
│   └── artifact-policy.md
├── state/
│   ├── current-task.md
│   ├── current-plan.md
│   ├── current-run.md
│   ├── current-risks.md
│   ├── current-changed-files.md
│   ├── current-checks.md
│   ├── current-open-questions.md
│   └── current-handoff.md
├── runs/
│   └── YYYY/
│       └── YYYY-MM-DD_HH-mm-ss__<kind>__<slug>/
│           ├── request.md
│           ├── context.md
│           ├── plan.md
│           ├── implementation.md
│           ├── decisions.md
│           ├── changed-files.md
│           ├── checks.md
│           ├── risks.md
│           ├── questions.md
│           ├── handoff.md
│           └── manifest.json
├── decisions/
│   ├── ADR-NNNN-<slug>.md
│   └── index.md
├── review-packs/
│   ├── current-plan-pack.md
│   ├── current-phase-pack.md
│   └── current-merge-pack.md
├── reviews/
│   ├── codex-plan-critic/
│   ├── codex-phase-audit/
│   └── codex-merge-gate/
├── knowledge/
│   ├── architecture-map.md
│   ├── module-notes.md
│   └── glossary.md
└── index/
    ├── runs-index.md
    ├── decisions-index.md
    └── reviews-index.md

Описание папок:

• state/ — только актуальное текущее состояние
• runs/ — история по отдельным логическим сессиям
• review-packs/ — компактные входные файлы для Codex
• reviews/ — результаты ревизии Codex (заполняет Codex, не этот skill)
• decisions/ — архитектурные решения (ADR)
• knowledge/ — проектные знания
• index/ — короткие индексы для навигации

7. ВИДЫ RUN

При создании нового run используй один из видов:

• plan — планирование
• feature — новая функциональность
• fix — исправление бага
• refactor — рефакторинг
• research — исследование
• review — ревизия
• hotfix — срочное исправление
• ops — операционные задачи

Формат папки run:

YYYY-MM-DD_HH-mm-ss__<kind>__<slug>

Пример: 2026-04-13_11-45-00__fix__session-logout-bug

Если kind неясен → используй review или коротко спроси пользователя.

8. СОДЕРЖАНИЕ STATE-ФАЙЛОВ

state/current-task.md

# Current Task

## Task Summary
## Business / User Goal
## Constraints
## Acceptance Criteria
## Important Context
## Source of Truth
## Status

state/current-plan.md

# Current Plan

## Task
## Constraints
## Assumptions
## Proposed Solution
## Alternatives Considered
## Risks
## Files Likely To Change
## Why This Approach
## Plan Status

state/current-run.md

# Current Run

## Active Run Path
## Run Kind
## Started At
## Last Updated
## Current Focus
## Related Files
## Status

state/current-risks.md

# Current Risks

## High Risks
## Medium Risks
## Low Risks
## Unknowns

state/current-changed-files.md

# Changed Files

## Changed Files
## Why Each File Changed
## Suspected Impact Areas

state/current-checks.md

# Current Checks

## Checks Run
## Results
## Failures
## Checks Not Run
## Confidence Level

state/current-open-questions.md

# Open Questions

## Open Questions
## Decisions Needed
## Missing Information

state/current-handoff.md

# Current Handoff

## What Was Done
## What Remains
## Known Issues
## Recommended Next Step
## Codex Review Readiness

9. СОДЕРЖАНИЕ RUN-ФАЙЛОВ

request.md

• Original Request
• Restated Goal
• Initial Constraints
• Source Context

context.md

• Project Context
• Affected Modules
• Existing Behavior
• Relevant History
• Environment Notes

plan.md

• Task
• Constraints
• Assumptions
• Proposed Solution
• Alternatives Considered
• Risks
• Files Likely To Change
• Why This Approach
• Confidence

implementation.md

• What Was Implemented
• Why
• Deviations From Plan
• Observed Problems
• Pending Work

decisions.md

• Decision Log
• Rejected Alternatives
• Why Chosen
• Consequences

changed-files.md

• Files
• Intent of Each Change
• Possible Side Effects

checks.md

• Checks Run
• Results
• Not Run
• Why Not Run

risks.md

• Active Risks
• Mitigations
• Unresolved Concerns

questions.md

• Questions Asked
• Answers Received
• Outstanding Questions

handoff.md

• Goal
• What Was Done
• Files Modified
• Checks Run
• Known Issues
• Follow-up Work
• Why These Changes

manifest.json

{
  "project_name": "<string>",
  "project_root": "<absolute path>",
  "artifact_root": "<absolute path>",
  "run_path": "<absolute path to run folder>",
  "run_kind": "<kind>",
  "slug": "<slug>",
  "created_at": "<ISO 8601>",
  "updated_at": "<ISO 8601>",
  "plan_status": "draft | approved | absent | reconstructed",
  "review_pack_paths": ["<absolute paths>"],
  "relevant_files": ["<relative paths>"],
  "status": "active | completed | abandoned"
}

10. СОДЕРЖАНИЕ И РЕЖИМЫ REVIEW-PACK ФАЙЛОВ ДЛЯ CODEX

Каждый review-pack — это готовый пакет для Codex со встроенной инструкцией. Пользователь должен просто скопировать путь к файлу в Codex.

10.1. РЕЖИМЫ ПЛОТНОСТИ (REVIEW DENSITY): LOW / MAX

Skill должен сам определить режим плотности review-pack и явно записывать его в Meta как Review Density: Low / Max.

Правило выбора:

• По умолчанию: Low.
• Повышение до Max: если есть хотя бы один сильный признак системности или многослойности.
• Сомнения: если сомневаешься, выбирай Low (если это не создаёт высокого риска ложной диагностики).
• Max не означает «много текста»; это означает «чуть шире охват и больше инженерных проверок».

🟢 Режим Low

Признаки: 1 явный баг или 1 локальная задача. Не более 1–2 вероятных файлов изменений. Нет признаков архитектурного затрагивания, миграций, вопросов безопасности, производительности, конкурентности, интеграций, сетевого каскада. Нет неоднозначности в нескольких слоях системы. Исторический контекст не обязателен. Правила: Держать пакет очень компактным. Не дублировать одно и то же между секциями. Не тащить лишний контекст! Ограничения:

• Task Summary: 1–2 предложения
• Constraints: до 3 bullets
• Evidence To Collect First: 2–4 bullets
• Proposed Plan Summary: до 3 bullets
• Assumptions: до 3 bullets
• Alternatives: до 2 bullets
• Risks: до 2 bullets
• Questions: до 2 bullets
• Files Likely To Change: до 3 файлов

🔴 Режим Max

Признаки: Несколько возможных слоёв (frontend/backend/api/router/state/data). Баг может быть системным. Риск затронуть несколько модулей. Вероятность регрессий. Конфликтующие гипотезы. Нехватка ключевых фактов. Правила: Pack всё равно должен быть умеренным (он не должен превращаться в длинный аналитический документ), но с расширенным охватом. Сохраняй строгую компактность. Разрешается краткий блок системных зависимостей. Ограничения:

• Task Summary: до 2 предложений
• Constraints: до 4 bullets
• Evidence To Collect First: 3–6 bullets
• Proposed Plan Summary: до 5 bullets
• Assumptions: до 5 bullets
• Alternatives: до 3 bullets
• Risks: до 5 bullets
• Questions: до 5 bullets
• Files Likely To Change: до 5 файлов

A. current-plan-pack.md

Синхронизация перед генерацией:

• Не теряй важные гипотезы из plan.md.
• Не теряй acceptance context из current-task.md.
• Не выкидывай backend/API ветку без причины.
• Не фантазируй; если мало данных, указывай Unknown или open question.

# Plan Review Pack

## Meta
- Project Name: <name>
- Project Root: <absolute path>
- Artifact Root: <absolute path>
- Active Run: <absolute path to run folder>
- Review Mode: plan-critic
- Teaching Mode: on
- Review Density: <Low | Max>

## Task Summary
<Краткое описание задачи в рамках лимитов режима. Включи acceptance context>

## Constraints
<Соблюдай лимит пунктов по режиму>

## Evidence To Collect First
<Компактный блок фактов до фиксов (важно: не прыгать сразу в код!): console errors, network/API failures, DOM visibility/class state, route activation path, reproduction steps. Соблюдай лимиты режима>

## Proposed Plan Summary
<Суть плана исходя из plan.md и гипотез. Соблюдай лимиты режима>

## Assumptions
<Соблюдай лимиты режима>

## Alternatives Already Considered
<Не пиши "Никаких", если в плане есть ветка! Review-pack не должен быть беднее plan.md. Укажи хотя бы кратко даже слабую альтернативу. Соблюдай лимиты>

## Key Risks
<Соблюдай лимиты режима>

## Open Questions
<Соблюдай лимиты режима>

## Files Likely To Change
<ВСЕГДА указывать ABSOLUTE PATHS. Если неясен — пиши Unknown. Соблюдай лимиты (до 3 файлов для Low, до 5 для Max)>

---

## Codex Instruction (plan-critic)

Ты — plan-critic. Прочитай план выше и проведи критическую ревизию.

**Фокус:**
- Скрытые риски
- Слабые допущения
- Архитектурные компромиссы
- Лучшие альтернативы
- Потенциально более простое или надёжное решение

**Правила:**
- Не соглашайся по умолчанию
- Не уходи в пустую контрарность
- Если критикуешь — предлагай лучший вариант
- Объясняй, почему твоё решение сильнее
- Параллельно обучай пользователя инженерному мышлению на примере этого кейса

**Ограничения:**
- Максимум 5 сильных замечаний
- Максимум 3 разумные альтернативы
- Обязательный финальный verdict
- Не раздувай проблему, если её нет
- Не занимайся вкусовщиной без влияния на качество
- Если данных мало, укажи уровень уверенности, не фантазируй

## Expected Output Format

Verdict: keep / revise / replace

Main Risks:

• ...

Better Alternatives:

• ...

Recommended Approach: ...

Why: ...

Engineering Principle: ...

What To Notice Next Time: ...

B. current-phase-pack.md

# Phase Audit Pack

## Meta
- Project Name: <name>
- Project Root: <absolute path>
- Artifact Root: <absolute path>
- Active Run: <absolute path to run folder>
- Review Mode: phase-audit
- Teaching Mode: on

## Task Summary
<краткое описание задачи>

## Plan Summary
<суть плана, если был>

## Plan Status
<draft | approved | absent | reconstructed>

## What Was Implemented
<краткое описание реализации>

## Files Changed
<до 10 файлов с кратким описанием>

## Checks Summary
<что проверено, результаты>

## Known Risks
<до 5 рисков>

## Suspected Weak Spots
<подозрительные места>

## Questions For Review
<до 5 вопросов>

---

## Codex Instruction (phase-audit)

Ты — phase-auditor. Проверь, соответствует ли реализация задаче и фактическому контексту.

**Найди:**
- Баги
- Слабые места
- Пропущенные тесты
- Архитектурные риски
- Регрессии
- Неочевидные edge cases
- Избыточную сложность
- Технический долг, который уже вредит

**Правила:**
- Не трать время на мелкие stylistic nitpicks
- Будь критичным, но доказательным
- Если плана не было — оценивай по задаче и фактическому поведению
- Параллельно обучай пользователя фундаментальным принципам кодинга

**Ограничения:**
- Максимум 5 сильных замечаний
- Обязательный финальный verdict
- Если проблема незначительная — обозначай как minor
- Если решение рабочее — разрешай verdict ship

## Expected Output Format

Verdict: Ship / No Ship

Blockers:

• ...

Important Issues:

• ...

Missing Tests:

• ...

Recommended Fixes:

• ...

Why This Matters: ...

Engineering Principle: ...

What To Notice Next Time: ...

C. current-merge-pack.md

# Merge Gate Pack

## Meta
- Project Name: <name>
- Project Root: <absolute path>
- Artifact Root: <absolute path>
- Active Run: <absolute path to run folder>
- Review Mode: merge-gate
- Teaching Mode: on

## Task Summary
<краткое описание задачи>

## What Is Ready
<что готово к merge>

## Remaining Risks
<остающиеся риски>

## Test Summary
<результаты тестов>

## Architecture Impact
<архитектурные последствия>

## Breaking Change Risk
<риск ломающих изменений>

## Rollback Notes
<заметки по откату>

## Final Questions Before Merge
<финальные вопросы>

---

## Codex Instruction (merge-gate)

Ты — merge-gate reviewer. Проведи финальную жёсткую ревизию перед merge/release.

**Проверь:**
- Готовность к ship
- Риск поломок после merge
- Критические пробелы в тестах
- Опасные архитектурные компромиссы
- Неполные rollback considerations
- Последствия для продакшена и поддержки

**Правила:**
- Не раздувай проблему там, где её нет
- Фокусируйся на реальных release risks
- Параллельно обучай пользователя тому, как сильные инженеры принимают решение ship / no-ship

**Ограничения:**
- Максимум 5 сильных замечаний
- Обязательный финальный verdict
- Если данных мало — укажи уровень уверенности

## Expected Output Format

Final Verdict: ship / no-ship

Critical Risks:

• ...

Missing Verification:

• ...

Release Concerns:

• ...

Rollback Concerns:

• ...

Must Fix Before Merge:

• ...

Why: ...

Engineering Principle: ...

What To Notice Next Time: ...

11. ПРАВИЛО: НЕ ПЕРЕЗАТИРАЙ ИСТОЧНИКИ

• Исходный план хранится в state/ и runs/.
• review-pack — отдельный компактный пакет для Codex.
• Codex позже пишет отдельные review-файлы в reviews/.
• Исходные plan.md или implementation.md нельзя перезаписывать чужой критикой.

12. ФОРМАТ ОТЧЁТА ПОСЛЕ КАЖДОЙ КОМАНДЫ

После /codex-plan или /codex-work всегда выводи отчёт:

## ✅ Отчёт codex-orchestra

### Что сделано
<описание>

### Созданные / обновлённые файлы
| Файл | Абсолютный путь |
|------|----------------|
| ... | ... |

### Не удалось определить
<что не определено, или «Всё определено»>

### Готово для следующего шага
<что можно делать дальше>

### 📋 Готовая строка для Codex

Шаблон готовой строки для plan:

Прочитай файл:
<ABSOLUTE_PATH_TO_CURRENT_PLAN_PACK>
Выполни встроенную в нём инструкцию как plan-critic.
Не меняй исходный план. Создай отдельную ревизию.

Шаблон готовой строки для phase:

Прочитай файл:
<ABSOLUTE_PATH_TO_CURRENT_PHASE_PACK>
Выполни встроенную в нём инструкцию как phase-audit.
Не меняй исходную реализацию. Создай отдельную ревизию.

Шаблон готовой строки для merge:

Прочитай файл:
<ABSOLUTE_PATH_TO_CURRENT_MERGE_PACK>
Выполни встроенную в нём инструкцию как merge-gate.
Не меняй исходные артефакты. Создай отдельную ревизию.

Пути всегда показывай в АБСОЛЮТНОМ виде.

13. ЭКОНОМИЯ КОНТЕКСТА И ТОКЕНОВ

Жёсткие ограничения:

1. Не вставляй длинные логи целиком.
2. Не вставляй полный diff, если можно сделать краткую сводку.
3. В review-pack соблюдай динамические лимиты (Режимы Low / Max):
   • Файлы: до 3 (Low) или до 5 (Max)
   • Риски/Вопросы: соразмерно режиму плотности
   • Подробнее см. раздел 10.1.
4. Не дублируй длинный текст в нескольких файлах.
5. State-файлы должны быть компактными.
6. Архив истории — в runs/, в текущую работу поднимай только актуальное.
7. Не превращай мелкий фикс в архитектурный трактат.
8. Если риск низкий — помечай low-risk, не драматизируй.
9. Если контекста много — сначала компактная выжимка.

14. ПОВЕДЕНИЕ БЕЗ БЕСКОНЕЧНОЙ КРИТИКИ

Для каждого review-pack ограничивай ожидания:

• Максимум 5 сильных замечаний
• Максимум 3 разумные альтернативы
• Обязательный финальный verdict

Не поощряй:

• Пустую контрарность
• Вкусовщину без влияния на качество
• Лишние архитектурные переделки для локальных задач

Если проблема незначительная → обозначай как minor. Если решение рабочее → разрешай verdict keep / ship. Если данных мало → проси Codex указать уровень уверенности.

15. ПОВЕДЕНИЕ, ЕСЛИ ПЛАНА НЕ БЫЛО

Если /codex-work вызван без формального плана:

1. Не считай это ошибкой.
2. Реконструируй замысел из чата, контекста, изменённых файлов и фактической работы.
3. В state/current-plan.md и phase-pack укажи: Plan Status: absent or reconstructed.
4. Подготовь пакет так, чтобы Codex мог оценивать работу по задаче и поведению.

16. ПОВЕДЕНИЕ ПРИ НЕХВАТКЕ ДАННЫХ

• Не выдумывай → помечай Unknown.
• При необходимости задай 1 короткий вопрос.
• После ответа продолжай автоматически.
• Если часть данных реконструирована → пометь reconstructed.

17. ПОВЕДЕНИЕ ПРИ ПОВТОРНОМ ВЫЗОВЕ

• Не создавай хаос и дубликаты.
• Обновляй актуальные state-файлы.
• При необходимости создавай новый run.
• Сохраняй историю аккуратно.
• Обновляй current-*.md.
• Сохраняй старые run-папки как архив.

Если работа продолжается → обновляй текущий active run. Если новый логический кусок → создавай новый run.

18. _meta/project.md (шаблон)

# Project Metadata

## Project Name
<имя>

## Project Root
<абсолютный путь>

## Artifact Root
<абсолютный путь>

## First Seen
<дата ISO 8601>

## Last Updated
<дата ISO 8601>

## Main Languages / Stack
<языки и технологии>

## Main Modules
<основные модули>

## Notes
<заметки>

19. _meta/artifact-policy.md (шаблон)

# Artifact Policy

## Что хранится во внешних артефактах
- Планы, задачи, контекст, решения, риски, проверки
- Review-packs для Codex
- История runs
- Архитектурные решения (ADR)

## Что НЕ хранится
- Исходный код проекта (хранится в репозитории)
- Служебные файлы Antigravity
- Secrets, credentials, API keys

## Как устроены review-pack файлы
- Каждый review-pack — готовый пакет для Codex со встроенной инструкцией
- 3 вида: plan-pack (plan-critic), phase-pack (phase-audit), merge-pack (merge-gate)
- Компактные, до 10 файлов, до 5 рисков, до 5 вопросов

## Правило неперезаписи
- Исходные планы и реализации НЕ перезаписываются ревизиями Codex
- Ревизии Codex хранятся отдельно в reviews/

20. ADR / РЕШЕНИЯ

Если в ходе работы принято архитектурное или важное техническое решение, сохрани его в decisions/.

Формат: ADR-NNNN-<slug>.md

# ADR-NNNN: <title>

## Context
## Decision
## Alternatives
## Consequences
## Why Chosen

Номеруй последовательно. Обновляй decisions/index.md.