homebox_lens/agent_promts/GITEA_ISSUE_DRIVEN_PROTOCOL.xml

<GITEA_ISSUE_DRIVEN_PROTOCOL>
    <META>
        <PURPOSE>Определить единый, отказоустойчивый и полностью автоматизированный протокол для межагентной коммуникации, постановки задач и управления жизненным циклом кода. Gitea служит центральной коммуникационной шиной и системой контроля версий. Взаимодействие с Gitea осуществляется через утилиту командной строки 'tea-cli'.</PURPOSE>
        <VERSION>3.0</VERSION>
    </META>

    <CORE_PRINCIPLES>
        <PRINCIPLE name="Gitea_As_The_System_Bus">
            <DESCRIPTION>Gitea Issues и Pull Requests являются единственным каналом для асинхронной коммуникации между AI-агентами. Взаимодействие происходит через 'tea-cli'.</DESCRIPTION>
        </PRINCIPLE>
        <PRINCIPLE name="Human_Out_Of_The_Loop">
            <DESCRIPTION>Человек взаимодействует с системой исключительно через диалог с Агентом-Архитектором. Gitea используется как "закулисный" механизм, и человек не должен создавать, комментировать или назначать Issues вручную.</DESCRIPTION>
        </PRINCIPLE>
        <PRINCIPLE name="Pull_Request_As_The_Unit_Of_Work">
            <DESCRIPTION>Конечным продуктом работы Агента-Разработчика является не просто ветка с кодом, а формальный Pull Request (PR). Именно PR является объектом верификации для QA-Агента и точкой слияния в основную ветку.</DESCRIPTION>
        </PRINCIPLE>
        <PRINCIPLE name="Traceability_Is_Paramount">
            <DESCRIPTION>Каждое действие в системе должно быть отслеживаемым. Это достигается за счет неразрывной связи: `GiteaIssue ID` <-> `Имя ветки` <-> `Pull Request ID`.</DESCRIPTION>
        </PRINCIPLE>
        <PRINCIPLE name="Initial_Check">
            <DESCRIPTION>Перед началом работы проверь логин tea-cli whoami. Логин должен соответствовать твоей роли агента</DESCRIPTION>
        </PRINCIPLE>
    </CORE_PRINCIPLES>

    <CLI_COMMANDS name="tea-cli">
        <COMMAND name="create_issue">
            <SYNTAX>`tea-cli issues create --title "{title}" --body "{body}" --assignee "{assignee}" --labels "{labels}"`</SYNTAX>
            <DESCRIPTION>Создает новое Issue.</DESCRIPTION>
        </COMMAND>
        <COMMAND name="list_issues">
            <SYNTAX>`tea-cli issues list --assignee "{assignee}" --labels "{labels}" --state "open"`</SYNTAX>
            <RATIONALE>ВНИМАНИЕ: Фильтрация по assignee и labels в tea-cli может работать некорректно. Агент должен самостоятельно фильтровать полученный список задач.</RATIONALE>
            <DESCRIPTION>Ищет открытые Issues по исполнителю и меткам.</DESCRIPTION>
        </COMMAND>
        <COMMAND name="update_issue">
            <SYNTAX>`tea-cli issues edit {issue-id} --add-labels "{labels_to_add}" --remove-labels "{labels_to_remove}" --title "{title}" --assignee "{assignee}"`</SYNTAX>
            <DESCRIPTION>Редактирует существующее Issue, в основном для смены статуса и исполнителя.</DESCRIPTION>
        </COMMAND>
        <COMMAND name="close_issue">
            <SYNTAX>`tea-cli issues close {issue-id}`</SYNTAX>
            <DESCRIPTION>Закрывает Issue.</DESCRIPTION>
        </COMMAND>
        <COMMAND name="create_pr">
            <SYNTAX>`tea-cli pull-request create --title "{title}" --body "{body}" --head "{branch_name}" --base "main"`</SYNTAX>
            <DESCRIPTION>Создает Pull Request.</DESCRIPTION>
        </COMMAND>
        <COMMAND name="merge_pr">
            <SYNTAX>`tea-cli pull-request merge {pr-id}`</SYNTAX>
            <DESCRIPTION>Сливает Pull Request.</DESCRIPTION>
        </COMMAND>
        <COMMAND name="close_pr">
            <SYNTAX>`tea-cli pull-request close {pr-id}`</SYNTAX>
            <DESCRIPTION>Отклоняет (закрывает) Pull Request.</DESCRIPTION>
        </COMMAND>
    </CLI_COMMANDS>

    <SYSTEM_SPECIFICATIONS>
        <SPECIFICATION name="Label_Taxonomy">
            <DESCRIPTION>Строгая система меток для управления статусом и типом задач.</DESCRIPTION>
            <SCHEMA>
                <CATEGORY prefix="status::">
                    <LABEL name="status::pending">Задача ожидает исполнителя.</LABEL>
                    <LABEL name="status::in-progress">Задача в работе.</LABEL>
                    <LABEL name="status::completed">Задача успешно выполнена и закрыта.</LABEL>
                    <LABEL name="status::failed">Выполнение провалено, задача возвращена на доработку.</LABEL>
                </CATEGORY>
                <CATEGORY prefix="type::">
                    <LABEL name="type::development">Задача для Агента-Разработчика.</LABEL>
                    <LABEL name="type::quality-assurance">Задача для QA-Агента.</LABEL>
                </CATEGORY>
            </SCHEMA>
        </SPECIFICATION>
        <SPECIFICATION name="Branch_Naming_Convention">
            <DESCRIPTION>Единый формат для всех веток, создаваемых AI-агентами.</DESCRIPTION>
            <TEMPLATE>`{type}/{issue-id}/{kebab-case-description}`</TEMPLATE>
            <COMPONENTS>
                <COMPONENT name="type">'feature' для новой разработки, 'fix' для исправлений.</COMPONENT>
                <COMPONENT name="issue-id">Номер Gitea Issue, инициировавшего создание ветки.</COMPONENT>
                <COMPONENT name="kebab-case-description">Машиночитаемый заголовок Issue.</COMPONENT>
            </COMPONENTS>
            <EXAMPLE>`feature/123/implement-user-authentication-flow`</EXAMPLE>
        </SPECIFICATION>
    </SYSTEM_SPECIFICATIONS>

    <MASTER_WORKFLOW name="Automated_Feature_Lifecycle">
        <STEP id="1" name="Initiation (Human <-> Architect)">
            <ACTION>Человек в диалоге ставит цель Архитектору. Архитектор проводит анализ, предлагает план и получает вербальное одобрение "Выполняй".</ACTION>
        </STEP>

        <STEP id="2" name="Chain_Genesis (Architect -> Gitea -> Developer)">
            <ACTION>Архитектор создает **первое Issue** в Gitea, используя команду `create_issue`.</ACTION>
            <CLI_CALL>`tea-cli issues create --title "[ARCHITECT -> DEV] {Feature Summary}" --body "{XML Work Orders}" --assignee "agent-developer" --labels "status::pending,type::development"`</CLI_CALL>
        </STEP>

        <STEP id="3" name="Development_And_PR_Creation (Developer)">
            <ACTION>1. Разработчик находит Issue (`list_issues`), меняет его статус на `status::in-progress` (`update_issue`).</ACTION>
            <CLI_CALL>`tea-cli issues edit {issue-id} --remove-labels "status::pending" --add-labels "status::in-progress"`</CLI_CALL>
            <ACTION>2. Создает ветку согласно **Branch Naming Convention**.</ACTION>
            <ACTION>3. Реализует код, коммитит его, проверяет сборку (`./gradlew build`).</ACTION>
            <ACTION>4. Создает **Pull Request** в Gitea (`create_pr`).</ACTION>
            <CLI_CALL>`tea-cli pull-request create --title "PR for Issue #{issue-id}: {Feature Summary}" --body "Fixes #{issue-id}" --head "{branch_name}" --base "main"`</CLI_CALL>
            <ACTION>5. Создает **новое Issue** для QA-Агента (`create_issue`).</ACTION>
            <CLI_CALL>`tea-cli issues create --title "[DEV -> QA] Verify & Merge PR #{pr-id}: {Feature Summary}" --body "<PULL_REQUEST_ID>{pr-id}</PULL_REQUEST_ID>" --assignee "agent-qa" --labels "status::pending,type::quality-assurance"`</CLI_CALL>
            <ACTION>6. Закрывает **свой** Issue (`close_issue`).</ACTION>
            <CLI_CALL>`tea-cli issues close {issue-id}`</CLI_CALL>
        </STEP>

        <STEP id="4" name="Verification_And_Merge (QA Agent)">
            <ACTION>1. QA-Агент находит Issue (`list_issues`), меняет статус на `status::in-progress` (`update_issue`).</ACTION>
            <CLI_CALL>`tea-cli issues edit {issue-id} --remove-labels "status::pending" --add-labels "status::in-progress"`</CLI_CALL>
            <ACTION>2. Извлекает `PULL_REQUEST_ID` и проводит полный аудит кода в PR.</ACTION>
            <ACTION>3. **ЕСЛИ УСПЕШНО:**</ACTION>
            <SUCCESS_PATH>
                <SUB_STEP>a. Сливает (Merge) Pull Request в `main` (`merge_pr`).</SUB_STEP>
                <CLI_CALL>`tea-cli pull-request merge {pr-id}`</CLI_CALL>
                <SUB_STEP>b. Удаляет feature-ветку.</SUB_STEP>
                <SUB_STEP>c. Закрывает свой Issue (`close_issue`). **Цикл завершен.**</SUB_STEP>
                <CLI_CALL>`tea-cli issues close {issue-id}`</CLI_CALL>
            </SUCCESS_PATH>
            <ACTION>4. **ЕСЛИ ПРОВАЛ:**</ACTION>
            <FAILURE_PATH>
                <SUB_STEP>a. Отклоняет Pull Request (`close_pr`).</SUB_STEP>
                <CLI_CALL>`tea-cli pull-request close {pr-id}`</CLI_CALL>
                <SUB_STEP>b. **Обновляет свой Issue**, возвращая его Разработчику (`update_issue`).</SUB_STEP>
                <CLI_CALL>`tea-cli issues edit {issue-id} --title "[QA -> DEV] FAILED: Fix Defects in PR #{pr-id}" --assignee "agent-developer" --remove-labels "status::in-progress,type::quality-assurance" --add-labels "status::failed,type::development"`</CLI_CALL>
                <RATIONALE>Это создает итеративный цикл исправления ошибок в рамках одной и той же ветки и PR.</RATIONALE>
            </FAILURE_PATH>
        </STEP>
    </MASTER_WORKFLOW>
</GITEA_ISSUE_DRIVEN_PROTOCOL>