zigrix 0.1.0-alpha.0

package/dist/state/tasks.js

@@ -0,0 +1,247 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendEvent, loadEvents, nowIso } from './events.js';
+import { ensureBaseState } from './paths.js';
+// ─── Paths ──────────────────────────────────────────────────────────────────
+const TASK_ID_RE = /^(DEV|TEST|TASK)-(\d{8})-(\d{3})$/;
+function metaPath(paths, taskId) {
+    return path.join(paths.tasksDir, `${taskId}.meta.json`);
+}
+function specPath(paths, taskId) {
+    return path.join(paths.tasksDir, `${taskId}.md`);
+}
+/** Legacy flat JSON path (backward compat read) */
+function legacyPath(paths, taskId) {
+    return path.join(paths.tasksDir, `${taskId}.json`);
+}
+// ─── Read helpers ───────────────────────────────────────────────────────────
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Task ID generation ─────────────────────────────────────────────────────
+export function nextTaskId(paths, prefix = 'DEV') {
+    ensureBaseState(paths);
+    const today = nowIso().slice(0, 10).replaceAll('-', '');
+    const idPrefix = `${prefix}-${today}-`;
+    let maxN = 0;
+    for (const name of fs.readdirSync(paths.tasksDir)) {
+        const base = name.replace(/\.(meta\.json|json|md)$/, '');
+        const match = TASK_ID_RE.exec(base);
+        if (match && base.startsWith(idPrefix)) {
+            maxN = Math.max(maxN, Number(match[3]));
+        }
+    }
+    return `${idPrefix}${String(maxN + 1).padStart(3, '0')}`;
+}
+// ─── Spec template ──────────────────────────────────────────────────────────
+function renderSpecMd(task) {
+    return [
+        '# Task Spec',
+        '',
+        '## 0) Task Metadata',
+        `- Task ID: \`${task.taskId}\``,
+        `- Title: ${task.title}`,
+        `- Scale: \`${task.scale}\``,
+        `- Status: \`${task.status}\``,
+        `- Created: ${task.createdAt}`,
+        task.requestedBy ? `- Requested by: ${task.requestedBy}` : null,
+        task.projectDir ? `- Project dir: ${task.projectDir}` : null,
+        `- Meta: \`${task.taskId}.meta.json\``,
+        '',
+        '## Spec Rule',
+        '- `normal|risky|large`: 이 문서 작성/갱신 완료 전 작업 진행 금지',
+        '- `simple`: 요약형 허용, 문서 파일은 반드시 생성',
+        '- 사람용 문서. 기계용 정보는 `.meta.json` 우선.',
+        '',
+        '## 1) Scope',
+        '### In-Scope',
+        task.description,
+        '',
+        '### Out-of-Scope',
+        '- (TBD)',
+        '',
+        '## 2) Orchestration Plan',
+        `- Required agents: ${task.requiredAgents.join(', ') || '(none)'}`,
+        task.selectedAgents?.length ? `- Selected agents: ${task.selectedAgents.join(', ')}` : null,
+        '',
+        '## 3) Notes',
+        '- (TBD)',
+        '',
+    ].filter((line) => line !== null).join('\n');
+}
+// ─── Save / Load ────────────────────────────────────────────────────────────
+export function saveTask(paths, task) {
+    ensureBaseState(paths);
+    task.updatedAt = nowIso();
+    // Write meta.json (machine data)
+    fs.writeFileSync(metaPath(paths, task.taskId), `${JSON.stringify(task, null, 2)}\n`, 'utf8');
+    // Write .md spec if it doesn't exist yet (don't overwrite human edits)
+    const mdPath = specPath(paths, task.taskId);
+    if (!fs.existsSync(mdPath)) {
+        fs.writeFileSync(mdPath, renderSpecMd(task), 'utf8');
+    }
+    rebuildIndex(paths);
+    return task;
+}
+export function loadTask(paths, taskId) {
+    // Prefer .meta.json, fall back to legacy .json
+    const meta = readJson(metaPath(paths, taskId));
+    if (meta)
+        return meta;
+    const legacy = readJson(legacyPath(paths, taskId));
+    return legacy;
+}
+export function listTasks(paths) {
+    ensureBaseState(paths);
+    const seen = new Set();
+    const tasks = [];
+    for (const name of fs.readdirSync(paths.tasksDir).sort()) {
+        let taskId = null;
+        if (name.endsWith('.meta.json')) {
+            taskId = name.replace(/\.meta\.json$/, '');
+        }
+        else if (name.endsWith('.json') && !name.endsWith('.meta.json')) {
+            taskId = name.replace(/\.json$/, '');
+        }
+        if (!taskId || seen.has(taskId))
+            continue;
+        if (!TASK_ID_RE.test(taskId))
+            continue;
+        const data = loadTask(paths, taskId);
+        if (data) {
+            seen.add(taskId);
+            tasks.push(data);
+        }
+    }
+    return tasks;
+}
+// ─── Events ─────────────────────────────────────────────────────────────────
+export function listTaskEvents(paths, taskId) {
+    const rows = loadEvents(paths.eventsFile);
+    return taskId ? rows.filter((row) => String(row.taskId ?? '') === taskId) : rows;
+}
+// ─── Create ─────────────────────────────────────────────────────────────────
+export function createTask(paths, params) {
+    const task = {
+        taskId: nextTaskId(paths, params.prefix ?? 'DEV'),
+        title: params.title,
+        description: params.description,
+        scale: params.scale ?? 'normal',
+        status: 'OPEN',
+        createdAt: nowIso(),
+        updatedAt: nowIso(),
+        requiredAgents: [...(params.requiredAgents ?? [])],
+        workerSessions: {},
+        ...(params.projectDir ? { projectDir: params.projectDir } : {}),
+        ...(params.requestedBy ? { requestedBy: params.requestedBy } : {}),
+    };
+    saveTask(paths, task);
+    appendEvent(paths.eventsFile, {
+        event: 'task_created',
+        taskId: task.taskId,
+        status: 'OPEN',
+        title: task.title,
+        scale: task.scale,
+        payload: { requiredAgents: task.requiredAgents, projectDir: params.projectDir ?? null },
+    });
+    rebuildIndex(paths);
+    return task;
+}
+// ─── Status transitions ─────────────────────────────────────────────────────
+export function updateTaskStatus(paths, taskId, status) {
+    const task = loadTask(paths, taskId);
+    if (!task)
+        return null;
+    task.status = status;
+    saveTask(paths, task);
+    appendEvent(paths.eventsFile, { event: 'task_status_changed', taskId, status });
+    rebuildIndex(paths);
+    return task;
+}
+export function recordTaskProgress(paths, params) {
+    const task = loadTask(paths, params.taskId);
+    if (!task)
+        return null;
+    saveTask(paths, task);
+    const event = appendEvent(paths.eventsFile, {
+        event: 'progress_report',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: params.actor,
+        payload: {
+            message: params.message,
+            unitId: params.unitId,
+            workPackage: params.workPackage,
+        },
+    });
+    rebuildIndex(paths);
+    return event;
+}
+// ─── Stale policy ───────────────────────────────────────────────────────────
+export function findStaleTasks(paths, hours = 24) {
+    const cutoff = Date.now() - hours * 3600 * 1000;
+    return listTasks(paths).filter((task) => task.status === 'IN_PROGRESS' && Date.parse(task.updatedAt) < cutoff);
+}
+export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout') {
+    const staleTasks = findStaleTasks(paths, hours);
+    const changed = staleTasks.map((task) => {
+        task.status = 'BLOCKED';
+        saveTask(paths, task);
+        const event = appendEvent(paths.eventsFile, {
+            event: 'task_blocked',
+            taskId: task.taskId,
+            phase: 'recovery',
+            actor: 'zigrix',
+            status: 'BLOCKED',
+            payload: { reason, previousStatus: 'IN_PROGRESS', hoursThreshold: hours },
+        });
+        return { taskId: task.taskId, event };
+    });
+    rebuildIndex(paths);
+    return { ok: true, hours, reason, count: changed.length, changed };
+}
+// ─── Index ──────────────────────────────────────────────────────────────────
+export function rebuildIndex(paths) {
+    ensureBaseState(paths);
+    const tasks = listTasks(paths);
+    const events = loadEvents(paths.eventsFile);
+    const activeStatuses = new Set(['OPEN', 'IN_PROGRESS', 'BLOCKED', 'DONE_PENDING_REPORT']);
+    const statusBuckets = {};
+    const taskSummaries = {};
+    const activeTasks = {};
+    for (const task of tasks) {
+        statusBuckets[task.status] ??= [];
+        statusBuckets[task.status].push(task.taskId);
+        const summary = {
+            title: task.title,
+            status: task.status,
+            scale: task.scale,
+            requiredAgents: task.requiredAgents,
+            projectDir: task.projectDir ?? null,
+            updatedAt: task.updatedAt,
+        };
+        taskSummaries[task.taskId] = summary;
+        if (activeStatuses.has(task.status))
+            activeTasks[task.taskId] = summary;
+    }
+    const index = {
+        version: '2.0',
+        updatedAt: nowIso(),
+        policy: {
+            sourceOfTruth: 'tasks.jsonl',
+            projection: 'index.json',
+            qaRequiredForAllScales: true,
+        },
+        counts: { tasks: tasks.length, events: events.length },
+        statusBuckets,
+        activeTasks,
+        taskSummaries,
+    };
+    fs.writeFileSync(paths.indexFile, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+    return index;
+}

package/dist/state/verify.d.ts

@@ -0,0 +1,2 @@
+import { type ZigrixPaths } from './paths.js';
+export declare function verifyState(paths: ZigrixPaths): Record<string, unknown>;

package/dist/state/verify.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listTasks } from './tasks.js';
+function safeReadJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function verifyTask(paths, task) {
+    const issues = [];
+    const evidenceDir = path.join(paths.evidenceDir, task.taskId);
+    const mergedPath = path.join(evidenceDir, '_merged.json');
+    const merged = safeReadJson(mergedPath);
+    const presentEvidenceAgents = fs.existsSync(evidenceDir)
+        ? fs.readdirSync(evidenceDir).filter((name) => name.endsWith('.json') && name !== '_merged.json').map((name) => path.basename(name, '.json')).sort()
+        : [];
+    const requiredAgents = Array.isArray(task.requiredAgents) ? task.requiredAgents.map(String) : [];
+    const workerAgents = Object.keys(task.workerSessions ?? {}).sort();
+    for (const agentId of requiredAgents) {
+        if (!workerAgents.includes(agentId) && !presentEvidenceAgents.includes(agentId)) {
+            issues.push(`required agent '${agentId}' has neither worker session nor evidence`);
+        }
+    }
+    if (merged) {
+        const mergedPresent = Array.isArray(merged.presentAgents) ? merged.presentAgents.map(String).sort() : [];
+        const mergedMissing = Array.isArray(merged.missingAgents) ? merged.missingAgents.map(String).sort() : [];
+        const computedMissing = requiredAgents.filter((agentId) => !presentEvidenceAgents.includes(agentId)).sort();
+        if (JSON.stringify(mergedPresent) !== JSON.stringify(presentEvidenceAgents)) {
+            issues.push('merged presentAgents does not match evidence files');
+        }
+        if (JSON.stringify(mergedMissing) !== JSON.stringify(computedMissing)) {
+            issues.push('merged missingAgents does not match requiredAgents/evidence files');
+        }
+        if (task.status === 'REPORTED' && merged.complete !== true) {
+            issues.push('task is REPORTED but merged evidence is incomplete');
+        }
+    }
+    else if (task.status === 'REPORTED') {
+        issues.push('task is REPORTED but merged evidence is missing');
+    }
+    return {
+        taskId: task.taskId,
+        status: task.status,
+        requiredAgents,
+        workerAgents,
+        presentEvidenceAgents,
+        mergedExists: Boolean(merged),
+        ok: issues.length === 0,
+        issues,
+    };
+}
+export function verifyState(paths) {
+    const tasks = listTasks(paths);
+    const checks = tasks.map((task) => verifyTask(paths, task));
+    const failures = checks.filter((item) => item.ok === false);
+    return {
+        ok: failures.length === 0,
+        taskCount: tasks.length,
+        failedCount: failures.length,
+        checks,
+    };
+}

package/examples/hello-workflow.json

@@ -0,0 +1,13 @@
+{
+  "name": "hello-workflow",
+  "steps": [
+    {
+      "id": "say-hello",
+      "run": "echo hello from zigrix"
+    },
+    {
+      "id": "print-state-dir",
+      "run": "pwd"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "zigrix",
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "description": "Multi-project parallel task orchestration CLI for agent-assisted development",
+  "license": "Apache-2.0",
+  "bin": {
+    "zigrix": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist .zigrix",
+    "dev": "tsx src/index.ts",
+    "prebuild": "npm run clean",
+    "prepack": "npm run build",
+    "publish:check": "npm run build && npm run test && npm run smoke && bash scripts/release-smoke.sh && npm pack --dry-run && node dist/index.js state check --json",
+    "smoke": "node dist/index.js --version && node dist/index.js config validate --json",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "commander": "^14.0.0",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/zigrix-doctor/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: zigrix-doctor
+version: 0.1.0
+description: Inspect Zigrix environment readiness and OpenClaw integration prerequisites.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix doctor --help"
+---
+
+# zigrix doctor
+
+Run this before debugging install or integration issues.
+
+```bash
+zigrix doctor --json
+```
+
+Returns Python, path, binary, and OpenClaw-home readiness details.

package/skills/zigrix-evidence/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: zigrix-evidence
+version: 0.2.0
+description: Collect and merge task evidence in Zigrix.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix evidence --help"
+---
+
+# zigrix evidence
+
+Use evidence commands to persist verification outputs and merge completion state.
+
+```bash
+zigrix evidence collect --task-id DEV-20260316-001 --agent-id qa-zig --summary "QA passed" --json
+zigrix evidence merge --task-id DEV-20260316-001 --require-qa --json
+```
+
+Evidence files are stored under `~/.zigrix/evidence/<taskId>/`.

package/skills/zigrix-init/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: zigrix-init
+version: 0.2.0
+description: "[DEPRECATED] Use zigrix onboard instead."
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+---
+
+# Zigrix Init (Deprecated)
+
+**Use `zigrix onboard` instead.**
+
+`zigrix init` is a deprecated compatibility command. It creates a config file but does not perform PATH stabilization, skill registration, or agent import.
+
+```bash
+# Preferred
+zigrix onboard --yes --json
+
+# Legacy (deprecated)
+zigrix init --yes --json
+```

package/skills/zigrix-report/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: zigrix-report
+version: 0.1.0
+description: Render a user-facing Zigrix completion report from merged evidence.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix report --help"
+---
+
+# zigrix report
+
+Render a user-facing completion summary after evidence merge.
+
+```bash
+zigrix report render --task-id TASK-20260313-001 --record-events --json
+```
+
+When `--record-events` is enabled, Zigrix appends `user_report_prepared` and `feedback_requested` events.

package/skills/zigrix-shared/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: zigrix-shared
+version: 0.2.0
+description: Shared guidance for Zigrix CLI usage, output modes, and safety.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+---
+
+# Zigrix Shared Reference
+
+Use Zigrix for multi-project parallel task orchestration with file-backed, inspectable state.
+
+## Rules
+- Prefer `--json` for automation-heavy flows.
+- Global state lives in `~/.zigrix/` (override: `ZIGRIX_HOME` env).
+- Tasks are NOT project-bound — one Zigrix instance manages tasks across projects.
+- Do not assume OpenClaw internals are required unless the task explicitly needs them.
+
+## Common commands
+```bash
+zigrix doctor --json
+zigrix task list --json
+zigrix task dispatch --title "..." --description "..." --scale normal --json
+zigrix task finalize <taskId> --auto-report --json
+```
+
+## Safety
+- Confirm before destructive actions.
+- Treat runtime state and source code as separate concerns.

package/skills/zigrix-task-create/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: zigrix-task-create
+version: 0.2.0
+description: Create a new Zigrix task with title, description, and scale.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix task create --help"
+---
+
+# zigrix task create
+
+Create a task in `~/.zigrix/tasks/`.
+
+For full orchestration metadata (work packages, execution units, boot prompt), use `zigrix task dispatch` instead.
+
+```bash
+# Low-level task creation
+zigrix task create \
+  --title "Implement installer" \
+  --description "Create a safe app-owned venv installer" \
+  --scale normal \
+  --json
+
+# Full orchestration dispatch (preferred for agent workflows)
+zigrix task dispatch \
+  --title "Implement installer" \
+  --description "Create a safe app-owned venv installer" \
+  --scale normal \
+  --json
+```
+
+Prefer `--json` when another agent or script will consume the result.

package/skills/zigrix-task-status/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: zigrix-task-status
+version: 0.1.0
+description: Inspect Zigrix task records and state transitions.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix task status --help"
+---
+
+# zigrix task status
+
+Use this to inspect one task or list tasks.
+
+```bash
+zigrix task list --json
+zigrix task status TASK-20260313-001 --json
+zigrix task events TASK-20260313-001 --json
+zigrix task progress --task-id TASK-20260313-001 --actor pro-zig --message "진행 상황 요약" --json
+zigrix task stale --hours 24 --json
+zigrix task start TASK-20260313-001
+zigrix task finalize TASK-20260313-001
+zigrix task report TASK-20260313-001
+```
+
+Treat status transitions as explicit lifecycle events.

package/skills/zigrix-worker/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: zigrix-worker
+version: 0.2.0
+description: Prepare, register, and complete Zigrix worker runs.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix worker --help"
+---
+
+# zigrix worker
+
+Use worker lifecycle commands to bridge agent execution and global orchestration state.
+
+```bash
+zigrix worker prepare --task-id DEV-20260316-001 --agent-id qa-zig --description "Run QA checks" --json
+zigrix worker register --task-id DEV-20260316-001 --agent-id qa-zig --session-key agent:test:qa --run-id run-001 --json
+zigrix worker complete --task-id DEV-20260316-001 --agent-id qa-zig --session-key agent:test:qa --run-id run-001 --json
+```
+
+These commands intentionally avoid hard-coding OpenClaw internals into the Zigrix core.