Skip to content

README.md

Latest commit

 

History

History
105 lines (72 loc) · 4.19 KB

README.md

File metadata and controls

105 lines (72 loc) · 4.19 KB
Raw

loopify

License: MIT Platform: Claude Code & Codex FX Studio AI

Deterministic compiler and runner for governed agent loops with explicit contracts and mechanical validation.

🌟 The Core Concept

Prompt Engineering: You write, read, and write again.
Looping Engineering: You design a SYSTEM — a fixed ritual reread on every turn, external checklist memory, and test suites as counter-pressure — allowing the AI agent to iterate autonomously until all acceptance criteria pass.

loopify compiles natural language requirements into governed, bounded autonomous loop packages for Claude Code and OpenAI Codex CLI, enforcing code-level constraints that prevent hallucination and task drift.

🚀 Usage

/loopify <raw prompt>                     # Generate autonomous loop package
/loopify <prompt> --runner codex          # codex | claude | both
/loopify <prompt> --dir loops/my-task     # Target directory
/loopify help                             # Interactive quickstart guide

Or in natural language: "turn this feature into an autonomous loop", "run overnight refactor".

📦 Generated Artifacts

Artifact Role
PROMPT.md Fixed ritual reread on every loop turn: 1 task per turn, investigate before assuming, no placeholders, selective commits, halt on LOOP_DONE.
LOOP_PLAN.md External memory: verified facts + checkbox task breakdown with mechanical acceptance criteria (command → expected output) + HUMAN-GATE checkpoints.
RUN.md Supervised manual execution instructions, monitoring, and emergency brakes.
loop_spec.json Machine-verifiable spec that generated the loop package.

🔄 Execution Lifecycle

flowchart TD
    Prompt([User Prompt]) --> Init[/loopify Command/]
    Init --> Decompose[Context & Test Suite Analysis]
    Decompose --> Spec[Deterministic Spec Generation]
    Spec --> Approve{Human Approval}
    
    Approve -- Yes --> Guard[Run loop_guard Supervisor]
    
    subgraph Autonomous Iteration Loop
        Guard --> Turn[Turn N: Execute Exactly 1 Task]
        Turn --> Test[Run Tests & Verify Working Tree]
        Test --> Check{Test Passed?}
        Check -- Yes --> Commit[Selective Git Commit]
        Check -- No --> Reset[Hard Reset to Previous Turn]
        Commit --> Next{Tasks Remaining?}
        Next -- Yes --> Turn
        Next -- No --> Done[Generate LOOP_DONE.md]
    end
    
    Done --> Final[Human Code Review & Merge]
Loading

🛡️ The 4 Deterministic Guard Layers

  1. Generator (scripts/loopify_gen.py): The LLM only fills loop_spec.json; ritual bytes and prohibition rules are deterministically generated from code. Tasks without mechanical acceptance criteria are rejected.
  2. Validator (scripts/loopify_validate.py): Inspects the package, verification markers, and rejects any forbidden flags (e.g., --dangerously-skip-permissions).
  3. Stop Hook (scripts/loopify_stop_hook.py): Runs outside the model after each response. Detects manual tampering or SHA-256 drift and locks the state until re-validation.
  4. Loop Guard (scripts/loop_guard.py): Enforces runtime invariants. Dispatches turns and verifies: exactly +1 checked task (or +1 BLOCKED), green test suite, and clean working tree. Violations trigger an immediate git reset --hard to the prior turn.

📦 Installation & Setup

Prerequisites

  • Python >= 3.10
  • Git
  • Claude Code or OpenAI Codex CLI

Local Setup

# Clone the repository
git clone https://github.com/fernandoxavier02/loopify.git
cd loopify; .\install.ps1

The installer registers the skill in ~/.claude/skills/loopify and configures the Stop Hook in ~/.claude/settings.json.

📄 License

MIT License — Copyright (c) 2026 Fernando Xavier — FX Studio AI.