metaagent integration
This commit is contained in:
@@ -0,0 +1,336 @@
|
||||
# META_AGENT_GUIDE — Главная инструкция
|
||||
|
||||
## Жизненный цикл сессии
|
||||
|
||||
```
|
||||
.agent/metaagent-request.md
|
||||
│
|
||||
▼
|
||||
INIT → ANALYSE → [DESIGN] → [RED_TEAM] → DECOMPOSITION → SETUP → (CHECKPOINT)* → HANDOFF → EXIT
|
||||
│ │
|
||||
▼ ▼
|
||||
ADR (опц.) Invariant Tasks (опц.)
|
||||
Alt.Arch (опц.)
|
||||
Risk Register (опц.)
|
||||
```
|
||||
|
||||
Фазы выполняются **строго последовательно**. Фаза DESIGN — только если project_type = greenfield/scaffold.
|
||||
Фаза RED_TEAM — только если config.red_team = yes.
|
||||
|
||||
Все артефакты размещаются в `.agent/` целевого репозитория (с layer-структурой или плоские, в зависимости от config).
|
||||
|
||||
---
|
||||
|
||||
## Конфигурация сессии (.agent/metaagent-request.md)
|
||||
|
||||
Перед запуском сессии пользователь заполняет `.agent/metaagent-request.md` (см. `TEMPLATES/metaagent-request.md`). Файл должен находиться в директории `.agent/` целевого репозитория.
|
||||
|
||||
Ключевые параметры:
|
||||
|
||||
### Шкала глубины (depth 1-10)
|
||||
|
||||
| Уровень | Название | Что выполняется |
|
||||
|---|---|---|
|
||||
| 1-2 | Scaffold | INIT → ANALYSIS → SETUP (только структура, без реализации) |
|
||||
| 3-4 | Light | + DESIGN (без ADR/альтернатив), DECOMPOSITION (без инвариантов), HANDOFF — **(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 |
|
||||
|
||||
### Функции (таблица вкл/выкл)
|
||||
|
||||
| Функция | Фаза | Глубина | Описание |
|
||||
|---|---|---|---|
|
||||
| adr | DESIGN | >=7 | Создание ADR для каждого ключевого решения |
|
||||
| alternative_arch | DESIGN | >=7 | Обязательное описание альтернативной архитектуры |
|
||||
| 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` (если не существовал)
|
||||
|
||||
```json
|
||||
{
|
||||
"metaagent_version": "1.1.0",
|
||||
"session_id": "<uuid>",
|
||||
"target_repo": "<path>",
|
||||
"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": "<timestamp>"
|
||||
}
|
||||
```
|
||||
|
||||
**Выход:** готовая `.agent/` + checkpoints.json с metaagent_version и config.
|
||||
|
||||
---
|
||||
|
||||
## Фаза 1: ANALYSE
|
||||
|
||||
**Вход:** целевой репозиторий, `.agent/metaagent-request.md` (или auto-generated), checkpoints.json (analysis: pending, config: from INIT).
|
||||
|
||||
**Протокол:** `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`
|
||||
|
||||
**Ветвление:**
|
||||
- `project_type = "greenfield"` или `"scaffold"` → далее фаза DESIGN
|
||||
- `project_type = "existing"` → DESIGN пропускается, сразу DECOMPOSITION
|
||||
|
||||
---
|
||||
|
||||
## Фаза 2: DESIGN (условная)
|
||||
|
||||
**Вход:** analysis-report.md, checkpoints.json (analysis: completed, project_type: greenfield/scaffold).
|
||||
|
||||
**Протокол:** `PROTOCOLS/02_DESIGN.md`
|
||||
|
||||
**Действия:**
|
||||
- **Прочитать `.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.red_team = yes → следующая фаза RED_TEAM
|
||||
- Иначе → сразу DECOMPOSITION
|
||||
|
||||
**Выход:** `.agent/design-report.md`, опционально `.agent/layer-1/adr/*.md`, `.agent/layer-1/risk-register.md`
|
||||
|
||||
---
|
||||
|
||||
## Фаза 2b: RED_TEAM (опциональная)
|
||||
|
||||
**Вход:** design-report.md, ADR (опционально), checkpoints.json (design: completed).
|
||||
|
||||
**Протокол:** `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"`
|
||||
|
||||
**Выход:** `.agent/layer-1/red-team-report.md`
|
||||
|
||||
---
|
||||
|
||||
## Фаза 3: DECOMPOSITION
|
||||
|
||||
**Вход:** analysis-report.md + design-report.md (опционально) + ADR (опционально) + checkpoints.json.
|
||||
|
||||
**Протокол:** `PROTOCOLS/03_DECOMPOSITION.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`
|
||||
|
||||
**Выход:** `.agent/task-manifest.json`, `.agent/task-manifest.md`
|
||||
|
||||
---
|
||||
|
||||
## Фаза 4: SETUP
|
||||
|
||||
**Вход:** analysis-report.md, design-report.md (опционально), task-manifest.json, checkpoints.json (decomposition: completed).
|
||||
|
||||
**Протокол:** `PROTOCOLS/04_ENVIRONMENT_SETUP.md`
|
||||
|
||||
**Действия:**
|
||||
- **Прочитать `.agent/rules/project-rules.md`** — учесть пользовательские правила
|
||||
- Выполнить настройку окружения по протоколу (ветка A для existing, ветка B для greenfield)
|
||||
- Записать результат проверки в `.agent/baseline-test-report.log` и `.agent/setup-report.log`
|
||||
- Обновить checkpoints.json: `phases.environment = "completed"`
|
||||
|
||||
**Выход:** рабочее окружение + `.agent/baseline-test-report.log`
|
||||
|
||||
---
|
||||
|
||||
## Фаза 5: CHECKPOINT (сквозная)
|
||||
|
||||
**Вход:** любая фаза.
|
||||
|
||||
**Протокол:** обновлять checkpoints.json после каждого значимого шага.
|
||||
|
||||
**Архивирование перед сохранением чекпоинта:**
|
||||
- Если checkpoints.json уже существует — сохранить предыдущую версию в `.agent/archive/checkpoints/<last_updated>.json`
|
||||
|
||||
**Формат:**
|
||||
|
||||
```json
|
||||
{
|
||||
"metaagent_version": "1.1.0",
|
||||
"session_id": "<uuid>",
|
||||
"target_repo": "<path>",
|
||||
"goal": "<цель>",
|
||||
"project_type": "existing | greenfield | scaffold",
|
||||
"config": {
|
||||
"depth": 6,
|
||||
"design": { "adr": true, "alternative_arch": true },
|
||||
"red_team": false,
|
||||
"risk_register": false,
|
||||
"decomposition": { "invariant_tests": true },
|
||||
"handoff": { "layer_structure": true }
|
||||
},
|
||||
"phases": {
|
||||
"analysis": "completed",
|
||||
"design": "completed",
|
||||
"red_team": "skipped",
|
||||
"decomposition": "in_progress",
|
||||
"environment": "pending",
|
||||
"handoff": "pending"
|
||||
},
|
||||
"tasks": [
|
||||
{ "id": "T1", "title": "...", "status": "completed",
|
||||
"depends_on": [], "acceptance_criteria": ["..."] },
|
||||
{ "id": "T2", "title": "...", "status": "pending",
|
||||
"depends_on": ["T1"], "acceptance_criteria": ["..."] }
|
||||
],
|
||||
"last_updated": "<timestamp>"
|
||||
}
|
||||
```
|
||||
|
||||
`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/<id>.json`
|
||||
- Заменить в манифесте на one-liner: `{ "id": "<id>", "title": "<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
|
||||
...
|
||||
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
|
||||
```
|
||||
|
||||
Исполнительный агент всегда начинает с layer-0 (checkpoints + session-summary),
|
||||
затем при необходимости обращается к layer-1 (ADR для понимания "почему"),
|
||||
layer-2 (детали дизайна), layer-3 (что было сделано).
|
||||
Reference in New Issue
Block a user