HG SDLC - от задачи до изменений в проекте

HG SDLC (Human Guided SDLC) — оркестратор, который организует работу AI-агента над задачей как управляемый процесс под контролем человека. Вы описываете задачу и запускаете подготовленный сценарий, а агент выполняет работу с файлами проекта, используя доступный контекст. Система управляет последовательностью шагов и переходами между ними: запускает агента, команды и проверки, запрашивает необходимые данные у человека и приостанавливает процесс в точках, где требуется принять решение или согласовать результат.

Human Guided SDLC отражает принцип работы платформы: человек не обязан вручную сопровождать каждый шаг, но сохраняет контроль там, где нужно уточнить требования, принять решение или проверить результат. Какие этапы проходит задача, какие проверки выполняются и где требуется участие человека, определяется выбранным сценарием и режимом согласований запуска.

Для чего нужен HG SDLC

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

HG SDLC позволяет оформить такой способ работы в повторно используемый сценарий. Например, можно подготовить процесс для исправления ошибок, добавления тестов, обновления документации, код-ревью или разработки нового функционала.

В сценарии команда определяет, какие действия выполняет агент, какие команды и автоматические проверки запускаются, где требуется участие человека и куда должна вернуться задача, если результат нужно доработать.

Для каждого запуска HG SDLC сохраняет историю выполнения: пройденные шаги, попытки, созданные артефакты и решения человека. Благодаря этому можно понять, что уже сделано, на каком шаге находится задача, почему процесс остановился и из-за чего потребовалась доработка.

Кому и как помогает HG SDLC

• Тому, кто ставит задачу: описать ожидаемый результат, запустить сценарий и подключаться в предусмотренных точках принятия решений. Например, владелец продукта может работать через подготовленный продуктовый сценарий, не погружаясь в техническую конфигурацию процесса.
• Разработчику: передать агенту часть работы с кодом, изучить изменения и результаты проверок, а затем принять результат или вернуть его на доработку с конкретным замечанием. Если проблему удобнее решить вручную, можно временно перехватить управление через «Перехват управления», внести изменения и затем вернуть задачу в управляемый процесс.
• Тому, кто настраивает работу команды: создавать и версионировать сценарии, настраивать инструкции для агентов, подключать навыки и субагентов, добавлять автоматические проверки и точки согласования. Переиспользуемые сценарии и компоненты можно хранить в каталоге и синхронизировать с Git-репозиторием.

Выбор доступных действий в интерфейсе зависит от вашей роли и доступа к проекту. Настройку процессов и повседневную работу над задачами могут выполнять разные участники команды.

HG SDLC не заменяет качественную постановку задачи, контекст и проверки и сам по себе не делает AI-агента сильнее. Его задача - связать этапы работы в управляемый процесс, сохранить его состояние и историю и показать человеку, где требуется его решение или вмешательство.

Как проходит работа над задачей

1. Опишите задачу. Выберите проект, сценарий и опишите, что нужно изменить.
2. Запустите процесс. Такой процесс называется сценарием: это заранее заданные шаги работы агента, проверок и участия человека. Конкретное выполнение сценария называется запуском. У него есть собственные параметры, статус и история.
3. Следите за выполнением. Платформа готовит рабочее пространство — рабочую копию файлов для этого запуска — и передаёт агенту задачу и настройки проекта. Агент выполняет свои шаги, а команды, добавленные в сценарий, проверяют результат. В карточке запуска можно посмотреть текущий шаг, журнал, изменения и созданные документы или другие файлы — артефакты.
4. Ответьте, когда требуется ваше участие. Точка запроса данных или согласования называется точкой участия человека. На ней можно уточнить требования или проверить подготовленный результат. При согласовании вы принимаете работу либо описываете, что нужно доработать. Возможность ручного редактирования зависит от состояния точки участия человека и ваших прав.
5. Проверьте итог. После успешного завершения процесса платформа отправляет изменения в Git. Способ отправки выбирается при запуске.

Сценарий имеет версии: команда может изменять процесс для новых задач, а запуск сохраняет сведения об использованных компонентах и параметрах. История помогает разобраться в выполнении, хотя одинаковые настройки не гарантируют одинаковый ответ ИИ при повторе.

Пример: добавить инструкцию в проект

Для первого знакомства удобно взять небольшую задачу с понятным результатом. В учебном сценарии агенту поручают создать файл hello-hgsdlc.md с описанием проекта и проверить, что файл появился.

В данном примере выбирается режим с ответом человека в каждой точке участия человека. Агент создаёт файл, предусмотренная команда проверяет его наличие, и на согласовании вы читаете текст. Проверка существования файла подтверждает только его наличие; содержание оцениваете вы.

Если текст неполный, замечание можно сформулировать так: «Добавь, для кого предназначен проект, и объясни первый шаг пользователя». После доработки проверьте новую версию. Когда процесс успешно завершится и изменения будут отправлены в Git в рабочую ветку.

Где вы управляете результатом

В (консоли запуска) видно, какой шаг выполняется, что сообщил агент или команда проверки и какие файлы изменились. Если процесс ждёт человека, откройте текущую точку участия человека и ответьте на запрос. Если шаг завершился ошибкой, изучите его сообщение; доступные действия для продолжения зависят от ошибки, состояния запуска и вашей роли.

Точка участия человека требует ответа только тогда, когда это предусмотрено выбранным режимом согласований. Есть режимы, пропускающие часть или все точки участия человека. Если хотите проверять каждую точку участия человека, выберите Требовать все гейты; сами точки согласования должны присутствовать в сценарии.

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

Принятие результата шага не означает предварительного разрешения каждой команды агента. Команды проверки выявляют предусмотренные ими ошибки, а участники команды оценивают результат и качество изменений. Ручная доработка позволяет изменить файлы в поддерживающей её точке участия человека, после чего результат тоже нужно проверить.

Что вы получаете на выходе

• Изменения проекта: код, документацию или другие файлы по задаче. Перед приёмкой проверьте полный список изменений: ожидаемые изменения в сценарии не ограничивают список файлов, которые может изменить агент.
• Сведения о выполнении: состояния и попытки шагов, журналы, результаты настроенных проверок и решения на согласованиях.
• Результат отправки в Git: отдельную рабочую ветку, изменения в выбранной ветке или запрос на слияние. Вариант зависит от режима публикации, прав подключения и поддержки Git-хостинга.

Отправка изменений в Git сама по себе не означает их слияния с основной версией проекта или развёртывания приложения. Эти действия определяются правилами команды. Если работа выполнена, но отправка завершилась ошибкой, статус публикации поможет отличить этот случай от ошибки самого процесса; подробнее о публикации.

Что нужно подготовить для работы

Если HG SDLC уже установлен у вашей команды, получите у администратора адрес, учётную запись и доступ к проекту. Уточните, какой сценарий использовать для первой задачи. Вам не нужно самостоятельно устанавливать сервер, если команда уже подготовила рабочую среду.

Для запуска задач с ИИ в установке должны быть подключены агент и доступ к модели, репозиторий проекта и совместимый каталог процессов. Эти настройки подготавливает администратор или другой уполномоченный участник.

Если устанавливаете HG SDLC самостоятельно

Способы установки описаны в README проекта. Выберите подходящий вместе с тем, кто будет обслуживать платформу:

• Локально из исходников — backend и frontend работают на вашей машине, PostgreSQL — в Docker. Основной путь для знакомства и разработки.
• Через пользовательский CLI — установка опубликованной JAR-сборки без клонирования исходников.
• Production Docker Compose — развёртывание PostgreSQL, backend и frontend на одной Linux VM.

Текущий backend Docker image устанавливает только Qwen CLI. Claude, GigaCode, Codex и OpenCode поддерживаются средой выполнения при локальной установке соответствующего CLI или ACP adapter. Готовых контейнерных образов для них в репозитории нет.

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

1. Подключите coding agent.
2. Добавьте SCM provider и тестовый репозиторий.
3. Подключите ветку тестового каталога для выбранного агента.
4. Выполните первый сценарий.

Краткий сценарий внутри справочника: первый проект и сценарий.

Поддерживаемые coding agents

Агент	Идентификатор среды выполнения	Локальная среда выполнения ACP	Текущий Docker image
Qwen	qwen	Да	Да
Claude	claude	Да	Нет
GigaCode	gigacode	Да	Нет
Codex	codex	Да	Нет
OpenCode	opencode	Да	Нет

Сценарии, навыки, субагенты и ветка тестового каталога должны соответствовать выбранному идентификатору среды выполнения. CLI или ACP adapter устанавливают и авторизуют на машине, где работает backend; порядок подключения.

Доступ после установки

• Локальный профиль local: пользователь для разработки admin / admin.
• Production: первый ADMIN создаётся однократно через bootstrap-процедуру.

admin / admin предназначен только для локальной разработки и не создаётся в production. Для существующей командной установки получите адрес и учётную запись у администратора.

Документация

• В этом справочнике: карта возможностей, роли и права, ограничения и данные.
• Полное руководство пользователя.
• Установка и первый запуск.
• Учебные сценарии.
• Создание сценариев, навыков и субагентов.
• Пользователи, команды и области видимости.
• Справочник системы.
• Эксплуатация.
• Устранение проблем.

Разработчикам

• Developer onboarding.
• Индекс технических спецификаций.
• Release notes 2.1 — описание выпуска 2.1, указанное в README; целевая версия этого справочника — 2.2.0.
• Contributing.
• Сборка справочника и публикация в GitVerse Pages.

Команды сборки и тестирования приведены в README проекта.

Возможности и границы

В терминах AI‑Disrupt PDLC платформа прежде всего помогает настроить петли намерения и реализации через сценарий. Сквозная валидация (validation spine) и контроль (governance mesh) реализованы частично; оценка бизнес-эффекта после развёртывания (outcome check) остаётся направлением развития. Подробнее — границы реализации и планы.

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

Рабочая копия файлов запуска отделена от других запусков, но сама по себе не ограничивает права процесса агента в операционной системе. Настройка среды выполнения остаётся задачей администратора. Код и текст задачи могут передаваться выбранному агенту и поставщику модели — учитывайте это при выборе данных для работы. Подробнее — в ограничениях и правилах работы с данными.

Что показала практика и что сохранять

Первые месяцы работы, описанные в статье «Практическое воплощение концепций AI‑Disrupt PDLC» от 25 августа 2026 года, показали ценность единой истории: можно увидеть версию сценария, результаты, причины возвратов и решения человека. Сопоставимых данных для оценки ускорения и улучшения качества на этом этапе было недостаточно; конкретный эффект в процентах платформе не приписывается.

Сравнивайте задачи в HG SDLC с привычным способом работы по затратам времени всей команды, качеству результата и цене ошибок. Оркестратор сам по себе не усиливает агента и не заменяет качественную спецификацию, контекст и проверки.

Долгосрочный актив команды — знания о продукте и системе, ограничениях, архитектурных решениях и фактических результатах. Инструкции, навыки и разбиение на шаги будут меняться вместе с моделями. Зафиксированные знания должны накапливаться независимо от выбранного инструмента; проверенные сценарии помогают применять их, а история исполнения — уточнять.

Версия документации

• Дата редакции справочника: 29 сентября 2026 года.
• Целевая версия продукта: 2.2.0.
• Исходная точка для описания возможностей: тег v2.2.0, коммит ee2b155d.
• Релизная ветка: release/2.2.0.

Доступность функций зависит от роли, настроек и установленных агентов. Для сборки с изменениями после релиза учитывайте её тег или коммит. Состав опубликованного выпуска сверяйте с релизами GitVerse.

Проект и обратная связь

• Концепция процесса, границы и направления развития изложены по статье «Практическое воплощение концепций AI‑Disrupt PDLC» от 25 августа 2026 года.
• README проекта — способы установки и таблица поддерживаемых агентов.
• Исходный код в GitVerse.
• Задачи проекта — укажите версию, шаги воспроизведения и очищенный от секретов журнал.
• Лицензия Apache 2.0.

Карта возможностей HG SDLC

Найдите нужную задачу в списке и откройте её описание. В каждом разделе указано, кому доступна возможность, как ею пользоваться и что проверить при ошибке.

Статусы

Статус	Значение
Реализовано (implemented)	Функция реализована в целевом релизе 2.2.0 (v2.2.0); доступность зависит от роли, настроек и установленных агентов.
Экспериментально (experimental)	Функция реализована, но имеет экспериментальный статус и ограничения доступности.
Частично (partial)	Доступен полезный сценарий, но паспорт явно фиксирует ограничения.
Запланировано (planned)	Функция описана как направление, но ещё не доступна пользователю.
Устаревает (deprecated)	Функция выводится из эксплуатации и не должна использоваться в новых сценариях.

Карта верхнего уровня

HG SDLC
├── Доступ и организация работы
├── Проекты и репозитории
├── Каталог сценариев / навыков / субагентов
├── Конструирование и отладка сценария
├── Запуски и расписания
├── Участие человека
├── Код, рабочее пространство и артефакты
├── Публикация результата
├── Интеграции и платформенные подключения
├── Наблюдаемость и аналитика
├── Установка и управление приложением
├── Оценка качества
└── AI-ассистент

Реестр функций

1. Доступ и организация работы

ID	Возможность	Статус	Паспорт
ACC-001	Аутентификация и сессия	Реализовано	Описание
ACC-002	Управление пользователями и командами	Реализовано	Описание

2. Проекты и репозитории

ID	Возможность	Статус	Паспорт
PRJ-001	Управление проектами и репозиториями	Реализовано	Описание
PRJ-002	Правила и публикационные шаблоны проекта	Реализовано	Описание

3. Каталог переиспользуемых компонентов

ID	Возможность	Статус	Паспорт
CAT-001	Каталог сценариев, навыков и субагентов	Реализовано	Описание
CAT-002	Версионирование и жизненный цикл каталога	Реализовано	Описание

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

4. Конструирование процессов

ID	Возможность	Статус	Паспорт
FLW-001	Визуальное и YAML-редактирование сценария	Реализовано	Описание
FLW-002	Валидация и отладочный запуск сценария	Реализовано	Описание

5. Выполнение процессов

ID	Возможность	Статус	Паспорт
RUN-001	Запуск сценария	Реализовано	Описание
RUN-002	Управление жизненным циклом запуска	Реализовано	Описание
RUN-003	Запуск по расписанию	Реализовано	Описание

Запуск сценария реализован; упрощённый интерфейс владельца продукта имеет экспериментальный статус. Подробнее — способы запуска.

6. Участие человека

ID	Возможность	Статус	Паспорт
HITL-001	Обработка точки участия человека	Реализовано	Описание
HITL-002	Ручная доработка (перехват управления)	Реализовано	Описание

7. Код и артефакты

ID	Возможность	Статус	Паспорт
ART-001	Рабочие файлы, изменения и артефакты запуска	Реализовано	Описание

8. Публикация

ID	Возможность	Статус	Паспорт
PUB-001	Согласование и публикация каталога	Реализовано	Описание
PUB-002	Публикация результата запуска	Реализовано	Описание

9. Интеграции

ID	Возможность	Статус	Паспорт
INT-001	External API и webhooks	Реализовано	Описание
INT-002	SCM, MCP и подключения ИИ-агентов	Реализовано	Описание

10. Наблюдаемость

ID	Возможность	Статус	Паспорт
OBS-001	Консоль запуска, аудит и диагностика	Реализовано	Описание
OBS-002	Состояние сервера и очистка рабочих файлов	Реализовано	Описание
OBS-003	Обзор состояния разработки	Реализовано	Описание
OBS-004	Аналитика команд и автономности проектов	Реализовано	Описание

11. Оценка качества

ID	Возможность	Статус	Паспорт
BEN-001	Сравнительные испытания	Экспериментально	Описание

12. AI-ассистент

ID	Возможность	Статус	Паспорт
AST-001	Контекстный чат и предложения изменений	Реализовано	Описание

13. Установка и управление приложением

ID	Возможность	Статус	Паспорт
OPS-001	Пользовательский CLI	Реализовано	Описание

Как связаны возможности

1. Администратор подключает SCM, ИИ-агента и при необходимости серверы MCP.
2. Пользователь создаёт проект и связывает его с одним или несколькими репозиториями.
3. Конфигуратор создаёт или выбирает сценарий, навыки и субагентов.
4. Оператор запускает сценарий вручную, по расписанию или через интеграцию.
5. Среда выполнения проходит шаги, фиксирует изменения и останавливается в точках участия человека, требующих ответа согласно режиму согласований.
6. Уполномоченный пользователь принимает результат, запрашивает доработку или перехватывает работу.
7. Платформа публикует ветки или запросы на слияние и сохраняет историю выполнения и решений.
8. Результаты видны в аналитике, используются внешними системами через события и API; экспериментальный раздел сравнительных испытаний позволяет сравнивать варианты на наборах задач.

Роли и права

Если нужной кнопки нет или действие недоступно, начните с проверки роли. В HG SDLC есть роли всей платформы и роли команды. Доступ также зависит от команды проекта и состояния запуска или точки участия человека.

Глобальные роли

ADMIN

Администратор платформы. Управляет пользователями и командами, настройками, ключами API, MCP/SCM-подключениями, каталогом, запусками, публикациями и сравнительными испытаниями.

FLOW_CONFIGURATOR

Оператор и конфигуратор платформы. Создаёт и публикует элементы каталога, управляет запусками, расписаниями, средой выполнения и сравнительными испытаниями. Управление пользователями и отдельные чувствительные операции, например секреты MCP и ключи API, остаются за ADMIN.

Командные роли

PRODUCT_OWNER

Работает с проектами своей команды. Может создавать проекты команды, просматривать каталог и запускать продуктовый сценарий «идея → разработка» через экспериментальный интерфейс владельца продукта. Не редактирует каталог, правила проекта и шаблоны публикации, не управляет запусками из технической консоли и не управляет расписаниями.

TEAM_MEMBER

Работает с проектами своей команды. Может просматривать и изменять доступные проекты, работать с запусками и точками участия человека в пределах команды. Не запускает продуктовый сценарий и не получает полномочия платформенного оператора.

TECH_APPROVER

Роль оставлена для совместимости. Для новых пользователей выбирайте действующие роли; право отвечать в точке участия человека зависит от текущих правил и доступа к проекту.

Матрица ключевых возможностей

Возможность	ADMIN	FLOW_CONFIGURATOR	PRODUCT_OWNER	TEAM_MEMBER
Просматривать глобальный каталог	Да	Да	Да	Да¹
Редактировать и публиковать каталог	Да	Да	Нет	Нет
Создавать проект	Да	Да	В своей команде	В своей команде
Просматривать проект и запуски	Все	Все	Своя команда	Своя команда
Редактировать правила проекта	Да	Да	Нет	В своей команде
Запускать из интерфейса владельца продукта (экспериментально)	Да	Да	В своей команде	Нет
Запускать и управлять через консоль запуска	Да	Да	Нет	В своей команде
Отвечать в точке участия человека	Да	Да	В своей команде	В своей команде
Управлять расписаниями	Да	Да	Нет	В своей команде
Использовать экспериментальный раздел сравнительных испытаний по прямой ссылке	Да	Да	Нет	Нет
Просматривать аналитику выбранных команд	Да	Да	Да, без ограничения своей командой	Да, без ограничения своей командой
Управлять пользователями и командами	Да	Нет	Нет	Нет
Редактировать MCP и ключи API	Да	Ограниченно²	Нет	Нет

¹ REST-каталог доступен аутентифицированным пользователям; отдельные UI-маршруты могут предоставлять более узкое представление.

² FLOW_CONFIGURATOR может редактировать обычные настройки среды выполнения, каталога и SCM, но управление MCP-конфигурацией с секретами и ключами API требует ADMIN.

Аналитика доступна четырём перечисленным ролям. Это исключение из обычного ограничения проектов по команде: текущий API аналитики фильтрует данные по параметрам запроса, без ограничения командой пользователя. В интерфейсе собственная команда лишь выбрана по умолчанию; подробнее в паспорте аналитики. Раздел сравнительных испытаний доступен только платформенным операторам по пути /benchmark в установленном приложении и отсутствует в основном меню.

Правила области видимости

• Глобальные операторы видят проекты, запуски, точки участия человека и расписания всех команд.
• Доступ командного пользователя к проектам, запускам и точкам участия человека ограничен своей командой. Аналитика и общий каталог имеют отдельные правила, описанные выше.
• Запрос объекта вне доступной команды возвращается как недоступный, чтобы не раскрывать его существование.
• Права на действие проверяются сервером; скрытие кнопки или маршрута в UI является дополнительной защитой, но не источником истины.

Проверка прав

Если ожидаемое действие недоступно, проверьте роль, команду проекта и состояние объекта. При обращении к администратору укажите версию приложения, раздел и действие.

Глоссарий HG SDLC

Для первого запуска достаточно трёх понятий: сценарий описывает процесс, запуск — его конкретное выполнение, а точка участия человека — шаг для получения данных или решения человека с учётом режима согласований. Остальные термины можно посмотреть здесь по мере работы.

Процесс и его участники

Термин	Что это значит
Сценарий	Версионированный граф процесса с допустимыми циклами: шаги, переходы, ожидаемые результаты, проверки и точки согласования.
Запуск	Один запуск сценария для проекта. В нём сохраняются параметры, версии компонентов, сведения о выполнении и результатах.
Контракт результата	Требования к результату шага: обязательные артефакты и ожидаемые изменения файлов. Проверки выполняются в предусмотренных для типа узла случаях.
Узел, шаг	Один шаг сценария: работа агента, выполнение команды, согласование или другой поддерживаемый тип. В интерфейсе может называться нодой.
Точка участия человека	Шаг сценария для получения решения или данных человека. Запуск ждёт ответа, если этого требует выбранный режим согласований.
Запрос данных у человека	Точка участия человека для получения недостающих данных.
Согласование с человеком	Точка участия человека для проверки результата: его можно принять или отправить на доработку.
Возврат на доработку	Возврат из точки участия человека или ИИ-узла на разрешённый шаг с корректирующей инструкцией. Маршруты задаются в сценарии; настройки определяют, сохранять или откатывать изменения рабочего пространства.
Ручная доработка (перехват управления)	Возможность самому исправить рабочие файлы в точке участия человека, а затем вернуть управление процессу.
ИИ-агент для разработки (coding agent)	Внешний агент, который читает инструкции и работает с кодом через настроенную среду выполнения.
Интерфейс владельца продукта	Экспериментальный интерфейс владельца продукта для запуска подготовленного процесса от описания задачи, просмотра хода работы, результатов и решений человека.
Платформенный оператор	Пользователь с ролью ADMIN или FLOW_CONFIGURATOR. Эти роли управляют процессами и каталогом; административные полномочия у них различаются.

Проект, каталог и файлы

Термин	Что это значит
Проект	Репозитории, правила и настройки публикации, объединённые одной задачей разработки и командой-владельцем.
Alias	Короткое имя репозитория, например main или backend. При запуске имена из сценария сопоставляются с репозиториями проекта.
Каталог	Общий реестр сценариев, навыков и субагентов, которые можно использовать в проектах.
Навык	Версия набора инструкций и дополнительных файлов для агента.
Субагент	Описание специализированного агента, например рецензента кода, которое AI-узел добавляет в контекст работы.
Рабочее пространство	Отдельная папка запуска с копиями выбранных репозиториев и служебными файлами. Сама по себе не изолирует процесс на уровне ОС.
Артефакт	Сохранённый результат шага: документ, данные или другой файл. Артефакты имеют версии и область run либо project.
Контрольная точка	Локальный снимок Git перед первым выполнением AI-узла. Используется для сравнения и отката; при доработке может использоваться повторно.
Изменения	Сравнение файлов с исходным состоянием или контрольной точкой.
Область	Для каталога team/organization задаёт владение и публикацию. Для артефактов run/project определяет использование результата. Область не заменяет проверку прав.

Подключения и публикация

Термин	Что это значит
SCM provider	Настроенное подключение к Git-хостингу и его API: чтение репозиториев, отправка веток и создание запроса на слияние.
MCP server	Сервер дополнительных инструментов агента. AI-узел ссылается на серверы в поле mcp_refs.
ACP	Agent Client Protocol: протокол общения платформы с агентом, в том числе для работы с сессией и выбора модели.
Среда выполнения	Часть платформы, которая запускает и координирует шаги сценария и процессы агента.
Переменная среды выполнения	Значение, подставляемое в инструкцию шага при выполнении: run.*, step[nodeId].* или env.*.
Предварительная проверка	Проверка доступности модели и параметров до запуска. Если нужна замена модели, её подтверждает пользователь.
Публикация каталога	Перевод проверенной версии сценария, навыка или субагента в состояние, доступное для рабочих запусков.
Публикация результата запуска	Отправка изменений в Git: в рабочую ветку, напрямую в выбранную ветку или через запрос на слияние.
Запрос на слияние (PR)	Запрос на включение изменений одной ветки в другую, созданный на Git-хостинге.

Сравнение и аналитика

Термин	Что это значит
Сравнительные испытания	Экспериментальный раздел для сравнения моделей и вариантов сценария на одинаковых задачах.
Набор испытаний	Задачи, варианты выполнения и параметры их оценки.
Ячейка испытаний	Результат одной пары «вариант × задача», включая запуск и оценку.
Оценщик	Способ оценки результата в сравнительных испытаниях; может быть отдельным сценарием.
Автономность	Показатели того, сколько участия человека предусмотрено и потребовалось в процессе. Раздел аналитики не задаёт разрешения агенту.

Как используются термины

Названия сценария, запуска, навыка, субагента и точки участия человека приведены на русском языке. В инструкциях «шаг» означает узел сценария, «рабочий каталог» — рабочее пространство, а «доработка» — возврат на доработку. Точные имена полей, команд и статусов выделяются как code.

Публикация каталога, публикация результата запуска и публикация этого справочника в GitVerse Pages — три разных действия. В соответствующих разделах всегда уточняется, что именно публикуется.

Ограничения и работа с данными

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

Связь с AI-Disrupt PDLC

HG SDLC позволяет команде сконфигурировать петли намерения и реализации через сценарий. Сквозная валидация (validation spine) и контроль (governance mesh) реализованы частично: доступны проверочные шаги, роли, точки участия человека и история решений. Полноценный пакет свидетельств проверки (evidence bundle), риск-адаптивные полномочия и контроль на всём пути требуют дальнейшей работы.

При подготовке сценария свяжите намерение и гипотезу с архитектурным решением, спецификацией, реализацией и проверками. Тогда ошибка проверки должна указывать, какое требование нарушено и куда вернуть работу. Это требование к устройству процесса; наличие журнала запуска само по себе не обеспечивает такую трассируемость. Для OpenSpec одним из инструментов связи требований и проверок может быть OpenFastTrace.

Выполняйте автоматические проверки там, где возникает проверяемый результат. В каждой точке участия человека определите проверяющего, критерии решения, блокируемое действие и путь эскалации разногласий — карту участия человека в принятии решений. Для решения нужны изменения, артефакты и результаты проверок; ответа агента «готово» недостаточно.

Оценка эффекта (outcome check) остаётся направлением развития. После развёртывания нужно вернуться к исходной гипотезе, настроить и измерить бизнес-метрики, а результаты вернуть в следующий цикл изменения. Технически принятое изменение и успешный запуск ещё не доказывают достижение бизнес-цели. Аналитика запусков помогает исследовать исполнение процесса, но не заменяет этот цикл.

Версии и повторяемость

Запуск сохраняет параметры запуска и версии компонентов. Повторное выполнение помогает воспроизвести условия, но ответы модели и состояние внешних сервисов могут измениться. Справочник ориентирован на релиз 2.2.0 с тегом v2.2.0; дата редакции указана на главной странице. Для сборки с изменениями после релиза сверяйте также тег или коммит, а доступность функции — с её требованиями к роли, настройкам и агенту.

Доступ к данным команд

Проекты, запуски и точки участия человека ограничиваются командой пользователя, кроме глобальных операторов. Аналитика имеет исключение: в текущем коде её API доступен четырём основным ролям и фильтрует данные по параметрам запроса без ограничения членством в команде. Собственная команда, выбранная в интерфейсе по умолчанию, не обеспечивает изоляцию аналитики. Учитывайте это при выборе состава пользователей общей установки; подробнее о правах.

Каталог также доступен аутентифицированным пользователям: область team определяет владение и публикацию, а не конфиденциальность карточки.

Агент и внешние сервисы

Агент выполняется с правами настроенного процесса. Раздельные рабочие каталоги запусков не заменяют изоляцию ОС или контейнера. Правила проекта являются инструкциями агенту; проверки изменений задаются отдельно контрактами и командами сценария.

Контекст задачи, исходный код и содержимое экранов могут передаваться настроенному агенту и поставщику модели. Маскирование известных полей секретов в интерфейсе и контексте ассистента не гарантирует удаления произвольных секретов из текста задачи, файлов и журналов. Настройте подключения и состав передаваемых данных под требования своей команды.

История и хранение файлов

В истории доступны состояния запуска, попытки узлов и решения в точках участия человека. Аудит не является записью каждого действия пользователя или агента. После очистки рабочего пространства история сохраняется, но просмотр и публикация удалённых файлов из этого рабочего пространства недоступны.

При публикации в несколько репозиториев возможен частичный успех. Проверяйте результат отдельно для каждого репозитория. Повтор публикации и принудительная публикация имеют разные условия применения; подробнее.

Экспериментальные возможности

Раздел сравнительных испытаний доступен платформенным операторам по пути /benchmark внутри установленного приложения и скрыт из основного меню. Его результаты зависят от выбранных задач, моделей и способа оценки.

Интерфейс владельца продукта — экспериментальный. Он сосредоточен на задаче, ходе выполнения, результатах и решениях человека и служит первым шагом от SDLC к PDLC. Форма запуска доступна по пути /product-pipeline; роли и условия запуска сохраняются.

Направления развития

Следующие направления описаны в статье от 25 августа 2026 года. Они задают дальнейшую работу и не означают, что перечисленные возможности уже доступны как готовые функции.

• Цифровые сотрудники. Объединить несколько AI-сценариев в рабочую роль с единой точкой входа, которая выбирает подходящий сценарий по задаче. Первые эксперименты используют текущие расписания и MCP для одного-двух сценариев, например ревью или исправления ошибок. Пример такой сборки: прочитать назначенные задачи из Jira, выполнить работу, создать PR и перевести задачу в ожидание ревью человеком. Удобная целостная роль остаётся целью развития.
• Управление контекстом. Подготавливать для каждого этапа нужные знания о продуктах, системах, репозиториях, контрактах и владельцах. Граф знаний или другая структурированная модель должны учитывать актуальность, происхождение, область применимости и права доступа (Context Supply Chain). Само подключение источника через MCP не решает эту задачу; увеличение объёма документов в контексте может мешать работе.
• Улучшение процессов по истории запусков. Анализировать повторяющиеся причины возвратов на доработку и перехватов управления, предлагать изменения инструкций, навыков и последовательности шагов. Человек принимает или отклоняет предложение. Замечание человека — сигнал, требующий проверки: требования могли измениться, а исправление может отражать личное предпочтение. Снижение числа возвратов за счёт ослабления проверок не является улучшением; критерии качества и границы риска должны сохраняться.
• Согласование несколькими людьми. Добавить точку участия человека с обязательным одобрением нескольких участников.

Накопленные знания о продукте и системе должны сохраняться при смене моделей и инструментов. В перспективе результаты проверки бизнес-гипотез смогут дополнять историю исполнения и помогать следующему циклу намерения; владельцем решения о цели остаётся человек.

Как читать адреса в справочнике

Пути интерфейса вроде /settings и /run-console относятся к вашей установке HG SDLC, а не к сайту документации. Технические руководства и исходники открываются в репозитории GitVerse и требуют доступа к сети. Описания функций внутри справочника доступны через его меню и поиск.

Установка и первый вход

Если команда уже развернула HG SDLC, получите адрес и учётную запись у администратора и переходите к первому процессу. GitVerse Pages размещает этот справочник; само приложение запускается отдельно.

Выберите способ установки

Способ	Когда использовать	Что потребуется
Из исходников	Для знакомства и разработки	Git, Java 21, Node.js 22 из .nvmrc, npm; Docker Compose для PostgreSQL
CLI	Для запуска готовой JAR без сборки	Java 21+, Node.js 18+ и npm, адрес сервера дистрибуции от администратора
Docker Compose	Для подготовленной серверной установки	Образы приложения, конфигурация БД и учётные данные агента

Ниже пройдём локальную установку из исходников на Linux, macOS или Windows с WSL. Для работы AI-узлов дополнительно установите и авторизуйте выбранного агента на машине backend.

1. Получите исходники

git clone https://gitverse.ru/kakvsbere/hgsdlc.git
cd hgsdlc

2. Запустите PostgreSQL

Из корня репозитория:

docker compose -f deploy/compose.dev.yaml up -d
docker compose -f deploy/compose.dev.yaml ps

Локальная конфигурация использует localhost:5432, базу и пользователя hgsdlc, пароль hgsdlc. Это параметры разработки. Дождитесь готовности контейнера.

3. Запустите backend

Из корня репозитория:

cd backend
SPRING_PROFILES_ACTIVE=local,postgres ./gradlew bootRun

Оставьте терминал открытым. Проверьте, что Gradle использует Java 21. Миграции БД применяются при старте приложения.

4. Запустите интерфейс

Во втором терминале, из корня репозитория:

cd frontend
npm ci
npm run dev

Откройте адрес, показанный Vite; по умолчанию это http://localhost:5173.

5. Проверьте установку

В третьем терминале:

curl -fsS http://localhost:8080/actuator/health

Ожидается status: UP в JSON-ответе. Войдите в интерфейс как admin с паролем admin. Эти данные предназначены только для локальной разработки; в общей установке используйте персональные учётные записи.

Пустые списки проектов и запусков нормальны для новой установки. Далее настройте агента, каталог и первый проект.

Если приложение не запускается

Признак	Что проверить
Ошибка подключения к БД	Готовность контейнера, доступность порта 5432 и профиль local,postgres
Ошибка версии Java	Вывод java -version и выбранную Java 21
Интерфейс открыт, запросы завершаются ошибкой	Журнал backend и ответ /actuator/health на порту 8080
Порт интерфейса занят	Фактический адрес в выводе Vite
Модели отсутствуют	Установку, авторизацию и настройки агента на машине backend

Остановка

Остановите backend и интерфейс сочетанием Ctrl+C. Затем из корня репозитория остановите PostgreSQL:

docker compose -f deploy/compose.dev.yaml down

Данные PostgreSQL остаются в томе. Для краткой проверки возможен режим H2, но его данные в памяти не сохраняются после остановки backend.

Первый процесс: от задачи до ветки в Git

Цель — добавить небольшой файл в тестовый репозиторий, пройти согласование и увидеть результат в Git. Начните с работающей установки. Первичную настройку выполняет ADMIN или FLOW_CONFIGURATOR; создание пользователей и команд доступно ADMIN.

1. Настройте агента

Установите CLI или ACP-адаптер выбранного ИИ-агента и авторизуйте его от имени того пользователя ОС, который запускает backend. В Settings → Runtime выберите агента, загрузите его настройки по умолчанию и сохраните их. Проверьте получение списка моделей.

Поддерживаемые агенты: Qwen, Claude, GigaCode, Codex и OpenCode. Выбор агента в интерфейсе не устанавливает и не авторизует его автоматически. Подробные команды подключения приведены в руководстве по агентам.

2. Подключите SCM и каталог

В настройках Git/SCM добавьте провайдера для своего Git-хостинга. Для GitVerse используется совместимый тип Gitea/GitVerse. Учётные данные должны разрешать чтение репозитория и отправку тестовой ветки; храните их в настройках подключения, а не в URL репозитория.

В Settings → Catalog укажите тестовый каталог и ветку для выбранного агента:

Агент	Ветка каталога
Qwen	qwen
Claude	claude
GigaCode	gigacode
Codex	codex
OpenCode	opencode

Сохраните настройки, выполните импорт/восстановление каталога и проверьте, что появились сценарии, навыки и субагенты. Выберите опубликованный проверочный сценарий, совместимый с вашим агентом. Название и состав примера зависят от ветки каталога.

3. Создайте проект

1. Создайте или выберите команду, затем откройте Projects и создайте проект этой команды.
2. Добавьте тестовый Git-репозиторий, в который у вас есть право отправлять изменения.
3. Задайте ему alias main и существующую исходную ветку — например, main, если она так называется в вашем репозитории.
4. Выберите соответствующее SCM-подключение.
5. Добавьте правила проекта: команды проверки, требования к стилю и ограничения на файлы с секретами.

Правила передаются агенту как инструкции. Для обязательных проверок используйте команды и контракты сценария; текст правил сам по себе не гарантирует их соблюдение.

4. Запустите сценарий

В технической форме запуска выберите проект и опубликованный проверочный сценарий. Этот учебный сценарий предназначен для платформенного оператора или участника команды с правами технического запуска. Для PRODUCT_OWNER предусмотрен отдельный порядок запуска через интерфейс владельца продукта: эта форма не позволяет выбрать require_all_gates и пропускает точки участия человека без PRODUCT_OWNER в allowed_roles.

Сопоставьте aliases сценария с репозиториями проекта. Выберите исходную ветку и новую рабочую ветку, например hgsdlc/hello-01; для повторного опыта используйте другое свободное имя. Выберите модель из списка, режим публикации Ветка и режим согласований require_all_gates, чтобы процесс ожидал ответа в каждой точке участия человека.

Введите задачу:

Добавь небольшой текстовый файл hello-hgsdlc.md с описанием проекта и проверь его наличие командой.

Запустите процесс. Если проверка модели предлагает замену, изучите её и подтвердите подходящий вариант либо исправьте настройки агента.

5. Проверьте результат и примите решение

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

Маршрут зависит от выбранного сценария: состав точек согласования определяется его графом. После успешного выполнения и публикации откройте рабочую ветку в Git-хостинге и проверьте наличие hello-hgsdlc.md. В режиме «Ветка» запрос на слияние автоматически не создаётся.

Если процесс остановился

Ситуация	Следующий шаг
Проверочный сценарий отсутствует	Проверьте импорт, статус published и совпадение ветки каталога с агентом
Модель недоступна	Проверьте среду выполнения и авторизацию агента на машине backend
Не найден навык или субагент	Проверьте импорт зависимостей и валидацию сценария
Запуск ждёт человека	Откройте текущую точку участия человека в консоли запуска или входящих согласованиях
Команда или проверка артефакта завершилась ошибкой	Прочитайте stdout/stderr и диагностику узла; исправьте причину до повтора
Push не выполнен	Проверьте права SCM, рабочую ветку и статус публикации; при PUBLISH_FAILED повторите публикацию после исправления причины

Далее: управление выполнением, публикация результата, подробная диагностика.

Путь: управляемая разработка

После первого запуска попробуйте пройти процесс на своей задаче: выберите подготовленный сценарий, проследите за изменениями и проверьте результат на согласовании.

Кто участвует

PRODUCT_OWNER запускает экспериментальный интерфейс владельца продукта для своей команды. ADMIN, FLOW_CONFIGURATOR и TEAM_MEMBER с доступом к проекту используют техническую форму запуска. Агент выполняет AI-шаги, а человек отвечает в точке участия человека в пределах своих прав.

Интерфейс владельца продукта использует require_po_gates_only и публикацию в ветку (branch). Он ждёт ответа только в точке участия человека с PRODUCT_OWNER в allowed_roles; остальные точки участия человека, в том числе без списка ролей, пропускаются. Проверьте настройки нужных согласований перед запуском. Если требуется пройти все точки участия человека, запуск выполняет уполномоченный пользователь через техническую форму с require_all_gates.

Пройдите процесс

1. Выберите проект, сценарий и опишите проверяемый результат задачи. В технической форме дополнительно задайте репозитории, ветки, модель и режим публикации; для проверки всех точек участия человека выберите require_all_gates. В интерфейсе владельца продукта действуют фиксированные режимы, описанные выше.
2. При техническом запуске дождитесь предварительной проверки модели: подтвердите предложенную замену либо исправьте настройки. Если интерфейс владельца продукта не может запустить задачу, изучите ошибку и привлеките участника с правами настройки.
3. Откройте созданный запуск. Платформа сохранит параметры и подготовит рабочие файлы, правила проекта и компоненты каталога.
4. Следите за графом и журналом. Перед первым выполнением AI-узла сохраняется контрольная точка, после шага проверяются ожидаемые изменения и артефакты.
5. Когда процесс дойдёт до точки участия человека, изучите изменения и ответьте на запрос. Можно принять результат, дополнить данные, попросить доработку или исправить файлы вручную.
6. После успешного завершения графа проверьте публикацию. Для новых запусков результат отправляется в Git согласно выбранному режиму; статус виден отдельно для каждого репозитория.

Пример: от спецификации до публикации

Рассмотрим задачу «добавить кнопку „Версия“». Подготовьте сценарий на основе своего SDD-процесса, например OpenSpec или Spec Kit. Это пример устройства сценария, а не гарантированно установленный шаблон каталога.

Шаг	Что выполняется и передаётся дальше
Подготовка спецификации — ИИ-узел	Агент изучает требования и код, описывает расположение кнопки, затронутые API и SDK, совместимость и критерии проверки. Спецификация становится входом для реализации.
Согласование спецификации — Согласование с человеком	Человек проверяет границы задачи, решения и критерии приёмки. Замечания возвращают работу к подготовке спецификации.
Код и тесты — ИИ-узел	Агент реализует согласованное изменение, обновляет тесты и при необходимости миграции, сохраняет материалы для проверки.
Автоматические проверки — Командный узел	Выполняются сборка, тесты и настроенные проверки безопасности. При ошибке процесс возвращается к исправлению и повторной проверке; у цикла есть условие выхода и лимит повторов.
Приёмка — Согласование с человеком	Человек получает изменения, артефакты и результаты проверок, затем принимает работу или возвращает её на соответствующий шаг.
Завершение и публикация	Успешный Terminal завершает маршрут, затем платформа публикует изменения в выбранном режиме — например, в ветке или PR.

Этап разработки может включать несколько AI-узлов, командные проверки и согласование. Узел графа не равен целому этапу производственного процесса. Если не хватает исходных данных или выбора человека, добавьте запрос данных у человека в нужной точке. Снимок графа, попытки, артефакты и решения остаются в истории конкретного запуска.

Задайте допустимые маршруты возврата из точки участия человека и ИИ-узлов: дефект кода возвращает к реализации, неверное предположение в требованиях — к спецификации. Изменение требований должно оставаться видимым в согласованных материалах. Решение о снятии точек контроля принимайте после отладки сценария на реальных задачах и оценки пользы и риска; по её результатам согласования может потребоваться сохранить.

Как дать полезное замечание

Вместо «сделай лучше» укажите, что именно нужно изменить и как проверить исправление. Например: «В сообщении об ошибке назови отсутствующее поле и добавь тест для пустого значения». При доработке с откатом учитывайте, что изменения после выбранной контрольной точки будут удалены.

Откат рабочего пространства не отменяет внешние действия: уже отправленные уведомления, публикации и изменения других систем могут потребовать отдельного восстановления. Если нужно исправить результат самому, используйте Перехват управления: временно примите роль исполнителя в IDE или встроенном редакторе, проверьте правки и верните управление процессу.

Если выполнение остановилось

Что вы видите	Что сделать
Запрос данных у человека	Передайте недостающие данные.
Согласование с человеком	Проверьте результат и примите его либо отправьте замечания.
Ошибка шага	Прочитайте журнал и устраните причину; повторите шаг, если действие доступно.
CRASHED после перезапуска backend	Откройте карточку и выберите Восстановить, если рабочий каталог не очищен.
PUBLISH_FAILED	Исправьте причину сбоя отправки в Git и повторите публикацию.

История запуска сохраняет состояния, попытки шагов и решения в точках участия человека. Файлы доступны, пока рабочий каталог не очищен. Для старых запусков в режиме local результат остаётся только в нём.

Подробнее

• Запуск сценария
• Жизненный цикл запуска
• Обработка точки участия человека
• Ручная доработка (перехват управления)
• Рабочее пространство, код и артефакты
• Публикация результата

Путь: публикация результата

Когда изменения проверены, убедитесь, что они попали в Git. Успешное выполнение шагов и успешная публикация — отдельные этапы: например, агент может закончить задачу, а Git-сервер отклонить отправку ветки.

Перед началом

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

Выберите результат

Режим	Что появится в Git
Ветка (branch)	Отдельная рабочая ветка с изменениями.
Прямая отправка (direct_push)	Изменения непосредственно в выбранной ветке.
Запрос на слияние (pr)	Рабочая ветка и запрос на её включение в целевую ветку, если SCM поддерживает создание PR.

Для первого опыта удобно использовать «Ветку» и тестовый репозиторий. Отладка сценария также использует branch. Режим local оставлен для старых запусков и не предлагается для новых обычных запусков.

Проверьте публикацию

1. Откройте консоль запуска и посмотрите статус публикации каждого репозитория.
2. При успехе перейдите в Git-хостинг: проверьте ветку, коммиты и, для режима PR, созданный запрос на слияние.
3. Если настроены исходящие webhooks, проверьте историю доставки уведомления внешней системе.
4. Если публикация не удалась, прочитайте ошибку. Частые причины — права доступа, недоступность SCM, конфликт веток или запрет отправки на стороне Git-сервера.
5. Исправьте причину и используйте повтор публикации для запуска в PUBLISH_FAILED. Повторно выполнять шаги сценария для этого не нужно.

Ошибка публикации сама по себе не удаляет рабочие файлы, но позже их может удалить настроенная очистка. После очистки отправить эти файлы из запуска уже нельзя. При работе с несколькими репозиториями проверяйте каждый: часть изменений могла успешно уйти в Git до сбоя.

Отправка ветки или создание запроса на слияние не означают слияние изменений и выпуск продукта. Проверки, слияние и развёртывание выполняются по правилам целевого репозитория.

Если сам запуск завершился с ошибкой

Принудительная публикация — отдельное действие для отправки уже выполненной работы из FAILED. Оно доступно только при выполнении серверных условий. Перед отправкой проверьте изменения: завершение сценария с ошибкой не подтверждает готовность результата. Условия принудительной публикации описаны отдельно.

Подробнее

• Публикация результата запуска
• Платформенные подключения
• External API и webhooks
• Консоль запуска и аудит

Пользовательские пути

Выберите сценарий по своей задаче: подготовить первый запуск, управлять выполнением или опубликовать проверенные изменения.

Путь	Основной актор	Результат
Первый проект	Администратор / конфигуратор	Первый сценарий выполнен, результат опубликован в тестовую ветку.
Управляемая разработка	Оператор / участник команды	Coding agent выполнил сценарий под контролем человека.
Публикация результата	Оператор / согласующий	Принятые изменения опубликованы в Git/SCM.

Аутентификация и сессия

Войдите под своей учётной записью, чтобы работать с проектами и запусками. Назначенные вам роли определяют доступные действия, а команда — доступ к проектам.

Кому доступно

Вход нужен всем, кто работает через интерфейс платформы. Внешние системы используют ключи API и описаны в External API и webhooks.

Перед началом

• Учётная запись активна и имеет пароль.
• Пользователь отправляет логин и пароль на странице входа.

Как это работает

1. Откройте страницу входа и введите логин и пароль.
2. После входа HG SDLC загрузит ваш профиль и доступные разделы.
3. Работайте с проектами: права проверяются сервером при каждом запросе.
4. Когда закончите, выйдите из учётной записи. Токен сессии станет недействительным.

Что учесть

• Неверные данные не раскрывают, существует ли пользователь.
• Истёкший или недействительный токен приводит к повторной аутентификации.
• Неактивная учётная запись не получает новую сессию.

Параметры и результат

• Параметры: имя пользователя и пароль.
• Результат: токен сессии и профиль текущего пользователя с ролями и областью команды.

Права

Вход не требует активной сессии. Все продуктовые функции, кроме проверок состояния/версии и отдельно защищённых интеграционных запросов, требуют аутентификации.

Где найти

• В приложении: /login.

Подробнее

• Роли и права
• Управление пользователями и командами

Управление пользователями и командами

Здесь администратор собирает команду: создаёт учётные записи, назначает роли и выбирает, с какими проектами будет работать каждый участник.

Кому доступно

• ADMIN управляет пользователями и командами.
• Остальные роли используют назначенные им полномочия и видят только доступные команды.

Перед началом

• Администратор аутентифицирован.
• Для назначения командной роли существует активная команда.

Как это работает

1. Создайте команду или выберите существующую.
2. Добавьте пользователя: укажите имя, пароль и роль.
3. Для командной роли выберите команду, к которой он относится.
4. Если полномочия изменились, обновите профиль. При необходимости сбросьте пароль или отключите учётную запись.
5. Проверьте назначенные роли: они определяют доступ к последующим действиям.

Что учесть

• Нельзя назначить командную роль без доступной команды.
• Нельзя получить доступ к проекту другой команды только через знание его ID.
• Удаление или деактивация пользователя не удаляет созданные им аудиторские записи.

Параметры и результат

• Параметры: данные пользователя или команды, глобальная или командная роль, ID команды.
• Результат: учётные записи и роли, по которым платформа проверяет доступ.

Права

Управление пользователями и административный реестр команд доступны только ADMIN. Обычный пользователь может получить список команд в пределах своей области.

Где найти

• В приложении: /users.

Подробнее

• Аутентификация
• Управление проектами
• Матрица ролей

Управление проектами и репозиториями

Начните с проекта: укажите команду и подключите репозитории, с которыми будет работать агент. В одном проекте можно объединить несколько репозиториев — например, backend и frontend.

Кому доступно

• ADMIN и FLOW_CONFIGURATOR работают со всеми проектами.
• PRODUCT_OWNER и TEAM_MEMBER работают с проектами своей команды.

Перед началом

• Существует команда-владелец проекта.
• Для удалённых репозиториев настроен подходящее SCM-подключение.
• Пользователь создаёт или открывает проект.

Как это работает

1. Укажите название проекта и команду-владельца.
2. Добавьте один или несколько Git-репозиториев.
3. Для каждого задайте короткое уникальное имя — alias — и исходную ветку по умолчанию.
4. Выберите SCM-подключение к тому же Git-хостингу.
5. Сохраните проект. При запуске сценария вы сможете выбрать нужные репозитории, сопоставить их с именами в сценарии и уточнить ветки.

Что учесть

• Повторяющийся alias отклоняется.
• Хост репозитория должен соответствовать выбранному SCM-подключению.
• Проект можно архивировать, исключив его из новых рабочих сценариев.
• Физическое удаление применяется только когда разрешено текущими ограничениями данных.

Параметры и результат

• Параметры: имя, ID команды, репозитории, SCM-подключение и описание проекта.
• Результат: проект с устойчивым ID, областью доступа и настройками репозиториев.

Права

Командные пользователи создают проекты только в собственной команде. Изменить команду существующего проекта может только ADMIN.

Где найти

• В приложении: /projects.

Подробнее

• Настройки проекта
• Запуск сценария
• Платформенные подключения
• Мультирепозиторная модель описана в описании выпуска 2.0.

Правила и публикационные шаблоны проекта

Запишите правила, которые агенту важно знать о вашем проекте: как собрать код, какие проверки запустить и какого стиля придерживаться. Здесь же задаются шаблоны сообщений коммитов и запросов на слияние.

Агент получает правила как инструкции. Если условие нужно проверять обязательно, добавьте соответствующую команду или контракт в сценарий.

Кому доступно

• Платформенные операторы настраивают все параметры.
• TEAM_MEMBER может редактировать правила проекта своей команды.
• PRODUCT_OWNER просматривает проект, но не редактирует правила и шаблоны публикации.

Перед началом

• Проект существует и доступен пользователю.
• Пользователь открывает настройки проекта.

Как это работает

1. Откройте настройки проекта и выберите шаблон правил для вашего агента либо напишите правила сами.
2. Укажите команды сборки и проверки, особенности структуры проекта и требования к изменениям.
3. Сохраните правила и настройте шаблоны коммитов и запросов на слияние.
4. Создайте новый запуск, чтобы проверить настройки. Он получит их снимок; уже созданные запуски сохранят прежние значения.

Что учесть

• Неподдерживаемый тип агента для шаблона правил отклоняется.
• Пустые правила допустимы, если сценарий и политика проекта не требуют их наличия.
• Настройки фиксируются при создании запуска. После изменения правил проверьте их в новом запуске.

Параметры и результат

• Параметры: текст правил и тип агента, шаблоны публикации.
• Результат: сохранённый проектный контекст для новых запусков.

Права

Редактирование правил недоступно PRODUCT_OWNER. Редактирование шаблонов публикации доступно платформенным операторам и разрешённым участникам команды, кроме PRODUCT_OWNER.

Где найти

• В приложении: /projects/{projectId}/settings.

Автономность оценивается отдельно в разделе Аналитика. Это метрики участия человека и выполнения сценария; настройки допустимого уровня автономности на этой странице нет.

Подробнее

• Рабочее пространство, код и артефакты
• Публикация результата
• Подготовка рабочего пространства
• Технический дизайн подготовки рабочего пространства

Каталог сценариев, навыков и субагентов

В каталоге хранятся сценарии, инструкции навыков и описания специализированных субагентов. Подготовьте их один раз и используйте в разных проектах.

Состав каталога

Сущность	Назначение
Сценарий	Определяет граф процесса разработки: шаги, переходы, запросы данных, согласования и требования к результату — обязательные артефакты и ожидаемые изменения файлов (контракты результата).
Навык	Содержит инструкции и дополнительные файлы для агента.
Субагент	Описывает специализированного вспомогательного агента для AI-узла.

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

Области каталога

• team — сущность принадлежит команде, требует кода команды и может публиковаться платформенным оператором напрямую.
• organization — общий каталог организации, публикация проходит согласование.

Область каталога определяет владение и канал публикации. Она не скрывает карточку от других команд: чтение каталога доступно аутентифицированным пользователям, с учётом ограничений UI. Область артефактов run/project имеет другое назначение.

Кому доступно

• Все пользователи, вошедшие в систему, могут получать доступный каталог через API.
• ADMIN, FLOW_CONFIGURATOR и PRODUCT_OWNER просматривают карточки каталога в UI.
• Редактирование доступно ADMIN и FLOW_CONFIGURATOR.

Как это работает

1. Найдите нужный сценарий, навык или субагента по имени, тегам или статусу.
2. Откройте карточку и выберите версию.
3. Если у вас есть права редактора, создайте черновик новой сущности или версии.
4. Добавьте содержимое: граф или YAML для сценария, инструкции и файлы для навыка, описание роли для субагента.
5. Проверьте зависимости сценария от навыков, субагентов и серверов MCP.
6. Опубликуйте проверенную версию, чтобы использовать её в рабочих запусках.

Что учесть

• Ссылка на отсутствующую или недоступную версию отклоняется валидацией.
• Черновик нельзя использовать как обычную опубликованную зависимость, кроме специально выделенного debug-сценария.
• Устаревшая версия сохраняется для истории, но не рекомендуется для новых запусков.

Параметры и результат

• Параметры: описание, версия, теги, содержимое и ссылки на зависимости.
• Результат: версия элемента каталога, на которую можно сослаться из сценария или запуска.

Где найти

• В приложении: /flows, /skills, /subagents и страницы соответствующих редакторов.

Подробнее

• Версионирование каталога
• Редактирование сценария
• Подготовка рабочего пространства

Версионирование и жизненный цикл каталога

Редактируйте новую версию в черновике, проверяйте её и только затем публикуйте. Уже созданные запуски сохраняют свои версии компонентов. Это помогает понять, что именно выполнялось, хотя ответ модели при повторном запуске может отличаться.

Кому доступно

ADMIN и FLOW_CONFIGURATOR создают версии, редактируют черновики и помечают версии устаревшими, отправляют и обрабатывают публикацию.

Как это работает

1. Создайте черновик новой сущности или версии.
2. Внесите изменения и проверьте их. Уже созданные запуски от этого не изменятся.
3. Отправьте версию на публикацию: для team оператор может опубликовать её напрямую, для organization требуется согласование.
4. После успешной публикации выбирайте новую версию при запуске. Синхронизация с Git-каталогом зависит от настроек.
5. Если версия больше не подходит для новых задач, пометьте её устаревшей (deprecated). История сохранится.

Что учесть

• Черновик можно удалить, если он ещё не стал опубликованной версией.
• Отклонение сохраняет причину и позволяет исправить новую версию.
• Сбой задания публикации можно повторить без создания дублирующей публикации.
• Параллельные решения и повторные задания защищены от двойного выполнения.

Параметры и результат

• Параметры: постоянный ID, семантическая версия, содержимое и данные публикации.
• Результат: версия сущности со статусами жизненного цикла, согласования и публикации.

Права

Просмотр каталога шире, чем его изменение. Сохранение, удаление черновика, пометка версии устаревшей и решения о публикации требуют роли платформенного оператора.

Где найти

• В приложении: редакторы каталога и /requests.

Подробнее

• Каталог
• Публикация каталога

Визуальное и YAML-редактирование сценария

Соберите процесс разработки из шагов: поручите агенту изменить код, добавьте команду проверки и согласование человеком. С графом можно работать визуально или в YAML — это два представления одного сценария.

Кому доступно

• ADMIN и FLOW_CONFIGURATOR создают и изменяют сценарии.
• PRODUCT_OWNER может просматривать доступный сценарий без сохранения изменений.

Как это работает

1. Создайте сценарий или откройте черновую версию.
2. Добавьте шаги из библиотеки и соедините их переходами.
3. Для AI-узла задайте инструкцию, модель, навык, субагента, ссылки MCP, ожидаемые артефакты и изменения.
4. Добавьте согласования, команды проверки и ветвления по результату.
5. Переключайтесь между графом и YAML — редактор синхронизирует оба представления.
6. Исправьте найденные ошибки и сохраните черновик.
7. Проверьте сценарий в отладке, затем опубликуйте его версию.

Существенные правила

• ID узлов уникальны внутри сценария.
• Переходы должны ссылаться на существующие шаги.
• Циклы ограничиваются max_loop_count.
• В сценарии для нескольких репозиториев используются короткие имена (aliases). При запуске сопоставьте их с репозиториями проекта.
• Ссылки на навык, субагента и MCP должны разрешаться в допустимые версии/настройки.

Для обязательной остановки при отсутствии результата включите fail_on_missing_declared_output и fail_on_missing_expected_mutation в настройках сценария. В начальной форме нового сценария оба переключателя выключены; required: true у артефакта или изменения не заменяет эти настройки. expected_mutations описывает ожидаемые изменения и не запрещает изменения других файлов; подробнее о валидации.

Что учесть

• Несогласованный YAML и граф не сохраняются как валидный сценарий.
• Ошибки схемы, переходов и контрактов отображаются до запуска.
• Несохранённый черновик может быть потерян при закрытии или перезагрузке страницы; сохраняйте изменения перед выходом.

Параметры и результат

• Параметры: описание сценария, граф/YAML, настройки узлов и ссылки на каталог.
• Результат: сохранённая черновая версия, готовая к отладке или публикации.

Где найти

• В приложении: /flows/create, /flows/{flowId}.

Подробнее

• Каталог
• Валидация и отладка
• Переменные среды выполнения
• Валидация узла

Валидация и отладочный запуск сценария

Проверьте черновик сценария на тестовом проекте до публикации. Вы увидите, как проходят шаги, где появляются ошибки и что меняется в коде. Учитывайте, что отладочный запуск тоже может отправлять изменения в Git.

Кому доступно

ADMIN и FLOW_CONFIGURATOR.

Перед началом

• В редакторе есть черновик сценария.
• Выбран доступный проект и введены требуемые переменные окружения и текст задачи.
• Пользователь нажимает «Отладочный запуск».

Как это работает

1. Откройте черновик в редакторе, выберите тестовый проект и укажите задачу и нужные переменные.
2. Нажмите «Отладочный запуск». Платформа проверит YAML, граф, зависимости и контракты.
3. При успешной проверке появится запуск с debug_mode и источником flow_debugger. Сервер выберет режим публикации в ветку и назначит рабочую ветку отладки.
4. Следите за графом, журналом и изменениями кода; отвечайте в точке участия человека по мере выполнения.
5. При ошибке прочитайте диагностику. Повтор шага и восстановление запуска доступны только в подходящем состоянии.
6. После проверки вернитесь в редактор и отдельно опубликуйте версию сценария.

Что учесть

• Ошибка схемы блокирует создание запуска.
• Если модель или зависимость каталога недоступна, предварительная проверка или запуск завершается ошибкой. Прочитайте её сообщение и проверьте настройки модели или ссылки на каталог.
• Если ошибка не допускает повтор, действие повтора узла недоступно.
• Debug-ветка может быть перезаписана повторным debug-выполнением по правилам режима.

Параметры и результат

• Параметры: черновик сценария, проект, текст задачи, переменные окружения и выбор модели.
• Результат: отдельный отладочный запуск и диагностические данные; опубликованная версия сценария автоматически не создаётся.

Где найти

• В приложении: /flow-debug?flowId=...&runId=....

Подробнее

• Редактирование сценария
• Запуск сценария
• Консоль запуска и аудит
• Валидация узла
• Возможности отладки сценария описаны в описании выпуска 2.1.

Запуск сценария

Выберите задачу, проект и сценарий — HG SDLC создаст отдельный запуск. В нём сохраняются параметры, выбранные версии компонентов, репозитории и модель, чтобы потом можно было разобраться в результате.

Как можно запустить сценарий

Откуда запускается	Кому доступно
Консоль запуска	ADMIN, FLOW_CONFIGURATOR, TEAM_MEMBER в своей команде
Интерфейс владельца продукта (экспериментально)	ADMIN, FLOW_CONFIGURATOR, PRODUCT_OWNER своей команды
Schedule	Планировщик от имени пользователя или политики, задавших расписание
External API	Внешняя система с ключом API
Сравнительные испытания	Платформенный оператор
Отладка сценария	ADMIN, FLOW_CONFIGURATOR

Интерфейс владельца продукта — экспериментальный и упрощённый. В центре находятся задача, ход выполнения, результаты и решения человека; техническая конфигурация графа остаётся в редакторе сценария.

Перед началом

• Проект активен и содержит выбранные репозитории.
• Версия сценария допустима для выбранного типа запуска.
• ИИ-агент и требуемая модель доступны либо подтверждена корректная замена.

Как это работает

Следующие шаги относятся к технической форме запуска для ADMIN, FLOW_CONFIGURATOR и TEAM_MEMBER с доступом к проекту. Для интерфейса владельца продукта используйте отдельный порядок ниже.

1. Выберите проект, опубликованный сценарий и опишите задачу.
2. Задайте нужные переменные окружения и режимы AI-сессии и публикации. Выберите режим согласований: require_all_gates, require_po_gates_only или skip_all_gates. Для проверки всех точек участия человека человеком используйте require_all_gates.
3. Выберите репозитории, сопоставьте их имена (aliases) со сценарием и укажите ветки. При необходимости добавьте исходящие webhooks.
4. Выберите модель. Если она недоступна, изучите предложенную замену либо исправьте настройки агента.
5. Запустите процесс. HG SDLC проверит права, зависимости и параметры, сохранит их в запуске и подготовит рабочие каталоги.
6. Перейдите к консоли запуска, чтобы следить за шагами и отвечать на согласования.

Запуск через интерфейс владельца продукта

1. Выберите проект своей команды, подготовленный сценарий и опишите задачу.
2. До запуска убедитесь, что у точек участия человека, на которых нужен ответ владельца продукта, в allowed_roles указан PRODUCT_OWNER.
3. Запустите процесс и следите за результатами и запросами участия человека.

Интерфейс владельца продукта фиксирует gate_mode=require_po_gates_only и publish_mode=branch: выбора режима всех согласований или публикации PR в этой форме нет. Точки участия человека без PRODUCT_OWNER в allowed_roles, включая точки участия человека без списка ролей, проходят автоматически. Наличие точки участия человека в графе не гарантирует остановку. Если нужны ответы на все точки участия человека, уполномоченный пользователь должен выполнить запуск через техническую форму с require_all_gates.

Что учесть

• Недоступная модель требует явного подтверждения предложенных замен либо блокирует запуск.
• Несогласованные aliases проекта и сценария отклоняются.
• Если рабочая ветка занята, выберите свободную ветку или завершите блокирующий запуск.
• Повторный запуск завершённого запуска открывает форму с сохранёнными параметрами и предупреждает о недоступных зависимостях.

Параметры и результат

• Параметры: проект, версия сценария, текст задачи, переменные, репозитории, режимы, webhooks и модель.
• Результат: ID запуска, источник запуска, сохранённые параметры и начальный статус.

Где найти

• В приложении: /run-launch, /product-pipeline, действие «Повторить запуск» в консоли запуска.

Подробнее

• Жизненный цикл запуска
• Расписания
• External API
• Жизненный цикл запуска
• Подготовка рабочего пространства
• Выбор модели и повторный запуск описаны в описании выпуска 2.1.

Управление жизненным циклом запуска

В карточке запуска видно, что выполняется сейчас и требуется ли ваше участие. Отсюда можно остановить процесс, повторить шаг или восстановить прерванный запуск. Доступные действия зависят от состояния запуска и ваших прав.

Кому доступно

• ADMIN и FLOW_CONFIGURATOR управляют запусками всех команд.
• TEAM_MEMBER управляет запусками проектов своей команды.
• PRODUCT_OWNER просматривает запуски своей команды и отвечает на доступные точки участия человека, но не выполняет технические операции управления запуском.

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

Что делает платформа

1. Запуск создаётся в начальном состоянии и переходит к выполнению.
2. Среда выполнения выбирает очередной шаг. Перед первым выполнением AI-узла сохраняется контрольная точка (checkpoint); при доработке она может использоваться повторно.
3. После шага платформа проверяет код завершения, ожидаемые изменения и артефакты.
4. По переходу сценарий выбирает следующий шаг.
5. В точке участия человека переводит запуск в ожидание человека, если этого требует режим согласований. Иначе автоматически проходит по переходу точки участия человека.
6. После ответа на открытую точку участия человека продолжает процесс либо возвращает работу на доработку.
7. После успешного завершения графа запускает публикацию. Итоговый статус запуска учитывает и её результат.

Управляющие действия

Действие	Когда применяется	Результат
Продолжить	запуск ожидает допустимого продолжения	Исполнение возвращается в граф.
Отменить	запуск активен	Новые шаги не запускаются, запуск завершается отменой.
Повторить	Ошибка допускает повтор	Повторяется шаг, для которого разрешена новая попытка.
Восстановить	запуск в CRASHED, рабочий каталог не очищен	По вашему действию начинается восстановление запуска.
Повтор публикации	запуск в PUBLISH_FAILED	Повторяется только публикация.
Принудительная публикация	запуск в FAILED, публикация ещё не успешна, рабочий каталог не очищен, код ошибки допускает действие, режим не local	По вашему действию публикуется уже выполненная работа; проверьте её перед отправкой.

Что учесть

• Ошибка при автоматическом повторе завершает запуск с диагностикой, а не оставляет его в RUNNING.
• После перезапуска backend выполнявшийся запуск переходит из RUNNING в CRASHED. Откройте его карточку и выберите Восстановить, если рабочий каталог не очищен.
• Прерванная публикация переходит из WAITING_PUBLISH в PUBLISH_FAILED; для неё используйте повтор публикации. Автоматического продолжения этих операций нет.
• Некорректный переход, превышение лимита циклов или нарушение контракта узла завершаются контролируемой ошибкой.
• Повтор управляющего действия зависит от текущего состояния запуска. После сетевого сбоя сначала обновите карточку запуска.

Параметры и результат

• Параметры: снимок сценария, параметры запуска и решения в точках участия человека.
• Результат: итоговый статус, попытки узлов, артефакты, аудит и статус публикации.

Где найти

• В приложении: /run-console, /flow-debug.

Подробнее

• Обработка точки участия человека
• Рабочее пространство, код и артефакты
• Жизненный цикл запуска
• Валидация узла
• Контрольная точка узла
• Agent Quarantine

Запуск по расписанию

Если один и тот же процесс нужен регулярно, задайте расписание. Например, можно запускать подготовленный сценарий каждую ночь. Вы также выбираете, что делать, если предыдущий запуск ещё не закончился.

Кому доступно

• ADMIN и FLOW_CONFIGURATOR управляют всеми расписаниями.
• TEAM_MEMBER управляет расписаниями проектов своей команды.
• PRODUCT_OWNER не управляет расписаниями.

Как это работает

1. Выберите проект и опубликованный сценарий.
2. Задайте cron-выражение, часовой пояс и параметры запуска.
3. Решите, что делать при пересечении запусков: пропустить новый, поставить один в очередь или выполнить параллельно.
4. Включите расписание и проверьте время следующего запуска.
5. При необходимости приостановите расписание или запустите его сразу, не дожидаясь очередного времени.

Стратегии пересечения

Стратегия	Поведение при активном предыдущем запуске
SKIP	Новый запуск пропускается.
QUEUE_ONE	Сохраняется один ожидающий запуск.
START_ANYWAY	Новый запуск создаётся параллельно.

Что учесть

• Если cron-выражение или часовой пояс указаны неверно, исправьте их перед сохранением.
• Если запланированный запуск не начался, откройте расписание и прочитайте сообщение об ошибке.
• Если проект или сценарий изменились, проверьте доступность сохранённых параметров перед повторным включением расписания.

Параметры и результат

• Параметры: cron-выражение, часовой пояс, стратегия пересечения запусков и параметры запуска.
• Результат: управляемое расписание со статусом и временем следующего запуска.

Где найти

• В приложении: /schedule.

Подробнее

• Запуск сценария
• Расписание запусков
• Технический дизайн расписания запусков

Обработка точки участия человека

Точка участия человека — шаг сценария для получения данных или решения человека. Если выбранный режим запуска требует прохождения этой точки участия человека, выполнение приостанавливается до ответа. Изучите изменения, дополните задачу или отправьте результат на доработку. После решения выполнение пойдёт по соответствующей ветке сценария.

Согласование результата шага не означает предварительного одобрения каждой команды агента. Действия внутри AI-шага зависят от агента, его настроек и доступных ему инструментов.

Кому доступно

• Платформенные операторы видят точки участия человека всех команд.
• PRODUCT_OWNER и TEAM_MEMBER отвечают в точках участия человека проектов своей команды.

Виды точек участия человека

Вид	Назначение	Основные действия
Запрос данных у человека	Получить недостающие данные	Передать данные
Согласование с человеком	Проверить результат шага	Одобрить, Запросить доработку

Режимы согласований

Режим gate_mode задаётся при запуске и определяет, какие точки участия человека требуют ответа.

Режим	Поведение
require_all_gates	Все точки участия человека требуют ответа. Используйте для первого запуска с проверкой человеком.
require_po_gates_only	Ответ требуется только для точек участия человека, у которых в allowed_roles указан PRODUCT_OWNER. Остальные точки участия человека, включая точки участия человека без списка ролей, пропускаются.
skip_all_gates	Все точки участия человека пропускаются без ответа человека.

При пропуске запроса данных у человека процесс автоматически проходит по переходу on_submit, при пропуске согласования с человеком — по on_approve. В аудите сохраняется событие gate_auto_skipped. Наличие точки участия человека в графе само по себе не гарантирует остановку для согласования.

Решение о снятии точек контроля принимайте после отладки процесса на реальных задачах и оценки пользы и потенциального риска. Оценка может обосновать сохранение согласований. Для каждой точки участия человека заранее определите проверяющего, критерии решения, блокируемое действие и путь эскалации разногласий.

Как выполнить

1. Откройте ожидающую точку участия человека во входящих согласованиях или в карточке запуска.
2. Прочитайте сводку, изучите артефакты, изменения файлов и журнал. Если нужно, задайте агенту вопрос в чате точки участия человека.
3. На запросе данных у человека передайте недостающие данные. На согласовании с человеком примите результат или опишите, что нужно исправить.
4. Отправьте ответ. В истории сохранятся ваше решение и время, а запуск продолжит выполнение по соответствующему переходу.

Возврат на доработку

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

• Инструкция может относиться ко всему результату, файлу или выделенному фрагменту.
• Настройки доработки определяют, возобновлять ли предыдущую AI-сессию и сохранять ли изменения неудачной попытки.
• Если вы выберете откат изменений, платформа вернёт рабочие файлы к контрольной точке перед повтором. Правки после этой точки будут потеряны.

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

Что учесть

• Решение закрытой точки участия человека не принимается повторно.
• Командный пользователь не видит точки участия человека проектов другой команды.
• После сбоя обновите состояние точки участия человека: если решение уже сохранено, повторно отправлять его не нужно.
• Если ответ не проходит проверку, точка участия человека остаётся открытой. Исправьте данные по сообщению об ошибке и отправьте их снова.

Параметры и результат

• Параметры: решение, комментарий или данные, замечания для доработки и при необходимости выбор модели и сессии чата.
• Результат: закрытая точка участия человека, событие аудита и продолжение запуска.

Где найти

• В приложении: /gates-inbox, /human-gate, /gate-input, /gate-approval, вкладка точки участия человека в консоли запуска.

Подробнее

• Ручная доработка (перехват управления)
• Жизненный цикл запуска
• Решение в точке участия человека
• Контрольная точка узла

Ручная доработка (перехват управления)

Иногда проще исправить несколько строк самому. Перехват управления позволяет временно взять редактирование на себя, внести изменения в рабочие файлы запуска и затем вернуться к согласованию.

Кому доступно

Пользователь, имеющий право отвечать в точке участия человека соответствующего проекта.

Перед началом

• Точка участия человека открыта и поддерживает ручное редактирование.
• Рабочий каталог запуска ещё существует.
• Действие ручного редактирования доступно в рабочей области точки участия человека.

Как выполнить

Выберите встроенный редактор или внешнюю IDE. Эти способы по-разному передают изменения в запуск.

Во встроенном редакторе

1. В открытой точке участия человека начните ручную доработку во встроенном редакторе.
2. На вкладке «Код» откройте файл, внесите правки и сохраните его в рабочем каталоге запуска.
3. Проверьте изменения и запросите возврат к согласованию. Если выбираете завершение доработки с одобрением точки участия человека, это решение сразу продолжит сценарий.

Во внешней IDE

Начало этого режима отправляет рабочую ветку запуска в Git до завершения согласования. Убедитесь, что промежуточные изменения можно отправлять в этот репозиторий.

1. В открытой точке участия человека начните ручную доработку во внешней IDE. Платформа создаст снимок текущих изменений и отправит рабочую ветку.
2. Получите эту ветку в своей локальной копии репозитория и откройте её в IDE.
3. Внесите и проверьте правки, создайте коммит и отправьте его в ту же ветку. Для нескольких репозиториев отправьте изменения каждого из них.
4. Вернитесь к точке участия человека и завершите доработку без одобрения (Завершить без одобрения). Платформа получит коммиты из Git, проверит совместимость истории с исходным снимком и обновит рабочие файлы запуска.
5. На согласовании проверьте обновлённые изменения и примите решение.

Что учесть

• Если редактор не открылся, проверьте состояние точки участия человека и доступность рабочего пространства, прежде чем продолжать.
• После очистки рабочего каталога продолжить этот запуск нельзя. Создайте новый запуск; удалённые локальные правки сами по себе не восстановятся.
• Встроенный редактор проверяет путь, состояние запуска и отсутствие изменений файла с момента его открытия. При завершении доработки проверяются состояние точки участия человека и, для внешней IDE, история Git. Эти проверки не заменяют проверку контрактов AI-узла или запуск тестов после ручных правок.
• Для внешней IDE локальных правок недостаточно: нужны коммиты в удалённой рабочей ветке. Если новых коммитов нет, интерфейс запросит подтверждение продолжения без изменений.
• Перед одобрением проверьте обязательные артефакты и полный список изменений на соответствие задаче, выполните нужные проверки проекта.

Параметры и результат

• Параметры: ID точки участия человека, режим ручного редактирования и ручные файловые изменения.
• Результат: обновлённый рабочий каталог запуска и возврат к согласованию либо продолжение сценария, если вы завершили доработку с одобрением точки участия человека.

Где найти

• В приложении: рабочая область точки участия человека и редактор кода запуска.

Подробнее

• Обработка точки участия человека
• Рабочее пространство, код и артефакты
• Редактор кода запуска
• Решение в точке участия человека

Рабочие файлы, изменения и артефакты запуска

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

Кому доступно

• Пользователи с доступом к запуску просматривают дерево файлов, содержимое, изменения и артефакты.
• Редактирование файлов доступно только в явно разрешённых сценариях, например перехват управления.

Что делает платформа

1. При старте запуска платформа создаёт рабочий каталог и извлекает выбранные версии репозиториев.
2. Для каждого репозитория сохраняет исходный коммит (base SHA) и ветки.
3. Подготавливает файлы правил проекта, навыки, субагентов и настройки MCP.
4. Перед первым выполнением AI-узла сохраняет контрольную точку; при доработке она может использоваться повторно.
5. После выполнения собирает изменения и проверяет объявленные артефакты и ожидаемые изменения с учётом настроек валидации сценария.
6. Регистрирует созданные артефакты с областью run или project.
7. Интерфейс показывает дерево по репозиториям, изменённые файлы, содержимое и изменения.

Артефакты

• Область run хранит результат конкретного запуска.
• Область project позволяет использовать результат в последующих шагах и запусках, если это допускают ссылки и правила доступа к артефактам.
• artifact_ref может разрешать конкретный путь или шаблон пути.
• Обязательный артефакт участвует в проверке узла.

Что учесть

• Отсутствующий обязательный артефакт завершает попытку ошибкой, если включён fail_on_missing_declared_output. При значении false платформа фиксирует node_validation_ignored, и выполнение может продолжиться. Одного required: true недостаточно для обязательной остановки.
• expected_mutations проверяет ожидаемые изменения перечисленных путей, но не запрещает правки других файлов. Проверяйте полный список изменений; при необходимости добавьте отдельную команду, проверяющую область изменений.
• Отсутствие обязательного ожидаемого изменения останавливает попытку при включённом fail_on_missing_expected_mutation. При false нарушение фиксируется в аудите без обязательной остановки.
• В начальных настройках визуального редактора нового сценария оба флага строгой проверки выключены. Для обязательного контроля результата включите их и проверьте сгенерированный YAML. Если поля отсутствуют в YAML, среда выполнения применяет строгую проверку по умолчанию.
• Служебные файлы агента отделяются от пользовательских изменений карантином.
• Очищенное рабочее пространство больше не предоставляет код, но сохранённые сведения о запуске и аудит остаются доступны.

Параметры и результат

• Параметры: снимок состояния репозиториев, контракты узлов и фактические файловые изменения.
• Результат: версии артефактов, дерево файлов, изменения, разница версий и контрольные точки.

Где найти

• В приложении: вкладки «Код», «Изменения» и «Артефакты» в консоли запуска и рабочей области точки участия человека.

Подробнее

• Artifacts
• Валидация узла
• Контрольная точка узла
• Редактор кода запуска
• Agent Quarantine

Согласование и публикация каталога

Когда сценарий, навык или субагент проверен, опубликуйте его версию, чтобы она стала доступна для рабочих запусков. Порядок зависит от области каталога: командная версия и общая версия организации проходят разные пути.

Кому доступно

ADMIN и FLOW_CONFIGURATOR отправляют версии, просматривают очередь и принимают решения.

Как это работает

1. Завершите черновик версии и отправьте его на публикацию.
2. Для области team используйте прямую публикацию оператором. Для organization отправьте запрос на согласование.
3. Если настроена синхронизация с Git-каталогом, платформа подготовит нужные операции с коммитом, веткой или запросом на слияние.
4. Оператор проверяет запрос и принимает либо отклоняет версию.
5. После успешной публикации новая версия появляется в формах запуска.

Что учесть

• Отклонение сохраняет решение и не делает версию доступной рабочим запускам.
• Сбой задания отображается в очереди и допускает повтор после устранения причины.
• После сбоя обновите очередь и проверьте состояние запроса, прежде чем отправлять решение повторно.
• При ошибке проверьте статус именно публикуемой версии в очереди; после устранения причины повторите её публикацию.

Параметры и результат

• Параметры: черновая версия, данные публикации и решение оператора.
• Результат: опубликованная/отклонённая версия и история заданий публикации.

Где найти

• В приложении: /requests.

Подробности областей и каналов публикации: Области каталога и руководство публикации.

Подробнее

• Версионирование каталога
• Платформенные подключения

Публикация результата запуска

После успешного завершения графа сценария HG SDLC запускает отправку изменений в Git. Необходимость проверки человеком определяется точками участия человека и режимом согласований. Вы можете получить отдельную рабочую ветку, прямой коммит в выбранную ветку или запрос на слияние. Если сбой произошёл только при публикации, её можно повторить без нового выполнения сценария.

Кому доступно

• Пользователи с доступом к запуску просматривают статус публикации.
• ADMIN и FLOW_CONFIGURATOR повторяют публикацию и используют доступную по состоянию принудительную публикацию для запусков всех команд.
• TEAM_MEMBER выполняет эти действия для запусков своей команды.
• PRODUCT_OWNER просматривает результат, но не управляет публикацией запуска.

Перед началом

• Для обычной публикации запуск завершил необходимые шаги и согласования, требуемые режимом запуска. Исключение — отдельное действие «Принудительная публикация», описанное ниже.
• Выбран режим с отправкой изменений в Git.
• У проекта настроено SCM-подключение и доступны учётные данные.

Что делает платформа

1. Среда выполнения проверяет итоговые изменения каждого репозитория запуска.
2. Формирует commit по публикационному шаблону.
3. Выполняет push согласно режиму: публикует рабочую ветку либо отправляет изменения напрямую в выбранную ветку.
4. Для PR-режима создаёт запрос на слияние в целевую ветку.
5. Сохраняет адрес результата и статус публикации для каждого репозитория.
6. Завершает запуск с итогом публикации и отправляет связанные события.

Отправка изменений в Git не означает их слияние или выпуск продукта. Дальнейшие проверки, слияние и развёртывание зависят от настроек целевого репозитория.

Что учесть

• Для новых запусков доступны branch, direct_push и pr (при поддержке SCM); debug использует branch.
• local — совместимость со старыми запусками: изменения остаются в рабочем пространстве, push не выполняется.
• Конфликт занятой рабочей ветки проверяется до начала работы агента; позже отправку могут отклонить изменения на Git-сервере.
• Если отправка отклонена как non-fast-forward, проверьте расхождение с удалённой веткой по сообщению об ошибке.
• Мультирепозиторная публикация может иметь разный статус по репозиториям; частичный результат явно отображается.
• publish retry повторяет публикацию для PUBLISH_FAILED без перезапуска шагов сценария.
• Принудительная публикация позволяет отправить уже выполненную работу из запуска в FAILED, если публикация ещё не завершилась успешно, рабочий каталог не очищен, код ошибки допускает это действие и режим не local. Кнопка доступна по результату серверной проверки. Перед нажатием изучите изменения: сам запуск завершился с ошибкой.
• После очистки рабочего пространства эти файлы опубликовать невозможно; используйте повторный запуск.

Параметры и результат

• Параметры: изменения рабочего каталога, режим публикации, стратегия веток, SCM и шаблоны.
• Результат: опубликованная ветка, прямой push или запрос на слияние по каждому репозиторию; для старого local запуска — файлы в рабочем пространстве.

Где найти

• В приложении: статус публикации, повтор публикации и доступная по состоянию принудительная публикация в консоли запуска.

Подробнее

• Путь публикации результата
• Платформенные подключения
• External API и webhooks
• Мультирепозиторная публикация описана в описании выпуска 2.0.

External API и webhooks

Подключите HG SDLC к CI или системе задач: внешняя система сможет запускать сценарии, а платформа — сообщать ей о ходе работы. Для запуска по API используются ключи доступа, для обмена событиями — webhooks.

Кто участвует

• Внешняя система с ключом API запускает запуск через External API.
• Внешняя система вызывает настроенный входящий webhook.
• HG SDLC отправляет события на настроенные адреса исходящих уведомлений.
• ADMIN управляет ключами API; доступные операторы настраивают webhooks.

External API

1. Администратор создаёт ключ API и сразу сохраняет показанный секрет.
2. Клиент передаёт ключ в запросе запуска.
3. Система проверяет ключ, область проекта и параметры запуска.
4. Создаётся запуск с источником external_api.
5. Отозванный ключ перестаёт принимать новые запросы.

Секрет хранится в виде хеша для проверки и не возвращается повторно после создания.

Входящие webhooks

1. Оператор создаёт именованную конфигурацию входящего webhook.
2. Внешняя система вызывает /api/webhooks/in/{name} с согласованными данными.
3. Система проверяет конфигурацию и выполняет связанное действие.
4. Связь webhook с запуском сохраняется для диагностики.

Исходящие webhooks

1. Оператор создаёт адрес получателя, выбирает события и параметры аутентификации.
2. При событии запуска система формирует HTTP-запрос.
3. Результат доставки записывается в истории исходящих уведомлений.
4. Пользователь может просмотреть историю доставки для запуска.

Что учесть

• Неверный или отозванный ключ API отклоняется до выполнения действия.
• При запуске через External API передавайте заголовок Idempotency-Key. Для повтора того же запроса используйте прежний ключ и те же данные; новый ключ обозначает отдельный запрос.
• Ошибка получателя уведомления не изменяет уже зафиксированный статус запуска.
• Секреты webhook/API не возвращаются в открытом виде в обычных ответах API чтения.

Где найти

• External API: POST /api/external/v1/runs/launch.
• Ключи API: /api/settings/api-keys.
• Приём входящих событий: POST /api/webhooks/in/{name}.
• Настройка webhooks: /api/webhooks/inbound, /api/webhooks/outbound.

Подробнее

• Запуск сценария
• Жизненный цикл запуска
• API Keys
• Webhooks

SCM, MCP и подключения ИИ-агентов

Чтобы агент мог работать с вашим кодом, настройте доступ к Git и среду его запуска. Если процессу нужны дополнительные инструменты, подключите серверы MCP. Ниже описано, за что отвечает каждое подключение.

Подключения к Git-хостингам

Оператор регистрирует подключение с типом, базовым URL API и учётными данными. Проект ссылается на подключение, а система проверяет соответствие хоста его репозиториям. Подключение используется для Git-доступа, push и создания запроса на слияние.

Серверы MCP

ADMIN создаёт конфигурацию сервера, выбирает транспорт, задаёт переменные окружения, заголовки, команду и секреты, проверяет предпросмотр для выбранного агента и включает сервер. AI-узел ссылается на него через mcp_refs. Конфигурация фиксируется для запуска; секреты маскируются в публичных представлениях. Для работы агенту могут потребоваться реальные учётные данные.

Среда выполнения агента

Поддерживаются Qwen, Claude, GigaCode, Codex и OpenCode. CLI/ACP-адаптер выбранного агента должен быть установлен и авторизован отдельно. Само приложение может запускаться без GigaCode; агент нужен для использующих его AI-сценариев.

Платформенный оператор настраивает команду запуска агента, ограничения ACP-процессов, время ожидания и модель по умолчанию. При запуске система получает каталог моделей, выполняет предварительную проверку и фиксирует запрошенную и фактически выбранную модель.

Как это работает

1. Создайте подключение и проверьте его параметры.
2. Сохраните секреты в предназначенных для них настройках.
3. Укажите подключение в проекте или сценарии.
4. Создайте тестовый запуск. На старте платформа проверит доступность подключения и сохранит снимок конфигурации.
5. При ошибке откройте диагностику запуска, шага или публикации — она поможет определить, какое подключение нужно исправить.

Что учесть

• Если MCP-сервер отключён, проверьте ссылки на него в сценарии и состояние подключения перед запуском.
• Предпросмотр маскирует известные поля секретов и показывает незаполненные обязательные параметры.
• Исчезнувшая после старта модель не заменяется молча во время AI-узла.
• Неверный хост SCM или учётные данные блокируют соответствующую операцию.

Права

• Просмотр общих настроек доступен аутентифицированным пользователям в пределах доступного интерфейса.
• Настройки среды выполнения, каталога и SCM редактируют ADMIN и FLOW_CONFIGURATOR.
• Настройки MCP с секретами редактирует только ADMIN.

Где найти

• В приложении: /settings.

Подробнее

• Управление проектами
• Запуск сценария
• Публикация результата
• Возможности MCP и SCM описаны в описании выпуска 2.0.
• Выбор модели описан в описании выпуска 2.1.

Консоль запуска, аудит и диагностика

Начните с консоли запуска, если хотите понять, что происходит с задачей. Здесь собраны шаги процесса, журналы, изменения кода и решения человека. При сбое можно перейти к конкретному шагу и прочитать его сообщение об ошибке.

Кому доступно

• Платформенные операторы видят запуски всех команд.
• Командные пользователи видят запуски своих проектов.
• PRODUCT_OWNER может просматривать доступные запуски, но не выполняет технические операции консоли запуска.

Как это работает

1. Откройте список запусков и найдите нужный запуск с помощью фильтров.
2. Откройте карточку: в ней видны статус, источник запуска, проект, сценарий, выбранную модель и статус публикации.
3. По графу и временной шкале найдите текущий и завершённые шаги.
4. Откройте детали шага, его вывод stdout/stderr и расход токенов, если агент его сообщает.
5. Изучите артефакты и изменения кода.
6. Проверьте последовательность событий аудита.
7. Перейдите к открытой точке участия человека или выберите доступное действие управления запуском.

Диагностические представления

Представление	Что отвечает пользователю
Список и карточка запуска	Где находится процесс и как он завершился?
Граф и временная шкала	Какой путь по сценарию фактически выполнен?
Журнал узла	Что сообщил исполнитель шага?
Код и изменения	Какие файлы изменились?
Artifacts	Какие документы и другие результаты созданы?
Audit	Кто и когда изменил состояние?
Контекст агента	Какой контекст получил агент?

Что учесть

• После очистки рабочего каталога файлы больше недоступны, но историю запуска по-прежнему можно открыть.
• Частично доступные данные показываются с диагностикой вместо маскировки всего запуска.
• Список и карточка запуска ограничены областью доступа пользователя.

Где найти

• В приложении: /run-console и разделы аудита, артефактов и контекста агента.

Подробнее

• Жизненный цикл запуска
• Рабочее пространство, код и артефакты
• Обработка точки участия человека
• Жизненный цикл запуска
• Artifacts

Состояние сервера и очистка рабочих файлов

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

Кому доступно

ADMIN и FLOW_CONFIGURATOR.

Как это работает

1. Откройте раздел «Состояние сервера» в настройках.
2. Посмотрите загрузку CPU, память и состояние ACP-процессов агента.
3. Настройте интервалы метрик, сроки хранения рабочих каталогов, расписание очистки и минимальный запас свободного места.
4. Проверьте правила отдельно для завершённых и активных запусков. При нехватке места очистка начинает со старейших каталогов, подходящих под эти правила.
5. Посмотрите журнал очистки. При необходимости запустите её вручную, предварительно сохранив нужные результаты.

Сохраняемые данные

Очистка удаляет рабочие файлы запуска. Записи запуска, аудит и служебные данные .hgsdlc сохраняются; удалённый код и артефакты из рабочего пространства больше недоступны.

Что учесть

• Срок хранения завершённых запусков сам по себе не применяется к активным рабочим каталогам: для них используются отдельные правила.
• Ошибка удаления записывается и не делает запуск завершённым успешно.
• Очистка затрагивает только рабочие каталоги, которыми управляет платформа.

Где найти

• В приложении: /settings, раздел «Состояние сервера».

Подробнее

• Консоль запуска и аудит
• Рабочее пространство, код и артефакты
• Возможность состояния сервера описана в описании выпуска 2.1.

Обзор состояния разработки

Откройте обзор после входа: сводка поможет увидеть, какие процессы работают, где возникли ошибки и какие согласования ждут ответа. Из неё можно сразу перейти к нужному запуску или точке участия человека.

Кому доступно

Все пользователи, вошедшие в систему. Метрики, недавние запуски и точки участия человека рассчитываются в их области доступа.

Как это работает

1. После входа откройте Overview.
2. Проверьте состояние платформы и время последнего наблюдения.
3. Оцените количество активных запусков, ожидающих точек участия человека и недавних ошибок.
4. Посмотрите опубликованные и черновые сценарии, события аудита и длительность ожидания решений.
5. Перейдите к ожидающей точке участия человека или откройте подробности нужного запуска.

Показатели

• активные запуски;
• точки участия человека, ожидающие ввода или решения;
• неуспешные запуски за 24 часа;
• медианное и максимальное ожидание точки участия человека;
• опубликованные и черновые сценарии;
• события аудита за 24 часа;
• недавние запуски и входящие согласования.

Что учесть

• Недоступный сигнал состояния отображается как degraded/unavailable и не скрывает остальные данные.
• Если вы только установили HG SDLC, пустые списки — это нормально: они заполнятся после первых запусков.
• Сводка ограничивается областью доступа пользователя. Отдельный раздел «Аналитика» имеет другое ограничение доступа.

Параметры и результат

• Параметры: текущий пользователь и его область доступа.
• Результат: агрегированная сводка и ссылки на требующие внимания объекты.

Где найти

• В приложении: /overview.

Подробнее

• Консоль запуска и аудит
• Обработка точки участия человека
• Состояние сервера

Аналитика команд и автономности проектов

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

Кому доступно

ADMIN, FLOW_CONFIGURATOR, PRODUCT_OWNER и TEAM_MEMBER. Если у пользователя есть команда, интерфейс выбирает её по умолчанию. Фильтры можно изменить.

Как это работает

1. Откройте «Аналитику» и выберите период: 7, 30 или 90 дней.
2. Укажите команду и проект. Если у вас есть команда, она выбрана по умолчанию, но фильтр можно изменить.
3. На вкладке команд сравните результаты запусков, их длительность, расход токенов по доступным данным и участие человека.
4. Откройте участника, чтобы посмотреть его запуски. Автоматические запуски учитываются отдельно.
5. На вкладке автономности сравните проект с предыдущим периодом: сколько участия человека предусмотрено в сценарии и сколько согласований, ожиданий и доработок произошло на практике.

Ограничения

• Автономность здесь — измеряемые показатели, а не настраиваемое разрешение агенту работать без человека. Точки контроля задаются сценарием и режимами запуска.
• Неполные данные о токенах и времени сопровождаются показателями покрытия; отсутствие измерений не означает нулевые затраты.
• В текущей реализации фильтрация аналитики определяется переданными параметрами, а не членством текущего пользователя в команде. Сервер допускает перечисленные роли, но не ограничивает выборку собственной командой. Начальный фильтр UI не является изоляцией данных.
• Несуществующая команда или проект вне выбранной команды отклоняются как некорректная область запроса.

Как оценивать улучшение процесса

История запусков позволяет находить причины задержек и возвратов; сама по себе она не доказывает эффект платформы. Сравнивайте с привычным способом работы затраты времени всей команды, качество результата и цену ошибок.

Снижение числа возвратов на доработку или ожиданий полезно оценивать вместе с качеством проверок: ослабление приёмки может улучшить показатели и ухудшить результат. Повторяющееся замечание человека — повод проверить инструкцию, навык или последовательность шагов, а не автоматически менять процесс.

Показатели исполнения не заменяют проверку исходной бизнес-гипотезы после развёртывания. Настройка бизнес-метрик, их замер и возврат результатов в следующий цикл изменения (outcome check) остаются направлением развития.

Параметры и результат

• Параметры: период, фильтры команды и проекта; для детализации — участник.
• Результат: сводка, сравнение с предыдущим периодом, показатели сценария и список запусков.

Где найти

• В приложении: /analytics, вкладки команд и автономности.

Подробнее

• Обзор состояния разработки
• Консоль запуска и аудит
• Настройки проекта

Сравнительные испытания

Хотите понять, какая модель или версия сценария лучше справляется с вашими задачами? Запустите их на одном наборе примеров и сравните результаты. Каждый вариант оценивается отдельно; данные можно выгрузить или использовать для повторной проверки.

Кому доступно

Экспериментальная возможность для ADMIN и FLOW_CONFIGURATOR. Раздел скрыт из основного меню. Откройте путь /benchmark в установленном приложении.

Перед началом

Подготовьте проект, каталог задач на сервере, совместимые сценарии, агентов и модели. Для автоматической оценки выберите сценарий-оценщик. Эталон задачи передаётся на оценку, но не используется как обычный вход проверяемого варианта.

Как провести сравнение

1. Откройте /benchmark/new и выберите проект.
2. Добавьте задачи и варианты, которые хотите сравнить, затем настройте оценку.
3. Создайте набор испытаний. Для каждой пары «вариант × задача» появится ячейка с отдельным результатом.
4. Следите за выполнением и сравнивайте оценки. При ошибке можно повторить запуск ячейки или только её оценку.
5. Если автоматическая оценка требует исправления, внесите явную корректировку с комментарием.
6. Выгрузите результаты. Незавершённый набор испытаний можно отменить.

Как читать результат

Сводка показывает результаты выполнения и оценки по вариантам. Ошибка агента и ошибка оценщика относятся к конкретной ячейке — сначала откройте её подробности. Ручная корректировка меняет оценку, но не повторяет задачу.

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

Где найти

В приложении: /benchmark, /benchmark/new, /benchmark/{suiteId}.

Подробнее

• Запуск сценария
• Консоль запуска и аудит
• Карта возможностей

Контекстный чат и предложения изменений

Откройте панель ассистента, если нужна помощь с текущим экраном. Например, можно обсудить сценарий и получить предложение изменений. Вы сами решаете, применять ли его: принятые правки попадут в черновик, который ещё нужно проверить и сохранить.

Кому доступно

Помощник доступен всем вошедшим пользователям в пределах их доступа к данным. Применение изменений сценария дополнительно ограничено правами редактора каталога.

Как это работает

1. Откройте плавающую панель ассистента.
2. Начните новую беседу или вернитесь к беседе для текущего экрана.
3. Выберите доступную модель и задайте вопрос. Ассистент получит контекст страницы с маскированием известных полей секретов.
4. Прочитайте ответ. Он появляется постепенно и сохраняется в истории.
5. Если появилось предложение изменить сценарий, изучите его карточку и примите или отклоните правки.
6. Проверьте принятые изменения в редакторе сценария. Они ещё не сохранены: сохраните черновик и отдельно опубликуйте проверенную версию.

Контекст бесед

• Обычные беседы с ассистентом группируются по contextKey экрана.
• Пользователь может переключаться между беседами текущего экрана и всеми своими беседами.
• Беседы в точке участия человека входят в тот же интерфейс отдельной группой; закрытая точка участия человека доступна только для чтения.

Что учесть

• Известные поля секретов маскируются. Произвольные секреты в тексте задачи или исходном коде могут попасть в контекст; учитывайте настройки агента и поставщика модели.
• При сбое отправки сначала проверьте сохранённую историю беседы, затем решайте, нужно ли повторять сообщение.
• Истечение времени ожидания или обрыв потока ответа оставляет уже сохранённую историю доступной.
• Предложение не обходит права и жизненный цикл каталога.

Параметры и результат

• Параметры: сообщение, контекст страницы, выбранные беседа и модель.
• Результат: сохранённый ответ и, при наличии, предложение изменения сценария.

Где найти

• В интерфейсе: плавающая панель ассистента на авторизованных страницах.

Подробнее

• Редактирование сценария
• Обработка точки участия человека
• Описание ассистента в версии 2.1

Пользовательский CLI

CLI подходит, если вы хотите запустить готовую сборку HG SDLC без сборки исходников. Несколькими командами можно проверить окружение, запустить приложение, посмотреть журнал и остановить его.

Перед началом

Node.js 18+ и npm, Java 21+, Git для работы с репозиториями, URL сервера дистрибуции и доступный пользовательский каталог. Без PostgreSQL приложение использует локальный профиль с H2; данные этого режима хранятся в памяти и не сохраняются после остановки. Node.js 18+ — требование CLI; для сборки из исходников используйте Node.js 22 из .nvmrc.

Как это работает

1. Получите адрес сервера дистрибуции у администратора и выполните указанную там команду установки CLI.
2. Запустите hgsdlc doctor, чтобы проверить окружение.
3. При необходимости подготовьте GigaCode командой hgsdlc setup, а подключение к PostgreSQL — командой hgsdlc configure.
4. Выполните hgsdlc run. CLI выберет и проверит JAR, запустит Java и дождётся ответа проверки состояния приложения.
5. Для просмотра журнала используйте hgsdlc logs, для остановки — hgsdlc stop.

Версии и обновление

• hgsdlc update обновляет сам CLI; JAR приложения выбирается при hgsdlc run.
• При первой установке пригодная JAR скачивается автоматически.
• Если в интерактивном терминале обнаружена новая версия, CLI предлагает обновление; ответ по умолчанию — сохранить локальную версию.
• Без интерактивного терминала при наличии пригодной локальной JAR запускается она, без ожидания ответа. При недоступности сервера также возможен запуск проверенной локальной копии.
• hgsdlc run --version <version> использует именно указанную опубликованную версию, без подмены другой сборкой.
• Ошибка скачивания или проверки принятого обновления завершает команду; старая проверенная JAR сохраняется.
• run не перезапускает уже работающий процесс: сначала выполните stop.

Подключение агента

GigaCode не обязателен для старта приложения: run его не устанавливает и не проверяет. setup подготавливает GigaCode отдельно; авторизация агента и настройка среды выполнения остаются обязательными для использующих его AI-сценариев. Другие поддерживаемые CLI/ACP-адаптеры устанавливаются отдельно.

Параметры и результат

• Параметры: URL дистрибуции, версия приложения, порт, опциональная конфигурация PostgreSQL.
• Результат: установленный CLI и управляемый локальный процесс приложения с конфигурацией, кэшем и логами в пользовательском каталоге.

Подробнее

• Подробное руководство CLI
• Установка через CLI
• Подключения ИИ-агентов

Эксплуатация установки

Когда установка готова, настройте резервное копирование и срок хранения рабочих файлов. Так у команды будет понятный способ сохранить данные и вернуться к работе после сбоя.

Что нужно сохранять

Для постоянной работы используйте PostgreSQL. Резервная копия базы сохраняет проекты, настройки и историю; каталог сценариев в Git и рабочие файлы запуска требуют отдельного учёта. Храните конфигурацию и секреты в защищённом хранилище.

Для развёртывания из deploy предусмотрен скрипт резервного копирования PostgreSQL:

cd deploy
./backup-postgres.sh ./.env.prod

Это команда для подготовленной серверной конфигурации с .env.prod. Она не относится к локальному запуску из учебного примера. Порядок настройки, проверки и восстановления описан в руководстве резервного копирования. Проверяйте восстановление на отдельной БД.

Обновление

Зафиксируйте текущую версию и сделайте резервную копию до изменения серверной установки. Проверьте совместимость схемы БД и выбранной сборки; возврат старого образа сам по себе не отменяет миграции. Следуйте руководству обновления и отката.

При установке через CLI команда hgsdlc update обновляет CLI, а выбор JAR приложения происходит при hgsdlc run. Подробности — в описании CLI.

Диск и диагностика

В разделе состояния сервера наблюдайте за ресурсами и сроком хранения рабочего пространства. Очистка освобождает диск, но удалённые файлы больше нельзя просмотреть или опубликовать из этого запуска. Перед очисткой убедитесь, что нужные результаты сохранены в Git или отдельно.

При ошибке сначала откройте консоль запуска: определите проблемный узел, прочитайте его журнал и статус публикации. Повтор узла, восстановление запуска и повтор публикации решают разные задачи и доступны по состоянию запуска. Описание действий поможет выбрать нужное.

Сборка и публикация справочника

Обновление материалов

Чтобы исправить текст на сайте, обновите соответствующие Markdown-файлы в docs/product/product-ru/ (русский) и docs/product/product-en/ (английский), затем пересоберите HTML. Не редактируйте сгенерированный файл вручную: следующая сборка перезапишет эти изменения. Правила описания функций предназначены для авторов документации.

Из корня репозитория, с Node.js 22 из .nvmrc:

npm --prefix docs/product ci
npm --prefix docs/product run build

Результат — docs/index.html. Если зависимости установлены, из корня достаточно npm --prefix docs/product run build.

Зависимости генератора описаны в docs/product/package.json и зафиксированы в docs/product/package-lock.json. Устанавливать зависимости frontend для сборки справочника не требуется.

Шаблон страницы: docs/product/scripts/product-docs.template.html. Генератор: docs/product/scripts/build-product-docs.mjs. Он проверяет существование локальных целей ссылок, уникальность ключей и ID, переходы между встроенными разделами и сохраняет многострочное форматирование HTML.

Описания функций, стили и навигация встроены в HTML. Ссылки между продуктовыми документами становятся переходами внутри справочника. Технические материалы за его пределами и ссылки «Источник» ведут на файлы ветки master в GitVerse; их содержимое может обновляться независимо от опубликованной редакции. Для работы с ними нужен доступ к сети.

Два языка

Один файл docs/index.html содержит все разделы на русском и английском. Переключатель RU / EN сохраняет текущий раздел и подраздел. Выбор языка сохраняется в браузере, если доступно локальное хранилище; при первом открытии без прямой ссылки используется английский для англоязычного браузера и русский для остальных.

Прямые ссылки задают язык независимо от сохранённого выбора: #doc/getting-started открывает русский раздел, #en/doc/getting-started — английский. Поиск работает по тексту выбранного языка, а при печати выводится только эта языковая версия. Внешние технические руководства сохраняют язык своего источника.

При добавлении или изменении раздела обновляйте обе версии. Сохраняйте одинаковые key, id, domain, order, status, last_updated, а также порядок и уровни заголовков. Переводите title, group, текст и подписи ссылок. Относительные пути между продуктовыми документами остаются прежними; фрагменты ссылок должны соответствовать заголовкам нужного языка. Генератор проверяет полноту переводов, метаданные, структуру заголовков и внутренние ссылки.

Из корня репозитория проверьте сборку, навигацию и переключение языка:

npm --prefix docs/product test

GitVerse Pages: публикация из ветки

Для текущей структуры подходит источник «Ветка» и папка /docs. GitVerse публикует содержимое выбранной папки; index.html имеет приоритет перед index.md и README.md. Согласно быстрому старту GitVerse, репозиторий должен быть публичным, а CI/CD — включён.

1. Пересоберите справочник и включите docs/index.html вместе с изменёнными исходниками в коммит выбранной ветки.
2. В репозитории откройте Настройки → Страницы, включите Pages.
3. Выберите Ветка, укажите ветку с подготовленными файлами и папку /docs.
4. Сохраните настройки и проверьте журнал публикации.

Режим использует встроенную сборку Jekyll и запускается при коммитах в выбранную ветку. Команду npm нашего генератора этот режим сам по себе не выполняет: готовый HTML нужно обновить до коммита.

Адрес проекта: kakvsbere.gitverse.site/hgsdlc. После публикации откройте сайт и проверьте, что на нём появилась ваша редакция.

Когда нужен workflow

Если HTML должен собираться при публикации, используйте источник «Воркфлоу». В .gitverse/workflows задаются установка Node.js, npm --prefix docs/product ci и npm --prefix docs/product run build из корня репозитория. Затем официальный gitverse/upload-pages-artifact@v1.0.0 получает каталог сайта через path, а gitverse/deploy-pages@v1.0.0 публикует артефакт. В корне каталога нужен index.html.

Каталог публикации выбирается явно: можно подготовить отдельную папку с HTML и нужными ресурсами. Необязательно передавать весь docs с техническими материалами. Пример и требования приведены в официальной инструкции workflow.

Проверка перед публикацией

Откройте docs/index.html, проверьте поиск, меню, мобильный вид и ссылки. После публикации повторите проверку по адресу проекта, включая переключение RU / EN и прямые переходы #doc/getting-started и #en/doc/getting-started. Убедитесь, что на сайте видна ожидаемая дата редакции. Если страница старая, проверьте выбранную ветку, наличие обновлённого HTML и журнал сборки Pages.

Правила описания функций

Описывайте одну задачу, которую читатель может решить с помощью HG SDLC. Начинайте с пользы и примера, затем объясняйте шаги и ограничения.

Домены

Домен	Содержимое
access	Вход, пользователи, команды и роли.
projects	Проекты, репозитории и проектные настройки.
catalog	Сценарии, навыки, субагенты, версии и жизненный цикл.
flow-design	Создание, проверка и отладка сценария.
execution	Запуск, выполнение, восстановление и расписания.
human-gates	Решения человека, доработка и перехват управления.
artifacts	Рабочее пространство, код, изменения и артефакты.
publication	Публикация каталога и результата запуска.
integrations	External API, webhooks, SCM, MCP и ИИ-агенты.
observability	Консоль запуска, аудит, состояние среды выполнения, аналитика команд и автономности.
benchmarks	Экспериментальное сравнение вариантов на наборах задач, judge и экспорт.
assistant	Контекстный AI-ассистент.
operations	Установка, запуск и обновление приложения через CLI.

Обязательный YAML-заголовок

---
key: capabilities/execution/run-launch
id: RUN-001
title: Запуск Flow
group: Выполнение
order: 17
domain: execution
status: implemented
last_updated: 2026-09-28
---

Как писать

• Обращайтесь к читателю на «вы»: «выберите проект», «проверьте журнал». Когда действие выполняет система, называйте её явно.
• Начинайте с того, для чего нужен раздел. Не повторяйте на каждой странице заголовки «Ценность», «Акторы» и «Предусловия и триггеры».
• Используйте термины из глоссария. Пишите «шаг», «рабочий каталог» и «доработка», если точное имя в интерфейсе не требуется.
• Сохраняйте без изменений имена команд, полей и статусов. Английское название кнопки можно дать рядом с объяснением действия.
• В разделе «Кому доступно» указывайте роли и область доступа. Действия системы описывайте в разделе «Что делает платформа», действия пользователя — в «Как выполнить». Указывайте наблюдаемый результат и условия его получения. Не добавляйте раздел, если он не помогает читателю.
• Разделяйте действия человека и автоматические действия платформы. Не превращайте пожелание из спецификации в обещание существующей функции.
• Для ошибки укажите следующий шаг: где её посмотреть, что проверить и когда возможен повтор.
• Проверяйте описание вместе с ролями, ограничениями и связанным пользовательским сценарием.
• Не обещайте одинаковые ответы модели, полную изоляцию или автоматическое восстановление без подтверждения в коде.

Пример структуры

# Название возможности

Коротко объясните, какую задачу читатель сможет решить. Если помогает,
приведите конкретный пример.

## Кому доступно

Укажите роли и область команды. Не скрывайте исключения.

## Перед началом

Что нужно подготовить — только если это не очевидно из шагов.

## Как выполнить

Действия пользователя в порядке выполнения. Для каждого укажите место
в интерфейсе и наблюдаемый результат, если это нужно для следующего шага.

## Что делает платформа

Автоматическое поведение и условия его запуска — если их нужно объяснить
отдельно от действий пользователя.

## Что учесть

Ограничения и действия при ошибках.

## Где найти

Название раздела приложения. Пути интерфейса относятся к установленному
HG SDLC, а не к сайту документации.

## Подробнее

Ссылки на следующий шаг, связанные возможности и технические материалы.

Добавляйте только полезные для конкретной возможности разделы. Таблица параметров нужна, если помогает читателю подготовить запуск; дублировать в ней уже описанные шаги не требуется.

Нумерация

Идентификатор стабилен и не переиспользуется после удаления функции. Префикс соответствует домену: ACC, PRJ, CAT, FLW, RUN, HITL, ART, PUB, INT, OBS, BEN, AST, OPS.

HG SDLC - from a task to changes in your project

HG SDLC (Human Guided SDLC) is an orchestrator that organizes an AI agent's work on a task as a controlled process under human supervision. You describe the task and start a prepared scenario, and the agent works with project files using the available context. The system manages the sequence of steps and transitions between them: it runs the agent, commands, and checks, requests the necessary information from a person, and pauses the process at points where a decision or approval of the result is required.

Human Guided SDLC reflects how the platform works: a person does not have to manually oversee every step but retains control wherever requirements need clarification, a decision needs to be made, or a result needs review. The selected scenario and the run’s approval mode determine which stages a task goes through, which checks run, and where human involvement is needed.

What HG SDLC is for

Working on a task requires more than passing it to an agent: context must be retained between stages, necessary checks performed, and participant decisions recorded. Without a connected workflow, a person has to manually collect the results of the previous step and pass them to the agent again at the next stage.

HG SDLC lets you capture this way of working in a reusable scenario. For example, you can prepare a workflow for fixing bugs, adding tests, updating documentation, reviewing code, or developing new functionality.

In the scenario, the team defines which actions the agent performs, which commands and automated checks run, where human participation is required, and where the task should return if the result needs rework.

For each run, HG SDLC records execution history: completed steps, attempts, created artifacts, and human decisions. This makes it possible to understand what has been done, which step the task is at, why the workflow stopped, and what prompted rework.

Who HG SDLC helps and how

• People requesting work: describe the expected result, start a scenario, and participate at designated decision points. For example, a product owner can use a prepared product scenario without delving into the workflow's technical configuration.
• Developers: delegate some coding work to an agent, inspect changes and check results, then accept the result or return it for rework with specific feedback. If a problem is easier to solve manually, temporarily take control through Human Takeover, make changes, and return the task to the controlled workflow.
• People configuring the team's workflows: create and version scenarios, configure agent instructions, connect skills and subagents, and add automated checks and approval points. Reusable scenarios and components can be stored in the catalog and synchronized with a Git repository.

The actions available in the interface depend on your role and project access. Different team members can configure workflows and carry out day-to-day task work.

HG SDLC does not replace a well-defined task, context, or checks, and does not itself make the AI agent stronger. Its purpose is to connect stages of work into a controlled process, retain its state and history, and show people where their decisions or intervention are needed.

How a task moves through the platform

1. Describe the task. Choose a project and scenario, and describe what needs to change.
2. Start the workflow. This workflow is called a Flow: predefined steps for agent work, checks, and human participation. A specific execution of a Flow is called a Run. It has its own parameters, status, and history.
3. Follow progress. The platform prepares a Workspace, a working copy of files for that run, and gives the agent the task and project settings. The agent performs its steps, while commands included in the Flow check the result. The run view shows the current step, logs, changes, and generated documents or other files, called artifacts.
4. Respond when your input is needed. A point for requesting information or approval is called a Human Gate. It lets you clarify requirements or review a prepared result. At an approval step, you accept the work or describe what needs changing. Manual editing depends on the Gate's state and your permissions.
5. Check the outcome. After the workflow completes successfully, the platform sends changes to Git. The publication method is selected when starting the run.

Flows have versions: your team can change a workflow for future tasks, while each Run retains information about the components and parameters it used. This history helps explain execution, although identical settings do not guarantee identical AI responses on a repeat run.

Example: add a guide to a project

A small task with a clear result is a useful first exercise. In the tutorial, the agent is asked to create a file named hello-hgsdlc.md describing the project and check that the file exists.

This example uses a mode that requires a human response at every Gate. The agent creates the file, a configured command checks its presence, and you read the text at the approval step. Checking that a file exists confirms only its presence; you assess its contents.

If the text is incomplete, your feedback could be: “Add who this project is for and explain the user's first step.” Review the new version after rework. After the workflow completes successfully, the changes are pushed to a working branch in Git.

Where you control the result

The Run Console shows which step is executing, what the agent or validation command reported, and which files changed. If the workflow is waiting for a person, open the current Gate and respond. If a step failed, inspect its message; available recovery actions depend on the error, the run state, and your role.

A Human Gate requires a response only when the selected approval mode requires one. Some modes skip selected Gates or all Gates. To review every Gate, choose Require all gates; the Flow must also contain the approval points you need.

Decide whether to remove control points after validating the workflow on real tasks and assessing its benefits and potential risks. The assessment may show that those controls need to remain. Define who makes each decision, the criteria, which action waits for approval, and where to escalate a disagreement.

Accepting a step's result does not grant prior permission for every agent command. Validation commands detect the problems they are designed to check, while team members assess the result and the quality of the changes. Manual editing lets you change files at a Gate that supports it; those changes also need checking.

What you get at the end

• Project changes: code, documentation, or other files for the task. Review the complete diff before acceptance: the expected changes declared in a Flow do not restrict which files the agent can modify.
• Execution records: step states and attempts, logs, results of configured checks, and approval decisions.
• A Git publication result: a separate working branch, changes pushed to a selected branch, or a Pull Request. The outcome depends on the publication mode, connection permissions, and Git hosting support.

Sending changes to Git does not itself merge them into the main project version or deploy the application. Your team's rules govern those actions. If the work completed but the push failed, the publication status helps distinguish that situation from a workflow failure; see publishing results.

What needs to be ready before you start

If your team already has HG SDLC, obtain its address, an account, and project access from your administrator. Ask which scenario to use for your first task. You do not need to install a server yourself when your team has already prepared the environment.

To run AI tasks, the installation needs a connected agent with model access, a project repository, and a compatible workflow catalog. An administrator or another authorized team member prepares these settings.

If you are installing HG SDLC yourself

The project README describes the installation methods. Choose one with the person who will operate the platform:

• Locally from source — backend and frontend run on your machine, with PostgreSQL in Docker. The main path for exploring and developing the platform.
• Through the user CLI — install a published JAR build without cloning the source repository.
• Production Docker Compose — deploy PostgreSQL, backend, and frontend on a single Linux VM.

The current backend Docker image installs only Qwen CLI. The runtime supports Claude, GigaCode, Codex, and OpenCode when their CLI or ACP adapter is installed locally. The repository does not provide ready-made container images for those agents.

After installation and startup:

1. Connect a coding agent.
2. Add an SCM provider and a test repository.
3. Connect the test catalog branch for your chosen agent.
4. Run your first Flow.

For a short walkthrough within this handbook, see your first project and Flow.

Supported coding agents

Agent	Runtime ID	Local ACP runtime	Current Docker image
Qwen	qwen	Yes	Yes
Claude	claude	Yes	No
GigaCode	gigacode	Yes	No
Codex	codex	Yes	No
OpenCode	opencode	Yes	No

Flows, Skills, Subagents, and the test catalog branch must match the selected Runtime ID. Install and authenticate the CLI or ACP adapter on the machine running the backend; see the connection instructions.

Access after installation

• Local profile local: development account admin / admin.
• Production: the first ADMIN is created once through the bootstrap procedure.

admin / admin is intended only for local development and is not created in production. For an existing team installation, obtain the address and an account from your administrator.

Documentation

• Within this handbook: capability map, roles and permissions, and limitations and data.
• Complete user guide.
• Installation and first startup.
• Tutorials.
• Creating Flows, Skills, and Subagents.
• Users, teams, and scopes.
• System reference.
• Operations.
• Troubleshooting.

For developers

• Developer onboarding.
• Technical specification index.
• Release notes 2.1 — the release 2.1 notes linked in the README; this handbook targets version 2.2.0.
• Contributing.
• Building the handbook and publishing to GitVerse Pages.

Build and test commands are listed in the project README.

Capabilities and boundaries

In AI‑Disrupt PDLC terms, the platform primarily helps configure intent and implementation loops through a Flow. The validation spine and governance mesh are partially implemented; checking business outcomes after deployment (outcome check) remains a development direction. See implementation boundaries and plans.

AI can make mistakes, and a successful command confirms only what that command checked. Before accepting a result, verify that it meets the task requirements; use your team’s tests and code review practices for code changes.

A Run’s working copy is separate from other runs, but it does not by itself restrict the agent process’s operating system permissions. An administrator remains responsible for the execution environment. Code and task text may be sent to the selected agent and model provider, so consider this when choosing the data you work with. See limitations and data handling for details.

Lessons from practice and knowledge to retain

The first months of use, described in the August 25, 2026 article “Practical implementation of AI‑Disrupt PDLC concepts,” showed the value of a unified history: scenario versions, results, reasons for rework, and human decisions remain visible. At that stage there was insufficient comparable data to assess speed or quality improvements; no specific percentage gain is attributed to the platform.

Compare tasks performed in HG SDLC with your usual approach using the whole team's time, result quality, and the cost of mistakes. An orchestrator does not itself make the agent stronger or replace a good specification, context, and checks.

The team's lasting asset is knowledge of the product and system, constraints, architectural decisions, and actual results. Instructions, skills, and the division of work into steps will change as models evolve. Recorded knowledge should accumulate independently of the chosen tool; validated scenarios help apply it, and execution history helps refine it.

Documentation version

• Handbook revision date: September 29, 2026.
• Target product version: 2.2.0.
• Baseline for capability descriptions: tag v2.2.0, commit ee2b155d.
• Release branch: release/2.2.0.

Feature availability depends on your role, settings, and installed agents. For a build with changes after the release, also check its tag or commit. Check the contents of published releases on GitVerse releases.

Project and feedback

• The workflow concept, boundaries, and development directions follow the August 25, 2026 article “Practical implementation of AI‑Disrupt PDLC concepts.”
• Project README — installation methods and the supported agent table.
• Source code on GitVerse.
• Project issues — include the version, reproduction steps, and a log with secrets removed.
• Apache 2.0 license.

HG SDLC capability map

Find your task in the list and open its description. Each section explains who can use the capability, how to use it, and what to check if an error occurs.

Statuses

Status	Meaning
Implemented (implemented)	The feature is implemented in the target release 2.2.0 (v2.2.0); availability depends on your role, settings, and installed agents.
Experimental (experimental)	The feature is implemented but has experimental status and availability restrictions.
Partial (partial)	A useful scenario is available, but the description explicitly records its limitations.
Planned (planned)	The feature is described as a future direction but is not yet available to users.
Deprecated (deprecated)	The feature is being retired and should not be used in new scenarios.

High-level map

HG SDLC
├── Access and work organization
├── Projects and repositories
├── Flow / Skill / Subagent catalog
├── Flow design and debugging
├── Runs and schedules
├── Human-in-the-loop
├── Code, workspace, and artifacts
├── Result publication
├── Integrations and platform connections
├── Observability and analytics
├── Application installation and management
├── Quality evaluation
└── AI assistant

Feature registry

1. Access and work organization

ID	Capability	Status	Details
ACC-001	Authentication and sessions	Implemented	Description
ACC-002	User and team management	Implemented	Description

2. Projects and repositories

ID	Capability	Status	Details
PRJ-001	Project and repository management	Implemented	Description
PRJ-002	Project rules and publication templates	Implemented	Description

3. Reusable component catalog

ID	Capability	Status	Details
CAT-001	Flow, Skill, and Subagent catalog	Implemented	Description
CAT-002	Catalog versioning and lifecycle	Implemented	Description

Development rules are not a separate entity in the global catalog: in the current version, they are configured at the project level.

4. Workflow design

ID	Capability	Status	Details
FLW-001	Visual and YAML Flow editing	Implemented	Description
FLW-002	Flow validation and debug runs	Implemented	Description

5. Workflow execution

ID	Capability	Status	Details
RUN-001	Launching a Flow	Implemented	Description
RUN-002	Managing the Run lifecycle	Implemented	Description
RUN-003	Scheduled runs	Implemented	Description

Flow execution is implemented; the simplified product owner interface has experimental status. See launch options.

6. Human-in-the-loop

ID	Capability	Status	Details
HITL-001	Processing Human Gates	Implemented	Description
HITL-002	Human takeover	Implemented	Description

7. Code and artifacts

ID	Capability	Status	Details
ART-001	Run working files, changes, and artifacts	Implemented	Description

8. Publication

ID	Capability	Status	Details
PUB-001	Catalog approval and publication	Implemented	Description
PUB-002	Publishing Run results	Implemented	Description

9. Integrations

ID	Capability	Status	Details
INT-001	External API and webhooks	Implemented	Description
INT-002	SCM, MCP, and coding agent connections	Implemented	Description

10. Observability

ID	Capability	Status	Details
OBS-001	Run Console, audit, and diagnostics	Implemented	Description
OBS-002	Server status and working file cleanup	Implemented	Description
OBS-003	Development status overview	Implemented	Description
OBS-004	Team and project autonomy analytics	Implemented	Description

11. Quality evaluation

ID	Capability	Status	Details
BEN-001	Benchmarking	Experimental	Description

12. AI assistant

ID	Capability	Status	Details
AST-001	Contextual chat and change proposals	Implemented	Description

13. Application installation and management

ID	Capability	Status	Details
OPS-001	User CLI	Implemented	Description

How the capabilities connect

1. An administrator connects SCM, a coding agent, and MCP servers if needed.
2. A user creates a project and links it to one or more repositories.
3. A configurator creates or selects a Flow, Skills, and Subagents.
4. An operator launches the Flow manually, on a schedule, or through an integration.
5. The runtime executes the steps, records changes, and pauses at Gates that require a response according to the approval mode.
6. An authorized user accepts the result, requests rework, or takes over the work.
7. The platform publishes branches or Pull Requests and saves the execution and decision history.
8. Results appear in analytics and are used by external systems through events and APIs; experimental Benchmark compares variants on sets of tasks.

Roles and permissions

If a button is missing or an action is unavailable, start by checking your role. HG SDLC has platform-wide roles and team roles. Access also depends on the project's team and the state of the Run or Gate.

Global roles

ADMIN

Platform administrator. Manages users and teams, settings, API keys, MCP/SCM connections, the catalog, runs, publications, and benchmarks.

FLOW_CONFIGURATOR

Platform operator and configurator. Creates and publishes catalog items and manages runs, schedules, the runtime, and benchmarks. User management and certain sensitive operations, such as MCP secrets and API keys, remain restricted to ADMIN.

Team roles

PRODUCT_OWNER

Works with projects belonging to their team. Can create team projects, view the catalog, and launch the “idea → development” product workflow through the experimental product owner interface. Cannot edit the catalog, project rules, or publication templates, manage Runs through the technical console, or manage schedules.

TEAM_MEMBER

Works with projects belonging to their team. Can view and modify accessible projects and work with Runs and Human Gates within their team. Cannot launch the product workflow and does not have platform operator permissions.

TECH_APPROVER

Retained for compatibility. Choose current roles for new users; permission to respond to Gates depends on current rules and project access.

Key capabilities matrix

Capability	ADMIN	FLOW_CONFIGURATOR	PRODUCT_OWNER	TEAM_MEMBER
View the global catalog	Yes	Yes	Yes	Yes¹
Edit and publish the catalog	Yes	Yes	No	No
Create a project	Yes	Yes	Within their team	Within their team
View projects and Runs	All	All	Their team	Their team
Edit project rules	Yes	Yes	No	Within their team
Launch from the product owner interface (experimental)	Yes	Yes	Within their team	No
Launch and manage through Run Console	Yes	Yes	No	Within their team
Respond to Human Gates	Yes	Yes	Within their team	Within their team
Manage schedules	Yes	Yes	No	Within their team
Use experimental Benchmark via a direct link	Yes	Yes	No	No
View analytics for selected teams	Yes	Yes	Yes, without restriction to their team	Yes, without restriction to their team
Manage users and teams	Yes	No	No	No
Edit MCP and API keys	Yes	Limited²	No	No

¹ The REST catalog is accessible to authenticated users; individual UI routes may provide a narrower view.

² FLOW_CONFIGURATOR can edit ordinary runtime, catalog, and SCM settings, but managing MCP configuration containing secrets and API keys requires ADMIN.

Analytics is available to all four listed roles. This is an exception to the usual team restriction for projects: the current analytics API filters data by request parameters without restricting it to the user's team. The UI merely selects the user's own team by default; see the analytics description. Benchmark is available only to platform operators at /benchmark in the installed application and is absent from the main menu.

Visibility rules

• Global operators can see projects, Runs, Gates, and schedules across all teams.
• A team user's access to projects, Runs, and Gates is limited to their own team. Analytics and the shared catalog have the separate rules described above.
• A request for an object outside the accessible team returns it as unavailable to avoid disclosing its existence.
• The server checks action permissions; hiding a button or UI route is an additional safeguard, not the source of truth.

Checking permissions

If an expected action is unavailable, check your role, the project's team, and the object's state. When contacting your administrator, include the application version, section, and action.

HG SDLC glossary

For your first run, three concepts are enough: a Flow describes the workflow, a Run is a specific execution of it, and a Gate is a step for obtaining information or a human decision according to the approval mode. Refer to the remaining terms here as you work.

Workflow and participants

Term	Meaning
Flow	A versioned workflow graph with allowed loops: steps, transitions, expected results, checks, and approval points.
Run	One execution of a Flow for a project. It saves parameters, component versions, and information about execution and results.
Result contract	Requirements for a step's result: required artifacts and expected file changes. Checks are performed in the cases supported by the node type.
Node — step	One step of a Flow: agent work, command execution, approval, or another supported type. The UI may call it a node.
Gate / Human Gate	A Flow step for obtaining a human decision or information. The run waits for a response if the selected approval mode requires it.
Human Input	A Gate for obtaining missing information.
Human Approval	A Gate for reviewing a result: it can be accepted or sent back for rework.
Rework	A return from a Human Gate or AI Node to an allowed step with corrective instructions. Routes are defined in the Flow; settings determine whether workspace changes are preserved or rolled back.
Human takeover	The ability to fix working files yourself at a Gate, then return control to the workflow.
Coding agent	An external agent that reads instructions and works with code through the configured runtime.
Product owner interface	An experimental product owner interface for launching a prepared workflow from a task description and reviewing progress, results, and human decisions.
Platform operator	A user with the ADMIN or FLOW_CONFIGURATOR role. These roles manage workflows and the catalog; their administrative permissions differ.

Projects, catalog, and files

Term	Meaning
Project	Repositories, rules, and publication settings grouped around a development task and an owning team.
Alias	A short repository name, such as main or backend. At launch, names from the Flow are mapped to project repositories.
Catalog	A shared registry of Flows, Skills, and Subagents that can be used in projects.
Skill	A versioned set of instructions and additional files for an agent.
Subagent	A description of a specialized agent, such as a code reviewer, which an AI node adds to its working context.
Workspace — working directory	A separate Run directory with copies of selected repositories and supporting files. It does not, by itself, isolate the process at the OS level.
Artifact	A saved step result: a document, data, or another file. Artifacts have versions and either run or project scope.
Checkpoint	A local Git snapshot before the first execution of an AI node. Used for comparison and rollback; it may be reused during rework.
Diff	A comparison of files with their initial state or a checkpoint.
Scope	For the catalog, team/organization defines ownership and publication. For artifacts, run/project determines how the result is used. Scope does not replace permission checks.

Connections and publication

Term	Meaning
SCM provider	A configured connection to a Git hosting service and its API: reading repositories, pushing branches, and creating Pull Requests.
MCP server	A server providing additional tools to an agent. An AI node references servers in the mcp_refs field.
ACP	Agent Client Protocol: the protocol used by the platform to communicate with an agent, including session management and model selection.
Runtime	The part of the platform that starts and coordinates Flow steps and agent processes.
Runtime variable	A value substituted into a step instruction during execution: run.*, step[nodeId].*, or env.*.
Preflight	A check of model availability and parameters before launch. If a model replacement is needed, the user confirms it.
Catalog publication	Moving a verified version of a Flow, Skill, or Subagent into a state available for normal runs.
Run result publication	Sending changes to Git: to a working branch, directly to the selected branch, or through a Pull Request.
Pull Request (PR)	A request to incorporate changes from one branch into another, created on the Git hosting service.

Comparison and analytics

Term	Meaning
Benchmark	An experimental section for comparing models and Flow variants on the same tasks.
Suite	Tasks, execution variants, and their evaluation parameters.
Cell	The result of one “variant × task” pair, including its run and evaluation.
Judge	A method for evaluating results in Benchmark; it can be a separate Flow.
Autonomy	Metrics showing how much human involvement was planned and required in a workflow. The analytics section does not grant permissions to an agent.

How terms are used

The Russian version uses Russian names for Flows, Runs, Skills, Subagents, and Human Gates. In instructions, “step” means a Flow node, “working directory” means Workspace, and “rework” means returning work for revision. Exact field names, commands, and statuses are formatted as code.

Publishing the catalog, publishing a Run result, and publishing this handbook to GitVerse Pages are three different actions. The relevant sections always specify what is being published.

Limitations and handling data

Before working on a shared server, check who can see the data and what information the agent receives. This section helps you choose suitable settings and understand the boundaries of the current implementation.

Relationship to AI-Disrupt PDLC

HG SDLC lets a team configure intent and implementation loops through a Flow. The validation spine and governance mesh are partially implemented: validation steps, roles, Gates, and decision history are available. A complete evidence bundle, risk-adaptive permissions, and control across the entire lifecycle require further work.

When preparing a scenario, connect intent and hypotheses to architectural decisions, specifications, implementation, and checks. A failed check should then identify the violated requirement and where to return the work. This is a requirement for process design; a Run log alone does not provide that traceability. OpenFastTrace is one possible tool for linking requirements and checks when using OpenSpec.

Run automated checks where a verifiable result appears. At each Human Gate, define the reviewer, decision criteria, blocked action, and escalation path for disagreements — a map of human participation in decision-making. Decisions need changes, artifacts, and check results; an agent's claim that the work is done is insufficient.

Outcome check remains a development direction. After deployment, return to the original hypothesis, configure and measure business metrics, and feed the results into the next change cycle. A technically accepted change and a successful Run do not yet prove that the business goal was achieved. Run analytics helps investigate workflow execution but does not replace that cycle.

Versions and repeatability

A Run saves launch parameters and component versions. Repeating execution helps reproduce the conditions, but model responses and external service state may change. This handbook targets release 2.2.0 with tag v2.2.0; the revision date is listed on the home page. For a build with changes after the release, also check the tag or commit, and check feature availability against its role, configuration, and agent requirements.

Access to team data

Projects, Runs, and Gates are restricted to the user's team, except for global operators. Analytics has an exception: in the current code, its API is available to the four main roles and filters data by request parameters without restricting it by team membership. Selecting your own team by default in the UI does not isolate analytics data. Consider this when choosing who can access a shared installation; see permissions.

The catalog is also available to authenticated users: team scope determines ownership and publication, not the confidentiality of an item's details.

Agents and external services

The agent runs with the permissions of the configured process. Separate Run working directories do not replace OS or container isolation. Project rules are instructions to the agent; change validation is defined separately through Flow contracts and commands.

Task context, source code, and screen contents may be sent to the configured agent and model provider. Masking known secret fields in the UI and assistant context does not guarantee removal of arbitrary secrets from task text, files, and logs. Configure connections and the data you send according to your team's requirements.

History and file retention

History includes Run states, node attempts, and Gate decisions. The audit trail does not record every user or agent action. After workspace cleanup, history is retained, but files removed from that workspace can no longer be viewed or published.

Publication to multiple repositories can partially succeed. Check the result for each repository separately. Retrying publication and Force publish have different conditions; see details.

Experimental features

Benchmark is available to platform operators at /benchmark inside the installed application and is hidden from the main menu. Its results depend on the selected tasks, models, and evaluation method.

The product owner interface is experimental. It focuses on the task, progress, results, and human decisions and is an initial step from SDLC toward PDLC. Its launch form is available at /product-pipeline; the documented roles and launch conditions still apply.

Development directions

The following directions are described in the August 25, 2026 article. They outline further work and do not mean that the listed capabilities are already available as complete features.

• Digital employees. Combine several AI scenarios into a working role with a single entry point that selects a suitable scenario for the task. Early experiments use existing schedules and MCP for one or two scenarios, such as reviews or bug fixes. One example reads assigned Jira tasks, performs the work, creates a PR, and moves the task to a state awaiting human review. A convenient, integrated role remains a development goal.
• Context management. Prepare the knowledge each stage needs about products, systems, repositories, contracts, and owners. A knowledge graph or another structured model should account for freshness, provenance, applicability, and access rights (Context Supply Chain). Connecting a source through MCP alone does not solve this problem; putting more documents into context can hinder the work.
• Improving workflows from execution history. Analyze recurring causes of Rework and Human Takeover and propose changes to instructions, skills, and the sequence of steps. A person accepts or rejects each proposal. Human feedback is a signal to validate: requirements may have changed, or a correction may reflect a personal preference. Fewer returns caused by weaker checks are not an improvement; quality criteria and risk boundaries must remain intact.
• Approval by several people. Add Human Gates that require approval from multiple participants.

Accumulated product and system knowledge should survive changes of models and tools. Eventually, business hypothesis outcomes can complement execution history and inform the next intent cycle; a person remains responsible for deciding which goal to pursue.

How to read addresses in this handbook

UI paths such as /settings and /run-console refer to your HG SDLC installation, not the documentation website. Technical guides and source files open in the GitVerse repository and require network access. Feature descriptions within the handbook are available through its menu and search.

Installation and first sign-in

If your team has already deployed HG SDLC, get the address and an account from your administrator, then proceed to your first workflow. GitVerse Pages hosts this handbook; the application itself runs separately.

Choose an installation method

Method	When to use it	Requirements
From source	For exploration and development	Git, Java 21, Node.js 22 from .nvmrc, npm; Docker Compose for PostgreSQL
CLI	To run a ready-made JAR without building	Java 21+, Node.js 18+ and npm, a distribution server address from your administrator
Docker Compose	For a prepared server installation	Application images, database configuration, and agent credentials

Below, we walk through a local installation from source on Linux, macOS, or Windows with WSL. To use AI nodes, also install and authenticate your chosen agent on the backend machine.

1. Get the source code

git clone https://gitverse.ru/kakvsbere/hgsdlc.git
cd hgsdlc

2. Start PostgreSQL

From the repository root:

docker compose -f deploy/compose.dev.yaml up -d
docker compose -f deploy/compose.dev.yaml ps

The local configuration uses localhost:5432, the database and user hgsdlc, and the password hgsdlc. These are development settings. Wait until the container is ready.

3. Start the backend

From the repository root:

cd backend
SPRING_PROFILES_ACTIVE=local,postgres ./gradlew bootRun

Leave the terminal open. Check that Gradle uses Java 21. Database migrations are applied when the application starts.

4. Start the UI

In a second terminal, from the repository root:

cd frontend
npm ci
npm run dev

Open the address shown by Vite; the default is http://localhost:5173.

5. Check the installation

In a third terminal:

curl -fsS http://localhost:8080/actuator/health

Expect status: UP in the JSON response. Sign in to the UI as admin with the password admin. These credentials are for local development only; use personal accounts in a shared installation.

Empty project and run lists are normal for a new installation. Next, configure an agent, the catalog, and your first project.

If the application does not start

Symptom	What to check
Database connection error	Container readiness, availability of port 5432, and the local,postgres profile
Java version error	The output of java -version and whether Java 21 is selected
The UI opens, but requests fail	The backend log and the /actuator/health response on port 8080
The UI port is in use	The actual address in the Vite output
No models are available	Agent installation, authentication, and settings on the backend machine

Stopping

Stop the backend and UI with Ctrl+C. Then stop PostgreSQL from the repository root:

docker compose -f deploy/compose.dev.yaml down

PostgreSQL data remains in the volume. For a quick check, you can use H2 mode, but its in-memory data is not retained after stopping the backend.

First workflow: from a task to a Git branch

The goal is to add a small file to a test repository, complete approval, and see the result in Git. Start with a working installation. Initial setup is performed by ADMIN or FLOW_CONFIGURATOR; creating users and teams is available to ADMIN.

1. Configure an agent

Install the CLI or ACP adapter for your chosen coding agent and authenticate it as the OS user that runs the backend. In Settings → Runtime, select the agent, load its default settings, and save them. Check that the model list can be retrieved.

Supported agents: Qwen, Claude, GigaCode, Codex, and OpenCode. Selecting an agent in the UI does not automatically install or authenticate it. Detailed connection commands are provided in the agent guide.

2. Connect SCM and the catalog

In Git/SCM settings, add a provider for your Git hosting service. GitVerse uses the compatible Gitea/GitVerse type. Credentials must allow reading the repository and pushing a test branch; store them in connection settings, not in the repository URL.

In Settings → Catalog, specify the test catalog and the branch for your chosen agent:

Agent	Catalog branch
Qwen	qwen
Claude	claude
GigaCode	gigacode
Codex	codex
OpenCode	opencode

Save the settings, import/restore the catalog, and check that Flows, Skills, and Subagents appear. Select a published smoke Flow compatible with your agent. The example's name and contents depend on the catalog branch.

3. Create a project

1. Create or select a team, then open Projects and create a project for that team.
2. Add a test Git repository that you have permission to push changes to.
3. Give it the alias main and an existing source branch — for example, main, if that is its name in your repository.
4. Select the corresponding SCM connection.
5. Add project rules: validation commands, style requirements, and restrictions on files containing secrets.

Rules are passed to the agent as instructions. Use Flow commands and contracts for mandatory checks; the rule text alone does not guarantee compliance.

4. Launch the Flow

In the technical launch form, select the project and a published smoke Flow. This tutorial is intended for a platform operator or team member with technical launch permissions. PRODUCT_OWNER uses the separate procedure for the product owner interface: that form does not offer require_all_gates and skips Gates without PRODUCT_OWNER in allowed_roles.

Map Flow aliases to project repositories. Select a source branch and a new working branch, for example hgsdlc/hello-01; use another available name when repeating the exercise. Select a model from the list, Branch publication mode, and the require_all_gates approval mode so that the workflow waits for a response at every Gate.

Enter the task:

Add a small text file named hello-hgsdlc.md describing the project, and verify that it exists using a command.

Launch the workflow. If the model check suggests a replacement, review it and confirm a suitable option or correct the agent settings.

5. Review the result and make a decision

Monitor the graph and step log in Run Console. At Human Input, provide the requested information. At Human Approval, open the file changes, artifacts, and validation command result. Accept the result or submit specific feedback for rework.

The route depends on the selected Flow: its graph defines the approval points. After successful execution and publication, open the working branch on your Git hosting service and check that hello-hgsdlc.md exists. Branch mode does not automatically create a Pull Request.

If the workflow stops

Situation	Next step
No smoke Flow is available	Check the import, published status, and that the catalog branch matches the agent
The model is unavailable	Check Runtime and agent authentication on the backend machine
A Skill or Subagent is missing	Check dependency import and Flow validation
The Run is waiting for a person	Open the current Gate in Run Console or the approvals inbox
A command or artifact check failed	Read stdout/stderr and node diagnostics; fix the cause before retrying
Push failed	Check SCM permissions, the working branch, and publication status; for PUBLISH_FAILED, retry publication after fixing the cause

Next: managing execution, publishing a result, detailed diagnostics.

Journey: guided development

After your first run, try the workflow on your own task: choose a prepared Flow, follow its changes, and review the result at approval.

Who participates

PRODUCT_OWNER launches the experimental product owner interface for their team. ADMIN, FLOW_CONFIGURATOR, and TEAM_MEMBER with project access use the technical launch form. The agent performs AI steps, while a person responds to Gates within their permissions.

The product owner interface uses require_po_gates_only and branch publication (branch). It waits for responses only at Gates with PRODUCT_OWNER in allowed_roles; other Gates, including those without a role list, are skipped. Check the required approval settings before launch. If every Gate needs review, an authorized user launches through the technical form with require_all_gates.

Follow the workflow

1. Select a project and Flow, and describe a verifiable task result. In the technical form, also select repositories, branches, model, and publication mode; choose require_all_gates for review at every Gate. The product owner interface uses the fixed modes described above.
2. For a technical launch, wait for model preflight: confirm a suggested replacement or correct the settings. If the product owner interface cannot start the task, inspect the error and involve someone with configuration permissions.
3. Open the created Run. The platform saves its parameters and prepares working files, project rules, and catalog components.
4. Follow the graph and log. A checkpoint is saved before the first execution of an AI node; expected changes and artifacts are checked after the step.
5. When the workflow reaches a Gate, review the changes and respond to the request. You can accept the result, provide more information, request rework, or fix files manually.
6. After the graph completes successfully, check publication. For new runs, the result is sent to Git according to the selected mode; status is shown separately for each repository.

Example: from specification to publication

Consider the task “add a Version button.” Prepare a Flow based on your SDD process, such as OpenSpec or Spec Kit. This illustrates a scenario design; it is not a catalog template guaranteed to be installed.

Step	Work performed and handed to the next step
Specification — AI Node	The agent studies requirements and code, describes the button's placement, affected APIs and SDKs, compatibility, and validation criteria. The specification becomes input to implementation.
Specification approval — Human Approval Gate	A person reviews scope, decisions, and acceptance criteria. Feedback returns the work to specification preparation.
Code and tests — AI Node	The agent implements the agreed change, updates tests and, if needed, migrations, and retains review materials.
Automated checks — Command Node	Build, tests, and configured security checks run. Failures lead back to correction and another check; the loop has an exit condition and an iteration limit.
Acceptance — Human Approval Gate	A person receives changes, artifacts, and check results, then accepts the work or returns it to the appropriate step.
Completion and publication	A successful Terminal ends the route, after which the platform publishes changes in the selected mode, such as a branch or PR.

A development stage can include several AI nodes, command checks, and approval. A graph node is not equivalent to a whole production stage. If information or a human choice is missing, add a Human Input Gate where needed. The graph snapshot, attempts, artifacts, and decisions remain in the history of the specific Run.

Define allowed return routes from Gates and AI Nodes: a code defect returns to implementation, while an incorrect assumption in requirements returns to specification. Requirement changes should remain visible in the agreed materials. Decide whether to remove control points after validating the scenario on real tasks and assessing benefits and risks; the assessment may show that approvals need to remain.

How to give useful feedback

Instead of “make it better,” specify exactly what needs to change and how to verify the fix. For example: “Name the missing field in the error message and add a test for an empty value.” When requesting rework with rollback, remember that changes after the selected checkpoint will be removed.

Workspace rollback does not undo external actions: notifications already sent, publications, and changes to other systems may require separate recovery. To correct the result yourself, use Human Takeover: temporarily take the executor role in an IDE or the built-in editor, validate the edits, and return control to the workflow.

If execution stops

What you see	What to do
Human Input	Provide the missing information.
Human Approval	Review the result and accept it or submit feedback.
Step error	Read the log and fix the cause; retry the step if the action is available.
CRASHED after a backend restart	Open the details and select Recover if the working directory has not been cleaned up.
PUBLISH_FAILED	Fix the cause of the Git push failure and retry publication.

Run history saves states, step attempts, and Gate decisions. Files remain available until the working directory is cleaned up. For older runs in local mode, the result remains only in that directory.

Further reading

• Launching a Flow
• Run lifecycle
• Processing Human Gates
• Human takeover
• Workspace, code, and artifacts
• Publishing a result

Journey: publishing a result

Once changes have been reviewed, make sure they reached Git. Successful execution of steps and successful publication are separate stages: for example, an agent may finish the task while the Git server rejects the branch push.

Before you begin

For normal publication, the necessary steps and approvals required by the run mode must be completed, and the Run must not be canceled. Check that the SCM connection has permission to push changes, the working branch name is available, and an appropriate publication mode is selected.

Choose the result

Mode	What appears in Git
Branch (branch)	A separate working branch containing the changes.
Direct push (direct_push)	Changes directly in the selected branch.
Pull Request (pr)	A working branch and a request to merge it into the target branch, if the SCM supports PR creation.

For your first attempt, Branch mode and a test repository are convenient. Flow Debug also uses branch. The local mode is retained for older Runs and is not offered for new normal runs.

Check publication

1. Open Run Console and check the publication status of each repository.
2. If successful, go to your Git hosting service: check the branch, commits, and, for PR mode, the created Pull Request.
3. If outgoing webhooks are configured, check the notification delivery history for the external system.
4. If publication failed, read the error. Common causes include access permissions, an unavailable SCM, branch conflicts, or a push restriction on the Git server.
5. Fix the cause and retry publication for a Run in PUBLISH_FAILED. You do not need to execute the Flow steps again.

A publication error does not, by itself, delete working files, but configured cleanup may remove them later. Once cleanup has run, those files can no longer be pushed from the Run. When working with multiple repositories, check each one: some changes may have reached Git before the failure.

Pushing a branch or creating a Pull Request does not mean merging changes or releasing the product. Checks, merging, and deployment follow the target repository's rules.

If the Run itself failed

Force publish is a separate action for sending work already completed in FAILED. It is available only when server-side conditions are met. Review the changes before pushing: a failed Flow does not confirm that the result is ready. Force publish conditions are described separately.

Further reading

• Publishing Run results
• Platform connections
• External API and webhooks
• Run Console and audit

User journeys

Choose a scenario for your task: prepare a first run, manage execution, or publish reviewed changes.

Journey	Main actor	Result
First project	Administrator / configurator	The first Flow has run, and its result is published to a test branch.
Guided development	Operator / team member	A coding agent has executed a Flow under human supervision.
Publishing a result	Operator / approver	Accepted changes are published to Git/SCM.

Authentication and sessions

Sign in with your account to work with projects and Runs. Your assigned roles determine the actions available to you, and your team determines access to projects.

Who can use it

Everyone working through the platform interface needs to sign in. External systems use API keys and are covered in External API and webhooks.

Before you begin

• The account is active and has a password.
• The user submits a username and password on the sign-in page.

How it works

1. Open the sign-in page and enter your username and password.
2. After sign-in, HG SDLC loads your profile and the sections available to you.
3. Work with projects: the server checks permissions on every request.
4. Sign out when you finish. The session token becomes invalid.

Things to consider

• Invalid credentials do not reveal whether the user exists.
• An expired or invalid token requires authentication again.
• An inactive account cannot obtain a new session.

Parameters and result

• Parameters: username and password.
• Result: a session token and the current user's profile with roles and team scope.

Permissions

Sign-in does not require an active session. All product features require authentication, except health/version checks and integration requests protected separately.

Where to find it

• In the application: /login.

Further reading

• Roles and permissions
• User and team management

User and team management

This is where an administrator builds a team: creates accounts, assigns roles, and chooses which projects each member will work with.

Who can use it

• ADMIN manages users and teams.
• Other roles use their assigned permissions and see only the teams available to them.

Before you begin

• The administrator is authenticated.
• An active team exists before a team role can be assigned.

How it works

1. Create a team or select an existing one.
2. Add a user: enter a name, password, and role.
3. For a team role, select the team the user belongs to.
4. Update the profile when permissions change. Reset the password or disable the account if needed.
5. Check the assigned roles: they determine access to subsequent actions.

Things to consider

• You cannot assign a team role without an available team.
• Knowing a project's ID alone does not grant access to another team's project.
• Deleting or deactivating a user does not delete the audit records they created.

Parameters and result

• Parameters: user or team details, a global or team role, and the team ID.
• Result: accounts and roles that the platform uses to check access.

Permissions

User management and the administrative team registry are available only to ADMIN. A regular user can retrieve a list of teams within their scope.

Where to find it

• In the application: /users.

Further reading

• Authentication
• Project management
• Role matrix

Project and repository management

Start with a project: specify a team and connect the repositories the agent will work with. A single project can bring together several repositories, such as backend and frontend.

Who can use it

• ADMIN and FLOW_CONFIGURATOR work with all projects.
• PRODUCT_OWNER and TEAM_MEMBER work with their team's projects.

Before you begin

• The team that owns the project exists.
• A suitable SCM connection is configured for remote repositories.
• The user creates or opens a project.

How it works

1. Enter the project name and the owning team.
2. Add one or more Git repositories.
3. Give each repository a short, unique name — an alias — and a default source branch.
4. Select an SCM connection to the same Git hosting service.
5. Save the project. When launching a Flow, you can select the repositories you need, map them to names in the Flow, and specify branches.

Things to consider

• Duplicate aliases are rejected.
• The repository host must match the selected SCM connection.
• A project can be archived to exclude it from new workflows.
• Physical deletion is available only when current data constraints allow it.

Parameters and result

• Parameters: name, team ID, repositories, SCM connection, and project description.
• Result: a project with a stable ID, access scope, and repository settings.

Permissions

Team users can create projects only within their own team. Only ADMIN can change the team of an existing project.

Where to find it

• In the application: /projects.

Further reading

• Project settings
• Launching a Flow
• Platform connections
• The multi-repository model is described in the 2.0 release notes.

Project rules and publication templates

Write down the rules your agent needs to know about the project: how to build the code, which checks to run, and which style to follow. Commit message and Pull Request templates are also configured here.

The agent receives the rules as instructions. If a condition must be checked, add the corresponding command or contract to the Flow.

Who can use it

• Platform operators configure all parameters.
• TEAM_MEMBER can edit rules for their team's projects.
• PRODUCT_OWNER can view the project but cannot edit rules or publication templates.

Before you begin

• The project exists and is accessible to the user.
• The user opens the project settings.

How it works

1. Open the project settings and select a rules template for your agent, or write the rules yourself.
2. Specify build and check commands, details of the project structure, and requirements for changes.
3. Save the rules and configure commit and Pull Request templates.
4. Create a new Run to check the settings. It receives a snapshot of them; Runs that already exist retain their previous values.

Things to consider

• An unsupported agent type for a rules template is rejected.
• Empty rules are allowed if the Flow and project policy do not require them.
• Settings are captured when a Run is created. After changing the rules, check them in a new Run.

Parameters and result

• Parameters: rules text and agent type, publication templates.
• Result: saved project context for new Runs.

Permissions

PRODUCT_OWNER cannot edit rules. Publication templates can be edited by platform operators and authorized team members, except PRODUCT_OWNER.

Where to find it

• In the application: /projects/{projectId}/settings.

Autonomy is assessed separately in Analytics. These are metrics of human participation and Flow execution; this page has no setting for an allowed level of autonomy.

Further reading

• Workspace, code, and artifacts
• Publishing results
• Workspace Initialization
• Workspace Initialization technical design

Flow, Skill, and Subagent catalog

The catalog stores Flows, Skill instructions, and descriptions of specialized Subagents. Prepare them once and reuse them across projects.

Catalog contents

Entity	Purpose
Flow	Defines the development process graph: steps, transitions, requests for input, approvals, and result requirements — required artifacts and expected file changes (result contracts).
Skill	Contains instructions and supporting files for an agent.
Subagent	Describes a specialized helper agent for an AI node.

Project rules are configured within the project and are not part of the global catalog.

Catalog scopes

• team — the entity belongs to a team, requires a team code, and can be published directly by a platform operator.
• organization — the shared organization catalog; publication requires approval.

The catalog scope determines ownership and the publication channel. It does not hide the card from other teams: authenticated users can read the catalog, subject to UI restrictions. The run/project artifact scope serves a different purpose.

Who can use it

• All signed-in users can retrieve the available catalog through the API.
• ADMIN, FLOW_CONFIGURATOR, and PRODUCT_OWNER can view catalog cards in the UI.
• ADMIN and FLOW_CONFIGURATOR can edit them.

How it works

1. Find the Flow, Skill, or Subagent you need by name, tags, or status.
2. Open its card and select a version.
3. If you have editing permissions, create a draft of a new entity or version.
4. Add the content: a graph or YAML for a Flow, instructions and files for a Skill, or a role description for a Subagent.
5. Check the Flow's dependencies on Skills, Subagents, and MCP servers.
6. Publish the verified version to use it in production Runs.

Things to consider

• Validation rejects references to missing or unavailable versions.
• A draft cannot be used as a regular published dependency, except in the designated debug scenario.
• Deprecated versions remain in the history but are not recommended for new Runs.

Parameters and result

• Parameters: description, version, tags, content, and dependency references.
• Result: a catalog item version that a Flow or Run can reference.

Where to find it

• In the application: /flows, /skills, /subagents, and their respective editor pages.

Further reading

• Catalog versioning
• Editing a Flow
• Workspace Initialization

Catalog versioning and lifecycle

Edit a new version as a draft, verify it, and then publish it. Existing Runs retain their component versions. This helps you understand exactly what was executed, although the model's response may differ when you run it again.

Who can use it

ADMIN and FLOW_CONFIGURATOR can create versions, edit drafts, deprecate versions, and submit and process publications.

How it works

1. Create a draft of a new entity or version.
2. Make and verify your changes. Existing Runs are unaffected.
3. Submit the version for publication: an operator can publish a team version directly; an organization version requires approval.
4. After successful publication, select the new version when launching a Run. Synchronization with the Git catalog depends on the configuration.
5. If a version is no longer suitable for new tasks, mark it as deprecated. Its history is preserved.

Things to consider

• A draft can be deleted before it becomes a published version.
• Rejection preserves the reason and lets you correct the new version.
• A failed publication job can be retried without creating a duplicate publication.
• Concurrent decisions and repeated jobs are protected against duplicate execution.

Parameters and result

• Parameters: stable ID, semantic version, content, and publication data.
• Result: an entity version with lifecycle, approval, and publication statuses.

Permissions

Catalog viewing is available more broadly than editing. Saving, deleting a draft, deprecating a version, and making publication decisions require a platform operator role.

Where to find it

• In the application: catalog editors and /requests.

Further reading

• Catalog
• Catalog publication

Visual and YAML Flow editing

Build a development process from steps: ask an agent to change code, add a validation command, and include human approval. Work with the graph visually or in YAML — these are two representations of the same Flow.

Who can use it

• ADMIN and FLOW_CONFIGURATOR can create and modify Flows.
• PRODUCT_OWNER can view an available Flow without saving changes.

How it works

1. Create a Flow or open a draft version.
2. Add steps from the library and connect them with transitions.
3. For an AI node, configure the instruction, model, Skill, Subagent, MCP references, expected artifacts, and changes.
4. Add approvals, validation commands, and branches based on results.
5. Switch between the graph and YAML — the editor keeps both representations synchronized.
6. Fix any errors found and save the draft.
7. Test the Flow in debug mode, then publish its version.

Key rules

• Node IDs must be unique within a Flow.
• Transitions must reference existing steps.
• Loops are limited by max_loop_count.
• Flows for multiple repositories use short names (aliases). Map them to project repositories when launching a Run.
• Skill, Subagent, and MCP references must resolve to valid versions or configurations.

To stop when required outputs are missing, enable fail_on_missing_declared_output and fail_on_missing_expected_mutation in the Flow settings. Both switches are off in the initial form for a new Flow; setting required: true on an artifact or change does not replace these settings. expected_mutations describes expected changes and does not prohibit edits to other files; see validation details.

Things to consider

• Inconsistent YAML and graph representations cannot be saved as a valid Flow.
• Schema, transition, and contract errors are displayed before launch.
• An unsaved draft may be lost when you close or reload the page; save your changes before leaving.

Parameters and result

• Parameters: Flow description, graph/YAML, node settings, and catalog references.
• Result: a saved draft version ready for debugging or publication.

Where to find it

• In the application: /flows/create, /flows/{flowId}.

Further reading

• Catalog
• Validation and debugging
• Runtime Variables
• Node Validation

Flow validation and debug Runs

Test a draft Flow on a test project before publishing it. You can see how steps execute, where errors occur, and what changes in the code. Keep in mind that a debug Run can also push changes to Git.

Who can use it

ADMIN and FLOW_CONFIGURATOR.

Before you begin

• A draft Flow is open in the editor.
• An accessible project is selected, and the required environment variables and task description are entered.
• The user clicks “Debug run”.

How it works

1. Open the draft in the editor, select a test project, and specify the task and required variables.
2. Click “Debug run”. The platform validates the YAML, graph, dependencies, and contracts.
3. If validation succeeds, a Run is created with debug_mode and the source flow_debugger. The server selects branch publication mode and assigns a debug working branch.
4. Monitor the graph, log, and code changes; respond to Human Gates as execution progresses.
5. If an error occurs, read the diagnostics. Step retries and Run recovery are available only in an appropriate state.
6. After testing, return to the editor and publish the Flow version separately.

Things to consider

• A schema error blocks Run creation.
• If a model or catalog dependency is unavailable, preflight validation or launch fails. Read the error message and check the model settings or catalog references.
• If the error does not allow a retry, the node retry action is unavailable.
• A debug branch may be overwritten by another debug execution according to the mode's rules.

Parameters and result

• Parameters: draft Flow, project, task description, environment variables, and model selection.
• Result: a separate debug Run and diagnostic data; a published Flow version is not created automatically.

Where to find it

• In the application: /flow-debug?flowId=...&runId=....

Further reading

• Editing a Flow
• Launching a Flow
• Run Console and audit
• Node Validation
• Flow Debug capabilities are described in the 2.1 release notes.

Launching a Flow

Choose a task, project, and Flow — HG SDLC creates a separate Run. It stores the parameters, selected component versions, repositories, and model so you can understand the result later.

Ways to launch a Flow

Launch source	Who can use it
Run Console	ADMIN, FLOW_CONFIGURATOR, and TEAM_MEMBER within their team
Product owner interface (experimental)	ADMIN, FLOW_CONFIGURATOR, and PRODUCT_OWNER within their team
Schedule	The scheduler, on behalf of the user or policy that configured the schedule
External API	An external system with an API key
Benchmark	A platform operator
Flow Debug	ADMIN, FLOW_CONFIGURATOR

The product owner interface is experimental and simplified. It focuses on the task, progress, results, and human decisions; technical graph configuration remains in the Flow editor.

Before you begin

• The project is active and contains the selected repositories.
• The Flow version is valid for the selected type of Run.
• The AI agent and required model are available, or a valid replacement has been confirmed.

How it works

The following steps apply to the technical launch form for ADMIN, FLOW_CONFIGURATOR, and TEAM_MEMBER with project access. Use the separate procedure below for the product owner interface.

1. Select a project and a published Flow, and describe the task.
2. Set the required environment variables, AI session mode, and publication mode. Select a Gate mode: require_all_gates, require_po_gates_only, or skip_all_gates. Use require_all_gates for human review at every Human Gate.
3. Select repositories, map their names (aliases) to the Flow, and specify branches. Add outgoing webhooks if needed.
4. Select a model. If it is unavailable, review the suggested replacement or correct the agent settings.
5. Launch the process. HG SDLC validates permissions, dependencies, and parameters, stores them in the Run, and prepares the working directories.
6. Go to Run Console to monitor the steps and respond to approval requests.

Launching through the product owner interface

1. Select your team’s project and a prepared Flow, and describe the task.
2. Before launching, confirm that Human Gates requiring a product owner’s response include PRODUCT_OWNER in allowed_roles.
3. Start the workflow and follow its results and requests for human participation.

The product owner interface fixes gate_mode=require_po_gates_only and publish_mode=branch: this form does not offer review at every Human Gate or PR publication. Human Gates without PRODUCT_OWNER in allowed_roles, including Human Gates without a role list, pass automatically. A Human Gate in the graph does not guarantee a pause. If every Human Gate needs a response, an authorized user must use the technical launch form with require_all_gates.

Things to consider

• An unavailable model requires explicit confirmation of the suggested replacements or blocks launch.
• Inconsistent project and Flow aliases are rejected.
• If the working branch is in use, select a free branch or finish the blocking Run.
• Rerunning a completed Run opens a form with its saved parameters and warns about unavailable dependencies.

Parameters and result

• Parameters: project, Flow version, task description, variables, repositories, modes, webhooks, and model.
• Result: a Run ID, launch source, saved parameters, and initial status.

Where to find it

• In the application: /run-launch, /product-pipeline, and the “Rerun” action in Run Console.

Further reading

• Run lifecycle
• Schedules
• External API
• Run Lifecycle
• Workspace Initialization
• Model selection and rerunning are described in the 2.1 release notes.

Managing the Run lifecycle

The Run card shows what is executing now and whether your participation is needed. From here, you can stop the process, retry a step, or recover an interrupted Run. Available actions depend on the Run state and your permissions.

Who can use it

• ADMIN and FLOW_CONFIGURATOR manage Runs across all teams.
• TEAM_MEMBER manages Runs for projects within their team.
• PRODUCT_OWNER views Runs within their team and responds to available Human Gates, but does not perform technical Run management operations.

The availability of a specific action also depends on the Run's state.

What the platform does

1. Creates the Run in its initial state and starts execution.
2. The runtime selects the next step. Before the first execution of an AI node, it saves a checkpoint that may be reused during rework.
3. After the step, the platform checks the exit code, expected changes, and artifacts.
4. Selects the next step according to the Flow transition.
5. At a Human Gate, puts the Run into a state waiting for human input if the Gate mode requires it. Otherwise, it automatically follows the Human Gate transition.
6. After a response to an open Human Gate, continues the process or returns the work for rework.
7. After the graph completes successfully, starts publication. The final Run status also reflects its result.

Control actions

Action	When it applies	Result
Resume	The Run is waiting for a permitted continuation	Execution returns to the graph.
Cancel	The Run is active	No new steps start, and the Run ends as canceled.
Retry	The error allows a retry	The step eligible for another attempt is retried.
Recover	The Run is CRASHED and its working directory has not been cleaned up	Your action starts Run recovery.
Publish retry	The Run is PUBLISH_FAILED	Only publication is retried.
Force publish	The Run is FAILED, publication has not yet succeeded, the working directory has not been cleaned up, the error code permits the action, and the mode is not local	Your action publishes the work already completed; review it before pushing.

Things to consider

• An error during an automatic retry ends the Run with diagnostics instead of leaving it in RUNNING.
• After a backend restart, an executing Run moves from RUNNING to CRASHED. Open its card and select Recover if the working directory has not been cleaned up.
• Interrupted publication moves from WAITING_PUBLISH to PUBLISH_FAILED; use publication retry for it. These operations do not resume automatically.
• An invalid transition, an exceeded loop limit, or a node contract violation results in a controlled failure.
• Repeating a control action depends on the current Run state. After a network failure, refresh the Run card first.

Parameters and result

• Parameters: Flow snapshot, launch parameters, and Human Gate decisions.
• Result: final status, node attempts, artifacts, audit trail, and publication status.

Where to find it

• In the application: /run-console, /flow-debug.

Further reading

• Handling Human Gates
• Workspace, code, and artifacts
• Run Lifecycle
• Node Validation
• Node Checkpoint
• Agent Quarantine

Scheduled Runs

Set a schedule when you need the same process regularly. For example, you can run a prepared Flow every night. You also choose what to do if the previous Run has not finished yet.

Who can use it

• ADMIN and FLOW_CONFIGURATOR manage all schedules.
• TEAM_MEMBER manages schedules for projects within their team.
• PRODUCT_OWNER does not manage schedules.

How it works

1. Select a project and a published Flow.
2. Set the cron expression, time zone, and launch parameters.
3. Decide how to handle overlapping Runs: skip the new Run, queue one Run, or run in parallel.
4. Enable the schedule and check the next run time.
5. If needed, pause the schedule or run it immediately without waiting for the next scheduled time.

Overlap strategies

Strategy	Behavior while the previous Run is active
SKIP	The new Run is skipped.
QUEUE_ONE	One pending Run is retained.
START_ANYWAY	A new Run is created in parallel.

Things to consider

• If the cron expression or time zone is invalid, correct it before saving.
• If a scheduled Run did not start, open the schedule and read the error message.
• If the project or Flow has changed, check the availability of the saved parameters before enabling the schedule again.

Parameters and result

• Parameters: cron expression, time zone, overlap strategy, and Run parameters.
• Result: a manageable schedule with a status and next run time.

Where to find it

• In the application: /schedule.

Further reading

• Launching a Flow
• Run Schedule
• Run Schedule technical design

Handling Human Gates

A Human Gate is a Flow step for obtaining input or a decision from a person. If the selected Run mode requires this Human Gate, execution pauses until a response arrives. Review the changes, add details to the task, or request rework. After the decision, execution follows the corresponding Flow branch.

Approval of a step's result does not mean advance approval of every agent command. Actions within an AI step depend on the agent, its settings, and the tools available to it.

Who can use it

• Platform operators can see Human Gates across all teams.
• PRODUCT_OWNER and TEAM_MEMBER respond to Human Gates for projects within their team.

Human Gate types

Type	Purpose	Main actions
Human input	Obtain missing information	Submit input
Human approval	Review a step's result	Approve, request rework

Gate modes

The gate_mode is set at launch and determines which Human Gates require a response.

Mode	Behavior
require_all_gates	All Human Gates require a response. Use this for a first Run with human review.
require_po_gates_only	Only Human Gates with PRODUCT_OWNER in allowed_roles require a response. All other Human Gates, including those without a role list, are skipped.
skip_all_gates	All Human Gates are skipped without a human response.

When Human Input is skipped, the process automatically follows the on_submit transition; when Human Approval is skipped, it follows on_approve. A gate_auto_skipped event is recorded in the audit trail. Having a Human Gate in the graph does not by itself guarantee a pause for approval.

Decide whether to remove control points after validating the workflow on real tasks and assessing benefits and potential risks. The assessment may justify retaining approvals. For each Human Gate, define the reviewer, decision criteria, blocked action, and escalation path for disagreements.

How to use it

1. Open a pending Human Gate in the approval inbox or on the Run card.
2. Read the summary and review artifacts, file changes, and the log. If needed, ask the agent a question in the Human Gate chat.
3. For Human Input, provide the missing information. For Human Approval, accept the result or describe what needs to be fixed.
4. Submit your response. Your decision and its time are recorded in the history, and the Run continues along the corresponding transition.

Rework

Rework returns work to a selected allowed step with corrective instructions. Returns can originate from a Human Gate or an AI node along routes defined in the Flow. An AI node can have several return targets: a code defect calls for implementation rework, while an incorrect assumption in requirements calls for a specification update. Requirement changes should remain visible in the revised specification.

• Instructions can apply to the entire result, a file, or a selected fragment.
• Rework settings determine whether to resume the previous AI session and preserve changes from the failed attempt.
• If you choose to roll back changes, the platform restores the working files to the checkpoint before retrying. Edits made after that checkpoint are lost.

Rollback restores working files to the target step's checkpoint. It does not undo notifications already sent, publications, or changes to external systems; those actions may require separate recovery.

Things to consider

• A decision for a closed Human Gate cannot be submitted again.
• A team user cannot see Human Gates for another team's projects.
• After a failure, refresh the Human Gate state: if the decision is already saved, you do not need to submit it again.
• If a response fails validation, the Human Gate remains open. Correct the data according to the error message and submit it again.

Parameters and result

• Parameters: decision, comment or input data, rework feedback, and, if needed, model and chat session selection.
• Result: a closed Human Gate, an audit event, and continued Run execution.

Where to find it

• In the application: /gates-inbox, /human-gate, /gate-input, /gate-approval, and the Human Gate tab in Run Console.

Further reading

• Manual rework (Human Takeover)
• Run lifecycle
• Human Gate Decision
• Node Checkpoint

Manual rework (Human Takeover)

Sometimes it is easier to fix a few lines yourself. Human Takeover lets you temporarily take over editing, change the Run's working files, and then return to the approval process.

Who can use it

A user with permission to respond to Human Gates for the corresponding project.

Before you begin

• The Human Gate is open and supports manual editing.
• The Run's working directory still exists.
• The manual editing action is available in the Human Gate Workspace.

How to use it

Choose the built-in editor or an external IDE. These methods transfer changes to the Run differently.

In the built-in editor

1. At an open Human Gate, start manual rework in the built-in editor.
2. On the Code tab, open a file, edit it, and save it to the Run's working directory.
3. Review the changes and request a return to approval. If you choose to finish rework with Human Gate approval, that decision immediately continues the Flow.

In an external IDE

Starting this mode pushes the Run's working branch to Git before approval is complete. Make sure intermediate changes may be pushed to this repository.

1. At an open Human Gate, start manual rework in an external IDE. The platform creates a snapshot of the current changes and pushes the working branch.
2. Fetch this branch in your local repository clone and open it in your IDE.
3. Make and verify your edits, create a commit, and push it to the same branch. For multiple repositories, push the changes for each one.
4. Return to the Human Gate and end rework without approval (End without approval). The platform fetches the commits from Git, checks that the history is compatible with the original snapshot, and updates the Run's working files.
5. During approval, review the updated changes and make a decision.

Things to consider

• If the editor does not open, check the Human Gate state and Workspace availability before continuing.
• After the working directory is cleaned up, this Run cannot continue. Create a new Run; deleted local edits will not restore themselves.
• The built-in editor checks the path, Run state, and that the file has not changed since it was opened. When rework ends, it checks the Human Gate state and, for an external IDE, the Git history. These checks do not replace AI node contract validation or running tests after manual edits.
• For an external IDE, local edits alone are insufficient: commits must be present on the remote working branch. If there are no new commits, the interface asks you to confirm continuation without changes.
• Before approving, check required artifacts and the full diff against the task, and run the necessary project checks.

Parameters and result

• Parameters: Human Gate ID, manual editing mode, and manual file changes.
• Result: an updated Run working directory and a return to approval, or continued Flow execution if you ended rework with Human Gate approval.

Where to find it

• In the application: the Human Gate Workspace and Run code editor.

Further reading

• Handling Human Gates
• Workspace, code, and artifacts
• Run Code Editor
• Human Gate Decision

Run working files, changes, and artifacts

Open the Run's working files to see what the agent changed. Here you can compare code versions, read generated documents, and check artifacts — the outputs that the Flow expects from its steps.

Who can use it

• Users with access to the Run can view the file tree, contents, changes, and artifacts.
• File editing is available only in explicitly permitted scenarios, such as Human Takeover.

What the platform does

1. When a Run starts, the platform creates a working directory and checks out the selected repository versions.
2. Saves the original commit (base SHA) and branches for each repository.
3. Prepares project rule files, Skills, Subagents, and MCP settings.
4. Saves a checkpoint before the first execution of an AI node; it may be reused during rework.
5. After execution, collects changes and validates declared artifacts and expected changes according to the Flow validation settings.
6. Registers created artifacts with the run or project scope.
7. The interface displays a tree organized by repository, changed files, contents, and diffs.

Artifacts

• The run scope stores the result of a specific Run.
• The project scope allows a result to be used in subsequent steps and Runs if artifact references and access rules permit it.
• An artifact_ref can resolve to a specific path or a path pattern.
• A required artifact is included in node validation.

Things to consider

• A missing required artifact fails the attempt when fail_on_missing_declared_output is enabled. When it is false, the platform records node_validation_ignored, and execution can continue. required: true alone does not guarantee a stop.
• expected_mutations checks expected changes to the listed paths but does not prohibit edits to other files. Review the complete diff; add a separate command to check the scope of changes when needed.
• A missing required expected change fails the attempt when fail_on_missing_expected_mutation is enabled. When it is false, the violation is recorded in the audit trail without necessarily stopping execution.
• Both strict validation flags are disabled in the visual editor’s initial settings for a new Flow. Enable them for mandatory output validation and inspect the generated YAML. If the fields are absent from YAML, the runtime defaults to strict validation.
• Agent service files are separated from user changes through quarantine.
• A cleaned-up Workspace no longer provides code, but saved Run information and the audit trail remain available.

Parameters and result

• Parameters: a snapshot of repository state, node contracts, and actual file changes.
• Result: artifact versions, file tree, changes, version diffs, and checkpoints.

Where to find it

• In the application: the Code, Changes, and Artifacts tabs in Run Console and the Human Gate Workspace.

Further reading

• Artifacts
• Node Validation
• Node Checkpoint
• Run Code Editor
• Agent Quarantine

Catalog approval and publication

Once a Flow, Skill, or Subagent has been verified, publish its version to make it available for production Runs. The process depends on the catalog scope: a team version and a shared organization version follow different paths.

Who can use it

ADMIN and FLOW_CONFIGURATOR submit versions, view the queue, and make decisions.

How it works

1. Complete the draft version and submit it for publication.
2. For the team scope, use direct publication by an operator. For organization, submit an approval request.
3. If synchronization with the Git catalog is configured, the platform prepares the required commit, branch, or Pull Request operations.
4. An operator reviews the request and accepts or rejects the version.
5. After successful publication, the new version appears in launch forms.

Things to consider

• Rejection records the decision and does not make the version available to production Runs.
• A failed job appears in the queue and can be retried after the cause is resolved.
• After a failure, refresh the queue and check the request state before submitting a decision again.
• If an error occurs, check the status of the specific version being published in the queue; after resolving the cause, retry its publication.

Parameters and result

• Parameters: draft version, publication data, and operator decision.
• Result: a published/rejected version and publication job history.

Where to find it

• In the application: /requests.

For details on scopes and publication channels, see Catalog scopes and the publication guide.

Further reading

• Catalog versioning
• Platform connections

Publishing Run results

After the Flow graph completes successfully, HG SDLC starts pushing changes to Git. Whether human review is required depends on the Human Gates and approval mode. You can get a separate working branch, a direct commit to the selected branch, or a Pull Request. If only publication fails, you can retry it without executing the Flow again.

Who can use it

• Users with access to the Run can view its publication status.
• ADMIN and FLOW_CONFIGURATOR can retry publication and use Force publish when the state allows it for Runs across all teams.
• TEAM_MEMBER performs these actions for Runs within their team.
• PRODUCT_OWNER views the result but does not manage Run publication.

Before you begin

• For regular publication, the Run has completed the necessary steps and approvals required by its Run mode. The separate Force publish action described below is an exception.
• A mode that pushes changes to Git is selected.
• The project has a configured SCM connection and available credentials.

What the platform does

1. The runtime checks the final changes in each Run repository.
2. Creates a commit using the publication template.
3. Pushes according to the mode: publishes the working branch or pushes changes directly to the selected branch.
4. In PR mode, creates a Pull Request targeting the destination branch.
5. Saves the result URL and publication status for each repository.
6. Completes the Run with the publication outcome and sends the related events.

Pushing changes to Git does not mean merging them or releasing the product. Further checks, merging, and deployment depend on the target repository's configuration.

Things to consider

• New Runs support branch, direct_push, and pr (where supported by the SCM); debug uses branch.
• local is supported for compatibility with older Runs: changes remain in the Workspace and no push occurs.
• Conflicts with a working branch already in use are checked before the agent starts; later, changes on the Git server may cause a push to be rejected.
• If a push is rejected as non-fast-forward, use the error message to check the divergence from the remote branch.
• Publication across multiple repositories can have different statuses per repository; partial results are explicitly displayed.
• publish retry retries publication for PUBLISH_FAILED without restarting Flow steps.
• Force publish lets you push work already completed in a FAILED Run if publication has not yet succeeded, the working directory has not been cleaned up, the error code permits the action, and the mode is not local. The button is available based on a server-side check. Review the changes before clicking it: the Run itself ended with an error.
• Once the Workspace has been cleaned up, these files cannot be published; rerun the process.

Parameters and result

• Parameters: working directory changes, publication mode, branching strategy, SCM, and templates.
• Result: a published branch, direct push, or Pull Request for each repository; for an older local Run, files in the Workspace.

Where to find it

• In the application: publication status, Retry publish, and Force publish when the state allows it in Run Console.

Further reading

• Result publication journey
• Platform connections
• External API and webhooks
• Publication across multiple repositories is described in the 2.0 release notes.

External API and webhooks

Connect HG SDLC to CI or an issue tracker: the external system can launch Flows, and the platform can report progress back to it. API launches use access keys; event exchange uses webhooks.

Who is involved

• An external system with an API key launches a Run through the External API.
• An external system calls a configured inbound webhook.
• HG SDLC sends events to configured outbound notification destinations.
• ADMIN manages API keys; authorized operators configure webhooks.

External API

1. An administrator creates an API key and immediately saves the displayed secret.
2. The client includes the key in the launch request.
3. The system checks the key, project scope, and launch parameters.
4. A Run is created with the source external_api.
5. A revoked key no longer accepts new requests.

The secret is stored as a hash for verification and is not returned again after creation.

Inbound webhooks

1. An operator creates a named inbound webhook configuration.
2. The external system calls /api/webhooks/in/{name} with the agreed data.
3. The system checks the configuration and performs the associated action.
4. The association between the webhook and the Run is saved for diagnostics.

Outbound webhooks

1. An operator creates a recipient destination and selects events and authentication parameters.
2. When a Run event occurs, the system constructs an HTTP request.
3. The delivery result is recorded in the outbound notification history.
4. The user can view the Run's delivery history.

Things to consider

• An invalid or revoked API key is rejected before the action executes.
• When launching through the External API, send the Idempotency-Key header. To retry the same request, reuse the original key and the same data; a new key indicates a separate request.
• A notification recipient's error does not change the Run status already recorded.
• Webhook/API secrets are not returned in plain text in ordinary read API responses.

Where to find it

• External API: POST /api/external/v1/runs/launch.
• API keys: /api/settings/api-keys.
• Inbound event reception: POST /api/webhooks/in/{name}.
• Webhook configuration: /api/webhooks/inbound, /api/webhooks/outbound.

Further reading

• Launching a Flow
• Run Lifecycle
• API Keys
• Webhooks

SCM, MCP, and AI agent connections

Configure Git access and the agent's runtime environment so it can work with your code. Connect MCP servers if the process needs additional tools. The sections below explain what each connection is responsible for.

Git hosting connections

An operator registers a connection with a type, base API URL, and credentials. The project references the connection, and the system checks that its host matches the project's repositories. The connection is used for Git access, pushing changes, and creating Pull Requests.

MCP servers

ADMIN creates a server configuration, selects the transport, specifies environment variables, headers, a command, and secrets, checks the preview for the selected agent, and enables the server. An AI node references it through mcp_refs. The configuration is captured for the Run; secrets are masked in public views. The agent may need real credentials to operate.

Agent runtime environment

Qwen, Claude, GigaCode, Codex, and OpenCode are supported. The selected agent's CLI/ACP adapter must be installed and authenticated separately. The application itself can start without GigaCode; the agent is required for AI workflows that use it.

A platform operator configures the agent launch command, ACP process limits, timeouts, and the default model. At launch, the system retrieves the model catalog, runs preflight checks, and records both the requested model and the model actually selected.

How it works

1. Create a connection and check its parameters.
2. Save secrets in the settings intended for them.
3. Specify the connection in a project or Flow.
4. Create a test Run. At startup, the platform checks connection availability and saves a configuration snapshot.
5. If an error occurs, open the launch, step, or publication diagnostics to identify the connection that needs fixing.

Things to consider

• If an MCP server is disabled, check references to it in the Flow and the connection state before launch.
• The preview masks known secret fields and shows required parameters that have not been filled in.
• A model that disappears after startup is not silently replaced during an AI node.
• An incorrect SCM host or invalid credentials block the corresponding operation.

Permissions

• Authenticated users can view general settings within the interface available to them.
• ADMIN and FLOW_CONFIGURATOR edit runtime, catalog, and SCM settings.
• Only ADMIN edits MCP settings containing secrets.

Where to find it

• In the application: /settings.

Further reading

• Project management
• Launching a Flow
• Publishing results
• MCP and SCM capabilities are described in the 2.0 release notes.
• Model selection is described in the 2.1 release notes.

Run Console, audit, and diagnostics

Start with Run Console to understand what is happening with a task. It brings together process steps, logs, code changes, and human decisions. If something fails, open the specific step and read its error message.

Who can use it

• Platform operators see Runs from all teams.
• Team users see Runs from their projects.
• PRODUCT_OWNER can view accessible Runs but cannot perform technical Run Console operations.

How it works

1. Open the Run list and use filters to find the Run you need.
2. Open its details: you can see the status, launch source, project, Flow, selected model, and publication status.
3. Use the graph and timeline to find current and completed steps.
4. Open a step's details, its stdout/stderr output, and token usage if the agent reports it.
5. Review artifacts and code changes.
6. Check the sequence of audit events.
7. Open an open Human Gate or choose an available Run management action.

Diagnostic views

View	Question it answers
Run list and details	Where is the process, and how did it finish?
Graph and timeline	Which path through the Flow was actually executed?
Node log	What did the step executor report?
Code and changes	Which files changed?
Artifacts	Which documents and other outputs were created?
Audit	Who changed the state, and when?
Agent context	What context did the agent receive?

Things to consider

• After the working directory is cleaned up, its files are no longer available, but you can still open the Run history.
• Partially available data is shown with diagnostics instead of hiding the entire Run.
• The Run list and details are limited to the user's access scope.

Where to find it

• In the application: /run-console and the audit, artifacts, and agent context sections.

Further reading

• Run lifecycle
• Workspace, code, and artifacts
• Handling Human Gates
• Run Lifecycle
• Artifacts

Server status and working file cleanup

Monitor server load and free disk space to spot resource shortages in time. This is also where you configure cleanup of Run working directories that no longer need to be retained.

Who can use it

ADMIN and FLOW_CONFIGURATOR.

How it works

1. Open the Server status section in settings.
2. Check CPU load, memory, and the state of the agent's ACP processes.
3. Configure metric intervals, working directory retention periods, the cleanup schedule, and the minimum free space reserve.
4. Check the rules for completed and active Runs separately. When space is low, cleanup starts with the oldest directories that match these rules.
5. Review the cleanup log. If needed, run cleanup manually after saving any results you need.

Retained data

Cleanup deletes Run working files. Run records, audit data, and .hgsdlc service data are retained; deleted code and artifacts from the Workspace are no longer available.

Things to consider

• The retention period for completed Runs does not itself apply to active working directories: separate rules apply to them.
• A deletion error is recorded and does not mark a Run as successfully completed.
• Cleanup affects only working directories managed by the platform.

Where to find it

• In the application: /settings, Server status section.

Further reading

• Run Console and audit
• Workspace, code, and artifacts
• The server status capability is described in the 2.1 release notes.

Development status overview

Open Overview after signing in: the summary helps you see which processes are running, where errors have occurred, and which approvals are waiting for a response. From there, you can go directly to the relevant Run or Human Gate.

Who can use it

All signed-in users. Metrics, recent Runs, and Human Gates are calculated within their access scope.

How it works

1. Open Overview after signing in.
2. Check the platform status and the time it was last observed.
3. Review the number of active Runs, pending Human Gates, and recent errors.
4. Review published and draft Flows, audit events, and how long decisions have been pending.
5. Go to a pending Human Gate or open the details of the Run you need.

Metrics

• active Runs;
• Human Gates waiting for input or a decision;
• unsuccessful Runs over the past 24 hours;
• median and maximum Human Gate waiting time;
• published and draft Flows;
• audit events over the past 24 hours;
• recent Runs and incoming approvals.

Things to consider

• An unavailable health signal is displayed as degraded/unavailable and does not hide other data.
• If you have just installed HG SDLC, empty lists are normal: they fill up after the first Runs.
• The summary is limited to the user's access scope. The separate Analytics section has a different access restriction.

Parameters and result

• Parameters: the current user and their access scope.
• Result: an aggregated summary and links to items that need attention.

Where to find it

• In the application: /overview.

Further reading

• Run Console and audit
• Handling Human Gates
• Server status

Team and project autonomy analytics

See where the team spends time: on agent work, waiting for a response, or rework. Comparing periods helps identify processes that frequently need manual intervention.

Who can use it

ADMIN, FLOW_CONFIGURATOR, PRODUCT_OWNER, and TEAM_MEMBER. If the user belongs to a team, the interface selects it by default. The filters can be changed.

How it works

1. Open Analytics and select a period: 7, 30, or 90 days.
2. Specify a team and project. If you belong to a team, it is selected by default, but you can change the filter.
3. On the teams tab, compare Run results, durations, token usage where data is available, and human participation.
4. Open a member to view their Runs. Automatic Runs are counted separately.
5. On the autonomy tab, compare the project with the previous period: how much human participation is planned in the Flow, and how many approvals, waits, and rework cycles occurred in practice.

Limitations

• Autonomy here refers to measured indicators, not a configurable permission for the agent to work without a human. Checkpoints are defined by the Flow and launch modes.
• Incomplete token and timing data is accompanied by coverage indicators; missing measurements do not mean zero costs.
• In the current implementation, analytics filtering is determined by the submitted parameters rather than the current user's team membership. The server admits the listed roles but does not limit the dataset to the user's own team. The initial UI filter does not provide data isolation.
• A nonexistent team or a project outside the selected team is rejected as an invalid request scope.

Evaluating workflow improvements

Run history helps identify causes of delays and rework; it does not itself prove the platform's impact. Compare the whole team's time, result quality, and cost of mistakes against your usual way of working.

Assess fewer rework cycles or waits alongside the quality of checks: weaker acceptance can improve the indicators while worsening the result. Recurring human feedback is a reason to review an instruction, skill, or step sequence, rather than automatically change the workflow.

Execution metrics do not replace checking the original business hypothesis after deployment. Configuring business metrics, measuring them, and feeding results into the next change cycle (outcome check) remain a development direction.

Parameters and result

• Parameters: period, team and project filters; a member for drill-down details.
• Result: a summary, comparison with the previous period, Flow metrics, and a list of Runs.

Where to find it

• In the application: /analytics, teams and autonomy tabs.

Further reading

• Development status overview
• Run Console and audit
• Project settings

Comparative testing

Want to understand which model or Flow version handles your tasks better? Run them on the same set of examples and compare the results. Each variant is evaluated separately; you can export the data or use it for another evaluation.

Who can use it

Experimental capability for ADMIN and FLOW_CONFIGURATOR. The section is hidden from the main menu. Open /benchmark in the installed application.

Before you begin

Prepare a project, a task directory on the server, compatible Flows, agents, and models. For automatic evaluation, select a judge Flow. A task's reference answer is passed to evaluation but is not used as ordinary input to the variant being tested.

How to run a comparison

1. Open /benchmark/new and select a project.
2. Add the tasks and variants you want to compare, then configure evaluation.
3. Create a test suite. Each variant × task pair gets a cell with its own result.
4. Monitor execution and compare scores. If an error occurs, you can rerun the cell or just its evaluation.
5. If the automatic evaluation needs correcting, add an explicit override with a comment.
6. Export the results. You can cancel an unfinished test suite.

How to read the result

The summary shows execution results and scores by variant. Agent errors and judge errors belong to a specific cell — open its details first. A manual override changes the score but does not rerun the task.

The comparison applies to the selected tasks and conditions. Running a model again may produce a different answer, so one successful result does not guarantee the same outcome on the next task.

Where to find it

In the application: /benchmark, /benchmark/new, /benchmark/{suiteId}.

Further reading

• Launching a Flow
• Run Console and audit
• Capability map

Contextual chat and change proposals

Open the assistant panel when you need help with the current screen. For example, you can discuss a Flow and receive a proposed change. You decide whether to apply it: accepted edits go into a draft that still needs to be reviewed and saved.

Who can use it

The assistant is available to all signed-in users within their data access scope. Applying Flow changes is additionally restricted by catalog editor permissions.

How it works

1. Open the floating assistant panel.
2. Start a new conversation or return to a conversation for the current screen.
3. Select an available model and ask a question. The assistant receives the page context with known secret fields masked.
4. Read the response. It appears progressively and is saved in history.
5. If a proposal to change the Flow appears, review its card and accept or reject the edits.
6. Check the accepted changes in the Flow editor. They are not saved yet: save the draft and publish the reviewed version separately.

Conversation context

• Regular assistant conversations are grouped by the screen's contextKey.
• Users can switch between conversations for the current screen and all their conversations.
• Human Gate conversations appear in the same interface as a separate group; a closed Human Gate is read-only.

Things to consider

• Known secret fields are masked. Arbitrary secrets in task text or source code may enter the context; consider the agent and model provider settings.
• If sending fails, first check the saved conversation history, then decide whether to resend the message.
• A timeout or interrupted response stream leaves previously saved history available.
• A proposal does not bypass permissions or the catalog lifecycle.

Parameters and result

• Parameters: message, page context, selected conversation and model.
• Result: a saved response and, if present, a proposed Flow change.

Where to find it

• In the interface: the floating assistant panel on authenticated pages.

Further reading

• Editing a Flow
• Handling Human Gates
• Assistant description in version 2.1

User CLI

The CLI is useful if you want to run a prebuilt HG SDLC distribution without building from source. A few commands let you check the environment, start the application, view its log, and stop it.

Before you begin

Node.js 18+ and npm, Java 21+, Git for working with repositories, a distribution server URL, and an accessible user directory. Without PostgreSQL, the application uses the local profile with H2; data in this mode is stored in memory and is not retained after shutdown. Node.js 18+ is the CLI requirement; to build from source, use Node.js 22 from .nvmrc.

How it works

1. Obtain the distribution server address from your administrator and run the CLI installation command provided there.
2. Run hgsdlc doctor to check the environment.
3. If needed, prepare GigaCode with hgsdlc setup and configure the PostgreSQL connection with hgsdlc configure.
4. Run hgsdlc run. The CLI selects and verifies the JAR, starts Java, and waits for the application health check to respond.
5. Use hgsdlc logs to view the log and hgsdlc stop to stop the application.

Versions and updates

• hgsdlc update updates the CLI itself; the application JAR is selected during hgsdlc run.
• On the first installation, a usable JAR is downloaded automatically.
• If a new version is detected in an interactive terminal, the CLI offers an update; the default response is to keep the local version.
• Without an interactive terminal, a usable local JAR is launched when available, without waiting for an answer. A verified local copy can also be launched when the server is unavailable.
• hgsdlc run --version <version> uses exactly the specified published version, without substituting another build.
• A download or verification error for an accepted update terminates the command; the previous verified JAR is retained.
• run does not restart an already running process: run stop first.

Connecting an agent

GigaCode is not required to start the application: run does not install or check it. setup prepares GigaCode separately; agent authentication and runtime configuration remain mandatory for AI workflows that use it. Other supported CLI/ACP adapters are installed separately.

Parameters and result

• Parameters: distribution URL, application version, port, optional PostgreSQL configuration.
• Result: an installed CLI and a managed local application process with configuration, cache, and logs in the user directory.

Further reading

• Detailed CLI guide
• Installing through the CLI
• AI agent connections

Operating an installation

Once the installation is ready, configure backups and working file retention. This gives your team a clear way to preserve data and resume work after a failure.

What to preserve

Use PostgreSQL for ongoing operation. A database backup preserves projects, settings, and history; the Flow catalog in Git and Run working files need to be handled separately. Keep configuration and secrets in secure storage.

Deployments from deploy include a PostgreSQL backup script:

cd deploy
./backup-postgres.sh ./.env.prod

This command is for a prepared server configuration with .env.prod. It does not apply to the local tutorial setup. Setup, verification, and recovery procedures are described in the backup guide. Test restoration in a separate database.

Updating

Record the current version and make a backup before changing a server installation. Check compatibility between the database schema and the selected build; restoring an older image does not, by itself, undo migrations. Follow the upgrade and rollback guide.

For CLI installations, hgsdlc update updates the CLI, while the application JAR is selected when running hgsdlc run. See the CLI description for details.

Disk usage and diagnostics

Use the server status section to monitor resources and workspace retention. Cleanup frees disk space, but deleted files can no longer be viewed or published from that Run. Before cleanup, make sure any results you need are saved in Git or elsewhere.

If an error occurs, open Run Console first: identify the problematic node and read its log and publication status. Retrying a node, recovering a Run, and retrying publication address different problems and are available depending on the run's state. The action descriptions help you choose the right one.

Building and publishing the handbook

Updating content

To correct text on the website, update the corresponding Markdown files in docs/product/product-ru/ (Russian) and docs/product/product-en/ (English), then rebuild the HTML. Do not edit the generated file manually: the next build will overwrite those changes. The feature documentation guidelines are intended for documentation authors.

From the repository root, using Node.js 22 from .nvmrc:

npm --prefix docs/product ci
npm --prefix docs/product run build

The result is docs/index.html. If dependencies are installed, running npm --prefix docs/product run build from the root is enough.

The generator dependencies are declared in docs/product/package.json and locked in docs/product/package-lock.json. Building the handbook does not require installing frontend dependencies.

Page template: docs/product/scripts/product-docs.template.html. Generator: docs/product/scripts/build-product-docs.mjs. It checks that local link targets exist, keys and IDs are unique, and links between embedded sections are valid, and preserves multiline HTML formatting.

Feature descriptions, styles, and navigation are embedded in the HTML. Links between product documents become navigation within the handbook. Technical materials outside it and “Source” links lead to files on the master branch in GitVerse; their contents may change independently of the published revision. Network access is required to use them.

Two languages

A single docs/index.html file contains every section in Russian and English. The RU / EN switch keeps the current document and subsection. The browser remembers your choice when local storage is available. On a first visit without a direct link, an English-language browser selects English; other browsers select Russian.

Direct links specify the language regardless of the saved preference: #doc/getting-started opens the Russian section, and #en/doc/getting-started opens the English section. Search uses the selected language, and printing includes only that language. External technical guides retain their original language.

When adding or changing a document, update both versions. Keep key, id, domain, order, status, last_updated, and the order and levels of headings identical. Translate title, group, body text, and link labels. Relative paths between product documents stay the same; link fragments must match headings in the target language. The generator checks translation coverage, metadata, heading structure, and internal links.

From the repository root, verify the build, navigation, and language switching:

npm --prefix docs/product test

GitVerse Pages: publishing from a branch

For the current structure, use the “Branch” source and the /docs folder. GitVerse publishes the selected folder's contents; index.html takes priority over index.md and README.md. According to the GitVerse quick start, the repository must be public and CI/CD must be enabled.

1. Rebuild the handbook and include docs/index.html together with changed source files in a commit on the selected branch.
2. In the repository, open Settings → Pages and enable Pages.
3. Select Branch, specify the branch with the prepared files, and select the /docs folder.
4. Save the settings and check the publication log.

This mode uses the built-in Jekyll build and runs on commits to the selected branch. It does not run our generator's npm command by itself: update the ready-made HTML before committing.

Project address: kakvsbere.gitverse.site/hgsdlc. After publication, open the site and check that your revision appears.

When a workflow is needed

If HTML should be built during publication, use the “Workflow” source. In .gitverse/workflows, configure Node.js installation, npm --prefix docs/product ci, and npm --prefix docs/product run build from the repository root. The official gitverse/upload-pages-artifact@v1.0.0 then receives the site directory through path, and gitverse/deploy-pages@v1.0.0 publishes the artifact. The directory root must contain index.html.

Choose the publication directory explicitly: you can prepare a separate folder containing HTML and the required resources. You do not have to upload the entire docs folder with its technical materials. An example and requirements are provided in the official workflow guide.

Checks before publication

Open docs/index.html and check search, the menu, the mobile layout, and links. After publication, repeat the checks at the project address, including the RU / EN switch and the direct links #doc/getting-started and #en/doc/getting-started. Make sure the expected revision date is visible on the site. If the page is outdated, check the selected branch, the presence of updated HTML, and the Pages build log.

Feature documentation guidelines

Describe one task the reader can solve with HG SDLC. Start with its benefit and an example, then explain the steps and limitations.

Domains

Domain	Contents
access	Sign-in, users, teams, and roles.
projects	Projects, repositories, and project settings.
catalog	Flows, Skills, Subagents, versions, and lifecycle.
flow-design	Creating, validating, and debugging Flows.
execution	Launch, execution, recovery, and schedules.
human-gates	Human decisions, rework, and Human Takeover.
artifacts	Workspace, code, changes, and artifacts.
publication	Publishing the catalog and Run results.
integrations	External API, webhooks, SCM, MCP, and AI agents.
observability	Run Console, audit, runtime status, team and autonomy analytics.
benchmarks	Experimental comparison of variants on task sets, judges, and export.
assistant	Contextual AI assistant.
operations	Installing, running, and updating the application through the CLI.

Required YAML frontmatter

---
key: capabilities/execution/run-launch
id: RUN-001
title: Launching a Flow
group: Execution
order: 17
domain: execution
status: implemented
last_updated: 2026-09-28
---

Writing guidelines

• Address the reader directly: “select a project,” “check the log.” When the system performs an action, name it explicitly.
• Start with the purpose of the section. Do not repeat headings such as “Value,” “Actors,” and “Prerequisites and triggers” on every page.
• Use terms from the glossary. Write “step,” “working directory,” and “rework” unless an exact UI name is needed.
• Keep command names, fields, and statuses unchanged. You can place the English button label alongside an explanation of the action.
• In “Who can use it,” specify roles and access scope. Describe system actions in “What the platform does” and user actions in “How to use it.” State the observable result and the conditions required to obtain it. Do not add a section unless it helps the reader.
• Distinguish human actions from automatic platform actions. Do not turn an aspiration from a specification into a promise of an existing feature.
• For an error, provide the next step: where to view it, what to check, and when a retry is possible.
• Check the description against roles, limitations, and the related user journey.
• Do not promise identical model responses, full isolation, or automatic recovery without confirmation in the code.

Example structure

# Capability name

Briefly explain the task the reader will be able to solve. If useful,
provide a concrete example.

## Who can use it

Specify roles and team scope. Do not hide exceptions.

## Before you begin

What to prepare — only if it is not obvious from the steps.

## How to use it

User actions in execution order. For each, specify the location
in the UI and the observable result if needed for the next step.

## What the platform does

Automatic behavior and the conditions that trigger it — if these need
an explanation separate from user actions.

## Things to consider

Limitations and actions to take when errors occur.

## Where to find it

The application section name. UI paths refer to the installed
HG SDLC application, not the documentation website.

## Further reading

Links to the next step, related capabilities, and technical materials.

Only add sections that are useful for the particular capability. A parameter table is useful if it helps the reader prepare a Run; it does not need to duplicate steps already described.

Numbering

An identifier is stable and is not reused after a feature is removed. Its prefix corresponds to the domain: ACC, PRJ, CAT, FLW, RUN, HITL, ART, PUB, INT, OBS, BEN, AST, OPS.