# Codex Project Autopilot

Локальный плагин для Codex, который превращает сырую идею в понятный проектный маршрут: вопросы, brief, план, реализация, проверка и финальный handoff.

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

Поддерживаемые платформы для локальной работы: macOS, Linux и Windows.

## Зачем он нужен

Обычный сценарий работы с ИИ выглядит так:

- пользователь пишет идею
- модель отвечает слишком общо или сразу прыгает в код
- важные требования теряются по ходу диалога
- архитектура, дизайн, безопасность и handoff оказываются недоговорёнными
- на финале всё равно приходится много переделывать руками

Этот плагин решает именно эту проблему. Он добавляет структуру, память проекта, роли, проверки и жёсткий маршрут работы.

## Что делает плагин

- принимает идею проекта и переводит её в понятный рабочий сценарий
- задаёт простые наводящие вопросы в формате квиза
- если после первых ответов информации мало, задаёт ещё одну короткую волну уточняющих вопросов
- объясняет простыми словами, зачем нужны эти уточнения и на что они влияют
- отдельно выясняет, что делает проект уникальным и на что он не должен быть похож
- определяет тип проекта и подходящий маршрут реализации
- собирает проектный контекст и план в отдельные артефакты
- предлагает 3 варианта плана: минимум, оптимально и с запасом
- рекомендует один вариант и объясняет простыми словами, почему
- делит работу по ролям: аналитика, архитектура, дизайн, фронтенд, бэкенд, база, автоматизация, QA, деплой
- не начинает реализацию, пока план не подтверждён
- замораживает утверждённый план, чтобы он не перезаписывался случайно
- проводит проверку перед финальным handoff
- собирает чеклист по секретам, env и ручным шагам
- вшивает безопасные дефолты в бриф, план, бэкенд, базу, QA и handoff
- напоминает про минимизацию данных, parameterized queries / ORM, разделение client/server ключей и базовую проверку зависимостей

## Уникальность и дизайн

Плагин не исходит из идеи, что все проекты должны выглядеть одинаково или быть одинаково “креативными”.

Он различает:

- спокойный продуктовый интерфейс
- выразительный маркетинговый экран
- действительно смелое визуальное направление

И выбирает это не по моде, а по задаче проекта.

Для этого он:

- фиксирует `project DNA` и правила уникальности
- отдельно определяет характер продукта, визуальную смелость и язык форм
- запрещает generic-решения по умолчанию
- умеет учитывать локальные style-skills, moodboard, brand guide и `design-system.json`
- не даёт превращать каждый проект в “Awwwards-лендинг” без причины

Отдельно зафиксировано правило типографики:

- если интерфейс и контент на русском, плагин должен использовать шрифты с поддержкой кириллицы
- отсутствие кириллицы у display/body шрифта считается ошибкой качества, а не “мелкой деталью на потом”

## Для каких проектов подходит

- лендинги и продуктовые сайты
- Telegram- и AI-боты
- SaaS MVP и кабинеты
- automation-скрипты
- API-интеграции и воркеры
- смешанные проекты, где есть несколько подсистем одновременно

Например:

- Telegram-бот + админ-панель
- SaaS + база + авторизация
- лендинг + форма заявок + простая автоматизация
- API-воркер + логирование + ручной handoff

## Как он работает

Плагин ведёт проект по фиксированным фазам:

1. `discovery`  
   Собирает требования через короткий и понятный квиз.

2. `planning`  
   Формирует brief, product intelligence, технический контекст, 3 варианта плана и рекомендуемый маршрут.

3. `approval`  
   Показывает варианты плана, объясняет разницу и просит одно явное подтверждение.

4. `execution`  
   Реализует проект по утверждённому маршруту.

5. `verification`  
   Проверяет, что проект не разваливается по основным сценариям.

6. `handoff`  
   Готовит финальные инструкции: что сделано, что осталось руками, какие секреты и env нужны, как запускать и деплоить.

## Почему он полезнее обычного промпта

- не теряет контекст между сессиями
- не начинает кодить слишком рано
- не даёт смешивать анализ, дизайн и реализацию в одну кашу
- помогает не скатываться в generic-решения
- снижает риск архитектурного хаоса
- делает финальный handoff частью процесса, а не “доделкой в конце”

## Экономия токенов

Одна из главных задач плагина — не только улучшать качество, но и уменьшать расход контекста.

Для этого он использует трёхслойный режим памяти:

- `phase-card.md`
  самый короткий фазовый снимок: что делать прямо сейчас и когда вообще можно открывать docs
- `ultra-context.md`  
  короткая выжимка для текущего шага
- `context-bundle.md`  
  фазовый bundle без лишних разделов не по текущему этапу

Идея в том, что агент сначала читает минимум, потом только нужную фазовую сводку, и только потом при необходимости открывает документы или knowledge packs. За счёт этого плагин в реальной работе может тратить заметно меньше токенов, чем обычный режим “прочитай всё и подумай ещё раз”.

## Что хранится в проекте

Плагин ведёт локальную память проекта в папке `.codex-agent/`.

Важно:

- `.codex-agent` создаётся в текущей папке проекта
- он не хранится глобально
- глобально устанавливается только сам плагин в пользовательский marketplace Codex
- у каждого проекта свои локальные артефакты и своё состояние

Там сохраняются:

- квиз и ответы пользователя
- brief проекта
- продуктовый и технический контекст
- активные решения по текущей фазе
- план реализации
- дизайн-направление
- лог выполнения
- отчёт по проверке
- чеклист по секретам и env
- финальный handoff
- состояние проекта в `state.json`
- замороженный утверждённый план в `approval-snapshot.json`

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

## Встроенные роли

Плагин использует роль-оркестратор и набор специализированных ролей:

- `project-discovery`
- `solution-architect`
- `design-director`
- `frontend-builder`
- `backend-builder`
- `database-designer`
- `automation-builder`
- `qa-reviewer`
- `deploy-operator`

Если в среде уже установлены подходящие skills, плагин старается использовать их как усилители. Если их нет, он продолжает работу встроенными ролями.

## Morecil Role System

Внутри плагина роли описаны по собственной системе `Morecil Role System`.

Это значит, что у каждой роли есть:

- миссия
- контракт
- обязательные артефакты
- критерии готовности
- handoff следующей роли

Роли не копируют чужие prompt-наборы один в один. Они собраны под стиль работы этого плагина:

- меньше хаоса
- меньше generic-решений
- больше понятности для новичка
- больше контроля над scope, quality и handoff

Дополнительно у плагина есть [SOULS.md](/Users/a/tgbot/codex-project-autopilot/SOULS.md) — верхнеуровневый канон ролей и принципов. Он задаёт не только контракты, но и “характер мышления” команды, чтобы проекты не сваливались в одинаковую шаблонную генерацию.

## Orchestration Modes

Плагин поддерживает два режима оркестрации:

- `solo`  
  один агент последовательно ведёт роли внутри одного потока
- `delegated`  
  оркестратор может раздавать независимые задачи отдельным под-агентам, если проект это оправдывает

Это нужно для составных проектов вроде:

- Telegram-бот + админ-панель
- SaaS + auth + data layer
- automation + API worker + verification

При этом финальный контроль, scope и handoff всё равно остаются у оркестратора.

В `delegated` режиме плагин теперь формирует для ролей готовые `delegation packets`:

- что читать сначала
- что именно можно менять
- что роль обязана вернуть
- в каком формате делать handoff обратно

## Внутри плагина

Плагин опирается не только на skills, но и на набор внутренних механизмов:

- knowledge packs  
  локальные правила и best practices под конкретные типы задач
- playbooks  
  маршруты реализации для разных архетипов проектов
- quality gates  
  минимальные требования к результату
- cross-checks  
  взаимные проверки между ролями
- plan lock  
  заморозка утверждённого плана после approve
- ultra-mode  
  сверхэкономная работа с контекстом
- project DNA  
  краткая модель характера продукта и его оси уникальности
- design profile  
  управляемая модель визуальной смелости, языка форм и источников стиля
- anti-template rules  
  правила против шаблонной генерации

## Для кого он особенно полезен

- для новичков, которым сложно сразу правильно сформулировать задачу ИИ
- для solo-разработчиков, которым нужна структура вместо хаотичного диалога
- для тех, кто хочет вести проект по шагам, а не “магией”
- для тех, кому важно не только сгенерировать код, но и получить нормальный handoff

## Что это не делает

Плагин не заменяет мышление и не превращает любую идею в идеальный production-продукт по одной кнопке.

Он делает другое:

- снижает хаос
- удерживает структуру
- не даёт пропустить важные этапы
- помогает довести проект до более зрелого состояния

То есть это не “волшебная кнопка”, а хороший операционный слой над Codex.

## Текущее состояние

Сейчас плагин уже умеет:

- работать по-русски
- вести проект по фазам
- поддерживать несколько типов проектов
- хранить локальную память проекта
- учитывать вторичные архетипы и capabilities
- вести discovery в две волны и собирать более сильный brief
- различать спокойный, выразительный и смелый дизайн
- учитывать локальные style-skills, brand guide, moodboard и `design-system.json`
- требовать кириллически совместимые шрифты для русского интерфейса
- жёстче проверять mobile, адаптив и читаемость
- замораживать план после approve
- экономить токены через phase-card, ultra-context и фазовый context bundle
- валидировать состояние проекта перед handoff

## Установка

Этот репозиторий и есть плагин.

Его можно подключать двумя способами:

- как общий локальный плагин для всех проектов
- как локальный плагин внутри конкретного проекта

Основной рекомендуемый сценарий: установить его один раз как **общий локальный плагин** и дальше использовать в любых проектах.

При этом:

- сам плагин хранится один раз
- в каждом новом проекте создаются свои локальные `.codex-agent` файлы
- проекты не мешают друг другу

### Самый простой способ

Можно вообще не настраивать всё руками.

Достаточно дать Codex ссылку на этот GitHub-репозиторий и написать что-то вроде:

```text
Склонируй этот репозиторий и установи плагин глобально, чтобы он был доступен во всех проектах.
```

После этого Codex может:

1. скачать репозиторий
2. сам прописать `marketplace.json`
3. подключить локальный путь к плагину

Тогда вам останется только:

1. открыть `Skills & Apps`
2. найти `Codex Project Autopilot`
3. нажать `Install`

Для глобальной установки в репозитории есть автоустановщик:

```bash
python3 scripts/install_home_plugin.py
```

Он сам:

1. скопирует плагин в `~/plugins/codex-project-autopilot`
2. создаст или обновит `~/.agents/plugins/marketplace.json`
3. зарегистрирует плагин как общий локальный источник для Codex

### 1. Скачайте этот репозиторий

Склонируйте репозиторий или скачайте архив с GitHub.

Дальше выберите один из двух вариантов.

#### Вариант A. Глобальная установка для всех проектов

Это основной рекомендуемый вариант.

Просто запустите:

```bash
python3 scripts/install_home_plugin.py
```

После этого плагин будет зарегистрирован как пользовательский локальный плагин.

Файлы установки будут лежать так:

```text
~/
├── .agents/
│   └── plugins/
│       └── marketplace.json
└── plugins/
    └── codex-project-autopilot/
```

Готовый пример для этого режима лежит в [examples/home-marketplace.json](/Users/a/tgbot/codex-project-autopilot/examples/home-marketplace.json).

После такой установки:

- открываете любой проект в Codex
- заходите в `Skills & Apps`
- переключаетесь на пользовательский источник
- нажимаете `Install` у `Codex Project Autopilot`

Сам `.codex-agent` при этом всё равно будет создаваться уже в текущем проекте, где вы реально работаете.

#### Вариант B. Плагин лежит внутри проекта

Положите репозиторий сюда:

`plugins/autonomous-project-agent/`

Итоговая структура должна выглядеть так:

```text
ваш-проект/
├── .agents/
├── plugins/
│   └── autonomous-project-agent/
└── ...
```

### 2. Добавьте локальный marketplace

Для project-local режима в проекте должен быть файл:

`.agents/plugins/marketplace.json`

Если файла ещё нет, создайте его. Если он уже есть, добавьте в него запись для локального плагина.

Готовый пример также лежит в [examples/marketplace.json](/Users/a/tgbot/codex-project-autopilot/examples/marketplace.json).

Если не хотите редактировать JSON вручную, просто запустите:

```bash
python3 scripts/install_local_plugin.py --workspace .
```

Скрипт сам создаст или обновит `marketplace.json`.

Минимальный пример для варианта B:

```json
{
  "name": "morecil-local",
  "interface": {
    "displayName": "Morecil Local Plugins"
  },
  "plugins": [
    {
      "name": "codex-project-autopilot",
      "source": {
        "source": "local",
        "path": "./plugins/autonomous-project-agent"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
```

Именно этот файл делает плагин видимым в `Skills & Apps`.

Если в интерфейсе Codex рядом с категорией вы видите что-то вроде `morecil-local, Productivity`, это означает:

- `Productivity` — категория самого плагина
- `morecil-local` — имя локального marketplace-источника

То есть это не две категории, а `источник + категория`.

### 3. Проверьте Python

Для локальных скриптов плагину нужен установленный Python 3.

Это важно для:

- инициализации `.codex-agent`
- локальной валидации состояния
- guardrail-проверок после записи файлов

### 4. Установите плагин в Codex

После этого:

- откройте проект в Codex
- зайдите в `Skills & Apps`
- в фильтре источников выберите нужный источник:
  - `Пользовательский` для глобальной установки
  - локальный marketplace проекта для project-local режима
- найдите `Codex Project Autopilot`
- нажмите `Install`

После установки плагин станет доступен в Codex для этого источника. Само состояние `.codex-agent` будет создаваться уже в той папке проекта, где вы реально его используете.

### Быстрый сценарий

1. Скачайте этот репозиторий.
2. Запустите `python3 scripts/install_home_plugin.py`.
3. Откройте любой проект в Codex.
4. Откройте проект в Codex.
5. Зайдите в `Skills & Apps`.
6. Выберите пользовательский источник плагинов.
7. Нажмите `Install` у `Codex Project Autopilot`.

### 5. Начните работу

После установки плагин можно использовать для:

- запуска нового проекта из идеи
- продолжения уже начатого проекта
- подготовки деплоя и секретов
- объяснения текущего проекта простым языком

### Важно

- Лучший режим для повседневной работы — глобальная установка через `install_home_plugin.py`.
- В этом режиме один и тот же плагин доступен в любых проектах.
- Если вы используете project-local установку, тогда да: папку плагина и `marketplace.json` нужно добавить в конкретный проект.
- `.codex-agent` не является частью самого плагина. Эта папка создаётся автоматически в текущем workspace, где вы запускаете плагин.

## Куда развивать дальше

Следующие сильные направления для развития:

- ещё более умные role contracts
- расширенная поддержка смешанных проектов
- более строгие phase transitions
- автоматическое обновление scorecard и verification report
- ещё более агрессивная экономия токенов на длинных проектах
- более глубокие product/design heuristics для нетиповых задач

## Итог

Codex Project Autopilot нужен для того, чтобы Codex работал не как генератор случайных ответов, а как управляемая мини-команда с памятью, этапами, проверками и финальной передачей проекта.

Если коротко:  
идея -> вопросы -> план -> подтверждение -> реализация -> проверка -> handoff

## Проверка локально

Если хотите быстро проверить, что плагин не повреждён после скачивания:

```bash
python3 -m py_compile scripts/*.py tests/*.py
python3 -m unittest discover -s tests
```