nifodea/.agent/src/META_AGENT_GUIDE.md

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 (если не существовал)

{
  "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

Формат:

{
  "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 (что было сделано).