zigrix-shared

name	zigrix-shared
version	0.4.0
description	Shared guidance for Zigrix authority, lifecycle commands, output modes, path resolution, and safety.
metadata	{"openclaw":{"requires":{"bins":["zigrix"]}}}

Zigrix Shared Reference

Use Zigrix for multi-project parallel Task orchestration with file-backed, inspectable state.

Rules

• Prefer --json for established automation surfaces.
• Tasks are not project-bound; one Zigrix instance manages tasks across projects.
• Treat tasks/<taskId>.meta.json as authoritative. Audit and index files are diagnostics/projections.
• Do not assume OpenClaw internals are required unless the task explicitly needs them.

Authority and lifecycle contract

The closed lifecycle is:

CREATE_TASK -> BIND_ORCHESTRATOR -> START
  -> PREPARE_WORKER -> REGISTER_WORKER
  -> SUBMIT_UNIT_RESULT
  -> APPROVE_UNIT_RESULT | REJECT_UNIT_RESULT
  -> FINALIZE -> REPORT

• Bootstrap composition may create and bind the actual spawned orchestrator.
• After binding, only the exact stored orchestrator agent/session/sessionId/binding epoch may commit top-level transitions, prepare/register assignments, decide results, expire/reassign workers, finalize, or report.
• A worker may submit only its exact active task/agent/session/sessionId/run/unit/assignment epoch result. Submission is not approval and never completes the Task.
• Operator cancellation/block and system stale detection are request-only. They do not mutate status or revision.
• Every mutation is revision-checked and identified by a deterministic command id and payload digest. Recover in-doubt work only by retrying that same command and payload.
• Never use a raw status setter, generic metadata setter, caller-supplied role, direct metadata edit, or audit/index rewrite as transition authority.

Use only the approved stable Task command names (create-task, bind-orchestrator, start, block, resume, finalize, report, block-request, stale-detected, ack-block-request, reject-block-request, prepare-worker, register-worker, submit-unit-result, approve-unit-result, reject-unit-result, expire-assignment, reassign-worker). Do not invent compatibility aliases or transport flags.

Path Resolution Contract

Bare symbolic keys such as paths.tasksDir and workspace.projectsBaseDir are config key names, not auto-expanded variables. Resolve paths in this order:

1. Use already-resolved path fields in the active command's JSON result, such as specPath, metaPath, promptPath, projectDir, and evidence artifact paths.

2. Use zigrix task status <taskId> --json for Task paths.

3. Use zigrix path for runtime directories:

   zigrix path get tasksDir --json
   zigrix path get evidenceDir --json
   zigrix path get workspace.projectsBaseDir --json
   zigrix path list --json
   

4. Use zigrix doctor --json for the environment overview.

5. As a last resort, read ~/.zigrix/zigrix.config.json and resolve paths.* manually.

Safe read-only commands

zigrix doctor --json
zigrix task list --json
zigrix task status <taskId> --json
zigrix task events <taskId> --json
zigrix path list --json

Safety

• Confirm before destructive actions.
• Treat runtime state and source code as separate concerns.
• Preserve OpenClaw managed-skill conflicts and user drift. Never force-overwrite a conflicting target.