diff --git a/skills/agent-estate/SKILL.md b/skills/agent-estate/SKILL.md new file mode 100644 index 000000000..e0bf841f9 --- /dev/null +++ b/skills/agent-estate/SKILL.md @@ -0,0 +1,122 @@ +--- +name: agent-estate +description: Perpetual autonomous work loop for Claude Code — no end condition, no memory regression, no context overfill. Maintains a persistent ledger across all sessions. +--- + +# Agent Estate + +Perpetual autonomous work loop plugin for Claude Code. Turns Claude into an agent that works cycle after cycle, maintaining a persistent ledger across all sessions, never stopping until explicitly told to. + +## Overview + +Agent Estate creates an infinite work loop by intercepting Claude's stop events via a shell hook. Each time Claude tries to exit, the hook blocks the exit, increments the cycle counter, and re-injects the prompt — creating a true perpetual agent. + +## Architecture + +``` +agent-estate/ +├── .claude-plugin/plugin.json # Plugin manifest (name, version, author) +├── commands/ +│ ├── start.md # /agent-estate:start — activates the loop +│ ├── stop.md # /agent-estate:stop — removes state file to allow exit +│ └── status.md # /agent-estate:status — shows cycle count, ledger summary +├── hooks/ +│ ├── hooks.json # Registers stop-hook.sh on the "Stop" event +│ └── stop-hook.sh # Core engine: blocks exit, increments cycle, re-injects prompt +├── scripts/ +│ └── setup-estate.sh # Creates .claude/agent-estate.local.md state file +├── LICENSE +└── README.md +``` + +## Key Components + +### Stop Hook (`hooks/stop-hook.sh`) + +The core engine. Runs on every Claude "Stop" event: + +1. Checks if `.claude/agent-estate.local.md` exists (is the loop active?) +2. If **not active**: exits normally (exit 0) +3. If **done** (`done: true` in frontmatter): removes state file, exits normally (auto-stop) +4. If **active and not done**: + - Detects rate limits (429) → waits 60s + - Detects API overload (529) → waits 30s + - Increments cycle counter in the state file + - Outputs a JSON `{"decision": "block", "reason": "..."}` to prevent exit + - Re-injects the prompt for the next cycle + +### Setup Script (`scripts/setup-estate.sh`) + +Creates the state file at `.claude/agent-estate.local.md` with YAML frontmatter (`active`, `cycle`, `started_at`, `user_prompt`) and the full cycle protocol instructions. If already active, outputs current state and continues. + +### Ledger (`.claude/agent-estate.md`) + +The persistent brain — every Claude session reads and updates it. Contains: + +- **Current Status** — phase, focus, momentum, cycle count +- **Session Log** — what happened each session +- **Worked Things** — table of everything done with files touched +- **Future Works** — prioritized task queue +- **More Works** — ideas, discoveries, nice-to-haves +- **Statistics** — cycles, tests, bugs fixed, features shipped +- **Tell The Next Claude** — sacred handoff message for cross-context memory + +### State File (`.claude/agent-estate.local.md`) + +Ephemeral file that signals an active loop. Contains the cycle counter and preserved user prompt. Removing this file (via `/agent-estate:stop`) is the **only** way to end the loop. + +## Commands + +| Command | Description | +|---------|-------------| +| `/agent-estate:start` | Activate the loop in perpetual mode (no end condition) | +| `/agent-estate:start ` | Start perpetual mode with a specific task focus | +| `/agent-estate:start --done ` | Start in done mode — auto-stops when task is complete | +| `/agent-estate:status` | Show current cycle, mode, stats, and the latest handoff message | +| `/agent-estate:stop` | Manually remove the state file to stop the loop | + +## Work Priority Protocol + +Built into the agent instructions, in order: + +1. **Broken things** — failing tests, bugs, errors +2. **Incomplete things** — half-finished features, TODOs, FIXMEs +3. **Missing things** — no tests, no error handling +4. **Ugly things** — code smells, dead code +5. **Slow things** — performance issues +6. **New things** — features that improve the project +7. **Creative things** — surprise the user + +## Cycle Protocol + +Each cycle follows this pattern: + +1. Read `.claude/agent-estate.md` (the ledger) +2. Decide what to work on next +3. **Do the work** — write code, fix bugs, add features, run tests +4. Update the ledger with what was done, discovered, and planned +5. Update statistics, session log, and "Tell The Next Claude" handoff +6. Immediately start the next cycle (never stop) + +## Prerequisites + +- `jq` — required for JSON output in the stop hook +- Claude Code with plugin support + +## Installation + +```bash +git clone https://github.com/MercuriusDream/agent-estate.git +mkdir -p ~/.claude/plugins/local +ln -s "$(pwd)/agent-estate" ~/.claude/plugins/local/agent-estate +chmod +x agent-estate/scripts/setup-estate.sh +chmod +x agent-estate/hooks/stop-hook.sh +``` + +## Tips + +- **Long sessions**: Claude Max recommended for extended autonomous runs +- **Guiding prompts**: Use `/agent-estate:start ` for focused work without being restrictive +- **Ledger size**: If it exceeds ~300KB, Claude will auto-summarize older cycles +- **Resuming**: The ledger persists after stop. Start again and Claude picks up from the handoff +- **Full autonomy**: No prompt = Claude explores and decides what's most valuable