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

> Explore the 10-stage LoopX goal lifecycle, from creation to completion. Understand how LoopX autonomously manages tasks in this open-source system.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: deep-dive
- Published: 2026-08-07

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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:

```python

# 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

# 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/goal_channel.py) for inter-process coordination.

```python
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/goal_vision.py) | Builds vision from TODOs, monitors, and targeted items |
| [`loopx/control_plane/goals/goal_vision_state.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/goal_vision_state.py) | Contains `goal_vision_state_is_closed` predicate |
| [`loopx/control_plane/goals/goal_vision_policy.py`](https://github.com/huangruiteng/loopx/blob/main/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:

```python

# 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`](https://github.com/huangruiteng/loopx/blob/main/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:

```python
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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/autonomous_replan_obligation.py) constructs these mutations.

```python
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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/project_skill_delivery.py) and [`project_uninstall.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) persists goal metadata to disk
- **Activation**: `run_goal_loop()` spawns dedicated goal processes
- **Vision**: [`goal_vision.py`](https://github.com/huangruiteng/loopx/blob/main/goal_vision.py) projects remaining work; [`goal_vision_state.py`](https://github.com/huangruiteng/loopx/blob/main/goal_vision_state.py) checks closure
- **Frontier**: [`goal_frontier.py`](https://github.com/huangruiteng/loopx/blob/main/goal_frontier.py) evaluates advancement items and derives terminal state
- **Re-planning**: [`goal_frontier_replan_rules.py`](https://github.com/huangruiteng/loopx/blob/main/goal_frontier_replan_rules.py) triggers autonomous obligations
- **Scheduling**: [`execution_context.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/goal_vision_policy.py). Each route through [`goal_frontier_replan_rules.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/goal_frontier.py) line 85. The registry entry is subsequently removed and metadata archived by the cleanup modules.