zigrix 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/onboard.d.ts

@@ -1,3 +1,4 @@
+import { type StandardAgentRole } from './agents/roles.js';
 import type { ZigrixConfig } from './config/schema.js';
 import { type ZigrixPaths } from './state/paths.js';
 export interface OpenClawAgent {
@@ -14,6 +15,7 @@ export interface OpenClawConfig {
         list?: OpenClawAgent[];
     };
 }
+export type AgentRoleAssignments = Record<string, StandardAgentRole>;
 export interface PathStabilizeResult {
     alreadyInPath: boolean;
     symlinkCreated: boolean;
@@ -50,12 +52,13 @@ export interface OnboardResult {
 export interface RunOnboardOptions {
     yes?: boolean;
     projectDir?: string;
+    orchestratorId?: string;
     silent?: boolean;
 }
 export declare function detectOpenClawHome(): string;
 export declare function loadOpenClawConfig(openclawHome: string): OpenClawConfig | null;
 export declare function filterAgents(agents: OpenClawAgent[]): OpenClawAgent[];
-export declare function registerAgents(config: ZigrixConfig, agents: OpenClawAgent[]): {
+export declare function registerAgents(config: ZigrixConfig, agents: OpenClawAgent[], roleAssignments?: AgentRoleAssignments): {
     config: ZigrixConfig;
     registered: string[];
     skipped: string[];
@@ -69,7 +72,10 @@ export declare function seedRules(sourceDir: string, targetDir: string): {
     skipped: string[];
     source: string;
 };
-export declare function checkZigrixInPath(): boolean;
+export declare const STABLE_SHELL_PATHS: string[];
+export declare function checkZigrixInPath(opts?: {
+    _overrideStablePaths?: string[];
+}): boolean;
 /**
  * Resolve the path to the zigrix CLI entry point (dist/index.js).
  * Works whether installed via npm link, npm install -g, or local checkout.
@@ -94,9 +100,11 @@ export declare function findUserBinDir(): string;
  *   2. ~/.local/bin   — user-local fallback; may not be in PATH, shows warning if so
  *
  * @param opts._overrideSystemBinDir - Override system bin dir selection (for testing)
+ * @param opts._overrideStablePaths  - Override stable paths list (for testing)
  */
 export declare function ensureZigrixInPath(opts?: {
     _overrideSystemBinDir?: string | null;
+    _overrideStablePaths?: string[];
 }): PathStabilizeResult;
 /**
  * Find the skills/ directory bundled with this zigrix package.
@@ -113,4 +121,10 @@ export declare function registerSkills(openclawHome: string): SkillRegistrationR
  * Space to toggle, Enter to confirm. All agents pre-selected by default.
  */
 export declare function promptAgentSelection(agents: OpenClawAgent[]): Promise<OpenClawAgent[]>;
+export declare function promptAgentRoleAssignments(agents: OpenClawAgent[]): Promise<AgentRoleAssignments>;
+export declare function ensureOrchestratorId(config: ZigrixConfig, preferredId?: string): {
+    config: ZigrixConfig;
+    changed: boolean;
+    warning?: string;
+};
 export declare function runOnboard(options: RunOnboardOptions): Promise<OnboardResult>;

package/dist/onboard.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { addAgent } from './agents/registry.js';
+import { inferStandardAgentRole, STANDARD_AGENT_ROLES } from './agents/roles.js';
 import { loadConfig, writeConfigFile, writeDefaultConfig } from './config/load.js';
 import { ensureBaseState, resolvePaths } from './state/paths.js';
 import { rebuildIndex } from './state/tasks.js';
@@ -28,7 +29,7 @@ export function filterAgents(agents) {
     return agents.filter((a) => a.id !== 'main');
 }
 // ─── Agent registration ───────────────────────────────────────────────────────
-export function registerAgents(config, agents) {
+export function registerAgents(config, agents, roleAssignments) {
     let current = structuredClone(config);
     const registered = [];
     const skipped = [];
@@ -38,7 +39,10 @@ export function registerAgents(config, agents) {
             skipped.push(agent.id);
             continue;
         }
-        const role = agent.identity?.theme ?? 'assistant';
+        const role = roleAssignments?.[agent.id] ?? inferStandardAgentRole({
+            agentId: agent.id,
+            theme: agent.identity?.theme ?? null,
+        });
         const result = addAgent(current, {
             id: agent.id,
             role,
@@ -102,9 +106,9 @@ export function seedRules(sourceDir, targetDir) {
     return { copied, skipped, source: effectiveSource === sourceDir ? 'external' : 'bundled' };
 }
 // ─── PATH check and stabilization ─────────────────────────────────────────────
-export function checkZigrixInPath() {
-    const pathEnv = process.env.PATH ?? '';
-    const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+export const STABLE_SHELL_PATHS = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+export function checkZigrixInPath(opts) {
+    const dirs = opts?._overrideStablePaths ?? STABLE_SHELL_PATHS;
     for (const dir of dirs) {
         try {
             if (!fs.existsSync(dir))
@@ -215,9 +219,10 @@ export function findUserBinDir() {
  *   2. ~/.local/bin   — user-local fallback; may not be in PATH, shows warning if so
  *
  * @param opts._overrideSystemBinDir - Override system bin dir selection (for testing)
+ * @param opts._overrideStablePaths  - Override stable paths list (for testing)
  */
 export function ensureZigrixInPath(opts) {
-    if (checkZigrixInPath()) {
+    if (checkZigrixInPath({ _overrideStablePaths: opts?._overrideStablePaths })) {
         return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
     }
     const binEntry = resolveZigrixBin();
@@ -249,7 +254,15 @@ export function ensureZigrixInPath(opts) {
             fs.chmodSync(symlinkPath, 0o755);
             return { alreadyInPath: false, symlinkCreated: true, symlinkPath, warning: null };
         }
-        catch {
+        catch (e) {
+            if (e.code === 'EACCES') {
+                return {
+                    alreadyInPath: false,
+                    symlinkCreated: false,
+                    symlinkPath: null,
+                    warning: `Cannot write to ${systemBinDir} (permission denied). Run:\n  sudo ln -sfn $(which zigrix) ${symlinkPath}`,
+                };
+            }
             // Fall through to user bin dir
         }
     }
@@ -418,6 +431,85 @@ export async function promptAgentSelection(agents) {
         return agents;
     }
 }
+export async function promptAgentRoleAssignments(agents) {
+    const defaults = Object.fromEntries(agents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]));
+    if (agents.length === 0)
+        return defaults;
+    try {
+        const { checkbox } = await import('@inquirer/prompts');
+        const assignments = {};
+        for (const agent of agents) {
+            const suggested = defaults[agent.id];
+            let selected = [];
+            while (selected.length !== 1) {
+                selected = await checkbox({
+                    message: `Assign role for ${agent.id} (space toggle + enter confirm, choose exactly one):`,
+                    choices: STANDARD_AGENT_ROLES.map((role) => ({
+                        name: `${role}${role === suggested ? ' (suggested)' : ''}`,
+                        value: role,
+                        checked: role === suggested,
+                    })),
+                });
+                if (selected.length !== 1) {
+                    console.log(`⚠️  Select exactly one role for ${agent.id}.`);
+                }
+            }
+            assignments[agent.id] = selected[0];
+        }
+        return assignments;
+    }
+    catch {
+        console.log('ℹ️  Non-interactive mode — inferring roles from agent ids/themes.');
+        return defaults;
+    }
+}
+export function ensureOrchestratorId(config, preferredId) {
+    const next = structuredClone(config);
+    const participants = new Set(next.agents.orchestration.participants);
+    const excluded = new Set(next.agents.orchestration.excluded);
+    const participantMode = participants.size > 0;
+    const eligible = Object.entries(next.agents.registry)
+        .filter(([agentId, agent]) => {
+        if (!agent.enabled)
+            return false;
+        if (agent.role !== 'orchestrator')
+            return false;
+        if (excluded.has(agentId))
+            return false;
+        if (participantMode && !participants.has(agentId))
+            return false;
+        return true;
+    })
+        .map(([agentId]) => agentId)
+        .sort();
+    const requested = preferredId?.trim();
+    const current = next.agents.orchestration.orchestratorId;
+    if (requested) {
+        if (!eligible.includes(requested)) {
+            return {
+                config: next,
+                changed: false,
+                warning: `requested orchestrator '${requested}' is not eligible (eligible: ${eligible.join(', ') || 'none'})`,
+            };
+        }
+        const changed = current !== requested;
+        next.agents.orchestration.orchestratorId = requested;
+        return { config: next, changed };
+    }
+    if (eligible.includes(current)) {
+        return { config: next, changed: false };
+    }
+    const fallback = eligible[0];
+    if (!fallback) {
+        return {
+            config: next,
+            changed: false,
+            warning: 'no eligible orchestrator role agent found. set one with --orchestrator-id after assigning roles.',
+        };
+    }
+    next.agents.orchestration.orchestratorId = fallback;
+    return { config: next, changed: true };
+}
 // ─── Ensure config (idempotent) ───────────────────────────────────────────────
 function ensureConfig() {
     const existing = loadConfig({});
@@ -471,18 +563,45 @@ export async function runOnboard(options) {
         else {
             selectedAgents = await promptAgentSelection(allAgents);
         }
+        let nextConfig = loaded.config;
         if (selectedAgents.length > 0) {
-            const result = registerAgents(loaded.config, selectedAgents);
+            const roleAssignments = options.yes
+                ? Object.fromEntries(selectedAgents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]))
+                : await promptAgentRoleAssignments(selectedAgents);
+            const result = registerAgents(nextConfig, selectedAgents, roleAssignments);
+            nextConfig = result.config;
             agentsRegistered = result.registered;
             agentsSkipped = result.skipped;
             if (agentsRegistered.length > 0) {
-                writeConfigFile(configPath, result.config);
                 log(`✅ Registered agents: ${agentsRegistered.join(', ')}`);
             }
             if (agentsSkipped.length > 0) {
                 log(`⏭️  Already registered (skipped): ${agentsSkipped.join(', ')}`);
             }
         }
+        const orchResult = ensureOrchestratorId(nextConfig, options.orchestratorId);
+        nextConfig = orchResult.config;
+        if (orchResult.warning) {
+            warnings.push(orchResult.warning);
+            log(`⚠️  ${orchResult.warning}`);
+        }
+        if (agentsRegistered.length > 0 || orchResult.changed) {
+            writeConfigFile(configPath, nextConfig);
+            if (orchResult.changed) {
+                log(`✅ Orchestrator set to: ${nextConfig.agents.orchestration.orchestratorId}`);
+            }
+        }
+    }
+    if (!openclawConfig && options.orchestratorId) {
+        const orchResult = ensureOrchestratorId(loaded.config, options.orchestratorId);
+        if (orchResult.warning) {
+            warnings.push(orchResult.warning);
+            log(`⚠️  ${orchResult.warning}`);
+        }
+        if (orchResult.changed) {
+            writeConfigFile(configPath, orchResult.config);
+            log(`✅ Orchestrator set to: ${orchResult.config.agents.orchestration.orchestratorId}`);
+        }
     }
     // 4. Seed rules
     const projectDir = options.projectDir ?? process.cwd();

package/dist/orchestration/dispatch.d.ts

@@ -1,5 +1,6 @@
+import type { ZigrixConfig } from '../config/schema.js';
 import { type ZigrixPaths } from '../state/paths.js';
-export declare function dispatchTask(paths: ZigrixPaths, params: {
+export declare function dispatchTask(paths: ZigrixPaths, config: ZigrixConfig, params: {
     title: string;
     description: string;
     scale: string;

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;