@crewx/wi 0.1.0

package/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: work-instruction
+description: Work Instruction (WI) skill. Draft, review, and issue structured task assignments to agents.
+metadata:
+  version: 0.1.0
+---
+
+# Work Instruction Skill
+
+> **Core principle**: Context belongs in the file, not in your head.
+> An agent should be able to execute a WI without asking questions.
+
+## When to use
+
+- When delegating work to an agent
+- Before issuing a task to a worker agent
+- When decomposing complex features into atomic units
+
+**Never delegate to an agent without a Work Instruction.**
+
+---
+
+## Commands
+
+### draft — Create a draft
+
+Takes the user's intent and drafts a Work Instruction.
+The lead reads the design doc and fills in the details.
+
+```bash
+npx skill work-instruction draft "task description"
+```
+
+**Lead execution steps:**
+
+1. Check today's date + existing WI count → assign ID
+   ```bash
+   ls docs/wi/ | grep $(date +%Y%m%d) | wc -l
+   ```
+
+2. Read relevant section from design doc
+   ```bash
+   npx doc section docs/design.md "section name"
+   ```
+
+3. Identify affected files + **impact analysis**
+   ```bash
+   # Track symbol references
+   npx skill tsserver find "symbolName"
+   npx skill tsserver refs path/to/file.ts lineNumber
+
+   # If API changed, find consumers
+   npx search "endpointName" ./src/ui --glob="**/*.ts,**/*.tsx"
+
+   # If types changed, find usages
+   npx search "typeName" ./src --glob="**/*.ts,**/*.tsx"
+   ```
+
+   → Fill in `api_changed`, `schema_changed`, `consumers`, `risk_level`
+
+4. Validate atomicity (decide if decomposition needed)
+   - More than 3 files modified → decompose
+   - Estimated cost > $0.30 → decompose
+   - Backend + frontend together → separate (apply Contract-First)
+
+5. Create `docs/wi/WI-{YYYYMMDD}-{SEQ}.md`
+   - Template: `docs/wi/WI-TEMPLATE.md`
+
+6. **WI verification** — do not skip
+   - Imagine a world where all ACs pass. Run the scenario in your head without writing code.
+   - Picture a user using this feature for the first time:
+     - Input → Process → **Save** → **Read** → Use — is the full path connected?
+     - Any gaps like "it saves but there's no way to retrieve it"?
+     - Any dead ends in error cases?
+   - If gaps found → revise AC/scope, repeat from step 5
+   - Attach verification results when reporting the draft
+
+7. Report draft to user → await approval
+
+---
+
+### issue — Issue to an agent
+
+Deliver an approved Work Instruction to the assigned agent.
+
+```bash
+npx skill work-instruction issue WI-20260312-001
+```
+
+**Issue steps:**
+
+1. Read WI file → check status (must be `approved`)
+
+2. Check WI's `impl_agent` (`consultant` is for advisory — not an issue target)
+
+3. Check agent memory (any in-progress work?)
+   ```bash
+   npx memory index {impl_agent}
+   ```
+
+4. Issue via `$CREWX_CLI x`:
+   ```bash
+   $CREWX_CLI x "@{impl_agent} Execute Work Instruction WI-{ID}.
+
+   Full WI:
+   {entire WI file content}
+
+   Report in the specified format when done." \
+   --thread="WI-{ID}" --result="WI-{ID}-impl"
+   ```
+
+5. Update WI status → `in-progress`
+
+6. Verify AC after completion report:
+   ```bash
+   npx tsc --noEmit
+   npx vitest run src/server/  # or src/ui/
+   ```
+
+7. If AC passes → status → `done`
+
+---
+
+### list — List WIs
+
+```bash
+npx skill work-instruction list
+npx skill work-instruction list --status=approved
+npx skill work-instruction list --status=in-progress
+```
+
+**Execution:**
+```bash
+# Full list
+ls docs/wi/ | grep "^WI-" | sort
+
+# Filter by status
+grep -l "status: approved" docs/wi/WI-*.md 2>/dev/null
+```
+
+---
+
+### review — Request lead review
+
+Request a review from the `consultant` before issuing.
+
+```bash
+npx skill work-instruction review WI-20260312-001
+```
+
+```bash
+$CREWX_CLI q "@{consultant} Review this Work Instruction.
+Check feasibility, missing items, and risks.
+
+{entire WI file content}" \
+--thread="WI-{ID}-review" --result="WI-{ID}-review"
+```
+
+---
+
+## Contract-First Rule
+
+When backend + frontend work is needed:
+
+```
+❌ Issue simultaneously (causes type drift)
+
+✅ Issue sequentially:
+  1. WI-001: Backend TypeScript types/DTO definitions
+  2. (after WI-001) WI-002: Backend service/controller implementation
+  3. (after WI-002) WI-003: Frontend integration
+```
+
+Enforce order with `depends_on`:
+```yaml
+depends_on: ["WI-20260312-001"]
+```
+
+---
+
+## Atomicity Criteria
+
+| Condition | Decision |
+|-----------|----------|
+| 1-3 files modified | ✅ Ready to issue |
+| 4+ files modified | ⚠️ Decompose |
+| Estimated cost ≤ $0.30 | ✅ Ready to issue |
+| Estimated cost > $0.30 | ⚠️ Decompose |
+| Backend + frontend together | ⚠️ Separate + depends_on |
+| Cannot verify with `tsc --noEmit` | ⚠️ Redefine AC |
+
+---
+
+## Failure Handling
+
+When AC fails after agent completion report:
+
+```
+1st failure → Re-issue with error details (same thread)
+2nd failure → STOP, escalate to user
+              → Rollback WI status to draft, redesign
+```
+
+**Two consecutive failures on the same error signals the WI itself needs rewriting.**
+
+---
+
+## References
+
+- Template: [docs/wi/WI-TEMPLATE.md](../../docs/wi/WI-TEMPLATE.md)
+- PM guide: [skills/pm/SKILL.md](../pm/SKILL.md)
+- Decomposition strategy: [docs/research/multi-agent-divide-conquer.md](../../docs/research/multi-agent-divide-conquer.md)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function main(inputArgs?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AAqDA,wBAAsB,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B9D"}

package/dist/cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let PKG_VERSION = 'unknown';
+try {
+    const _pkgPath = fs.existsSync(path.join(__dirname, 'package.json'))
+        ? path.join(__dirname, 'package.json')
+        : path.join(__dirname, '..', 'package.json');
+    const _pkg = JSON.parse(fs.readFileSync(_pkgPath, 'utf-8'));
+    if (_pkg?.version)
+        PKG_VERSION = String(_pkg.version);
+}
+catch { }
+async function loadTracer() {
+    try {
+        return await Promise.resolve().then(() => __importStar(require('@crewx/shared/skill-tracer')));
+    }
+    catch {
+        return null;
+    }
+}
+function showDetailedUsage() {
+    const skillMd = path.join(__dirname, '..', 'SKILL.md');
+    if (fs.existsSync(skillMd)) {
+        process.stdout.write(fs.readFileSync(skillMd, 'utf-8'));
+    }
+    else {
+        console.log('No SKILL.md found. Use --help for usage.');
+    }
+}
+function printUsage() {
+    console.log(`
+@crewx/wi@${PKG_VERSION} - Structured task delegation via Work Instructions
+
+Usage:
+  wi <command> [args]
+
+Commands:
+  wi usage                               Show detailed guide (SKILL.md)
+  wi draft <description>                 Draft a new Work Instruction (planned)
+  wi issue <WI-ID>                       Issue WI to assigned agent (planned)
+  wi list [--status=...]                 List Work Instructions (planned)
+  wi review <WI-ID>                      Request lead review (planned)
+
+Options:
+  --version                              Show version
+  --help, -h                             Show this help
+
+Note:
+  Phase 1 — only 'usage' is available. Other subcommands are planned.
+
+Template: docs/wi/WI-TEMPLATE.md
+For detailed usage guide: wi usage
+`);
+}
+async function main(inputArgs) {
+    const args = inputArgs ?? process.argv.slice(2);
+    const command = args[0];
+    if (args.includes('--version')) {
+        console.log(PKG_VERSION);
+        return;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        printUsage();
+        return;
+    }
+    if (command === 'usage') {
+        showDetailedUsage();
+        return;
+    }
+    if (command === 'draft' || command === 'issue' || command === 'list' || command === 'review') {
+        console.log(`\n  '${command}' is not yet implemented (Phase 1).\n`);
+        console.log(`  Run 'wi usage' for the full guide.\n`);
+        return;
+    }
+    printUsage();
+}
+if (require.main === module) {
+    loadTracer().then(tracer => {
+        const opts = tracer ? { skillVersion: tracer.getOwnSkillVersion(__dirname) } : {};
+        return tracer ? tracer.run('crewx/wi', () => main(), opts) : main();
+    }).catch((e) => {
+        console.error(e.message);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,oBA0BC;AA7ED,uCAAyB;AACzB,2CAA6B;AAE7B,IAAI,WAAW,GAAG,SAAS,CAAC;AAC5B,IAAI,CAAC;IACH,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAClE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC;QACtC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5D,IAAI,IAAI,EAAE,OAAO;QAAE,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC;AAAC,MAAM,CAAC,CAAA,CAAC;AAEV,KAAK,UAAU,UAAU;IACvB,IAAI,CAAC;QAAC,OAAO,wDAAa,4BAA4B,GAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;AACnF,CAAC;AAED,SAAS,iBAAiB;IACxB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACvD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,CAAC,GAAG,CAAC;YACF,WAAW;;;;;;;;;;;;;;;;;;;;;CAqBtB,CAAC,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,IAAI,CAAC,SAAoB;IAC7C,MAAM,IAAI,GAAG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,UAAU,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,iBAAiB,EAAE,CAAC;QACpB,OAAO;IACT,CAAC;IAED,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC7F,OAAO,CAAC,GAAG,CAAC,QAAQ,OAAO,uCAAuC,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;QACtD,OAAO;IACT,CAAC;IAED,UAAU,EAAE,CAAC;AACf,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,UAAU,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;QACzB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAQ,EAAE,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@crewx/wi",
+  "version": "0.1.0",
+  "description": "Work Instruction engine for CrewX - structured task delegation",
+  "type": "commonjs",
+  "main": "dist/cli.js",
+  "exports": {
+    ".": {
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.js",
+      "default": "./dist/cli.js"
+    },
+    "./cli": {
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.js",
+      "default": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "wi": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "templates/"
+  ],
+  "dependencies": {
+    "@crewx/shared": "0.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}

package/templates/WI-TEMPLATE.md

@@ -0,0 +1,153 @@
+---
+wi_id: WI-{YYYYMMDD}-{SEQ}
+title: ""
+date: ""
+author: ""
+status: draft          # draft | approved | in-progress | done | cancelled
+priority: normal       # critical | high | normal | low
+
+# Assignment
+assignee: ""           # Agent assigned to this work
+reviewer: ""           # Agent to review
+
+# Git
+base_branch: main
+target_branch: develop
+worktree: false        # true = work in isolated worktree
+
+# Design doc cross-link
+spec_id: ""            # Design doc API ID (e.g. MSG.LIST)
+design_doc: ""
+design_section: ""
+screens: []            # Affected screen IDs (e.g. THDUI002)
+
+# Dependencies
+depends_on: []         # WI IDs that must complete before this starts
+blocks: []             # WI IDs blocked by this WI
+
+# Impact
+risk_level: low        # low | medium | high | critical
+api_changed: false     # if true, contract_type + consumers required
+contract_type: none    # none | additive | breaking | deprecation
+schema_changed: false  # if true, check migration needs
+
+# Consumers (required when api_changed: true)
+consumers:
+  # - screen: THDUI002
+  #   file: src/ui/pages/threads/ThreadDetailPage.tsx
+  #   store: useThreadDetailStore
+  #   component: MessageBubble
+
+# Estimated scope (atomicity: ≤ $0.30, 1-3 files)
+estimated_files: 0
+estimated_cost: "$0.00"
+---
+
+# {title}
+
+## Background (Why)
+
+> Why this work is needed. 1-3 sentences.
+
+## Goal (What)
+
+> What changes when this is complete. Feature perspective.
+
+## Scope
+
+### Files to modify
+
+| File | Description |
+|------|-------------|
+| `path/to/file.ts` | description |
+
+**Out of scope (do not touch)**
+
+- list items
+
+## Impact Analysis
+
+### Design doc cross-link
+
+> Summary of the relevant design doc section.
+
+```bash
+npx doc section {design_doc} "{spec_id}"
+```
+
+| Item | Value |
+|------|-------|
+| API ID | `{spec_id}` |
+| Screen ID | `{screens}` |
+| Section | `{design_section}` |
+
+### API / Type changes
+
+> Skip this section if `api_changed: false`.
+
+| Changed item | contract_type | Consumers (screen / file / store) |
+|-------------|--------------|-----------------------------------|
+| (none) | - | - |
+
+### Consumer impact checklist
+
+> Required when `api_changed: true`. Empty = cannot approve.
+
+- [ ] Affected screen IDs identified (`screens` field)
+- [ ] Affected frontend components identified (`consumers.component`)
+- [ ] Affected stores identified (`consumers.store`)
+- [ ] If `contract_type: breaking`, issue separate consumer WI (add to `blocks`)
+- [ ] DB schema change migration: (none / Phase N needed)
+
+### Side-effect risk areas
+
+> Areas that broke in similar past work. "None" if none.
+
+### risk_level criteria
+
+| Level | Condition |
+|-------|-----------|
+| `low` | Single file, no API change, existing tests sufficient |
+| `medium` | 2-3 files, API change with ≤ 1 consumer |
+| `high` | API change + 2+ consumers, or store refactoring |
+| `critical` | DB schema change, or core SDK interface change |
+
+> `high` or above: consult lead before implementation.
+
+---
+
+## Implementation Guide (How)
+
+> Concrete instructions an agent can follow without judgment calls.
+> Include code examples, type definitions, caveats.
+
+```typescript
+// Example code (if applicable)
+```
+
+## Acceptance Criteria (AC)
+
+> All must pass to mark "done". If any fails, STOP and report.
+
+- [ ] `npx tsc --noEmit` passes
+- [ ] `npx vitest run src/server/` passes (backend work)
+- [ ] `npx vitest run src/ui/` passes (frontend work)
+- [ ] (add feature-specific AC)
+
+## Completion Report Format
+
+```
+## Completion Report
+
+### Modified files
+- path/to/file.ts (+N/-M)
+
+### tsc result
+Pass / Fail
+
+### Test result
+N tests passed
+
+### Remaining items
+None / (list if any)
+```