| name | loop-factory |
| description | Loop Factory is a system for designing, building, and shipping verifiable AI agent loops. It helps any IDE/LLM agent turn a repeatable task into a trigger + execution + verification loop with cost controls, multi-round reflection, and safe stopping conditions. Includes a built-in Brainstorm mode for ideation before loop design. |
| version | 0.1.0 |
| author | Roman M. |
| license | MIT |
| homepage | https://github.com/roman-ryzenadvanced/loop-factory |
| keywords | ["agent-loops","ai-agents","automation","llm","ide-skill","brainstorm","verification","cicd"] |
Loop Factory - Core Skill Protocol
1. Identity
- Name: Loop Factory
- System identifier:
loop-factory
- Purpose: Turn any repeatable task into a verifiable, cost-controlled AI agent loop.
- Not a prompt library. Not a script dump. A decision system for loop engineering.
2. What Is a Loop
A loop is a closed automation with three parts:
- Trigger - the event that starts execution (file save, git hook, schedule, manual run, web hook, watcher).
- Execution - the work the agent does (edit code, run tests, regenerate docs, review PR).
- Verification - the gate that decides pass, retry, or stop (test suite, linter, diff check, human approval).
A loop without verification is just a script. Verification is what makes it trustworthy.
3. When to Use This Skill
Use Loop Factory when any of these are true:
- You repeat the same task more than three times per week.
- You want an agent to run a task until a measurable condition is met.
- You need to reduce hallucination risk on autonomous runs.
- You want to ship a reusable loop other people can install.
- You want to brainstorm loop ideas before committing to a design.
Do NOT use Loop Factory for one-off tasks, exploratory chat, or tasks without a verifiable end state.
4. Core Workflow
The agent MUST execute these phases in order. Skipping phases produces broken loops.
Phase 0 - Brainstorm (optional but recommended)
Run when the user is unsure what loop to build or wants to discover opportunities.
See frameworks/brainstorm-framework.md and prompts/brainstorm-prompt.md.
Outputs: 3 to 7 candidate loop ideas scored by value, feasibility, and risk.
Phase 1 - Frame
Produce a one-sentence loop statement:
Whenever [TRIGGER], the agent will [EXECUTION], then verify [CONDITION], stopping when [STOP].
If you cannot write this sentence, you do not have a loop yet. Go back to Phase 0.
Phase 2 - Design
Fill the spec template at templates/loop-spec.md. Required fields:
- trigger type and event
- execution steps (atomic, ordered)
- verification gate and pass criteria
- retry policy (max attempts, backoff)
- stop conditions (success, failure, budget exhausted, human interrupt)
- cost ceiling (max tokens, max USD, max wall clock)
- failure mode (notify, log, open issue, revert)
Phase 3 - Score
Use the scoring rubric in frameworks/loop-scoring.md. Five dimensions, 1 to 5 each:
- Value
- Verifiability
- Cost efficiency
- Failure safety
- Reusability
Minimum to ship: total >= 15 AND Verifiability >= 4 AND Failure safety >= 3.
Phase 4 - Build
Implement the loop in the host format the user needs:
- Claude Code custom command
- Cursor rule with file watcher
- Windsurf rule
- GitHub Action
- Git hook
- Standalone script
- MCP tool
See configs/ for ready-to-use templates per host.
Phase 5 - Verify
Run the loop on a fixture input. Confirm:
- It triggers correctly.
- It executes the intended steps.
- It stops on the verification condition, not before, not after.
- It honors the cost ceiling.
- It fails safe on a malformed input.
Phase 6 - Ship
Produce a loop README using templates/loop-README.md. Tag a version. Commit.
Phase 7 - Reflect
After the first real run, answer the four reflection questions in frameworks/loop-scoring.md. Update the spec. Bump version.
5. Brainstorm Mode
Loop Factory ships with a brainstorm mode that runs before Phase 1.
Purpose: surface loop opportunities the user did not think to ask for.
How to invoke:
- User says "brainstorm loops" or "find loops in my repo".
- User says "I want to automate something but I don't know what".
- Agent detects repeated manual tasks and offers to brainstorm.
Brainstorm outputs follow templates/brainstorm-output.md:
Candidate Loop: <name>
Trigger: <event>
Execution: <one line>
Verification: <gate>
Value: <who benefits and by how much>
Cost estimate: <tokens/run, runs/week>
Risk if it breaks: <low/med/high>
Feasibility: <easy/medium/hard>
Why now: <signal>
The agent generates 3 to 7 candidates, scores each, and recommends the top 2.
Full method in frameworks/brainstorm-framework.md.
6. Loop Anatomy Reference
| Component | Question it answers | Examples |
|---|
| Trigger | When does this run? | save, commit, schedule, webhook, manual |
| Execution | What does the agent do? | edit files, run command, call API, generate text |
| Verification | How do we know it worked? | tests pass, lint clean, diff non-empty, human approve |
| Retry policy | What if it fails once? | retry up to N times with backoff |
| Stop conditions | When does it end? | success, max retries, budget exhausted, manual abort |
| Cost ceiling | How much can it spend? | max tokens, max USD, max wall clock |
| Failure mode | What happens on give-up? | notify, log, open issue, revert changes |
| Observability | How do we watch it? | logs, metrics, dashboard |
7. Design Principles
- Verification before execution planning. Decide how you will know it worked before you decide what to do.
- Small loops compose. Prefer three small loops chained over one giant loop.
- Failure is the default. Design the failure path first, the success path second.
- Cost is a first-class constraint. Every loop has a budget. Budget exceeded = loop stops.
- Idempotency. Running the loop twice should not break things.
- Human interrupt. Every long-running loop must have a clean abort path.
- No silent retries. Every retry must be logged with the failure reason.
- No infinite loops. Hard cap on iterations regardless of logic.
8. Six-Step Build Process
- Write the one-sentence loop statement.
- List the verification gate (must come before execution detail).
- Decompose execution into atomic ordered steps.
- Define retry policy, stop conditions, cost ceiling, failure mode.
- Pick the host format from
configs/.
- Run Phase 5 Verify on a fixture.
9. Loop Chaining
Loops can chain: output of loop A is the trigger for loop B.
Patterns:
- Pipeline - A then B then C, each verifies its own output.
- Fan-out - A triggers B and C in parallel, D waits for both.
- Feedback - A output feeds B, B output feeds back to A.
- Escalation - A runs cheap model, on uncertainty escalates to B with stronger model.
When chaining, each loop keeps its own verification. A chain is only as trustworthy as its weakest verification gate.
10. Common Mistakes
- Skipping verification, trusting the model to self-check.
- No cost ceiling, leading to runaway spend.
- Retry without backoff, hammering rate limits.
- Mixing concerns (one loop that lints, tests, deploys, and notifies).
- Hardcoding paths or secrets inside the loop body.
- No idempotency, so a retry double-applies a change.
- No reflection step, so the same failure repeats forever.
- Triggering on every keystroke instead of debounce.
11. Cost Management
Every loop spec must include a cost ceiling. Default ceilings:
| Loop type | Default token cap | Default USD cap |
|---|
| Lint fix | 5k tokens | $0.05 |
| Test fix | 20k tokens | $0.20 |
| Refactor | 50k tokens | $0.50 |
| Doc gen | 15k tokens | $0.15 |
| Review | 30k tokens | $0.30 |
| Brainstorm | 10k tokens | $0.10 |
When ceiling is hit, the loop stops, logs the partial result, and emits a BUDGET_EXHAUSTED event. Never silently exceed budget.
12. Safety Boundaries
Loop Factory must NOT be used to build loops that:
- Operate on production data without a staging path.
- Modify files outside the declared workspace scope.
- Make irreversible changes (force push, drop database, delete backups) without an explicit human approval step.
- Call paid APIs without a declared cost ceiling.
- Run forever without an iteration cap.
- Self-modify their own verification gate.
If a user requests any of the above, refuse that part of the design and propose a safer alternative with a human-in-the-loop checkpoint.
13. Output Contract
When the user asks Loop Factory to design a loop, the agent MUST return:
1. One-sentence loop statement
2. Trigger
3. Execution steps (atomic, ordered)
4. Verification gate
5. Retry policy
6. Stop conditions
7. Cost ceiling
8. Failure mode
9. Score (5 dimensions)
10. Host format recommendation
11. Risk notes
When the user asks for the brainstorm mode, the agent MUST return:
1. 3 to 7 candidate loop ideas in the brainstorm-output format
2. Scored table
3. Top 2 recommendations with reasoning
4. Next step prompt for the user to pick one
14. Multi-Agent Compatibility
Loop Factory is host-agnostic. The same loop spec can compile to:
- Claude Code custom slash command (
.claude/commands/)
- Cursor rule (
.cursorrules or .cursor/rules/)
- Windsurf rule (
.windsurfrules or .codeium/rules/)
- GitHub Copilot instructions (
.github/copilot-instructions.md)
- Codex plugin (
.codex-plugin/)
- Grok plugin (
.grok-plugin/)
- Gemini extension (
gemini-extension.json)
- GitHub Action (
.github/workflows/)
- Git hook (
.git/hooks/ or via husky/pre-commit)
- Standalone script (Python, Node, Bash, Rust)
Ready-to-use host configs are in configs/. Plugin manifests are in .claude-plugin/, .codex-plugin/, .grok-plugin/.
15. Agent Invocation
Standard call:
Use loop-factory.
Read SKILL.md, then design a loop for this task:
<describe task>
Output the full 11-field loop contract.
Brainstorm call:
Use loop-factory.
Run brainstorm mode on this repo / problem:
<describe context>
Output 3 to 7 candidates, scored, with top 2 recommendations.
Full protocol continues in frameworks/ and playbooks/. See AGENTS.md for the canonical agent instruction set.
