zigrix 0.2.0 → 0.2.1

package/skills/oz/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: oz
+version: 0.2.0
+description: Official OpenClaw Zigrix entrypoint. Force Zigrix delegation when a message starts with `/oz`, and semantically route plain-language requests to hand work off, assign it, or have Zigrix take it instead of doing the work directly.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix task dispatch --help"
+---
+
+# /oz — OpenClaw Zigrix Entrypoint
+
+Use this skill when either of the following is true:
+
+1. the user message starts with `/oz `
+2. the user is clearly asking, in natural language, to have work **delegated / handed off / assigned / orchestrated through Zigrix** instead of having the current main agent do it directly
+
+This skill is the public OpenClaw-facing entrypoint for Zigrix after `zigrix onboard` installs bundled skills.
+
+## 1) Route selection
+
+### `/oz` prefix
+If the message starts with `/oz `, treat it as:
+- `route = delegate`
+- `delegateMode = force`
+
+Remove the `/oz` prefix and use the remaining text as the delegation payload.
+
+### Natural-language delegation
+If there is no `/oz` prefix, judge the user's intent **semantically**.
+
+- Use the full meaning of the request and nearby context.
+- Do **not** rely on keyword tables or regex lists as the decision mechanism.
+- When helpful, read:
+  - `references/routing-rubric.md`
+  - `references/examples.md`
+
+Classify the turn into one of:
+- `delegate`
+- `direct`
+- `answer`
+
+### Semantic routing policy
+- Choose **`delegate`** when the user wants work to be handed off, assigned, orchestrated, or otherwise run through Zigrix rather than performed directly by the current main agent.
+- Choose **`direct`** only when the user explicitly wants the current agent to do it directly.
+- Choose **`answer`** when the user is asking for explanation, status, architecture, policy, or other non-execution discussion.
+- If the request is ambiguous but points toward tracked execution / implementation / multi-step change, bias toward `delegate` unless the user explicitly asked for direct execution.
+
+## 2) Delegate flow
+
+If `route = delegate`, use the canonical Zigrix handoff chain:
+
+1. Turn the user request into:
+   - `title`
+   - `description`
+   - `scale`
+   - optional `projectDir`
+2. Run:
+
+```bash
+zigrix task dispatch \
+  --title "..." \
+  --description "..." \
+  --scale simple|normal|risky|large \
+  --project-dir /path/to/project \
+  --json
+```
+
+3. Read the JSON result and extract:
+   - `taskId`
+   - `orchestratorId`
+   - `orchestratorPrompt`
+   - `projectDir`
+4. Spawn the orchestrator with the returned prompt.
+
+Preferred pattern:
+
+```text
+sessions_spawn(
+  agentId: <orchestratorId>,
+  mode: "session",
+  thread: true when the current surface supports stable Zigrix thread orchestration, otherwise false,
+  label: "[<orchestratorId>] <taskId>",
+  task: <orchestratorPrompt>,
+  cwd: <projectDir when present>
+)
+```
+
+5. Reply briefly with the handoff result (`taskId`, orchestrator/session/thread info).
+
+## 3) Delegate-only guard
+
+Once this skill decides `route = delegate`:
+- do **not** directly implement the task
+- do **not** directly edit/write project files as a substitute for Zigrix handoff
+- do **not** fallback to direct execution if dispatch or spawn fails
+
+If dispatch or spawn fails:
+- report the failure clearly
+- include the failing step
+- stop there
+
+## 4) Empty or underspecified payloads
+
+If `/oz` is used but the remaining payload is empty or too underspecified to create a task:
+- ask the user to restate the task in one clear sentence
+- do not silently guess
+- do not direct-execute instead
+
+## 5) Direct / answer cases
+
+If semantic routing chooses:
+- `direct` → current agent may proceed with direct execution
+- `answer` → answer normally without creating a Zigrix task
+
+This skill exists to decide **whether the request should enter Zigrix orchestration** and, when yes, to force the canonical delegation path.

package/skills/oz/references/examples.md

@@ -0,0 +1,44 @@
+# `/oz` Routing Examples
+
+These examples are here to anchor semantic routing. They are examples, not an exhaustive phrase list.
+
+## Force delegate
+- `/oz 로그인 세션 버그 고쳐`
+- `/oz hand this to Zigrix and fix the auth flow`
+- `/oz investigate why onboard is skipping skills`
+
+Expected route: `delegate`
+
+## Natural-language delegate
+- `이거 맡겨`
+- `이 작업 위임해라`
+- `오케스트레이터로 넘겨서 처리해`
+- `이건 네가 직접 하지 말고 Zigrix로 태워`
+- `hand this off`
+- `route this through Zigrix`
+- `assign this to the orchestrator`
+
+Expected route: `delegate`
+
+## Direct execution
+- `이건 네가 직접 해`
+- `위임하지 말고 지금 네가 수정해`
+- `don’t delegate this, do it yourself`
+
+Expected route: `direct`
+
+## Answer only
+- `왜 task dispatch 다음에 sessions_spawn이 필요한데?`
+- `현재 Zigrix/OpenClaw 통합 구조 설명해라`
+- `what does zigrix onboard actually register?`
+
+Expected route: `answer`
+
+## Ambiguous but execution-oriented
+- `로그인 버그 고쳐`
+- `이 이슈 조사해서 정리해`
+- `세션/thread 진입점 구조 정리하고 필요한 수정 진행해`
+
+Default bias:
+- if the surrounding context implies tracked orchestration / handoff, choose `delegate`
+- if the surrounding context clearly asks the current agent to do it directly, choose `direct`

package/skills/oz/references/routing-rubric.md

@@ -0,0 +1,71 @@
+# `/oz` Semantic Routing Rubric
+
+This reference exists to keep natural-language delegation routing **semantic-first**.
+
+## Core principle
+Do **not** implement delegation routing as a keyword table or regex checklist.
+
+Instead, decide from the user's **meaning**:
+- who should own the work
+- whether execution is being requested
+- whether the user wants Zigrix/orchestration/another agent to take the task
+- whether the user is explicitly asking for direct execution instead
+
+## Route categories
+
+### 1) `delegate`
+Choose `delegate` when the user wants work to be:
+- handed off
+- assigned
+- orchestrated
+- run through Zigrix
+- taken by another agent / worker / orchestrator
+
+Also choose `delegate` when the request is clearly about **tracked execution** and the intent is to kick off work rather than just discuss it.
+
+Typical shapes:
+- implementation / bug fix / refactor / investigation / multi-step execution
+- “don’t do this yourself — pass it through the orchestration flow”
+- “make Zigrix take this task”
+
+### 2) `direct`
+Choose `direct` only when the user clearly wants the **current main agent** to do the work directly.
+
+Typical signs:
+- explicit direct instruction
+- explicit anti-delegation instruction
+- small bounded task with no request to hand it off
+
+### 3) `answer`
+Choose `answer` when the user is not asking to execute or hand off work, but instead wants:
+- explanation
+- architecture discussion
+- status
+- comparison
+- policy/design reasoning
+- review of an idea without starting execution
+
+## Bias rule
+If the request is ambiguous but points toward:
+- state-changing work
+- multi-step implementation
+- tracked execution
+- “someone else / Zigrix should take this”
+
+bias toward `delegate` unless the user clearly requested direct execution.
+
+## Hard rules
+- `/oz ...` is always `delegate`.
+- Once `delegate` is chosen, do not direct-execute as a fallback.
+- If the task text is too thin to dispatch safely, ask for clarification instead of direct-executing.
+- Use the existing canonical Zigrix chain:
+  - `zigrix task dispatch --json`
+  - `sessions_spawn(... orchestratorPrompt ...)`
+
+## What this rubric is not
+This rubric is not:
+- a regex spec
+- an exhaustive phrase list
+- a locale-locked keyword matcher
+
+It is a semantic decision guide for LLM-based routing.

package/skills/zigrix-main-agent-guide/SKILL.md

@@ -1,17 +1,27 @@
 ---
 name: zigrix-main-agent-guide
-version: 0.2.0
-description: Main-agent guide for using Zigrix CLI (task issuance, orchestrator spawn, dashboard, and path resolution).
+version: 0.3.0
+description: Main-agent-only guide for Zigrix CLI (task issuance, orchestrator spawn, `/oz` handoff guard, dashboard, and path resolution). Never use this skill as orchestrator/worker runtime instruction.
 metadata:
   openclaw:
     requires:
       bins: ["zigrix"]
 ---
 
-# Zigrix Main Agent Guide
+# Zigrix Main Agent Guide (MAIN-ONLY)
 
 메인 에이전트가 Zigrix를 사용할 때의 표준 흐름.
 
+## 0) Scope Guard (Critical)
+
+이 스킬은 **main agent 전용**이다.
+
+- 허용 주체: 사용자 요청을 받아 `dispatch/spawn/report`를 수행하는 **main agent**
+- 금지 주체: orchestrator/worker runtime 세션(역할 워커 세션 전반)
+
+오케스트레이터/워커는 이 스킬을 런타임 규칙으로 사용하지 않는다.  
+오케스트레이터/워커의 canonical instruction은 `zigrix/rules/defaults/*` + dispatch/worker overlay prompt다.
+
 ## 1) 기본 명령
 
 ```bash
@@ -47,6 +57,7 @@ zigrix task dispatch \
 - `baselineRequiredAgents`
 - `candidateAgents`
 - `orchestratorPrompt`
+- `orchestratorLabel`
 - `specPath` — resolved absolute path to spec markdown
 - `metaPath` — resolved absolute path to metadata JSON
 - `promptPath` — resolved absolute path to dispatch prompt
@@ -59,20 +70,39 @@ zigrix task dispatch \
 ```text
 sessions_spawn(
   agentId: <orchestratorId>,
+  label: <dispatchResult.orchestratorLabel>,
+  cwd: <dispatchResult.projectDir>,
   task: <dispatchResult.orchestratorPrompt>
 )
 ```
 
+spawn 직후 main agent는 반환된 실제 세션 ref를 즉시 바인딩한다.
+
+```bash
+zigrix task bind-orchestrator --task-id <taskId> --agent-id <orchestratorId> --session-key <childSessionKey> --session-id <childSessionId> --json
+```
+
 오케스트레이터는 이후 워커를 `zigrix worker prepare/register/complete` 체인으로 관리한다.
 
+### `/oz` and delegation guard
+
+`/oz` skill 또는 자연어 위임 라우팅이 현재 턴을 **delegate** 로 판정했다면, 메인 에이전트는 실행자가 아니라 **router** 다.
+
+이 경우:
+- 허용: `zigrix task dispatch`, dispatch 결과 확인, `sessions_spawn`, 상태/실패 보고
+- 금지: 직접 구현, 직접 파일 수정으로 우회, direct fallback
+- dispatch/spawn 실패 시: 실패를 보고하고 중단
+
+즉, Zigrix handoff가 시작된 이후에는 메인 에이전트가 로컬 직접 작업으로 대체하지 않는다.
+
 ## 4) 워커/검증/최종 보고 체인
 
 ```bash
-# 워커 준비 (returns promptPath, specPath, metaPath, projectDir)
+# 워커 준비 (returns promptPath, specPath, metaPath, projectDir, spawnLabel)
 zigrix worker prepare --task-id <taskId> --agent-id <agentId> --description "..." --json
 
 # 워커 세션 등록
-zigrix worker register --task-id <taskId> --agent-id <agentId> --session-key <sessionKey> --run-id <runId> --json
+zigrix worker register --task-id <taskId> --agent-id <agentId> --session-key <sessionKey> --label <spawnLabel> --project-dir <projectDir> --run-id <runId> --json
 
 # 워커 완료
 zigrix worker complete --task-id <taskId> --agent-id <agentId> --session-key <sessionKey> --run-id <runId> --json
@@ -116,9 +146,9 @@ bare symbolic key(`paths.tasksDir`, `workspace.projectsBaseDir`)를 파일 경
 
 | Step | Command | Key resolved path fields |
 |------|---------|--------------------------|
-| Dispatch | `zigrix task dispatch` | `specPath`, `metaPath`, `promptPath`, `projectDir` |
+| Dispatch | `zigrix task dispatch` | `specPath`, `metaPath`, `promptPath`, `projectDir`, `orchestratorLabel` |
 | Start | `zigrix task start` | |
-| Worker prepare | `zigrix worker prepare` | `promptPath`, `specPath`, `metaPath`, `projectDir` |
+| Worker prepare | `zigrix worker prepare` | `promptPath`, `specPath`, `metaPath`, `projectDir`, `spawnLabel` |
 | Worker register | `zigrix worker register` | |
 | Worker complete | `zigrix worker complete` | |
 | Evidence collect | `zigrix evidence collect` | `evidencePath` |