Current version: 1.2.1
A reusable Codex / CLI-agent skill for single-person software development workflows—from goal intake to verified close.
Agent Loop is a controller skill. It tells the agent:
- What stage the project is in
- Which reference to load next
- What artifacts to produce or update
- When to stop and ask the human
The human controls goals, source requirements, and stage gates. The agent controls workflow mechanics, artifacts, implementation, verification, and backfill.
Without a structured loop, agents tend to:
- Skip specification and jump straight to code
- Miss edge cases and drift from requirements
- Leave tasks "done" without fresh verification
- Lose project context between sessions
Agent Loop fixes this with a repeatable, inspectable workflow:
Project Entry → Remote Project Discovery if needed
→ Re-Adopt Agent Loop Project if needed
→ Project Onboarding Scan if needed → Requirement Archive
→ Product Brief if needed → Brainstorm / Clarify if needed
→ Feature Follow-up / Flow-back if needed
→ Targeted Feature Scan if needed → Feature Spec → Requirement Checklist
→ Work Breakdown → Delivery Contract if needed → Test Design
→ E2E Discovery if Web → Technical Design / Code Context
→ Plan Gate / Plan if needed → Analyze Consistency
→ Subagent Execution if approved → Execute Task / Story
→ Verify → Review → Drift Check → Project Memory Update
→ Feature Completion Check → Submit / Integrate if requested
→ Pause / Close
| Concept | Meaning |
|---|---|
| Feature | One behavior-changing work area under .agent-loop/features/<date>-<slug>/ |
| Story | User-perspective slice inside a feature (e.g. US1, US2) |
| Task | Default executable engineering unit. Small, verifiable, tied to a story. |
| Plan | Construction-grade execution plan for the active task/story |
| Evidence | Fresh proof: test output, build output, API results, E2E checks, logs |
| Drift | Mismatch between docs, code reality, or human decisions |
| Feature Follow-up / Flow-back | Bug/change intake that checks recent features before creating a new feature. Default lookback is 30 days. |
| Delivery Contract | Optional producer-consumer boundary handoff. Used only when API, event, public data, UI state/behavior, SDK/library, runtime, or explicit cross-agent/human handoff needs a stable contract. |
.agent-loop/
remote.md # optional local-entry pointer for remote projects
project.md # Long-term project memory
project/ # optional enterprise memory detail files
onboarding-db/ # optional human-readable project onboarding docs
maps/ # optional categorized navigation docs
modules/ # optional core module detail docs
flows/ # optional flow detail docs
runtime/ # optional run / async / deploy docs
domain/ # optional data / state / glossary docs
quality/ # optional testing / risk docs
requirements/
YYYY-MM-DD-<topic>/
README.md
requirement.*
prototype.*
feedback.*
notes.*
features/
YYYY-MM-DD-<feature-slug>/
product.md (optional)
spec.md
tasks.md
tests.md
plan.md
notes.md
contracts.md (optional)
tasks/ (optional complex details)
tests/ (optional complex details)
plans/ (optional dated plan cycles)
handoffs/ (optional subagent briefs and returns)
contracts/ (optional contract details)
New target projects use .agent-loop/ by default. Existing visible agent-loop/ roots remain readable as legacy memory and should be migrated only after human confirmation.
Copy this directory into your agent's skill path:
# For Codex CLI
~/.codex/skills/agent-loop/
# For project-local use
./.kimi/skills/agent-loop/Tell the agent:
"Let's set up agent-loop for this project."
The agent will:
- Inspect the repo
- Classify the entry scenario (new / existing / remote / resume)
- Load the right references
- Propose
.agent-loop/project.md, rootAGENTS.md, and aCLAUDE.mdpointer toAGENTS.md
For existing projects, the agent offers onboarding modes:
| Mode | Use When |
|---|---|
| Quick Onboarding | Build enough project memory to continue feature work soon |
| Deep Project Onboarding Scan | Generate newcomer-readable .agent-loop/onboarding-db/, diagrams, walkthroughs, evidence chains, and backfill proposals |
| Targeted Onboarding Scan | Understand one module, flow, async task, deployment path, or problem area |
"I want to add login."
After project init/onboarding is accepted, the agent will:
- Archive your requirement
- Write
spec.mdwith stories and acceptance criteria - Break down
tasks.md - Design
tests.md - Execute tasks with TDD
"带我熟悉这个项目，从哪里开始看？"
If .agent-loop/onboarding-db/ exists, the agent uses it first: it checks freshness, gives a short orientation, recommends one reading path, answers targeted questions, and proposes focused diagram/doc updates only after confirmation.
Deep onboarding defaults to Expanded onboarding-db output. Expanded has a minimum required set for project overview, maps, setup, data model, testing, risks, and core module docs. It is also discovery-driven: when the scan finds complex flows, async/jobs, deployment, security, observability, or complex entities, the agent must create the matching docs or record why they were skipped. Diagram coverage grows with project complexity: large projects should get more focused module, flow, state, async/job, data, and deployment diagrams instead of one overloaded global view. Diagrams are embedded in the relevant docs by default and every diagram needs both How To Read and Step-by-Step Walkthrough text. Standalone diagrams/ files are created only when a diagram is reused or too large to embed comfortably.
After each onboarding explanation, the agent should recommend one next action: read a specific doc, inspect a module/flow, generate or update a focused diagram, run a setup/verification command, or return to feature development.
Compact or Standard onboarding-db layouts are used only when the human explicitly requests fewer/simpler files, or when maintaining an existing onboarding-db already organized that way. Onboarding-db human-readable docs default to Chinese, while code symbols, file paths, commands, API names, and artifact names stay as-is.
"Continue the login feature."
The agent reads .agent-loop/project.md, finds the active feature, and resumes from the last checkpoint.
"测试发现上次做的上传功能有 bug."
The agent does not immediately create a new feature. It first checks recent features, using a 30-day default lookback window, then presents candidate matches with evidence. After human confirmation it either flows the work back to the owning feature, creates a linked new feature, creates a Feature Type: maintenance-fix feature, or investigates first.
If a closed feature is reopened for follow-up, the original close record remains intact. The follow-up gets its own notes.md intake record, updated tasks/tests/plan as needed, fresh verification, review, drift check, and a new close confirmation.
If no recent feature owns the bugfix and the work is not a new product capability, the agent creates a narrow maintenance-fix feature under .agent-loop/features/YYYY-MM-DD-fix-<slug>/. Maintenance fixes still use spec/tasks/tests/plan/notes, fresh verification, review, drift check, project memory impact check, and close.
| Mode | Description |
|---|---|
| Strict Mode (default) | Agent asks before and after every stage |
| Feature Auto-Loop | After Feature Spec acceptance, agent advances Agent-ready stages automatically |
| Task Auto-Run | After plan acceptance, agent completes one task/story through TDD, verification, review, and drift check |
Auto modes still stop for Human-gated decisions, unclear decisions, risky changes, failed verification, drift needing approval, unrelated dirty work blocking progress, human original requirement changes, first-version exclusions, Delivery Contract creation/acceptance/breaking changes, directory guidance changes, unapproved subagent dispatch, submit, pause, close, commit, PR, merge, release, or publish.
Agent Loop can use external skills such as Superpowers for brainstorming, construction-grade planning, TDD, debugging, verification, review, finishing, and bounded subagent execution.
Before falling back to built-in stage guidance, the agent should scan the current runtime for available stage helpers and prefer matching helpers such as Superpowers when present.
External skills are stage helpers only. Agent Loop still owns artifact paths, human gates, task status, project memory, drift, submit, pause, and close. Native external directories such as docs/superpowers/* are not created by default.
contracts.md is not a default artifact for every feature. The agent should suggest a Delivery Contract only when the human asks for cross-boundary handoff/API/interface documentation, or when the agent detects a likely downstream consumer such as frontend, another service, SDK user, shared event, public data schema, UI state contract, or runtime integration.
Simple single-person tasks, pure internal logic, and changes with no downstream consumer should skip contract files.
- Initialize agent-managed development in a new or existing project
- Re-adopt an old
agent-loopproject after code changed without updating docs - Turn requirements or prototypes into specs, tasks, tests, plans, and implementation
- Continue a paused feature or recover project context
- Execute a task/story with TDD and verification
- Submit, pause, resume, or close a feature
- One-off edits that explicitly bypass workflow
- Changes that do not affect feature behavior, public interfaces, or project memory
See examples/:
login-feature/— Small feature with TDD workflowcomplex-saas-project/— Larger takeover + feature execution with delivery contractsremote-entry/— Local directory pointing to a remote project
This skill stays aligned with:
draft_agent_loop_struct.mdfinal_agent_loop_skill_design.md
If a reference conflicts with either design source, the design source wins.
MIT