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; new Goal state defaults to .loopx/goals/<goal-id>/ACTIVE_GOAL_STATE.md.
• Shared local control plane: the default ~/.loopx stores run history and registry.global.json for multi-project status.

Use the registry-declared state_file and the resolved runtime/global-registry route for existing installations. .codex/goals and ~/.codex/loopx are legacy compatibility paths, not defaults to recreate or migrate implicitly. If routes conflict, diagnose the existing state before selecting or migrating one.

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.

Read The Relevant Procedure Before Acting

The following resources ship with this skill. Resolve their links relative to this file, including after host installation. Read the matching procedure before its operation; ordinary admitted work does not load every procedure.

Operation	Required procedure
/loopx goal-start, connect, identity binding or scope changes	Start and connect
Missing CLI, desktop upgrade, runtime drift, Ego host-skill refresh, diagnosis or registry recovery	Installation and diagnosis
Set up or repair autonomous execution, missing/contradictory contract, state-only delivery writeback	Autonomous execution and settlement
Create, recover or change a recurring heartbeat or host loop	Heartbeat hosts
Relay a review packet, record a human reward or run separately authorized child work	Handoff and feedback
Register material, change an owner-facing Explore view or qualify an enabled change-quality diff	Materials, Explore and quality

Slash Command Fallback

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>

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.

Read start and connect before the first command. From the target project root, pass the explicit goal objective:

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

Append --capability-route issue-fix only for that exact caller-supplied switch. start-goal --project keeps the requested project route, including a linked git worktree. Preserve the returned stable Goal/Agent/thread binding. Do not infer takeover from registry order or the only registered lane. Fresh registration must be executed and read back before continuation; a preview is advisory. /loopx <goal text> is an explicit goal-start intent: first produce a concise ordered plan, then write todos in priority order. Use planner order plus todo add write order as the same-priority tie-breaker, with no management-only filler. If guided start is unavailable, repair the CLI; do not silently downgrade /loopx <goal text> into a bare /loopx read-only command.

Global manager commands such as /loopx-global-summary, /loopx-global-gates, /loopx-global-todos, and /loopx-global-risks are not project bootstrap commands. Route them to the global manager contract or status summary. Legacy /loop-global-* forms are aliases. Read the start procedure for first-use command discovery and use loopx slash-commands for CLI help.

For /loopx-pr-review, load the narrower loopx-pr-review skill. Do not handle /loopx-pr-review from this broader project skill, and do not route it to loopx-pr-merge unless the user later asks to approve, comment on, merge, self-merge, or admin-bypass a specific PR. For a delivery program spanning several PRs/MRs, load loopx-pr-program after the project Goal transaction is established; keep deep review and provider mutations in their separately authorized workflows.

Current State, Continued Work And Settlement

Before autonomous work, read fresh admission, required sources and the current interaction_contract, keeping the same registered Goal/Agent identity. Its user, agent and CLI channels own the current ask/work/settlement split; compatibility fields and summaries are evidence, not competing policy owners. Read goal_boundary for allowed scope, guards, approvals and stop conditions. Quota, context, tools and installed skills do not grant write or spawn authority. A raw/legacy attention queue is not owner/gate/stop authority without a project-asset-backed source.

For first-time or recovered recurring hosts, read heartbeat hosts and install the returned stable bootstrap loader. Each wake reads the full fresh result and follows its current task_body only when ok=true. Never save an expanded static execution body, freeze a turn id, or copy manual accounting into the saved automation. Recover within existing authority when loading fails; if recovery fails, do not execute or account for work, and report the exact blocker.

Choose a verifiable outcome from the current goal, acceptance criteria and recent evidence. Continue while useful in-scope work remains authorized; one operation, writeback, a small diff or an empty Todo frontier is not completion. Carry the selected effort through related implementation/research, validation, writeback and readback. The autonomous procedure retains steering candidates, successor and typed replan details. Correct affected work first; broader replan needs current goal, path, dependency or acceptance evidence. Do not invent replan/self-pause thresholds from wake counts.

Honor explicit user stops and current Core/host stop boundaries. Preserve owed settlement according to the current terminal/recovery contract; continuation or settlement guidance must not override an explicit no-spend stop. If execution is not permitted, retain unsettled state and do not claim settlement is complete. If should_run=false, do not begin delivery unless the current guard explicitly admits a safe bypass. Execute projected monitor, recovery and owed settlement actions within their current contract; these actions do not expand authority. Recover failed or uncertain heartbeat receipts with the same current turn identity before accounting again. No repeated quota spend, invented Todo/lease or new direction follows from this skill.

Notification and execution are separate: notify=DONT_NOTIFY cannot cancel execution_obligation.must_attempt_work=true. Surface the actual projected user action and obey notification cooldowns; do not replace it with a vague owner gate. A gated path does not block independent allowed work for the current goal. Routine public-safe publication can proceed under existing authority after validation and a clean boundary scan; do not add a standing approval gate. Private material, destructive operations, production and explicit repository approval rules retain their own boundaries.

When recording validated progress, provide the actual delivery semantics: --classification <PUBLIC_SAFE_PROGRESS_CLASSIFICATION>, --delivery-batch-scale <ACTUAL_DELIVERY_BATCH_SCALE>, and --delivery-outcome <ACTUAL_DELIVERY_OUTCOME>. Do not infer scale/outcome from a classification name or upgrade preparatory work to satisfy a floor. Follow the refresh procedure for state-only writes, external-sink scope, successor lineage and final readback.

Capability Context And Child Models

Read interaction_contract.agent_context at planning time (or turn_envelope.agent_context in LoopX Turn, resolving its detail reference when compacted). If the host supplies neither, use the read-only loopx agent-context --goal-id <goal> --agent-id <agent> --phase before_plan. If context is absent, disabled, or the read fails, preserve the existing single agent workflow: do not seek delegation splits or invoke child tools because of this capability. Tool availability and installed skills do not activate it. Only apply delegation guidance from a non-null, current-scope enabled context; the capability provider owns that policy. Context never grants spawn authority. Before separately authorized child work, read handoff and feedback for boundary reads, model support, result acceptance and configuration readback.

Validation

After connect or refresh, run the smallest useful set:

loopx registry
loopx status
loopx check --scan-path <PUBLIC_SAFE_FILE_OR_DIR>

For multi-project UI updates, use the current resolved global registry to refresh the dashboard status JSON:

loopx --registry <GLOBAL_REGISTRY> \
  --format json status > <dashboard>/public/status.local.json

Reporting

Report in Chinese when the user is reviewing:

• changed files and whether they are public or local-private;
• validation commands and results;
• how the goal appears in dashboard or attention queue;
• the next safe action;
• any missing gates before decision-advisor or write-controller behavior.

Never include credentials, private docs, raw internal links, production task ids, or raw local evidence in public repo docs or examples.