hermes-loop-plugin 1.0.0__py3-none-any.whl

hermes_loop_plugin/__init__.py

@@ -0,0 +1,290 @@
+"""Hermes Loop plugin — registration.
+
+Provides continuous task execution loop with state persistence and completion promises.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from . import commands, schemas, tools
+
+logger = logging.getLogger(__name__)
+
+
+def _on_post_tool_call(tool_name: str, args: dict, result: str, task_id: str, **kwargs):
+    """Hook: runs after every tool call to check loop continuation."""
+    
+    # Only process if this is a loop-related tool or we're in a loop session
+    loop_tools = ['loop_status', 'set_completion_promise', 'init_loop', 
+                  'complete_task', 'add_blocking_issue', 'reset_loop']
+    
+    if not any(t in tool_name for t in loop_tools):
+        return
+    
+    cwd = kwargs.get('cwd', str(Path.cwd()))
+    state_file_path = Path(cwd) / '.hermes-loop-state.json'
+    
+    # Check if we have an active state file
+    if not state_file_path.exists():
+        return
+    
+    try:
+        with open(state_file_path) as f:
+            state = json.load(f)
+        
+        total_tasks = state.get('total_tasks', 0)
+        completed_tasks = state.get('completed_tasks', 0)
+        blocking_issues = state.get('blocking_issues', [])
+        
+        # If all tasks complete, signal loop end
+        if completed_tasks >= total_tasks and not blocking_issues:
+            logger.info(f"[hermes-loop] All {total_tasks} tasks completed at session {task_id}")
+            
+            # Add completion marker to transcript for detection by stop hook
+            transcript_path = kwargs.get('transcript_path')
+            if transcript_path:
+                try:
+                    with open(transcript_path, 'a') as f:
+                        f.write(f"\n# [HERMES-LOOP] ALL_TASKS_COMPLETE at {task_id}\n")
+                except Exception as e:
+                    logger.error(f"Failed to write completion marker: {e}")
+                    
+    except Exception as e:
+        logger.error(f"[hermes-loop] Error in post_tool_call hook: {e}")
+
+
+def _on_session_start(session_id: str, platform: str, **kwargs):
+    """Hook: runs when a new session starts."""
+    
+    cwd = kwargs.get('cwd', str(Path.cwd()))
+    state_file_path = Path(cwd) / '.hermes-loop-state.json'
+    
+    if not state_file_path.exists():
+        return
+    
+    try:
+        with open(state_file_path) as f:
+            state = json.load(f)
+        
+        total_tasks = state.get('total_tasks', 0)
+        completed_tasks = state.get('completed_tasks', 0)
+        
+        if total_tasks > 0 and completed_tasks < total_tasks:
+            logger.info(
+                f"[hermes-loop] Resuming loop from session {session_id}: "
+                f"{completed_tasks}/{total_tasks} tasks complete"
+            )
+            
+    except Exception as e:
+        logger.error(f"[hermes-loop] Error in on_session_start hook: {e}")
+
+
+def _on_stop_hook(input_data: dict, **kwargs) -> int:
+    """Hook: determines if loop should continue or stop.
+    
+    Returns 0 to continue, non-zero to stop.
+    This is the main loop controller."""
+    
+    cwd = input_data.get('cwd', str(Path.cwd()))
+    transcript_path = input_data.get('transcript_path')
+    
+    state_file_path = Path(cwd) / '.hermes-loop-state.json'
+    
+    # If no state file, nothing to continue
+    if not state_file_path.exists():
+        return 0
+    
+    try:
+        with open(state_file_path) as f:
+            state = json.load(f)
+        
+        total_tasks = state.get('total_tasks', 0)
+        completed_tasks = state.get('completed_tasks', 0)
+        blocking_issues = state.get('blocking_issues', [])
+        completion_promise = state.get('completion_promise')
+        
+        # Check for explicit ALL_TASKS_COMPLETE in transcript (backup detection)
+        if transcript_path and Path(transcript_path).exists():
+            with open(transcript_path) as f:
+                content = f.read()
+                if 'ALL_TASKS_COMPLETE' in content:
+                    logger.info("[hermes-loop] Detected ALL_TASKS_COMPLETE marker")
+                    return 1  # Stop
+        
+        # Check blocking issues first
+        if blocking_issues:
+            logger.warning(
+                f"[hermes-loop] Blocking issues detected, stopping loop: {blocking_issues}"
+            )
+            return 1
+        
+        # Check completion promise
+        if completion_promise and not completion_promise.get('fulfilled', False):
+            promise_type = completion_promise.get('promise_type', '')
+            condition = completion_promise.get('condition', '')
+            
+            # Evaluate the promise condition
+            promise_fulfilled = False
+            
+            if promise_type == 'task_count':
+                expected = int(completion_promise.get('expected_value', 0))
+                promise_fulfilled = completed_tasks >= expected
+                
+            elif promise_type == 'file_exists':
+                check_path = Path(cwd) / condition
+                promise_fulfilled = check_path.exists()
+                
+            elif promise_type == 'content_match':
+                check_path = Path(cwd) / condition
+                if check_path.exists():
+                    content = check_path.read_text()
+                    pattern = completion_promise.get('expected_value', '')
+                    promise_fulfilled = pattern in content
+            
+            # Update fulfilled status
+            if promise_fulfilled:
+                completion_promise['fulfilled'] = True
+                with open(state_file_path, 'w') as f:
+                    json.dump(state, f, indent=2)
+            
+            if not promise_fulfilled:
+                logger.info(
+                    f"[hermes-loop] Completion promise not yet fulfilled "
+                    f"({promise_type}: {condition}), continuing loop"
+                )
+                return 0
+        
+        # Check if all tasks complete
+        if completed_tasks >= total_tasks:
+            logger.info(f"[hermes-loop] All {total_tasks} tasks completed, stopping loop")
+            return 1
+        
+        # Continue the loop
+        logger.debug(
+            f"[hermes-loop] Continuing loop: {completed_tasks}/{total_tasks} tasks complete"
+        )
+        
+    except Exception as e:
+        logger.error(f"[hermes-loop] Error in stop hook: {e}")
+    
+    return 0  # Default to continue on error
+
+
+def register(ctx):
+    """Register tools and hooks with Hermes Agent."""
+    
+    # Core loop status tool
+    ctx.register_tool(
+        name="loop_status",
+        toolset="hermes-loop",
+        schema=schemas.LOOP_STATUS,
+        handler=tools.loop_status
+    )
+    
+    # Completion promise tool
+    ctx.register_tool(
+        name="set_completion_promise",
+        toolset="hermes-loop",
+        schema=schemas.COMPLETE_PROMISE,
+        handler=tools.set_completion_promise
+    )
+    
+    # Command-style tools for easier usage
+    ctx.register_tool(
+        name="init_loop",
+        toolset="hermes-loop",
+        schema={
+            "name": "init_loop",
+            "description": (
+                "Initialize a new loop state. Creates the state file and sets up task tracking."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "total_tasks": {
+                        "type": "integer",
+                        "description": "Total number of tasks in the loop"
+                    },
+                    "promise_type": {
+                        "type": "string", 
+                        "description": "Optional completion promise type (task_count, file_exists, content_match)"
+                    },
+                    "condition": {
+                        "type": "string",
+                        "description": "Path/pattern for the promise"
+                    },
+                    "expected_value": {
+                        "type": "string",
+                        "description": "Expected value for content_match promises"
+                    }
+                },
+                "required": ["total_tasks"]
+            }
+        },
+        handler=tools.init_loop
+    )
+    
+    # Command-style tools (aliases for easier usage)
+    ctx.register_tool(
+        name="complete_task",
+        toolset="hermes-loop", 
+        schema={
+            "name": "complete_task",
+            "description": (
+                "Mark next task as completed. Increments the completed tasks counter."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+        },
+        handler=tools.complete_task
+    )
+    
+    ctx.register_tool(
+        name="add_blocking_issue",
+        toolset="hermes-loop",
+        schema={
+            "name": "add_blocking_issue", 
+            "description": (
+                "Add a blocking issue. When issues block progress, the loop will stop automatically."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "issue": {
+                        "type": "string",
+                        "description": "Description of the blocking issue"
+                    }
+                },
+                "required": ["issue"]
+            }
+        },
+        handler=tools.add_blocking_issue
+    )
+    
+    ctx.register_tool(
+        name="reset_loop",
+        toolset="hermes-loop",
+        schema={
+            "name": "reset_loop",
+            "description": (
+                "Reset loop state. Clears completed task count but keeps total tasks and promise."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+        },
+        handler=tools.reset_loop
+    )
+    
+    # Register hooks for loop continuation control
+    ctx.register_hook("post_tool_call", _on_post_tool_call)
+    ctx.register_hook("on_session_start", _on_session_start)
+    ctx.register_hook("stop_hook", _on_stop_hook)
+    
+    logger.info("[hermes-loop] Plugin registered with 6 tools and 3 hooks")

hermes_loop_plugin/commands.py

@@ -0,0 +1,328 @@
+"""Command-style wrappers for hermes-loop tools.
+
+These provide more intuitive, slash-command-like interfaces to the loop functionality."""
+
+import json
+from pathlib import Path
+
+
+class LoopCommands:
+    """Convenience class providing command-style access to loop operations."""
+    
+    def __init__(self):
+        self.state_file = Path.cwd() / '.hermes-loop-state.json'
+    
+    def init_loop(self, total_tasks: int, promise_type: str = None, 
+                  condition: str = None, expected_value: str = None) -> dict:
+        """Initialize a new loop state.
+        
+        Args:
+            total_tasks: Total number of tasks in the loop
+            promise_type: Optional completion promise type (task_count, file_exists, content_match)
+            condition: Path/pattern for the promise
+            expected_value: Expected value for content_match promises
+            
+        Returns:
+            dict with initialization status
+        """
+        state = {
+            "total_tasks": total_tasks,
+            "completed_tasks": 0,
+            "blocking_issues": [],
+            "created_at": None
+        }
+        
+        if promise_type:
+            state["completion_promise"] = {
+                "promise_type": promise_type,
+                "condition": condition,
+                "expected_value": expected_value,
+                "fulfilled": False
+            }
+        else:
+            state["completion_promise"] = None
+        
+        with open(self.state_file, 'w') as f:
+            json.dump(state, f, indent=2)
+        
+        return {
+            "success": True,
+            "message": f"Loop initialized with {total_tasks} tasks",
+            "state_file": str(self.state_file),
+            "promise_set": bool(promise_type)
+        }
+    
+    def complete_task(self) -> dict:
+        """Mark one task as completed.
+        
+        Returns:
+            dict with updated state
+        """
+        if not self.state_file.exists():
+            return {
+                "success": False,
+                "error": "No active loop state found"
+            }
+        
+        try:
+            with open(self.state_file) as f:
+                state = json.load(f)
+            
+            old_count = state['completed_tasks']
+            state['completed_tasks'] += 1
+            
+            # Track completion history if this is the first task
+            if state['completed_tasks'] == 1 and 'completion_history' not in state:
+                state['completion_history'] = []
+            
+            if 'completion_history' in state:
+                from datetime import datetime
+                state['completion_history'].append({
+                    "task_index": state['completed_tasks'],
+                    "timestamp": datetime.now().isoformat()
+                })
+            
+            with open(self.state_file, 'w') as f:
+                json.dump(state, f, indent=2)
+            
+            return {
+                "success": True,
+                "previous_count": old_count,
+                "new_count": state['completed_tasks'],
+                "total_tasks": state['total_tasks'],
+                "remaining": state['total_tasks'] - state['completed_tasks']
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e)
+            }
+    
+    def set_promise(self, promise_type: str, condition: str = None, 
+                    expected_value: str = None) -> dict:
+        """Set or update the completion promise.
+        
+        Args:
+            promise_type: Type of promise (task_count, file_exists, content_match)
+            condition: Path/pattern for the promise
+            expected_value: Expected value for content_match promises
+            
+        Returns:
+            dict with promise status
+        """
+        if not self.state_file.exists():
+            return {
+                "success": False,
+                "error": "No active loop state found"
+            }
+        
+        try:
+            with open(self.state_file) as f:
+                state = json.load(f)
+            
+            promise = {
+                "promise_type": promise_type,
+                "condition": condition,
+                "expected_value": expected_value,
+                "fulfilled": False
+            }
+            
+            state['completion_promise'] = promise
+            
+            with open(self.state_file, 'w') as f:
+                json.dump(state, f, indent=2)
+            
+            return {
+                "success": True,
+                "promise_type": promise_type,
+                "message": f"Promise set via {promise_type}"
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e)
+            }
+    
+    def add_blocking_issue(self, issue: str) -> dict:
+        """Add a blocking issue that will stop the loop.
+        
+        Args:
+            issue: Description of the blocking issue
+            
+        Returns:
+            dict with update status
+        """
+        if not self.state_file.exists():
+            return {
+                "success": False,
+                "error": "No active loop state found"
+            }
+        
+        try:
+            with open(self.state_file) as f:
+                state = json.load(f)
+            
+            if issue not in state['blocking_issues']:
+                state['blocking_issues'].append(issue)
+                
+                # Add timestamp for tracking
+                if 'issues' not in state:
+                    from datetime import datetime
+                    state['issues'] = []
+                state['issues'].append({
+                    "issue": issue,
+                    "timestamp": datetime.now().isoformat()
+                })
+            
+            with open(self.state_file, 'w') as f:
+                json.dump(state, f, indent=2)
+            
+            return {
+                "success": True,
+                "message": f"Blocking issue added: '{issue}'",
+                "total_issues": len(state['blocking_issues'])
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e)
+            }
+    
+    def status(self) -> dict:
+        """Get current loop status.
+        
+        Returns:
+            dict with full status information
+        """
+        if not self.state_file.exists():
+            return {
+                "active": False,
+                "message": "No active loop state found"
+            }
+        
+        try:
+            with open(self.state_file) as f:
+                state = json.load(f)
+            
+            total = state.get('total_tasks', 0)
+            completed = state.get('completed_tasks', 0)
+            blocking = state.get('blocking_issues', [])
+            promise = state.get('completion_promise')
+            
+            # Check if promise is fulfilled
+            promise_fulfilled = False
+            if promise:
+                promise_type = promise.get('promise_type', '')
+                
+                if promise_type == 'task_count':
+                    expected = int(promise.get('expected_value', 0))
+                    promise_fulfilled = completed >= expected
+                    
+                elif promise_type == 'file_exists':
+                    check_path = Path.cwd() / promise.get('condition', '')
+                    promise_fulfilled = check_path.exists()
+                    
+                elif promise_type == 'content_match':
+                    check_path = Path.cwd() / promise.get('condition', '')
+                    if check_path.exists():
+                        content = check_path.read_text()
+                        pattern = promise.get('expected_value', '')
+                        promise_fulfilled = pattern in content
+            
+            has_remaining = completed < total and not promise_fulfilled
+            
+            return {
+                "active": True,
+                "has_remaining_tasks": has_remaining,
+                "tasks_completed": completed,
+                "total_tasks": total,
+                "remaining_tasks": total - completed,
+                "completion_reached": (not has_remaining) or promise_fulfilled,
+                "blocking_issues": blocking,
+                "promise_status": {
+                    "has_promise": bool(promise),
+                    "type": promise.get('promise_type') if promise else None,
+                    "fulfilled": promise_fulfilled and promise  # Only mark fulfilled if not already done
+                } if promise else None
+            }
+        except Exception as e:
+            return {
+                "active": False,
+                "error": str(e)
+            }
+    
+    def reset(self) -> dict:
+        """Reset the loop state (clears completed tasks but keeps total).
+        
+        Returns:
+            dict with reset status
+        """
+        if not self.state_file.exists():
+            return {
+                "success": False,
+                "error": "No active loop state found"
+            }
+        
+        try:
+            with open(self.state_file) as f:
+                state = json.load(f)
+            
+            old_completed = state['completed_tasks']
+            state['completed_tasks'] = 0
+            
+            # Clear completion history on reset
+            if 'completion_history' in state:
+                del state['completion_history']
+            
+            with open(self.state_file, 'w') as f:
+                json.dump(state, f, indent=2)
+            
+            return {
+                "success": True,
+                "message": f"Loop reset - cleared {old_completed} completed tasks",
+                "total_tasks": state['total_tasks']
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e)
+            }
+
+
+# Convenience functions for tool handlers to use
+
+def init_loop_command(total_tasks: int, promise_type: str = None, 
+                      condition: str = None, expected_value: str = None) -> str:
+    """Command-style loop initialization."""
+    cmds = LoopCommands()
+    result = cmds.init_loop(total_tasks, promise_type, condition, expected_value)
+    return json.dumps(result)
+
+
+def complete_task_command() -> str:
+    """Mark next task as completed."""
+    cmds = LoopCommands()
+    result = cmds.complete_task()
+    return json.dumps(result)
+
+
+def set_promise_command(promise_type: str, condition: str = None, 
+                        expected_value: str = None) -> str:
+    """Set completion promise."""
+    cmds = LoopCommands()
+    result = cmds.set_promise(promise_type, condition, expected_value)
+    return json.dumps(result)
+
+
+def add_blocking_issue_command(issue: str) -> str:
+    """Add a blocking issue."""
+    cmds = LoopCommands()
+    result = cmds.add_blocking_issue(issue)
+    return json.dumps(result)
+
+
+def loop_status_command() -> str:
+    """Get current loop status."""
+    cmds = LoopCommands()
+    result = cmds.status()
+    return json.dumps(result, indent=2)

hermes_loop_plugin/schemas.py

@@ -0,0 +1,43 @@
+"""Tool schemas — what the LLM sees for the hermes-loop plugin."""
+
+LOOP_STATUS = {
+    "name": "loop_status",
+    "description": (
+        "Check the current status of the task execution loop. "
+        "Returns whether tasks remain, if completion is reached, and any blocking issues. "
+        "Use this when you need to understand the loop state or debug continuation logic."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": []
+    }
+}
+
+COMPLETE_PROMISE = {
+    "name": "set_completion_promise",
+    "description": (
+        "Set a completion promise that defines when the loop should stop. "
+        "Use this to specify custom termination conditions beyond automatic task detection. "
+        "The loop will continue until either all tasks complete OR this promise is fulfilled."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "promise_type": {
+                "type": "string",
+                "description": "Type of completion condition: 'task_count', 'file_exists', 'content_match', or 'custom'",
+                "enum": ["task_count", "file_exists", "content_match", "custom"]
+            },
+            "condition": {
+                "type": "string",
+                "description": "The specific condition to check (e.g., file path, content pattern, task index)"
+            },
+            "expected_value": {
+                "type": "string",
+                "description": "Expected value for the condition (optional)"
+            }
+        },
+        "required": ["promise_type", "condition"]
+    }
+}

hermes_loop_plugin/tools.py

@@ -0,0 +1,126 @@
+"""Tool handlers for hermes-loop plugin.
+
+These provide both direct JSON responses and command-style interfaces."""
+
+import json
+from pathlib import Path
+
+
+def loop_status(args: dict, **kwargs) -> str:
+    """Check current loop status (alias for /loop_status).
+    
+    Returns detailed status including completion progress and promise state.
+    """
+    from .commands import LoopCommands
+    
+    cmds = LoopCommands()
+    result = cmds.status()
+    return json.dumps(result, indent=2)
+
+
+def set_completion_promise(args: dict, **kwargs) -> str:
+    """Set completion promise (alias for /set_promise).
+    
+    Defines custom termination conditions for the loop.
+    """
+    from .commands import LoopCommands
+    
+    cmds = LoopCommands()
+    result = cmds.set_promise(
+        promise_type=args.get('promise_type'),
+        condition=args.get('condition'),
+        expected_value=args.get('expected_value')
+    )
+    return json.dumps(result)
+
+
+def init_loop(args: dict, **kwargs) -> str:
+    """Initialize a new loop state (alias for /init_loop).
+    
+    Creates the state file and sets up task tracking.
+    
+    Args:
+        total_tasks: Total number of tasks in the loop
+        promise_type: Optional completion promise type
+        condition: Path/pattern for the promise
+        expected_value: Expected value for content_match promises
+    """
+    from .commands import LoopCommands
+    
+    cmds = LoopCommands()
+    result = cmds.init_loop(
+        total_tasks=args.get('total_tasks', 0),
+        promise_type=args.get('promise_type'),
+        condition=args.get('condition'),
+        expected_value=args.get('expected_value')
+    )
+    return json.dumps(result)
+
+
+def complete_task(args: dict, **kwargs) -> str:
+    """Complete next task (alias for /complete_task).
+    
+    Increments the completed tasks counter.
+    Use this after each subagent or implementation step.
+    """
+    from .commands import LoopCommands
+    
+    cmds = LoopCommands()
+    result = cmds.complete_task()
+    return json.dumps(result)
+
+
+def add_blocking_issue(args: dict, **kwargs) -> str:
+    """Add a blocking issue (alias for /add_blocking_issue).
+    
+    When issues block progress, the loop will stop automatically.
+    Use this when you hit an error that requires manual intervention.
+    
+    Args:
+        issue: Description of the blocking issue
+    """
+    from .commands import LoopCommands
+    
+    cmds = LoopCommands()
+    result = cmds.add_blocking_issue(args.get('issue', ''))
+    return json.dumps(result)
+
+
+def reset_loop(args: dict, **kwargs) -> str:
+    """Reset loop state (alias for /reset_loop).
+    
+    Clears completed task count but keeps total tasks and promise.
+    Use this to restart iteration from the beginning.
+    """
+    from .commands import LoopCommands
+    
+    cmds = LoopCommands()
+    result = cmds.reset()
+    return json.dumps(result)
+
+
+# Command-style aliases for more intuitive usage
+
+def command_init_loop(args: dict, **kwargs) -> str:
+    """Command-style loop initialization."""
+    return init_loop(args, **kwargs)
+
+
+def command_complete_task(args: dict, **kwargs) -> str:
+    """Mark next task as completed."""
+    return complete_task(args, **kwargs)
+
+
+def command_set_promise(args: dict, **kwargs) -> str:
+    """Set completion promise."""
+    return set_completion_promise(args, **kwargs)
+
+
+def command_add_blocking_issue(args: dict, **kwargs) -> str:
+    """Add a blocking issue."""
+    return add_blocking_issue(args, **kwargs)
+
+
+def command_loop_status(args: dict, **kwargs) -> str:
+    """Get current loop status."""
+    return loop_status(args, **kwargs)

hermes_loop_plugin-1.0.0.dist-info/METADATA

@@ -0,0 +1,471 @@
+Metadata-Version: 2.4
+Name: hermes-loop-plugin
+Version: 1.0.0
+Summary: Continuous task execution loop plugin for Hermes Agent
+Author-email: Hermes Agent Community <community@hermes-agent.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/NousResearch/hermes-loop-plugin
+Project-URL: Documentation, https://github.com/NousResearch/hermes-loop-plugin#readme
+Project-URL: Repository, https://github.com/NousResearch/hermes-loop-plugin.git
+Project-URL: Issues, https://github.com/NousResearch/hermes-loop-plugin/issues
+Keywords: hermes-agent,plugin,loop,iteration,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Hermes Loop Plugin
+
+Continuous task execution loop that keeps the agent running until goals are completed via state file monitoring and optional completion promises.
+
+## Overview
+
+This plugin enables **persistent multi-step workflows** where tasks span multiple sessions or require iterative refinement. It works similarly to Claude Code's ralph-wiggum-loop but is designed specifically for Hermes Agent's plugin architecture.
+
+## Features
+
+- **State Persistence**: Tracks task progress via `.hermes-loop-state.json`
+- **Completion Promises**: Define custom termination conditions (file exists, content match, task count)
+- **Automatic Resumption**: Continues from where it left off across sessions
+- **Blocking Detection**: Stops loop when critical issues prevent progress
+- **Command-style Tools**: Intuitive tool names that work like slash commands!
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `init_loop` | Initialize a new loop state |
+| `loop_status` | Check current loop status |
+| `complete_task` | Mark next task as completed |
+| `set_completion_promise` | Define custom termination condition |
+| `add_blocking_issue` | Add blocker that stops loop |
+| `reset_loop` | Reset completed count |
+
+## Installation
+
+### From GitHub (Current) 🚀
+
+The plugin is available for direct installation from our GitHub repository:
+
+```bash
+pip install git+https://github.com/AshMartian/hermes-loop-plugin.git@v1.0.0
+```
+
+After installation, the plugin will be automatically discovered when you start Hermes Agent. No additional configuration required!
+
+### Verify Installation
+
+Check that the plugin is installed correctly:
+
+```bash
+# Check if package is installed
+pip show hermes-loop-plugin
+
+# Or verify plugin location (if using local development)
+ls ~/.hermes/plugins/hermes-loop/
+```
+
+You should see:
+- `plugin.yaml` - Plugin manifest
+- `__init__.py` - Registration and hooks
+- `schemas.py` - Tool schemas (what LLM sees)
+- `tools.py` - Tool handlers (actual implementation)
+- `SKILL.md` - Comprehensive usage documentation
+
+### Local Development Installation
+
+For development or custom builds, install from source:
+
+```bash
+# Clone the repository
+git clone https://github.com/AshMartian/hermes-loop-plugin.git
+cd hermes-loop-plugin
+
+# Install in editable mode for development
+pip install -e .
+
+# Or build and install manually
+python -m build
+pip install dist/hermes_loop_plugin-*.whl
+```
+
+### Manual Installation (for advanced users)
+
+If you need to install the plugin manually:
+
+1. Download the package from [GitHub Releases](https://github.com/AshMartian/hermes-loop-plugin/releases) or clone the repository
+2. Install using pip: `pip install dist/hermes_loop_plugin-X.X.X.tar.gz`
+3. Restart Hermes Agent to load the plugin
+
+### 📦 PyPI Installation (Coming Soon!)
+
+The plugin will be available on [PyPI](https://pypi.org/) for easier installation:
+
+```bash
+# Coming soon!
+pip install hermes-loop-plugin
+```
+
+**Track progress:** Check our [GitHub Releases](https://github.com/AshMartian/hermes-loop-plugin/releases) for updates when we publish to PyPI.
+
+## Quick Start
+
+### 1. Initialize a loop state
+
+Create a `.hermes-loop-state.json` file in your working directory:
+
+```python
+from pathlib import Path
+import json
+
+state_file = Path.cwd() / '.hermes-loop-state.json'
+
+with open(state_file, 'w') as f:
+    json.dump({
+        "total_tasks": 5,
+        "completed_tasks": 0,
+        "blocking_issues": [],
+        "completion_promise": {
+            "promise_type": "file_exists",
+            "condition": "src/features/new-feature.tsx"
+        }
+    }, f)
+```
+
+### 2. Set completion promise (optional)
+
+Use the tool to define custom termination conditions:
+
+```python
+set_completion_promise(
+    promise_type="content_match",
+    condition="tests/feature.test.ts",
+    expected_value="describe('Feature'"
+)
+```
+
+### 3. Execute tasks
+
+Run your tasks via subagents or direct implementation, updating the state after each completion:
+
+```python
+from pathlib import Path
+
+# Task 1
+delegate_task(goal="Implement feature step 1")
+
+# Update state
+state_file = Path.cwd() / '.hermes-loop-state.json'
+with open(state_file) as f:
+    state = json.load(f)
+state['completed_tasks'] += 1
+with open(state_file, 'w') as f:
+    json.dump(state, f, indent=2)
+
+# Repeat for remaining tasks...
+```
+
+### 4. Loop continues automatically
+
+The plugin's stop hook monitors the state file and determines whether to continue or stop execution based on:
+- Task completion count vs total
+- Completion promise fulfillment status  
+- Blocking issues present
+
+## State File Format
+
+```json
+{
+  "total_tasks": 5,
+  "completed_tasks": 2,
+  "blocking_issues": [],
+  "completion_promise": {
+    "promise_type": "file_exists",
+    "condition": "src/features/new-feature.tsx",
+    "expected_value": null,
+    "fulfilled": false
+  },
+  "created_at": "2026-03-17T09:38:00Z"
+}
+```
+
+**Fields:**
+- `total_tasks`: Total number of tasks in the loop
+- `completed_tasks`: Number completed so far  
+- `blocking_issues`: List of issues that should stop the loop
+- `completion_promise`: Optional custom termination condition
+- `created_at`: Timestamp when loop started
+
+## Completion Promise Types
+
+### 1. Task Count
+
+Stop after completing a specific number of tasks:
+
+```json
+{
+  "promise_type": "task_count",
+  "condition": null,
+  "expected_value": "3"
+}
+```
+
+**Use case:** Continue until I've tried at least 3 debugging approaches
+
+### 2. File Exists
+
+Stop when a specific file is created:
+
+```json
+{
+  "promise_type": "file_exists",
+  "condition": "src/features/new-feature.tsx"
+}
+```
+
+**Use case:** Keep implementing until the feature file exists
+
+### 3. Content Match
+
+Stop when a file contains specific content:
+
+```json
+{
+  "promise_type": "content_match",
+  "condition": "src/utils/validation.ts",
+  "expected_value": "export function validateInput("
+}
+```
+
+**Use case:** Continue until validation logic is implemented
+
+### 4. Custom
+
+Define your own condition via tool implementation:
+
+```json
+{
+  "promise_type": "custom",
+  "condition": "my_custom_condition"
+}
+```
+
+**Use case:** Complex conditions requiring custom logic (extend the plugin)
+
+## Tools Provided
+
+### `loop_status`
+
+Check current loop state and whether continuation is needed.
+
+**Parameters:** None
+
+**Returns:** JSON with:
+- `has_remaining_tasks`: true if tasks remain
+- `tasks_completed`: number completed so far
+- `total_tasks`: total tasks in loop
+- `completion_reached`: true if all conditions met
+- `blocking_issues`: list of blocking issues (if any)
+
+### `set_completion_promise`
+
+Set custom termination condition for the loop.
+
+**Parameters:**
+- `promise_type`: Type of condition (`task_count`, `file_exists`, `content_match`, `custom`)
+- `condition`: Specific condition to check (e.g., file path, content pattern)
+- `expected_value`: Expected value for condition (optional)
+
+## Integration Patterns
+
+### With subagent-driven-development
+
+Use the loop to keep subagents running across sessions:
+
+```python
+# Initialize state
+state_file = Path.cwd() / '.hermes-loop-state.json'
+with open(state_file, 'w') as f:
+    json.dump({"total_tasks": 5, "completed_tasks": 0}, f)
+
+# Dispatch tasks via subagents (loop continues automatically)
+delegate_task(goal="Implement Task 1")
+mark_task_complete(state_file)
+
+delegate_task(goal="Implement Task 2")
+mark_task_complete(state_file)
+
+# Loop will continue until all 5 tasks complete
+```
+
+### With writing-plans
+
+Use loop for plans requiring iteration:
+
+```python
+plan = read_file("docs/plans/feature-plan.md")
+tasks = parse_plan_tasks(plan)
+
+state_file = Path.cwd() / '.hermes-loop-state.json'
+with open(state_file, 'w') as f:
+    json.dump({"total_tasks": len(tasks), "completed_tasks": 0}, f)
+
+# Execute tasks (loop continues automatically across sessions)
+```
+
+### With systematic-debugging
+
+Loop works seamlessly with debugging workflows:
+
+```python
+state_file = Path.cwd() / '.hermes-loop-state.json'
+with open(state_file, 'w') as f:
+    json.dump({
+        "total_tasks": 10,
+        "completed_tasks": 0,
+        "blocking_issues": [],
+        "completion_promise": {
+            "promise_type": "content_match",
+            "condition": "src/app.tsx",
+            "expected_value": "// Bug fixed"
+        }
+    }, f)
+
+# Follow systematic-debugging process:
+# 1. Identify symptoms
+# 2. Form hypothesis  
+# 3. Test hypothesis
+# 4. Update state if test fails
+# 5. Loop continues until bug fixed or max iterations
+```
+
+## Debugging
+
+### Check loop status
+
+```python
+status = loop_status()
+print(f"Remaining: {status['has_remaining_tasks']}")
+print(f"Completed: {status['tasks_completed']}/{status['total_tasks']}")
+```
+
+### Inspect state file directly
+
+```bash
+cat .hermes-loop-state.json
+```
+
+### Force stop the loop
+
+If loop is stuck, remove or rename the state file:
+
+```bash
+mv .hermes-loop-state.json .hermes-loop-state.json.backup
+# Loop will detect missing state and stop
+```
+
+## Extending the Plugin
+
+To add new promise types or customize behavior:
+
+1. **Update `schemas.py`** - Add new enum values to tool parameters
+2. **Modify `tools.py`** - Implement handler logic for new features  
+3. **Edit `__init__.py`** - Update `_on_stop_hook()` to evaluate new conditions
+
+Example: Add HTTP status promise type:
+
+```python
+# In __init__.py, add to _on_stop_hook:
+elif promise_type == 'http_status':
+    import requests
+    url = completion_promise.get('condition', '')
+    response = requests.get(url)
+    expected_status = int(completion_promise.get('expected_value', 200))
+    promise_fulfilled = (response.status_code == expected_status)
+```
+
+## Security Considerations
+
+### State file permissions
+
+Ensure state files are not world-readable if they contain sensitive data:
+
+```bash
+chmod 600 .hermes-loop-state.json
+```
+
+### Validate promise conditions
+
+Prevent path traversal attacks by validating promise conditions:
+
+```python
+def validate_promise_condition(condition: str) -> bool:
+    """Prevent path traversal attacks."""
+    if '..' in condition or condition.startswith('/'):
+        return False  # Reject absolute paths and path traversal
+    return True
+```
+
+## Comparison with Claude Code's ralph-wiggum-loop
+
+| Feature | Hermes Loop | Ralph Wiggum Loop |
+|---------|-------------|-------------------|
+| Platform | Hermes Agent | Claude Code |
+| State file format | JSON | JSON (similar) |
+| Promise types | 4 built-in (task_count, file_exists, content_match, custom) | Similar |
+| Hook integration | post_tool_call, on_session_start, stop_hook | Similar pattern |
+| Tool interface | Explicit tools (loop_status, set_completion_promise) | Implicit via commands |
+| Installation | ~/.hermes/plugins/ | .claude-plugin/ |
+
+The Hermes Loop plugin follows the same conceptual model as ralph-wiggum but is adapted for Hermes Agent's tool-based architecture.
+
+## License
+
+MIT License - see LICENSE file in repository root
+
+**Repository:** [https://github.com/AshMartian/hermes-loop-plugin](https://github.com/AshMartian/hermes-loop-plugin)
+
+## Contributing
+
+Contributions welcome! To contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Update documentation
+5. Submit a pull request
+
+### Plugin structure for contributors
+
+```
+hermes-loop/
+├── plugin.yaml         # Plugin manifest
+├── __init__.py         # Registration and hooks
+├── schemas.py          # Tool schemas (LLM-facing)
+├── tools.py            # Tool handlers (implementation)
+├── SKILL.md            # Usage documentation
+└── README.md           # This file
+```
+
+## Resources
+
+- [Hermes Agent Plugin Documentation](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/guides/build-a-hermes-plugin.md)
+- [Subagent-Driven Development Skill](~/.hermes/skills/software-development/subagent-driven-development/SKILL.md)
+- [Writing Plans Skill](~/.hermes/skills/software-development/writing-plans/SKILL.md)
+
+## Version History
+
+### v1.0.0 (2026-03-17)
+
+- Initial release with core loop functionality
+- Support for task_count, file_exists, content_match promise types
+- Automatic state persistence and resumption
+- Stop hook integration for loop continuation control

hermes_loop_plugin-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hermes_loop_plugin/__init__.py,sha256=SgNmDb0Uhun_yXSszooVSG41DzHs-ZnWsKSrcJ5ObIA,10171
+hermes_loop_plugin/commands.py,sha256=6iMnLpeCBiK99S4yqSymSB38fKhxhhj5rAkbyOuhN_w,11186
+hermes_loop_plugin/schemas.py,sha256=WaFNvQsZaS65C_fj2HuE9d7E94MA1EskJuJ4b1YA5Go,1610
+hermes_loop_plugin/tools.py,sha256=WSDdI0VVHlvakWOKvYbD818ew7FLBwJA57o-xnJHrrc,3611
+hermes_loop_plugin-1.0.0.dist-info/licenses/LICENSE,sha256=0-Ba0Itudgl1DfFJZM0eTtHpYyOIywhwDm7EFZHPVCo,1079
+hermes_loop_plugin-1.0.0.dist-info/METADATA,sha256=dzrfK_MpFWQglAIPeHXs5dvOSn7Y_yvQ4SBcdwudwAw,13220
+hermes_loop_plugin-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hermes_loop_plugin-1.0.0.dist-info/entry_points.txt,sha256=FFWtkXHYnVLUyNo5r6_QVauw90iQdP3gJ3zMGiGH_mg,65
+hermes_loop_plugin-1.0.0.dist-info/top_level.txt,sha256=Sr9EdLfHHxs06hjHwbP44kon4k6oNaTPk2ALL7r3lts,19
+hermes_loop_plugin-1.0.0.dist-info/RECORD,,

hermes_loop_plugin-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hermes_loop_plugin-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+hermes-loop = hermes_loop_plugin:register

hermes_loop_plugin-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermes Agent Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_loop_plugin-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hermes_loop_plugin