# agent-loop

Adopt this skill: https://proskills.md/skills/other/larchanka-skills-agent-loop

Page: https://proskills.md/skills/other/larchanka-skills-agent-loop
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: agent-loop/SKILL.md
size: 7840
sha: f516e05caadffa715aebc69b458dd7368c28d55b
upstream: https://github.com/larchanka/skills/blob/main/agent-loop/SKILL.md

````text
---
name: agent-loop
description: Orchestrates a multi-agent loop involving planning, development, review, and publishing sub-agents to implement and publish features test-first and with high standards compliance.
metadata:
   version: 1.2.0
---

# Multi-Agent Iteration Loop

This skill coordinates four independent subagents (`planning`, `development`, `review`, and `publisher`) in a continuous loop to deliver and publish spec-compliant, standard-abiding features.

```mermaid
graph TD
    Start["User Request / Spec"] --> Plan["1. Planning Subagent<br/>(planning-and-task-breakdown)"]
    Plan --> SavePlan["Generate tasks/plan.md & tasks/todo.md"]
    SavePlan --> ApprPlan{"User Approval?"}
    ApprPlan -- No --> Plan
    ApprPlan -- Yes --> Dev["2. Development Subagent<br/>(test-driven-development + refactoring)"]
    Dev --> ImpTask["Implement Next Task via TDD & Quality Gates"]
    ImpTask --> Rev["3. Review Subagent<br/>(code-review)"]
    Rev --> Check{"Any Findings?"}
    Check -- Yes (Bug / Smell) --> Dev
    Check -- No --> CheckMore{"More Tasks in todo.md?"}
    CheckMore -- Yes --> Dev
    CheckMore -- No --> Pub["4. Publisher Subagent<br/>(pull-request)"]
    Pub --> OpenPR["Create Branch, Commit & gh pr create"]
    OpenPR --> Done["Done - Pull Request Published"]
```

## Coordinator Constraints & Disciplines

> [!IMPORTANT]
> **Strict Pure Orchestration**:
> 1. **Zero Task-Related Actions**: The orchestrator MUST NOT read codebase files, search or grep code, explore project architecture, or inspect git diffs. All exploration, reading, implementation, testing, and reviewing belong strictly to subagents.
> 2. **Zero Code Changes**: The orchestrator MUST NOT write code, create source files, edit application logic, or run execution commands.
> 3. **Pass Raw Task Context Directly**: Pass user requests, specs, and file paths directly to the subagents without pre-reading, summarizing, or distilling them.
> 4. **Force Skill Loading (No Instruction Inlining)**: The orchestrator MUST NOT summarize, fragment, or paraphrase skill instructions in subagent prompts. Instead, the orchestrator MUST explicitly instruct each subagent to read and execute its designated skill (`SKILL.md`).

## Workflow Execution Steps

### 1. Planning Phase
- **Action**: Spawn the `planning` subagent using `invoke_subagent`. Pass the user's raw feature request/specification verbatim.
- **Skill Mandate**: Force the subagent to load and follow [planning-and-task-breakdown](../planning-and-task-breakdown/SKILL.md).
- **Subagent Prompt Directive**:
  ```text
  You are the Planning Subagent for agent-loop.
  MANDATORY: Your very first step is to read and strictly execute the skill at `planning-and-task-breakdown/SKILL.md` (or skill `planning-and-task-breakdown`).
  Do NOT rely on abbreviated instructions or skip reading the skill.
  Explore the codebase, analyze requirements, and produce:
  1. `tasks/plan.md` (architectural design and breakdown)
  2. `tasks/todo.md` (checkbox checklist of implementation tasks)
  Return the plan summary and todo list to the coordinator when done.

  <USER_REQUEST>
  {RAW_USER_REQUEST_OR_SPEC}
  </USER_REQUEST>
  ```
- **Handoff**: Once the planning subagent returns `tasks/plan.md` and `tasks/todo.md`, present the plan to the user for approval before starting implementation.

### 2. Development Phase (Task Implementation)
- **Action**: Check which task is next in `tasks/todo.md`. Spawn or message the `development` subagent to implement that single task.
- **Skill Mandate**: Force the subagent to load and follow [test-driven-development](../test-driven-development/SKILL.md) and [refactoring](../refactoring/SKILL.md).
- **Subagent Prompt Directive**:
  ```text
  You are the Development Subagent for agent-loop.
  MANDATORY: You must execute this task using two designated workspace skills in order. First read their complete SKILL.md files:
  1. `test-driven-development/SKILL.md` (for the test-first Red-Green cycle at public boundaries)
  2. `refactoring/SKILL.md` (for automated quality gates: CRAP < 10, duplication elimination, mutation killing)
  Do NOT skip reading these skills. Strictly follow their protocols.

  Task to implement:
  {CURRENT_TASK_DESCRIPTION}

  References:
  - Plan: tasks/plan.md
  - Checklist: tasks/todo.md

  When done, mark the task as completed [x] in `tasks/todo.md` and report a concise summary of the changes made and tests passed.
  ```

### 3. Review Phase (Quality Gates)
- **Action**: Spawn the `review` subagent to review the git diff for the changes introduced.
- **Skill Mandate**: Force the subagent to load and follow [code-review](../code-review/SKILL.md).
- **Subagent Prompt Directive**:
  ```text
  You are the Review Subagent for agent-loop.
  MANDATORY: Your very first step is to read and strictly execute the skill at `code-review/SKILL.md`.
  Audit the current git diff across the 5 axes (Correctness, Readability, Architecture, Security, Performance) and quality gates.
  Output your findings categorized under `## Standards` and `## Spec` headers.
  Report whether the review passes with 0 findings or list any actionable findings to remediate.
  ```
- **Evaluate results**:
  - **If there are findings**: Pass the reviewer's findings directly back to the `development` subagent with instructions to address them. Re-run the `review` subagent once the developer has remediated the issues.
  - **If there are 0 findings**: Advance to the next task in `tasks/todo.md` (back to Step 2). If all tasks are completed `[x]`, proceed to Step 4.

### 4. Publishing Phase (Deployment Gate)
- **Action**: Spawn the `publisher` subagent to finalize, commit, push, and create the PR.
- **Skill Mandate**: Force the subagent to load and follow [pull-request](../pull-request/SKILL.md).
- **Subagent Prompt Directive**:
  ```text
  You are the Publisher Subagent for agent-loop.
  MANDATORY: Your very first step is to read and strictly execute the skill at `pull-request/SKILL.md`.
  Perform worktree cleanup, stage files, commit using Conventional Commits, push the feature branch to origin, and run `gh pr create` with clear titles and descriptions.
  Return the final Pull Request URL.
  ```
- **Handoff**: Provide the user with the direct link to the published Pull Request.

## Practice Guidelines

- **Zero Inspection by Coordinator**: The coordinator thread stays clean and minimal. Never load or read application source files in the orchestrator session.
- **Pass Pure Payloads**: Hand off unedited user instructions and artifacts directly to subagents.
- **Strict Skill Enforcement**: Subagents have rich, detailed instructions in their respective skill folders. Force subagents to read their `SKILL.md` instead of inlining summarized versions.
- **Keep a Log**: Track workflow transitions and reasons in a lightweight orchestrator log.

## Exit Criteria
- All tasks in `tasks/todo.md` are marked `[x]`.
- The `review` agent reports 0 standard violations or spec omissions.
- All unit and integration tests in the test suite pass successfully.
- Quality gates (`risk-gate`, `clone-check`, `mutant-gate`) pass without violations.
- The `publisher` agent has successfully pushed and opened a GitHub Pull Request, sharing its URL.

## Sub-Agent Skill Directory Mapping

| Sub-Agent | Primary Skills | Skill Path |
| :--- | :--- | :--- |
| **Planning Sub-Agent** | `planning-and-task-breakdown` | [planning-and-task-breakdown](../planning-and-task-breakdown/SKILL.md) |
| **Development Sub-Agent** | `test-driven-development`<br/>`refactoring` | [test-driven-development](../test-driven-development/SKILL.md)<br/>[refactoring](../refactoring/SKILL.md) |
| **Review Sub-Agent** | `code-review` | [code-review](../code-review/SKILL.md) |
| **Publisher Sub-Agent** | `pull-request` | [pull-request](../pull-request/SKILL.md) |
````

## File: agent-loop/README.md
size: 9769
sha: 3c65a6da201657e160c22955cfea6503aff89c6f
upstream: https://github.com/larchanka/skills/blob/main/agent-loop/README.md

````text
# Multi-Agent Iteration Loop (`agent-loop`)

An autonomous, multi-agent coordination skill that orchestrates four dedicated AI subagents—**Planning**, **Development**, **Review**, and **Publisher**—in a continuous, test-driven iteration loop to deliver and publish spec-compliant, high-standard software features.

---

## Overview & Core Philosophy

### Philosophy: Strict Separation of Concerns & Pure Orchestration
The fundamental principles of `agent-loop` are **role isolation** and **pure orchestration**:
- **The Coordinator Agent**: Acts strictly as the project manager and workflow orchestrator.
  - **Zero Task-Related Actions**: The coordinator **MUST NOT** read codebase files, search or grep code, explore project architecture, or inspect git diffs. All reading, implementation, testing, and reviewing are delegated strictly to subagents.
  - **Zero Code Changes**: The coordinator **MUST NOT** write code, create source files, or edit application logic.
  - **Force Skill Loading (No Instruction Inlining)**: The coordinator **MUST NOT** summarize, fragment, or paraphrase skill instructions in subagent prompts. Instead, it explicitly instructs each subagent to read and execute its designated skill (`SKILL.md`).
- **The Subagents**: Specialized agents spawned for distinct phases of the software development lifecycle (SDLC), required to load and operate under dedicated workspace skill playbooks (`planning-and-task-breakdown`, `test-driven-development`, `refactoring`, `code-review`, and `pull-request`).

By enforcing strict boundaries, the loop eliminates common single-agent failure modes—such as skipping unit tests, rationalizing sloppy implementations, or opening half-finished pull requests without quality audits.

### When to Use
- **Feature Development**: Converting a specification, PRD, or user story into production-ready code.
- **Complex Refactoring**: Multi-step codebase refactorings requiring incremental test verification at each step.
- **Autonomous End-to-End Execution**: Hands-off development workflows that must culminate in a validated GitHub Pull Request without human micro-management.

---

## Workflow & Architecture

The skill manages a closed-loop state machine with quality gates at every transition:

```mermaid
graph TD
    Start["User Request / Specification"] --> Plan["1. Planning Subagent<br/>(planning-and-task-breakdown)"]
    Plan --> SavePlan["Generate tasks/plan.md & tasks/todo.md"]
    SavePlan --> ApprPlan{"User Approval?"}
    ApprPlan -- "No / Revisions" --> Plan
    ApprPlan -- "Yes (Proceed)" --> Dev["2. Development Subagent<br/>(test-driven-development + refactoring)"]
    Dev --> ImpTask["Implement Next Task via TDD & Quality Gates"]
    ImpTask --> Rev["3. Review Subagent<br/>(code-review)"]
    Rev --> Check{"Any Findings?<br/>(Standards / Spec / Bugs)"}
    Check -- "Yes (Findings > 0)" --> Dev
    Check -- "No (0 Findings)" --> CheckMore{"Remaining Tasks in todo.md?"}
    CheckMore -- "Yes" --> Dev
    CheckMore -- "No" --> Pub["4. Publisher Subagent<br/>(pull-request)"]
    Pub --> OpenPR["Create Branch, Conventional Commit, Push & gh pr create"]
    OpenPR --> Done["Complete: Pull Request Published"]
```

### The 4 Phases

1. **Planning Phase (`planning` subagent)**
   - Coordinator passes user request/spec directly without inspecting or reading codebase files.
   - Subagent is mandated to load and follow `planning-and-task-breakdown/SKILL.md`.
   - Explores codebase architecture, decomposes the initiative into small, vertically sliced tasks.
   - Produces `tasks/plan.md` (architectural design) and `tasks/todo.md` (actionable checklist) for user confirmation.
2. **Development Phase (`development` subagent)**
   - Coordinator delegates the next incomplete task from `tasks/todo.md`.
   - Subagent is mandated to load and follow `test-driven-development/SKILL.md` (test-first Red-Green cycle) and `refactoring/SKILL.md` (automated quality gates: CRAP < 10, duplication elimination, mutation killing).
   - Writes tests first, implements minimal code to pass, refactors under quality gates, and marks task `[x]`.
3. **Review Phase (`review` subagent)**
   - Coordinator triggers the subagent without inspecting diffs itself.
   - Subagent is mandated to load and follow `code-review/SKILL.md`.
   - Inspects `git diff` against five review axes: Correctness, Readability, Architecture, Security, and Performance.
   - Findings are routed directly back to the development subagent for remediation.
4. **Publishing Phase (`publisher` subagent)**
   - Coordinator delegates publication once all tasks in `tasks/todo.md` pass review.
   - Subagent is mandated to load and follow `pull-request/SKILL.md`.
   - Cleans worktree, verifies test suite, commits following Conventional Commits, pushes branch, and opens a GitHub Pull Request via `gh pr create`.

---

## Required Dependencies & Installation Links

To execute `agent-loop` and its underlying subagent tools, ensure the following command-line tools and runtimes are installed:

| Tool | Purpose | Download & Documentation |
| :--- | :--- | :--- |
| **Git** | Distributed version control and diff tracking | [git-scm.com](https://git-scm.com/) |
| **GitHub CLI (`gh`)** | Automated authentication, branch push, and PR creation | [cli.github.com](https://cli.github.com/) |
| **Python 3** | Runtime for auxiliary automation scripts (v3.10+) | [python.org/downloads](https://www.python.org/downloads/) |

### Installation Instructions

#### macOS (Homebrew)
```bash
# Install Git, GitHub CLI, and Python
brew install git gh python

# Authenticate GitHub CLI with your GitHub account
gh auth login
```

#### Ubuntu / Debian Linux
```bash
# Install Git and Python
sudo apt-get update
sudo apt-get install -y git python3 python3-pip

# Install GitHub CLI (official repository)
type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh -y

# Authenticate GitHub CLI
gh auth login
```

#### Windows (Winget / Scoop)
```powershell
# Using Winget
winget install --id Git.Git -e --source winget
winget install --id GitHub.cli -e --source winget
winget install --id Python.Python.3.12 -e --source winget

# Authenticate GitHub CLI
gh auth login
```

---

## Usage & Examples

### Invoking via AI Assistant

When prompting an AI assistant or orchestrator in an agentic coding environment:

```text
Use the agent-loop skill to implement the following user feature:
"Add rate-limiting middleware to our Express API router based on client IP using a sliding window algorithm."
Ensure tasks are tracked in tasks/plan.md and tasks/todo.md, and open a PR when completed.
```

### Coordinator Execution Contract

The coordinator executes pure workflow orchestration without inspecting codebase files:

1. **Step 1: Plan Generation**
   - Coordinator invokes `planning` subagent, passing raw user request/spec directly.
   - Mandates the subagent load and execute `planning-and-task-breakdown/SKILL.md`.
   - Files created by subagent:
     ```
     tasks/
     ├── plan.md   # Architectural breakdown and design rationale
     └── todo.md   # [ ] Task 1, [ ] Task 2, [ ] Task 3
     ```
   - Coordinator presents plan summary to the user for approval.

2. **Step 2: Task-by-Task TDD Implementation**
   - Coordinator selects the next incomplete task from `tasks/todo.md`.
   - Invokes `development` subagent, mandating it to load and execute `test-driven-development/SKILL.md` and `refactoring/SKILL.md`.
   - Subagent implements test-first, refactors under quality gates (CRAP < 10, clone checks, mutation tests), and marks task `[x]`.

3. **Step 3: Quality Gate Review**
   - Coordinator triggers `review` subagent, mandating it to load and execute `code-review/SKILL.md`.
   - Subagent audits git diff against the 5 quality axes.
   - If findings are reported, coordinator routes the reviewer's report directly to `development` subagent to address.
   - When 0 findings remain, the loop advances to the next task in `tasks/todo.md`.

4. **Step 4: Publishing Pull Request**
   - Once all tasks in `tasks/todo.md` are marked `[x]`, coordinator invokes `publisher` subagent.
   - Mandates the subagent load and execute `pull-request/SKILL.md`.
   - Subagent cleans worktree, validates tests, commits via Conventional Commits, pushes branch, and executes `gh pr create`.
   - The coordinator shares the published pull request URL with the user.

---

## File Structure & Subagent Skill References

```
agent-loop/
├── README.md               # Overview, dependencies, workflow, and instructions (this file)
└── SKILL.md                # Core execution rules, phase definitions, and constraints
```

### Linked Workspace Skills
`agent-loop` relies on subagents loading specialized workspace skills:

- **Planning Subagent**: [planning-and-task-breakdown](../planning-and-task-breakdown/SKILL.md) (Task sizing, vertical slicing, dependency ordering)
- **Development Subagent**: [test-driven-development](../test-driven-development/SKILL.md) (Red-Green-Refactor loop, interface seams, anti-patterns)
- **Review Subagent**: [code-review](../code-review/SKILL.md) (5-axis code quality gate, severity tagging)
- **Publisher Subagent**: [pull-request](../pull-request/SKILL.md) (Git branch isolation, Conventional Commits, GitHub CLI PR automation)
````