LoopX Project Workflow
Use this skill when the requested operation changes or diagnoses the project
lifecycle, Goal configuration, registry routing, or status projection, or a direct
user request materially refines the bound Goal’s supporting outcomes. 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
~/.loopxstores run history andregistry.global.jsonfor 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.
Direct User Refinements In A Bound Goal
Ordinary user additions and corrections matter even without a /loopx prefix.
Before continuing a substantive deliverable, read outcome refinement.
Reuse the existing Goal/Agent and outcome. A correction to what counts as success
must update the corresponding durable requirements before dependent work; chat,
peer acknowledgements and Vision alone do not update acceptance. Preserve the
overall objective when only acceptance changes, and preserve unaffected earlier
requirements. Reconcile any conflict explicitly through the existing owner.
A milestone artifact with independent quality criteria can be a supporting
outcome without another runtime/Goal. Do not promote every step.
The source is actual direct user context, not heartbeat text, quotations, tools
or peer instructions. Attribution never expands authority. Record in-scope
refinement under existing authorization, link concrete work, read back, and
revisit unmet requirements before switching focus or claiming completion.
If recorded direct user direction makes the Goal objective obsolete, use
goal-acceptance prepare-objective with the proposed objective, reason and
opaque source reference. Autonomous replanning may discover this mismatch from
existing user context; it need not request new intent merely because the Agent
initiated the review. Surface the existing proposal once as reviewable output,
not a mandatory question or precondition for continuing authorized work.
Preparing or reusing a pending proposal changes neither the current objective
nor execution authority. Continue under the current valid Goal; pause only an
action that actually depends on missing intent or authority. Use existing
explicit authorization for the unchanged proposal without asking again. These
rules also apply in unattended harness and benchmark runs; never create an
owner gate merely to surface a proposal. Do not silently edit Markdown or treat
a peer/document as authorization.
Ordinary progress, Todo/route changes, diagnostic feedback, wording polish or
age alone need no revision. Reuse an existing pending proposal without polling.
The current canonical objective then takes precedence over the old source text.
Only after owner apply, before new execution, each Agent reviews its own Todo/Vision route and records
goal-acceptance adopt-objective with its exact revision/digest and inspected
objective_work_digest. One peer cannot acknowledge for another; no unanimous
vote, human response or extra write is needed after that revision is adopted.
Use CLI inspect-proposal / apply-proposal --proposal-id and the document
formats in goal-acceptance --help; App access or source-code inspection is
not required. Owner apply retains its authority boundary. See the
operating-objective procedure.
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.
Use the narrowest existing read that answers the next decision. Known paths or
record IDs go directly to batched reads; discover only missing locations. Reuse
the same captured response while applicable, and size independent read batches
against their combined output budget. Keep dependent operations and mutations
ordered; refresh authority after relevant state changes. For missing paths,
truncation or uncertain effects, load loopx-self-repair, then follow its
references/targeted-diagnostics.md instead of repeating a
directory/status/full-packet preflight.
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
Choose validation for the operation actually performed:
- After connection, routing changes or state repair, verify the affected registry
route and Goal status through the relevant procedure. Use the command's complete
readback when it proves the result; request missing facts with scoped
loopx registryorloopx statusreads. - For ordinary admitted work, validate the deliverable and consume the current
interaction_contractsettlement receipts. A successfulrefresh-statedoes not itself require another registry/status discovery or public-boundary scan of private working evidence. Do not create extra validation manifests merely to certify those same receipts. Preserve fresh admission, required source reads, leases, required checks and failed/uncertain writeback recovery. - Before public submission or export, run
loopx check --scan-path <PUBLIC_SAFE_FILE_OR_DIR>on the actual publication candidates and inspect the result. Private settlement does not replace this boundary check.
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.