General Loop: Keep complex projects moving with an AI team
A general coordination method built on Markdown Tasks: a periodically awakened Loop Agent observes live execution, coordinates multiple Agents, clears blockers, and brings people only the decisions that need them.
Why more AI can create more work for people
For one or two tasks, a person can drive one conversation from requirements through release. In a complex project, requirements, bugs, investigations, regressions, and releases overlap while Agents compete for files, candidates, devices, accounts, and release windows.
If a person still has to open every conversation, ask for progress, move context, issue the next instruction, and decide manually what should wait or run in parallel, adding Agents only increases the coordination burden. General Loop takes over that daily coordination layer.
State the goal, then handle only decisions that truly need you
The Loop takes on the project-manager responsibilities for the AI team: continuously checking every Task and live execution, arranging investigation, development, testing, and release, identifying safe parallel work and shared-resource conflicts, handling failures, continuing or switching Agents, and moving every item into its next real stage.
People keep ownership of goals, requirements, product judgment, authorization for high-risk actions, and necessary acceptance. The Loop organizes progress, delegation, evidence, and exceptions before bringing them to you instead of making you watch every Agent.
It does not make a day of builds, tests, and reviews finish instantly. It changes whether you must stay present for that entire day. Parallel work is no longer limited by one person’s attention, pointless waiting is detected earlier, and you return only when a real review or decision needs you.
How General Loop works
One Loop Agent, a readable and versioned Markdown Task library, multiple execution Agents, and people all coordinate through the same Task library.
Loop Agent
Uses tools, reads and writes Tasks, observes or starts Agents, and is woken periodically by the host or an external scheduler.
Task Markdown
The shared interface for people, the Loop, and every executor—requirements, Handler, execution reference, facts, evidence, and next action.
Execution Agents
Investigation, development, QA, release, support, and other roles read context from Tasks and write real results back.
People
Can talk to the Loop or enter through any other AI conversation; the current Agent records confirmed information in the Task.
How the Loop keeps turning
- Scan every non-terminal Task, not just recently changed ones.
- Use execution references to verify that Agent sessions and commands are actually alive.
- Identify dependencies, candidate drift, stale evidence, resource conflicts, and safe parallel work.
- Decide whether to wait, continue, correct, dispatch, test, release, stop, or close.
- Take the smallest useful action and write facts, evidence, Handler, and next action back to the Task.
- Report meaningful changes; otherwise wait quietly for the next wake-up.
The timer only wakes the Loop; project judgment still belongs to the Loop Agent.
Reusable role and Task prompts
The repository contains the full files; these three prompts are the reusable core contract. The Loop coordinates continuously, execution Agents complete concrete stages, and every participant reads and writes the same Markdown Tasks.
Loop Agent role
You are this project's only Loop Agent. Read AGENTS.md, agents/loop.md, and every non-terminal Task. On each cycle, verify live execution references, dependencies, candidates, evidence, and shared resources; within existing authority choose whether to wait, continue, correct, dispatch, test, release, or close, then write facts, Handler, evidence, and the next action back to the Task. Schedule by real dependencies and resources: Tasks that neither depend on one another nor compete for files, candidates, devices, accounts, ports, or release windows should run concurrently under different unique Handlers; queue, coordinate yielding, or serialize only when a dependency or resource conflict exists. Respect person-directed conversations and do not duplicate assignments or take their resources. Report meaningful changes and stay quiet otherwise. Prefer native recurring wake-ups; only when the host safely supports persistent wait and resume may you wait 5 minutes after each cycle and continue until the user pauses or every Task is terminal.Execution Agent contract
You are the execution Agent for the current Task. First read AGENTS.md, the relevant role file, and the Task; register yourself as its only primary Handler with a recoverable execution reference. Work only within the current requirement and authority, continuously writing live progress, candidate, evidence, risk, result, and next action back to the same Task. Do not leave the only useful state in chat or treat starting a command as completion. When the stage ends, record the result, evidence, and explicit handoff stage.Task Markdown contract
Create or update a Markdown Task from tasks/template.md for every item that needs durable tracking. Use YYYYMMDD-HHmm_short-title_current-status.md and keep the filename, H1, and Status aligned. Every Task records objective and acceptance criteria; facts, unknowns, and risks; current Handler, coordination authority, and execution reference; candidate and shared resources; result and evidence; human decisions; a concrete next action; and an append-only work log. Every active state has exactly one primary Handler and a real execution reference.A real case: an Agent stopped, but the project kept moving
During a real project delivery, the Claude session handling a fix exited because of quota. The Loop detected the failure, switched to an available Agent, kept conflict-free work moving, and preserved testing and release gates.
The result is simple: no one had to inspect every conversation, repeat reminders, or manually reassign the work. When the person returned, the project was already moving again, with human attention needed only for real decisions and acceptance.
How it differs from nearby projects
These projects overlap. General Loop is not trying to be a heavier control plane; it is a coordination protocol you can copy into an existing repository.
| Project | Primary shape | General Loop focus |
|---|---|---|
| LoopX | CLI + state kernel + goals, gates, quota, claims, and leases | No dedicated runtime or private state format |
| Ralph Loop | Repeated fresh coding-agent runs | Continuous project-level Tasks, roles, and shared resources |
| AgentLoop | Single-Agent closed-loop implementation | Cross-session, cross-role project coordination |
| Athena Loops | Coded orchestrator → worker → reviewer harness | Agent judgment with Task documents as the shared interface |
| Agentic Loop | Markdown-first supervised work units | Periodic wake-ups, whole-project queue, live execution and resource checks |
The advantage is the lightweight combination: no new service, readable versioned Tasks, shared write-back by every Agent, human entry from any conversation, and a real large multi-platform delivery behind it.
Codex alone is enough
If the host supports project instructions, multiple Agent sessions, and recurring automation, General Loop needs no extra tool. Its core is only AGENTS.md, agents/, and tasks/; the single prompt at the end adds the protocol and asks whether to start the current conversation when setup is complete.
Connect the AI tools on your machine with Shennian (optional)
When several AI tools are installed on one machine, they are more than separate chat windows: they are execution resources with different strengths, speeds, and costs. Shennian lets the Loop start those local AI tools, follow their live status, and collect results while the same Tasks keep context and progress aligned.
Interface and automation
Send UI operation, computer use, and end-to-end visual checks to an Agent with those capabilities.
Code and deep implementation
Send code analysis, implementation, and refactoring to a coding Agent suited to engineering work.
Fast, cost-efficient work
Send organization, summaries, and routine checks to faster, lower-cost models.
The Loop can choose based on required capability, availability, cost, concurrency, and shared resources: the right Agent handles the right work, while conflict-free Tasks run in parallel. This makes better use of the AI tools already on the machine while reducing waiting and unnecessary high-cost calls. Shennian is one option for this cross-AI path, not a prerequisite for General Loop.