zigrix 0.2.0 → 0.2.1

package/dist/orchestration/prompt-compose.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inferStandardAgentRole, normalizeAgentRole, } from '../agents/roles.js';
+const ROLE_RULE_FILE = {
+    orchestrator: 'orchestrator-agent.md',
+    qa: 'qa-agent.md',
+    security: 'security-agent.md',
+    frontend: 'frontend-agent.md',
+    backend: 'backend-agent.md',
+    system: 'system-agent.md',
+};
+const WORKER_COMMON_RULE_FILE = 'worker-common.md';
+function bundledRulesDir() {
+    return path.resolve(fileURLToPath(new URL('../../rules/defaults', import.meta.url)));
+}
+function firstReadableRulePath(paths, fileName) {
+    const candidates = [
+        path.join(paths.rulesDir, fileName),
+        path.join(bundledRulesDir(), fileName),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function loadRuleText(paths, fileName) {
+    const resolved = firstReadableRulePath(paths, fileName);
+    if (!resolved) {
+        throw new Error(`required Zigrix rule file not found: ${fileName}`);
+    }
+    return fs.readFileSync(resolved, 'utf8').trim();
+}
+function compactBlock(text) {
+    return text.replace(/\r\n/g, '\n').trim();
+}
+function joinPromptBlocks(...blocks) {
+    return blocks
+        .map((block) => (typeof block === 'string' ? compactBlock(block) : ''))
+        .filter((block) => block.length > 0)
+        .join('\n\n---\n\n');
+}
+function renderRoleMap(task) {
+    const entries = Object.entries(task.roleAgentMap ?? {}).filter(([, ids]) => Array.isArray(ids) && ids.length > 0);
+    if (entries.length === 0)
+        return '- (none)';
+    return entries.map(([role, ids]) => `- ${role}: ${ids.join(', ')}`).join('\n');
+}
+function resolveTaskRole(task, agentId) {
+    if (typeof task.orchestratorId === 'string' && task.orchestratorId === agentId)
+        return 'orchestrator';
+    if (typeof task.qaAgentId === 'string' && task.qaAgentId === agentId)
+        return 'qa';
+    const roleMap = task.roleAgentMap;
+    if (roleMap && typeof roleMap === 'object') {
+        for (const [role, agentIds] of Object.entries(roleMap)) {
+            if (!Array.isArray(agentIds))
+                continue;
+            if (agentIds.includes(agentId)) {
+                const normalized = normalizeAgentRole(role);
+                if (normalized)
+                    return normalized;
+            }
+        }
+    }
+    return null;
+}
+export function resolveAgentRole(config, task, agentId) {
+    const fromTask = resolveTaskRole(task, agentId);
+    if (fromTask)
+        return fromTask;
+    const fromRegistry = config.agents.registry[agentId]?.role;
+    if (typeof fromRegistry === 'string') {
+        const normalized = normalizeAgentRole(fromRegistry);
+        if (normalized)
+            return normalized;
+    }
+    return inferStandardAgentRole({ agentId, theme: null });
+}
+export function buildSpawnLabel(taskId, agentId) {
+    return `[${agentId}] ${taskId}`;
+}
+export function composeOrchestratorPrompt(params) {
+    const roleRule = loadRuleText(params.paths, ROLE_RULE_FILE.orchestrator);
+    const overlay = [
+        `## Runtime Task Overlay: ${params.task.taskId}`,
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| taskId | ${params.task.taskId} |`,
+        `| title | ${params.task.title} |`,
+        `| scale | ${params.task.scale} |`,
+        `| orchestratorId | ${params.orchestratorId} |`,
+        `| qaAgentId | ${params.qaAgentId} |`,
+        `| specPath | ${params.specPath} |`,
+        `| metaPath | ${params.metaPath} |`,
+        `| promptPath | ${params.promptPath} |`,
+        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
+        '',
+        '### Authority Boundary',
+        '- 이 prompt는 Zigrix orchestrator role rule + task overlay를 합성한 canonical instruction이다.',
+        '- 메인 전용 skill (`zigrix-main-agent-guide`)이나 일반 OpenClaw skill discovery를 근거 규칙으로 삼지 않는다.',
+        '- 실제 runtime agentId는 아래 role mapping과 task metadata를 따른다.',
+        '',
+        '### Original Request',
+        params.task.description,
+        params.constraints ? `\n### Constraints\n${params.constraints}` : '',
+        '',
+        '### Runtime Role Mapping',
+        renderRoleMap(params.task),
+        '',
+        '### Required CLI Chain',
+        '1. `zigrix task start <taskId> --json`',
+        '2. `zigrix task status <taskId> --json`',
+        '3. 필요 워커마다 `zigrix worker prepare → sessions_spawn → zigrix worker register → zigrix worker complete`',
+        '4. evidence 수집/머지 확인',
+        '5. `zigrix task finalize <taskId> --json`',
+        '',
+        '### Worker Dispatch Contract',
+        '- worker spawn 전에 반드시 `zigrix worker prepare --task-id <taskId> --agent-id <workerId> --description "..." --json` 를 호출해 worker prompt / projectDir / spawnLabel을 확보한다.',
+        '- worker spawn 시 `agentId`, `label`, `cwd`, `task` 를 모두 명시한다.',
+        '- spawn 후에는 prepare 응답의 `spawnLabel` / `projectDir` 와 실제 `sessionKey` / `sessionId` 를 함께 `zigrix worker register` 에 전달한다.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return joinPromptBlocks(roleRule, overlay);
+}
+export function composeWorkerPrompt(params) {
+    const role = resolveAgentRole(params.config, params.task, params.agentId);
+    const roleRule = loadRuleText(params.paths, ROLE_RULE_FILE[role]);
+    const baseRule = role === 'orchestrator' ? '' : loadRuleText(params.paths, WORKER_COMMON_RULE_FILE);
+    const overlay = [
+        `## Runtime Worker Overlay: ${params.task.taskId}`,
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| taskId | ${params.task.taskId} |`,
+        `| title | ${params.task.title} |`,
+        `| scale | ${params.task.scale} |`,
+        `| agentId | ${params.agentId} |`,
+        `| role | ${role} |`,
+        `| specPath | ${params.specPath} |`,
+        `| metaPath | ${params.metaPath} |`,
+        `| promptPath | ${params.promptPath} |`,
+        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
+        '',
+        '### Authority Boundary',
+        '- 이 prompt는 Zigrix role rule + task overlay를 합성한 canonical worker instruction이다.',
+        '- 메인 전용 skill (`zigrix-main-agent-guide`)이나 일반 OpenClaw skill discovery를 근거 규칙으로 삼지 않는다.',
+        '- role rule 안의 예시 agent 이름보다 현재 overlay의 `agentId` / `role` / `projectDir` 를 우선 적용한다.',
+        '',
+        '### Assignment',
+        params.description,
+        params.constraints ? `\n### Constraints\n${params.constraints}` : '',
+        params.dod ? `\n### Definition of Done\n${params.dod}` : '',
+        params.unitId || params.workPackage
+            ? `\n### Execution Context\n- unitId: ${params.unitId ?? 'N/A'}\n- workPackage: ${params.workPackage ?? 'N/A'}`
+            : '',
+        '',
+        '### Completion Chain',
+        `- evidence collect: \`zigrix evidence collect --task-id ${params.task.taskId} --agent-id ${params.agentId} --summary "<result summary>"\``,
+        '- 결과 보고에는 taskId / sessionKey / runId / evidence / risks 를 포함한다.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return {
+        role,
+        prompt: joinPromptBlocks(baseRule, roleRule, overlay),
+    };
+}

package/dist/orchestration/worker.d.ts

@@ -1,8 +1,9 @@
+import type { ZigrixConfig } from '../config/schema.js';
 import { type ZigrixPaths } from '../state/paths.js';
 import { type ZigrixTask } from '../state/tasks.js';
 export declare const DEFAULT_REQUIRED_ROLES: readonly ["orchestrator", "qa"];
 export declare function resolveRequiredAgents(task: Partial<ZigrixTask> & Record<string, unknown>): string[];
-export declare function prepareWorker(paths: ZigrixPaths, params: {
+export declare function prepareWorker(paths: ZigrixPaths, config: ZigrixConfig, params: {
     taskId: string;
     agentId: string;
     description: string;
@@ -21,6 +22,8 @@ export declare function registerWorker(paths: ZigrixPaths, params: {
     unitId?: string;
     workPackage?: string;
     reason?: string;
+    label?: string;
+    projectDir?: string;
 }): Record<string, unknown> | null;
 export declare function completeWorker(paths: ZigrixPaths, params: {
     taskId: string;

package/dist/orchestration/worker.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { appendEvent } from '../state/events.js';
 import { ensureBaseState } from '../state/paths.js';
 import { loadTask, resolveTaskPaths, saveTask } from '../state/tasks.js';
+import { buildSpawnLabel, composeWorkerPrompt } from './prompt-compose.js';
 export const DEFAULT_REQUIRED_ROLES = ['orchestrator', 'qa'];
 function firstNonEmpty(...values) {
     for (const value of values) {
@@ -47,45 +48,51 @@ export function resolveRequiredAgents(task) {
     }
     return resolveDefaultRequiredAgents(task);
 }
-function renderPrompt(params) {
-    const sections = [
-        `## Worker Assignment: ${params.task.taskId}`,
-        '',
-        '| Field | Value |',
-        '|---|---|',
-        `| taskId | ${params.task.taskId} |`,
-        `| title | ${params.task.title} |`,
-        `| scale | ${params.task.scale} |`,
-        `| role | ${params.agentId} |`,
-        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
-        '',
-        '### Assignment',
-        params.description,
-    ];
-    if (params.constraints)
-        sections.push('', '### Constraints', params.constraints);
-    if (params.dod)
-        sections.push('', '### Definition of Done', params.dod);
-    if (params.unitId || params.workPackage) {
-        sections.push('', '### Execution Context', `- unitId: ${params.unitId ?? 'N/A'}`, `- workPackage: ${params.workPackage ?? 'N/A'}`);
-    }
-    sections.push('', '### Completion', '작업 완료 후 다음 순서를 반드시 따르라:', '', '1. **증적(evidence) 수집** — 작업 결과 증적을 먼저 기록한다:', '   ```bash', `   zigrix evidence collect --task-id ${params.task.taskId} --agent-id ${params.agentId} --summary "<작업 결과 요약>"`, '   ```', '2. **결과 보고** — 증적 수집 완료 후 결과와 근거를 명확히 보고하라.', '', '⚠️ 증적 없이 완료하면 finalize에서 incomplete 판정된다.');
-    return sections.join('\n');
+function normalizePathValue(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return null;
+    return path.resolve(value.trim());
+}
+function parseSessionKey(sessionKey) {
+    const matched = sessionKey.match(/^agent:([^:]+):subagent:([^:\s]+)$/);
+    if (!matched)
+        return null;
+    return { agentId: matched[1], sessionId: matched[2] };
 }
-export function prepareWorker(paths, params) {
+export function prepareWorker(paths, config, params) {
     ensureBaseState(paths);
     const task = loadTask(paths, params.taskId);
     if (!task)
         return null;
-    const projectDir = params.projectDir ?? task.projectDir;
-    const prompt = renderPrompt({ task, ...params, projectDir });
+    const taskPaths = resolveTaskPaths(paths, params.taskId);
     const promptPath = path.join(paths.promptsDir, `${params.taskId}-${params.agentId}.md`);
-    fs.writeFileSync(promptPath, `${prompt}\n`, 'utf8');
+    const projectDir = normalizePathValue(params.projectDir ?? task.projectDir ?? null);
+    const spawnLabel = buildSpawnLabel(params.taskId, params.agentId);
+    const composed = composeWorkerPrompt({
+        paths,
+        config,
+        task,
+        agentId: params.agentId,
+        description: params.description,
+        constraints: params.constraints,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        dod: params.dod,
+        projectDir,
+        promptPath,
+        specPath: taskPaths.specPath,
+        metaPath: taskPaths.metaPath,
+    });
+    fs.writeFileSync(promptPath, `${composed.prompt}\n`, 'utf8');
     task.workerSessions[params.agentId] = {
+        ...(task.workerSessions[params.agentId] ?? {}),
         status: 'prepared',
+        role: composed.role,
         unitId: params.unitId,
         workPackage: params.workPackage,
         promptPath,
+        expectedLabel: spawnLabel,
+        projectDir,
     };
     const required = task.requiredAgents.length > 0 ? task.requiredAgents : resolveRequiredAgents(task);
     if (!required.includes(params.agentId))
@@ -101,36 +108,60 @@ export function prepareWorker(paths, params) {
         status: 'IN_PROGRESS',
         unitId: params.unitId,
         workPackage: params.workPackage,
-        payload: { agentId: params.agentId, description: params.description, constraints: params.constraints ?? '', dod: params.dod ?? '', promptPath },
+        payload: {
+            agentId: params.agentId,
+            role: composed.role,
+            description: params.description,
+            constraints: params.constraints ?? '',
+            dod: params.dod ?? '',
+            promptPath,
+            spawnLabel,
+            projectDir,
+        },
     });
     return {
         ok: true,
         taskId: params.taskId,
         agentId: params.agentId,
+        role: composed.role,
         promptPath,
-        prompt,
+        prompt: composed.prompt,
         unitId: params.unitId,
         workPackage: params.workPackage,
-        projectDir: projectDir ?? null,
-        ...resolveTaskPaths(paths, params.taskId),
+        projectDir,
+        spawnLabel,
+        ...taskPaths,
     };
 }
-/**
- * Extract sessionId from a sessionKey of the form `agent:<agentId>:subagent:<sessionId>`.
- * Returns null if the sessionKey does not match the expected pattern.
- */
-function parseSessionIdFromKey(sessionKey) {
-    const matched = sessionKey.match(/^agent:[^:]+:subagent:([^:\s]+)$/);
-    return matched?.[1] ?? null;
-}
 export function registerWorker(paths, params) {
     const task = loadTask(paths, params.taskId);
     if (!task)
         return null;
-    // Resolve sessionId: use provided value, or fall back to parsing it from sessionKey
-    const resolvedSessionId = params.sessionId || parseSessionIdFromKey(params.sessionKey) || null;
+    const parsedKey = parseSessionKey(params.sessionKey);
+    if (parsedKey && parsedKey.agentId !== params.agentId) {
+        throw new Error(`worker register validation failed: sessionKey belongs to '${parsedKey.agentId}', expected '${params.agentId}'`);
+    }
+    const previous = task.workerSessions[params.agentId] ?? {};
+    const expectedLabel = firstNonEmpty(previous.expectedLabel) ?? buildSpawnLabel(params.taskId, params.agentId);
+    const providedLabel = firstNonEmpty(params.label);
+    if (!providedLabel) {
+        throw new Error('worker register validation failed: label is required (use spawnLabel from worker prepare).');
+    }
+    if (providedLabel !== expectedLabel) {
+        throw new Error(`worker register validation failed: label mismatch (expected '${expectedLabel}', got '${providedLabel}')`);
+    }
+    const expectedProjectDir = normalizePathValue(firstNonEmpty(previous.projectDir, task.projectDir));
+    const providedProjectDir = normalizePathValue(params.projectDir);
+    if (expectedProjectDir && !providedProjectDir) {
+        throw new Error('worker register validation failed: projectDir is required for this task.');
+    }
+    if (expectedProjectDir && providedProjectDir && expectedProjectDir !== providedProjectDir) {
+        throw new Error(`worker register validation failed: projectDir mismatch (expected '${expectedProjectDir}', got '${providedProjectDir}')`);
+    }
+    const resolvedSessionId = params.sessionId || parsedKey?.sessionId || null;
+    const resolvedProjectDir = providedProjectDir ?? expectedProjectDir;
     task.workerSessions[params.agentId] = {
-        ...(task.workerSessions[params.agentId] ?? {}),
+        ...previous,
         status: 'dispatched',
         sessionKey: params.sessionKey,
         runId: params.runId ?? '',
@@ -138,6 +169,9 @@ export function registerWorker(paths, params) {
         unitId: params.unitId,
         workPackage: params.workPackage,
         reason: params.reason ?? '',
+        label: providedLabel,
+        expectedLabel,
+        projectDir: resolvedProjectDir,
     };
     const required = task.requiredAgents.length > 0 ? task.requiredAgents : resolveRequiredAgents(task);
     if (!required.includes(params.agentId))
@@ -145,11 +179,37 @@ export function registerWorker(paths, params) {
     task.requiredAgents = required;
     saveTask(paths, task);
     appendEvent(paths.eventsFile, {
-        event: 'worker_dispatched', taskId: params.taskId, phase: 'execution', actor: 'zigrix', targetAgent: params.agentId, status: 'IN_PROGRESS',
-        sessionKey: params.sessionKey, sessionId: resolvedSessionId, unitId: params.unitId, workPackage: params.workPackage,
-        payload: { agentId: params.agentId, runId: params.runId ?? '', reason: params.reason ?? '' },
+        event: 'worker_dispatched',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: 'zigrix',
+        targetAgent: params.agentId,
+        status: 'IN_PROGRESS',
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        payload: {
+            agentId: params.agentId,
+            runId: params.runId ?? '',
+            reason: params.reason ?? '',
+            label: providedLabel,
+            projectDir: resolvedProjectDir,
+        },
     });
-    return { ok: true, taskId: params.taskId, agentId: params.agentId, sessionKey: params.sessionKey, runId: params.runId ?? '', sessionId: resolvedSessionId, unitId: params.unitId, workPackage: params.workPackage, status: 'dispatched' };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+        runId: params.runId ?? '',
+        sessionId: resolvedSessionId,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        label: providedLabel,
+        projectDir: resolvedProjectDir,
+        status: 'dispatched',
+    };
 }
 export function completeWorker(paths, params) {
     const task = loadTask(paths, params.taskId);
@@ -167,16 +227,36 @@ export function completeWorker(paths, params) {
     };
     saveTask(paths, task);
     appendEvent(paths.eventsFile, {
-        event: 'worker_done', taskId: params.taskId, phase: 'execution', actor: params.agentId, targetAgent: params.agentId,
-        status: (params.result ?? 'done') === 'blocked' ? 'BLOCKED' : 'IN_PROGRESS', sessionKey: params.sessionKey, sessionId: params.sessionId ?? null,
-        unitId: params.unitId ?? prev.unitId, workPackage: params.workPackage ?? prev.workPackage,
+        event: 'worker_done',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: params.agentId,
+        targetAgent: params.agentId,
+        status: (params.result ?? 'done') === 'blocked' ? 'BLOCKED' : 'IN_PROGRESS',
+        sessionKey: params.sessionKey,
+        sessionId: params.sessionId ?? null,
+        unitId: params.unitId ?? prev.unitId,
+        workPackage: params.workPackage ?? prev.workPackage,
         payload: { result: params.result ?? 'done', runId: params.runId },
     });
     const evidenceDir = path.join(paths.evidenceDir, params.taskId);
     const presentAgents = fs.existsSync(evidenceDir)
-        ? fs.readdirSync(evidenceDir).filter((file) => file.endsWith('.json') && file !== '_merged.json').map((file) => path.basename(file, '.json')).sort()
+        ? fs
+            .readdirSync(evidenceDir)
+            .filter((file) => file.endsWith('.json') && file !== '_merged.json')
+            .map((file) => path.basename(file, '.json'))
+            .sort()
         : [];
     const required = resolveRequiredAgents(task);
     const missingAgents = required.filter((agentId) => !presentAgents.includes(agentId));
-    return { ok: true, taskId: params.taskId, agentId: params.agentId, result: params.result ?? 'done', requiredAgents: required, presentEvidenceAgents: presentAgents, missingEvidenceAgents: missingAgents, allEvidenceCollected: missingAgents.length === 0 };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        result: params.result ?? 'done',
+        requiredAgents: required,
+        presentEvidenceAgents: presentAgents,
+        missingEvidenceAgents: missingAgents,
+        allEvidenceCollected: missingAgents.length === 0,
+    };
 }

package/dist/state/tasks.d.ts

@@ -91,6 +91,12 @@ export declare function createTask(paths: ZigrixPaths, params: {
     prefix?: string;
 }): ZigrixTask;
 export declare function updateTaskStatus(paths: ZigrixPaths, taskId: string, status: string): ZigrixTask | null;
+export declare function bindOrchestratorSession(paths: ZigrixPaths, params: {
+    taskId: string;
+    agentId: string;
+    sessionKey: string;
+    sessionId?: string;
+}): Record<string, unknown> | null;
 export declare function recordTaskProgress(paths: ZigrixPaths, params: {
     taskId: string;
     actor: string;

package/dist/state/tasks.js

@@ -170,6 +170,45 @@ export function updateTaskStatus(paths, taskId, status) {
     rebuildIndex(paths);
     return task;
 }
+export function bindOrchestratorSession(paths, params) {
+    const task = loadTask(paths, params.taskId);
+    if (!task)
+        return null;
+    const parsed = parseAgentSubagentSessionKey(params.sessionKey);
+    if (parsed && parsed.agentId !== params.agentId) {
+        throw new Error(`orchestrator bind validation failed: sessionKey belongs to '${parsed.agentId}', expected '${params.agentId}'`);
+    }
+    const resolvedSessionId = params.sessionId ?? parsed?.sessionId ?? null;
+    task.orchestratorId = params.agentId;
+    task.orchestratorSessionKey = params.sessionKey;
+    if (resolvedSessionId) {
+        task.orchestratorSessionId = resolvedSessionId;
+    }
+    else {
+        delete task.orchestratorSessionId;
+    }
+    saveTask(paths, task);
+    appendEvent(paths.eventsFile, {
+        event: 'orchestrator_bound',
+        taskId: params.taskId,
+        phase: 'dispatch',
+        actor: 'zigrix',
+        targetAgent: params.agentId,
+        status: task.status,
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        payload: { agentId: params.agentId },
+    });
+    rebuildIndex(paths);
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        status: task.status,
+    };
+}
 export function recordTaskProgress(paths, params) {
     const task = loadTask(paths, params.taskId);
     if (!task)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigrix",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Multi-project parallel task orchestration CLI for agent-assisted development",
   "license": "Apache-2.0",
@@ -70,11 +70,11 @@
     "@inquirer/prompts": "^8.3.2",
     "bcryptjs": "^2.4.3",
     "commander": "^14.0.0",
-    "next": "^15.2.3",
+    "next": "^15.5.15",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
-    "yaml": "^2.8.1",
+    "yaml": "^2.8.3",
     "zod": "^4.1.5"
   },
   "devDependencies": {

package/rules/defaults/orchestrator-agent.md

@@ -1,6 +1,7 @@
 # orchestrator-agent Rules (Orchestrator)
 
 > orchestrator-agent는 오케스트레이터로서 worker-common이 아닌 자체 규칙을 따른다.
+> 이 문서 안의 `frontend-agent`/`backend-agent`/`qa-agent`/`orchestrator-agent` 표기는 **role label 예시**다. 실제 runtime agentId는 dispatch overlay의 `roleAgentMap`, `orchestratorId`, `qaAgentId`를 따른다.
 
 ## 1) Mission
 - 사용자 개발 요청을 `simple|normal|risky|large`로 분류하고,
@@ -23,7 +24,8 @@
 11. **오케스트레이션 파이프라인 필수 경유:**
     - 작업은 `zigrix task dispatch`로 등록한 상태에서만 수신
     - 오케스트레이션 미등록(taskId/spec 미존재) 작업은 수행 거부
-12. **CLI 체인 워크플로우 (필수):**
+12. **메인 전용 스킬 사용 금지:** `zigrix-main-agent-guide`는 main agent 전용이며, orchestrator runtime 세션은 dispatch prompt + Zigrix role rule만 canonical instruction으로 사용한다.
+13. **CLI 체인 워크플로우 (필수):**
     - orchestrator-agent의 task prompt(boot prompt)는 **`zigrix task start` 실행 지시**만 포함한다.
     - **태스크 메타 및 dispatch prompt가 태스크 브리핑이자 작업 지시서**이다.
     - 모든 상태 추적은 CLI 체인을 통해 자동 기록된다.
@@ -33,7 +35,7 @@
       1. **착수:** `zigrix task start <taskId> --json`
       2. **태스크 경로 확인:** `zigrix task status <taskId> --json` → `specPath`, `metaPath`, `projectDir` 확보
       3. **워커 prompt 생성:** `zigrix worker prepare --task-id <taskId> --agent-id <workerId> --description "..." --json` → `promptPath`, `specPath`, `metaPath`, `projectDir`를 확인하고 sessions_spawn에 prompt를 전달
-      4. **워커 등록:** `zigrix worker register --task-id <taskId> --agent-id <workerId> --session-key <key> --run-id <rid>` → 다음 행동 출력
+      4. **워커 등록:** `zigrix worker register --task-id <taskId> --agent-id <workerId> --session-key <key> --label <spawnLabel> --project-dir <projectDir> --run-id <rid>` → 다음 행동 출력
       5. **워커 완료:** `zigrix worker complete --task-id <taskId> --agent-id <workerId> --session-key <key> --run-id <rid>` → 완료 여부 + 다음 행동 출력
       6. **최종 보고:** `zigrix task finalize <taskId> --auto-report`
 13. task는 크게 유지하고 내부 실행은 `workPackages[]` + `executionUnits[]`로 세분화한다.

package/rules/defaults/worker-common.md

@@ -1,5 +1,7 @@
 # Worker Common Rules (front/back/sys/sec/qa)
 
+> 이 문서 안의 역할명은 role label 기준이다. 실제 runtime agentId / projectDir / task context는 worker overlay prompt를 우선 따른다.
+
 ## 1) Mission
 - orchestrator-agent가 분배한 task를 역할 범위 내에서 수행하고,
 - 결과를 검증 가능한 증적과 함께 반환한다.
@@ -13,6 +15,7 @@
 6. **모든 문제는 근본적인 해결을 원칙으로 한다. 임시방편(workaround) 금지.**
 7. **오케스트레이션 필수 (owner 고정, 2026-03-04):** 오케스트레이션에 등록되지 않은 작업은 수행 거부. 확인은 `zigrix task status <taskId> --json`의 성공 여부와 반환된 `specPath`/`metaPath`를 기준으로 한다. taskId가 있더라도 조회가 실패하면 orchestrator-agent에 확인 요청.
 8. **CLI 체인 정합:** 워커 lifecycle 기록(`worker_dispatched`/`worker_done`/`worker_skipped`)은 orchestrator-agent가 `zigrix worker prepare → zigrix worker register → zigrix worker complete` 체인으로 처리한다.
+9. **메인 전용 스킬 사용 금지:** `zigrix-main-agent-guide`는 main agent 전용이며, worker runtime 세션은 worker overlay prompt + Zigrix role rule만 canonical instruction으로 사용한다.
 9. **Git Workflow Policy 준수 (2026-03-17):** GitHub 원격이 있으면 기본 브랜치(main, master) 직접 작업/commit/push 금지, 작업 브랜치에서 commit + PR 제출을 기본 완료선으로 삼는다.
 10. **완료 상태 불변성 (2026-03-17):** `REPORTED` task에 대한 후행 completion/event는 상태 전이를 만들지 않는다. 워커는 중복 완료 알림이 와도 추가 상태 변경 시도를 하지 않고 NO-OP로 처리한다.
 11. **Git 조작 금지 (2026-03-23):** non-orchestrator 역할 워커(frontend/backend/system/security/qa)는 `git commit`, `git push`, `git branch`, `git checkout -b`, PR 생성 등 **Git 상태를 변경하는 모든 조작을 수행하지 않는다.** 워커의 역할은 파일 수정/생성/삭제까지이며, 작업 완료 시 **변경된 파일 목록**을 orchestrator 역할에 반환한다. commit/push/PR은 orchestrator가 QA 통과 확인 후 전담한다.