zigrix 0.1.0-alpha.8 → 0.1.0-alpha.9

package/dist/orchestration/dispatch.js

@@ -1,18 +1,106 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { ROLE_HINTS } from '../agents/roles.js';
 import { appendEvent } from '../state/events.js';
-import { ensureBaseState } from '../state/paths.js';
 import { createTask, rebuildIndex, saveTask } from '../state/tasks.js';
-// ─── Constants ──────────────────────────────────────────────────────────────
-const BASELINE_REQUIRED = ['pro-zig', 'qa-zig'];
-const CANDIDATE_AGENTS = ['front-zig', 'back-zig', 'sys-zig', 'sec-zig'];
-const SELECTION_HINTS = {
-    'front-zig': 'UI / styling / client-side integration when present',
-    'back-zig': 'API / DB / server-side logic when present',
-    'sys-zig': 'architecture / infra / system-wide change when present',
-    'sec-zig': 'security-sensitive scope or risky changes when present',
-};
-// ─── Execution unit skeletons ───────────────────────────────────────────────
+import { ensureBaseState } from '../state/paths.js';
+const BASELINE_REQUIRED_ROLES = ['orchestrator', 'qa'];
+const CANDIDATE_ROLE_ORDER = ['frontend', 'backend', 'system', 'security'];
+function unique(items) {
+    return [...new Set(items)];
+}
+function listEligibleAgentsByRole(config) {
+    const byRole = new Map();
+    const participants = new Set(config.agents.orchestration.participants);
+    const excluded = new Set(config.agents.orchestration.excluded);
+    const participantMode = participants.size > 0;
+    for (const [agentId, agent] of Object.entries(config.agents.registry).sort(([a], [b]) => a.localeCompare(b))) {
+        if (!agent.enabled)
+            continue;
+        if (excluded.has(agentId))
+            continue;
+        if (participantMode && !participants.has(agentId))
+            continue;
+        const role = agent.role;
+        const row = byRole.get(role) ?? [];
+        row.push(agentId);
+        byRole.set(role, row);
+    }
+    return byRole;
+}
+function pickRequiredAgentByRole(params) {
+    if (params.role === 'orchestrator') {
+        if (params.roleAgents.length === 0) {
+            throw new Error('dispatch validation failed: no eligible agent for required role "orchestrator"');
+        }
+        if (!params.roleAgents.includes(params.orchestratorId)) {
+            throw new Error(`dispatch validation failed: configured orchestratorId '${params.orchestratorId}' is not eligible (available: ${params.roleAgents.join(', ')})`);
+        }
+        return params.orchestratorId;
+    }
+    const picked = params.roleAgents[0];
+    if (!picked) {
+        throw new Error(`dispatch validation failed: no eligible agent for required role "${params.role}"`);
+    }
+    return picked;
+}
+function resolveAgentSelection(config, scale) {
+    const scalePolicy = config.rules.scales[scale];
+    if (!scalePolicy) {
+        throw new Error(`unknown scale: ${scale}`);
+    }
+    const requiredRoles = unique([...BASELINE_REQUIRED_ROLES, ...scalePolicy.requiredRoles]);
+    const optionalRoles = unique(scalePolicy.optionalRoles.filter((role) => !requiredRoles.includes(role)));
+    const eligibleByRole = listEligibleAgentsByRole(config);
+    const requiredAgents = [];
+    const roleAgentMap = {};
+    for (const role of requiredRoles) {
+        const roleAgents = eligibleByRole.get(role) ?? [];
+        roleAgentMap[role] = [...roleAgents];
+        const picked = pickRequiredAgentByRole({
+            role,
+            roleAgents,
+            orchestratorId: config.agents.orchestration.orchestratorId,
+        });
+        requiredAgents.push(picked);
+    }
+    const candidateRoles = unique([...optionalRoles, ...CANDIDATE_ROLE_ORDER.filter((role) => !requiredRoles.includes(role))]);
+    const candidateAgents = [];
+    for (const role of candidateRoles) {
+        const roleAgents = eligibleByRole.get(role) ?? [];
+        roleAgentMap[role] = [...roleAgents];
+        for (const agentId of roleAgents) {
+            if (requiredAgents.includes(agentId))
+                continue;
+            if (!candidateAgents.includes(agentId))
+                candidateAgents.push(agentId);
+        }
+    }
+    const selectionHints = {};
+    for (const [role, agentIds] of Object.entries(roleAgentMap)) {
+        const hint = ROLE_HINTS[role] ?? 'role-based selection';
+        for (const agentId of agentIds) {
+            selectionHints[agentId] = `${hint} (role: ${role})`;
+        }
+    }
+    const qaAgentId = requiredAgents.find((agentId) => {
+        const role = config.agents.registry[agentId]?.role;
+        return role === 'qa';
+    });
+    if (!qaAgentId) {
+        throw new Error('dispatch validation failed: no selected QA agent');
+    }
+    return {
+        requiredRoles,
+        optionalRoles,
+        requiredAgents,
+        candidateAgents,
+        roleAgentMap,
+        selectionHints,
+        orchestratorId: config.agents.orchestration.orchestratorId,
+        qaAgentId,
+    };
+}
 function defaultWorkPackages(scale) {
     return [
         { id: 'WP1', key: 'planning', title: 'planning', parallel: false },
@@ -21,33 +109,33 @@ function defaultWorkPackages(scale) {
         { id: 'WP4', key: 'release', title: 'release', parallel: false },
     ];
 }
-function defaultExecutionUnits(scale) {
+function defaultExecutionUnits(scale, owners) {
     if (['normal', 'risky', 'large'].includes(scale)) {
         return [
-            { id: 'U1', title: 'spec confirmation', kind: 'planning', owner: 'pro-zig', workPackage: 'planning', dependsOn: [], parallel: false, status: 'OPEN', dod: 'scope / constraints / edge cases fixed' },
-            { id: 'U2', title: 'implementation planning / work package split', kind: 'planning', owner: 'pro-zig', workPackage: 'planning', dependsOn: ['U1'], parallel: false, status: 'OPEN', dod: 'execution units and work packages fixed' },
-            { id: 'U3', title: 'implementation slices', kind: 'implementation', owner: 'pro-zig', workPackage: 'implementation', dependsOn: ['U2'], parallel: true, status: 'OPEN', dod: 'required work packages complete' },
-            { id: 'U4', title: 'qa / regression', kind: 'verification', owner: 'qa-zig', workPackage: 'verification', dependsOn: ['U3'], parallel: false, status: 'OPEN', dod: 'qa evidence attached' },
-            { id: 'U5', title: 'report / deploy / wrap-up', kind: 'reporting', owner: 'pro-zig', workPackage: 'release', dependsOn: ['U4'], parallel: false, status: 'OPEN', dod: 'final report prepared and deployment decision recorded' },
+            { id: 'U1', title: 'spec confirmation', kind: 'planning', owner: owners.orchestratorId, workPackage: 'planning', dependsOn: [], parallel: false, status: 'OPEN', dod: 'scope / constraints / edge cases fixed' },
+            { id: 'U2', title: 'implementation planning / work package split', kind: 'planning', owner: owners.orchestratorId, workPackage: 'planning', dependsOn: ['U1'], parallel: false, status: 'OPEN', dod: 'execution units and work packages fixed' },
+            { id: 'U3', title: 'implementation slices', kind: 'implementation', owner: owners.orchestratorId, workPackage: 'implementation', dependsOn: ['U2'], parallel: true, status: 'OPEN', dod: 'required work packages complete' },
+            { id: 'U4', title: 'qa / regression', kind: 'verification', owner: owners.qaAgentId, workPackage: 'verification', dependsOn: ['U3'], parallel: false, status: 'OPEN', dod: 'qa evidence attached' },
+            { id: 'U5', title: 'report / deploy / wrap-up', kind: 'reporting', owner: owners.orchestratorId, workPackage: 'release', dependsOn: ['U4'], parallel: false, status: 'OPEN', dod: 'final report prepared and deployment decision recorded' },
         ];
     }
     return [
-        { id: 'U1', title: 'spec confirmation', kind: 'planning', owner: 'pro-zig', workPackage: 'planning', dependsOn: [], parallel: false, status: 'OPEN', dod: 'scope / constraints / edge cases fixed' },
-        { id: 'U2', title: 'implementation slice', kind: 'implementation', owner: 'pro-zig', workPackage: 'implementation', dependsOn: ['U1'], parallel: false, status: 'OPEN', dod: 'main implementation slice complete' },
-        { id: 'U3', title: 'qa / regression', kind: 'verification', owner: 'qa-zig', workPackage: 'verification', dependsOn: ['U2'], parallel: false, status: 'OPEN', dod: 'qa evidence attached' },
+        { id: 'U1', title: 'spec confirmation', kind: 'planning', owner: owners.orchestratorId, workPackage: 'planning', dependsOn: [], parallel: false, status: 'OPEN', dod: 'scope / constraints / edge cases fixed' },
+        { id: 'U2', title: 'implementation slice', kind: 'implementation', owner: owners.orchestratorId, workPackage: 'implementation', dependsOn: ['U1'], parallel: false, status: 'OPEN', dod: 'main implementation slice complete' },
+        { id: 'U3', title: 'qa / regression', kind: 'verification', owner: owners.qaAgentId, workPackage: 'verification', dependsOn: ['U2'], parallel: false, status: 'OPEN', dod: 'qa evidence attached' },
     ];
 }
-// ─── Boot prompt ────────────────────────────────────────────────────────────
-function buildBootPrompt(task) {
+function buildBootPrompt(task, options) {
     return `## Orchestration Task Boot: ${task.taskId}
 - **Title:** ${task.title}
 - **Scale:** ${task.scale}
+- **Orchestrator:** ${options.orchestratorId}
 
 ---
 
-## ⚠️ 절대 규칙: qa-zig 호출 필수 (모든 스케일)
+## ⚠️ 절대 규칙: QA 역할 워커 호출 필수
 
-**scale이 simple이든 normal이든 risky든 large든, qa-zig 워커는 반드시 호출해야 한다.**
+**이 태스크는 QA 역할(${options.qaAgentId}) 워커 완료가 필수다.**
 
 ---
 
@@ -78,24 +166,31 @@ zigrix task finalize ${task.taskId} --json
 \`\`\`
 `;
 }
-// ─── Dispatch ───────────────────────────────────────────────────────────────
-export function dispatchTask(paths, params) {
+export function dispatchTask(paths, config, params) {
     ensureBaseState(paths);
-    // Create the task
+    const selection = resolveAgentSelection(config, params.scale);
     const task = createTask(paths, {
         title: params.title,
         description: params.description,
         scale: params.scale,
-        requiredAgents: [...BASELINE_REQUIRED],
+        requiredAgents: [...selection.requiredAgents],
         projectDir: params.projectDir,
         requestedBy: params.requestedBy,
     });
-    // Enrich with orchestration metadata
-    task.selectedAgents = [...BASELINE_REQUIRED];
+    task.selectedAgents = [...selection.requiredAgents];
     task.workPackages = defaultWorkPackages(params.scale);
-    task.executionUnits = defaultExecutionUnits(params.scale);
+    task.executionUnits = defaultExecutionUnits(params.scale, {
+        orchestratorId: selection.orchestratorId,
+        qaAgentId: selection.qaAgentId,
+    });
+    task.baselineRequiredAgents = [...selection.requiredAgents];
+    task.candidateAgents = [...selection.candidateAgents];
+    task.requiredRoles = [...selection.requiredRoles];
+    task.optionalRoles = [...selection.optionalRoles];
+    task.roleAgentMap = selection.roleAgentMap;
+    task.orchestratorId = selection.orchestratorId;
+    task.qaAgentId = selection.qaAgentId;
     saveTask(paths, task);
-    // Write dispatch prompt
     const promptPath = path.join(paths.promptsDir, `${task.taskId}-dispatch.md`);
     const dispatchPrompt = [
         `## Orchestration Task: ${task.taskId}`,
@@ -103,19 +198,30 @@ export function dispatchTask(paths, params) {
         '### 기본 정보',
         `- **Title:** ${task.title}`,
         `- **Scale:** ${task.scale}`,
-        `- **Baseline Required Agents:** ${BASELINE_REQUIRED.join(', ')}`,
-        `- **Candidate Agents:** ${CANDIDATE_AGENTS.join(', ')}`,
+        `- **Orchestrator:** ${selection.orchestratorId}`,
+        `- **Baseline Required Agents:** ${selection.requiredAgents.join(', ')}`,
+        `- **Candidate Agents:** ${selection.candidateAgents.length > 0 ? selection.candidateAgents.join(', ') : '(none)'}`,
+        `- **Required Roles:** ${selection.requiredRoles.join(', ')}`,
+        `- **Optional Roles:** ${selection.optionalRoles.length > 0 ? selection.optionalRoles.join(', ') : '(none)'}`,
         params.projectDir ? `- **Project Dir:** ${params.projectDir}` : '',
         '',
         '### 요청 내용',
         params.description,
         params.constraints ? `\n### 제약사항\n${params.constraints}` : '',
         '',
+        '### 역할 매핑',
+        ...Object.entries(selection.roleAgentMap)
+            .filter(([, agentIds]) => agentIds.length > 0)
+            .map(([role, agentIds]) => `- ${role}: ${agentIds.join(', ')}`),
+        '',
         '### 선택 규칙',
-        ...Object.entries(SELECTION_HINTS).map(([k, v]) => `- ${k}: ${v}`),
+        ...Object.entries(selection.selectionHints).map(([agentId, hint]) => `- ${agentId}: ${hint}`),
     ].filter(Boolean).join('\n');
     fs.writeFileSync(promptPath, `${dispatchPrompt}\n`, 'utf8');
-    const bootPrompt = buildBootPrompt(task);
+    const orchestratorPrompt = buildBootPrompt(task, {
+        orchestratorId: selection.orchestratorId,
+        qaAgentId: selection.qaAgentId,
+    });
     appendEvent(paths.eventsFile, {
         event: 'task_dispatched',
         taskId: task.taskId,
@@ -124,8 +230,12 @@ export function dispatchTask(paths, params) {
         status: 'OPEN',
         payload: {
             scale: task.scale,
-            baselineRequiredAgents: BASELINE_REQUIRED,
-            candidateAgents: CANDIDATE_AGENTS,
+            orchestratorId: selection.orchestratorId,
+            baselineRequiredAgents: selection.requiredAgents,
+            candidateAgents: selection.candidateAgents,
+            requiredRoles: selection.requiredRoles,
+            optionalRoles: selection.optionalRoles,
+            roleAgentMap: selection.roleAgentMap,
             projectDir: params.projectDir ?? null,
         },
     });
@@ -135,12 +245,18 @@ export function dispatchTask(paths, params) {
         taskId: task.taskId,
         title: task.title,
         scale: task.scale,
-        baselineRequiredAgents: BASELINE_REQUIRED,
-        candidateAgents: CANDIDATE_AGENTS,
+        orchestratorId: selection.orchestratorId,
+        qaAgentId: selection.qaAgentId,
+        baselineRequiredAgents: selection.requiredAgents,
+        candidateAgents: selection.candidateAgents,
+        requiredRoles: selection.requiredRoles,
+        optionalRoles: selection.optionalRoles,
+        roleAgentMap: selection.roleAgentMap,
         specPath: path.join(paths.tasksDir, `${task.taskId}.md`),
         metaPath: path.join(paths.tasksDir, `${task.taskId}.meta.json`),
         promptPath,
-        proZigPrompt: bootPrompt,
+        orchestratorPrompt,
+        proZigPrompt: orchestratorPrompt,
         projectDir: params.projectDir ?? null,
     };
 }

package/dist/orchestration/evidence.js

@@ -32,6 +32,19 @@ function extractEvidence(rows) {
     }
     return { lastAssistant, toolResults: toolResults.slice(-3) };
 }
+function resolveQaAgentId(task) {
+    if (typeof task.qaAgentId === 'string' && task.qaAgentId.trim().length > 0) {
+        return task.qaAgentId;
+    }
+    const roleMap = task.roleAgentMap;
+    if (roleMap && typeof roleMap === 'object') {
+        const qaAgents = roleMap.qa;
+        if (Array.isArray(qaAgents) && qaAgents.length > 0) {
+            return String(qaAgents[0]);
+        }
+    }
+    return 'qa-zig';
+}
 export function collectEvidence(paths, params) {
     ensureBaseState(paths);
     const task = loadTask(paths, params.taskId);
@@ -83,9 +96,10 @@ export function mergeEvidence(paths, params) {
     const presentAgents = [...new Set(items.map((item) => String(item.agentId)))].sort();
     const requiredAgents = [...(params.requiredAgents?.length ? params.requiredAgents : resolveRequiredAgents(task))];
     const missingAgents = requiredAgents.filter((agentId) => !presentAgents.includes(agentId));
-    const qaPresent = presentAgents.includes('qa-zig');
+    const qaAgentId = resolveQaAgentId(task);
+    const qaPresent = presentAgents.includes(qaAgentId);
     const complete = missingAgents.length === 0 && (!(params.requireQa ?? false) || qaPresent);
-    const merged = { ts: nowIso(), taskId: params.taskId, requiredAgents, presentAgents, missingAgents, qaPresent, complete, items };
+    const merged = { ts: nowIso(), taskId: params.taskId, requiredAgents, presentAgents, missingAgents, qaAgentId, qaPresent, complete, items };
     const outPath = path.join(taskDir, '_merged.json');
     fs.writeFileSync(outPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
     appendEvent(paths.eventsFile, {
@@ -93,5 +107,5 @@ export function mergeEvidence(paths, params) {
         payload: { requiredAgents, missingAgents, complete, mergedPath: outPath, qaPresent },
     });
     rebuildIndex(paths);
-    return { ok: true, taskId: params.taskId, complete, missingAgents, mergedPath: outPath };
+    return { ok: true, taskId: params.taskId, complete, missingAgents, qaAgentId, qaPresent, mergedPath: outPath };
 }

package/dist/orchestration/finalize.js

@@ -15,8 +15,8 @@ function autoCloseCompletedUnits(task) {
         if (s.status === 'done')
             doneAgents.add(agentId);
     }
-    // pro-zig is always "done" at finalize time
-    doneAgents.add('pro-zig');
+    // orchestrator is always "done" at finalize time
+    doneAgents.add(task.orchestratorId ?? 'pro-zig');
     let changed = false;
     for (const unit of units) {
         if (['OPEN', 'IN_PROGRESS'].includes(unit.status.toUpperCase()) && doneAgents.has(unit.owner)) {

package/dist/orchestration/report.js

@@ -44,7 +44,12 @@ function collectRisks(merged) {
 }
 function qaLine(merged) {
     const present = new Set(Array.isArray(merged.presentAgents) ? merged.presentAgents.map(String) : []);
-    return present.has('qa-zig') ? '- qa-zig evidence 존재, QA 수행됨' : '- qa-zig evidence 없음 또는 별도 QA 미실행';
+    const qaAgentId = typeof merged.qaAgentId === 'string' && merged.qaAgentId.trim().length > 0
+        ? merged.qaAgentId
+        : 'qa-zig';
+    return present.has(qaAgentId)
+        ? `- ${qaAgentId} evidence 존재, QA 수행됨`
+        : `- ${qaAgentId} evidence 없음 또는 별도 QA 미실행`;
 }
 export function renderReport(paths, params) {
     const task = loadTask(paths, params.taskId);

package/dist/orchestration/worker.d.ts

@@ -1,6 +1,6 @@
 import { type ZigrixPaths } from '../state/paths.js';
 import { type ZigrixTask } from '../state/tasks.js';
-export declare const DEFAULT_REQUIRED_AGENTS: string[];
+export declare const DEFAULT_REQUIRED_AGENTS: readonly ["orchestrator", "qa"];
 export declare function resolveRequiredAgents(task: Partial<ZigrixTask> & Record<string, unknown>): string[];
 export declare function prepareWorker(paths: ZigrixPaths, params: {
     taskId: string;

package/dist/orchestration/worker.js

@@ -3,7 +3,22 @@ import path from 'node:path';
 import { appendEvent } from '../state/events.js';
 import { ensureBaseState } from '../state/paths.js';
 import { loadTask, saveTask } from '../state/tasks.js';
-export const DEFAULT_REQUIRED_AGENTS = ['pro-zig', 'qa-zig'];
+export const DEFAULT_REQUIRED_AGENTS = ['orchestrator', 'qa'];
+const DEFAULT_ORCHESTRATOR_ID = 'pro-zig';
+const DEFAULT_QA_AGENT_ID = 'qa-zig';
+function resolveDefaultRequiredAgents(task) {
+    const orchestratorId = typeof task.orchestratorId === 'string' && task.orchestratorId.trim().length > 0
+        ? task.orchestratorId
+        : DEFAULT_ORCHESTRATOR_ID;
+    const qaAgentId = typeof task.qaAgentId === 'string' && task.qaAgentId.trim().length > 0
+        ? task.qaAgentId
+        : DEFAULT_QA_AGENT_ID;
+    const resolvedByRole = {
+        orchestrator: orchestratorId,
+        qa: qaAgentId,
+    };
+    return [...new Set(DEFAULT_REQUIRED_AGENTS.map((role) => resolvedByRole[role]))];
+}
 export function resolveRequiredAgents(task) {
     for (const key of ['requiredAgents', 'selectedAgents', 'baselineRequiredAgents']) {
         const value = task[key];
@@ -15,7 +30,7 @@ export function resolveRequiredAgents(task) {
     if (workers && typeof workers === 'object' && Object.keys(workers).length > 0) {
         return Object.keys(workers).sort();
     }
-    return [...DEFAULT_REQUIRED_AGENTS];
+    return resolveDefaultRequiredAgents(task);
 }
 function renderPrompt(params) {
     const sections = [

package/dist/rules/templates.js

@@ -1,3 +1,4 @@
+import { STANDARD_AGENT_ROLES } from '../agents/roles.js';
 export const TEMPLATE_PLACEHOLDERS = {
     workerPrompt: ['taskId', 'title', 'scale', 'agentId', 'description', 'constraints', 'requiredRoles', 'workPackage', 'unitId'],
     finalReport: ['taskId', 'title', 'scale', 'status', 'summary', 'missingAgents'],
@@ -36,12 +37,8 @@ export function validateTemplate(kind, body) {
 }
 export function validateRules(config) {
     const knownRoles = new Set(Object.values(config.agents.registry).map((agent) => agent.role));
-    knownRoles.add('orchestrator');
-    knownRoles.add('qa');
-    knownRoles.add('frontend');
-    knownRoles.add('backend');
-    knownRoles.add('security');
-    knownRoles.add('infra');
+    for (const role of STANDARD_AGENT_ROLES)
+        knownRoles.add(role);
     const invalidRoles = new Set();
     for (const scale of Object.values(config.rules.scales)) {
         for (const role of [...scale.requiredRoles, ...scale.optionalRoles]) {

package/dist/state/tasks.d.ts

@@ -31,6 +31,13 @@ export type ZigrixTask = {
     selectedAgents?: string[];
     workPackages?: WorkPackage[];
     executionUnits?: ExecutionUnit[];
+    baselineRequiredAgents?: string[];
+    candidateAgents?: string[];
+    requiredRoles?: string[];
+    optionalRoles?: string[];
+    roleAgentMap?: Record<string, string[]>;
+    orchestratorId?: string;
+    qaAgentId?: string;
     orchestratorSessionKey?: string;
     orchestratorSessionId?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigrix",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "type": "module",
   "description": "Multi-project parallel task orchestration CLI for agent-assisted development",
   "license": "Apache-2.0",

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

@@ -0,0 +1,118 @@
+---
+name: zigrix-main-agent-guide
+version: 0.1.0
+description: Main-agent guide for using Zigrix CLI (task issuance, orchestrator spawn, dashboard, and Python-script-to-CLI migration).
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+---
+
+# Zigrix Main Agent Guide
+
+메인 에이전트가 Zigrix를 사용할 때의 표준 흐름.
+
+## 1) 기본 명령
+
+```bash
+# 초기 설정
+zigrix onboard --yes --json
+
+# 환경/설정 점검
+zigrix doctor
+zigrix config validate --json
+zigrix agent list --json
+
+# 대시보드 실행
+zigrix dashboard --port 5173
+```
+
+## 2) 태스크 발급 흐름 (권장)
+
+`task create`보다 `task dispatch`를 우선 사용한다.
+
+```bash
+zigrix task dispatch \
+  --title "Implement X" \
+  --description "..." \
+  --scale normal \
+  --project-dir /path/to/project \
+  --json
+```
+
+디스패치 결과에서 확인할 핵심 필드:
+- `taskId`
+- `orchestratorId`
+- `qaAgentId`
+- `baselineRequiredAgents`
+- `candidateAgents`
+- `orchestratorPrompt` (`proZigPrompt` 호환 별칭 포함)
+
+## 3) 오케스트레이터 spawn 패턴
+
+디스패치 응답의 `orchestratorPrompt`를 오케스트레이터 에이전트에게 전달한다.
+
+```text
+sessions_spawn(
+  agentId: <orchestratorId>,
+  task: <dispatchResult.orchestratorPrompt>
+)
+```
+
+오케스트레이터는 이후 워커를 `zigrix worker prepare/register/complete` 체인으로 관리한다.
+
+## 4) 워커/검증/최종 보고 체인
+
+```bash
+# 워커 준비
+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 complete --task-id <taskId> --agent-id <agentId> --session-key <sessionKey> --run-id <runId> --json
+
+# evidence 수집/머지
+zigrix evidence collect --task-id <taskId> --agent-id <agentId> --summary "..." --json
+zigrix evidence merge --task-id <taskId> --require-qa --json
+
+# 최종화
+zigrix task finalize <taskId> --auto-report --json
+```
+
+## 5) 대시보드 사용 포인트
+
+대시보드에서 확인:
+- Task 상태 (OPEN → IN_PROGRESS → REPORTED)
+- 워커 세션 매핑
+- 이벤트 로그
+- Conversation/증적 추적
+
+문제 상황 디버깅 순서:
+1. `zigrix task status <taskId> --json`
+2. `zigrix task events <taskId> --json`
+3. `zigrix evidence merge --task-id <taskId> --require-qa --json`
+
+## 6) Python 스크립트 체인 → Zigrix CLI 전환 가이드
+
+기존(레거시 Python):
+- `dev_dispatch.py`
+- `dev_start.py`
+- `orch_prepare_worker.py`
+- `orch_register_worker.py`
+- `orch_complete_worker.py`
+- `dev_finalize.py`
+
+신규(권장 Zigrix CLI):
+- `zigrix task dispatch`
+- `zigrix task start`
+- `zigrix worker prepare`
+- `zigrix worker register`
+- `zigrix worker complete`
+- `zigrix task finalize`
+
+전환 원칙:
+- 신규 자동화는 CLI 우선
+- Python 스크립트는 호환/과도기용
+- JSON 출력(`--json`)을 기본으로 파이프라인에서 파싱