/loopx-project

name: loopx-project
description: "Use for LoopX project lifecycle work: connect or configure a project/Goal, repair project-local state or stale dashboard status, sync registry entries, or diagnose CLI/PATH/status/history routing. Ordinary task execution and routine refresh-state settlement already directed by a current interaction_contract do not require this skill. For registering durable project materials, prefer loopx-doc-registry."

LoopX Project Workflow

Use this skill when the requested operation changes or diagnoses the project lifecycle, Goal configuration, registry routing, or status projection. A LoopX mention, registry path, or routine `refresh-state` command in an admitted task does not by itself select the project lifecycle workflow.

For ordinary task execution, follow the current `interaction_contract`, its required reads and ordered settlement commands. Do not repeat onboarding, registry synchronization, or lifecycle discovery merely to execute that packet. This routing rule does not replace fresh admission, lease checks, required reads, or repair instructions. A missing or contradictory contract still needs the relevant diagnosis; an explicit request to use this skill still applies.

If the task is mainly about reading, remembering, recording, indexing, or registering a durable project material, load `loopx-doc-registry` and use that narrower workflow first.

LoopX has two layers:

• **Project-local state**: each repo owns `.loopx/registry.json` and

`.codex/goals/<goal-id>/ACTIVE_GOAL_STATE.md`.

• **Shared local control plane**: `~/.codex/loopx` stores run history and

`registry.global.json` for multi-project status.

Do not manually copy one project's registry entry into another project. Local `connect` and `refresh-state` should sync into the shared global registry automatically.

Slash Command Fallback

When asked to upgrade LoopX on a machine with the desktop App, inspect the App bundle and its runtime as well as the CLI. `loopx doctor` exposes `desktop_installation` for standard macOS install locations; a paired bundle still does not prove which App process is running. Upgrade the App and its bundled runtime together, then restart and verify the App, CLI and service source revisions. Never claim a desktop upgrade from CLI/HTTP checks alone: current App builds ask before replacing a different CLI runtime (update the App, or align the CLI to the App's bundled runtime), while an older build can still replace a separately upgraded CLI with its bundle. Keep SSH host verification separate; a host without an App needs no App install.

When the visible user message is exactly a LoopX slash command or starts with a LoopX slash command plus arguments, do not treat it as ordinary chat.

Recognized project-local goal-start command:

• `/loopx <goal text>`
• `/loopx --capability-route issue-fix <goal text>`

Recognized repo-review commands:

• `/loopx-pr-review`
• `/loopx-pr-review <time window or filter text>`

If the text after `/loopx` begins with the exact optional prefix `--capability-route issue-fix`, remove only that prefix from the goal text and pass it as the explicit start-goal route switch. Otherwise every non-whitespace character after `/loopx` is goal text. Never infer a product capability route from issue/PR wording, URLs, or semantic similarity. Do not downgrade either form into a status or inspection turn.

`start-goal --project` keeps the requested project route, including a linked git worktree, so a fresh task cannot inherit an older worktree's goal. Lower-level diagnostic command packs may still report a canonical `canonical_project_alias` / `source_registry` route. Do not manually replace either route with an unadvertised bootstrap command.

From the target project root, pass the text after `/loopx` as the explicit goal-start objective before planning or writing project state:

loopx start-goal --guided --project . --goal-text "<GOAL_TEXT>"

Append `--capability-route issue-fix` only when the caller supplied that exact explicit route switch.

Include `--goal-id <STABLE_GOAL_ID>` when known. Codex App automatically reads the stable ambient `CODEX_THREAD_ID`, while Trae App reads `TRAECLI_THREAD_ID`; other hosts that expose a stable opaque thread id should pass it as `--thread-id <HOST_THREAD_ID>` on every `/loopx` invocation. If that thread is already bound, reuse the returned `--agent-id <REGISTERED_AGENT_ID>` on start, heartbeat, quota, refresh-state, and Todo commands. Include `--agent-id <REGISTERED_AGENT_ID>` only when the current session already owns that identity, the thread binding resolves to it, or the user explicitly asks to take over that exact agent's work.

When a stable thread id is present but has no binding, treat it as a new host session and follow the returned fresh-registration default. Select an existing lane only when the user explicitly requests takeover of that exact agent, then bind it with the returned `bind-agent-thread` command. When no thread id is available, preserve the fail-closed identity gate and never infer takeover from registry order or the only registered lane; pass `--new-peer` only when the user explicitly requests fresh onboarding on that unboundable host. Choose a fresh public-safe id, preview then execute `register-agent`, and require the `--require-new --execute` result to report `ok=true`, `changed=true`, `written=true`, successful global sync, and verified registration readback before rerunning `start-goal` with that new id. A preview is advisory and never allows continuation. If `start-goal --guided` is not available, refresh the local LoopX CLI or use the checked-out LoopX repository CLI for validation; do not silently downgrade `/loopx <goal text>` into a bare `/loopx` read-only command. Use `loopx bootstrap-command-pack --project . --goal-text "<GOAL_TEXT>"` only when implementing or debugging the lower-level host handoff packet.

If the connected goal later needs a wider or correc