Use when adding new error messages to React, or seeing "unknown error code" warnings.
loop-controller
1
0
# Install this skill:
npx skills add miles-knowbl/orchestrator --skill "loop-controller"
Install specific skill from multi-skill repository
# Description
Orchestrates the engineering loop execution. Manages state machine transitions, decides what to do next, handles failures and retries, determines completion, and triggers human handoffs. The 'brain' that runs the autonomous development cycle.
# SKILL.md
name: loop-controller
description: "Orchestrates the engineering loop execution. Manages state machine transitions, decides what to do next, handles failures and retries, determines completion, and triggers human handoffs. The 'brain' that runs the autonomous development cycle."
phase: META
category: meta
version: "1.0.0"
depends_on: []
tags: [meta, orchestration, control]
Loop Controller
The execution brain of the agentic loop.
When to Use
- Starting a system build β Initialize loop state and begin execution
- Resuming work β Determine where to continue after cold boot
- After any skill completes β Decide what's next
- On failure β Determine retry strategy or escalation
- At checkpoints β Decide if human approval needed
Reference Requirements
MUST read before applying this skill:
| Reference | Why Required |
|---|---|
decision-trees.md |
State transition logic |
gate-procedures.md |
How to handle stage gates |
Read if applicable:
| Reference | When Needed |
|---|---|
failure-handling.md |
When handling failures/retries |
autonomy-configuration.md |
When configuring autonomy mode |
loop-state-schema.json |
When initializing/updating state |
Verification: Ensure loop-state.json is accurate and transitions are valid.
Required Deliverables
| Deliverable | Location | Condition |
|---|---|---|
loop-state.json |
domain-memory/{domain}/ |
Always (maintained) |
Core Concept
Loop Controller answers: "What should I do next?"
It maintains execution state and makes orchestration decisions so the agent doesn't have to reason about the loop itself β just execute the current skill.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LOOP CONTROLLER β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β STATE MACHINE β β
β β β β
β β INIT β SCAFFOLD β IMPLEMENT β TEST β VERIFY β VALIDATE β β β
β β DOCUMENT β REVIEW β SHIP β COMPLETE β β
β β β β
β β Any stage can transition to: FAILED β RETRY or BLOCKED β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β DECISION ENGINE β β
β β β β
β β Current State + Context β Next Action β β
β β β β
β β β’ What skill to invoke? β β
β β β’ Is human approval needed? β β
β β β’ Should we retry or escalate? β β
β β β’ Is the system complete? β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Loop State Machine
States
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LOOP STATES β
β β
β ββββββββββββ β
β β INIT β βββ Load context, verify prerequisites β
β ββββββ¬ββββββ β
β β β
β βΌ β
β ββββββββββββ β
β β SCAFFOLD β βββ Create project structure, setup config β
β ββββββ¬ββββββ β
β β β
β βΌ β
β ββββββββββββ ββββββββββββ ββββββββββββ β
β βIMPLEMENT ββββββΆβ TEST ββββββΆβ VERIFY β βββ Per-capability loop β
β ββββββ¬ββββββ ββββββ¬ββββββ ββββββ¬ββββββ β
β β β β β
β ββββββββββββββββββ΄βββββββββββββββββ (next capability) β
β β β
β βΌ (all capabilities done) β
β ββββββββββββ β
β β VALIDATE β βββ Full system validation (security, perf, integration) β
β ββββββ¬ββββββ β
β β β
β βΌ β
β ββββββββββββ β
β β DOCUMENT β βββ Generate/update documentation β
β ββββββ¬ββββββ β
β β β
β βΌ β
β ββββββββββββ β
β β REVIEW β βββ Self-review, prepare PR β
β ββββββ¬ββββββ β
β β β
β βΌ β
β ββββββββββββ β
β β SHIP β βββ Create PR, await approval, merge β
β ββββββ¬ββββββ β
β β β
β βΌ β
β ββββββββββββ β
β β COMPLETE β βββ Update queue, create handoff, trigger next system β
β ββββββββββββ β
β β
β βββββββββββββββββββββββ FAILURE STATES βββββββββββββββββββββββ β
β β
β ββββββββββββ ββββββββββββ ββββββββββββ β
β β FAILED ββββββΆβ RETRY ββββββΆβ BLOCKED β β
β ββββββββββββ ββββββββββββ ββββββββββββ β
β β β β
β ββββ Auto-retry if retries remain β β
β ββββ Human intervention needed β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
State Definitions
| State | Description | Entry Condition | Exit Condition |
|---|---|---|---|
INIT |
Load context, verify ready | System claimed from queue | Context loaded, worktree ready |
SCAFFOLD |
Create project structure | Init complete | Structure exists, builds |
IMPLEMENT |
Write code for capability | Scaffold done or prev capability done | Code written |
TEST |
Write tests for capability | Implementation done | Tests written |
VERIFY |
Run verification checks | Tests done | Lint, types, tests pass |
VALIDATE |
Full system validation | All capabilities done | Security, perf, integration pass |
DOCUMENT |
Generate documentation | Validation passed | Docs updated |
REVIEW |
Self-review, prep PR | Docs done | PR ready |
SHIP |
Create PR, await merge | Review done | PR merged |
COMPLETE |
Finalize, update queue | PR merged | Queue updated, handoff created |
FAILED |
Something went wrong | Any check fails | Retry initiated or blocked |
RETRY |
Attempting fix | Failure with retries left | Back to failed stage or blocked |
BLOCKED |
Needs human help | Max retries exceeded | Human resolves |
Loop State File
Store execution state in loop-state.json:
{
"systemId": "sys-002",
"systemName": "Work Order Service",
"githubIssue": 123,
"branch": "feature/system-work-orders",
"worktree": ".worktrees/system-work-orders",
"state": "IMPLEMENT",
"stateEnteredAt": "2024-01-17T10:30:00Z",
"capabilities": {
"total": 5,
"completed": 2,
"current": "work-order-assignment",
"remaining": ["status-transitions", "completion-flow"]
},
"stages": {
"INIT": { "status": "complete", "completedAt": "2024-01-17T09:00:00Z" },
"SCAFFOLD": { "status": "complete", "completedAt": "2024-01-17T09:30:00Z" },
"IMPLEMENT": { "status": "in-progress", "startedAt": "2024-01-17T09:35:00Z" },
"TEST": { "status": "pending" },
"VERIFY": { "status": "pending" },
"VALIDATE": { "status": "pending" },
"DOCUMENT": { "status": "pending" },
"REVIEW": { "status": "pending" },
"SHIP": { "status": "pending" },
"COMPLETE": { "status": "pending" }
},
"failures": {
"count": 1,
"maxRetries": 3,
"history": [
{
"stage": "VERIFY",
"capability": "work-order-creation",
"error": "Type error in WorkOrder model",
"timestamp": "2024-01-17T10:15:00Z",
"resolution": "Fixed type definition",
"resolvedAt": "2024-01-17T10:25:00Z"
}
]
},
"gates": {
"architecture": { "required": false },
"security": { "required": true, "status": "pending" },
"database": { "required": true, "status": "approved", "approvedBy": "[email protected]" },
"deploy": { "required": true, "status": "pending" }
},
"checkpoints": [
{ "type": "commit", "hash": "abc1234", "message": "feat: work order model", "at": "..." },
{ "type": "commit", "hash": "def5678", "message": "feat: create endpoint", "at": "..." }
],
"updatedAt": "2024-01-17T10:30:00Z"
}
Skills Logging
Track which skills are invoked, why, and how long they take:
{
"skillsUsage": {
"entry-portal": 1,
"spec": 1,
"estimation": 1,
"architect": 0,
"scaffold": 0,
"implement": 0,
"...": 0
},
"skillsLog": [
{
"skill": "entry-portal",
"reason": "New domain: define dream state and systems",
"startedAt": "2025-01-17T21:48:00Z",
"completedAt": "2025-01-17T22:00:00Z",
"durationMs": 720000,
"status": "complete",
"deliverables": ["dream-state.md", "system-queue.json"],
"referencesRead": ["clarifying-questions.md", "system-decomposition.md"],
"children": [
{
"skill": "spec",
"reason": "Generate FEATURESPEC for first system",
"startedAt": "2025-01-17T21:52:00Z",
"completedAt": "2025-01-17T21:55:00Z",
"durationMs": 180000,
"status": "complete",
"deliverables": ["FEATURESPEC.md"]
}
]
}
]
}
skillsUsage β Count of invocations per skill for this system. Provides at-a-glance view of which skills are being used heavily vs rarely.
skillsLog β Sequential log with full details:
| Field | Description |
|---|---|
skill |
Skill name |
reason |
Why this skill was invoked |
startedAt |
When skill execution began |
completedAt |
When skill finished |
durationMs |
Execution time in milliseconds |
status |
complete, failed, skipped |
deliverables |
Files produced |
referencesRead |
Reference docs consulted |
children |
Nested skill invocations (e.g., entry-portal β spec) |
Logging rules:
- Create log entry when skill starts
- Update with completion time and deliverables when skill finishes
- Increment skillsUsage count on completion
- Nested calls appear as children of parent skill
- Failed skills remain in log with status: failed
Velocity Tracking Integration
For real-time velocity monitoring, also append to metrics.skillHistory when each skill completes:
{
"metrics": {
"skillsInvoked": 5,
"skillHistory": [
{
"skill": "implement",
"timestamp": "2025-01-18T10:30:00Z",
"durationMs": 1800000
}
]
}
}
Required fields:
- skill: Name of the skill invoked
- timestamp: ISO-8601 completion timestamp
- durationMs: Duration in milliseconds (optional but recommended)
This enables velocity-tracker's loop-monitor to detect skill invocations in real-time and display them in the dashboard.
β See references/loop-state-schema.json
Decision Engine
Main Decision Loop
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β DECISION ALGORITHM β
β β
β function decideNextAction(loopState, context): β
β β
β 1. CHECK BLOCKED β
β if state == BLOCKED: β
β return { action: "WAIT_FOR_HUMAN", reason: blockedReason } β
β β
β 2. CHECK GATES β
β gate = getPendingGate(loopState) β
β if gate and gate.required: β
β return { action: "WAIT_FOR_APPROVAL", gate: gate } β
β β
β 3. CHECK FAILURE β
β if state == FAILED: β
β if failures.count < maxRetries: β
β return { action: "RETRY", stage: lastFailedStage } β
β else: β
β return { action: "ESCALATE", reason: "Max retries exceeded" } β
β β
β 4. DETERMINE NEXT STATE β
β nextState = getNextState(currentState, context) β
β skill = getSkillForState(nextState) β
β return { action: "EXECUTE_SKILL", state: nextState, skill: skill } β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
State Transitions
function getNextState(current, context) {
switch (current) {
case "INIT":
return "SCAFFOLD";
case "SCAFFOLD":
return "IMPLEMENT";
case "IMPLEMENT":
return "TEST";
case "TEST":
return "VERIFY";
case "VERIFY":
if (context.capabilities.remaining.length > 0) {
// More capabilities to implement
return "IMPLEMENT";
}
return "VALIDATE";
case "VALIDATE":
return "DOCUMENT";
case "DOCUMENT":
return "REVIEW";
case "REVIEW":
return "SHIP";
case "SHIP":
if (context.prMerged) {
return "COMPLETE";
}
return "SHIP"; // Wait for merge
case "COMPLETE":
return null; // Done
default:
throw new Error(`Unknown state: ${current}`);
}
}
State to Skill Mapping
| State | Primary Skill | Supporting Skills |
|---|---|---|
INIT |
memory-manager (cold boot) |
git-workflow |
SCAFFOLD |
scaffold |
architect |
IMPLEMENT |
implement |
β |
TEST |
test-generation |
β |
VERIFY |
code-verification |
debug-assist on failure |
VALIDATE |
code-validation |
security-audit, perf-analysis, integration-test |
DOCUMENT |
document |
β |
REVIEW |
code-review |
β |
SHIP |
git-workflow |
β |
COMPLETE |
memory-manager (handoff) |
entry-portal (queue update) |
Hard Verification Gates
Build and tests MUST pass before any stage transition. This is enforced, not optional.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β VERIFICATION GATE (HARD REQUIREMENT) β
β β
β BEFORE transitioning from any state: β
β β
β 1. RUN BUILD β
β npm run build (or equivalent) β
β β If fails: STOP, invoke debug-assist, fix, retry β
β β
β 2. RUN TESTS (if tests exist) β
β npm test (or equivalent) β
β β If fails: STOP, invoke debug-assist, fix, retry β
β β
β 3. RUN LINT (if configured) β
β npm run lint (or equivalent) β
β β If fails: STOP, fix lint errors, retry β
β β
β 4. LOG VERIFICATION β
β Record in journey-log: { verification: "pass", timestamp: ... } β
β β
β ONLY proceed to next state if ALL checks pass β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Transition | Required Checks | On Failure |
|---|---|---|
| SCAFFOLD β IMPLEMENT | Build compiles | Fix build errors |
| IMPLEMENT β TEST | Build compiles | Fix build errors |
| TEST β VERIFY | Build + Tests pass | Fix failing tests |
| VERIFY β VALIDATE | Build + Tests + Lint | Fix all issues |
| VALIDATE β DOCUMENT | Build + Tests | Fix regressions |
| DOCUMENT β REVIEW | Build + Tests | Fix regressions |
| REVIEW β SHIP | Build + Tests + Approved | Wait for approval |
No exceptions. Autonomous execution must never ship broken code.
Failure Handling
Failure Detection
| Check Type | Failure Signal | Severity |
|---|---|---|
| Build | Non-zero exit code | High |
| Lint | Lint errors | Medium |
| Type check | Type errors | High |
| Unit tests | Test failures | High |
| Integration tests | Test failures | High |
| Security scan | Critical/High findings | High |
| Performance | Exceeds thresholds | Medium |
Retry Strategy
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β RETRY STRATEGY β
β β
β On Failure: β
β β
β 1. CAPTURE β
β β’ Error message and stack trace β
β β’ Failing file/line if available β
β β’ Test output if test failure β
β β
β 2. DIAGNOSE β
β β’ Invoke debug-assist skill β
β β’ Form hypotheses β
β β’ Identify likely root cause β
β β
β 3. FIX β
β β’ Apply targeted fix β
β β’ Do NOT change unrelated code β
β β’ Commit fix separately β
β β
β 4. VERIFY FIX β
β β’ Re-run failed check β
β β’ Ensure fix doesn't break other tests β
β β’ Run full verification suite β
β β
β 5. CONTINUE OR ESCALATE β
β β’ If fixed: continue to next state β
β β’ If still failing: increment retry counter β
β β’ If max retries: transition to BLOCKED β
β β
β Retry Limits: β
β β’ Default: 3 retries per failure β
β β’ Same error: 2 retries (don't keep trying same thing) β
β β’ Different error: Reset counter β
β β’ Total failures: 10 max before forced BLOCKED β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Escalation to Human
Transition to BLOCKED when:
- Max retries exceeded
- Circular failure (fix breaks something else, fixing that breaks original)
- Security finding requires human decision
- External dependency unavailable
- Ambiguous requirement discovered
Blocked state message:
## π« BLOCKED: [System Name]
**Reason:** [Why blocked]
**Last Failure:** [Error details]
**Retry Attempts:** [X] / [Max]
**What was tried:**
1. [Attempt 1]
2. [Attempt 2]
3. [Attempt 3]
**Human action needed:**
[Specific ask]
**To resume:**
1. Resolve the issue
2. Update loop-state.json: set state to [resume state]
3. Run loop controller
β See references/failure-handling.md
Verification Gates (Hard Requirements)
Build and tests MUST pass before any stage transition. This is a hard gate, not optional.
Verification Matrix
| Transition | Required Checks | Block If |
|---|---|---|
| SCAFFOLD β IMPLEMENT | Build compiles | Build fails |
| IMPLEMENT β TEST | Build compiles | Build fails |
| TEST β VERIFY | Build + Unit tests | Any test fails |
| VERIFY β VALIDATE | Build + All tests + Lint | Verification fails |
| VALIDATE β DOCUMENT | Build + All tests | Validation fails |
| REVIEW β SHIP | Build + All tests + Review approved | Any check fails |
Verification Protocol
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β HARD VERIFICATION GATE β
β β
β BEFORE any stage transition: β
β β
β 1. RUN BUILD β
β npm run build (or equivalent) β
β If fails β STOP, do not transition β
β β
β 2. RUN TESTS β
β npm test (or equivalent) β
β If fails β STOP, do not transition β
β β
β 3. RUN LINT (if configured) β
β npm run lint (or equivalent) β
β If fails β STOP, do not transition β
β β
β 4. RECORD RESULT β
β Log verification status in journey-log β
β Update loop-state.json with lastVerification timestamp β
β β
β ONLY if all pass β Transition to next stage β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Verification Commands
Standard commands to run (adapt to project):
# TypeScript/Node
npm run build && npm test && npm run lint
# Python
python -m pytest && python -m flake8 && python -m mypy .
# Django
python manage.py check && python manage.py test
# Rust
cargo build && cargo test && cargo clippy
On Verification Failure
- Do NOT proceed to next stage
- Invoke
debug-assistskill to diagnose - Fix the issue
- Re-run verification
- Only transition when all checks pass
This ensures autonomous execution never ships broken code.
Mandatory Skill Enforcement
Phase Skill Requirements
Before transitioning out of any phase, ALL required skills for that phase MUST be completed (or explicitly skipped).
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MANDATORY SKILL CHECK β
β β
β BEFORE transitioning from any phase: β
β β
β 1. GET REQUIRED SKILLS β
β required = skillExecution[currentPhase].required β
β β
β 2. CHECK COMPLETION β
β completed = skillExecution[currentPhase].completed β
β skipped = skillExecution[currentPhase].skipped β
β missing = required - completed - skipped β
β β
β 3. BLOCK IF MISSING β
β if missing.length > 0: β
β Display: "β οΈ Cannot proceed: [skill] not invoked" β
β Options: β
β - Invoke the skill now β
β - Skip with reason: skip [skill] --reason "explanation" β
β STOP - do not transition β
β β
β 4. VERIFY DELIVERABLES β
β Run skill-verifier on all completed skills β
β if verification fails: BLOCK β
β β
β 5. PROCEED β
β Only if all checks pass β Transition to next phase β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Required Skills by Phase
| Phase | Required Skills |
|---|---|
| INIT | entry-portal, requirements, spec, estimation, triage, memory-manager |
| SCAFFOLD | architect, architecture-review, scaffold, git-workflow |
| IMPLEMENT | implement |
| TEST | test-generation |
| VERIFY | code-verification (+ debug-assist if tests fail) |
| VALIDATE | code-validation, integration-test, security-audit, perf-analysis |
| DOCUMENT | document |
| REVIEW | code-review, refactor |
| SHIP | deploy, git-workflow |
| COMPLETE | memory-manager, retrospective, calibration-tracker, loop-controller |
Skip Command
When a mandatory skill cannot be completed, use the skip command:
skip [skill] --reason "explanation"
Example:
skip git-workflow --reason "No git repo configured, user chose to continue without version control"
skip security-audit --reason "CLI tool with no user input, security audit not applicable"
Skips are recorded in:
- loop-state.json β skillExecution[phase].skipped
- journey-log.jsonl β Entry with status: "skipped" and reason
Prerequisite Prompts
For skills with external dependencies:
| Skill | Prerequisite | Prompt |
|---|---|---|
| git-workflow | .git/ directory | "No git repo configured. 'init' to create or 'skip git' to continue without" |
| deploy | Deploy target | "No deploy target configured. Specify target or 'skip deploy' to skip" |
Record prerequisite decisions in loop-state.json:
{
"prerequisites": {
"git": { "status": "configured|skipped", "prompted": true },
"deploy": { "status": "configured|skipped", "target": "npm publish", "prompted": true }
}
}
Human Gates
Gate Types
| Gate | Trigger | Approver | How to Approve |
|---|---|---|---|
architecture |
New patterns, major structural changes | Tech Lead | PR comment: "architecture approved" |
security |
Auth, crypto, PII handling | Security Team | Security review checklist |
database |
Schema migrations | DBA | Migration review |
external |
Third-party API integration | Tech Lead | Integration review |
deploy |
Production merge | Release Manager | PR approval |
Gate Enforcement
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β GATE CHECK β
β β
β function checkGates(loopState, changesInStage): β
β β
β // Determine which gates apply β
β requiredGates = [] β
β β
β if changesInStage.hasNewArchitecturalPatterns: β
β requiredGates.push("architecture") β
β β
β if changesInStage.touchesSecurity: β
β requiredGates.push("security") β
β β
β if changesInStage.hasSchemaChanges: β
β requiredGates.push("database") β
β β
β if changesInStage.hasExternalAPIs: β
β requiredGates.push("external") β
β β
β // Always require deploy gate for SHIP β
β if currentState == "REVIEW": β
β requiredGates.push("deploy") β
β β
β // Check approval status β
β for gate in requiredGates: β
β if not loopState.gates[gate].approved: β
β return { blocked: true, gate: gate } β
β β
β return { blocked: false } β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Requesting Approval
When gate is required:
1. Create PR (or update existing)
2. Add appropriate label (needs:security-review, etc.)
3. Add reviewer
4. Post comment explaining what needs review
5. Transition to waiting state
6. Check periodically for approval
# Request security review
gh pr edit $PR_NUMBER \
--add-label "needs:security-review" \
--add-reviewer @security-team
gh pr comment $PR_NUMBER --body "## Security Review Requested
This PR includes authentication changes:
- JWT token handling in \`src/auth/\`
- Password hashing in \`src/users/\`
Please review per security checklist."
β See references/gate-procedures.md
Completion Criteria
System Complete When
All must be true:
- [ ] All capabilities implemented
- [ ] All tests passing
- [ ] Code verification passing (lint, types, complexity)
- [ ] Code validation passing (logic, requirements)
- [ ] Security audit passing (no critical/high)
- [ ] Performance targets met
- [ ] Documentation updated
- [ ] Code review self-assessment passing
- [ ] PR approved and merged
- [ ] All required gates approved
Completion Actions
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ON COMPLETION β
β β
β 1. UPDATE QUEUE β
β β’ Set system status to "complete" β
β β’ Set completedAt timestamp β
β β’ Identify newly unblocked systems β
β β
β 2. CREATE HANDOFF β
β β’ Document what was built β
β β’ Note any deferred items β
β β’ Archive to sessions/ β
β β
β 3. UPDATE INTERFACES β
β β’ Finalize API contracts β
β β’ Update event schemas β
β β’ Notify dependent systems β
β β
β 4. CLEAN UP β
β β’ Remove loop-state.json (or archive) β
β β’ Remove worktree β
β β’ Delete branch (if configured) β
β β
β 5. TRIGGER NEXT β
β β’ Check queue for next ready system β
β β’ If found and auto-continue: start next β
β β’ If found and manual: notify human β
β β’ If none: report domain progress β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Running the Loop
Manual Execution
# 1. Initialize loop for a system
./loop init sys-002
# 2. Run one iteration
./loop next
# 3. Check status
./loop status
# 4. Run until blocked or complete
./loop run
# 5. Resume after human intervention
./loop resume
Session Integration
At start of session:
1. Cold boot (memory-manager)
2. Load loop-state.json
3. Call loop controller: decideNextAction()
4. Execute returned action
5. Update loop-state.json
6. Repeat until session ends or system completes
At end of session:
1. Complete current skill cleanly (don't leave mid-implementation)
2. Commit any pending changes
3. Update loop-state.json
4. Create session handoff (memory-manager)
5. Save all state files
Loop Commands Reference
Initialize
# From queue, claim next ready system
loop init --next
# Specific system
loop init sys-002
# Creates:
# - Worktree
# - loop-state.json
# - Initial branch
Status
loop status
# Output:
# System: Work Order Service (sys-002)
# State: IMPLEMENT (capability 3/5: work-order-assignment)
# Failures: 1 (resolved)
# Gates: database β, security pending
# Last activity: 2024-01-17T10:30:00Z
Next
loop next
# Executes one state transition:
# 1. Decide next action
# 2. Execute skill
# 3. Update state
# 4. Return
Run
loop run
# Runs until:
# - COMPLETE reached
# - BLOCKED reached
# - Gate requires approval
# - Max iterations (safety)
Resume
loop resume
# After human intervention:
# 1. Validates state
# 2. Clears BLOCKED if resolved
# 3. Continues from current state
Relationship to Other Skills
| Skill | Relationship |
|---|---|
| All 17 other skills | Loop controller invokes them based on state |
memory-manager |
Provides cold boot and handoff |
entry-portal |
Provides systems to build, queue updates |
git-workflow |
Provides worktree and PR operations |
debug-assist |
Invoked on failures |
Key Principles
One state at a time. Complete current state before transitioning.
Fail fast, retry smart. Detect failures immediately, diagnose before retrying.
Gates are non-negotiable. Never bypass required human approvals.
State is sacred. Always update loop-state.json after any change.
Clean handoffs. Never end session with corrupt or ambiguous state.
References
references/loop-state-schema.json: JSON Schema for state filereferences/failure-handling.md: Detailed retry and escalation logicreferences/gate-procedures.md: How to request and check approvalsreferences/decision-trees.md: Visual decision flowcharts
# Related Skills
Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging...
Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.
Use when you need to check feature flag states, compare channels, or debug why a feature behaves...
# Supported AI Coding Agents
This skill is compatible with the SKILL.md standard and works with all major AI coding agents:
Amp
Antigravity
Claude Code
Clawdbot
Codex
Cursor
Droid
Gemini CLI
GitHub Copilot
Goose
Kilo Code
Kiro CLI
OpenCode
Roo Code
Trae
Windsurf
Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.