zigrix 0.1.0-alpha.8 → 0.1.0

package/LICENSE

@@ -169,7 +169,7 @@ recommend that a file or class name and description of purpose be included on
 the same "printed page" as the copyright notice for easier identification
 within third-party archives.
 
-Copyright [yyyy] [name of copyright owner]
+Copyright 2026 owen-ever
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/README.md

@@ -1,164 +1,203 @@
-# Zigrix
+<h1 align="center">Zigrix</h1>
 
-Zigrix is a **multi-project parallel task orchestration CLI** for agent-assisted development workflows.
+<p align="center">
+  <strong>OpenClaw-first orchestration CLI for tracked, multi-agent execution.</strong>
+</p>
 
-It turns ad-hoc delegation into a file-backed, inspectable flow with:
-- global runtime state (`~/.zigrix/`) — tasks are not project-bound
-- task dispatch and finalization with full orchestration metadata
-- agent registry + participation control
-- rule/template validation and recovery
-- evidence merge + final report rendering
-- OpenClaw integration (skill registration + PATH stabilization)
-- built-in web dashboard (`zigrix dashboard --port 3838`)
-- release-friendly Node/TypeScript packaging
+<p align="center">
+  Zigrix turns ad-hoc delegation into a visible workflow with specialist routing,
+  evidence collection, and reportable finalization.
+</p>
 
-## Current status
-- Stage: **alpha, productization in progress**
-- Main implementation: **Node/TypeScript at repository root**
-- Legacy reference: **Python prototype under `legacy-python/`**
-- Supported first: **macOS, Linux**
-- Packaging path: **GitHub Releases + install.sh**, npm publish prepared for manual follow-up
+<p align="center">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License">
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey" alt="Platform">
+  <img src="https://img.shields.io/badge/OpenClaw-first-6f42c1" alt="OpenClaw-first">
+</p>
 
-## Intended user model
-- **Human operator:** install Zigrix, run `zigrix onboard`, and stop there unless recovery or advanced maintenance is needed.
-- **OpenClaw agents:** use the operational Zigrix commands (`task`, `worker`, `evidence`, `report`, `pipeline`, and low-level config surfaces) after onboarding.
-- **Advanced maintenance:** `zigrix configure` for reconfiguration, `zigrix reset` for recovery.
+<p align="center">
+  <a href="#why-zigrix">Why Zigrix</a> ·
+  <a href="#is-zigrix-for-you">Is Zigrix for you?</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#core-workflow">Core Workflow</a> ·
+  <a href="#openclaw-integration">OpenClaw Integration</a> ·
+  <a href="#dashboard--docs">Dashboard / Docs</a>
+</p>
 
-See `docs/onboarding-ownership-model.md` for the product-direction source of truth.
+---
 
-## Quick start
+## Why Zigrix
 
-```bash
-# Install and onboard (one-time human setup)
-./install.sh
-zigrix onboard
+Most agent-heavy workflows break down in the same places:
 
-# Verify readiness
-zigrix doctor
+- work gets delegated, but not consistently tracked
+- specialist routing depends on memory, not policy
+- outputs arrive without structured evidence
+- final reporting is manual and hard to audit
 
-# Launch dashboard (foreground, Ctrl+C to stop)
-zigrix dashboard
-# zigrix dashboard --port 3939
-```
+Zigrix gives that flow a control surface: dispatch, worker lifecycle, evidence, and finalization in one runtime.
 
-### Prerequisites: Node.js version
+---
 
-Zigrix requires Node.js **22 or later**. Verify before installing:
+## Is Zigrix for you?
 
-```bash
-node --version   # must be v22.x or higher
-```
+Zigrix is a strong fit if you want:
+
+- **one-time operator setup, then agent-driven execution**
+- **repeatable orchestration rules** instead of ad-hoc delegation
+- **recoverable local runtime state** for task progress and reports
+- **OpenClaw compatibility** without requiring a plugin-based architecture
+
+Zigrix may be a poor fit if your main goal is a hosted, multi-tenant control plane.
+
+---
+
+## Supported environments
+
+- **Operating systems:** macOS, Linux
+- **Runtime:** Node.js (current LTS recommended)
+- **Package manager:** npm
+- **OpenClaw:** optional, but recommended for full orchestration flow
+
+Zigrix still works as a standalone CLI when OpenClaw is not installed.
+
+---
 
-If you use **nvm**, make sure the correct version is active:
+## Quick Start
+
+### 1) Install
 
 ```bash
-nvm use 22        # or: nvm use --lts
-node --version    # confirm v22+
+npm install -g zigrix
 ```
 
-> **Important (nvm users):** `npm link` binds `zigrix` to whichever Node version is active at install time.
-> If you switch node versions later, re-run the install to rebind:
-> ```bash
-> npm run build && npm link
-> ```
+From source:
 
-### Version mismatch troubleshooting
+```bash
+./install.sh
+```
 
-If `zigrix --version` shows an unexpected version after updating, rebuild and relink:
+### 2) Onboard
 
 ```bash
-npm run build && npm link
-zigrix --version   # should now match package.json
+zigrix onboard
 ```
 
-`zigrix onboard` will:
-1. Create `~/.zigrix/` with default config
-2. Detect OpenClaw and import agents from `openclaw.json`
-3. Seed rule files from `orchestration/rules/`
-4. Ensure `zigrix` is reachable from PATH (creates symlink if needed)
-5. Register zigrix skill packs into OpenClaw's `~/.openclaw/skills/`
-
-## What Zigrix can do today
-- **dispatch** tasks with full orchestration metadata (replaces `dev_dispatch.py`)
-- **finalize** tasks with evidence merge and execution unit checks (replaces `dev_finalize.py`)
-- validate, inspect, change, diff, and reset config
-- manage agent registry and orchestration membership
-- validate, render, edit, diff, and reset rules/templates
-- create and track tasks with append-only event history
-- manage worker/evidence/report lifecycle
-- detect stale tasks, verify state consistency, and recover state
-- start a bundled web dashboard with explicit port control (`zigrix dashboard --port <n>`, default 3838)
-- **configure** agents, rules, PATH, skills, and workspace after initial setup
-
-## Recovery-first operations
-Reset one broken template:
+### 3) Verify
+
 ```bash
-zigrix template reset workerPrompt --yes
+zigrix doctor
+zigrix dashboard
 ```
 
-Reset all config back to defaults:
-```bash
-zigrix reset config --yes
+That is the intended entry flow: **install → onboard → done**.
+
+---
+
+## Usage model: human vs agent
+
+| Role | Primary responsibility |
+|---|---|
+| **Human operator** | Install Zigrix, run `zigrix onboard`, verify readiness (`zigrix doctor`), then step out of day-to-day orchestration |
+| **OpenClaw / automation agents** | Run task/worker/evidence/report commands to execute and complete orchestration work |
+| **Human (maintenance mode)** | Use `zigrix configure` or `zigrix reset` only when reconfiguration or recovery is needed |
+
+This split keeps normal operation agent-driven while keeping setup and governance human-controlled.
+
+---
+
+## Core Workflow
+
+Typical operational flow:
+
+```text
+Human setup
+  install -> zigrix onboard -> doctor check
+
+Agent execution
+  zigrix task dispatch
+    -> worker prepare/register/complete
+    -> evidence collect/merge
+    -> task finalize + report
 ```
 
-Reset runtime state only:
+Common commands:
+
 ```bash
+# Dispatch orchestration work
+zigrix task dispatch --title "Implement auth module" --description "..." --scale normal --json
+
+# Check runtime health
+zigrix doctor
+
+# Launch dashboard
+zigrix dashboard --port 3838
+
+# Maintenance surfaces
+zigrix configure --section agents
+zigrix configure --section skills
 zigrix reset state --yes
 ```
 
-## Documentation map
-- `docs/quickstart.md`
-- `docs/onboarding-ownership-model.md`
-- `docs/product-decisions.md`
-- `docs/cli-spec.md`
-- `docs/openclaw-integration.md`
-- `docs/concepts.md`
-- `docs/runtime-flow.md`
-- `docs/state-layout.md`
-- `docs/troubleshooting.md`
-- `docs/v1-scope.md`
-- `docs/non-goals.md`
-- `docs/install.md`
-- `docs/release-process.md`
-- `docs/versioning.md`
-- `docs/known-limitations.md`
-- `docs/npm-publish-manual.md`
-
-## Repository layout
-```text
-zigrix/
-├─ src/                # Node/TS main implementation
-├─ tests/              # test coverage
-├─ skills/             # OpenClaw skill packs
-├─ examples/           # example workflows
-├─ scripts/            # smoke / release helpers
-├─ docs/               # product + architecture docs
-├─ legacy-python/      # reference prototype only
-└─ .github/            # CI + issue/PR templates
+---
+
+## What onboard does
+
+`zigrix onboard` prepares runtime and integration in one pass:
+
+1. creates runtime directories from `zigrix.config.json` (`paths.*`) and default config/state structure
+2. seeds rule files from bundled templates
+3. ensures `zigrix` is reachable from the runtime-visible PATH
+4. detects OpenClaw and imports agents from `openclaw.json`
+5. registers bundled `skills/zigrix-*` into `~/.openclaw/skills/`
+6. leaves the environment ready for agent-led orchestration
+
+---
+
+## OpenClaw Integration
+
+When OpenClaw is present, Zigrix is optimized for this model:
+
+- import agent definitions and normalize roles
+- establish orchestrator ownership for task execution
+- register Zigrix skill packs for agent readiness checks
+- keep CLI reachability stable for OpenClaw runtime
+
+Read the full integration contract in [docs/openclaw-integration.md](docs/openclaw-integration.md).
+
+---
+
+## Dashboard / Docs
+
+Start dashboard:
+
+```bash
+zigrix dashboard --port 3838
 ```
 
-## Product stance
-- local-first
-- config-first
-- recoverable by default
-- OpenClaw-friendly, not OpenClaw-dependent in the core
-- stability before speculative expansion
+Key docs:
 
-## Non-goals right now
-- hosted control plane
-- hosted multi-user control-plane UI surface
-- generalized plugin SDK
-- automatic npm publish execution
-- Windows-first support
+- [Quickstart](docs/quickstart.md)
+- [Install](docs/install.md)
+- [OpenClaw Integration](docs/openclaw-integration.md)
+- [CLI Spec](docs/cli-spec.md)
+- [Architecture](docs/architecture.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+---
 
 ## Contributing
-See `CONTRIBUTING.md`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Support
-See `SUPPORT.md`.
+
+See [SUPPORT.md](SUPPORT.md).
 
 ## Security
-See `SECURITY.md`.
+
+See [SECURITY.md](SECURITY.md).
 
 ## License
+
 Apache-2.0

package/dist/agents/registry.js

@@ -1,3 +1,4 @@
+import { assertStandardAgentRole } from './roles.js';
 import { zigrixConfigSchema } from '../config/schema.js';
 function assertAgentExists(config, agentId) {
     if (!config.agents.registry[agentId]) {
@@ -7,6 +8,18 @@ function assertAgentExists(config, agentId) {
 function unique(items) {
     return [...new Set(items)];
 }
+function normalizeOrchestratorId(config) {
+    const current = config.agents.orchestration.orchestratorId;
+    if (config.agents.registry[current])
+        return;
+    const candidates = Object.entries(config.agents.registry)
+        .filter(([, agent]) => agent.role === 'orchestrator')
+        .map(([agentId]) => agentId)
+        .sort();
+    if (candidates.length > 0) {
+        config.agents.orchestration.orchestratorId = candidates[0];
+    }
+}
 export function listAgents(config) {
     return Object.entries(config.agents.registry)
         .map(([id, agent]) => ({
@@ -24,10 +37,11 @@ export function addAgent(config, params) {
     if (config.agents.registry[params.id]) {
         throw new Error(`agent already exists: ${params.id}`);
     }
+    const normalizedRole = assertStandardAgentRole(params.role, 'agent role');
     const next = structuredClone(config);
     next.agents.registry[params.id] = {
         label: params.label ?? params.id,
-        role: params.role,
+        role: normalizedRole,
         runtime: params.runtime,
         enabled: params.enabled ?? true,
         metadata: {},
@@ -36,6 +50,7 @@ export function addAgent(config, params) {
         next.agents.orchestration.participants = unique([...next.agents.orchestration.participants, params.id]);
         next.agents.orchestration.excluded = next.agents.orchestration.excluded.filter((item) => item !== params.id);
     }
+    normalizeOrchestratorId(next);
     return {
         config: zigrixConfigSchema.parse(next),
         changed: true,
@@ -48,6 +63,7 @@ export function removeAgent(config, agentId) {
     delete next.agents.registry[agentId];
     next.agents.orchestration.participants = next.agents.orchestration.participants.filter((item) => item !== agentId);
     next.agents.orchestration.excluded = next.agents.orchestration.excluded.filter((item) => item !== agentId);
+    normalizeOrchestratorId(next);
     return {
         config: zigrixConfigSchema.parse(next),
         changed: true,
@@ -88,8 +104,9 @@ export function setAgentEnabled(config, agentId, enabled) {
 }
 export function setAgentRole(config, agentId, role) {
     assertAgentExists(config, agentId);
+    const normalizedRole = assertStandardAgentRole(role, 'agent role');
     const next = structuredClone(config);
-    next.agents.registry[agentId].role = role;
+    next.agents.registry[agentId].role = normalizedRole;
     return {
         config: zigrixConfigSchema.parse(next),
         changed: true,

package/dist/agents/roles.d.ts

@@ -0,0 +1,10 @@
+export declare const STANDARD_AGENT_ROLES: readonly ["orchestrator", "qa", "security", "frontend", "backend", "system"];
+export type StandardAgentRole = (typeof STANDARD_AGENT_ROLES)[number];
+export declare const ROLE_HINTS: Record<StandardAgentRole, string>;
+export declare function normalizeAgentRole(value: string): StandardAgentRole | null;
+export declare function assertStandardAgentRole(value: string, context?: string): StandardAgentRole;
+export declare function inferStandardAgentRole(params: {
+    agentId: string;
+    theme?: string | null;
+}): StandardAgentRole;
+export declare function listStandardRolesText(): string;

package/dist/agents/roles.js

@@ -0,0 +1,83 @@
+export const STANDARD_AGENT_ROLES = [
+    'orchestrator',
+    'qa',
+    'security',
+    'frontend',
+    'backend',
+    'system',
+];
+const ROLE_ALIAS_MAP = {
+    orchestrator: 'orchestrator',
+    orchestration: 'orchestrator',
+    orchestrate: 'orchestrator',
+    pro: 'orchestrator',
+    qa: 'qa',
+    quality: 'qa',
+    qualityassurance: 'qa',
+    test: 'qa',
+    testing: 'qa',
+    security: 'security',
+    sec: 'security',
+    frontend: 'frontend',
+    front: 'frontend',
+    ui: 'frontend',
+    client: 'frontend',
+    backend: 'backend',
+    back: 'backend',
+    server: 'backend',
+    api: 'backend',
+    system: 'system',
+    sys: 'system',
+    infra: 'system',
+    infrastructure: 'system',
+    architecture: 'system',
+};
+export const ROLE_HINTS = {
+    orchestrator: 'coordination / orchestration / execution planning',
+    qa: 'quality assurance / regression / verification',
+    security: 'security-sensitive scope or risky changes',
+    frontend: 'UI / styling / client-side integration when present',
+    backend: 'API / DB / server-side logic when present',
+    system: 'system architecture / technical decision / platform-wide changes',
+};
+export function normalizeAgentRole(value) {
+    const normalized = value.trim().toLowerCase().replace(/[^a-z]/g, '');
+    return ROLE_ALIAS_MAP[normalized] ?? null;
+}
+export function assertStandardAgentRole(value, context = 'role') {
+    const normalized = normalizeAgentRole(value);
+    if (!normalized) {
+        throw new Error(`${context} must be one of: ${STANDARD_AGENT_ROLES.join(', ')}`);
+    }
+    return normalized;
+}
+function inferRoleFromHints(agentIdOrTheme) {
+    const normalized = agentIdOrTheme.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    if (normalized.includes('qa') || normalized.includes('test'))
+        return 'qa';
+    if (normalized.includes('sec'))
+        return 'security';
+    if (normalized.includes('front') || normalized.includes('ui'))
+        return 'frontend';
+    if (normalized.includes('back') || normalized.includes('api') || normalized.includes('server'))
+        return 'backend';
+    if (normalized.includes('sys') || normalized.includes('infra') || normalized.includes('arch'))
+        return 'system';
+    if (normalized.includes('pro') || normalized.includes('orch') || normalized.includes('coord'))
+        return 'orchestrator';
+    return null;
+}
+export function inferStandardAgentRole(params) {
+    const fromTheme = params.theme ? inferRoleFromHints(params.theme) : null;
+    if (fromTheme)
+        return fromTheme;
+    const fromId = inferRoleFromHints(params.agentId);
+    if (fromId)
+        return fromId;
+    return 'system';
+}
+export function listStandardRolesText() {
+    return STANDARD_AGENT_ROLES.join(', ');
+}

package/dist/config/defaults.d.ts

@@ -1,5 +1,11 @@
-export declare const ZIGRIX_HOME: string;
-export declare const defaultConfig: {
+export declare const CONFIG_FILENAME = "zigrix.config.json";
+export declare const LEGACY_DEFAULT_GATEWAY_URL = "http://127.0.0.1:18789";
+export declare function expandTilde(input: string): string;
+export declare function resolveAbsolutePath(input: string): string;
+export declare function resolveCanonicalConfigHome(): string;
+export declare function resolveCanonicalConfigPath(): string;
+export declare function resolveDefaultWorkspaceDir(baseDir?: string): string;
+export declare function buildDefaultConfig(baseDir?: string): {
     readonly paths: {
         readonly baseDir: string;
         readonly tasksDir: string;
@@ -11,13 +17,14 @@ export declare const defaultConfig: {
         readonly rulesDir: string;
     };
     readonly workspace: {
-        readonly projectsBaseDir: "";
+        readonly projectsBaseDir: string;
     };
     readonly agents: {
         readonly registry: {};
         readonly orchestration: {
             readonly participants: readonly [];
             readonly excluded: readonly [];
+            readonly orchestratorId: "orchestrator";
         };
     };
     readonly rules: {
@@ -32,7 +39,7 @@ export declare const defaultConfig: {
             };
             readonly risky: {
                 readonly requiredRoles: readonly ["orchestrator", "qa", "security"];
-                readonly optionalRoles: readonly ["frontend", "backend", "infra"];
+                readonly optionalRoles: readonly ["frontend", "backend", "system"];
             };
         };
         readonly completion: {
@@ -46,10 +53,80 @@ export declare const defaultConfig: {
     };
     readonly templates: {
         readonly workerPrompt: {
+            readonly format: "markdown";
+            readonly version: 2;
+            readonly placeholders: readonly ["taskId", "title", "scale", "agentId", "description"];
+            readonly body: "## Worker Assignment: {{taskId}}\n- title: {{title}}\n- scale: {{scale}}\n- agent: {{agentId}}\n- description: {{description}}\n\n### Completion\n작업 완료 후 반드시 증적을 먼저 수집하라:\n```bash\nzigrix evidence collect --task-id {{taskId}} --agent-id {{agentId}} --summary \"<결과 요약>\"\n```\n⚠️ 증적 없이 완료하면 finalize에서 incomplete 판정된다.";
+        };
+        readonly finalReport: {
             readonly format: "markdown";
             readonly version: 1;
+            readonly placeholders: readonly ["taskId", "title", "status", "summary"];
+            readonly body: "## Final Report: {{taskId}}\n- title: {{title}}\n- status: {{status}}\n- summary: {{summary}}";
+        };
+    };
+    readonly openclaw: {
+        readonly home: "";
+        readonly binPath: null;
+        readonly gatewayUrl: "";
+    };
+    readonly runtime: {
+        readonly outputMode: "text";
+        readonly jsonIndent: 2;
+    };
+};
+export declare const defaultConfig: {
+    readonly paths: {
+        readonly baseDir: string;
+        readonly tasksDir: string;
+        readonly evidenceDir: string;
+        readonly promptsDir: string;
+        readonly eventsFile: string;
+        readonly indexFile: string;
+        readonly runsDir: string;
+        readonly rulesDir: string;
+    };
+    readonly workspace: {
+        readonly projectsBaseDir: string;
+    };
+    readonly agents: {
+        readonly registry: {};
+        readonly orchestration: {
+            readonly participants: readonly [];
+            readonly excluded: readonly [];
+            readonly orchestratorId: "orchestrator";
+        };
+    };
+    readonly rules: {
+        readonly scales: {
+            readonly simple: {
+                readonly requiredRoles: readonly ["orchestrator"];
+                readonly optionalRoles: readonly ["qa"];
+            };
+            readonly normal: {
+                readonly requiredRoles: readonly ["orchestrator", "qa"];
+                readonly optionalRoles: readonly ["frontend", "backend"];
+            };
+            readonly risky: {
+                readonly requiredRoles: readonly ["orchestrator", "qa", "security"];
+                readonly optionalRoles: readonly ["frontend", "backend", "system"];
+            };
+        };
+        readonly completion: {
+            readonly requireQa: true;
+            readonly requireEvidence: true;
+            readonly requireUserReport: true;
+        };
+        readonly stale: {
+            readonly defaultHours: 24;
+        };
+    };
+    readonly templates: {
+        readonly workerPrompt: {
+            readonly format: "markdown";
+            readonly version: 2;
             readonly placeholders: readonly ["taskId", "title", "scale", "agentId", "description"];
-            readonly body: "## Worker Assignment: {{taskId}}\n- title: {{title}}\n- scale: {{scale}}\n- agent: {{agentId}}\n- description: {{description}}";
+            readonly body: "## Worker Assignment: {{taskId}}\n- title: {{title}}\n- scale: {{scale}}\n- agent: {{agentId}}\n- description: {{description}}\n\n### Completion\n작업 완료 후 반드시 증적을 먼저 수집하라:\n```bash\nzigrix evidence collect --task-id {{taskId}} --agent-id {{agentId}} --summary \"<결과 요약>\"\n```\n⚠️ 증적 없이 완료하면 finalize에서 incomplete 판정된다.";
         };
         readonly finalReport: {
             readonly format: "markdown";
@@ -58,9 +135,14 @@ export declare const defaultConfig: {
             readonly body: "## Final Report: {{taskId}}\n- title: {{title}}\n- status: {{status}}\n- summary: {{summary}}";
         };
     };
+    readonly openclaw: {
+        readonly home: "";
+        readonly binPath: null;
+        readonly gatewayUrl: "";
+    };
     readonly runtime: {
         readonly outputMode: "text";
         readonly jsonIndent: 2;
     };
 };
-export type DefaultConfig = typeof defaultConfig;
+export type DefaultConfig = ReturnType<typeof buildDefaultConfig>;