Agent Loop

Current version: 1.5.3 (development)

Agent Loop is a reusable controller skill for single-human, CLI-agent software development. It lets the Agent own project diagnosis, workflow sequencing, implementation, verification, and memory maintenance while the human keeps control of goals, product meaning, consequential decisions, and external actions.

Human-directed · Agent-owned · Evidence-verified

The human sets the goal and confirms consequential decisions. Between those gates, the Agent independently understands the project, shapes the product, selects the smallest safe delivery route, plans and implements, verifies the result, repairs drift, updates durable memory, and recommends the next action.

Open the interactive autonomous workflow to follow the Agent-owned path and Human Gates, or inspect its Archify workflow source.

The diagram is an overview, not the runtime source of truth. Open the interactive capability map to inspect relationships and guided views, or review its Archify workflow source. Canonical behavior remains in references/design.md and references/runtime.md.

The primary loop is:

Human Goal
→ Agent Loop Controller
→ Product Definition
→ Design Readiness / Decision & Design If Needed
→ Right-sized Delivery
→ Fresh Verification and Review
→ Project Memory and Verified Close

Existing legacy onboarding-db files remain readable evidence; migration requires the current Onboarding gates.

Agent Loop uses Adaptive Product Definition and an internal Requirement/Product Grill to turn a human need into an accepted product definition.

During requirements discussion, the agent records Design Readiness evidence and Decision Candidates without creating ADR files. A requirement-driven ADR resolves an Effective Requirement Snapshot and gives every in-scope model ID a Requirement Model Technical Landing Trace before Feature Spec.

New Feature work creates no Feature product.md; Feature spec.md selects a bounded Product Slice from the effective Requirement Product Definition.

Feature work now starts from a local Feature Context Snapshot in spec.md. Agent Loop first scans objective facts for the real Requirement product.md selected by Requirement README plus applicable ADRs. CURRENT uses the fast path; CHANGED lets the Agent assess semantic impact and refresh derived evidence without turning ordinary drift into a checker failure; only physical authority contradictions return BLOCKED. The Snapshot is derived context, never a second product truth.

Feature delivery includes:

• direct Product Requirement Source and bounded Product Slice in spec.md
• freshness-checked Feature Context Snapshot for Task, Test, Plan, Resume, Execute, Handoff, Verify, Review, Drift, and Close
• story/task breakdown, test design, Web E2E discovery, and construction-grade planning
• TDD with real RED/GREEN evidence for behavior changes
• optional Delivery Contracts for durable producer-consumer boundaries
• optional project-local Skills for repeatable, verified project operations
• mandatory helper resolution for Project Skill Creation / Update, Brainstorm, Plan Gate, execution, diagnosis, verification, and review
• Feature Auto-Loop and Task Auto-Run for uninterrupted Agent-ready work
• approved subagent execution and complex artifact modes when scale requires them

Feature construction uses two meaningful reviews instead of interrupting the human after every internal quality stage. Feature Definition Review confirms Goal, Scope, Acceptance, and Explicit Exclusions. The Agent then writes and self-reviews tasks, tests, E2E evidence, code context, Plan, verification, risk, and rollback without changing target code. Implementation Readiness Review confirms the Execution Boundary, Verification, Risk/Rollback, and whether to start. The Agent directly owns Human intent, complete Package Files, Gate/action/time consistency, and all Task/Plan/product semantics; Feature Gate acceptance and continuation do not depend on a local digest or Feature review Checker. New Agent-ready Task IDs inside the same accepted Story/Product Slice/Acceptance do not require another Human Gate—even when every initial Task ID is replaced—but new execution boundaries do. Delivery Contract, Human-gated tasks, subagent, Git, external, submit, close, and release actions remain separately gated.

For a later start after package-only acceptance, the Agent re-reads the recorded package files and current Feature artifacts, compares them with the accepted boundary, checks the Human instruction and stop conditions, preserves the original Gate 2 baseline, and records a separate start transition plus current execution mode. If Human decision evidence is unavailable after context loss, the Agent asks once.

Agent Loop does not treat “code written” as done. Completion requires proportional, fresh evidence:

Execute
→ Verify
→ Review
→ Drift Check
→ Project Memory Update
→ Feature Completion Check
→ Human-reviewed Submit / Pause / Close

The Agent checks implementation, tests, requirement and decision coverage, unrelated changes, stale documentation, rollback, residual risk, and the next recoverable action. Structural validators help, but never replace semantic Human Review.

Small, fact-determined memory conflicts are resolved and verified by the Agent without creating a report. The human sees only the few alternatives that remain genuinely ambiguous. A concise Memory Merge Report is reserved for coupled conflicts, cross-session work, substantial rollback evidence, or an explicit request. Four-snapshot, all-path Scan → Plan → Apply → Restore tooling is available only through an explicitly authorized Full Memory Audit / Recovery.

The Agent owns:

• inspecting available evidence before asking
• identifying the current stage and smallest safe route
• planning at the depth the risk needs
• implementation, tests, verification, review, drift repair, and documentation backfill
• keeping work resumable and recommending the next action
• continuing authorized work until verified completion or a real Human Gate

The human owns:

• goals, scope, source requirements, and accepted product meaning
• unresolved product or technical choices with material consequences
• changes to human-authored source material
• production, paid, secret-bearing, destructive, or external-service actions
• branch mutation, commit, push, PR, merge, tag, release, and publish
• acceptance of ADRs, Delivery Contracts, Feature close, Bug close, and other explicit lifecycle gates

Approving one gate never approves another.

Install Agent Loop directly from GitHub with the open skills CLI. This is the recommended external installation path for Codex, Kimi Code CLI, Claude Code, and OpenCode:

npx -y skills add Shadow-linux/agent-loop \
  --global \
  --skill agent-loop \
  --agent codex \
  --agent kimi-code-cli \
  --agent claude-code \
  --agent opencode \
  --yes

The unqualified GitHub source follows main, which Agent Loop maintains as the latest formal stable release channel. Alpha branches are available only through an explicitly selected source revision and never replace the default channel.

For an interactive Agent selection:

npx skills add Shadow-linux/agent-loop -g

Update Agent Loop and check the global installation:

npx skills update agent-loop -g
npx skills list -g

The public GitHub route requires Node.js 18 or later.

Use this route when npx is unavailable or the environment must install from a Git mirror. Choose exactly one source:

# Public GitHub
git clone \
  --branch stable-v1.5.2 \
  --depth 1 \
  https://github.com/Shadow-linux/agent-loop.git \
  ~/.local/share/agent-loop-source

# Private Git mirror
git clone \
  --branch stable-v1.5.2 \
  --depth 1 \
  <git-mirror-url> \
  ~/.local/share/agent-loop-source

On macOS or Linux, synchronize the checked-out Skill into the shared Agent Skills directory:

mkdir -p ~/.agents/skills/agent-loop
rsync -ac --delete \
  --exclude='.git' \
  --exclude='.DS_Store' \
  --exclude='__pycache__/' \
  ~/.local/share/agent-loop-source/ \
  ~/.agents/skills/agent-loop/

On Windows PowerShell, use the equivalent mirrored copy:

$Source = "$HOME\.local\share\agent-loop-source"
$Target = "$HOME\.agents\skills\agent-loop"
New-Item -ItemType Directory -Force $Target | Out-Null
robocopy $Source $Target /MIR /XD .git __pycache__ /XF .DS_Store
if ($LASTEXITCODE -ge 8) { exit $LASTEXITCODE }

For a later clone-based upgrade, fetch tags, check out the new stable tag explicitly, and repeat the platform-specific synchronization:

git -C ~/.local/share/agent-loop-source fetch --tags origin
git -C ~/.local/share/agent-loop-source checkout --detach stable-v1.5.2

~/.agents/skills/agent-loop is the preferred shared location. If an Agent runtime does not discover it, synchronize the same verified source into that runtime's configured Skill directory rather than maintaining divergent copies.

Verify the installed version in SKILL.md, then refresh the managed guidance of every active Agent Loop project:

Do not copy Agent Loop into a target project's .agent-loop/; that directory stores project memory and work artifacts, not the Skill package.

Tell the Agent:

Use Agent Loop to take over this project.
See where things stand, then keep the agreed work moving until you need a decision from me.

The Agent will inspect project state before proposing .agent-loop/ memory or root guidance. It will not create a Feature merely because the task has several steps.

I have a product idea, but it is still rough. Help me clarify it before we build anything.
Let me know first if a full product-design pass will take a lot of discussion or tokens.

After the product definition is accepted, ask:

The product definition is approved. Work out what technical design is still needed,
then start with the smallest sensible implementation slice.

Continue the last Agent Loop task.
Check the current state first, then resume from the safest point.

See Usage.md for copy-ready prompts covering requirements, ADR, lightweight changes, Features, Bugs, project-local Skills, branch strategy, archive/rehydrate, post-merge memory reconciliation, submission, and close.

.agent-loop/
  project.md                    # stable project memory
  project/                      # optional enterprise memory
  onboarding-db/                # project understanding knowledge base
  requirements/
    YYYY-MM-DD-<topic>/
      README.md                 # lifecycle and effective source pointer
      product.md                # accepted Brief/Standard product definition
      sources/                  # preserved human originals
      visuals/                  # optional derived visual sources/renders
  decisions/
    0001-<decision>.md          # optional, Human-gated ADR
  changes/
    YYYY-MM/
      YYYY-MM-DD-<topic>.md     # persistent lightweight execution card
  bugs/
    INDEX.md
    YYYY-MM-DD-<bug>/
      README.md
      evidence/
  features/
    archive.md
    YYYY-MM-DD-<feature>/
      spec.md
      tasks.md
      tests.md
      plan.md
      notes.md
      contracts.md              # optional
    YYYY-MM/
      YYYY-MM-DD-<feature>/     # archived directory kept intact
  skills/
    INDEX.md
    <skill-name>/
      SKILL.md
      validation.md
  memory-merges/
    MM-<merged-code-sha>-<topic>/
      README.md                 # only for complex or durable conflict review

New projects use .agent-loop/. A visible legacy agent-loop/ root remains readable and requires Human-confirmed migration. Dual roots fail closed.

Ordinary post-merge handling does not create memory-merges/: no observed conflict means no scan or report, and a small conflict stays in the conversation unless durable coordination or recovery evidence is needed.

Project-local capability discovery starts at .agent-loop/skills/; runtime/global Skill inventory does not replace .agent-loop/skills/INDEX.md.

Agent Loop remains the controller when it uses Superpowers-style helpers, project-local Skills, Archify, or other adapters. Helpers can improve a stage method; they cannot change Agent Loop artifact ownership, stage order, status, or Human Gates.

For complex product or technical communication, Agent Loop prefers an active project-local visual skill, then installed Archify. When Archify is absent but would materially improve review, the Agent recommends its exact installation/use before offering Mermaid/ASCII/text; fallback remains valid after decline, unsupported environments, or failure. Installing any external skill requires separate, exact Human authorization.

The visual rule is:

Render to converge; text to record.

Working visuals help humans correct the Agent's understanding. Accepted meaning must be rewritten into the owning Markdown. A durable visual additionally binds typed source and render with digests and validation evidence.

In Feature Spec, a visual may explain only the accepted Product Slice, feature responsibility, and feature-local implementation or acceptance path. Accepted feature-local clarification returns to spec.md; new product meaning returns to Requirements Discussion and is never written directly to Requirement product.md from Feature Spec.

references/design.md owns the core model and constraints; references/runtime.md owns executable routing, stage order, gates, and state transitions.

MIT