From 12611edd6f221172f83da66b398138a7b40b3d79 Mon Sep 17 00:00:00 2001 From: oqyude Date: Fri, 7 Aug 2026 22:30:19 +0300 Subject: [PATCH] metaagent update --- .agent/src/BOUNDARIES.md | 20 +- .agent/src/CHANGELOG.md | 87 ++++ .agent/src/COMMANDS/adr.md | 95 ++++ .agent/src/COMMANDS/alt-arch.md | 85 ++++ .agent/src/COMMANDS/invariant-tests.md | 68 +++ .agent/src/COMMANDS/red-team.md | 104 ++++ .agent/src/COMMANDS/risk-register.md | 80 +++ .agent/src/GUIDE.md | 205 ++++++++ .agent/src/META_AGENT_GUIDE.md | 458 ++++++++++-------- .agent/src/PROTOCOLS/00_CONFIG.md | 7 +- .agent/src/PROTOCOLS/00_INIT.md | 128 +++++ .agent/src/PROTOCOLS/00_MIGRATE.md | 155 +++++- .agent/src/PROTOCOLS/01_ANALYSE.md | 95 ++++ .agent/src/PROTOCOLS/01_ANALYSIS.md | 24 +- .agent/src/PROTOCOLS/02_DESIGN.md | 18 +- .agent/src/PROTOCOLS/02_ROADMAP.md | 99 ++++ .agent/src/PROTOCOLS/02b_REDTEAM.md | 6 +- .agent/src/PROTOCOLS/03_DECOMPOSITION.md | 48 +- .agent/src/PROTOCOLS/03_DESIGN.md | 142 ++++++ .agent/src/PROTOCOLS/04_DECOMPOSITION.md | 117 +++++ .agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md | 22 +- .agent/src/PROTOCOLS/04_EXECUTION.md | 138 ++++++ .agent/src/PROTOCOLS/05_EXECUTION.md | 136 ++++++ .agent/src/PROTOCOLS/05_HANDOFF.md | 203 +++----- .agent/src/PROTOCOLS/06_METASTATE.md | 149 ++++++ .agent/src/PROTOCOLS/07_HANDOFF.md | 113 +++++ .agent/src/TEMPLATES/handoff-summary.md | 4 +- .agent/src/TEMPLATES/metaagent-request.md | 2 +- .agent/src/TEMPLATES/project-state.md | 43 ++ .agent/src/TEMPLATES/request.json | 29 ++ .agent/src/TEMPLATES/roadmap-sources.md | 42 ++ .../TEMPLATES/schemas/checkpoints-schema.json | 93 ++++ .../schemas/decisions-index-schema.json | 60 +++ .../schemas/task-manifest-schema.json | 91 ++++ .agent/src/TEMPLATES/session-summary.md | 7 +- .agent/src/TEMPLATES/task-manifest.json | 2 +- .agent/src/VERSION | 2 +- .agent/src/WORKFLOW.md | 216 ++++++++- .agent/src/install.ps1 | 248 ++++++++-- .agent/src/install.sh | 189 +++++++- AGENTS.md | 38 +- LICENSE | 21 + 42 files changed, 3377 insertions(+), 512 deletions(-) create mode 100644 .agent/src/CHANGELOG.md create mode 100644 .agent/src/COMMANDS/adr.md create mode 100644 .agent/src/COMMANDS/alt-arch.md create mode 100644 .agent/src/COMMANDS/invariant-tests.md create mode 100644 .agent/src/COMMANDS/red-team.md create mode 100644 .agent/src/COMMANDS/risk-register.md create mode 100644 .agent/src/GUIDE.md create mode 100644 .agent/src/PROTOCOLS/00_INIT.md create mode 100644 .agent/src/PROTOCOLS/01_ANALYSE.md create mode 100644 .agent/src/PROTOCOLS/02_ROADMAP.md create mode 100644 .agent/src/PROTOCOLS/03_DESIGN.md create mode 100644 .agent/src/PROTOCOLS/04_DECOMPOSITION.md create mode 100644 .agent/src/PROTOCOLS/04_EXECUTION.md create mode 100644 .agent/src/PROTOCOLS/05_EXECUTION.md create mode 100644 .agent/src/PROTOCOLS/06_METASTATE.md create mode 100644 .agent/src/PROTOCOLS/07_HANDOFF.md create mode 100644 .agent/src/TEMPLATES/project-state.md create mode 100644 .agent/src/TEMPLATES/request.json create mode 100644 .agent/src/TEMPLATES/roadmap-sources.md create mode 100644 .agent/src/TEMPLATES/schemas/checkpoints-schema.json create mode 100644 .agent/src/TEMPLATES/schemas/decisions-index-schema.json create mode 100644 .agent/src/TEMPLATES/schemas/task-manifest-schema.json create mode 100644 LICENSE diff --git a/.agent/src/BOUNDARIES.md b/.agent/src/BOUNDARIES.md index 842b110..926cd3b 100644 --- a/.agent/src/BOUNDARIES.md +++ b/.agent/src/BOUNDARIES.md @@ -1,34 +1,36 @@ # BOUNDARIES — Рамки и границы -Что мета-агенту **разрешено**, **запрещено** и в каких случаях **нужно остановиться**. +Что агенту **разрешено**, **запрещено** и в каких случаях **нужно остановиться**. ## Разрешено | Действие | Примечание | |---|---| | Читать любые файлы в целевом репозитории | Все файлы, включая .git, конфиги, историю | -| Создавать/изменять файлы в `.agent/` | Единственная директория для артефактов | +| Создавать/изменять файлы в `.agent/` | Директория метаданных проекта (rules, decisions, tasks, context, archive, requests, roadmap) | +| Создавать `.temp/` в корне проекта | Для временных файлов агента (всегда на одном уровне с `.agent/`) | +| Писать production-код | В фазе EXECUTION, по задачам из manifest.json | +| Рефакторить существующий код | Только если это часть задачи в manifest.json | +| Делать коммиты | По завершении задачи, перед созданием request | +| Создавать/дополнять `.gitignore` | Только для добавления `.temp/` | | Устанавливать/обновлять зависимости | Только через штатный пакетный менеджер проекта | | Изменять конфигурационные файлы | Только если это необходимо для сборки/тестов (например, добавить requirements.txt) | -| Запускать сборку и тесты | Для верификации окружения | +| Запускать сборку и тесты | Для верификации окружения и проверки request-ов | | Читать документацию, issue, PRs | Для понимания контекста | | Запрашивать уточнения у пользователя | Если не хватает информации для декомпозиции | | Копировать исходники MetaAgent в `.agent/src/` целевого проекта | Только на фазе INIT, без перезаписи существующих файлов | | Создавать/обновлять `AGENTS.md` в корне целевого проекта | Только если файла не существует | | **Обязательно:** читать `.agent/rules/project-rules.md` перед каждой фазой | Исполнение правил пользователя — приоритет выше стандартных протоколов | -| Перемещать завершённые артефакты в `.agent/archive/` | Только на фазе HANDOFF, только для completed/failed артефактов | +| Перемещать завершённые артефакты в `.agent/archive/` | На фазах METASTATE и HANDOFF, только для completed/failed артефактов | +| **Обязательно:** после выполнения задачи создавать request в `.agent/requests/active/` | Request — единица результата, основа для METASTATE | ## Запрещено | Действие | Почему | |---|---| -| Писать production-код | Это работа исполнительного агента | -| Рефакторить существующий код | Мета-агент не меняет логику | | Удалять файлы | Если файл мешает — нужно сообщить пользователю | -| Коммитить в main/master | Коммиты делает исполнительный агент по задачам | | Менять удалённые настройки CI/CD | Если CI сломан — сообщить пользователю | -| Пул-реквесты | Исполнительный агент создаёт PR после выполнения задач | -| Модифицировать код, не связанный с задачей | Только то, что нужно для окружения | +| Модифицировать код, не связанный с задачей | Только то, что нужно в рамках задачи из manifest.json | ## Когда остановиться diff --git a/.agent/src/CHANGELOG.md b/.agent/src/CHANGELOG.md new file mode 100644 index 0000000..95c2009 --- /dev/null +++ b/.agent/src/CHANGELOG.md @@ -0,0 +1,87 @@ +# Changelog + +## 3.0.0 — Упрощение модели + +**Дата:** 2026-10-08 + +### Что изменилось + +Принята модель «жизненный цикл + команды на вызов» вместо «жизненный цикл с уровнями глубины». + +**Удалено:** +- Шкала глубины (depth 1-10) и все её варианты (Scaffold/Light/Standard/Deep/Maximum). +- Условные фичи в фазах: `adr`, `alternative_arch`, `red_team`, `risk_register`, `invariant_tests`. +- Интервью с пользователем на старте (5 вопросов про depth и фичи). +- `.agent/metaagent-request.md` — конфиг-файл, который сейчас не нужен. +- `TEMPLATES/metaagent-request.md`. + +**Добавлено:** +- Директория `COMMANDS/` с пятью on-demand инструкциями: `adr.md`, `red-team.md`, `risk-register.md`, `alt-arch.md`, `invariant-tests.md`. +- `GUIDE.md` — заменяет `META_AGENT_GUIDE.md`, описание цикла + список команд. +- `CHANGELOG.md` — этот файл. + +**Переименовано / перенумеровано:** +- `META_AGENT_GUIDE.md` → `GUIDE.md`. +- `PROTOCOLS/01_ANALYSIS.md` → `01_ANALYSE.md`. +- `PROTOCOLS/02_DESIGN.md` → `03_DESIGN.md`. +- `PROTOCOLS/03_DECOMPOSITION.md` → `04_DECOMPOSITION.md`. +- `PROTOCOLS/04_EXECUTION.md` → `05_EXECUTION.md`. +- `PROTOCOLS/05_HANDOFF.md` → `07_HANDOFF.md`. +- `PROTOCOLS/06_METASTATE.md` остался под тем же именем (теперь фаза 6). + +**Удалены протоколы:** +- `PROTOCOLS/00_CONFIG.md` — конфигурация больше не нужна. +- `PROTOCOLS/00_MIGRATE.md` — миграция теперь документируется в этом CHANGELOG. +- `PROTOCOLS/04_ENVIRONMENT_SETUP.md` — поглощён фазой `00_INIT.md`. +- `PROTOCOLS/02b_REDTEAM.md` — теперь команда `COMMANDS/red-team.md`. + +**Структура `.agent/checkpoints.json`** упрощена: убраны `config.depth`, `config.design.adr`, `config.red_team`, `config.risk_register`, `config.decomposition.invariant_tests`. + +### Миграция с v2.1 → v3.0 + +Для проектов, созданных с MetaAgent v2.1: + +1. **Удалить** из `.agent/checkpoints.json` секцию `config` целиком (она больше не читается). +2. **Удалить** `.agent/metaagent-request.md` (не используется). +3. **Удалить** `.agent/decisions/config.json`, если есть (аналог config для решений). +4. **Запустить** `install.sh --update` (или `install.ps1 -Update` / `install.bat --update`) — перезапишет исходники MetaAgent. +5. **Переименовать** пути в существующих артефактах: `layer-1/adr/` → `decisions/` (если остались с v1.x), `layer-2/analysis-report.md` → `context/analysis-report.md` и т.п. — это касается только проектов, оставшихся на v1.x. +6. **Записать** в `.agent/checkpoints.json` новое значение `metaagent_version: "3.0.0"`. + +`request.json`, `manifest.json`, `decisions/index.json` остаются в том же формате, что в v2.1. + +### Экономия + +| | v2.1 | v3.0 | +|---|---|---| +| Markdown строк всего | ~3 820 | ~1 800 (целевой) | +| Протоколов | 10 | 8 | +| Уровней конфигурации | 5 (depth) | 0 | + +--- + +## 2.1.0 — Project Loop + Work Loop + Requests + +**Дата:** 2025-08 (предыдущая версия) + +- Введён двухконтурный жизненный цикл: Project Loop (однократно) + Work Loop (циклически). +- Добавлены фазы: ROADMAP, METASTATE, RED_TEAM. +- Введены `requests/` как единица результата выполненной задачи. +- Введён `metaagent-request.md` с конфигом сессии (depth scale, фичи). +- Введена структура `.agent/` с семантическими директориями: `decisions/`, `tasks/`, `context/`, `rules/`, `requests/`, `roadmap/`, `archive/`. +- Шкала глубины 1-10 с условными фичами (adr, alternative_arch, red_team, risk_register, invariant_tests). + +## 2.0.0 — Реструктуризация `.agent/` + +- Переход от слоистой структуры `layer-0..3` к семантическим директориям. +- Полный MIGRATE-протокол для апгрейда с v1.x. + +## 1.1.0 — Добавлены rules, archive + +- `PROTOCOLS/01_ANALYSIS.md` обзавёлся правилами из `.agent/rules/`. +- Добавлена директория `archive/`. + +## 1.0.0 — Первый релиз + +- Односессионный pipeline: INIT → ANALYSE → DECOMP → SETUP → HANDOFF. +- Структура `layer-0..3`. diff --git a/.agent/src/COMMANDS/adr.md b/.agent/src/COMMANDS/adr.md new file mode 100644 index 0000000..e16f6cb --- /dev/null +++ b/.agent/src/COMMANDS/adr.md @@ -0,0 +1,95 @@ +# ADR — Architecture Decision Record + +## Назначение + +Зафиксировать архитектурное решение в `.agent/decisions/NNN-slug.md` так, чтобы будущий агент (или человек) мог понять: что решили, почему, какие альтернативы рассматривали, какие последствия. + +ADR создаются по явной команде пользователя: «запиши это как решение», «/adr», «сделай ADR для текущего подхода». + +## Когда вызывать + +- Принято неочевидное архитектурное решение (выбор БД, паттерна, библиотеки, структуры модулей). +- Решение может измениться в будущем — стоит зафиксировать контекст. +- Есть trade-off, который нужно объяснить следующему агенту. + +Не вызывать для очевидных вещей: «используем pytest», «классы называем в PascalCase». + +## Вход + +- Контекст решения: что обсуждалось, какие варианты сравнивались, что выбрали. +- `.agent/decisions/index.json` — текущий список ADR (для нумерации). +- `.agent/context/project-state.md` — текущее состояние проекта. + +## Шаги + +### 1. Определить номер + +Прочитать `.agent/decisions/index.json`. Следующий номер = max существующих + 1. Если файла нет — создать, начать с 001. + +### 2. Slug + +Короткое имя в kebab-case, отражающее суть: `use-sqlite-for-mvp`, `auth-via-jwt-cookies`, `modular-monolith`. + +### 3. Записать ADR + +Создать `.agent/decisions/{NNN}-{slug}.md` по шаблону `TEMPLATES/adr-NNNN.md`: + +```markdown +# {NNN}. {Заголовок} + +**Дата:** {YYYY-MM-DD} +**Статус:** Accepted | Superseded by {NNN} | Deprecated + +## Контекст + +{Что за проблема. Какие ограничения. Что нужно было решить.} + +## Решение + +{Что выбрали. Коротко и конкретно.} + +## Альтернативы, которые рассмотрели + +### {Альтернатива 1} +{Описание. Почему не выбрали.} + +### {Альтернатива 2} +{Описание. Почему не выбрали.} + +## Последствия + +### Положительные +- {что становится лучше} + +### Отрицательные +- {что становится хуже или сложнее} + +### Инварианты +- {что не должно сломаться, чтобы решение оставалось валидным} +``` + +### 4. Обновить index.json + +```json +{ + "version": "3.0.0", + "decisions": [ + { "id": "001", "title": "Использовать SQLite для MVP", "file": "001-use-sqlite-for-mvp.md", "status": "Accepted" } + ], + "last_updated": "{timestamp}" +} +``` + +### 5. Если есть supersession + +Если новый ADR отменяет старый — в старом ADR поставить `Статус: Superseded by {NNN}` и добавить ссылку. В новом — в контексте упомянуть, что отменяет. + +## Выход + +- `.agent/decisions/{NNN}-{slug}.md` +- Обновлённый `.agent/decisions/index.json` + +## Связанные команды + +- **/invariant-tests** — после ADR можно зафиксировать инварианты как задачи в manifest. +- **/alt-arch** — если хочется явно зафиксировать альтернативу до решения. diff --git a/.agent/src/COMMANDS/alt-arch.md b/.agent/src/COMMANDS/alt-arch.md new file mode 100644 index 0000000..a9b5c20 --- /dev/null +++ b/.agent/src/COMMANDS/alt-arch.md @@ -0,0 +1,85 @@ +# Alternative Architecture + +## Назначение + +Описать альтернативный вариант архитектуры / подхода, чтобы сравнить с текущим и принять осознанное решение. Не «сделать вместо», а «сравнить и выбрать». + +## Когда вызывать + +- Текущий дизайн кажется спорным, нужна трезвая оценка альтернативы. +- Хочется зафиксировать «почему не сделали иначе» — потом пригодится при росте. +- Перед крупным решением (выбор БД, монолит-vs-микросервисы, sync-vs-async). + +## Вход + +- Текущий дизайн / план (`.agent/context/design-report.md` или текущее состояние). +- Ограничения проекта (сроки, стек, бюджет). + +## Шаги + +### 1. Определить, что сравниваем + +Один конкретный вопрос: «SQLite vs PostgreSQL», «монолит vs микросервисы», «REST vs GraphQL», «sync-обработка vs очередь». + +### 2. Сформулировать альтернативу + +Краткое описание: что предлагается вместо текущего подхода. Без длинного дизайна — на уровне «как это работает и чем отличается». + +### 3. Сравнить + +| Аспект | Текущий | Альтернатива | +|---|---|---| +| Сложность реализации | | | +| Время до MVP | | | +| Производительность | | | +| Масштабирование | | | +| Поддерживаемость | | | +| Стоимость изменений | | | +| Риски | | | + +### 4. Записать + +Создать `.agent/context/alt-architecture.md` (если файла нет) или дополнить. Структура: + +```markdown +# Alternative Architecture — {что сравниваем} + +**Дата:** {YYYY-MM-DD} + +## Контекст + +{Почему рассматриваем альтернативу. Что не устраивает в текущем.} + +## Альтернатива + +{Краткое описание. Архитектура, ключевые компоненты, поток данных.} + +## Сравнение + +{Таблица из шага 3.} + +## Когда альтернатива выигрывает + +{В каких условиях стоит переключиться. Триггеры для миграции.} + +## Когда остаёмся на текущем + +{Что в текущем работает достаточно хорошо, чтобы не менять.} + +## Рекомендация + +{Остаёмся или мигрируем. Почему.} +``` + +### 5. Связать с ADR + +Если после сравнения принимается решение — использовать **/adr** для фиксации. Альтернативный файл остаётся как исторический артефакт. + +## Выход + +- `.agent/context/alt-architecture.md` + +## Связанные команды + +- **/adr** — зафиксировать итоговое решение. +- **/risk-register** — если альтернатива снимает/добавляет риски. diff --git a/.agent/src/COMMANDS/invariant-tests.md b/.agent/src/COMMANDS/invariant-tests.md new file mode 100644 index 0000000..0d975a8 --- /dev/null +++ b/.agent/src/COMMANDS/invariant-tests.md @@ -0,0 +1,68 @@ +# Invariant Tests + +## Назначение + +Превратить инварианты из ADR в задачи-тесты в `.agent/tasks/manifest.json`. Инвариант — это «что не должно сломаться, чтобы ADR оставался валидным». Без явного теста это просто слова. + +## Когда вызывать + +- После создания ADR, в секции «Инварианты» которого перечислены условия валидности решения. +- Когда хочется, чтобы архитектурные решения были защищены регрессионными тестами. + +## Вход + +- `.agent/decisions/*.md` — ADR с секцией «Инварианты». +- `.agent/tasks/manifest.json` — текущий манифест (для нумерации задач). + +## Шаги + +### 1. Найти ADR с инвариантами + +Прочитать все `.agent/decisions/*.md`, найти секции «Инварианты». + +### 2. Для каждого инварианта — задача + +Каждый инвариант = одна задача-тест. Формат: + +```json +{ + "id": "T-INV-001", + "title": "Invariant: auth-сессия не переживает рестарт сервиса", + "type": "test", + "origin": "invariant:001", + "depends_on": [], + "acceptance_criteria": [ + "Тест рестартит auth-сервис и проверяет, что все сессии инвалидированы", + "Тест проверяет, что refresh-токен не работает после рестарта" + ], + "files": [ + "tests/auth/test_invariants.py" + ] +} +``` + +### 3. Добавить в manifest + +Записать задачи в `.agent/tasks/manifest.json` с `status: "pending"`. Связать `depends_on` с задачами, которые реализуют компонент (если ещё не выполнены). + +### 4. Связать с ADR + +В самом ADR добавить (опционально) ссылку на задачу-инвариант: + +```markdown +## Инварианты +- {{ ... }} + +### Покрытие тестами +- T-INV-001: ... +``` + +## Выход + +- Новые задачи в `.agent/tasks/manifest.json` с `origin: "invariant:{adr_id}"` +- (опционально) обновлённый ADR со ссылкой на задачи + +## Связанные команды + +- **/adr** — источник инвариантов. +- **/risk-register** — некоторые инварианты рождаются из рисков. diff --git a/.agent/src/COMMANDS/red-team.md b/.agent/src/COMMANDS/red-team.md new file mode 100644 index 0000000..a43978c --- /dev/null +++ b/.agent/src/COMMANDS/red-team.md @@ -0,0 +1,104 @@ +# Red Team Review + +## Назначение + +Попытаться сломать текущий дизайн / архитектуру / план. Зафиксировать найденные уязвимости в `.agent/context/red-team-report.md`, чтобы разработчик мог их закрыть до реализации. + +Red Team — это adversarial-проход по дизайну. Не «улучшить», а «найти, что не так». + +## Когда вызывать + +- После фазы DESIGN, до декомпозиции задач. +- Когда дизайн кажется слишком гладким. +- Перед крупным рефакторингом. +- Когда непонятно, какие риски у текущего подхода. + +## Вход + +- `.agent/context/design-report.md` (если есть). +- `.agent/decisions/*.md` — связанные ADR. +- `.agent/context/project-state.md` — текущее состояние. + +## Шаги + +### 1. Прочитать целевой дизайн + +Понять, что именно ревьюится: вся архитектура, конкретный модуль, конкретное решение. + +### 2. Провести атаки по категориям + +#### 2.1. Нагрузка и масштабирование +- Что будет при 10x / 100x объёма? +- Где узкое место? +- Что сломается первым? + +#### 2.2. Отказы и доступность +- Что если упадёт БД / кэш / внешний сервис? +- Есть ли SPOF (single point of failure)? +- Как восстанавливаемся? + +#### 2.3. Безопасность +- Где хранятся секреты? +- Какие поверхности атаки? +- Что с аутентификацией / авторизацией? +- Injection, SSRF, XSS — что релевантно? + +#### 2.4. Корректность +- Где гонки (race conditions)? +- Что с консистентностью данных? +- Какие edge cases не покрыты? + +#### 2.5. Поддерживаемость +- Что будет сложно менять через год? +- Где связность, которую придётся разрывать? +- Какие зависимости могут устареть? + +#### 2.6. Миграция и совместимость +- Если меняем API — как старые клиенты переживут? +- Если меняем схему БД — что со старыми данными? +- Если выкатываем поэтапно — какой план? + +### 3. Записать отчёт + +Создать `.agent/context/red-team-report.md` (если файла нет) или дополнить: + +```markdown +# Red Team Review — {что ревьюим} + +**Дата:** {YYYY-MM-DD} +**Цель:** {что именно атакуем} + +## Критические находки + +### R1. {Краткое название} +- **Категория:** безопасность / нагрузка / корректность / ... +- **Сценарий:** {как воспроизвести} +- **Воздействие:** {что произойдёт} +- **Рекомендация:** {что сделать} + +## Существенные находки + +### R2. ... + +## Минорные находки + +### R3. ... + +## Что выдержало атаку + +- {Что оказалось надёжным — это тоже полезно знать.} +``` + +### 4. Связать с задачами + +Если находка превращается в задачу — добавить в `.agent/tasks/manifest.json` (фаза DECOMPOSITION) с `origin: "red-team:{номер_находки}"`. + +## Выход + +- `.agent/context/red-team-report.md` +- (опционально) новые задачи в manifest + +## Связанные команды + +- **/adr** — если Red Team выявил, что нужно зафиксировать решение иначе. +- **/risk-register** — для систематизации рисков. diff --git a/.agent/src/COMMANDS/risk-register.md b/.agent/src/COMMANDS/risk-register.md new file mode 100644 index 0000000..6b88d36 --- /dev/null +++ b/.agent/src/COMMANDS/risk-register.md @@ -0,0 +1,80 @@ +# Risk Register + +## Назначение + +Явный реестр допущений и рисков проекта в `.agent/context/risk-register.md`. Чтобы не держать в голове «ну мы же понимаем, что X может сломаться» — а записать, оценить и (если надо) превратить в задачи. + +## Когда вызывать + +- В начале проекта — зафиксировать стартовые допущения. +- При появлении нового риска (новый внешний сервис, новая зависимость, новое требование). +- При обзоре дизайна (после DESIGN или Red Team). + +## Вход + +- `.agent/context/design-report.md` (если есть). +- `.agent/context/analysis-report.md` — что уже знаем о проекте. +- `.agent/decisions/*.md` — принятые решения (могут быть источниками рисков). + +## Шаги + +### 1. Собрать риски + +Источники: +- Допущения, на которых держится дизайн («считаем, что PostgreSQL выдержит 1k qps»). +- Внешние зависимости без SLA. +- Технологии, которые команда не знает. +- Сроки, которые давят. +- Решения, которые сложно откатить. + +### 2. Оценить каждый риск + +По двум осям: +- **Вероятность** (1-низкая, 2-средняя, 3-высокая). +- **Воздействие** (1-небольшое, 2-серьёзное, 3-критическое). + +`score = вероятность × воздействие` (1-9). + +### 3. Записать + +Создать или дополнить `.agent/context/risk-register.md` по шаблону `TEMPLATES/risk-register.md`: + +```markdown +# Risk Register + +**Дата:** {YYYY-MM-DD} + +## Высокий риск (score 6-9) + +### R-001. {Краткое название} +- **Категория:** технический / продуктовый / организационный +- **Описание:** {что может пойти не так} +- **Воздействие:** {что будет если случится} +- **Вероятность:** 3 / 2 / 1 +- **Счёт:** 9 / 6 / 4 +- **Митигация:** {что делаем чтобы уменьшить} +- **Владелец:** {кто отвечает} +- **Статус:** open / mitigated / accepted / closed + +## Средний риск (score 3-4) +... + +## Низкий риск (score 1-2) +... + +## Закрытые риски +... +``` + +### 4. Связать с задачами + +Если риск требует действия — добавить задачу в `.agent/tasks/manifest.json` с `origin: "risk:R-001"`. + +## Выход + +- `.agent/context/risk-register.md` + +## Связанные команды + +- **/red-team** — источник технических рисков. +- **/adr** — некоторые риски закрываются через принятое решение. diff --git a/.agent/src/GUIDE.md b/.agent/src/GUIDE.md new file mode 100644 index 0000000..d331bab --- /dev/null +++ b/.agent/src/GUIDE.md @@ -0,0 +1,205 @@ +# MetaAgent GUIDE v3.0 + +MetaAgent — набор инструкций для AI-агента. Задача: превратить хаотичное общение с агентом в структурированный процесс, в котором состояние проекта переживает любую сессию. + +## Два слоя + +- **Цикл** (всегда, по необходимости) — последовательность фаз, которую агент проходит при работе с проектом. +- **Команды** (по запросу пользователя) — on-demand инструкции, которые не привязаны к фазе. + +Состояние проекта живёт в `.agent/` целевого репозитория. Следующий агент читает `.agent/` и не лезет в исходники. + +--- + +## Цикл + +``` + .agent/checkpoints.json + │ + ▼ + ┌─────────────────────────────────────┐ + │ PROJECT LOOP (разово) │ + │ │ + │ INIT → ANALYSE → ROADMAP → │ + │ → [DESIGN] → DECOMPOSITION │ + │ │ + │ Выход: .agent/tasks/manifest.json │ + └──────────────────┬──────────────────┘ + │ + ▼ + ┌─────────────────────────────────────┐ + │ WORK LOOP (циклически) │ + │ │ + │ EXECUTION → (request) → │ + │ → METASTATE (по команде) │ + │ │ + │ Беру задачу → делаю → request → │ + │ накопилось → METASTATE │ + └──────────────────┬──────────────────┘ + │ + ▼ + HANDOFF (завершение) +``` + +Фазы выполняются **строго последовательно** внутри PROJECT LOOP. WORK LOOP повторяется многократно. + +### Ветвление + +| Тип проекта | Цикл | +|---|---| +| **existing** | INIT → ANALYSE → ROADMAP → DECOMPOSITION → EXECUTION → METASTATE → HANDOFF | +| **greenfield / scaffold** | + фаза DESIGN между ROADMAP и DECOMPOSITION | + +Тип проекта определяется автоматически в фазе ANALYSE. Никакого интервью с пользователем, никакой шкалы глубины. + +--- + +## Фазы + +| # | Фаза | Протокол | Что делает | +|---|---|---|---| +| 0 | INIT | `PROTOCOLS/00_INIT.md` | Создаёт `.agent/`, ставит исходники, инициализирует checkpoints | +| 1 | ANALYSE | `PROTOCOLS/01_ANALYSE.md` | Сканирует проект, создаёт `analysis-report.md` + начальный `project-state.md` | +| 2 | ROADMAP | `PROTOCOLS/02_ROADMAP.md` | Собирает источники задач (FUTURE, ADR, user-запросы) → `roadmap/sources.md` | +| 3 | DESIGN | `PROTOCOLS/03_DESIGN.md` | Только greenfield. Архитектура, модули, API, модели | +| 4 | DECOMPOSITION | `PROTOCOLS/04_DECOMPOSITION.md` | Разбивает цель на атомарные задачи → `tasks/manifest.json` | +| 5 | EXECUTION | `PROTOCOLS/05_EXECUTION.md` | Цикл: берёт задачу → код → тесты → коммит → request | +| 6 | METASTATE | `PROTOCOLS/06_METASTATE.md` | По команде. Ревью requests, обновление project-state, handoff-summary | +| 7 | HANDOFF | `PROTOCOLS/07_HANDOFF.md` | Валидация `.agent/`, финализация checkpoints, session-summary | + +--- + +## Команды + +Эти инструкции выполняются **по явной просьбе пользователя** в любой момент сессии. Они не привязаны к фазе. + +| Команда | Файл | Что делает | +|---|---|---| +| «запиши ADR» / «/adr» | `COMMANDS/adr.md` | Создаёт `.agent/decisions/NNN-slug.md` | +| «red team» / «/red-team» | `COMMANDS/red-team.md` | Создаёт `.agent/context/red-team-report.md` — попытка сломать дизайн | +| «risk register» / «/risk-register» | `COMMANDS/risk-register.md` | Создаёт `.agent/context/risk-register.md` | +| «альтернативная архитектура» / «/alt-arch» | `COMMANDS/alt-arch.md` | Описывает альтернативу текущему дизайну | +| «invariant-тесты» / «/invariant-tests» | `COMMANDS/invariant-tests.md` | Создаёт задачи-инварианты для ADR | + +### Когда вызывать + +- **ADR** — после архитектурного решения, которое нужно зафиксировать. Типично во время DESIGN или при появлении неочевидного выбора в EXECUTION. +- **Red Team** — после готового дизайна, чтобы найти слабые места до реализации. +- **Risk Register** — в начале проекта или при появлении новых допущений. +- **Alt Arch** — если сомневаетесь в выбранном подходе, хотите сравнить варианты. +- **Invariant Tests** — после ADR, чтобы зафиксировать «что не должно сломаться». + +Команды **не обязательны**. Если не вызваны — не выполняются. Состояние проекта от них не зависит. + +--- + +## Структура `.agent/` + +``` +.agent/ + checkpoints.json # состояние сессии (ядро) + session-summary.md # краткая сводка сессии + handoff-summary.md # сводка для следующего агента (создаётся METASTATE) + + src/ # исходники MetaAgent (всегда) + GUIDE.md + BOUNDARIES.md + CHANGELOG.md + PROTOCOLS/ + COMMANDS/ + TEMPLATES/ + VERSION + install.sh / install.ps1 + + rules/ + project-rules.md # ваши правила — читать перед каждой фазой + + roadmap/ # источники задач + sources.md + archive/ + + decisions/ # ADR + index.json + 001-*.md + + tasks/ # задачи + manifest.json + manifest.md + backlog/ + + requests/ # результаты выполненных задач + active/ # ready_for_review + archive/ # approved / rejected + + context/ + analysis-report.md + project-state.md # обновляется в METASTATE + design-report.md # только greenfield + red-team-report.md # если вызывали /red-team + risk-register.md # если вызывали /risk-register + baseline-test-report.log + + archive/ + index.json + tasks/ + decisions/ + requests/ + checkpoints/ +``` + +`.temp/` в корне проекта — для временных файлов агента. Всегда в `.gitignore`. + +--- + +## Checkpoints + +`checkpoints.json` обновляется после каждой фазы: + +```json +{ + "metaagent_version": "3.0.0", + "session_id": "", + "target_repo": "", + "goal": "<цель>", + "project_type": "existing | greenfield | scaffold", + "phases": { + "init": "completed", + "analyse": "completed", + "roadmap": "completed", + "design": "skipped", + "decomposition": "completed", + "execution": "in_progress", + "metastate": "pending", + "handoff": "pending" + }, + "tasks": [ + { "id": "T1", "title": "...", "status": "in_progress", "origin": "user:direct" } + ], + "last_updated": "" +} +``` + +Секции `config` больше нет. Параметры, которые раньше были в `config` (depth, adr, red_team и т.п.), теперь либо не существуют, либо живут в отдельных командах. + +--- + +## Принципы + +### Цикл vs команды + +Цикл — это «что агент делает по умолчанию». Команды — «что агент делает по явной просьбе». Не путать: ADR не запускается автоматически в DESIGN, а только когда пользователь скажет «запиши это как решение». + +### `.agent/` как слепок проекта + +После METASTATE `.agent/` содержит всю картину. Следующий агент читает только `.agent/`, не исходники. + +### Request — единица результата + +Каждая выполненная задача в EXECUTION завершается созданием `request` (`.agent/requests/active/req-{id}.json`). Request содержит суть изменений, коммиты, верификацию, закрытые acceptance criteria. Ревью request-ов происходит в METASTATE. + +### Правила выше протоколов + +Перед каждой фазой читать `.agent/rules/project-rules.md`. Если правило пользователя противоречит протоколу — следовать правилу. + +### Контекст бесконечно не растёт + +Завершённые задачи архивируются в `.agent/archive/tasks/`, request-ы — в `.agent/requests/archive/`. Текущий manifest остаётся lean. diff --git a/.agent/src/META_AGENT_GUIDE.md b/.agent/src/META_AGENT_GUIDE.md index 6fabfa7..1147483 100644 --- a/.agent/src/META_AGENT_GUIDE.md +++ b/.agent/src/META_AGENT_GUIDE.md @@ -1,23 +1,40 @@ -# META_AGENT_GUIDE — Главная инструкция +# META_AGENT_GUIDE — Главная инструкция v2.1 ## Жизненный цикл сессии ``` -.agent/metaagent-request.md - │ - ▼ -INIT → ANALYSE → [DESIGN] → [RED_TEAM] → DECOMPOSITION → SETUP → (CHECKPOINT)* → HANDOFF → EXIT - │ │ - ▼ ▼ - ADR (опц.) Invariant Tasks (опц.) - Alt.Arch (опц.) - Risk Register (опц.) + .agent/metaagent-request.md + │ + ▼ +┌─────────────────────────────────────────────────────┐ +│ PROJECT LOOP (однократно) │ +│ │ +│ INIT → ANALYSE → ROADMAP → DESIGN → DECOMPOSITION │ +│ │ +│ Выход: .agent/tasks/manifest.json │ +└──────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────┐ +│ WORK LOOP (циклически) │ +│ │ +│ EXECUTION → (request) → METASTATE (по команде) │ +│ │ +│ Цикл повторяется: беру задачу → делаю → │ +│ создаю request → накопилось → METASTATE │ +└──────────────────────┬──────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────┐ +│ HANDOFF (завершение) │ +└─────────────────────────────────────────────────────┘ ``` -Фазы выполняются **строго последовательно**. Фаза DESIGN — только если project_type = greenfield/scaffold. -Фаза RED_TEAM — только если config.red_team = yes. +Фазы выполняются **строго последовательно** внутри PROJECT LOOP. +WORK LOOP может повторяться многократно. +HANDOFF — легковесное завершение. -Все артефакты размещаются в `.agent/` целевого репозитория (с layer-структурой или плоские, в зависимости от config). +Все артефакты размещаются в `.agent/` целевого репозитория. --- @@ -32,12 +49,12 @@ INIT → ANALYSE → [DESIGN] → [RED_TEAM] → DECOMPOSITION → SETUP → (CH | Уровень | Название | Что выполняется | |---|---|---| | 1-2 | Scaffold | INIT → ANALYSIS → SETUP (только структура, без реализации) | -| 3-4 | Light | + DESIGN (без ADR/альтернатив), DECOMPOSITION (без инвариантов), HANDOFF — **(default)** | +| 3-4 | Light | + ROADMAP, DESIGN (без ADR/альтернатив), DECOMPOSITION — **(default)** | | 5-6 | Standard | полный цикл с базовым DESIGN и DECOMPOSITION | | 7-8 | Deep | + ADR, Alternative Architecture, Risk Register, Invariant Tests | | 9-10 | Maximum | + Red Team Review, Executable Invariants для всех ADR | -### Функции (таблица вкл/выкл) +### Функции | Функция | Фаза | Глубина | Описание | |---|---|---|---| @@ -46,180 +63,190 @@ INIT → ANALYSE → [DESIGN] → [RED_TEAM] → DECOMPOSITION → SETUP → (CH | red_team | DESIGN (после) | >=9 | Red Team Review — попытка разрушить архитектуру | | risk_register | DESIGN | >=7 | Явный реестр допущений | | invariant_tests | DECOMPOSITION | >=7 | Задачи-инварианты для каждого ADR | -| layer_structure | HANDOFF | любая | Организация .agent/ по слоям (layer-0..3) | --- ## Фаза 0: INIT -**Вход:** целевой репозиторий + опционально `.agent/metaagent-request.md`. - **Протокол:** `PROTOCOLS/00_CONFIG.md` **Действия:** - Прочитать `VERSION` — текущая версия MetaAgent - Склонировать/открыть целевой репозиторий - Создать директорию `.agent/` в корне целевого репозитория (если нет) -- **Установить исходники MetaAgent в `.agent/src/`:** - - Скопировать `META_AGENT_GUIDE.md`, `BOUNDARIES.md`, `WORKFLOW.md`, `VERSION` в `.agent/src/` - - Скопировать `PROTOCOLS/` и `TEMPLATES/` в `.agent/src/` - - Скопировать `install.sh` и `install.ps1` в `.agent/src/` (для возможности обновления) - - Если файлы уже существуют — пропустить (не перезаписывать) -- **Создать `.agent/rules/`** — директорию для пользовательских правил - - Если `.agent/rules/project-rules.md` не существует — создать из шаблона `.agent/src/TEMPLATES/project-rules.md` -- **Создать/обновить `AGENTS.md` в корне целевого репозитория** (если нет — создать, если есть — не трогать) -- Прочитать `PROTOCOLS/00_CONFIG.md` -- Выполнить 00_CONFIG: - - Если `.agent/metaagent-request.md` существует — прочитать config из него - - Если нет — провести интервью с пользователем (или принять `default`) - - Валидировать config относительно depth - - Если не было файла — создать `.agent/metaagent-request.md` с пометкой Auto-generated -- **Проверить версию:** если `.agent/checkpoints.json` существует → выполнить `PROTOCOLS/00_MIGRATE.md` (сравнить metaagent_version, применить миграцию при необходимости) -- Прочитать `PROTOCOLS/01_ANALYSIS.md` -- Инициализировать `.agent/checkpoints.json` с `metaagent_version` (если не существовал) +- Создать `.temp/` в корне целевого репозитория (если нет), добавить в `.gitignore` +- Установить исходники MetaAgent в `.agent/src/` +- Создать структуру `.agent/`: `rules/`, `decisions/`, `tasks/` (с `backlog/`), `context/`, `requests/` (с `active/`, `archive/`), `roadmap/` (с `archive/`), `archive/` (с `tasks/`, `decisions/`, `checkpoints/`) +- Создать/обновить `AGENTS.md` в корне +- Прочитать/создать `.agent/metaagent-request.md` (интервью или default) +- Проверить версию, инициализировать `checkpoints.json` -```json -{ - "metaagent_version": "1.1.0", - "session_id": "", - "target_repo": "", - "goal": "<цель от пользователя>", - "project_type": "pending", - "config": { - "depth": 4, - "design": { "adr": false, "alternative_arch": false }, - "red_team": false, - "risk_register": false, - "decomposition": { "invariant_tests": false }, - "handoff": { "layer_structure": false } - }, - "phases": { - "analysis": "pending", - "design": "pending", - "red_team": "pending", - "decomposition": "pending", - "environment": "pending", - "handoff": "pending" - }, - "tasks": [], - "last_updated": "" -} -``` - -**Выход:** готовая `.agent/` + checkpoints.json с metaagent_version и config. +**Выход:** готовая `.agent/` + checkpoints.json. --- -## Фаза 1: ANALYSE - -**Вход:** целевой репозиторий, `.agent/metaagent-request.md` (или auto-generated), checkpoints.json (analysis: pending, config: from INIT). +## Фаза 1: ANALYSIS **Протокол:** `PROTOCOLS/01_ANALYSIS.md` **Действия:** -- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила -- Прочитать config из checkpoints.json (уже получен на INIT через 00_CONFIG) -- Если config отсутствует — применить default config (depth=4) как fallback -- Выполнить анализ репозитория по протоколу (определяет тип проекта) -- Записать результат в `.agent/analysis-report.md` -- Обновить checkpoints.json: `phases.analysis = "completed"`, `project_type = "existing" | "greenfield" | "scaffold"` - -**Выход:** `.agent/analysis-report.md` +- Прочитать `.agent/rules/project-rules.md` +- Прочитать config из checkpoints.json +- Выполнить анализ репозитория: + - Определить тип проекта (existing / greenfield / scaffold) + - Зафиксировать стек, архитектуру, конвенции, тесты + - Для greenfield — извлечь требования из README +- Создать начальный `.agent/context/project-state.md` — слепок проекта +- Записать `.agent/context/analysis-report.md` +- Обновить checkpoints.json **Ветвление:** -- `project_type = "greenfield"` или `"scaffold"` → далее фаза DESIGN -- `project_type = "existing"` → DESIGN пропускается, сразу DECOMPOSITION +- `project_type = "greenfield"` или `"scaffold"` → далее ROADMAP → DESIGN +- `project_type = "existing"` → далее ROADMAP (DESIGN пропускается) + +**Выход:** `.agent/context/analysis-report.md`, `.agent/context/project-state.md` --- -## Фаза 2: DESIGN (условная) +## Фаза 2: ROADMAP -**Вход:** analysis-report.md, checkpoints.json (analysis: completed, project_type: greenfield/scaffold). +**Протокол:** `PROTOCOLS/02_ROADMAP.md` + +**Действия:** +- Прочитать `.agent/rules/project-rules.md` +- Сканировать FUTURE/ — долгосрочные планы +- Сканировать `.agent/decisions/index.json` — ADR, требующие реализации +- Учесть пользовательские запросы и выявленные улучшения +- Приоритизировать все источники (P0-P3) +- Создать `.agent/roadmap/sources.md` + +**Выход:** `.agent/roadmap/sources.md` + +--- + +## Фаза 3: DESIGN (условная) **Протокол:** `PROTOCOLS/02_DESIGN.md` +Выполняется только для greenfield/scaffold. + **Действия:** -- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила - Спроектировать архитектуру, модули, данные, интерфейсы -- Если config.design.alternative_arch: описать альтернативную архитектуру -- Если config.design.adr: создать ADR для каждого ключевого решения → `.agent/layer-1/adr/` -- Если config.risk_register: создать `.agent/layer-1/risk-register.md` -- Записать результат в `.agent/design-report.md` -- Обновить checkpoints.json: `phases.design = "completed"` +- Если config.design.adr: создать ADR → `.agent/decisions/` +- Если config.risk_register: создать `.agent/context/risk-register.md` +- Записать `.agent/context/design-report.md` -**Ветвление:** -- Если config.red_team = yes → следующая фаза RED_TEAM -- Иначе → сразу DECOMPOSITION - -**Выход:** `.agent/design-report.md`, опционально `.agent/layer-1/adr/*.md`, `.agent/layer-1/risk-register.md` +**Выход:** `.agent/context/design-report.md`, опционально ADR, risk-register --- -## Фаза 2b: RED_TEAM (опциональная) - -**Вход:** design-report.md, ADR (опционально), checkpoints.json (design: completed). +## Фаза 3b: RED_TEAM (опциональная) **Протокол:** `PROTOCOLS/02b_REDTEAM.md` -**Действия:** -- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила -- Выполнить Red Team Review по протоколу -- Записать результат в `.agent/layer-1/red-team-report.md` -- Дополнить risk-register.md (если существует) -- Если найдены критические проблемы — исправить design-report -- Обновить checkpoints.json: `phases.red_team = "completed"` +Только если config.red_team = yes (depth >= 9). -**Выход:** `.agent/layer-1/red-team-report.md` +**Выход:** `.agent/context/red-team-report.md` --- -## Фаза 3: DECOMPOSITION - -**Вход:** analysis-report.md + design-report.md (опционально) + ADR (опционально) + checkpoints.json. +## Фаза 4: DECOMPOSITION **Протокол:** `PROTOCOLS/03_DECOMPOSITION.md` **Действия:** -- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила +- Прочитать `.agent/rules/project-rules.md` - Разбить цель (и дизайн) на атомарные задачи -- Если config.decomposition.invariant_tests: создать задачи-инварианты для каждого ADR -- Записать манифест в `.agent/task-manifest.json` и `.agent/task-manifest.md` -- Обновить checkpoints.json: `phases.decomposition = "completed"`, заполнить `tasks` +- Каждой задаче присвоить `origin` (источник: roadmap, ADR, user, agent) +- Если есть `.agent/roadmap/sources.md` — сверить приоритеты +- Если config.invariant_tests: создать задачи-инварианты для ADR +- Записать `.agent/tasks/manifest.json` и `.agent/tasks/manifest.md` -**Выход:** `.agent/task-manifest.json`, `.agent/task-manifest.md` +**Выход:** `.agent/tasks/manifest.json` + `.agent/tasks/manifest.md` --- -## Фаза 4: SETUP +## Фаза 5: EXECUTION (циклическая) -**Вход:** analysis-report.md, design-report.md (опционально), task-manifest.json, checkpoints.json (decomposition: completed). - -**Протокол:** `PROTOCOLS/04_ENVIRONMENT_SETUP.md` +**Протокол:** `PROTOCOLS/04_EXECUTION.md` **Действия:** -- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила -- Выполнить настройку окружения по протоколу (ветка A для existing, ветка B для greenfield) -- Записать результат проверки в `.agent/baseline-test-report.log` и `.agent/setup-report.log` -- Обновить checkpoints.json: `phases.environment = "completed"` +1. Выбрать следующую задачу из manifest.json (pending, все depends_on выполнены) +2. Отметить `in_progress` +3. Реализовать (код, тесты, конфиги) +4. Верифицировать (тесты, LSP diagnostics) +5. Закоммитить +6. Создать request в `.agent/requests/active/req-{id}.json` +7. Отметить `completed` в manifest.json +8. Повторить, пока есть задачи +9. Если задач нет — ожидать команду пользователя -**Выход:** рабочее окружение + `.agent/baseline-test-report.log` +**Request — единица результата:** +```json +{ + "request_id": "req-T1", + "task_id": "T1", + "title": "Human-readable title", + "status": "ready_for_review", + "changes": { + "summary": "Суть изменений", + "commits": ["abc1234"], + "files_changed": ["path/to/file.py"] + }, + "verification": { + "tests_passed": "24/24", + "lsp_clean": true + }, + "fulfills_ac": ["AC1"] +} +``` + +**Выход:** выполненные задачи в manifest + request-ы в `.agent/requests/active/` --- -## Фаза 5: CHECKPOINT (сквозная) +## Фаза 6: METASTATE (по команде пользователя) -**Вход:** любая фаза. +**Протокол:** `PROTOCOLS/06_METASTATE.md` -**Протокол:** обновлять checkpoints.json после каждого значимого шага. +Запускается по команде: «обнови метасостояние», «update metastate», «подведи итог». -**Архивирование перед сохранением чекпоинта:** -- Если checkpoints.json уже существует — сохранить предыдущую версию в `.agent/archive/checkpoints/.json` +**Действия:** +1. **Ревью requests** — проверить каждый `ready_for_review`: + - ✅ approved → в `.agent/requests/archive/`, задача confirmed + - ❌ rejected → задача reopened, комментарий +2. **Архивация** — completed задачи → one-liner в manifest, детали в `.agent/archive/tasks/` +3. **Обновление project-state.md** — актуальный слепок проекта +4. **Обновление roadmap** — отметить выполненное, пересчитать приоритеты +5. **Создание handoff-summary.md** — полная сводка для следующего агента +6. **Индекс архива** — `.agent/archive/index.json` -**Формат:** +**Выход:** обновлённый `.agent/` — полный слепок проекта. Следующий агент читает только `.agent/`. + +--- + +## Фаза 7: HANDOFF + +**Протокол:** `PROTOCOLS/05_HANDOFF.md` + +**Действия:** +- Если METASTATE был — просто валидировать и финализировать +- Если METASTATE не было — лёгкая архивация completed задач +- Валидация структуры `.agent/` +- Создание `.agent/session-summary.md` +- Финализация checkpoints.json + +**Выход:** `.agent/session-summary.md`, финальный checkpoints.json + +--- + +## Checkpoint (сквозная) + +checkpoints.json обновляется после каждой фазы: ```json { - "metaagent_version": "1.1.0", + "metaagent_version": "2.1.0", "session_id": "", "target_repo": "", "goal": "<цель>", @@ -229,108 +256,125 @@ INIT → ANALYSE → [DESIGN] → [RED_TEAM] → DECOMPOSITION → SETUP → (CH "design": { "adr": true, "alternative_arch": true }, "red_team": false, "risk_register": false, - "decomposition": { "invariant_tests": true }, - "handoff": { "layer_structure": true } + "decomposition": { "invariant_tests": true } }, "phases": { "analysis": "completed", + "roadmap": "completed", "design": "completed", "red_team": "skipped", - "decomposition": "in_progress", - "environment": "pending", - "handoff": "pending" + "decomposition": "completed", + "execution": "completed", + "metastate": "completed", + "handoff": "completed" }, "tasks": [ - { "id": "T1", "title": "...", "status": "completed", - "depends_on": [], "acceptance_criteria": ["..."] }, - { "id": "T2", "title": "...", "status": "pending", - "depends_on": ["T1"], "acceptance_criteria": ["..."] } + { "id": "T1", "title": "...", "status": "archived", "origin": "user:direct" }, + { "id": "T2", "title": "...", "status": "pending", "origin": "roadmap:010" } ], "last_updated": "" } ``` -`status` может быть: `pending`, `in_progress`, `completed`, `failed`, `skipped`. -Фаза `red_team` может быть `skipped` если config.red_team = false. - ---- - -## Фаза 6: HANDOFF - -**Вход:** все предыдущие фазы completed. - -**Протокол:** `PROTOCOLS/05_HANDOFF.md` - -**Действия:** -- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила -- **Архивировать завершённые задачи:** - - Для каждой задачи со статусом `completed` в `task-manifest.json`: - - Перенести полное описание в `.agent/archive/tasks/.json` - - Заменить в манифесте на one-liner: `{ "id": "", "title": "", "status": "archived" }` - - Создать `.agent/archive/index.json` со списком архивированных задач - - Заархивировать предыдущий `checkpoints.json` в `.agent/archive/checkpoints/` -- Выполнить валидацию всех артефактов -- Если config.handoff.layer_structure: организовать `.agent/` по слоям -- Записать `.agent/handoff-summary.md` (в layer-3 при layer_structure=yes) -- Создать `.agent/session-summary.md` (в layer-0 при layer_structure=yes) -- Обновить checkpoints.json: `phases.handoff = "completed"` -- Сообщить пользователю/оркестратору - -**Выход:** `.agent/handoff-summary.md` — итоговый документ для исполнительного агента. - ---- - -## Фаза 7: EXIT - -Мета-агент завершает работу. Управление переходит к исполнительному агенту. - --- ## Структура .agent/ -.agent/ всегда содержит служебную директорию `src/` с исходниками MetaAgent (см. фазу INIT). -При layer_structure=yes артефакты сессии раскладываются по слоям layer-0..3. - ``` .agent/ - src/ # исходники MetaAgent (всегда) - META_AGENT_GUIDE.md # главная инструкция - PROTOCOLS/ # протоколы фаз - TEMPLATES/ # шаблоны артефактов - BOUNDARIES.md # границы - WORKFLOW.md # примеры работы - VERSION # версия MetaAgent - install.sh # скрипт установки/обновления (Unix) - install.ps1 # скрипт установки/обновления (Windows) - rules/ # пользовательские правила (всегда) - project-rules.md # правила проекта — читать перед каждой фазой - archive/ # архив завершённых артефактов (создаётся при HANDOFF) - index.json # мета-индекс архива - tasks/ # детали завершённых задач - checkpoints/ # исторические чекпоинты - adr/ # заменённые ADR - reports/ # устаревшие отчёты - layer-0/ # ядро сессии (только при layer_structure=yes) - checkpoints.json # всегда (ядро) - session-summary.md # краткая сводка сессии - layer-1/ # архитектурные решения (справочно) - adr/ - 001-технологический-стек.md - 002-архитектурный-паттерн.md - ... + checkpoints.json # состояние сессии (ядро) + session-summary.md # краткая сводка сессии + handoff-summary.md # сводка для следующего агента (создаётся METASTATE) + + src/ # исходники MetaAgent (всегда) + META_AGENT_GUIDE.md + PROTOCOLS/ + TEMPLATES/ + BOUNDARIES.md + WORKFLOW.md + VERSION + install.sh / install.ps1 + + rules/ + project-rules.md + + roadmap/ # ИСТОЧНИКИ ЗАДАЧ (новое в v2.1) + sources.md # консолидированный список с приоритетами + archive/ # устаревшие roadmap-планы + + decisions/ # архитектурные решения (ADR) + index.json + 001-*.md + + tasks/ # задачи + manifest.json # + поле origin + manifest.md + backlog/ + + requests/ # ЕДИНИЦЫ РЕЗУЛЬТАТА (новое в v2.1) + active/ # req-T1.json (ready_for_review) + archive/ # req-T1.json (approved/rejected) + + context/ + analysis-report.md # замороженный анализ на старте + project-state.md # динамический слепок проекта (обновляется METASTATE) + design-report.md risk-register.md red-team-report.md - layer-2/ # дизайн и анализ (справочно) - analysis-report.md - design-report.md - layer-3/ # состояние исполнения - handoff-summary.md - task-manifest.json - task-manifest.md baseline-test-report.log - setup-report.log + + archive/ + index.json + tasks/ + decisions/ + requests/ + checkpoints/ ``` -Исполнительный агент всегда начинает с layer-0 (checkpoints + session-summary), -затем при необходимости обращается к layer-1 (ADR для понимания "почему"), -layer-2 (детали дизайна), layer-3 (что было сделано). +`.temp/` в корне проекта: + +``` +.temp/ + downloads/ + patches/ + cache/ + agent-session-xxx/ +``` + +--- + +## Принципы работы + +### Два контура + +**Project Loop** (однократно): INIT → ANALYSIS → ROADMAP → DESIGN → DECOMPOSITION. +Настраивает проект, определяет задачи. + +**Work Loop** (циклически): EXECUTION → (request) → METASTATE (по команде). +Агент работает, создаёт requests, по команде пользователя подводит итог. + +### Request — единица результата + +Каждая выполненная задача завершается созданием request. Не просто «сделано», а документированный результат: +- суть изменений (не diff, а именно суть) +- ссылки на коммиты +- верификация (тесты, LSP) +- какие acceptance criteria закрыты + +Request проходит ревью в METASTATE. + +### .agent/ как слепок проекта + +После METASTATE `.agent/` содержит полную картину. Следующий агент читает `.agent/` и не лезет в исходники проекта. + +### Depth scale + +Определяет глубину проработки: + +| Depth | PROJECT LOOP | WORK LOOP | +|-------|-------------|-----------| +| 1-2 | INIT → ANALYSIS → DECOMP | EXECUTION (scaffold only) | +| 3-4 | + ROADMAP, DESIGN (light) | EXECUTION → METASTATE | +| 5-6 | + DESIGN (full), invariants | EXECUTION → METASTATE | +| 7-8 | + ADR, risk_register | EXECUTION → METASTATE | +| 9-10 | + Red Team | EXECUTION → METASTATE | \ No newline at end of file diff --git a/.agent/src/PROTOCOLS/00_CONFIG.md b/.agent/src/PROTOCOLS/00_CONFIG.md index bcaab2f..5e8a679 100644 --- a/.agent/src/PROTOCOLS/00_CONFIG.md +++ b/.agent/src/PROTOCOLS/00_CONFIG.md @@ -66,9 +66,6 @@ Q5 (если глубина >= 9): Нужен Red Team Review? "risk_register": false, "decomposition": { "invariant_tests": false - }, - "handoff": { - "layer_structure": false } } ``` @@ -78,7 +75,7 @@ Depth=4 (Light) означает: - DESIGN — выполняется (если greenfield), но **без** ADR, Alternative Architecture, Risk Register - DECOMPOSITION — задачи с acceptance criteria, **без** invariant-тестов - SETUP — полный -- HANDOFF — плоский `.agent/` (без layer-структуры) +- HANDOFF — `.agent/` организован по семантическим группам (decisions, tasks, context, rules) ### 0.4. Запись .agent/metaagent-request.md @@ -98,7 +95,7 @@ Depth=4 (Light) означает: | RISK_REGISTER | {{ risk_register }} | — | | DECOMPOSITION | ✓ | invariant_tests={{ invariant_tests }} | | SETUP | ✓ | — | -| HANDOFF | ✓ | layer_structure={{ layer_structure }} | +| HANDOFF | ✓ | — | ## Глубина проработки diff --git a/.agent/src/PROTOCOLS/00_INIT.md b/.agent/src/PROTOCOLS/00_INIT.md new file mode 100644 index 0000000..eab0cd3 --- /dev/null +++ b/.agent/src/PROTOCOLS/00_INIT.md @@ -0,0 +1,128 @@ +# Протокол 00: Инициализация (INIT) + +## Цель + +Подготовить `.agent/` в целевом репозитории: установить исходники MetaAgent, создать структуру директорий, инициализировать `checkpoints.json`, создать/обновить `AGENTS.md`. + +INIT выполняется **один раз** в начале работы с проектом. Если `.agent/` уже существует и инициализирован — пропускается. + +## Вход + +- Целевой репозиторий (путь или текущая директория) +- `VERSION` — текущая версия MetaAgent +- Опционально: существующий `.agent/` (если обновление) + +## Шаги + +### 0.1. Определить целевой репозиторий + +Если не указан явно — текущая рабочая директория. Если указан как URL — клонировать во временную директорию, дальше работать с копией. + +### 0.2. Проверить существующий `.agent/` + +Если `.agent/` существует: + +- Прочитать `.agent/checkpoints.json` → `metaagent_version` +- Если `metaagent_version == VERSION` → INIT уже выполнен, выйти +- Если версия старше → запустить `install.sh --update` (Unix) или `install.ps1 -Update` (Windows) для переустановки исходников, затем выйти +- Если `.agent/` есть, но `checkpoints.json` отсутствует → продолжить INIT (создать checkpoints) + +Если `.agent/` не существует → продолжить INIT. + +### 0.3. Создать структуру `.agent/` + +Создать директории: + +``` +.agent/ + src/ # исходники MetaAgent (копируются из METAAGENT_SRC) + rules/ + decisions/ + tasks/ + backlog/ + context/ + requests/ + active/ + archive/ + roadmap/ + archive/ + archive/ + tasks/ + decisions/ + requests/ + checkpoints/ +``` + +### 0.4. Создать `.temp/` в корне проекта + +Если не существует — создать `.temp/` в корне целевого репозитория. Добавить в `.gitignore` (если его нет — создать с одной строкой `.temp/`). + +### 0.5. Скопировать исходники MetaAgent + +Скопировать в `.agent/src/`: + +- `GUIDE.md` +- `BOUNDARIES.md` +- `CHANGELOG.md` +- `VERSION` +- `PROTOCOLS/` +- `COMMANDS/` +- `TEMPLATES/` +- `install.sh`, `install.ps1` + +Существующие файлы в `.agent/src/` не перезаписывать (только с явным `--update`). + +### 0.6. Создать `.agent/rules/project-rules.md` + +Если файла нет — создать по шаблону `TEMPLATES/project-rules.md`. + +### 0.7. Создать/обновить `AGENTS.md` в корне + +Если `AGENTS.md` в корне проекта отсутствует — создать по `AGENTS.template.md` с подставленной версией. + +Если существует и не относится к MetaAgent — не трогать (попросить пользователя переименовать или подтвердить перезапись). + +### 0.8. Инициализировать `checkpoints.json` + +Создать `.agent/checkpoints.json`: + +```json +{ + "metaagent_version": "3.0.0", + "session_id": "<uuid>", + "target_repo": "<путь>", + "goal": null, + "project_type": null, + "phases": { + "init": "completed", + "analyse": "pending", + "roadmap": "pending", + "design": "pending", + "decomposition": "pending", + "execution": "pending", + "metastate": "pending", + "handoff": "pending" + }, + "tasks": [], + "last_updated": "<timestamp>" +} +``` + +Поля `goal` и `project_type` остаются `null` до фазы ANALYSE (goal может быть задан пользователем заранее — тогда заполнить сразу). + +## Выход + +- `.agent/` с полной структурой +- `.agent/src/` с актуальными исходниками MetaAgent +- `.agent/rules/project-rules.md` +- `.agent/checkpoints.json` со `session_id` и `phases.init = "completed"` +- `AGENTS.md` в корне проекта +- `.temp/` в корне + `.gitignore` обновлён + +## Критерии завершения + +- [ ] `.agent/` содержит все обязательные директории +- [ ] `.agent/src/` содержит GUIDE.md, PROTOCOLS/, COMMANDS/, TEMPLATES/, VERSION +- [ ] `.agent/checkpoints.json` валиден (JSON parse) +- [ ] `AGENTS.md` присутствует в корне +- [ ] `.temp/` существует и в `.gitignore` diff --git a/.agent/src/PROTOCOLS/00_MIGRATE.md b/.agent/src/PROTOCOLS/00_MIGRATE.md index ca20668..f6f6e07 100644 --- a/.agent/src/PROTOCOLS/00_MIGRATE.md +++ b/.agent/src/PROTOCOLS/00_MIGRATE.md @@ -45,6 +45,7 @@ def needs_migration(stored, current): |---|---|---| | v0.x (нет поля) | v1.0.0 | M3.1 — M3.4 | | v1.0.0 | v1.1.0 | M3.5 — M3.6 (см. ниже) | +| v1.1.x | v2.0.0 | M6.1 — M6.17 (см. ниже) | ### M4. Шаги миграции v0.x → v1.0.0 @@ -97,6 +98,158 @@ touch .agent/layer-1/adr/.gitkeep Если `risk-register.md` уже существует на верхнем уровне — переместить в `.agent/layer-1/risk-register.md`. +### M6. Шаги миграции v1.1.x → v2.0.0 + +Цель: перейти от layer-0..3 структуры к семантической (decisions/tasks/context/rules). + +#### M6.1. Удалить `handoff.layer_structure` из config + +Если в `checkpoints.json` присутствует `config.handoff.layer_structure` — удалить поле: + +```python +checkpoints["config"].pop("handoff", None) +# или если handoff пуст — удалить целиком +if "handoff" in checkpoints["config"] and not checkpoints["config"]["handoff"]: + del checkpoints["config"]["handoff"] +``` + +#### M6.2. Создать новые директории + +```bash +mkdir -p .agent/decisions +mkdir -p .agent/tasks/backlog +mkdir -p .agent/context +mkdir -p .agent/archive/decisions +``` + +#### M6.3. Перенести ADR (.agent/layer-1/adr/ → .agent/decisions/) + +```bash +if [ -d ".agent/layer-1/adr" ]; then + cp -n .agent/layer-1/adr/*.md .agent/decisions/ 2>/dev/null || true +fi +``` + +#### M6.4. Создать decisions/index.json + +Если в `.agent/decisions/` есть .md файлы — создать индекс: + +```json +{ + "version": "2.0.0", + "decisions": [ + { "id": "001", "title": "<извлечь из первого заголовка>", "file": "001-....md" } + ], + "created_at": "<timestamp>" +} +``` + +#### M6.5. Перенести risk-register.md (.agent/layer-1/ → .agent/context/) + +```bash +if [ -f ".agent/layer-1/risk-register.md" ]; then + mv .agent/layer-1/risk-register.md .agent/context/risk-register.md +fi +``` + +#### M6.6. Перенести red-team-report.md (.agent/layer-1/ → .agent/context/) + +```bash +if [ -f ".agent/layer-1/red-team-report.md" ]; then + mv .agent/layer-1/red-team-report.md .agent/context/red-team-report.md +fi +``` + +#### M6.7. Перенести analysis-report.md (.agent/layer-2/ → .agent/context/) + +```bash +if [ -f ".agent/layer-2/analysis-report.md" ]; then + mv .agent/layer-2/analysis-report.md .agent/context/analysis-report.md +fi +``` + +#### M6.8. Перенести design-report.md (.agent/layer-2/ → .agent/context/) + +```bash +if [ -f ".agent/layer-2/design-report.md" ]; then + mv .agent/layer-2/design-report.md .agent/context/design-report.md +fi +``` + +#### M6.9. Перенести task-manifest (.agent/task-manifest.json → .agent/tasks/manifest.json) + +```bash +if [ -f ".agent/task-manifest.json" ]; then + mv .agent/task-manifest.json .agent/tasks/manifest.json +fi +if [ -f ".agent/task-manifest.md" ]; then + mv .agent/task-manifest.md .agent/tasks/manifest.md +fi +``` + +#### M6.10. Перенести handoff-summary.md (.agent/layer-3/ → .agent/) + +```bash +if [ -f ".agent/layer-3/handoff-summary.md" ]; then + mv .agent/layer-3/handoff-summary.md .agent/handoff-summary.md +fi +``` + +#### M6.11. Перенести baseline-test-report.log (.agent/layer-3/ → .agent/context/) + +```bash +if [ -f ".agent/layer-3/baseline-test-report.log" ]; then + mv .agent/layer-3/baseline-test-report.log .agent/context/baseline-test-report.log +fi +``` + +#### M6.12. Перенести setup-report.log (.agent/layer-3/ → .agent/context/) + +```bash +if [ -f ".agent/layer-3/setup-report.log" ]; then + mv .agent/layer-3/setup-report.log .agent/context/setup-report.log +fi +``` + +#### M6.13. Перенести session-summary.md (.agent/layer-0/ → .agent/) + +```bash +if [ -f ".agent/layer-0/session-summary.md" ]; then + mv .agent/layer-0/session-summary.md .agent/session-summary.md +fi +``` + +#### M6.14. Перенести checkpoints.json (.agent/layer-0/ → .agent/) + +```bash +if [ -f ".agent/layer-0/checkpoints.json" ]; then + cp .agent/layer-0/checkpoints.json .agent/checkpoints.json + echo "[backup] layer-0/checkpoints.json сохранён на случай отката" +fi +``` + +#### M6.15. Перенести archive/adr/ → archive/decisions/ + +```bash +if [ -d ".agent/archive/adr" ]; then + cp -n .agent/archive/adr/* .agent/archive/decisions/ 2>/dev/null || true + rm -rf .agent/archive/adr +fi +``` + +#### M6.16. Удалить пустые layer-директории + +```bash +rm -rf .agent/layer-0 .agent/layer-1 .agent/layer-2 .agent/layer-3 +rm -rf .agent/archive/reports 2>/dev/null || true +``` + +#### M6.17. Обновить metaagent_version в checkpoints.json + +```json +"metaagent_version": "2.0.0" +``` + ### M4. После миграции — резюме Записать в `.agent/migration-report.log`: @@ -112,7 +265,7 @@ touch .agent/layer-1/adr/.gitkeep ## Выход - Обновлённый `.agent/checkpoints.json` (metaagent_version + config) -- Опционально: `.agent/layer-1/` структура +- Обновлённая структура `.agent/` (decisions/tasks/context вместо layer-0..3) - `.agent/migration-report.log` ## Критерии завершения diff --git a/.agent/src/PROTOCOLS/01_ANALYSE.md b/.agent/src/PROTOCOLS/01_ANALYSE.md new file mode 100644 index 0000000..7d0b997 --- /dev/null +++ b/.agent/src/PROTOCOLS/01_ANALYSE.md @@ -0,0 +1,95 @@ +# Протокол 01: Анализ репозитория (ANALYSE) + +## Цель + +Составить полную картину целевого репозитория: тип проекта, стек, архитектура, конвенции, состояние тестов. Создать начальный слепок проекта. + +## Вход + +- Целевой репозиторий +- `.agent/checkpoints.json` (фаза analyse: pending) +- `.agent/rules/project-rules.md` — прочитать первым + +## Шаги + +### 1.1. Прочитать правила проекта + +Прежде чем что-либо делать — прочитать `.agent/rules/project-rules.md`. Если есть правила, применить их к фазе. + +### 1.2. Определить тип проекта + +Просканировать корень репозитория: + +- **`existing`** — есть исходный код, тесты, система сборки (`.py`, `.js`, `.ts`, `.rs`, `.go` и т.д. помимо конфигов и README). +- **`greenfield`** — пусто или только README/LICENSE/.gitignore. +- **`scaffold`** — есть базовая структура (`pyproject.toml`/`package.json`), но нет значимого кода. + +Записать тип в `checkpoints.json → project_type`. + +### 1.3. Сканировать проект + +Для `existing` / `scaffold` собрать: + +- **README** — описание, инструкции по сборке/тестам. +- **Лицензия** — какой LICENSE. +- **CI/CD** — `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `Makefile`. +- **Стек** — язык, фреймворк, БД, тестовый раннер, пакетный менеджер, линтер. +- **Структура** — `tree -L 3` (не более 3 уровней). +- **Архитектурный паттерн** — MVC, модульный монолит, микросервисы, слоистая. +- **Ключевые модули/пакеты** — список с краткой ответственностью. +- **Конвенции** — стиль, именование, обработка ошибок, логирование. +- **Тесты** — где лежат, как запускаются, текущее состояние (запустить). +- **Сборка** — выполняется ли проект. + +Для `greenfield` — извлечь требования из README: + +- Функциональные требования (user stories, сценарии). +- Нефункциональные (стек, производительность, безопасность). +- Бизнес-контекст (зачем, для кого). +- Сомнительные / неясные требования (вопросы пользователю). + +### 1.4. Создать analysis-report + +Записать `.agent/context/analysis-report.md` по шаблону `TEMPLATES/analysis-report.md`. Заполнить соответствующие секции. + +### 1.5. Создать начальный project-state + +Создать `.agent/context/project-state.md` по шаблону `TEMPLATES/project-state.md`. Это **начальный** слепок. В дальнейшем обновляется в фазе METASTATE. + +Заполнить: +- Тип проекта +- Краткая архитектура (из шага 1.3) +- Ключевые модули и их статус +- Tech stack +- Статус тестов + +### 1.6. Обновить checkpoints + +```json +{ + "phases": { "analyse": "completed" }, + "project_type": "existing | greenfield | scaffold", + "last_updated": "<timestamp>" +} +``` + +## Ветвление + +| project_type | Следующая фаза | +|---|---| +| `existing` | ROADMAP → DECOMPOSITION (DESIGN пропускается) | +| `greenfield` | ROADMAP → DESIGN → DECOMPOSITION | +| `scaffold` | ROADMAP → DESIGN → DECOMPOSITION | + +## Выход + +- `.agent/context/analysis-report.md` +- `.agent/context/project-state.md` (начальный) +- Обновлённый `checkpoints.json` + +## Критерии завершения + +- [ ] Тип проекта определён +- [ ] `analysis-report.md` содержит все соответствующие секции +- [ ] `project-state.md` создан с начальным слепком +- [ ] `checkpoints.json` обновлён diff --git a/.agent/src/PROTOCOLS/01_ANALYSIS.md b/.agent/src/PROTOCOLS/01_ANALYSIS.md index e4f71dd..0924de4 100644 --- a/.agent/src/PROTOCOLS/01_ANALYSIS.md +++ b/.agent/src/PROTOCOLS/01_ANALYSIS.md @@ -24,8 +24,7 @@ "design": { "adr": false, "alternative_arch": false }, "red_team": false, "risk_register": false, - "decomposition": { "invariant_tests": false }, - "handoff": { "layer_structure": false } + "decomposition": { "invariant_tests": false } } ``` @@ -36,8 +35,7 @@ "design": { "adr": true, "alternative_arch": true }, "red_team": false, "risk_register": false, - "decomposition": { "invariant_tests": true }, - "handoff": { "layer_structure": true } + "decomposition": { "invariant_tests": true } } ``` @@ -125,15 +123,27 @@ - Вопросы, которые нужно задать пользователю перед проектированием - Противоречия в README +### 1.8. Initial project state snapshot + +После завершения анализа создать `.agent/context/project-state.md` — начальный слепок проекта по шаблону `TEMPLATES/project-state.md`: +- Тип проекта +- Текущая архитектура (кратко, из p.1.3) +- Ключевые модули и их статус (existing/stub/nonexistent) +- Tech stack (из p.1.2) +- Статус тестов (из p.1.5) +- Этот файл будет обновляться фазой METASTATE по мере эволюции проекта + ## Выход -`.agent/analysis-report.md` по шаблону `TEMPLATES/analysis-report.md`. +- `.agent/context/analysis-report.md` по шаблону `TEMPLATES/analysis-report.md` +- `.agent/context/project-state.md` — начальный слепок проекта Обновить checkpoints.json: `phases.analysis = "completed"`. Если проект `greenfield`, также установить `project_type = "greenfield"`. ## Критерии завершения фазы - [ ] Тип проекта определён (existing / greenfield / scaffold) -- [ ] Все соответствующие разделы (1.1–1.7) выполнены -- [ ] `.agent/analysis-report.md` создан и заполнен +- [ ] Все соответствующие разделы (1.1–1.8) выполнены +- [ ] `.agent/context/analysis-report.md` создан и заполнен +- [ ] `.agent/context/project-state.md` создан с начальным слепком - [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/02_DESIGN.md b/.agent/src/PROTOCOLS/02_DESIGN.md index b9b684f..2c345cb 100644 --- a/.agent/src/PROTOCOLS/02_DESIGN.md +++ b/.agent/src/PROTOCOLS/02_DESIGN.md @@ -6,7 +6,7 @@ ## Вход -- `.agent/analysis-report.md` (project_type: greenfield или scaffold) +- `.agent/context/analysis-report.md` (project_type: greenfield или scaffold) - `.agent/metaagent-request.md` (конфигурация сессии: adr, alternative_arch, risk_register) - `.agent/checkpoints.json` (фаза design: pending) @@ -120,16 +120,16 @@ Для каждого ключевого архитектурного решения (стек, БД, паттерн, структура модулей) создать отдельный ADR-файл: ``` -.agent/layer-1/adr/001-технологический-стек.md -.agent/layer-1/adr/002-модульный-монолит.md -.agent/layer-1/adr/003-json-хранение.md +.agent/decisions/001-технологический-стек.md +.agent/decisions/002-модульный-монолит.md +.agent/decisions/003-json-хранение.md ``` Формат — по шаблону `TEMPLATES/adr-NNNN.md`. ### 2.10. Risk Register (если config.risk_register = yes) -Создать `.agent/layer-1/risk-register.md` по шаблону `TEMPLATES/risk-register.md`: +Создать `.agent/context/risk-register.md` по шаблону `TEMPLATES/risk-register.md`: | # | Assumption | Impact if wrong | Mitigation | Review trigger | |---|---|---|---|---| @@ -150,9 +150,9 @@ T4: API endpoints ## Выход -- `.agent/design-report.md` по шаблону `TEMPLATES/design-report.md` -- `.agent/layer-1/adr/*.md` (если adr=yes) -- `.agent/layer-1/risk-register.md` (если risk_register=yes) +- `.agent/context/design-report.md` по шаблону `TEMPLATES/design-report.md` +- `.agent/decisions/*.md` (если adr=yes) +- `.agent/context/risk-register.md` (если risk_register=yes) - Предварительная группировка задач (для передачи в DECOMPOSITION) Обновить checkpoints.json: `phases.design = "completed"`. @@ -169,5 +169,5 @@ T4: API endpoints - [ ] ADR созданы (если config требует) - [ ] Risk Register создан (если config требует) - [ ] Задачи предварительно сгруппированы -- [ ] `.agent/design-report.md` создан +- [ ] `.agent/context/design-report.md` создан - [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/02_ROADMAP.md b/.agent/src/PROTOCOLS/02_ROADMAP.md new file mode 100644 index 0000000..14bcbed --- /dev/null +++ b/.agent/src/PROTOCOLS/02_ROADMAP.md @@ -0,0 +1,99 @@ +# Протокол 02: Дорожная карта (ROADMAP) + +## Цель + +Определить источники задач для проекта, их приоритеты и взаимосвязи. ROADMAP — мост между видением проекта и конкретными задачами в манифесте. + +## Вход + +- `.agent/context/analysis-report.md` — анализ репозитория +- `.agent/metaagent-request.md` — цель сессии +- `FUTURE/` — директория долгосрочных планов (если существует) +- `.agent/decisions/index.json` — принятые ADR (опционально) +- `.agent/checkpoints.json` (фаза roadmap: pending) +- Внешние источники: issues, feedback, пользовательские запросы + +## Шаги + +### 2.1. Сканирование FUTURE/ + +Если в корне проекта существует `FUTURE/`: +- Прочитать все `.md` файлы +- Каждый план: название, статус (active/archived), приоритет, зависимости +- Зафиксировать, какие планы уже реализованы, какие ожидают + +### 2.2. Сканирование ADR + +Если существует `.agent/decisions/index.json`: +- Прочитать индекс ADR +- Определить, какие решения требуют реализации (не все ADR — технические, часть может быть организационными) +- Для каждого ADR, требующего реализации: сформулировать задачу + +### 2.3. Внешние источники + +- Прочитать `.agent/metaagent-request.md` — явные запросы пользователя +- Если есть issues / feedback — включить в анализ +- Если агент обнаружил tech debt или улучшения в ANALYSIS — зафиксировать + +### 2.4. Приоритизация + +Присвоить каждой задаче приоритет: + +| Приоритет | Описание | +|-----------|----------| +| **P0** | Критично, делать следующим | +| **P1** | Важно, сделать скоро | +| **P2** | Желательно | +| **P3** | В долгосрочной перспективе / отложено | + +Правила приоритизации: +- Блокирующие зависимости поднимают приоритет задачи +- User-requested задачи получают P0-P1 по умолчанию +- ADR-задачи получают приоритет, соответствующий срочности решения + +### 2.5. Консолидация в sources.md + +Создать `.agent/roadmap/sources.md` по шаблону `TEMPLATES/roadmap-sources.md`: + +``` +# Roadmap Sources + +## FUTURE Plans +| План | Приоритет | Статус | +|------|-----------|--------| +| 010-omo-integration | P1 | active | + +## ADR-Derived Tasks +| ADR | Задача | Приоритет | +|-----|--------|-----------| + +## User Requests +| Запрос | Приоритет | Источник | +|--------|-----------|----------| + +## Agent-Identified Improvements +| Наблюдение | Задача | Приоритет | +|------------|--------|-----------| + +## Consolidated Priority Queue +1. task (origin) — P0 +``` + +### 2.6. Архивация устаревших roadmap + +Если в `.agent/roadmap/archive/` есть предыдущие версии — они остаются справочно. +Если какие-то планы из FUTURE/* больше не актуальны — переместить в `FUTURE/archive/`. + +## Выход + +- `.agent/roadmap/sources.md` — консолидированный список источников задач с приоритетами +- Обновлённый `FUTURE/` (если были перемещения в archive) +- Обновить checkpoints.json: `phases.roadmap = "completed"` + +## Критерии завершения + +- [ ] Все источники задач просканированы (FUTURE, ADR, пользователь, агент) +- [ ] `.agent/roadmap/sources.md` создан с приоритетами P0-P3 +- [ ] Каждая задача имеет origin-ссылку на источник +- [ ] Устаревшие планы перемещены в archive +- [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/02b_REDTEAM.md b/.agent/src/PROTOCOLS/02b_REDTEAM.md index 9b6848a..0ecc181 100644 --- a/.agent/src/PROTOCOLS/02b_REDTEAM.md +++ b/.agent/src/PROTOCOLS/02b_REDTEAM.md @@ -6,8 +6,8 @@ ## Вход -- `.agent/design-report.md` -- `.agent/layer-1/adr/*.md` (если созданы) +- `.agent/context/design-report.md` +- `.agent/decisions/*.md` (если созданы) - `.agent/metaagent-request.md` (глубина проработки >= 9) ## Когда выполняется @@ -56,7 +56,7 @@ ## Выход -`.agent/layer-1/red-team-report.md` с секциями: +`.agent/context/red-team-report.md` с секциями: ``` ## Найденные проблемы diff --git a/.agent/src/PROTOCOLS/03_DECOMPOSITION.md b/.agent/src/PROTOCOLS/03_DECOMPOSITION.md index 39cfa23..f05564a 100644 --- a/.agent/src/PROTOCOLS/03_DECOMPOSITION.md +++ b/.agent/src/PROTOCOLS/03_DECOMPOSITION.md @@ -6,10 +6,11 @@ ## Вход -- `.agent/analysis-report.md` -- `.agent/design-report.md` (опционально — для greenfield/scaffold) -- `.agent/layer-1/adr/*.md` (опционально) -- `.agent/layer-1/risk-register.md` (опционально) +- `.agent/context/analysis-report.md` +- `.agent/context/design-report.md` (опционально — для greenfield/scaffold) +- `.agent/decisions/*.md` (опционально) +- `.agent/context/risk-register.md` (опционально) +- `.agent/roadmap/sources.md` (опционально — из фазы ROADMAP) - `.agent/metaagent-request.md` (конфигурация сессии) - Цель пользователя (из checkpoints.json) - `.agent/checkpoints.json` (фаза decomposition: pending) @@ -33,7 +34,14 @@ - Затрагивает 5+ файлов - Содержит союзы "и", "а также", "после чего" -### 3.3. Структура задачи +### 3.3. Учёт roadmap + +Если существует `.agent/roadmap/sources.md`: +- Сверить задачи с roadmap-приоритетами +- Задачи из roadmap получают приоритет P0-P3 в соответствии с sources.md +- Задачи без явного источника получают `origin: "decomposition"` + +### 3.4. Структура задачи Каждая задача содержит: @@ -44,12 +52,20 @@ | `description` | Описание (как и зачем) | "Создать SQLAlchemy модель..." | | `type` | Тип задачи | `feature`, `refactor`, `test`, `fix`, `config`, `design`, `docs` | | `status` | Статус задачи | `pending`, `in_progress`, `completed`, `failed`, `archived` | +| `origin` | Источник задачи | `roadmap:filename`, `adr:NNN`, `user:direct`, `agent:analysis`, `decomposition` | | `files` | Список файлов, которые нужно создать/изменить | `["app/models/user.py"]` | | `depends_on` | ID задач, от которых зависит | `[]` или `["T0"]` | | `acceptance_criteria` | Список критериев приёмки (3-5 пунктов) | `["Модель проходит миграцию"]` | | `context` | Доп. информация (ссылки на доки, примеры, релевантные секции из design-report) | `"Смотри app/models/base.py"` | -### 3.4. Типы задач +`origin` связывает задачу с источником: +- `roadmap:{filename}` — из FUTURE/ или roadmap плана +- `adr:{NNN}` — из Architecture Decision Record +- `user:direct` — напрямую от пользователя +- `agent:analysis` — выявлено агентом при анализе +- `decomposition` — создано при декомпозиции без внешнего источника + +### 3.5. Типы задач (нумерация сдвинута) | Тип | Описание | |---|---| @@ -62,25 +78,25 @@ | `docs` | Документация | | `invariant` | Тест, проверяющий архитектурный инвариант (см. 3.7) | -### 3.5. Зелёная декомпозиция (для greenfield/scaffold) +### 3.6. Зелёная декомпозиция (для greenfield/scaffold) -Если есть `.agent/design-report.md` — задачи формируются на основе группировки из дизайна: +Если есть `.agent/context/design-report.md` — задачи формируются на основе группировки из дизайна: 1. **T1: init** — инициализация проекта, зависимости, конфиги, scaffold 2. **T2..Tn: features** — модули/функциональность по одному 3. **Tn+1: tests** — тесты на каждый модуль (можно в составе feature-задачи) 4. **Tn+2: polish** — документация, форматирование, финальная проверка -### 3.6. Сортировка +### 3.7. Сортировка Задачи в манифесте располагаются в порядке выполнения: 1. Сначала задачи без зависимостей 2. Потом те, чьи зависимости уже выполнены 3. Последними — задачи с наибольшим числом зависимостей -### 3.7. Executable Invariants (если config.invariant_tests = yes) +### 3.8. Executable Invariants (если config.invariant_tests = yes) -Для каждого ADR (из layer-1/adr/) создать задачу типа `invariant` — тест, проверяющий архитектурное правило. +Для каждого ADR (из `.agent/decisions/`) создать задачу типа `invariant` — тест, проверяющий архитектурное правило. **Правила превращения ADR в инварианты:** @@ -111,23 +127,25 @@ ## Выход -- `.agent/task-manifest.json` — по схеме `TEMPLATES/task-manifest.json` -- `.agent/task-manifest.md` — по шаблону `TEMPLATES/task-manifest.md` +- `.agent/tasks/manifest.json` — по шаблону `TEMPLATES/task-manifest.json` +- `.agent/tasks/manifest.md` — по шаблону `TEMPLATES/task-manifest.md` Обновить checkpoints.json: - `phases.decomposition = "completed"` - `tasks` = полный массив задач со статусом `pending` > **Примечание:** после HANDOFF завершённые задачи будут архивированы — -> полное описание уходит в `.agent/archive/tasks/`, в манифесте остаётся +> полное описание уходит в `.agent/archive/tasks/`, в manifest.json остаётся > one-liner с `"status": "archived"`. ## Критерии завершения фазы - [ ] Цель разбита на атомарные задачи - [ ] Для каждой задачи указаны acceptance criteria +- [ ] Для каждой задачи указан origin (источник) - [ ] Для каждой задачи указаны affected files - [ ] Зависимости между задачами корректны (нет циклов) +- [ ] Задачи сверены с roadmap приоритетами (если sources.md существует) - [ ] Invariant-задачи созданы для каждого ADR (если config требует) -- [ ] `.agent/task-manifest.json` и `.agent/task-manifest.md` созданы +- [ ] `.agent/tasks/manifest.json` и `.agent/tasks/manifest.md` созданы - [ ] checkpoints.json обновлён diff --git a/.agent/src/PROTOCOLS/03_DESIGN.md b/.agent/src/PROTOCOLS/03_DESIGN.md new file mode 100644 index 0000000..531f4fa --- /dev/null +++ b/.agent/src/PROTOCOLS/03_DESIGN.md @@ -0,0 +1,142 @@ +# Протокол 03: Архитектурное проектирование (DESIGN) + +## Цель + +Спроектировать архитектуру, модули, данные и интерфейсы для greenfield/scaffold-проекта. + +DESIGN выполняется **только** для `project_type = greenfield` или `scaffold`. Для existing-проектов пропускается. + +## Вход + +- `.agent/context/analysis-report.md` (project_type: greenfield или scaffold) +- `.agent/roadmap/sources.md` (опционально) +- `.agent/checkpoints.json` (фаза design: pending) +- `.agent/rules/project-rules.md` — прочитать первым + +## Правила + +1. **Реалистичность** — архитектура реализуема за 1 сессию (до 10 задач). +2. **Документируемость** — каждый модуль, модель и интерфейс описывается в `design-report.md`. +3. **Тестируемость** — каждый компонент проектируется с учётом тестирования. +4. **Итеративность** — первая версия минимально рабочая (MVP), расширения — отдельными задачами. + +## Шаги + +### 3.1. Прочитать правила проекта + +Прочитать `.agent/rules/project-rules.md`, применить. + +### 3.2. Технологический стек + +Если стек не указан в README — предложить обоснованный выбор. Если указан — зафиксировать. + +Для каждого компонента: +- Язык и версия +- Фреймворк / библиотека +- База данных (движок, схема) +- Инфраструктура (Docker, CI/CD, хостинг) + +### 3.3. High-level архитектура + +- **Паттерн** — монолит, модульный монолит, микросервисы, слоистая, луковая. +- **Компоненты** — что делает каждый модуль/сервис. +- **Схема взаимодействия** — текстовое описание потоков данных. + +``` +[Client] → HTTP → [API Gateway] → [Auth Service] + ↓ + [Core Service] → [Database] + ↓ + [External API] → [3rd Party] +``` + +### 3.4. Модули + +| Поле | Описание | +|---|---| +| Имя модуля | `app/services/cashflow.py` | +| Ответственность | Что делает | +| Ключевые классы/функции | Сигнатуры без реализации | +| Зависимости | Какие модули нужны | +| Контракт | Что экспортирует | + +### 3.5. Модели данных + +Описать сущности, поля, связи: + +```json +{ + "entity": "Transaction", + "fields": [ + {"name": "id", "type": "UUID", "pk": true}, + {"name": "amount", "type": "Decimal"}, + {"name": "date", "type": "datetime"}, + {"name": "category_id", "type": "UUID", "fk": "Category"} + ] +} +``` + +### 3.6. API интерфейсы + +| Метод | Путь | Описание | Request | Response | Статусы | +|---|---|---|---|---|---| +| GET | /transactions | Список | ?page, ?limit | [Transaction] | 200 | +| POST | /transactions | Создать | CreateTransactionDTO | Transaction | 201, 400 | + +Если GUI — ключевые страницы. Если CLI — команды. + +### 3.7. Обработка ошибок + +- Стратегия: исключения / Result / коды. +- Формат API-ошибок: `{ "error": "...", "code": "...", "details": {} }`. +- Логирование: уровни для разных событий. + +### 3.8. Стратегия тестирования + +- Какие тесты нужны (unit, integration, e2e). +- Как изолировать зависимости. +- Команда запуска тестов. + +### 3.9. Группировка в задачи + +Предварительно наметить задачи по модулям — вход для DECOMPOSITION: + +``` +T1: Инициализация проекта + зависимости +T2: Модель данных (сущности, миграции) +T3: Service (core logic) +T4: API endpoints +T5: Tests +``` + +### 3.10. Создать design-report + +Записать `.agent/context/design-report.md` по шаблону `TEMPLATES/design-report.md`. + +### 3.11. Дополнительно (по команде пользователя) + +Эти шаги **не выполняются автоматически** — только если пользователь явно попросил: + +- **ADR** — вызвать `COMMANDS/adr.md` для ключевых решений. +- **Alternative Architecture** — вызвать `COMMANDS/alt-arch.md` для сравнения. +- **Risk Register** — вызвать `COMMANDS/risk-register.md` для допущений. +- **Red Team** — вызвать `COMMANDS/red-team.md` для атаки на дизайн. + +## Выход + +- `.agent/context/design-report.md` +- Предварительная группировка задач (для DECOMPOSITION) +- Возможно: ADR, risk-register, alt-architecture, red-team-report (если вызывали команды) +- `checkpoints.json: phases.design = "completed"` + +## Критерии завершения + +- [ ] Стек определён +- [ ] High-level архитектура описана +- [ ] Модули и их ответственность описаны +- [ ] Модели данных спроектированы +- [ ] API/интерфейсы описаны (если применимо) +- [ ] Стратегия тестирования определена +- [ ] Задачи предварительно сгруппированы +- [ ] `design-report.md` создан +- [ ] `checkpoints.json` обновлён diff --git a/.agent/src/PROTOCOLS/04_DECOMPOSITION.md b/.agent/src/PROTOCOLS/04_DECOMPOSITION.md new file mode 100644 index 0000000..6b416a3 --- /dev/null +++ b/.agent/src/PROTOCOLS/04_DECOMPOSITION.md @@ -0,0 +1,117 @@ +# Протокол 04: Декомпозиция задач (DECOMPOSITION) + +## Цель + +Разбить цель пользователя (и архитектурный план, если есть) на атомарные, независимо выполнимые задачи. Записать в `manifest.json` + `manifest.md`. + +## Вход + +- `.agent/context/analysis-report.md` +- `.agent/context/design-report.md` (опционально — для greenfield) +- `.agent/roadmap/sources.md` (опционально) +- `.agent/decisions/*.md` (опционально) +- Цель пользователя (goal из `checkpoints.json`) +- `.agent/rules/project-rules.md` — прочитать первым +- `.agent/checkpoints.json` (фаза decomposition: pending) + +## Принципы + +1. **Атомарность** — одна задача = одна логическая единица, выполнимая и проверяемая за один подход. +2. **Независимость (макс.)** — минимизировать зависимости между задачами. +3. **Тестируемость** — каждая задача имеет измеримые acceptance criteria. +4. **Границы** — задача не выходит за пределы `BOUNDARIES.md`. +5. **Порядок** — задачи с зависимостями выполняются строго последовательно. + +## Шаги + +### 4.1. Прочитать правила проекта + +Прочитать `.agent/rules/project-rules.md`, применить. + +### 4.2. Размер задачи + +Задача должна укладываться в **1-2 часа работы агента**. Если крупнее — разбить. + +Признак слишком крупной задачи: +- Нельзя сформулировать acceptance criteria одной строкой. +- Затрагивает 5+ файлов. +- Содержит союзы «и», «а также», «после чего». + +### 4.3. Сверить с roadmap + +Если существует `.agent/roadmap/sources.md`: + +- Задачи из roadmap получают приоритет P0-P3 в соответствии с `sources.md`. +- Задачи без явного источника получают `origin: "decomposition"`. + +### 4.4. Структура задачи + +| Поле | Описание | Пример | +|---|---|---| +| `id` | Уникальный идентификатор | `T1`, `T2` | +| `title` | Что сделать | "Добавить модель User" | +| `description` | Как и зачем | "Создать SQLAlchemy модель..." | +| `type` | Тип | `feature`, `refactor`, `test`, `fix`, `config`, `design`, `docs`, `invariant` | +| `status` | Статус | `pending`, `in_progress`, `completed`, `failed`, `archived` | +| `origin` | Источник | `roadmap:file`, `adr:NNN`, `user:direct`, `agent:analysis`, `decomposition` | +| `files` | Файлы | `["app/models/user.py"]` | +| `depends_on` | Зависимости | `[]` или `["T0"]` | +| `acceptance_criteria` | 3-5 измеримых пунктов | `["Модель проходит миграцию"]` | +| `context` | Доп. информация | `"Смотри app/models/base.py"` | + +**Типы origin:** + +- `roadmap:{filename}` — из FUTURE/ или roadmap +- `adr:{NNN}` — из Architecture Decision Record +- `user:direct` — от пользователя +- `agent:analysis` — выявлено агентом +- `decomposition` — создано при декомпозиции +- `invariant:{adr_id}` — инвариант для ADR (создаётся командой `/invariant-tests`) +- `risk:{R-NNN}` — из Risk Register + +### 4.5. Зелёная декомпозиция (greenfield/scaffold) + +Если есть `design-report.md` — задачи на основе группировки из дизайна: + +1. **T1: init** — инициализация, зависимости, scaffold. +2. **T2..Tn: features** — модули по одному. +3. **Tn+1: tests** — тесты (можно в составе feature). +4. **Tn+2: polish** — документация, форматирование. + +### 4.6. Сортировка + +Задачи в манифесте в порядке выполнения: + +1. Без зависимостей. +2. Чьи зависимости уже выполнены. +3. С наибольшим числом зависимостей. + +### 4.7. Записать manifest + +Создать `.agent/tasks/manifest.json` по шаблону `TEMPLATES/task-manifest.json`. +Создать `.agent/tasks/manifest.md` по шаблону `TEMPLATES/task-manifest.md`. + +### 4.8. Обновить checkpoints + +```json +{ + "phases": { "decomposition": "completed" }, + "tasks": [...], + "last_updated": "<timestamp>" +} +``` + +## Выход + +- `.agent/tasks/manifest.json` +- `.agent/tasks/manifest.md` +- Обновлённый `checkpoints.json` + +## Критерии завершения + +- [ ] Цель разбита на атомарные задачи +- [ ] У каждой задачи — acceptance criteria, origin, files +- [ ] Зависимости корректны (нет циклов) +- [ ] Задачи сверены с roadmap (если `sources.md` существует) +- [ ] `manifest.json` и `manifest.md` созданы +- [ ] `checkpoints.json` обновлён diff --git a/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md b/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md index 0de6530..96d93cd 100644 --- a/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md +++ b/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md @@ -1,4 +1,8 @@ -# Протокол 04: Настройка окружения (SETUP) +# DEPRECATED — Протокол 04: Настройка окружения (SETUP) + +> **Устарел в MetaAgent v2.1.** Заменён на `PROTOCOLS/04_EXECUTION.md`. +> Оставлен для обратной совместимости (проекты, использующие v2.0). +> Новые проекты используют фазу EXECUTION, в которой настройка окружения — первый шаг перед выполнением задач. ## Цель @@ -6,9 +10,9 @@ ## Вход -- `.agent/analysis-report.md` -- `.agent/design-report.md` (опционально, для greenfield) -- `.agent/task-manifest.json` +- `.agent/context/analysis-report.md` +- `.agent/context/design-report.md` (опционально, для greenfield) +- `.agent/tasks/manifest.json` - `.agent/checkpoints.json` (фаза environment: pending) ## Поведение в зависимости от типа проекта @@ -44,7 +48,7 @@ ### 4A.4. Baseline-тесты - Запустить все тесты проекта -- Записать в `.agent/baseline-test-report.log`: +- Записать в `.agent/context/baseline-test-report.log`: - Команда запуска - Общее количество тестов - Пройдено / упало / пропущено @@ -97,7 +101,7 @@ class CashflowService: - Создать пустой тестовый файл для каждого модуля - Настроить тестовый раннер (pytest, jest и т.д.) -- Записать в `.agent/baseline-test-report.log`: "0 tests — greenfield, scaffold готов" +- Записать в `.agent/context/baseline-test-report.log`: "0 tests — greenfield, scaffold готов" ### 4B.5. Проверка сборки @@ -110,8 +114,8 @@ class CashflowService: ## Выход - Работоспособное окружение / инициализированный проект -- `.agent/baseline-test-report.log` — результат прогона тестов -- `.agent/setup-report.log` — лог установки зависимостей и сборки +- `.agent/context/baseline-test-report.log` — результат прогона тестов +- `.agent/context/setup-report.log` — лог установки зависимостей и сборки Обновить checkpoints.json: `phases.environment = "completed"`. @@ -120,7 +124,7 @@ class CashflowService: - [ ] Зависимости установлены / проект инициализирован - [ ] Проект собирается / импортируется без ошибок - [ ] Baseline-тесты запущены, результат записан -- [ ] `.agent/baseline-test-report.log` и `.agent/setup-report.log` созданы +- [ ] `.agent/context/baseline-test-report.log` и `.agent/context/setup-report.log` созданы - [ ] checkpoints.json обновлён Если проект не собирается — **фаза считается проваленной**, checkpoints.json отмечает `phases.environment = "failed"`, управление возвращается пользователю. diff --git a/.agent/src/PROTOCOLS/04_EXECUTION.md b/.agent/src/PROTOCOLS/04_EXECUTION.md new file mode 100644 index 0000000..3bdb19b --- /dev/null +++ b/.agent/src/PROTOCOLS/04_EXECUTION.md @@ -0,0 +1,138 @@ +# Протокол 04: Исполнение задач (EXECUTION) + +## Цель + +Выполнить задачи из manifest.json: реализовать код, написать тесты, закоммитить, создать request — артефакт результата. + +## Вход + +- `.agent/tasks/manifest.json` — манифест с задачами +- `.agent/context/analysis-report.md` — контекст проекта +- `.agent/context/design-report.md` — архитектурный план (опционально) +- `.agent/decisions/*.md` — ADR (опционально) +- `.agent/rules/project-rules.md` — правила проекта +- `.agent/checkpoints.json` (фаза execution: pending) + +## Шаги + +### 4.0. Setup окружения (первый запуск) + +Если это первый запуск EXECUTION в сессии: +- Установить зависимости (через штатный пакетный менеджер) +- Запустить сборку/базовые тесты для верификации окружения +- Записать baseline в `.agent/context/baseline-test-report.log` + +### 4.1. Выбор задачи + +Найти в `.agent/tasks/manifest.json` задачу, удовлетворяющую всем условиям: +- `status: "pending"` +- Все `depends_on` имеют статус `completed` или `archived` + +Если таких задач нет — EXECUTION завершён, перейти к ожиданию команды пользователя. + +### 4.2. Блокировка задачи + +Отметить задачу в манифесте: +```json +{ + "id": "T1", + "status": "in_progress" +} +``` + +### 4.3. Исполнение + +Реализовать задачу в соответствии с acceptance criteria: +- Следовать конвенциям проекта (выявленным в ANALYSIS) +- Соблюдать BOUNDARIES.md +- Если задача ссылается на ADR — следовать архитектурному решению +- Писать код + тесты + +### 4.4. Верификация + +- Запустить тесты (все или релевантные) +- Проверить LSP diagnostics на изменённых файлах +- Убедиться, что acceptance criteria выполнены + +### 4.5. Коммит + +Сделать git-коммит с результатами задачи. Сообщение коммита должно отражать суть выполненной задачи. + +### 4.6. Создание request + +Создать `.agent/requests/active/req-{task_id}.json`: + +```json +{ + "request_id": "req-T1", + "task_id": "T1", + "title": "GET /health endpoint", + "status": "ready_for_review", + "goal": "Добавить ручку GET /health с тестами", + "changes": { + "summary": "Создан health router, подключён в main.py, написаны тесты", + "commits": ["abc1234", "abc1235"], + "files_changed": [ + "app/routers/health.py", + "app/main.py", + "tests/test_health.py" + ] + }, + "verification": { + "tests_passed": "24/24", + "lsp_clean": true + }, + "fulfills_ac": [ + "Ручка возвращает 200 + {\"status\":\"ok\"}" + ] +} +``` + +Request фиксирует: +- **changes.summary** — краткая суть изменений (не полный diff, а именно суть) +- **changes.commits** — ссылки на коммиты (чтобы можно было проанализировать при ревью) +- **changes.files_changed** — какие файлы затронуты +- **verification** — результаты проверки +- **fulfills_ac** — какие acceptance criteria закрыты + +### 4.7. Завершение задачи + +В манифесте: +```json +{ + "id": "T1", + "status": "completed" +} +``` + +### 4.8. Цикл + +Перейти к шагу 4.1 — выбрать следующую задачу. +Если задач больше нет — сообщить пользователю и ожидать команду (METASTATE или новую задачу). + +## Request как единица результата + +Request — ключевой артефакт v2.1. Не просто «задача сделана», а документированный результат: +- Что сделано (суть, не diff) +- Как проверить (коммиты, тесты) +- Что закрыто (acceptance criteria) + +Request проходит ревью в фазе METASTATE: +- `ready_for_review` → после проверки → `approved` или `rejected` + +## Выход + +- Выполненные задачи в manifest.json (status: completed) +- `.agent/requests/active/req-{task_id}.json` для каждой выполненной задачи +- Обновлённый checkpoints.json (`phases.execution = "in_progress"` или `"completed"`) + +## Критерии завершения + +Фаза EXECUTION не имеет единого момента завершения — она циклична. Критерии для одной итерации: + +- [ ] Acceptance criteria задачи выполнены +- [ ] Тесты проходят +- [ ] LSP diagnostics чист +- [ ] Коммит создан +- [ ] Request создан в `.agent/requests/active/` +- [ ] Задача в manifest.json отмечена completed diff --git a/.agent/src/PROTOCOLS/05_EXECUTION.md b/.agent/src/PROTOCOLS/05_EXECUTION.md new file mode 100644 index 0000000..fa049ff --- /dev/null +++ b/.agent/src/PROTOCOLS/05_EXECUTION.md @@ -0,0 +1,136 @@ +# Протокол 05: Исполнение задач (EXECUTION) + +## Цель + +Выполнить задачи из `manifest.json`: реализовать код, написать тесты, закоммитить, создать request — артефакт результата. + +EXECUTION — **циклическая** фаза. Работает, пока есть задачи со статусом `pending` и выполненными `depends_on`. + +## Вход + +- `.agent/tasks/manifest.json` +- `.agent/context/analysis-report.md` +- `.agent/context/design-report.md` (опционально) +- `.agent/decisions/*.md` (опционально) +- `.agent/rules/project-rules.md` — прочитать первым +- `.agent/checkpoints.json` (фаза execution: pending) + +## Шаги (цикл) + +### 5.1. Прочитать правила проекта + +Прочитать `.agent/rules/project-rules.md`, применить. + +### 5.2. Setup окружения (первый запуск) + +Если это первый запуск EXECUTION в сессии: + +- Установить зависимости через штатный пакетный менеджер. +- Запустить сборку / базовые тесты. +- Записать baseline в `.agent/context/baseline-test-report.log`. + +### 5.3. Выбрать задачу + +Найти в `manifest.json` задачу, удовлетворяющую: + +- `status: "pending"` +- Все `depends_on` имеют `status: "completed"` или `"archived"`. + +Если таких нет — EXECUTION завершён, перейти к ожиданию команды пользователя. + +### 5.4. Заблокировать задачу + +В `manifest.json`: + +```json +{ "id": "T1", "status": "in_progress" } +``` + +### 5.5. Исполнить + +- Следовать конвенциям проекта (из ANALYSE). +- Соблюдать `BOUNDARIES.md`. +- Если задача ссылается на ADR — следовать архитектурному решению. +- Писать код + тесты. + +### 5.6. Верифицировать + +- Запустить тесты (все или релевантные). +- Проверить LSP diagnostics на изменённых файлах. +- Убедиться, что acceptance criteria выполнены. + +### 5.7. Закоммитить + +Сделать git-коммит. Сообщение — суть задачи. + +### 5.8. Создать request + +Создать `.agent/requests/active/req-{task_id}.json` по шаблону `TEMPLATES/request.json`: + +```json +{ + "request_id": "req-T1", + "task_id": "T1", + "title": "GET /health endpoint", + "status": "ready_for_review", + "goal": "Добавить ручку GET /health с тестами", + "changes": { + "summary": "Создан health router, подключён в main.py, написаны тесты", + "commits": ["abc1234"], + "files_changed": ["app/routers/health.py", "app/main.py", "tests/test_health.py"] + }, + "verification": { + "tests_passed": "24/24", + "lsp_clean": true + }, + "fulfills_ac": ["Ручка возвращает 200 + {\"status\":\"ok\"}"] +} +``` + +Request фиксирует: +- **summary** — суть изменений (не diff). +- **commits** — ссылки на коммиты. +- **files_changed** — какие файлы. +- **verification** — тесты + LSP. +- **fulfills_ac** — какие acceptance criteria закрыты. + +### 5.9. Завершить задачу + +```json +{ "id": "T1", "status": "completed" } +``` + +### 5.10. Цикл + +Перейти к шагу 5.3. Если задач больше нет — сообщить пользователю и ожидать команду (METASTATE, новая задача, или завершение). + +## Request как единица результата + +Не просто «задача сделана», а документированный результат. Request проходит ревью в фазе METASTATE: + +- `ready_for_review` → после проверки → `approved` или `rejected`. + +## Команды во время EXECUTION + +В любой момент цикла пользователь может вызвать: + +- **/adr** — зафиксировать архитектурное решение, появившееся в процессе. +- **/red-team** — попытаться сломать текущий подход. +- **/risk-register** — зафиксировать новый риск. + +Команды не прерывают EXECUTION, но могут добавить задачи в manifest. + +## Выход + +- Выполненные задачи в `manifest.json` (status: completed) +- `.agent/requests/active/req-{task_id}.json` для каждой выполненной задачи +- Обновлённый `checkpoints.json` + +## Критерии завершения (одна итерация) + +- [ ] Acceptance criteria выполнены +- [ ] Тесты проходят +- [ ] LSP diagnostics чист +- [ ] Коммит создан +- [ ] Request создан в `.agent/requests/active/` +- [ ] Задача в `manifest.json` отмечена completed diff --git a/.agent/src/PROTOCOLS/05_HANDOFF.md b/.agent/src/PROTOCOLS/05_HANDOFF.md index 0939ec2..e8bf33b 100644 --- a/.agent/src/PROTOCOLS/05_HANDOFF.md +++ b/.agent/src/PROTOCOLS/05_HANDOFF.md @@ -1,188 +1,123 @@ -# Протокол 05: Передача исполнительному агенту (HANDOFF) +# Протокол 07: Завершение сессии (HANDOFF) ## Цель -Подготовить и передать исполнительному агенту полный контекст для работы: задачи, окружение, правила. +Легковесное завершение сессии: валидация структуры `.agent/`, финализация чекпоинтов, формирование сводки. Архивация и обновление project-state выполняются фазой METASTATE. + +> **Важно:** если перед HANDOFF была выполнена фаза METASTATE (06) — архивация, project-state и handoff-summary уже готовы. +> HANDOFF в этом случае только валидирует и финализирует. ## Вход -- `.agent/analysis-report.md` -- `.agent/design-report.md` (опционально, для greenfield) -- `.agent/layer-1/adr/*.md` (опционально) -- `.agent/layer-1/risk-register.md` (опционально) -- `.agent/layer-1/red-team-report.md` (опционально) -- `.agent/task-manifest.json` -- `.agent/task-manifest.md` -- `.agent/baseline-test-report.log` - `.agent/checkpoints.json` (все предыдущие фазы: completed) +- `.agent/context/project-state.md` (опционально, создан в ANALYSIS, обновлён в METASTATE) +- `.agent/handoff-summary.md` (опционально, создан в METASTATE) +- `.agent/tasks/manifest.json` +- `.agent/roadmap/sources.md` (опционально) +- Все артефакты `.agent/` ## Шаги -### 5.1. Архивация завершённых артефактов +### 5.1. Проверка: была ли METASTATE? -Перед валидацией и передачей выполнить архивирование. +Если существует `.agent/handoff-summary.md` и `.agent/context/project-state.md`: +- METASTATE уже выполнен +- Перейти к шагу 5.3 (Валидация) -**Архивировать завершённые задачи:** +Если нет: +- METASTATE не выполнялся (например, сессия завершается до execution) +- Перейти к шагу 5.2 (Лёгкая архивация) -Для каждой задачи в `task-manifest.json` со статусом `completed`: -1. Создать `.agent/archive/tasks/<id>.json` — перенести полное описание задачи (все поля) -2. В `task-manifest.json` заменить задачу на one-liner: - ```json - { "id": "<id>", "title": "<title>", "status": "archived" } - ``` +### 5.2. Лёгкая архивация (если METASTATE не было) -**Архивировать чекпоинты:** +Если есть completed задачи в manifest.json: +- Архивировать их в `.agent/archive/tasks/{id}.json` +- Заменить в manifest.json на one-liner +- Создать `.agent/archive/index.json` -Если `checkpoints.json` уже существует — сохранить предыдущую версию в `.agent/archive/checkpoints/<last_updated>.json`. +Если нет completed задач — пропустить. -**Создать индекс архива:** +### 5.3. Валидация -```json -{ - "version": "1.1.0", - "archived_at": "<timestamp>", - "tasks": [ - { "id": "T1", "title": "...", "archived_at": "<timestamp>" } - ], - "checkpoints": [ - { "file": "checkpoints/2026-07-15T10-00-00.json", "archived_at": "<timestamp>" } - ] -} -``` +Проверить: -### 5.2. Валидация - -Перед передачей проверить: - -- [ ] Все фазы отмечены как `completed` в checkpoints.json -- [ ] `.agent/` содержит все обязательные файлы: +- [ ] Все фазы отмечены как `completed` или `skipped` в checkpoints.json +- [ ] `.agent/` содержит обязательные файлы: - `checkpoints.json` - - `analysis-report.md` - - `task-manifest.json` + `task-manifest.md` - - `baseline-test-report.log` - - `setup-report.log` + - `context/analysis-report.md` + - `context/project-state.md` + - `tasks/manifest.json` + `tasks/manifest.md` - `src/META_AGENT_GUIDE.md` - `src/BOUNDARIES.md` - `src/VERSION` - `src/PROTOCOLS/` - `src/TEMPLATES/` - `rules/project-rules.md` - - `archive/index.json` -- [ ] Для greenfield: `design-report.md` присутствует -- [ ] В task-manifest.json нет циклических зависимостей +- [ ] В `.agent/tasks/manifest.json` нет циклических зависимостей - [ ] Все acceptance criteria сформулированы измеримо -- [ ] Для каждой задачи указаны affected files -- [ ] В репозитории нет незакоммиченных изменений (кроме `.agent/`) -- [ ] `.agent/src/` содержит актуальные исходники MetaAgent (META_AGENT_GUIDE.md, PROTOCOLS/, TEMPLATES/, BOUNDARIES.md, VERSION) +- [ ] Для каждой задачи указаны affected files и origin +- [ ] `.agent/src/` содержит актуальные исходники - [ ] `AGENTS.md` присутствует в корне репозитория -- [ ] `.agent/rules/` содержит `project-rules.md` -**Дополнительные проверки (если config включает):** -- [ ] ADR присутствуют (если adr=yes) -- [ ] Risk Register заполнен (если risk_register=yes) -- [ ] Red Team Report есть (если red_team=yes) -- [ ] Invariant-задачи в манифесте (если invariant_tests=yes) +### 5.4. Создание session-summary.md -### 5.3. Layer-структура .agent/ +Создать `.agent/session-summary.md` — краткая сводка сессии: -Если `config.layer_structure = yes`, организовать артефакты по слоям: +```markdown +# Session Summary -``` -.agent/ - layer-0/ - checkpoints.json # всегда (ядро) - session-summary.md # краткая сводка сессии (создаётся здесь) - layer-1/ - adr/ # ADR (опционально) - risk-register.md # (опционально) - red-team-report.md # (опционально) - layer-2/ - analysis-report.md - design-report.md - design-report.md - layer-3/ - handoff-summary.md - task-manifest.json - task-manifest.md - baseline-test-report.log - setup-report.log +**Session:** <id> +**MetaAgent version:** 2.1.0 +**Date:** <timestamp> +**Goal:** <goal> + +## Phases Executed +- [x] INIT +- [x] ANALYSIS +- [x] ROADMAP +- [x] DESIGN +- [x] DECOMPOSITION +- [x] EXECUTION (N tasks) +- [x] METASTATE +- [x] HANDOFF + +## Results +- Tasks completed: N +- Requests approved: N +- Files changed: [list] + +## Next +Следующий агент: читай .agent/handoff-summary.md ``` -Если `layer_structure = no` — артефакты остаются плоскими в `.agent/`, как раньше. - -### 5.4. Создать handoff-summary.md - -Заполнить по шаблону `TEMPLATES/handoff-summary.md`: - -- **Session Info** — ID, цель, дата -- **Configuration** — какие функции были включены, глубина -- **Repo Summary** — краткая выжимка из analysis-report -- **Environment Status** — результат сборки и тестов -- **Design Summary** (если есть design-report) — ключевые архитектурные решения -- **ADR Summary** (если adr=yes) — какие решения задокументированы -- **Risk Register** (если risk_register=yes) — основные допущения -- **Task Overview** — количество задач, типы, список -- **Next Steps** — с какой задачи начинать исполнительному агенту -- **Project Rules** — ссылка на `.agent/rules/project-rules.md` (передаётся exec-агенту) -- **Archive** — ссылка на `.agent/archive/index.json` (история завершённых задач) -- **Caveats** — известные проблемы, ограничения, неясные моменты -- **Checkpoints** — актуальное состояние чекпоинтов - -### 5.5. Финализировать checkpoints +### 5.5. Финализация checkpoints - Отметить `phases.handoff = "completed"` - Записать финальный `last_updated` ### 5.6. Сигнал -Сообщить пользователю/оркестратору: - ``` HANDOFF COMPLETE Session: <session_id> Target: <target_repo> Type: <existing | greenfield | scaffold> -Config: depth=<N>, adr=<yes|no>, red_team=<yes|no>, ... -Tasks: <count> tasks ready +Tasks: <N> total, <M> completed, <K> pending -Исполнительный агент может начинать с задачи <T1>. -Контекст: .agent/handoff-summary.md -Манифест: .agent/task-manifest.json +Следующий агент начинает с .agent/handoff-summary.md ``` -## Что получает исполнительный агент - -1. **Целевой репозиторий** — полностью настроенный, с установленными зависимостями -2. **`.agent/`** — директория со всеми артефактами (layer-структура или плоская) -3. **`task-manifest.json`** — машиночитаемый список задач -4. **`task-manifest.md`** — человекочитаемый список задач -5. **`handoff-summary.md`** — итоговая сводка -6. **`checkpoints.json`** — актуальное состояние (исполнительный агент будет его обновлять) -7. **`layer-1/adr/*.md`** (опционально) — ключевые решения -8. **`layer-1/risk-register.md`** (опционально) — допущения -9. **`layer-2/analysis-report.md`** — полный анализ репозитория (справочно) -10. **`layer-2/design-report.md`** (только для greenfield) — архитектурный план -11. **`layer-3/baseline-test-report.log`** — baseline тестов (чтобы не сломать существующее) -12. **`.agent/src/`** — полные исходники MetaAgent (справочно, всегда присутствуют) -13. **`.agent/rules/`** — пользовательские правила проекта -14. **`AGENTS.md`** — инструкция для AI-агента в корне проекта (всегда присутствует) -15. **`.agent/archive/`** — архив завершённых задач, чекпоинтов и устаревших артефактов - ## Выход -- `.agent/layer-0/session-summary.md` (если layer_structure=yes) -- `.agent/layer-3/handoff-summary.md` -- `.agent/layer-0/checkpoints.json` (финальный) -- `.agent/archive/index.json` (создаётся при архивации) +- `.agent/session-summary.md` +- `.agent/checkpoints.json` (финальный) +- Если METASTATE не было: `.agent/archive/index.json` ## Критерии завершения -- [ ] Все артефакты на месте (с учётом layer-структуры) -- [ ] `.agent/src/` содержит актуальные исходники MetaAgent -- [ ] `.agent/rules/` содержит `project-rules.md` -- [ ] `AGENTS.md` присутствует в корне репозитория -- [ ] `.agent/archive/index.json` создан, завершённые задачи архивированы -- [ ] handoff-summary.md заполнен (включая config, design summary, ADR summary, archive) +- [ ] Все артефакты на месте (согласно структуре .agent/) +- [ ] Если METASTATE не было — completed задачи архивированы +- [ ] session-summary.md создан - [ ] checkpoints.json финализирован -- [ ] Сигнал отправлен пользователю/оркестратору +- [ ] Сигнал отправлен пользователю diff --git a/.agent/src/PROTOCOLS/06_METASTATE.md b/.agent/src/PROTOCOLS/06_METASTATE.md new file mode 100644 index 0000000..fca75da --- /dev/null +++ b/.agent/src/PROTOCOLS/06_METASTATE.md @@ -0,0 +1,149 @@ +# Протокол 06: Обновление метасостояния (METASTATE) + +## Цель + +По команде пользователя «обнови метасостояние проекта» — провести ревью накопленных requests, синхронизировать манифест, обновить слепок проекта и подготовить `.agent/` как полную картину для следующей сессии. + +## Вход + +- `.agent/requests/active/` — все request-ы со статусом `ready_for_review` +- `.agent/tasks/manifest.json` — текущее состояние задач +- `.agent/context/project-state.md` — текущий слепок проекта (создан в ANALYSIS) +- `.agent/roadmap/sources.md` — дорожная карта (создана в ROADMAP) +- `.agent/checkpoints.json` + +## Шаги + +### 6.1. Сбор requests + +Прочитать все файлы из `.agent/requests/active/` со статусом `ready_for_review`. +Каждый request — это выполненная задача, ожидающая подтверждения. + +### 6.2. Ревью каждого request + +Для каждого request: + +1. **Верифицировать** — проверить, что verification корректен: + - Тесты действительно проходят (перезапустить, если нужно) + - LSP diagnostics чист + - Acceptance criteria выполнены + - При необходимости — проверить коммиты (git show) + +2. **Принять или отклонить:** + - ✅ **approved** — всё ОК: + - Переместить request: `.agent/requests/active/` → `.agent/requests/archive/` + - Убедиться, что задача в manifest.json имеет `status: "completed"` + - ❌ **rejected** — есть проблемы: + - Оставить request в active/ с комментарием о причинах отказа + - В manifest.json: `status: "reopened"`, снять `claimed_by` + - Добавить `rejection_reason` в request + +### 6.3. Архивация завершённых задач + +Для каждой задачи в manifest.json со статусом `completed`: +1. Создать `.agent/archive/tasks/{id}.json` — полное описание задачи (все поля) +2. В manifest.json заменить на one-liner: + ```json + { "id": "T1", "title": "GET /health endpoint", "status": "archived", "origin": "user:direct" } + ``` + +### 6.4. Обновление project-state.md + +Переписать `.agent/context/project-state.md` с учётом выполненных задач: +- Обновить список модулей (какие добавлены/изменены) +- Обновить архитектурную схему (кратко) +- Обновить статус тестов +- Добавить новые ADR, если появились +- Убрать закрытые concerns + +Цель: следующий агент читает project-state.md и понимает проект, не открывая исходники. + +### 6.5. Обновление roadmap + +В `.agent/roadmap/sources.md`: +- Отметить выполненные пункты +- Пересчитать приоритеты +- Если появились новые источники — добавить + +### 6.6. Индекс архива + +Создать/обновить `.agent/archive/index.json`: +```json +{ + "version": "2.1.0", + "archived_at": "<timestamp>", + "tasks": [ + { "id": "T1", "title": "GET /health", "archived_at": "<timestamp>" } + ], + "requests": [ + { "id": "req-T1", "task_id": "T1", "archived_at": "<timestamp>" } + ], + "checkpoints": [ + { "file": "checkpoints/<timestamp>.json", "archived_at": "<timestamp>" } + ] +} +``` + +### 6.7. Создание handoff-summary.md + +Создать `.agent/handoff-summary.md` — полную сводку для следующего агента: + +```markdown +## Session Summary +**Session:** <id> +**Goal:** <goal> +**Completed:** N tasks +**Pending:** M tasks +**Approved requests:** req-T1, req-T2 + +## Project State +(краткая выжимка из project-state.md) + +## Next Steps +(с чего начать следующую сессию) + +## Key Artifacts +- Project state: `.agent/context/project-state.md` +- Tasks: `.agent/tasks/manifest.json` +- Roadmap: `.agent/roadmap/sources.md` +- Pending reviews: `.agent/requests/active/` +- Archive: `.agent/archive/index.json` +``` + +### 6.8. Финализация чекпоинта + +Обновить checkpoints.json: +- `phases.metastate = "completed"` +- Актуальный список задач +- `last_updated` + +## Выход + +- Подтверждённые requests: `.agent/requests/archive/` +- Архив задач: `.agent/archive/tasks/{id}.json` +- Обновлённый project-state.md +- Обновлённый roadmap/sources.md +- `.agent/handoff-summary.md` — полная сводка +- `.agent/archive/index.json` +- Финальный checkpoints.json + +## Критерии завершения + +- [ ] Все ready_for_review requests проверены (approved/rejected) +- [ ] Approved requests перемещены в archive +- [ ] Completed задачи архивированы (one-liner в manifest) +- [ ] project-state.md отражает актуальное состояние проекта +- [ ] roadmap/sources.md обновлён +- [ ] archive/index.json создан +- [ ] handoff-summary.md готов +- [ ] checkpoints.json финализирован + +## Когда запускать + +По команде пользователя: +- «обнови метасостояние» +- «update metastate» +- «подведи итог» +- «заверши сессию» + +Может запускаться многократно в течение жизни проекта — после каждой группы выполненных задач. diff --git a/.agent/src/PROTOCOLS/07_HANDOFF.md b/.agent/src/PROTOCOLS/07_HANDOFF.md new file mode 100644 index 0000000..7c7bdb2 --- /dev/null +++ b/.agent/src/PROTOCOLS/07_HANDOFF.md @@ -0,0 +1,113 @@ +# Протокол 07: Завершение сессии (HANDOFF) + +## Цель + +Финализация сессии: валидация структуры `.agent/`, финальный `session-summary.md`, отметка `phases.handoff = "completed"`. + +> Если перед HANDOFF был METASTATE — архивация, project-state, handoff-summary уже готовы. HANDOFF только валидирует и финализирует. + +## Вход + +- `.agent/checkpoints.json` (все фазы кроме handoff: completed или skipped) +- Все артефакты `.agent/` + +## Шаги + +### 7.1. Проверить: был ли METASTATE? + +Если существуют `.agent/handoff-summary.md` и `.agent/context/project-state.md` (обновлён) — METASTATE выполнен. Перейти к шагу 7.3. + +Если нет — выполнить лёгкую архивацию (шаг 7.2). + +### 7.2. Лёгкая архивация (если METASTATE не было) + +Если есть `completed` задачи в `manifest.json`: + +- Архивировать в `.agent/archive/tasks/{id}.json`. +- Заменить в `manifest.json` на one-liner. +- Создать `.agent/archive/index.json`. + +### 7.3. Валидация + +Проверить: + +- [ ] Все фазы в `checkpoints.json` отмечены `completed` или `skipped`. +- [ ] `.agent/` содержит обязательные файлы: + - `checkpoints.json` + - `context/analysis-report.md` + - `context/project-state.md` + - `tasks/manifest.json` + `manifest.md` + - `rules/project-rules.md` + - `src/GUIDE.md` + - `src/BOUNDARIES.md` + - `src/VERSION` + - `src/PROTOCOLS/` + - `src/COMMANDS/` + - `src/TEMPLATES/` +- [ ] В `manifest.json` нет циклических зависимостей. +- [ ] У каждой задачи — measurable acceptance criteria и origin. +- [ ] `AGENTS.md` присутствует в корне репозитория. + +### 7.4. Создать session-summary + +Создать `.agent/session-summary.md`: + +```markdown +# Session Summary + +**Session:** <id> +**MetaAgent version:** 3.0.0 +**Date:** <timestamp> +**Goal:** <goal> + +## Phases Executed +- [x] INIT +- [x] ANALYSE +- [x] ROADMAP +- [x] DESIGN (или skipped) +- [x] DECOMPOSITION +- [x] EXECUTION (N tasks) +- [x] METASTATE (или skipped) +- [x] HANDOFF + +## Results +- Tasks completed: N +- Requests approved: N +- Files changed: [list] + +## Next +Следующий агент: читай `.agent/handoff-summary.md`. +``` + +### 7.5. Финализировать checkpoints + +```json +{ "phases": { "handoff": "completed" }, "last_updated": "<timestamp>" } +``` + +### 7.6. Сигнал + +``` +HANDOFF COMPLETE + +Session: <session_id> +Target: <target_repo> +Type: <existing | greenfield | scaffold> +Tasks: <N> total, <M> completed, <K> pending + +Следующий агент начинает с .agent/handoff-summary.md +``` + +## Выход + +- `.agent/session-summary.md` +- Финальный `.agent/checkpoints.json` +- (если METASTATE не было) `.agent/archive/index.json` + +## Критерии завершения + +- [ ] Все артефакты на месте +- [ ] (если METASTATE не было) `completed` задачи архивированы +- [ ] `session-summary.md` создан +- [ ] `checkpoints.json` финализирован +- [ ] Сигнал отправлен пользователю diff --git a/.agent/src/TEMPLATES/handoff-summary.md b/.agent/src/TEMPLATES/handoff-summary.md index 5de97f4..165eeee 100644 --- a/.agent/src/TEMPLATES/handoff-summary.md +++ b/.agent/src/TEMPLATES/handoff-summary.md @@ -17,7 +17,7 @@ ## Project Type - **Type:** {{ project_type }} -- **Design report:** {% if project_type == "greenfield" or project_type == "scaffold" %}`.agent/design-report.md`{% else %}—{% endif %} +- **Design report:** {% if project_type == "greenfield" or project_type == "scaffold" %}`.agent/context/design-report.md`{% else %}—{% endif %} ## ADR Summary (если применимо) @@ -39,7 +39,7 @@ - **Build:** {{ build_status }} - **Tests:** {{ tests_passed }}/{{ tests_total }} passed -- **Baseline log:** `.agent/baseline-test-report.log` +- **Baseline log:** `.agent/context/baseline-test-report.log` - **Dependencies:** {{ deps_status }} ## Task Overview diff --git a/.agent/src/TEMPLATES/metaagent-request.md b/.agent/src/TEMPLATES/metaagent-request.md index 836560f..e953f7a 100644 --- a/.agent/src/TEMPLATES/metaagent-request.md +++ b/.agent/src/TEMPLATES/metaagent-request.md @@ -14,7 +14,7 @@ | RISK_REGISTER | ✗ | — | | DECOMPOSITION | ✓ | invariant_tests=yes | | SETUP | ✓ | — | -| HANDOFF | ✓ | layer_structure=yes | +| HANDOFF | ✓ | — | ## Глубина проработки diff --git a/.agent/src/TEMPLATES/project-state.md b/.agent/src/TEMPLATES/project-state.md new file mode 100644 index 0000000..a14595e --- /dev/null +++ b/.agent/src/TEMPLATES/project-state.md @@ -0,0 +1,43 @@ +# Project State +# Auto-generated — updated by ANALYSE (initial) and METASTATE (on updates) + +**Last updated:** {{ timestamp }} +**Session:** {{ session_id }} + +## Project Type + +{{ project_type }} + +## Tech Stack + +| Category | Technology | +|----------|-----------| +| Language | {{ language }} | +| Framework | {{ framework }} | +| Database | {{ database }} | +| Test runner | {{ test_runner }} | +| Package manager | {{ package_manager }} | + +## Current Architecture + +{{ architecture_description }} + +## Key Modules + +| Module | Status | Description | +|--------|--------|-------------| +| {{ module_name }} | {{ existing / stub / new }} | {{ module_description }} | + +## Decisions in Effect + +| ADR | Decision | Status | +|-----|----------|--------| +| {{ adr_id }} | {{ decision_summary }} | {{ active / superseded }} | + +## Testing Status + +{{ testing_summary }} + +## Open Concerns + +- {{ concern_1 }} diff --git a/.agent/src/TEMPLATES/request.json b/.agent/src/TEMPLATES/request.json new file mode 100644 index 0000000..286922d --- /dev/null +++ b/.agent/src/TEMPLATES/request.json @@ -0,0 +1,29 @@ +{ + "$schema": ".agent/src/TEMPLATES/schemas/request-schema.json", + "template_version": "1.0", + "request_id": "req-{{ task_id }}", + "task_id": "{{ task_id }}", + "title": "{{ task_title }}", + "status": "ready_for_review", + "created_at": "{{ timestamp }}", + "goal": "{{ task_goal }}", + + "changes": { + "summary": "{{ changes_summary }}", + "commits": [ + "{{ commit_hash }}" + ], + "files_changed": [ + "path/to/file.py" + ] + }, + + "verification": { + "tests_passed": "{{ test_results }}", + "lsp_clean": true + }, + + "fulfills_ac": [ + "{{ acceptance_criterion }}" + ] +} diff --git a/.agent/src/TEMPLATES/roadmap-sources.md b/.agent/src/TEMPLATES/roadmap-sources.md new file mode 100644 index 0000000..76ef0d7 --- /dev/null +++ b/.agent/src/TEMPLATES/roadmap-sources.md @@ -0,0 +1,42 @@ +# Roadmap Sources +# Auto-generated — created by ROADMAP phase + +**Created:** {{ timestamp }} +**Session:** {{ session_id }} + +## Priority Legend + +- **P0** — Critical, do next +- **P1** — Important, do soon +- **P2** — Nice to have +- **P3** — Future / deferred + +## Sources + +### FUTURE Plans + +| Plan | Priority | Status | Origin File | +|------|----------|--------|-------------| +| {{ plan_title }} | {{ P0-P3 }} | {{ active / archived }} | FUTURE/{{ filename }}.md | + +### ADR-Derived Tasks + +| Source ADR | Task | Priority | +|------------|------|----------| +| {{ adr_id }} | {{ task_description }} | {{ P0-P3 }} | + +### User Requests + +| Request | Priority | Source | +|---------|----------|--------| +| {{ request }} | {{ P0-P3 }} | {{ direct / issue / feedback }} | + +### Agent-Identified Improvements + +| Observation | Suggested Task | Priority | +|-------------|----------------|----------| +| {{ observation }} | {{ task }} | {{ P0-P3 }} | + +## Consolidated Priority Queue + +1. **{{ task_title }}** ({{ origin }}) — {{ priority }} diff --git a/.agent/src/TEMPLATES/schemas/checkpoints-schema.json b/.agent/src/TEMPLATES/schemas/checkpoints-schema.json new file mode 100644 index 0000000..ec5473c --- /dev/null +++ b/.agent/src/TEMPLATES/schemas/checkpoints-schema.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "metaagent/checkpoints/2.0.0", + "title": "MetaAgent Checkpoints", + "description": "Schema for .agent/checkpoints.json — session state", + "type": "object", + "properties": { + "metaagent_version": { + "type": "string", + "description": "MetaAgent version that created this checkpoint", + "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" + }, + "session_id": { + "type": "string", + "description": "Unique session identifier" + }, + "target_repo": { + "type": "string", + "description": "Path to the target repository" + }, + "goal": { + "type": "string", + "description": "Session goal" + }, + "project_type": { + "type": "string", + "enum": ["pending", "existing", "greenfield", "scaffold"], + "description": "Type of the target project" + }, + "config": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "description": "Depth of the session (1-10)" + }, + "design": { + "type": "object", + "properties": { + "adr": { "type": "boolean" }, + "alternative_arch": { "type": "boolean" } + }, + "additionalProperties": false + }, + "red_team": { "type": "boolean" }, + "risk_register": { "type": "boolean" }, + "decomposition": { + "type": "object", + "properties": { + "invariant_tests": { "type": "boolean" } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }, + "phases": { + "type": "object", + "properties": { + "analysis": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "design": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "red_team": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "decomposition": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "environment": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] }, + "handoff": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "skipped"] } + }, + "additionalProperties": false + }, + "tasks": { + "type": "array", + "description": "List of tasks (one-liners after archiving)", + "items": { + "type": "object", + "properties": { + "id": { "type": "string" }, + "title": { "type": "string" }, + "status": { "type": "string", "enum": ["pending", "in_progress", "completed", "failed", "archived"] } + }, + "required": ["id", "title", "status"], + "additionalProperties": false + } + }, + "last_updated": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of last update" + } + }, + "required": ["metaagent_version", "session_id", "goal", "config", "phases", "last_updated"], + "additionalProperties": false +} diff --git a/.agent/src/TEMPLATES/schemas/decisions-index-schema.json b/.agent/src/TEMPLATES/schemas/decisions-index-schema.json new file mode 100644 index 0000000..8b3ca3e --- /dev/null +++ b/.agent/src/TEMPLATES/schemas/decisions-index-schema.json @@ -0,0 +1,60 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "metaagent/decisions-index/2.0.0", + "title": "MetaAgent Decisions Index", + "description": "Schema for .agent/decisions/index.json — machine-readable index of ADRs", + "type": "object", + "properties": { + "version": { + "type": "string", + "description": "Schema version", + "enum": ["2.0"] + }, + "decisions": { + "type": "array", + "description": "List of architecture decision records", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[0-9]{3,}$", + "description": "ADR number (001, 002, ...)" + }, + "title": { + "type": "string", + "description": "Short title of the decision" + }, + "status": { + "type": "string", + "enum": ["proposed", "accepted", "deprecated", "superseded"], + "description": "ADR status" + }, + "file": { + "type": "string", + "description": "Filename in .agent/decisions/ (e.g. 001-stack.md)" + }, + "date": { + "type": "string", + "format": "date", + "description": "Decision date (ISO 8601)" + } + }, + "required": ["id", "title", "file"], + "additionalProperties": false + } + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of index creation" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of last update" + } + }, + "required": ["version", "decisions"], + "additionalProperties": false +} diff --git a/.agent/src/TEMPLATES/schemas/task-manifest-schema.json b/.agent/src/TEMPLATES/schemas/task-manifest-schema.json new file mode 100644 index 0000000..b934b0f --- /dev/null +++ b/.agent/src/TEMPLATES/schemas/task-manifest-schema.json @@ -0,0 +1,91 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "metaagent/task-manifest/2.0.0", + "title": "MetaAgent Task Manifest", + "description": "Schema for .agent/tasks/manifest.json — the global task manifest", + "type": "object", + "properties": { + "version": { + "type": "string", + "description": "Schema version", + "enum": ["2.0"] + }, + "session_id": { + "type": "string", + "description": "Session ID that created this manifest" + }, + "goal": { + "type": "string", + "description": "Overall goal of the session" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of creation" + }, + "tasks": { + "type": "array", + "description": "List of tasks", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^T[0-9]+$", + "description": "Unique task identifier (T1, T2, ...)" + }, + "title": { + "type": "string", + "description": "Task title" + }, + "description": { + "type": "string", + "description": "Detailed description" + }, + "type": { + "type": "string", + "enum": ["feature", "refactor", "test", "fix", "config", "design", "docs", "invariant"], + "description": "Task type" + }, + "files": { + "type": "array", + "items": { "type": "string" }, + "description": "Files affected by this task" + }, + "depends_on": { + "type": "array", + "items": { "type": "string" }, + "description": "Task IDs this task depends on" + }, + "acceptance_criteria": { + "type": "array", + "items": { "type": "string" }, + "description": "Measurable criteria for completion" + }, + "context": { + "type": "string", + "description": "Additional context or references" + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "failed", "archived"], + "description": "Current task status" + }, + "claimed_by": { + "type": "string", + "description": "Worker ID if claimed" + }, + "claimed_at": { + "type": "string", + "format": "date-time", + "description": "When the task was claimed" + } + }, + "required": ["id", "title", "type", "status"], + "additionalProperties": false + } + } + }, + "required": ["version", "tasks"], + "additionalProperties": false +} diff --git a/.agent/src/TEMPLATES/session-summary.md b/.agent/src/TEMPLATES/session-summary.md index e4e175b..f12f894 100644 --- a/.agent/src/TEMPLATES/session-summary.md +++ b/.agent/src/TEMPLATES/session-summary.md @@ -14,7 +14,6 @@ | Red Team | {{ red_team_enabled }} | | Risk Register | {{ risk_register_enabled }} | | Invariant Tests | {{ invariant_tests_enabled }} | -| Layer Structure | {{ layer_structure_enabled }} | ## Phase Status @@ -29,7 +28,7 @@ ## Quick Links -- Task Manifest: `.agent/task-manifest.json` +- Task Manifest: `.agent/tasks/manifest.json` - Handoff Summary: `.agent/handoff-summary.md` -- Design Report: `.agent/analysis-report.md` -- ADR: `.agent/layer-1/adr/` (если есть) +- Design Report: `.agent/context/design-report.md` +- ADR: `.agent/decisions/` (если есть) diff --git a/.agent/src/TEMPLATES/task-manifest.json b/.agent/src/TEMPLATES/task-manifest.json index 8dbb6ca..9b0debf 100644 --- a/.agent/src/TEMPLATES/task-manifest.json +++ b/.agent/src/TEMPLATES/task-manifest.json @@ -1,5 +1,5 @@ { - "$schema": "metaagent-task-manifest", + "$schema": ".agent/src/TEMPLATES/schemas/task-manifest-schema.json", "version": "1.0", "session_id": "{{ session_id }}", "goal": "{{ goal }}", diff --git a/.agent/src/VERSION b/.agent/src/VERSION index 9084fa2..7ec1d6d 100644 --- a/.agent/src/VERSION +++ b/.agent/src/VERSION @@ -1 +1 @@ -1.1.0 +2.1.0 diff --git a/.agent/src/WORKFLOW.md b/.agent/src/WORKFLOW.md index c315f12..0415204 100644 --- a/.agent/src/WORKFLOW.md +++ b/.agent/src/WORKFLOW.md @@ -28,8 +28,7 @@ "design": { "adr": false, "alternative_arch": false }, "red_team": false, "risk_register": false, - "decomposition": { "invariant_tests": false }, - "handoff": { "layer_structure": false } + "decomposition": { "invariant_tests": false } }, "phases": { "analysis": "pending", @@ -50,7 +49,7 @@ Мета-агент выполняет `PROTOCOLS/01_ANALYSIS.md`. Определяет тип проекта: `existing`. -Результат `.agent/analysis-report.md`: +Результат `.agent/context/analysis-report.md`: ```markdown ## 2. Стек технологий @@ -91,7 +90,7 @@ | T2 | Подключить router в main.py | config | T1 | Ручка доступна по /health | | T3 | Написать тесты для /health | test | T2 | Тесты проверяют 200 и структуру ответа | -Создан `.agent/task-manifest.json` и `.agent/task-manifest.md`. +Создан `.agent/tasks/manifest.json` и `.agent/tasks/manifest.md`. Чекпоинт обновлён: `decomposition = "completed"`. Tasks: T1-T3 со статусом `pending`. @@ -103,7 +102,7 @@ - `pip install -r requirements.txt` — OK - Запуск pytest — OK, 12 passed (базовый тест) -- Результат в `.agent/baseline-test-report.log` +- Результат в `.agent/context/baseline-test-report.log` Чекпоинт обновлён: `environment = "completed"`. @@ -138,8 +137,7 @@ "design": { "adr": false, "alternative_arch": false }, "red_team": false, "risk_register": false, - "decomposition": { "invariant_tests": false }, - "handoff": { "layer_structure": false } + "decomposition": { "invariant_tests": false } }, "phases": { "analysis": "completed", @@ -199,8 +197,7 @@ Tasks: 3 tasks ready "design": { "adr": true, "alternative_arch": true }, "red_team": false, "risk_register": true, - "decomposition": { "invariant_tests": true }, - "handoff": { "layer_structure": true } + "decomposition": { "invariant_tests": true } }, "phases": { "analysis": "pending", @@ -243,7 +240,7 @@ Tasks: 3 tasks ready Мета-агент выполняет `PROTOCOLS/02_DESIGN.md`. -Результат `.agent/design-report.md`: +Результат `.agent/context/design-report.md`: ```markdown ## 1. Технологический стек @@ -313,7 +310,7 @@ T6: tests — тесты - Установка fastapi, uvicorn, sqlalchemy, matplotlib, pytest - Создание scaffold-структуры: `app/models/`, `app/services/`, `app/schemas/`, `tests/` - Пустые заглушки модулей -- `.agent/baseline-test-report.log`: "0 tests — greenfield, scaffold готов" +- `.agent/context/baseline-test-report.log`: "0 tests — greenfield, scaffold готов" --- @@ -328,15 +325,15 @@ Config: depth=7, adr=yes, risk_register=yes, invariant_tests=yes Tasks: 6 tasks ready Исполнительный агент может начинать с задачи T1 (init). -Архитектурный план: .agent/design-report.md -ADR: .agent/layer-1/adr/ +Архитектурный план: .agent/context/design-report.md +ADR: .agent/decisions/ ``` --- ## После HANDOFF: работа исполнительного агента -Исполнительный агент читает `.agent/handoff-summary.md`, `.agent/task-manifest.json`, выполняет задачи по порядку, обновляя checkpoints.json после каждой. +Исполнительный агент читает `.agent/handoff-summary.md`, `.agent/tasks/manifest.json`, выполняет задачи по порядку, обновляя checkpoints.json после каждой. После завершения всех задач: @@ -354,3 +351,194 @@ T6: Тесты ✓ Все тесты проходят: 24/24 passed. ``` + +--- + +## Сценарий C: v2.1 — Координирующий агент + requests + METASTATE + +**Цель:** Рефакторинг модуля авторизации: вынести логику из монолитного файла в отдельные модули. + +**Целевой репозиторий:** `github.com/example/fastapi-app` + +**Пользователь:** "Вынеси авторизацию в отдельные модули: auth/router.py, auth/schemas.py, auth/deps.py" + +**Версия MetaAgent: 2.1.0** + +--- + +### PROJECT LOOP + +#### Фаза INIT + +Агент создаёт `.agent/`, инициализирует чекпоинт: + +```json +{ + "metaagent_version": "2.1.0", + "session_id": "ses_v21_001", + "goal": "Рефакторинг авторизации: вынести в модули auth/", + "project_type": "existing", + "phases": { + "analysis": "pending", + "roadmap": "pending", + "design": "skipped", + "decomposition": "pending", + "execution": "pending", + "metastate": "pending", + "handoff": "pending" + } +} +``` + +#### Фаза ANALYSIS + +Агент сканирует проект: +- Стек: Python, FastAPI, SQLAlchemy +- auth/login.py — 450 строк, монолит (цель рефакторинга) +- Создаёт `.agent/context/analysis-report.md` +- Создаёт `.agent/context/project-state.md` — начальный слепок + +#### Фаза ROADMAP + +Сканирование FUTURE/ — пусто. ADR — нет. Единственный источник — пользовательский запрос. + +Создаётся `.agent/roadmap/sources.md`: +```markdown +## Sources +### User Requests +| Вынести авторизацию | P0 | user:direct | +### Consolidated Priority Queue +1. Вынести auth/ (user:direct) — P0 +``` + +#### Фаза DECOMPOSITION + +Задачи с origin: +```json +{ + "tasks": [ + { + "id": "T1", + "title": "Создать auth/router.py", + "origin": "user:direct", + "status": "pending", + "files": ["app/auth/router.py"] + }, + { + "id": "T2", + "title": "Создать auth/schemas.py", + "origin": "user:direct", + "status": "pending", + "files": ["app/auth/schemas.py"], + "depends_on": ["T1"] + }, + { + "id": "T3", + "title": "Создать auth/deps.py", + "origin": "user:direct", + "status": "pending", + "files": ["app/auth/deps.py"], + "depends_on": ["T1"] + } + ] +} +``` + +--- + +### WORK LOOP (первая итерация) + +#### Фаза EXECUTION — задача T1 + +1. Берёт T1 (`pending`, нет зависимостей) +2. Отмечает `in_progress` +3. Создаёт `app/auth/router.py` — переносит логику роутов из `auth/login.py` +4. Пишет тесты +5. Тесты проходят: 48/48 +6. Коммит: `abc1234 — feat: extract auth router` +7. Создаёт request: + +```json +{ + "request_id": "req-T1", + "task_id": "T1", + "title": "Создать auth/router.py", + "status": "ready_for_review", + "changes": { + "summary": "Вынесены роуты авторизации из auth/login.py в auth/router.py. Добавлены тесты.", + "commits": ["abc1234"], + "files_changed": ["app/auth/router.py", "app/auth/__init__.py", "tests/test_auth_router.py"] + }, + "verification": { "tests_passed": "48/48", "lsp_clean": true }, + "fulfills_ac": ["Роуты авторизации доступны через app/auth/router.py", "Старые тесты проходят"] +} +``` + +8. T1 → completed + +#### Фаза EXECUTION — задача T2 (аналогично) + +Создаёт `auth/schemas.py`, request `req-T2`. + +#### Фаза EXECUTION — задача T3 (аналогично) + +Создаёт `auth/deps.py`, request `req-T3`. + +Задачи закончились. Агент ждёт команду. + +--- + +### METASTATE (по команде пользователя) + +**Пользователь:** "обнови метасостояние" + +1. **Ревью requests:** три request-а, все approved + - req-T1 → `.agent/requests/archive/req-T1.json` + - req-T2 → `.agent/requests/archive/req-T2.json` + - req-T3 → `.agent/requests/archive/req-T3.json` + +2. **Архивация задач:** + - T1 в manifest → one-liner, детали в `.agent/archive/tasks/T1.json` + - T2, T3 — аналогично + +3. **Обновление project-state.md:** + ```markdown + ## Key Modules + | Module | Status | Description | + |--------|--------|-------------| + | app/auth/router.py | new | Вынесенные роуты авторизации | + | app/auth/schemas.py | new | Pydantic схемы | + | app/auth/deps.py | new | Dependency injection | + ``` + +4. **Обновление roadmap:** задачи выполнены → moved to done + +5. **Создание handoff-summary.md:** + ```markdown + ## Session Summary + **Goal:** Рефакторинг авторизации + **Completed:** 3/3 tasks + **Approved requests:** req-T1, req-T2, req-T3 + + ## Project State + Модуль auth разбит на router+schema+deps. + Исходный auth/login.py: 450 → 120 строк. + + ## Next Steps + - Проверить, не осталось ли прямых импортов из старого login.py + - Обновить main.py если нужно + ``` + +--- + +### HANDOFF + +```text +HANDOFF COMPLETE + +Session: ses_v21_001 +Type: existing +Tasks: 3/3 completed + +Следующий агент начинает с .agent/handoff-summary.md +``` diff --git a/.agent/src/install.ps1 b/.agent/src/install.ps1 index fc8f560..08d57fa 100644 --- a/.agent/src/install.ps1 +++ b/.agent/src/install.ps1 @@ -1,29 +1,45 @@ #!/usr/bin/env pwsh # MetaAgent — установка исходников в целевой проект -# Usage: .\install.ps1 [[-Path] target_path] [-Update] +# Usage: .\install.ps1 [[-Path] target_path] [-Check] [-Update] param( [string]$Path = "", + [switch]$Check, [switch]$Update, [switch]$Help ) $MetaAgentSrc = Split-Path -Parent $MyInvocation.MyCommand.Path +# --- helpers --- +function Write-Info { Write-Host " →" -NoNewline -ForegroundColor Blue; Write-Host " $args" } +function Write-Ok { Write-Host " ✓" -NoNewline -ForegroundColor Green; Write-Host " $args" } +function Write-Skip { Write-Host " −" -NoNewline -ForegroundColor Yellow; Write-Host " $args" } +function Write-Warn { Write-Host " ⚠" -NoNewline -ForegroundColor Yellow; Write-Host " $args" } +function Write-Fail { Write-Host " ✗" -NoNewline -ForegroundColor Red; Write-Host " $args" } +function Write-Header { param([string]$Label) + Write-Host "" + Write-Host ("─" * 40) + Write-Host " $Label" + Write-Host ("─" * 40) +} + function Show-Usage { @" -Usage: install.ps1 [[-Path] target_path] [-Update] [-Help] +Usage: install.ps1 [[-Path] target_path] [-Check] [-Update] [-Help] Install MetaAgent sources into <target>/.agent/src/ Options: -Path Path to target project (default: interactive prompt) + -Check Dry-run: only check target readiness, no install -Update Overwrite existing files in .agent/src/ -Help Show this help Examples: .\install.ps1 .\install.ps1 -Path C:\Projects\MyApp + .\install.ps1 -Path C:\Projects\MyApp -Check .\install.ps1 -Path C:\Projects\MyApp -Update "@ exit 0 @@ -31,69 +47,163 @@ Examples: if ($Help) { Show-Usage } +# --- resolve target --- $TargetPath = $Path if (-not $TargetPath) { $TargetPath = Read-Host "Enter path to target project" } - $TargetPath = $TargetPath.Trim() + +# --- pre-flight ----------------------------------------------------------- +Write-Header "Pre-flight" + +# 1. target exists? if (-not (Test-Path $TargetPath -PathType Container)) { - Write-Error "Directory '$TargetPath' does not exist." + Write-Fail "Target directory '$TargetPath' does not exist." exit 1 } $TargetPath = (Resolve-Path $TargetPath).Path +Write-Ok "Target: $TargetPath" +# 2. write permission? (try to create a temp file as probe) +$probe = [System.IO.Path]::Combine($TargetPath, ".metaagent_probe.tmp") +try { + [System.IO.File]::WriteAllBytes($probe, [byte[]]@()) + Remove-Item $probe -Force + Write-Ok "Write permission: yes" +} catch { + Write-Fail "No write permission on '$TargetPath'." + exit 1 +} + +# 3. already installed? compare versions $AgentDir = Join-Path $TargetPath ".agent" $SrcDir = Join-Path $AgentDir "src" -$RulesDir = Join-Path $AgentDir "rules" -$ArchiveDir = Join-Path $AgentDir "archive" $VersionFile = Join-Path $MetaAgentSrc "VERSION" -$Version = if (Test-Path $VersionFile) { Get-Content $VersionFile -Raw | ForEach-Object { $_.Trim() } } else { "?" } -New-Item -ItemType Directory -Path $SrcDir -Force | Out-Null -New-Item -ItemType Directory -Path $RulesDir -Force | Out-Null -New-Item -ItemType Directory -Path $ArchiveDir -Force | Out-Null -Write-Host "Installing MetaAgent v$Version → $SrcDir" +$Version = if (Test-Path $VersionFile -PathType Leaf) { + (Get-Content $VersionFile -Raw -Encoding UTF8).Trim() +} else { "?" } + +$oldVerPath = Join-Path $SrcDir "VERSION" +if (Test-Path $oldVerPath -PathType Leaf) { + $oldVer = (Get-Content $oldVerPath -Raw -Encoding UTF8).Trim() + if ($oldVer -ne $Version) { + Write-Info "Existing MetaAgent v$oldVer found → upgrading to v$Version" + } else { + Write-Skip "MetaAgent v${Version} already installed (use -Update to reinstall)" + if (-not $Check) { + Write-Warn "No changes applied. Run with -Update to overwrite existing files." + } + } +} else { + Write-Info "Fresh install: MetaAgent v$Version" +} + +# 4. summary +$AgentsMd = Join-Path $TargetPath "AGENTS.md" +$RulesDir = Join-Path $AgentDir "rules" +$DecisionsDir = Join-Path $AgentDir "decisions" +$TasksDir = Join-Path $AgentDir "tasks" +$ContextDir = Join-Path $AgentDir "context" +$ArchiveDir = Join-Path $AgentDir "archive" +$RequestsDir = Join-Path $AgentDir "requests" +$RoadmapDir = Join-Path $AgentDir "roadmap" +$TempDir = Join-Path $TargetPath ".temp" + +$DirList = @( + $SrcDir, $RulesDir, $DecisionsDir, $TasksDir, + (Join-Path $TasksDir "backlog"), $ContextDir, + $ArchiveDir, + (Join-Path $ArchiveDir "tasks"), + (Join-Path $ArchiveDir "decisions"), + (Join-Path $ArchiveDir "checkpoints"), + (Join-Path $RequestsDir "active"), + (Join-Path $RequestsDir "archive"), + $RoadmapDir, + (Join-Path $RoadmapDir "archive"), + $TempDir +) + +if ($Check) { + Write-Host "" + Write-Info "--check mode: all checks passed, no changes applied." + exit 0 +} + +# --- phase 1: directories ------------------------------------------------ +Write-Header "Directories" + +foreach ($d in $DirList) { + $null = New-Item -ItemType Directory -Path $d -Force + $short = $d.Replace("$TargetPath\", "") + if (Test-Path $d -PathType Container) { + Write-Ok $short + } else { + Write-Fail "$short (creation failed)" + } +} + +# --- phase 2: files ------------------------------------------------------ +Write-Header "Files" + +$copyCount = 0 +$skipCount = 0 +$failCount = 0 -# --- copy files --- function Copy-File { param([string]$Src, [string]$DstDir) $name = Split-Path $Src -Leaf + $dst = Join-Path $DstDir $name if (-not (Test-Path $Src -PathType Leaf)) { - Write-Host " [skip] $name (not found)" + Write-Skip "$name (source not found)" + $script:skipCount++ return } - $dst = Join-Path $DstDir $name if ($Update -or -not (Test-Path $dst)) { - Copy-Item $Src $dst -Force - Write-Host " [copy] $name" + try { + Copy-Item $Src $dst -Force -ErrorAction Stop + Write-Ok $name + $script:copyCount++ + } catch { + Write-Fail $name + $script:failCount++ + } } else { - Write-Host " [skip] $name (exists, use -Update to overwrite)" + Write-Skip "$name (exists, use -Update to overwrite)" + $script:skipCount++ } } function Copy-Dir { param([string]$Src, [string]$DstDir) $name = Split-Path $Src -Leaf + $dst = Join-Path $DstDir $name if (-not (Test-Path $Src -PathType Container)) { - Write-Host " [skip] $name/ (not found)" + Write-Skip "$name/ (source not found)" + $script:skipCount++ return } - $dst = Join-Path $DstDir $name - New-Item -ItemType Directory -Path $dst -Force | Out-Null - if ($Update) { - Get-ChildItem $Src | ForEach-Object { - Copy-Item $_.FullName $dst -Recurse -Force - } - } else { - Get-ChildItem $Src | ForEach-Object { - $targetPath = Join-Path $dst $_.Name - if (-not (Test-Path $targetPath)) { - Copy-Item $_.FullName $dst -Recurse + $null = New-Item -ItemType Directory -Path $dst -Force + try { + if ($Update) { + Get-ChildItem $Src | ForEach-Object { + Copy-Item $_.FullName $dst -Recurse -Force -ErrorAction Stop + } + } else { + Get-ChildItem $Src | ForEach-Object { + $targetPath = Join-Path $dst $_.Name + if (-not (Test-Path $targetPath)) { + Copy-Item $_.FullName $dst -Recurse -ErrorAction Stop + } } } + Write-Ok "$name/" + $script:copyCount++ + } catch { + Write-Fail "$name/ (partial copy)" + $script:failCount++ } - Write-Host " [copy] $name/" } Copy-File (Join-Path $MetaAgentSrc "META_AGENT_GUIDE.md") $SrcDir @@ -105,12 +215,11 @@ Copy-Dir (Join-Path $MetaAgentSrc "TEMPLATES") $SrcDir Copy-File (Join-Path $MetaAgentSrc "install.sh") $SrcDir Copy-File (Join-Path $MetaAgentSrc "install.ps1") $SrcDir -# --- create / update AGENTS.md in root of target --- -$AgentsMd = Join-Path $TargetPath "AGENTS.md" +# --- phase 3: AGENTS.md -------------------------------------------------- +Write-Header "AGENTS.md" -function New-AgentsMd { - param([string]$Path) -@" +if (-not (Test-Path $AgentsMd -PathType Leaf)) { + $content = @" # MetaAgent Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v$Version — @@ -144,20 +253,69 @@ function New-AgentsMd { 3. **Прочитай** `.agent/rules/project-rules.md` — выполни пользовательские правила. 4. **Проверь** `.agent/checkpoints.json` — если существует, используй как состояние сессии. 5. **Проверь** `.agent/task-manifest.json` — если существует, выполняй задачи по порядку. -6. Если `.agent/` не инициализирован или устарел — запусти `install.ps1 -Update` для +6. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для обновления исходников MetaAgent до актуальной версии. "@ -} - -if (-not (Test-Path $AgentsMd -PathType Leaf)) { - New-AgentsMd $AgentsMd | Out-File -FilePath $AgentsMd -Encoding utf8 - Write-Host " [create] AGENTS.md" + $utf8 = [System.Text.Encoding]::UTF8 + [System.IO.File]::WriteAllBytes($AgentsMd, $utf8.GetBytes($content)) + Write-Ok "AGENTS.md created" } elseif ($Update) { - New-AgentsMd $AgentsMd | Out-File -FilePath $AgentsMd -Encoding utf8 - Write-Host " [update] AGENTS.md" + $content = @" +# MetaAgent + +Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v$Version — +набор инструкций для AI-агента. + +## Контекст MetaAgent + +| Ресурс | Путь | +|--------|------| +| Главная инструкция | `.agent/src/META_AGENT_GUIDE.md` | +| Протоколы фаз | `.agent/src/PROTOCOLS/` | +| Шаблоны артефактов | `.agent/src/TEMPLATES/` | +| Границы (что разрешено/запрещено) | `.agent/src/BOUNDARIES.md` | +| Правила проекта | `.agent/rules/project-rules.md` | +| Примеры работы | `.agent/src/WORKFLOW.md` | +| Версия | `.agent/src/VERSION` | + +## Состояние сессии (если инициализировано) + +| Артефакт | Путь | +|----------|------| +| Чекпоинты сессии | `.agent/checkpoints.json` | +| Манифест задач | `.agent/task-manifest.json` | +| Сводка для exec-агента | `.agent/handoff-summary.md` | +| Анализ репозитория | `.agent/analysis-report.md` | + +## Для исполнительного агента + +1. **Прочитай** `.agent/src/META_AGENT_GUIDE.md` — пойми жизненный цикл MetaAgent. +2. **Прочитай** `.agent/src/BOUNDARIES.md` — соблюдай границы. +3. **Прочитай** `.agent/rules/project-rules.md` — выполни пользовательские правила. +4. **Проверь** `.agent/checkpoints.json` — если существует, используй как состояние сессии. +5. **Проверь** `.agent/task-manifest.json` — если существует, выполняй задачи по порядку. +6. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для + обновления исходников MetaAgent до актуальной версии. +"@ + $utf8 = [System.Text.Encoding]::UTF8 + [System.IO.File]::WriteAllBytes($AgentsMd, $utf8.GetBytes($content)) + Write-Ok "AGENTS.md updated" } else { - Write-Host " [skip] AGENTS.md (exists, use -Update to overwrite)" + Write-Skip "AGENTS.md (exists, use -Update to overwrite)" + $script:skipCount++ } +# --- summary ------------------------------------------------------------- +Write-Header "Summary" +Write-Host " MetaAgent v$Version → $SrcDir" Write-Host "" -Write-Host "Done! MetaAgent v$Version installed at $SrcDir" +if ($copyCount -gt 0) { Write-Ok "$copyCount file(s) copied" } +if ($skipCount -gt 0) { Write-Skip "$skipCount file(s) skipped" } +if ($failCount -gt 0) { Write-Fail "$failCount file(s) failed" } +Write-Host "" +if ($failCount -eq 0) { + Write-Ok "Installation completed successfully." +} else { + Write-Fail "Installation completed with $failCount error(s)." + exit 1 +} diff --git a/.agent/src/install.sh b/.agent/src/install.sh index 2ca564f..3e2335f 100644 --- a/.agent/src/install.sh +++ b/.agent/src/install.sh @@ -1,89 +1,207 @@ #!/usr/bin/env bash # MetaAgent — установка исходников в целевой проект -# Usage: ./install.sh [--update] [target_path] +# Usage: ./install.sh [--check|--update] [target_path] set -euo pipefail METAAGENT_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +# --- helpers --- +red=; grn=; ylw=; blu=; rst= +if [[ -t 1 ]] && command -v tput >/dev/null 2>&1; then + red=$(tput setaf 1); grn=$(tput setaf 2) + ylw=$(tput setaf 3); blu=$(tput setaf 4) + rst=$(tput sgr0) +fi +info() { echo " ${blu}→${rst} $*"; } +ok() { echo " ${grn}✓${rst} $*"; } +skip() { echo " ${ylw}−${rst} $*"; } +warn() { echo " ${ylw}⚠${rst} $*"; } +fail() { echo " ${red}✗${rst} $*"; } +header(){ echo; echo "────────────────────────────────────────"; echo " $*"; echo "────────────────────────────────────────"; } + usage() { cat <<EOF -Usage: $0 [--update] [target_path] +Usage: $0 [--check|--update] [target_path] Install MetaAgent sources into <target>/.agent/src/ Options: + --check, -c Dry-run: only check target readiness, no install --update, -u Overwrite existing files in .agent/src/ --help, -h Show this help Examples: $0 $0 /path/to/project + $0 --check /path/to/project $0 --update /path/to/project EOF exit 0 } +# --- arg parsing --- +CHECK=false UPDATE=false TARGET_PATH="" while [[ $# -gt 0 ]]; do case "$1" in - --update|-u) UPDATE=true; shift ;; - --help|-h) usage ;; - --*) echo "Unknown option: $1"; usage ;; + --check|-c) CHECK=true; shift ;; + --update|-u) UPDATE=true; shift ;; + --help|-h) usage ;; + --*) echo "${red}Unknown option:${rst} $1"; usage ;; *) TARGET_PATH="$1"; shift ;; esac done +# --- resolve target --- if [[ -z "$TARGET_PATH" ]]; then read -r -p "Enter path to target project: " TARGET_PATH fi - TARGET_PATH="${TARGET_PATH/#\~/$HOME}" + +# --- pre-flight ----------------------------------------------------------- +header "Pre-flight" + +# 1. target exists? +if [[ ! -d "$TARGET_PATH" ]]; then + fail "Target directory '$TARGET_PATH' does not exist." + exit 1 +fi + +# resolve to absolute path TARGET_PATH="$(cd "$TARGET_PATH" 2>/dev/null && pwd)" || { - echo "Error: Directory '$TARGET_PATH' does not exist." + fail "Cannot access '$TARGET_PATH'." exit 1 } +ok "Target: $TARGET_PATH" +# 2. write permission? +if [[ ! -w "$TARGET_PATH" ]]; then + fail "No write permission on '$TARGET_PATH'." + exit 1 +fi +ok "Write permission: yes" + +# 3. already installed? compare versions AGENT_DIR="$TARGET_PATH/.agent" SRC_DIR="$AGENT_DIR/src" VERSION="$(cat "$METAAGENT_SRC/VERSION" 2>/dev/null || echo '?')" +if [[ -f "$SRC_DIR/VERSION" ]]; then + OLD_VER="$(cat "$SRC_DIR/VERSION" 2>/dev/null || echo '?')" + if [[ "$OLD_VER" != "$VERSION" ]]; then + info "Existing MetaAgent v${OLD_VER} found → upgrading to v${VERSION}" + else + skip "MetaAgent v${VERSION} already installed (use --update to reinstall)" + if [[ "$CHECK" == false ]]; then + warn "No changes applied. Run with --update to overwrite existing files." + fi + fi +else + info "Fresh install: MetaAgent v$VERSION" +fi + +# 4. summary +AGENTS_MD="$TARGET_PATH/AGENTS.md" RULES_DIR="$AGENT_DIR/rules" +DECISIONS_DIR="$AGENT_DIR/decisions" +TASKS_DIR="$AGENT_DIR/tasks" +CONTEXT_DIR="$AGENT_DIR/context" ARCHIVE_DIR="$AGENT_DIR/archive" -mkdir -p "$SRC_DIR" "$RULES_DIR" "$ARCHIVE_DIR" -echo "Installing MetaAgent v$VERSION → $SRC_DIR" +ARCHIVE_TASKS_DIR="$ARCHIVE_DIR/tasks" +ARCHIVE_DECISIONS_DIR="$ARCHIVE_DIR/decisions" +ARCHIVE_CHECKPOINTS_DIR="$ARCHIVE_DIR/checkpoints" +REQUESTS_DIR="$AGENT_DIR/requests" +REQUESTS_ACTIVE_DIR="$REQUESTS_DIR/active" +REQUESTS_ARCHIVE_DIR="$REQUESTS_DIR/archive" +ROADMAP_DIR="$AGENT_DIR/roadmap" +ROADMAP_ARCHIVE_DIR="$ROADMAP_DIR/archive" +TEMP_DIR="$TARGET_PATH/.temp" + +if [[ "$CHECK" == true ]]; then + echo "" + info "${ylw}--check mode:${rst} all checks passed, no changes applied." + exit 0 +fi + +# --- phase 1: directories ------------------------------------------------ +header "Directories" + +mkdir -p "$SRC_DIR" "$RULES_DIR" "$DECISIONS_DIR" "$TASKS_DIR" "$TASKS_DIR/backlog" \ + "$CONTEXT_DIR" "$ARCHIVE_DIR" "$ARCHIVE_TASKS_DIR" "$ARCHIVE_DECISIONS_DIR" \ + "$ARCHIVE_CHECKPOINTS_DIR" \ + "$REQUESTS_ACTIVE_DIR" "$REQUESTS_ARCHIVE_DIR" \ + "$ROADMAP_DIR" "$ROADMAP_ARCHIVE_DIR" \ + "$TEMP_DIR" + +for d in "$SRC_DIR" "$RULES_DIR" "$DECISIONS_DIR" "$TASKS_DIR" "$TASKS_DIR/backlog" \ + "$CONTEXT_DIR" "$ARCHIVE_DIR" "$ARCHIVE_TASKS_DIR" "$ARCHIVE_DECISIONS_DIR" \ + "$ARCHIVE_CHECKPOINTS_DIR" \ + "$REQUESTS_ACTIVE_DIR" "$REQUESTS_ARCHIVE_DIR" \ + "$ROADMAP_DIR" "$ROADMAP_ARCHIVE_DIR" \ + "$TEMP_DIR"; do + short="${d#$TARGET_PATH/}" + if [[ -d "$d" ]]; then + ok "$short" + else + fail "$short (creation failed)" + fi +done + +# --- phase 2: files ------------------------------------------------------ +header "Files" + +COPY_COUNT=0 +SKIP_COUNT=0 +FAIL_COUNT=0 -# --- copy files --- copy_file() { local src="$1" dst_dir="$2" local name; name="$(basename "$src")" + local dst="$dst_dir/$name" if [[ ! -f "$src" ]]; then - echo " [skip] $name (not found)" + skip "$name (source not found)" + ((SKIP_COUNT += 1)) return fi - if [[ "$UPDATE" == true ]] || [[ ! -f "$dst_dir/$name" ]]; then - cp "$src" "$dst_dir/$name" - echo " [copy] $name" + if [[ "$UPDATE" == true ]] || [[ ! -f "$dst" ]]; then + if cp "$src" "$dst"; then + ok "$name" + ((COPY_COUNT++)) + else + fail "$name" + ((FAIL_COUNT++)) + fi else - echo " [skip] $name (exists, use --update to overwrite)" + skip "$name (exists, use --update to overwrite)" + ((SKIP_COUNT += 1)) fi } copy_dir() { local src="$1" dst_dir="$2" local name; name="$(basename "$src")" + local dst="$dst_dir/$name" if [[ ! -d "$src" ]]; then - echo " [skip] $name/ (not found)" + skip "$name/ (source not found)" + ((SKIP_COUNT += 1)) return fi - mkdir -p "$dst_dir/$name" + mkdir -p "$dst" if [[ "$UPDATE" == true ]]; then - cp -rf "$src"/* "$dst_dir/$name/" 2>/dev/null || true + if cp -rf "$src"/* "$dst/" 2>/dev/null; then + ok "$name/" + ((COPY_COUNT++)) + else + fail "$name/ (partial copy)" + ((FAIL_COUNT++)) + fi else - cp -rn "$src"/* "$dst_dir/$name/" 2>/dev/null || true + cp -rn "$src"/* "$dst/" 2>/dev/null || true + ok "$name/" + ((COPY_COUNT++)) fi - echo " [copy] $name/" } copy_file "$METAAGENT_SRC/META_AGENT_GUIDE.md" "$SRC_DIR" @@ -95,8 +213,8 @@ copy_dir "$METAAGENT_SRC/TEMPLATES" "$SRC_DIR" copy_file "$METAAGENT_SRC/install.sh" "$SRC_DIR" copy_file "$METAAGENT_SRC/install.ps1" "$SRC_DIR" -# --- create / update AGENTS.md in root of target --- -AGENTS_MD="$TARGET_PATH/AGENTS.md" +# --- phase 3: AGENTS.md -------------------------------------------------- +header "AGENTS.md" create_agents_md() { cat > "$1" << AGENTS_EOF @@ -140,13 +258,32 @@ AGENTS_EOF if [[ ! -f "$AGENTS_MD" ]]; then create_agents_md "$AGENTS_MD" - echo " [create] AGENTS.md" + ok "AGENTS.md created" elif [[ "$UPDATE" == true ]]; then create_agents_md "$AGENTS_MD" - echo " [update] AGENTS.md" + ok "AGENTS.md updated" else - echo " [skip] AGENTS.md (exists, use --update to overwrite)" + skip "AGENTS.md (exists, use --update to overwrite)" + ((SKIP_COUNT += 1)) fi +# --- summary ------------------------------------------------------------- +header "Summary" +echo " MetaAgent v$VERSION → $SRC_DIR" echo "" -echo "Done! MetaAgent v$VERSION installed at $SRC_DIR" +if (( COPY_COUNT > 0 )); then + ok "${COPY_COUNT} file(s) copied" +fi +if (( SKIP_COUNT > 0 )); then + skip "${SKIP_COUNT} file(s) skipped" +fi +if (( FAIL_COUNT > 0 )); then + fail "${FAIL_COUNT} file(s) failed" +fi +echo "" +if (( FAIL_COUNT == 0 )); then + ok "Installation completed successfully." +else + fail "Installation completed with ${FAIL_COUNT} error(s)." + exit 1 +fi diff --git a/AGENTS.md b/AGENTS.md index 44dc3db..b79af86 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,35 @@ # MetaAgent -Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v1.1.0 — +Этот проект использует [MetaAgent](.agent/src/META_AGENT_GUIDE.md) v2.1.0 — набор инструкций для AI-агента. ## Контекст MetaAgent | Ресурс | Путь | |--------|------| -| Главная инструкция | `.agent/src/META_AGENT_GUIDE.md` | -| Протоколы фаз | `.agent/src/PROTOCOLS/` | -| Шаблоны артефактов | `.agent/src/TEMPLATES/` | -| Границы (что разрешено/запрещено) | `.agent/src/BOUNDARIES.md` | -| Правила проекта | `.agent/rules/project-rules.md` | -| Примеры работы | `.agent/src/WORKFLOW.md` | -| Версия | `.agent/src/VERSION` | +| Главная инструкция | .agent/src/META_AGENT_GUIDE.md | +| Протоколы фаз | .agent/src/PROTOCOLS/ | +| Шаблоны артефактов | .agent/src/TEMPLATES/ | +| Границы (что разрешено/запрещено) | .agent/src/BOUNDARIES.md | +| Правила проекта | .agent/rules/project-rules.md | +| Примеры работы | .agent/src/WORKFLOW.md | +| Версия | .agent/src/VERSION | ## Состояние сессии (если инициализировано) | Артефакт | Путь | |----------|------| -| Чекпоинты сессии | `.agent/checkpoints.json` | -| Манифест задач | `.agent/task-manifest.json` | -| Сводка для exec-агента | `.agent/handoff-summary.md` | -| Анализ репозитория | `.agent/analysis-report.md` | +| Чекпоинты сессии | .agent/checkpoints.json | +| Манифест задач | .agent/task-manifest.json | +| Сводка для exec-агента | .agent/handoff-summary.md | +| Анализ репозитория | .agent/analysis-report.md | ## Для исполнительного агента -1. **Прочитай** `.agent/src/META_AGENT_GUIDE.md` — пойми жизненный цикл MetaAgent. -2. **Прочитай** `.agent/src/BOUNDARIES.md` — соблюдай границы. -3. **Прочитай** `.agent/rules/project-rules.md` — выполни пользовательские правила. -4. **Проверь** `.agent/checkpoints.json` — если существует, используй как состояние сессии. -5. **Проверь** `.agent/task-manifest.json` — если существует, выполняй задачи по порядку. -6. Если `.agent/` не инициализирован или устарел — запусти `install.sh --update` для - обновления исходников MetaAgent до актуальной версии. +1. **Прочитай** .agent/src/META_AGENT_GUIDE.md — пойми жизненный цикл MetaAgent. +2. **Прочитай** .agent/src/BOUNDARIES.md — соблюдай границы. +3. **Прочитай** .agent/rules/project-rules.md — выполни пользовательские правила. +4. **Проверь** .agent/checkpoints.json — если существует, используй как состояние сессии. +5. **Проверь** .agent/task-manifest.json — если существует, выполняй задачи по порядку. +6. Если .agent/ не инициализирован или устарел — запусти install.sh --update для + обновления исходников MetaAgent до актуальной версии. \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d74a182 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Jor Oqyude + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.