full cycle developer

When to Use

Triggered when user says:

• "full cycle for [project] [task/issue]"
• "do full cycle"
• "work in full cycle mode"

Prompts Location

All role prompts live in /opt/projects/llm-review-prompts/prompts/. Select the right language variant based on project stack from AGENTS.md.

prompts/
├── developer/   dotnet | rust | python | go
├── architect/   dotnet | rust | python | go
├── tester/      manual | e2e | autotests
├── reviewer/    general
└── security/    general

---

Execution Mode — MAIN SESSION AS ORCHESTRATOR

The user sees only one final Output. The main session silently performs all steps — without intermediate messages.

Orchestration scheme

ГЛАВНАЯ СЕССИЯ (молча)
│
├── Шаг 1-3: sessions_spawn(developer-субагент)  → ждёт → [diff, tests green]
│
├── Шаг 4: sessions_spawn × 4 (параллельно):
│   ├── Developer review  → sessionKey_dev
│   ├── Architect review  → sessionKey_arch
│   ├── Tester review     → sessionKey_test
│   └── Security review   → sessionKey_sec
│   └── Ждёт все 4 через subagents(action="list")
│   └── Забирает результаты через sessions_history
│
├── Шаг 4e: Final review — inline в главной сессии
│   (читает промпт reviewer/general.md + PREVIOUS_REVIEWS из 4 ролей)
│
├── Шаг 5: sessions_spawn(fix-субагент)
│   (передаёт агрегированные BLOCKING/MUST HAVE явно в task)
│   → ждёт → [tests green, commit]
│
└── Шаг 6: создаёт PR → Output пользователю

Main session rules

• Do NOT send intermediate messages to the user between steps
• Tool calls happen silently — only the result
• If something went wrong → report the reason + what managed to be committed

---

Execution Pipeline

1-3. DEVELOP   — developer-субагент: INIT + код + тесты → green
4.   REVIEW    — 4 ревью-субагента параллельно → главная сессия агрегирует → Final inline
5.   FIX       — fix-субагент получает BLOCKING список явно → фиксит → тесты green
6.   PUSH      — главная сессия открывает PR → Output

---

Step 1-3: Developer subagent

The main session spawns a subagent with task:

## DEVELOPER SUBAGENT — <project> <task>

INIT:
- git fetch origin && git pull origin main && git checkout -b <branch>
- Прочитать: AGENTS.md, docs/, ROADMAP.md
- memory_search("<project> architecture decisions")
- memory_search("<task topic> patterns")
- Загрузить TASK_CONTEXT из issue или описания

DEVELOP:
- Читать prompts/developer/<stack>.md
- Написать реализацию следуя Critical Rules из AGENTS.md

TEST:
- Читать prompts/tester/autotests.md
- Написать тесты — каждый тест должен падать при сломанной реализации
- Запустить тесты → должны быть green
- Не заканчивать пока тесты красные

LINT (обязательно для Python):
- python3 -m ruff check src/ tests/ 2>&1 | head -30
- Исправить все ошибки ruff перед коммитом
- Не коммитить с красным ruff

ЕСЛИ ROADMAP есть — прочитать, найти текущий пункт, запомнить для architect.

DOCS (ОБЯЗАТЕЛЬНО перед финальным коммитом):
- Обновить AGENTS.md: статус задачи, новые решения, pitfalls (раздел Status + Pitfalls)
- Если изменился публичный API или CLI — обновить README (EN + RU секция)
- Если архитектурное решение — добавить запись в docs/ или соответствующий .md
- Если ROADMAP.md / BACKLOG.md — отметить пункт выполненным (✅)
- Не коммитить реализацию без обновлённых доков

Output: один блок в конце:
BRANCH: <branch-name>
STACK: <python|rust|dotnet|go>
TESTS: <N passed>
LINT: ruff clean / <N errors>
DOCS: AGENTS.md updated / README updated / skipped (reason)
DIFF_SUMMARY: <3-5 строк что изменилось>

Timeout: runTimeoutSeconds=900

After completion — retrieve BRANCH, STACK, TESTS, DIFF_SUMMARY from sessions_history.

---

Step 4: 4 review subagents in parallel

Get diff:

cd <project_root> && git diff origin/main...<branch> 2>&1 | head -400

Read the prompts in advance (main session):

cat /opt/projects/llm-review-prompts/prompts/developer/<stack>.md
cat /opt/projects/llm-review-prompts/prompts/architect/<stack>.md
cat /opt/projects/llm-review-prompts/prompts/tester/manual.md
cat /opt/projects/llm-review-prompts/prompts/security/general.md

Spawn all 4 simultaneously, each with a task containing:

• Role prompt (full text)
• PROJECT_CONTEXT (AGENTS.md)
• TASK_CONTEXT (description + AC)
• DIFF (git diff)
• Instruction to return findings at the end in a single block

⚠️ Scope limitation for ALL roles (especially Security): Check ONLY changes in the DIFF. Pre-existing issues that existed before this MR → not BLOCKING, file them in the MINOR section with the note [pre-existing]. Security must not block the MR because of problems that are not introduced by the current change.

Task template for each role

## <ROLE> REVIEW

<полный текст промпта роли>

---

PROJECT_CONTEXT:
<содержимое AGENTS.md>

TASK_CONTEXT:
<описание задачи + acceptance criteria>

DIFF:
<git diff>

---

Верни findings одним блоком в конце:
[BLOCKING/MINOR/CRITICAL/HIGH/MEDIUM/MUST HAVE/SHOULD HAVE]: описание, файл:строка, fix
Итого: X blocking, Y minor.

Timeout for each: runTimeoutSeconds=1200

Wait for all 4

# Собрать sessionKeys всех 4 субагентов
role_keys = {
    "developer": key_dev,
    "architect": key_arch,
    "tester":    key_test,
    "security":  key_sec,
}

# Ждать в цикле через subagents(action="list")
while True:
    active = subagents(action="list")["active"]
    active_keys = {s["sessionKey"] for s in active}
    if not any(v in active_keys for v in role_keys.values()):
        break
    exec("sleep 15")

# Забрать результаты
reviews = {}
for role, key in role_keys.items():
    hist = sessions_history(sessionKey=key, limit=2)
    reviews[role] = hist["messages"][-1]["content"]  # последнее сообщение

Step 4b (Architect) + ROADMAP

Add to the task for architect:

Дополнительно: обнови ROADMAP.md
- Если ROADMAP.md есть → найди текущую задачу и отметь [x], добавь новые пункты если выявлены
- Если нет → создай ROADMAP.md (текущее состояние + ближайшие задачи + дальние планы)
Сохрани изменения: exec("cd <project_root> && git add ROADMAP.md && git commit -m 'docs: update ROADMAP'")

Step 4e: Final Review (inline)

The main session itself aggregates and issues the verdict:

Assemble PREVIOUS_REVIEWS:

## Developer Review
<reviews["developer"]>

## Architect Review
<reviews["architect"]>

## Tester Review
<reviews["tester"]>

## Security Review
<reviews["security"]>

Read prompts/reviewer/general.md, apply to PREVIOUS_REVIEWS + DIFF. Issue the verdict: APPROVE / REQUEST_CHANGES.

---

Step 5: Fix subagent

Aggregate all BLOCKING by table:

Role	Fix before MR	В issue
Developer	BLOCKING	MINOR, SUGGESTION
Architect	BLOCKING	MINOR
Tester	MUST HAVE	SHOULD HAVE → issue
Security	CRITICAL, HIGH	MEDIUM → issue, LOW → ignore

fix → review cycle (repeat until clean)

review_round = 1
MAX_ROUNDS = 3

while blocking_count > 0:
    if review_round > MAX_ROUNDS:
        → прервать, сообщить пользователю: "Не удалось устранить все BLOCKING за 3 итерации"
    fix_subagent(blocking_list)
    review_round += 1
    повторить шаг 4 (все 4 роли + 4e) → получить новый blocking_count

After each fix subagent — MANDATORY to repeat the full review of step 4 (all 4 roles in parallel + 4e Final). Do not consider the branch clean solely on the basis of "fix applied" — new changes may introduce new BLOCKING issues.

Proceed to Step 6 only when blocking_count == 0 based on the review results.

⚠️ CRITICAL RULE: DO NOT INTERRUPT THE CYCLE

The main session must NOT send intermediate review results to the user.

The cycle develop → review → fix → review → ... runs fully autonomously. The user must NOT ping the agent to continue — that is an orchestration failure.

The only cases when you may write to the user before the PR:

1. MAX_ROUNDS exhausted — explain what failed and hand over control
2. Fatal error (tests are red and the fix subagent cannot repair it within 3 attempts)
3. Ambiguity in the task that cannot be resolved without a user decision

In all other cases — silently launch the next step.

🔔 Mandatory self-ping via cron (anti-freeze)

Problem: the main session may "freeze" after launching subagents — the completion event does not always wake the session. Without an external trigger, the cycle will stop.

Rule: launched a group of subagents → immediately set two crons. Without exceptions.

Cron timing:

Subagent type	Timeout	Cron 1	Cron 2
4 review roles	1200s (20 min)	T + 20 min	T + 23 min
Fix subagent	600s (10 min)	T + 12 min	T + 15 min

Logic: the cron must fire after the expected completion, not during it.

Cron text template:

Full-cycle самопинг: раунд {N} ревью <project>/<branch>.
Проверь subagents list (labels содержат '<role>').

Если ВСЕ done → агрегируй sessions_history, подсчитай blocking.
  blocking > 0 → запусти fix-субагент (не пиши пользователю).
  blocking = 0 → создай PR → напиши пользователю итог.

Если ЕСТЬ active → удали этот cron, поставь новый на T+5 мин с тем же текстом.

НЕ пиши пользователю пока нет финального результата (PR или фатальная ошибка).

Self-rescheduling logic (if subagents are still active):

# В тексте systemEvent cron должен содержать инструкцию:
# "если active → удали себя (cron remove), поставь новый cron на now+5min"
# Это обеспечивает polling без busy-loop

• deleteAfterRun: true — each cron is one-shot
• Two crons: if the first does not wake the session — the second will fire after 3 min
• If the main session has already continued on its own — cron will fire on an empty subagents list → no-op (subagents done, PR already exists or fix already started)
• Do not use cron when the subagents have already returned results to the active session — aggregate immediately

How to check BLOCKING before the fix subagent

Before starting the fix subagent, check the actual code (do not blindly trust the reviewers' output):

• Open the files mentioned in the BLOCKING findings
• Make sure the problem really exists in the code and is not a false alarm
• Reviewers without access to the sources are often wrong (they analyze from the diff)
• False alarms do not need to be fixed — they are not BLOCKING

This saves rounds and does not introduce unnecessary changes to the code.

If BLOCKING = 0 on the first try → no fix subagent is needed, go straight to Step 6.

If BLOCKING > 0 → spawn the fix subagent with task:

## FIX SUBAGENT — <project> <branch>

cd <project_root> && git checkout <branch>

Исправить следующие BLOCKING findings:

<нумерованный список с файл:строка и конкретным fix для каждого>

После каждого fix — запустить тесты:
<команда запуска тестов>
Не коммитить пока тесты красные.

Запустить линтер (Python):
python3 -m ruff check src/ tests/ 2>&1 | head -30
Исправить все ошибки ruff. Не коммитить с красным ruff.

Обновить документацию (ОБЯЗАТЕЛЬНО):
- AGENTS.md: добавить найденные pitfalls, обновить статус
- README / docs: если fix затронул поведение — обновить соответствующую секцию

После всех fix:
git add -A
git commit -m "fix: <краткое описание>"
git push https://KoshelevDV:$(gh auth token)@github.com/KoshelevDV/<repo>.git <branch>

Создать сводный issue для MINOR/MEDIUM:
gh issue create --repo KoshelevDV/<repo> \
  --title "Minor: <feature>" \
  --body "<список>"

Output в конце:
TESTS: <N passed>
LINT: ruff clean / <N errors>
FIXES: <N blocking fixed>
ISSUE: <url или none>

Timeout: runTimeoutSeconds=600

---

Step 5.5: Updating documentation (after fix, before PR)

After blocking_count == 0 and the tests are green — update the project documentation:

cd <project_root>

# 1. AGENTS.md — обновить статус, стек, питфолы, новые решения
# Добавить в секцию Status: что реализовано, что изменилось
# Добавить в Pitfalls: нетривиальные находки из ревью

# 2. README.md — если добавлены новые возможности (config options, API endpoints, etc.)
# Обновить секцию конфигурации, добавить пример использования новой фичи

# 3. Коммит документации
git add AGENTS.md README.md
git commit -m "docs: update AGENTS.md and README for <feature>"
git push ...

What to update in AGENTS.md:

• ## Status — mark the feature as implemented
• ## Pitfalls — add non-trivial constraints found during the review
• Stack, if new dependencies were added

What to update in README.md:

• New config options (with a YAML example)
• New API endpoints
• Behavior changes

If nothing fundamentally changed (only internal fixes) — AGENTS.md is enough.

---

Step 6: PUSH + Output

The main session creates the PR:

gh pr create \
  --title "<type>: <description>" \
  --body "..." \
  --base main --head <branch>

Then sends a single message to the user:

✅ Full cycle завершён — <project> / <branch>

Tests:   <N passed / Y total>
Commits: <N>

Self-review:
  Developer  — <N blocking fixed, M minor → issue>
  Architect  — <N blocking fixed>
  QA/Manual  — <N ACs covered, M missing → issue>
  Security   — CLEAR / <N critical fixed>
  Final      — APPROVE ✅ / REQUEST_CHANGES ⚠️

PR: <url>
Issues: <url или none>

---

Severity Table (required)

Role	= BLOCKING	→ issue
Developer	BLOCKING	MINOR, SUGGESTION
Architect	BLOCKING	MINOR
Tester	MUST HAVE	SHOULD HAVE, NICE TO HAVE
Security	CRITICAL, HIGH	MEDIUM, LOW

MUST HAVE from tester = BLOCKING — a missing test for an AC = an incomplete feature.

---

Rules

• Do NOT send intermediate messages to the user (only the final result)
• Never push with red tests
• Fix BLOCKING and CRITICAL/HIGH before the MR
• MINOR → one consolidated issue, not a commit
• docs/ always read in the developer subagent
• TASK_CONTEXT is required — without it the developer subagent does not start
• git fetch before checkout — always from the up-to-date remote