loop — Engineered Orchestration

/loop enters a goal-oriented self-loop: LLM explores the project, builds a plan with user confirmation, executes each task with verification, and self-corrects on failure.

How It Works

/loop <goal>
  → Explore project context (read-only tools)
  → User confirms exploration → Plan tasks with verify commands
  → User confirms plan → Execute each task → Verify → ✓ Pass / ✗ Retry
  → Summary

The key difference from harness: every major phase requires user confirmation before proceeding.

Architecture

AgentLoop (编排器: 探索→规划→执行→验证→汇总)
  └── ChatService._call_llm_with_tools()
        └── HarnessEngine (工具循环内核，复用 harness 引擎)
              ├── StreamEngine (流式传输 + watchdog)
              └── ToolExecutor (工具执行)

/loop runs on top of harness — each task execution internally calls the harness tool-use loop. The AgentLoop adds structured phases and user confirmation gates around it.

Pipeline Phases

Phase 1: Explore (探索)

LLM uses read-only tools (kg_find_symbol, read_file, glob_files, grep_content) to understand the project's current state — file paths, existing interfaces, tech stack.

The exploration summary is presented to the user with three options:

Action	Effect
Enter	Accept exploration, proceed to planning
Type text	Provide correction/instruction, re-explore
q	Cancel the loop

Phase 2: Plan (规划)

LLM decomposes the goal into a JSON task list. Each task contains:

Field	Description
`desc`	Task description (specific enough to execute directly)
`constraints`	Technical/design/naming constraints
`acceptance`	Verifiable acceptance criteria
`verify`	Machine-checkable verification command (optional)

The task list is presented to the user with three options:

Action	Effect
Enter	Confirm plan, start execution
Type text	Provide correction, re-plan
q	Cancel the loop

Phase 3: Execute (执行)

Tasks execute sequentially. Each task:

Enters a harness tool-use loop (LLM reads files, edits code, runs commands)
First round forces read-only tools (explore before acting)
After the harness loop completes, runs the verify command
On failure: feeds failure reason back into the task (self-correction), up to 3 retries

Phase 4: Summary (汇总)

Reports completion status for every task:

目标完成情况：4/5 任务验证通过
目标：Add phone_number column

[OK] 任务1: Create migration SQL — 验证通过
[OK] 任务2: Update SQLAlchemy model — 验证通过
[OK] 任务3: Update API endpoints — 验证通过（尝试 2 次）
[OK] 任务4: Add validation — 验证通过
[!!] 任务5: Run tests — 验证失败: test_phone_format FAILED

Marker	Meaning
`[OK]`	Passed verification
`[!!]`	Failed after 3 self-correction retries

Dual Gate System

Gate	Limit	Purpose
Task rounds	MAX_ROUNDS = 20	Hard cap on total tasks executed
Per-task retries	MAX_RETRIES = 3	Self-correction attempts per task
User re-do	MAX_REDO = 3	Max re-exploration / re-planning rounds

3 failures don't interrupt the loop — the step is marked as [!!] and the loop continues with remaining tasks.

Verification Strategy

Default Mode

Compile/syntax check commands run normally (e.g., py_compile, mvn compile, pytest)
Startup commands are intercepted (npm start, python app.py, etc.) and automatically downgraded to compile checks

--run Mode

/loop --run <goal> enables startup command execution:

Long-running commands are allowed
On timeout: user chooses between compile downgrade, retry, or skip
Use for tasks that genuinely need to boot the application

Auto-Downgrade Map

Startup Command	Fallback
`spring-boot:run`	`mvn compile -q`
`npm start`	`npm run build --if-present`
`python app.py`	`python -m py_compile app.py`
`flask run`	`python -m py_compile app.py`
`django runserver`	`python manage.py check`

When to Use /loop

Good For	Not Ideal For
Decomposable tasks	Exploratory research
Multi-file refactoring	Single quick edits
Migration scripts	Tasks requiring creative decisions
CI/CD pipeline changes	Ambiguous requirements

Example: Database Migration

/loop Add a new `phone_number` column to the users table:
1. Create migration SQL file
2. Add column to SQLAlchemy model
3. Update all API endpoints that return user data
4. Add validation for phone format
5. Run tests and verify

/loop will:

Explore the project to find existing models, endpoints, and test patterns
Present exploration summary for your confirmation
Generate a task list with specific file paths and verify commands
Present the plan for your confirmation
Execute each task sequentially with self-correction
Report results with pass/fail status

Example: Dependency Upgrade

/loop Upgrade httpx from 0.24 to 0.27:
1. Update requirements.txt
2. Run pip install
3. Fix all import errors
4. Run test suite
5. Update CI config if needed

Tips

Be Specific About Verification

/loop works best when each step has a clear success criterion:

# Good — clear verification
/loop Refactor the auth module:
1. Move login/register to auth/service.py
2. Update imports in all files that use them (verify: grep returns 0 old imports)
3. Run tests (verify: all tests pass)

# Vague — hard to verify
/loop Refactor the auth module

Use Corrections During Confirmation

At each confirmation gate, you can type a correction instead of pressing Enter:

After exploration: "You missed the utils/auth.py helper functions — include them in the plan"
After planning: "Task 3 should also update the API docs in docs/api.md"

This triggers a re-run of that phase with your feedback injected.

Each Step Uses Harness Internally

You get the best of both worlds:

harness handles the complexity within each step (file reading, editing, command execution)
/loop provides structure and verification between steps