autonomous-execution-loop

A generic Hermes skill for file-backed autonomous execution: durable plan packages, lightweight control loops, checkpoints, scheduled continuation, and anti-drift rules.

The short version: chat is not the source of truth. The loop files are.

Why it is useful

Autonomous agents fail less because they lack a Kanban board and more because they lose operational state:

• stale next actions
• vague “done” criteria
• cron jobs that keep wandering
• evidence trapped in chat/stdout
• no clear handoff surface for the next run
• bloated execution logs that every next agent rereads from top to bottom like a raccoon with a context window budget

This skill gives agents a scan-friendly file contract that works with any board, repo, notes vault, or scheduler. Execution logs include a top-level TOC so agents can read only the relevant history.

Skill structure

SKILL.md
references/
  full_plan_package_contract.md
  lightweight_control_loop.md
  scheduled_execution_contract.md
  validation_and_checkpoints.md
  design_notes.md
templates/
  full_plan_package/
  lightweight_control_loop/
scripts/
  validate_loop_package.py

Two loop shapes

Full plan package:

plans/<slug>/
├── <slug>_index.md
├── <slug>_plan.md
├── <slug>_next_steps.md
├── <slug>_handoff.md
└── outputs/<slug>_execution_log.md

Lightweight control loop:

<domain>/<slug>.md
<domain>/<slug>/
├── <slug>_control.md
└── <slug>_execution_log.md

Install as a Hermes skill

Copy this folder into a Hermes skills category, for example:

cp -R autonomous-execution-loop /opt/data/skills/productivity/autonomous-execution-loop

Then load it with skill_view(name="autonomous-execution-loop") or through the normal Hermes skill loader.

If you want frontmatter YAML syntax validation, install:

pip install -r requirements.txt

Quick validation

python scripts/validate_loop_package.py <path-to-loop-root>
python scripts/validate_loop_package.py examples/full_plan_package/example_project
python scripts/validate_loop_package.py examples/lightweight_control_loop/example_trip

The validator treats missing/stale execution-log TOCs as warnings rather than hard failures. That keeps the contract non-breaking while still nudging agents away from full-log token bonfires.

Suggested pitch

This complements Hermes autonomous boards: the board shows work; the loop package tells the executing agent how to resume, validate, checkpoint, and stop without guessing.

Concept ideas / future improvements

These are intentionally listed for the next agent or maintainer reading this repo. The current package is usable as a file-contract skill; these ideas would make it easier to adopt upstream.

1. One-command loop generator

Add a small script that creates a valid loop from templates:

python scripts/create_loop.py --kind full --slug my_project --root ./workspace
python scripts/create_loop.py --kind lightweight --domain work --slug client_audit --root ./workspace

Expected behavior:

• copy the right template set
• rename files from template names to <slug>_*
• fill frontmatter dates, slug, status, loop mode
• create outputs/ for full packages
• seed execution-log ## TOC
• run validate_loop_package.py at the end

This would turn the concept from “nice docs” into “try it in 20 seconds”.

2. Board adapter / bridge

Kanban boards and this file contract should reinforce each other:

• board card = visible work item
• loop files = source of truth for autonomous execution
• execution-log TOC = cheap progress/history index
• next_steps or control = what the next run should actually do

A future adapter could scan loop folders and expose cards with:

• slug
• status
• current phase
• next action
• last checkpoint
• blocker / needs human
• link to relevant file surfaces

This avoids making the board the only state store, which is where agents go to cosplay productivity until the context window dies.

3. Stronger validator

Current validator is deliberately lightweight. Future checks worth adding:

• TOC entries match real execution-log headings
• newest log heading appears in TOC
• next_steps / control next action is non-empty when status is active
• done/paused/blocked states include evidence or reason
• full packages always put execution logs under outputs/
• scheduled loops define stop/pause criteria
• stale locks or stale last_run_started_at are flagged

4. Tiny “agent resume” command

Add a script that prints the minimal context an agent should read:

python scripts/resume_context.py ./plans/my_project

Output could include:

• status
• phase
• next action
• blocker
• latest checkpoint
• relevant execution-log TOC lines
• exact files to read next

This keeps the token-saving idea operational instead of relying on every agent to be disciplined. Bold assumption, historically adorable.

5. Clear upstream proposal note

If proposing this to Hermes core, add a short PROPOSAL.md:

• problem: autonomous runs lose durable execution state
• existing board value: visual work tracking
• missing layer: file-backed execution contract
• proposed integration: board reads/writes loop package metadata
• non-goal: replacing boards or project management tools
• MVP: skill + generator + validator + board scanner

Creator probably will not read every reference file. The agent reviewing the repo should be able to pitch it from one page.