roman-ryzenadvanced/loop-factory

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:

1. Trigger - the event that starts execution (file save, git hook, schedule, manual run, web hook, watcher).
2. Execution - the work the agent does (edit code, run tests, regenerate docs, review PR).
3. 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

1. Verification before execution planning. Decide how you will know it worked before you decide what to do.
2. Small loops compose. Prefer three small loops chained over one giant loop.
3. Failure is the default. Design the failure path first, the success path second.
4. Cost is a first-class constraint. Every loop has a budget. Budget exceeded = loop stops.
5. Idempotency. Running the loop twice should not break things.
6. Human interrupt. Every long-running loop must have a clean abort path.
7. No silent retries. Every retry must be logged with the failure reason.
8. No infinite loops. Hard cap on iterations regardless of logic.

8. Six-Step Build Process

1. Write the one-sentence loop statement.
2. List the verification gate (must come before execution detail).
3. Decompose execution into atomic ordered steps.
4. Define retry policy, stop conditions, cost ceiling, failure mode.
5. Pick the host format from configs/.
6. 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.