LoopX Goal Lifecycle: From Creation to Completion in Open-Source Autonomous Task Management

A LoopX goal progresses through a 10-stage pipeline: creation via slash command, registration in the goal registry, activation by the runtime, vision construction, frontier evaluation, autonomous re-planning, task scheduling, monitoring, terminal state derivation, and post-completion cleanup.

LoopX treats a Goal as a first-class, long-running unit of work managed by an autonomous control plane. Understanding the complete LoopX goal lifecycle helps developers debug stuck goals, optimize re-plan rules, and extend the system with custom monitors. This article traces the exact implementation across the huangruiteng/loopx repository, referencing actual source file paths and core functions.

---

Goal Creation and Slash Command Registration

Goals originate from user or automation-initiated slash commands.

The test suite in tests/test_slash_command_install.py validates that the createLoopxGoalPlugin command is registered correctly. Lines 152-158 verify the plugin's presence and command string:

# tests/test_slash_command_install.py

plugin = Path("src/loopx/feature/goal_creation_plugin")
skill_text = plugin.read_text(encoding="utf-8")
assert "Ark Managed Agent one-shot Goal submission" in skill_text
assert "createLoopxGoalPlugin" in plugin.read_text(encoding="utf-8")

When invoked, this command:

• Generates a unique LoopX Goal ID
• Captures the prompt and optional metadata
• Triggers goal registration

# Python wrapper for Goal creation

from loopx.slash_commands import createLoopxGoalPlugin

goal_id = createLoopxGoalPlugin(
    prompt="Refactor the authentication middleware",
    metadata={"priority": "critical", "team": "platform"}
)
print(f"Created Goal {goal_id}")

---

Goal Registration and Registry Persistence

The slash command handler writes a goal definition file and updates loopx/registry.py, which maintains the central index of active goals.

The registry:

• Stores in-memory goal metadata
• Persists to ~/.loopx/registry.json
• Enables runtime discovery of new and existing goals

---

Goal Activation and Runtime Loop Spawning

loopx/runtime.py detects newly registered goals and spawns dedicated Goal Loop processes via run_goal_loop(goal_id).

Each goal loop owns:

• Execution context
• Vision projection (remaining work)
• Frontier projection (unclaimed advancement items)

The loop registers with goal_channel.py for inter-process coordination.

from loopx.runtime import run_goal_loop

# Normally triggered automatically; manual activation for testing

run_goal_loop(goal_id)  # Starts the goal's event loop

---

Vision Construction and State Evaluation

The vision represents a projection of all remaining work—TODOs, monitor lanes, and pending successor goals. It answers three critical questions:

• Can the goal close?
• Does it need re-planning?
• Must it spawn a successor?

Core Vision Files

File	Purpose
loopx/control_plane/goals/goal_vision.py	Builds vision from TODOs, monitors, and targeted items
loopx/control_plane/goals/goal_vision_state.py	Contains goal_vision_state_is_closed predicate
loopx/control_plane/goals/goal_vision_policy.py	Policy rules for vision transitions

The vision module imports build_targeted_items to construct work item projections:

# From goal_vision.py

from .targeted_item import (
    targeted_item,
    create_targeted_item,
    build_targeted_items,
)
from .goal_vision_state import (
    goal_vision_state_is_closed,
    # ...

)

---

Frontier Evaluation and Terminal State Derivation

The frontier contains unclaimed or partially claimed advancement items. loopx/control_plane/goals/goal_frontier.py evaluates whether autonomous action is required.

Key Function: derive_goal_terminal_state

Lines 69-85 determine if a goal reaches terminal state based on TODO summaries and frontier emptiness:

from loopx.control_plane.goals.goal_frontier import derive_goal_terminal_state

terminal, detail = derive_goal_terminal_state(
    user_todo_summary=user_summary,
    agent_todo_summary=agent_summary,
    projection=current_projection
)

if terminal is not None:
    print(f"Goal complete: {detail}")
    # Stores with schema version goal_terminal_state_v0

Monitor Triggers

Constants defined lines 49-52 configure automatic re-plan triggers:

• MONITOR_NO_CHANGE_STREAK_TRIGGER: Fires when a monitor lane shows no activity

---

Autonomous Re-Planning and Obligations

When frontier rules trigger, goal_frontier_replan_rules.py generates autonomous re-plan obligations—actions that mutate the goal's work plan without human intervention.

Rules include:

• AUTONOMOUS_REPLAN_REQUIRED
• Successor goal spawning
• TODO gap filling

The payload builder build_autonomous_replan_obligation_payload in autonomous_replan_obligation.py constructs these mutations.

from loopx.control_plane.goals.goal_frontier import trigger_autonomous_replan

# Manually trigger for monitor gaps or testing

trigger_autonomous_replan(goal_id, reason="monitor_no_change_streak")

---

Task Scheduling and Execution

loopx/control_plane/scheduler/execution_context.py pulls tasks from the frontier and assigns them to agents.

The GoalRuntimeContinuationDisposition enumeration defines execution outcomes:

• CONTINUE: Proceed with next task
• PAUSE: Block pending external input
• TERMINATE: End goal loop

Task types include:

• Normal TODO advances
• Monitor checks
• Continuation prompts

---

Monitoring and Gap Handling

Continuous monitors track work lane health. When MONITOR_NO_CHANGE_STREAK_TRIGGER fires:

• The event records in the projection
• May trigger automatic re-planning
• Surfaces to operators for intervention

---

Goal Completion and Cleanup

A goal completes when:

1. All TODOs are closed
2. Vision reports goal_vision_state_is_closed is true
3. Frontier is empty (derive_goal_terminal_state returns non-None)

Terminal state is stored with schema version goal_terminal_state_v0 (line 85).

Post-completion, project_skill_delivery.py and project_uninstall.py:

• Archive goal metadata
• Remove registry entry
• Release temporary resources (files, sockets)

---

Summary

• Creation: Slash command createLoopxGoalPlugin registers new goals
• Registration: loopx/registry.py persists goal metadata to disk
• Activation: run_goal_loop() spawns dedicated goal processes
• Vision: goal_vision.py projects remaining work; goal_vision_state.py checks closure
• Frontier: goal_frontier.py evaluates advancement items and derives terminal state
• Re-planning: goal_frontier_replan_rules.py triggers autonomous obligations
• Scheduling: execution_context.py dispatches tasks to agents
• Monitoring: Built-in triggers detect stalled lanes
• Termination: Terminal state derived when TODOs closed and frontier empty
• Cleanup: Registry purge and resource release by delivery/uninstall modules

---

Frequently Asked Questions

How do I programmatically check if a LoopX goal is finished?

Query the goal's projection and check goal_vision_state_is_closed combined with an empty frontier. The derive_goal_terminal_state function in goal_frontier.py wraps this logic—returning a terminal record only when both conditions satisfy completion criteria.

What triggers automatic re-planning in LoopX?

Three primary conditions: monitor no-change streaks exceeding MONITOR_NO_CHANGE_STREAK_TRIGGER, frontier items remaining unclaimed past timeout thresholds, and policy violations detected in goal_vision_policy.py. Each route through goal_frontier_replan_rules.py to generate obligations.

Can I manually force a goal to re-plan?

Yes. Import trigger_autonomous_replan from loopx.control_plane.goals.goal_frontier and invoke with the goal ID and reason string. This bypasses normal trigger conditions and immediately enqueues re-plan obligations.

Where is the goal's completion state stored?

Terminal state records use schema version goal_terminal_state_v0, persisted by derive_goal_terminal_state at goal_frontier.py line 85. The registry entry is subsequently removed and metadata archived by the cleanup modules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}