Help us improve
Share bugs, ideas, or general feedback.
npx claudepluginhub enduser123/loop-coreHow this skill is triggered — by the user, by Claude, or both
Slash command
/loop-core:loop-codeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Autonomous AI development loop that iterates through a plan, executing tasks and tracking completion state until exit conditions are met.
Creates p5.js generative art with seeded randomness, noise fields, and interactive parameter exploration. Use for algorithmic art, flow fields, or particle systems.
Share bugs, ideas, or general feedback.
Autonomous AI development loop that iterates through a plan, executing tasks and tracking completion state until exit conditions are met.
Implements the Ralph-style autonomous loop pattern:
/codeUse /loop-code when you have:
- [ ] TASK-001)Each iteration follows this exact sequence:
Detect terminal_id
get_terminal_id() from loop-core terminal detectionRead loop_state
TerminalStateManager.read_state("loop_state")Load config (fresh each iteration)
load_config() from loop_policy module.claude/loop/config.yamlParse plan
parse_plan_with_cache() from loop_policy module- [ ])Log iteration_start (Observability hook)
log_decision(terminal_id, "iteration_start", {...}) from loop_observabilityExecute /code for task
/code skill with task descriptionUpdate loop_state
TerminalStateManager.write_state("loop_state", state, validate_schema=True)Update metrics (Observability hook)
update_metrics(terminal_id, {...}) from loop_observabilityCheck should_exit
should_exit(tasks, loop_state, config) from loop_policy modulecompletion_indicators >= min_completion_indicators (always required)EXIT_SIGNAL: true (if require_exit_signal is true)require_all_tasks_complete is true)require_verification_pass is true)verification.enabled: true):
Log iteration_end (Observability hook)
log_decision(terminal_id, "iteration_end", {...}) from loop_observabilityLog loop_exit (if should_exit is true) (Observability hook)
log_decision(terminal_id, "loop_exit", {...}) from loop_observabilityExit conditions are configured in .claude/loop/config.yaml:
version: 1
enforcement:
enabled: true # Full policy (default)
# false = Minimal policy (EXIT_SIGNAL + indicators only)
exit_policy:
min_completion_indicators: 2 # Minimum iterations (default: 2)
require_exit_signal: true # Require EXIT_SIGNAL in RALPH_STATUS
require_all_tasks_complete: true # Require all tasks marked complete
require_verification_pass: false # Require verification to pass
verification:
enabled: true # Practical verification (default)
# false = Disabled
lookback_turns: 10 # Chat lookback window for concerns
fuzzy_match_threshold: 0.8 # Requirement matching threshold (0.0-1.0)
plans:
default_plan: plan.md
allow_per_terminal_plan: false
logging:
decision_log: .claude/loop/logs/decision.log
verifier_log: .claude/loop/logs/verifier.log
Enforcement Modes (TASK-018):
enforcement.enabled: true (default): Full policy enforcement
enforcement.enabled: false: Minimal policy enforcement
completion_indicators >= min + EXIT_SIGNAL: truerequire_all_tasks_complete and require_verification_passSetting EXIT_SIGNAL:
The LLM adds this to the plan file's RALPH_STATUS block when it believes all work is complete:
## RALPH_STATUS
- EXIT_SIGNAL: true
- completion_indicators: 3
- current_task: TASK-005
When verification.enabled: true (default), the loop uses practical verification instead of formal PRD verification:
Plan Requirement Extraction:
## Acceptance Criteria## Success Metrics## Constraints## Acceptance Criteria
- [ ] User can authenticate with email/password
- [ ] Password hashing uses bcrypt
- [ ] Login endpoint returns JWT token
Requirement Verification:
Chat Concern Extraction:
Configuration:
verification:
enabled: true # Practical verification (default)
lookback_turns: 10 # Chat lookback window
fuzzy_match_threshold: 0.8 # Requirement matching threshold
Policy-based exit flexibility:
min_completion_indicators: Prevents premature exit on simple tasksrequire_exit_signal: LLM's explicit judgment that plan is completerequire_all_tasks_complete: Ensures all tasks are marked donerequire_verification_pass: Requires successful verification run/loop-code path/to/plan.md
# Feature: User Authentication
## RALPH_STATUS
- EXIT_SIGNAL: false
- completion_indicators: 0
- current_task: TASK-001
## Tasks
- [ ] TASK-001 Design database schema for users table
- [ ] TASK-002 Implement password hashing utility
- [ ] TASK-003 Create login endpoint
- [ ] TASK-004 Write unit tests for auth module
- [ ] TASK-005 Verify all tests pass and document API
Each iteration:
get_terminal_id()state_mgr.read_state("loop_state")load_config(".claude/loop/config.yaml")parse_plan_with_cache("plan.md")log_decision(terminal_id, "iteration_start", {iteration, current_task_id, total_tasks})/code TASK-001 Design database schemastate_mgr.write_state("loop_state", state, validate_schema=True)update_metrics(terminal_id, {iterations: 1, tasks_completed: 1, tasks_failed: 0})should_exit(tasks, loop_state, config)log_decision(terminal_id, "iteration_end", {iteration, tasks_completed, should_exit, exit_reason})log_decision(terminal_id, "loop_exit", {total_iterations, exit_reason, final_state})Continue until all enabled exit conditions are met.
This skill uses loop-core utilities:
loop_policy.load_config(): Load and validate configurationloop_policy.should_exit(): Policy-based exit decision (includes practical verification)loop_policy.parse_plan_with_cache(): Parse plan with cachingloop_policy.parse_plan_requirements(): Extract requirements from plan.mdloop_policy.verify_completion_against_requirements(): Check requirements satisfiedloop_policy.extract_user_concerns_from_chat(): Extract user issues from chatloop_observability.log_decision(): Log iteration eventsloop_observability.update_metrics(): Update performance metricsTerminalStateManager: Persist loop state with schema validation┌─────────────────────────────────────────────────────────────┐
│ /loop-code Skill │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Detect │───→│ Read State │───→│ Load Config │ │
│ │ terminal_id │ │ (state_mgr) │ │ (loop_policy)│ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │
│ │ ┌──────────────┐ │ │
│ └────────→│ Parse Plan │←────────────┘ │
│ │ (loop_policy)│ │
│ └──────────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ Execute /code│ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ Update State│ │
│ │ + Log Event │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ Check Exit │ │
│ │ (should_exit)│ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────────┴──────────┐ │
│ │ │ │
│ Exit true Exit false │
│ │ │ │
│ ┌────┴────┐ ┌─────┴─────┐ │
│ │ EXIT │ │ CONTINUE │ │
│ └─────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
The loop persists state to terminal-local directory:
~/.claude/state/terminals/<terminal_id>/
├── loop_state.json # Current loop state (validated)
├── loop_metrics.json # Performance metrics (best-effort)
└── logs/
└── decision.log # Decision log (JSON lines)
State file structure (loop_state.json) - Canonical Schema:
{
"current_task_id": "TASK-003",
"completed_tasks": ["TASK-001", "TASK-002"],
"failed_tasks": [],
"completion_indicators": 2,
"loop_metadata": {
"plan_path": "/path/to/plan.md",
"started_at": "2026-03-14T10:00:00",
"last_update": "2026-03-14T10:15:00",
"iterations": 3
}
}
All writes to loop_state.json use validate_schema=True to ensure canonical schema compliance.
The loop logs decision events to decision.log (JSON lines format) and metrics to loop_metrics.json:
{"terminal_id": "term_001", "event": "iteration_start", "payload": {"iteration": 1, "current_task_id": "TASK-001", "total_tasks": 5}, "timestamp": "2026-03-14T10:00:00"}
{"terminal_id": "term_001", "event": "iteration_end", "payload": {"iteration": 1, "tasks_completed": ["TASK-001"], "tasks_failed": [], "should_exit": false, "exit_reason": null}, "timestamp": "2026-03-14T10:05:31"}
{"terminal_id": "term_001", "event": "iteration_start", "payload": {"iteration": 2, "current_task_id": "TASK-002", "total_tasks": 5}, "timestamp": "2026-03-14T10:05:32"}
{"terminal_id": "term_001", "event": "iteration_end", "payload": {"iteration": 2, "tasks_completed": ["TASK-001", "TASK-002"], "tasks_failed": [], "should_exit": true, "exit_reason": "all_tasks_complete"}, "timestamp": "2026-03-14T10:10:45"}
{"terminal_id": "term_001", "event": "loop_exit", "payload": {"total_iterations": 2, "total_tasks_completed": 2, "exit_reason": "all_tasks_complete", "final_state": {...}}, "timestamp": "2026-03-14T10:10:46"}
{"terminal_id": "term_001", "event": "error", "payload": {"error_type": "PlanParseError", "error_message": "Plan file not found", "iteration": 3, "current_task_id": "TASK-003"}, "timestamp": "2026-03-14T10:15:00"}
iteration_start: Logged at the beginning of each iteration
iteration, current_task_id, total_tasksiteration_end: Logged at the end of each iteration
iteration, tasks_completed (array), tasks_failed (array), should_exit, exit_reasonloop_exit: Logged when the loop exits (after final iteration)
total_iterations, total_tasks_completed, exit_reason, final_stateerror: Logged when an error occurs during iteration
error_type, error_message, iteration, current_task_id, traceback (optional)loop_metrics.json contains aggregated metrics:
{
"iterations": 5,
"tasks_completed": 5,
"tasks_failed": 0,
"last_update": "2026-03-14T10:10:46"
}
Best-effort logging: I/O errors never break loop execution.
log_decision(terminal_id, "error", {...}) to log errors with details:
error_type: Exception class nameerror_message: Error messageiteration: Current iteration numbercurrent_task_id: Task being executed when error occurredtraceback: Optional traceback string for debugging| Condition | Purpose | Set By | Config Flag | Enforcement Mode |
|---|---|---|---|---|
completion_indicators >= min | Heuristic completion | Auto-incremented | Always required | Both |
EXIT_SIGNAL: true | Explicit LLM judgment | LLM in RALPH_STATUS | require_exit_signal | Both |
| All tasks complete | Ensure all tasks done | Checkbox completion | require_all_tasks_complete | Enabled only |
| Verification passed | Verification required | Verifier skill | require_verification_pass | Enabled only |
Exit logic: ALL enabled conditions must be true (AND logic).
Enforcement modes:
enforcement.enabled: true: All conditions apply (full policy)enforcement.enabled: false: Only completion_indicators >= min + EXIT_SIGNAL: true (minimal policy)Example scenarios:
completion_indicators = 0 and EXIT_SIGNAL: true → Continue (min not met)completion_indicators = 5 and EXIT_SIGNAL: false → Continue (signal not set)verification_status.passed = false → Continue (enforcement enabled, verification required and failed)enforcement.enabled: false, incomplete tasks, but EXIT_SIGNAL: true → Exit (minimal policy, ignores task completion)/code — Feature development workflow (executed by loop for each task)/refactor — Multi-file refactoring (can be invoked for specific tasks)/verify — Verification orchestrator (used when verification enabled)P:/packages/loop-core/skills/loop-code/SKILL.mdP:/packages/loop-core/scripts/loop_policy.pyP:/packages/loop-core/scripts/loop_observability.pyP:/packages/loop-core/scripts/state_manager.pyP:/packages/loop-core/scripts/plan_parser.pyP:/packages/loop-core/scripts/config_schema.pyP:/packages/loop-core/README.md, P:/packages/loop-core/ARCHITECTURE.mdralph-loop, autonomous-development, state-management, policy-based-exit, task-iteration, observability