zigrix-main-agent-guide

name	zigrix-main-agent-guide
version	0.4.0
description	Main-agent-only guide for Zigrix Task creation, orchestrator binding, lifecycle handoff, dashboard, and path resolution. Never use this skill as orchestrator/worker runtime instruction.
metadata	{"openclaw":{"requires":{"bins":["zigrix"]}}}

Zigrix Main Agent Guide (MAIN-ONLY)

메인 에이전트가 Zigrix를 사용할 때의 표준 흐름.

0) Scope Guard (Critical)

이 스킬은 main agent 전용이다.

• main agent는 사용자 요청을 Task로 만들고, 오케스트레이터를 spawn한 뒤 실제 세션을 Task에 바인딩한다.
• 바인딩 이후 top-level transition과 워커 관리는 저장된 orchestrator binding만 수행한다.
• orchestrator/worker runtime 세션은 이 스킬을 런타임 규칙으로 사용하지 않는다.

오케스트레이터/워커의 canonical instruction은 zigrix/rules/defaults/*와 해당 dispatch/worker overlay prompt다. 호출자가 role: orchestrator라고 주장하거나 로컬 설정에 같은 agent id가 있다는 사실은 권한이 아니다.

1) 기본 명령

zigrix onboard --yes --json
zigrix doctor
zigrix config validate --json
zigrix agent list --json
zigrix dashboard --port 5173

자동화에서는 JSON 출력을 우선 사용한다. 새 lifecycle command의 transport별 flag가 확정되지 않은 경우 zigrix task <command>의 command name과 typed payload contract를 따르고 임의 alias나 누락 필드 추론을 만들지 않는다.

2) 권한이 포함된 표준 lifecycle

순서는 다음과 같이 고정된다.

단계	Stable command	실행 권한과 결과
CREATE	zigrix task create-task / CREATE_TASK	bootstrap composition이 revision 0의 OPEN snapshot을 만든다.
BIND	zigrix task bind-orchestrator / BIND_ORCHESTRATOR	main agent가 spawn에서 반환된 실제 agent/session/sessionId를 저장한다.
START	zigrix task start / START	exact stored orchestrator가 Task를 시작한다.
PREPARE	zigrix task prepare-worker / PREPARE_WORKER	stored orchestrator가 unit의 새 assignment epoch를 준비한다.
REGISTER	zigrix task register-worker / REGISTER_WORKER	stored orchestrator가 실제 worker session/run/unit을 그 epoch에 활성화한다.
SUBMIT	zigrix task submit-unit-result / SUBMIT_UNIT_RESULT	exact bound worker가 자기 active task/agent/session/sessionId/run/unit/assignment epoch의 결과만 제출한다.
APPROVE/REJECT	zigrix task approve-unit-result 또는 zigrix task reject-unit-result	stored orchestrator가 exact submission id/digest/artifact를 판정한다.
FINALIZE	zigrix task finalize / FINALIZE	모든 required unit의 승인 결과와 readiness guard를 확인한 stored orchestrator만 실행한다.
REPORT	zigrix task report / REPORT	stored orchestrator가 DONE_PENDING_REPORT Task를 보고한다.

SUBMIT_UNIT_RESULT는 worker의 bound unit result 제출일 뿐 top-level 완료가 아니다. worker session 종료, ownership, evidence 파일 존재만으로 unit 승인이나 Task 완료를 추론하지 않는다.

3) 오케스트레이터 spawn과 binding

CREATE 결과와 composition layer가 만든 orchestrator prompt를 사용해 오케스트레이터를 spawn한다.

sessions_spawn(
  agentId: <selectedOrchestratorId>,
  label: <orchestratorLabel>,
  cwd: <resolvedProjectDir>,
  task: <orchestratorPrompt>
)

spawn 성공 직후 main agent는 반환된 실제 sessionKey와 sessionId를 BIND_ORCHESTRATOR payload에 넣는다. 저장된 binding은 agentId, sessionKey, sessionId, bindingEpoch가 모두 정확히 일치해야 하며, 이후 START, worker prepare/register, result approval/rejection, FINALIZE, REPORT에도 이 principal을 사용한다.

main agent는 binding 이후 자신이 START, FINALIZE, REPORT를 대신 호출하지 않는다. 오케스트레이터 spawn 또는 binding이 실패하면 실패를 보고하고 로컬 직접 구현으로 우회하지 않는다.

/oz and delegation guard

/oz 또는 자연어 위임 라우팅이 현재 턴을 delegate로 판정하면 main agent는 실행자가 아니라 router다.

• 허용: CREATE, orchestrator spawn, BIND, read-only status/events 확인, 실패 보고
• 금지: 직접 구현, 직접 파일 수정 우회, worker 결과 대리 제출, orchestrator transition 대리 실행
• create/spawn/bind 실패 시: 실패를 보고하고 중단

4) Command identity, revision, recovery

모든 mutation은 schema version, deterministic command id, payload digest, expected revision을 포함한다.

• latest authoritative metadata revision을 기준으로 command를 구성한다.
• 성공 응답 또는 같은 receipt를 받기 전에는 command id와 payload를 바꾸지 않는다.
• 같은 command id와 같은 payload의 재시도만 idempotent recovery다.
• 같은 id에 다른 payload는 command_id_collision, pending 중 다른 command는 pending_commit_conflict다.
• recoverable_in_doubt에서는 snapshotUnchanged:false로 간주하고 원래 command id/payload로 복구한다. metadata, audit, evidence, index를 직접 고치거나 새 command로 추월하지 않는다.

5) Cancel/stale는 request-only

operator cancel/block 의도는 zigrix task block-request / BLOCK_REQUEST, system stale 진단은 zigrix task stale-detected / STALE_DETECTED로 기록한다. 둘 다 Task status나 revision을 바꾸지 않는다.

stored orchestrator만 ACK_BLOCK_REQUEST로 실제 BLOCK transition을 합성하거나 REJECT_BLOCK_REQUEST로 요청을 기각한다. 오케스트레이터가 응답하지 않으면 요청은 unresolved 상태와 orchestrator_action_required로 남는다. 직접 stale 적용, timeout 권한 승격, raw status 수정은 금지한다.

6) 경로와 상태 확인

CLI JSON 응답의 resolved path를 우선 사용한다. bare symbolic key(paths.tasksDir, workspace.projectsBaseDir)를 파일 경로처럼 직접 쓰지 않는다.

zigrix task status <taskId> --json
zigrix task events <taskId> --json
zigrix path get tasksDir --json
zigrix path get workspace.projectsBaseDir --json
zigrix path list --json

대시보드와 status에서 다음을 확인한다.

• top-level 상태: OPEN → IN_PROGRESS → DONE_PENDING_REPORT → REPORTED 또는 orchestrator-authorized BLOCKED
• stored orchestrator binding과 binding epoch
• unit별 current assignment epoch와 worker session binding
• submitted result와 orchestrator approval/rejection
• unresolved block/stale request와 orchestrator_action_required
• pendingCommit 및 in-doubt recovery 정보

Task metadata snapshot이 source of truth다. tasks.jsonl은 audit diagnostic, index.json은 rebuildable projection이며 어느 쪽도 snapshot을 덮어쓰지 않는다.