@nahisaho/shikigami 2.0.4 → 2.0.6

package/scripts/build-cowork-plugin.js

@@ -0,0 +1,859 @@
+#!/usr/bin/env node
+/**
+ * SHIKIGAMI Cowork Plugin Builder
+ * 
+ * Builds a Microsoft 365 Copilot Cowork plugin package (.zip)
+ * from SHIKIGAMI's Agent Skills following the official "Build from scratch" guide.
+ * 
+ * Usage: npx shikigami cowork [options]
+ *   --out <dir>     Output directory (default: ./dist)
+ *   --check         Dry-run validation only
+ *   --help          Show help
+ * 
+ * Reference: https://learn.microsoft.com/microsoft-365/copilot/cowork/cowork-plugin-development
+ * 
+ * Cross-platform: The same SKILL.md files work in GitHub Copilot CLI,
+ * VS Code Copilot, Claude Code, Gemini CLI, and Copilot Cowork.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const MAX_COMPANIONS_PER_SKILL = 20;
+const MAX_COMPANION_SIZE = 5 * 1024 * 1024; // 5 MB
+const MAX_COMPANION_TOTAL = 10 * 1024 * 1024; // 10 MB per skill
+const MAX_SKILLS = 20;
+const MAX_FOLDER_PATH = 256;
+const RECOMMENDED_BODY_WORDS = 3000;
+
+const PACKAGE_NAME = 'com.nahisaho.shikigami';
+const APP_ID = 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d';
+const ACCENT_COLOR = '#6B46C1';
+
+const WINDOWS_RESERVED = new Set([
+  'CON', 'PRN', 'AUX', 'NUL',
+  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+]);
+
+const SAFE_FILENAME_RE = /^[a-zA-Z0-9\-_. !]+$/;
+
+// Cowork-specific frontmatter defaults per skill
+const COWORK_DEFAULTS = {
+  'shikigami-planner': { category: 'Research', icon: 'Lightbulb' },
+  'shikigami-deep-research': { category: 'Research', icon: 'Search' },
+  'shikigami-consulting-framework': { category: 'Analysis', icon: 'Briefcase' },
+  'shikigami-writing': { category: 'Writing', icon: 'DocumentBulletList' },
+};
+
+// ── Minimal PNG generator (no dependencies) ───────────────────────────────
+
+function createMinimalPNG(width, height, r, g, b) {
+  const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+  function crc32(buf) {
+    let crc = 0xFFFFFFFF;
+    const table = new Int32Array(256);
+    for (let i = 0; i < 256; i++) {
+      let c = i;
+      for (let j = 0; j < 8; j++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+      table[i] = c;
+    }
+    for (let i = 0; i < buf.length; i++) {
+      crc = table[(crc ^ buf[i]) & 0xFF] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+  }
+
+  function makeChunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const typeAndData = Buffer.concat([Buffer.from(type), data]);
+    const crcBuf = Buffer.alloc(4);
+    crcBuf.writeUInt32BE(crc32(typeAndData));
+    return Buffer.concat([len, typeAndData, crcBuf]);
+  }
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = 2; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+
+  const rowSize = 1 + width * 3;
+  const rawData = Buffer.alloc(rowSize * height);
+  for (let y = 0; y < height; y++) {
+    rawData[y * rowSize] = 0;
+    for (let x = 0; x < width; x++) {
+      const offset = y * rowSize + 1 + x * 3;
+      rawData[offset] = r;
+      rawData[offset + 1] = g;
+      rawData[offset + 2] = b;
+    }
+  }
+
+  const zlib = require('zlib');
+  const compressed = zlib.deflateSync(rawData);
+
+  return Buffer.concat([
+    signature,
+    makeChunk('IHDR', ihdr),
+    makeChunk('IDAT', compressed),
+    makeChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+// ── YAML Frontmatter Parser ───────────────────────────────────────────────
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const yaml = match[1];
+  const result = {};
+  let currentKey = null;
+  let blockLines = [];
+  let inBlock = false;
+  let currentIndent = 0;
+  let mapKey = null;
+  let mapObj = null;
+
+  function flushBlock() {
+    if (inBlock && currentKey) {
+      result[currentKey] = blockLines.join('\n').trim();
+      inBlock = false;
+      blockLines = [];
+    }
+    if (mapKey && mapObj) {
+      result[mapKey] = mapObj;
+      mapKey = null;
+      mapObj = null;
+    }
+  }
+
+  for (const line of yaml.split('\n')) {
+    // Handle block scalar continuation
+    if (inBlock) {
+      if (line.match(/^\s{2,}/) || line.trim() === '') {
+        blockLines.push(line.replace(/^\s{2}/, ''));
+        continue;
+      } else {
+        flushBlock();
+      }
+    }
+
+    // Handle map continuation (metadata:, cowork: style)
+    if (mapKey && line.match(/^\s{2,}\w/)) {
+      const kvMatch = line.trim().match(/^(\w[\w.-]*)\s*:\s*(.*)/);
+      if (kvMatch) {
+        mapObj[kvMatch[1]] = kvMatch[2].trim().replace(/^["']|["']$/g, '');
+        continue;
+      }
+    } else if (mapKey) {
+      flushBlock();
+    }
+
+    // Top-level key: value
+    const kvMatch = line.match(/^(\w[\w.-]*)\s*:\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      const value = kvMatch[2].trim();
+      if (value === '|' || value === '>') {
+        inBlock = true;
+        blockLines = [];
+      } else if (value === '') {
+        // Could be a map start (metadata:, cowork:)
+        mapKey = currentKey;
+        mapObj = {};
+      } else {
+        result[currentKey] = value.replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+
+  flushBlock();
+  return result;
+}
+
+function extractBody(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)/);
+  return match ? match[1].trim() : content;
+}
+
+// ── Companion File Path Validation ────────────────────────────────────────
+
+function validateCompanionPath(relPath) {
+  const errors = [];
+  const parts = relPath.split('/');
+
+  // No absolute paths
+  if (path.isAbsolute(relPath)) {
+    errors.push(`Absolute path not allowed: ${relPath}`);
+  }
+  // No path traversal
+  if (parts.includes('..')) {
+    errors.push(`Path traversal (..) not allowed: ${relPath}`);
+  }
+  // No backslashes or null bytes
+  if (relPath.includes('\\') || relPath.includes('\0')) {
+    errors.push(`Backslash or null byte in path: ${relPath}`);
+  }
+
+  for (const part of parts) {
+    // No hidden files
+    if (part.startsWith('.')) {
+      errors.push(`Hidden file not allowed: ${relPath}`);
+    }
+    // No Windows reserved names
+    const baseName = part.replace(/\.[^.]*$/, '').toUpperCase();
+    if (WINDOWS_RESERVED.has(baseName)) {
+      errors.push(`Windows reserved name: ${part} in ${relPath}`);
+    }
+    // Safe characters only
+    if (!SAFE_FILENAME_RE.test(part)) {
+      errors.push(`Unsafe characters in filename: ${part} in ${relPath}`);
+    }
+  }
+
+  return errors;
+}
+
+// ── Companion File Consolidation ──────────────────────────────────────────
+
+function discoverCompanions(skillDir) {
+  const allFiles = [];
+
+  function walkDir(dir, prefix) {
+    if (!fs.existsSync(dir)) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue; // skip hidden
+      const fullPath = path.join(dir, entry.name);
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walkDir(fullPath, relPath);
+      } else if (entry.name !== 'SKILL.md') {
+        allFiles.push({ fullPath, relPath, name: entry.name });
+      }
+    }
+  }
+
+  walkDir(skillDir, '');
+  return allFiles;
+}
+
+function consolidateCompanions(allFiles, skillName) {
+  if (allFiles.length <= MAX_COMPANIONS_PER_SKILL) {
+    return allFiles.map(f => ({
+      relativePath: f.relPath,
+      content: fs.readFileSync(f.fullPath),
+    }));
+  }
+
+  const files = [];
+
+  // Group by top-level directory
+  const topGroups = {};
+  for (const f of allFiles) {
+    const topDir = f.relPath.split('/')[0] || '_root';
+    if (!topGroups[topDir]) topGroups[topDir] = [];
+    topGroups[topDir].push(f);
+  }
+
+  for (const [dir, dirFiles] of Object.entries(topGroups)) {
+    if (dir === '_root') {
+      for (const f of dirFiles) {
+        files.push({
+          relativePath: f.relPath,
+          content: fs.readFileSync(f.fullPath),
+        });
+      }
+      continue;
+    }
+
+    // Check if sub-directory grouping keeps within limits
+    const subGroups = {};
+    for (const f of dirFiles) {
+      const parts = f.relPath.split('/');
+      const subKey = parts.length > 1 ? parts[1] : '_direct';
+      if (!subGroups[subKey]) subGroups[subKey] = [];
+      subGroups[subKey].push(f);
+    }
+
+    // If sub-grouping fits, use it; otherwise consolidate entire directory
+    if (Object.keys(subGroups).length <= MAX_COMPANIONS_PER_SKILL - files.length) {
+      for (const [sub, subFiles] of Object.entries(subGroups)) {
+        let consolidated = `# ${dir}/${sub}\n\nConsolidated reference for ${skillName}.\n\n`;
+        for (const f of subFiles) {
+          const content = fs.readFileSync(f.fullPath, 'utf-8');
+          const basename = path.basename(f.name, path.extname(f.name));
+          consolidated += `---\n\n## ${basename}\n\n${content}\n\n`;
+        }
+        files.push({
+          relativePath: `references/${dir}-${sub}.md`,
+          content: Buffer.from(consolidated, 'utf-8'),
+        });
+      }
+    } else {
+      // Consolidate entire top-level directory into one file
+      let consolidated = `# ${dir}\n\nConsolidated reference for ${skillName}.\n\n`;
+      for (const f of dirFiles) {
+        const content = fs.readFileSync(f.fullPath, 'utf-8');
+        const basename = path.basename(f.name, path.extname(f.name));
+        consolidated += `---\n\n## ${basename}\n\n${content}\n\n`;
+      }
+
+      const consolidatedBuf = Buffer.from(consolidated, 'utf-8');
+
+      // Chunk if exceeds 5MB
+      if (consolidatedBuf.length > MAX_COMPANION_SIZE) {
+        const lines = consolidated.split('\n');
+        let chunk = [];
+        let chunkSize = 0;
+        let chunkIdx = 1;
+        for (const line of lines) {
+          const lineSize = Buffer.byteLength(line + '\n', 'utf-8');
+          if (chunkSize + lineSize > MAX_COMPANION_SIZE * 0.9 && chunk.length > 0) {
+            files.push({
+              relativePath: `references/${dir}-${String(chunkIdx).padStart(2, '0')}.md`,
+              content: Buffer.from(chunk.join('\n'), 'utf-8'),
+            });
+            chunk = [];
+            chunkSize = 0;
+            chunkIdx++;
+          }
+          chunk.push(line);
+          chunkSize += lineSize;
+        }
+        if (chunk.length > 0) {
+          files.push({
+            relativePath: `references/${dir}-${String(chunkIdx).padStart(2, '0')}.md`,
+            content: Buffer.from(chunk.join('\n'), 'utf-8'),
+          });
+        }
+      } else {
+        files.push({
+          relativePath: `references/${dir}.md`,
+          content: consolidatedBuf,
+        });
+      }
+    }
+  }
+
+  return files;
+}
+
+// ── SKILL.md Rewriter for Cowork ──────────────────────────────────────────
+
+function rewriteSkillMdForCowork(content, originalCompanions, packagedCompanions, skillName) {
+  /**
+   * Creates a Cowork-compatible version of SKILL.md:
+   * 1. Adds cowork.category and cowork.icon to frontmatter if missing
+   * 2. Adds metadata.author and metadata.version if missing
+   * 3. Updates file path references to match consolidated paths
+   * 4. Adds "Additional Resources" section listing companion files
+   */
+  let result = content;
+
+  // Update frontmatter with Cowork fields
+  const fmMatch = result.match(/^(---\n)([\s\S]*?)(\n---)/);
+  if (fmMatch) {
+    let fm = fmMatch[2];
+    const defaults = COWORK_DEFAULTS[skillName] || {};
+
+    if (!fm.includes('cowork.category') && defaults.category) {
+      fm += `\ncowork.category: ${defaults.category}`;
+    }
+    if (!fm.includes('cowork.icon') && defaults.icon) {
+      fm += `\ncowork.icon: ${defaults.icon}`;
+    }
+    if (!fm.includes('metadata:')) {
+      fm += `\nmetadata:\n  author: nahisaho\n  version: "2.0"`;
+    }
+
+    result = `${fmMatch[1]}${fm}${fmMatch[3]}${result.slice(fmMatch[0].length)}`;
+  }
+
+  // Build path mapping: original -> consolidated
+  if (originalCompanions.length > MAX_COMPANIONS_PER_SKILL) {
+    const pathMap = {};
+    for (const orig of originalCompanions) {
+      const topDir = orig.relPath.split('/')[0];
+      const consolidated = packagedCompanions.find(
+        p => p.relativePath.startsWith(`references/${topDir}`)
+      );
+      if (consolidated) {
+        pathMap[orig.relPath] = consolidated.relativePath;
+      }
+    }
+
+    // Replace file path references in body
+    for (const [origPath, newPath] of Object.entries(pathMap)) {
+      result = result.replace(new RegExp(escapeRegex(origPath), 'g'), newPath);
+    }
+  }
+
+  // Add Additional Resources section if companions exist and not already present
+  if (packagedCompanions.length > 0 && !result.includes('## Additional Resources')) {
+    let resources = '\n\n## Additional Resources\n\n';
+    for (const c of packagedCompanions) {
+      const name = path.basename(c.relativePath, path.extname(c.relativePath));
+      resources += `- **\`${c.relativePath}\`** — ${name}\n`;
+    }
+    result += resources;
+  }
+
+  return result;
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ── ZIP Builder ───────────────────────────────────────────────────────────
+
+function createZip(outputPath, files) {
+  const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'shikigami-cowork-'));
+
+  try {
+    for (const file of files) {
+      const filePath = path.join(tmpDir, file.path);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      if (Buffer.isBuffer(file.content)) {
+        fs.writeFileSync(filePath, file.content);
+      } else {
+        fs.writeFileSync(filePath, file.content, 'utf-8');
+      }
+    }
+
+    const absOutput = path.resolve(outputPath);
+    try {
+      execFileSync('zip', ['-r', absOutput, '.'], { cwd: tmpDir, stdio: 'pipe' });
+    } catch {
+      // Fallback: PowerShell (Windows)
+      try {
+        execFileSync('powershell', [
+          '-Command',
+          `Compress-Archive -Path '${tmpDir}${path.sep}*' -DestinationPath '${absOutput}' -Force`
+        ], { stdio: 'pipe' });
+      } catch {
+        console.error('❌ zip command not found. Install zip or use PowerShell on Windows.');
+        process.exit(1);
+      }
+    }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ── Manifest Generator ─────────────────────────────────────────────────────
+
+function generateManifest(skills, version) {
+  return {
+    '$schema': 'https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json',
+    manifestVersion: 'devPreview',
+    version: version,
+    id: APP_ID,
+    packageName: PACKAGE_NAME,
+    developer: {
+      name: 'nahisaho',
+      websiteUrl: 'https://github.com/nahisaho/SHIKIGAMI',
+      privacyUrl: 'https://github.com/nahisaho/SHIKIGAMI/blob/main/LICENSE',
+      termsOfUseUrl: 'https://github.com/nahisaho/SHIKIGAMI/blob/main/LICENSE',
+    },
+    name: {
+      short: 'SHIKIGAMI',
+      full: 'SHIKIGAMI - Deep Research & Consulting Agent Skills',
+    },
+    description: {
+      short: 'AI-powered deep research and consulting framework analysis',
+      full: 'SHIKIGAMI provides 4 specialized Agent Skills: '
+        + 'deep research with hallucination prevention, 50+ consulting frameworks '
+        + '(SWOT, PEST, 5Forces, BCG Matrix, etc.), structured report writing, '
+        + 'and project planning with 5 Whys/JTBD purpose discovery. '
+        + 'Cross-platform compatible with GitHub Copilot CLI, VS Code, Claude Code, and Gemini CLI.',
+    },
+    icons: {
+      color: 'color.png',
+      outline: 'outline.png',
+    },
+    accentColor: ACCENT_COLOR,
+    agentSkills: skills.map(s => ({ folder: `./skills/${s.name}` })),
+  };
+}
+
+// ── Validation (ASKILL codes from official docs) ──────────────────────────
+
+function validateManifest(manifest) {
+  const errors = [];
+
+  // ASKILL-M001: folder required in each agentSkills entry
+  for (const skill of manifest.agentSkills || []) {
+    if (!skill.folder) {
+      errors.push('[ASKILL-M001] `folder` is required for each agentSkills entry');
+    }
+  }
+
+  // ASKILL-M002: max 20 skills
+  if ((manifest.agentSkills || []).length > MAX_SKILLS) {
+    errors.push(`[ASKILL-M002] Max ${MAX_SKILLS} agentSkills entries (found ${manifest.agentSkills.length})`);
+  }
+
+  // ASKILL-M003: folder path max 256 chars
+  for (const skill of manifest.agentSkills || []) {
+    if (skill.folder && skill.folder.length > MAX_FOLDER_PATH) {
+      errors.push(`[ASKILL-M003] Folder path exceeds ${MAX_FOLDER_PATH} chars: ${skill.folder}`);
+    }
+  }
+
+  // ASKILL-P008: no duplicate folder values
+  const folders = (manifest.agentSkills || []).map(s => s.folder);
+  const dupes = folders.filter((f, i) => folders.indexOf(f) !== i);
+  if (dupes.length > 0) {
+    errors.push(`[ASKILL-P008] Duplicate folder values: ${[...new Set(dupes)].join(', ')}`);
+  }
+
+  // GUID format
+  if (!manifest.id || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(manifest.id)) {
+    errors.push('[Manifest] Invalid GUID format for id');
+  }
+
+  return errors;
+}
+
+function validateSkill(skillDir, skillName) {
+  const errors = [];
+  const warnings = [];
+
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillMdPath)) {
+    // ASKILL-P002
+    errors.push(`[ASKILL-P002] SKILL.md not found in ${skillName}`);
+    return { errors, warnings };
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf-8');
+  const frontmatter = parseFrontmatter(content);
+
+  // ASKILL-P003: valid YAML frontmatter
+  if (!frontmatter) {
+    errors.push(`[ASKILL-P003] No valid YAML frontmatter in ${skillName}/SKILL.md`);
+    return { errors, warnings };
+  }
+
+  // ASKILL-P004: name field required
+  if (!frontmatter.name) {
+    errors.push(`[ASKILL-P004] Missing 'name' field in ${skillName}/SKILL.md frontmatter`);
+  } else {
+    // ASKILL-P006: name matches folder name
+    if (frontmatter.name !== skillName) {
+      errors.push(`[ASKILL-P006] Frontmatter name '${frontmatter.name}' doesn't match folder '${skillName}'`);
+    }
+    // ASKILL-P007: name is kebab-case, 1-64 chars
+    if (frontmatter.name.length > 64) {
+      errors.push(`[ASKILL-P007] Name exceeds 64 characters: ${frontmatter.name}`);
+    }
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(frontmatter.name)) {
+      errors.push(`[ASKILL-P007] Name must be kebab-case: ${frontmatter.name}`);
+    }
+  }
+
+  // ASKILL-P005: description field required, 1-1024 chars
+  if (!frontmatter.description) {
+    errors.push(`[ASKILL-P005] Missing 'description' field in ${skillName}/SKILL.md frontmatter`);
+  } else if (frontmatter.description.length > 1024) {
+    errors.push(`[ASKILL-P005] Description exceeds 1024 characters (${frontmatter.description.length}) in ${skillName}`);
+  }
+
+  // Body size warning
+  const body = extractBody(content);
+  const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+  if (wordCount > RECOMMENDED_BODY_WORDS) {
+    warnings.push(`${skillName}: SKILL.md body is ~${wordCount} words (recommended <${RECOMMENDED_BODY_WORDS}). Consider moving details to references/`);
+  }
+
+  // Discover and validate companion files
+  const originalCompanions = discoverCompanions(skillDir);
+
+  // Validate companion file paths
+  for (const f of originalCompanions) {
+    const pathErrors = validateCompanionPath(f.relPath);
+    for (const e of pathErrors) {
+      errors.push(`[Companion] ${skillName}: ${e}`);
+    }
+  }
+
+  // Consolidate companions for packaging
+  const packagedCompanions = consolidateCompanions(originalCompanions, skillName);
+
+  // Validate consolidated results
+  if (packagedCompanions.length > MAX_COMPANIONS_PER_SKILL) {
+    errors.push(`[Companion] ${skillName}: ${packagedCompanions.length} files after consolidation (max ${MAX_COMPANIONS_PER_SKILL})`);
+  }
+
+  const totalSize = packagedCompanions.reduce((sum, f) => sum + f.content.length, 0);
+  if (totalSize > MAX_COMPANION_TOTAL) {
+    errors.push(`[Companion] ${skillName}: Total size ${(totalSize / 1024 / 1024).toFixed(1)}MB exceeds 10MB limit`);
+  }
+
+  for (const f of packagedCompanions) {
+    if (f.content.length > MAX_COMPANION_SIZE) {
+      errors.push(`[Companion] ${skillName}: ${f.relativePath} exceeds 5MB limit`);
+    }
+    // Validate packaged paths too
+    const pathErrors = validateCompanionPath(f.relativePath);
+    for (const e of pathErrors) {
+      errors.push(`[Companion] ${skillName}: ${e}`);
+    }
+  }
+
+  return { errors, warnings, originalCompanions, packagedCompanions, frontmatter, content };
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  return {
+    out: args.includes('--out') ? args[args.indexOf('--out') + 1] : './dist',
+    check: args.includes('--check') || args.includes('--dry-run'),
+    help: args.includes('--help') || args.includes('-h'),
+  };
+}
+
+function showHelp() {
+  console.log(`
+🎭 SHIKIGAMI Cowork Plugin Builder
+
+Builds a Microsoft 365 Copilot Cowork plugin package (.zip)
+following the official "Build a plugin from scratch" guide.
+
+Usage: npx shikigami cowork [options]
+
+Options:
+  --out <dir>     Output directory (default: ./dist)
+  --check         Validation only (dry-run)
+  -h, --help      Show this help
+
+Steps (per official docs):
+  1. Discover & validate SKILL.md files (frontmatter, naming, paths)
+  2. Consolidate companion files (max 20 per skill)
+  3. Rewrite SKILL.md for Cowork (add cowork.category, cowork.icon, metadata)
+  4. Generate manifest.json (M365 Unified App Manifest devPreview)
+  5. Generate icons (color.png 192×192, outline.png 32×32)
+  6. Create .zip package
+
+Cross-platform:
+  Same SKILL.md files work in GitHub Copilot CLI, VS Code Copilot,
+  Claude Code, Gemini CLI, Cursor, JetBrains Junie, and Copilot Cowork.
+
+Reference:
+  https://learn.microsoft.com/microsoft-365/copilot/cowork/cowork-plugin-development
+`);
+}
+
+function build() {
+  const { out, check, help } = parseArgs();
+
+  if (help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log('🎭 SHIKIGAMI Cowork Plugin Builder');
+  console.log('====================================');
+  console.log('');
+
+  // ── Step 0: Locate skills directory ──
+  const packageDir = path.resolve(__dirname, '..');
+  let skillsRoot = path.join(packageDir, 'github-assets', 'skills');
+
+  if (!fs.existsSync(skillsRoot)) {
+    skillsRoot = path.join(packageDir, '.github', 'skills');
+  }
+  if (!fs.existsSync(skillsRoot)) {
+    skillsRoot = path.join(process.cwd(), '.github', 'skills');
+  }
+
+  if (!fs.existsSync(skillsRoot)) {
+    console.error('❌ Skills directory not found.');
+    console.error('   Run `npx shikigami init` first to copy skills to your project.');
+    process.exit(1);
+  }
+
+  let version = '1.0.0';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'));
+    version = pkg.version || version;
+  } catch { /* ignore */ }
+
+  // ── Step 1: Discover & validate skills ──
+  console.log('Step 1: Discovering and validating skills...');
+  console.log(`📂 Skills root: ${skillsRoot}`);
+  console.log('');
+
+  const skillDirs = fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter(d => d.isDirectory() && d.name.startsWith('shikigami-'))
+    .map(d => d.name);
+
+  if (skillDirs.length === 0) {
+    console.error('❌ No skills found (expected shikigami-* directories)');
+    process.exit(1);
+  }
+
+  let hasErrors = false;
+  const validatedSkills = [];
+
+  for (const skillName of skillDirs) {
+    const skillDir = path.join(skillsRoot, skillName);
+    const result = validateSkill(skillDir, skillName);
+
+    if (result.errors.length > 0) {
+      hasErrors = true;
+      for (const err of result.errors) console.log(`  ❌ ${err}`);
+    }
+    for (const warn of result.warnings) console.log(`  ⚠️  ${warn}`);
+
+    if (result.errors.length === 0) {
+      const origCount = result.originalCompanions ? result.originalCompanions.length : 0;
+      const pkgCount = result.packagedCompanions ? result.packagedCompanions.length : 0;
+      const consolidatedNote = origCount > MAX_COMPANIONS_PER_SKILL
+        ? ` (consolidated ${origCount} → ${pkgCount})`
+        : '';
+      console.log(`  ✅ ${skillName} (${pkgCount} companion files${consolidatedNote})`);
+      validatedSkills.push({
+        name: skillName,
+        dir: skillDir,
+        originalCompanions: result.originalCompanions,
+        packagedCompanions: result.packagedCompanions,
+        frontmatter: result.frontmatter,
+        content: result.content,
+      });
+    }
+  }
+
+  console.log('');
+
+  if (hasErrors) {
+    console.error('❌ Validation failed. Fix errors above before building.');
+    process.exit(1);
+  }
+
+  if (validatedSkills.length > MAX_SKILLS) {
+    console.error(`❌ [ASKILL-M002] Too many skills: ${validatedSkills.length} (max ${MAX_SKILLS})`);
+    process.exit(1);
+  }
+
+  // ── Manifest validation ──
+  const manifest = generateManifest(validatedSkills, version);
+  const manifestErrors = validateManifest(manifest);
+  if (manifestErrors.length > 0) {
+    hasErrors = true;
+    for (const err of manifestErrors) console.log(`  ❌ ${err}`);
+  }
+
+  if (hasErrors) {
+    console.error('❌ Manifest validation failed.');
+    process.exit(1);
+  }
+
+  if (check) {
+    console.log('✅ Validation passed (dry-run mode)');
+    console.log(`   ${validatedSkills.length} skills ready for packaging`);
+    console.log('');
+    console.log('Cross-platform compatibility:');
+    console.log('   ✅ GitHub Copilot CLI');
+    console.log('   ✅ VS Code Copilot');
+    console.log('   ✅ Microsoft 365 Copilot Cowork');
+    console.log('   ✅ Claude Code / Gemini CLI / Cursor');
+    process.exit(0);
+  }
+
+  // ── Step 2-5: Build package ──
+  console.log('Step 2: Building Cowork plugin package...');
+
+  const zipFiles = [];
+
+  // Step 4: manifest.json
+  zipFiles.push({
+    path: 'manifest.json',
+    content: JSON.stringify(manifest, null, 2),
+  });
+  console.log('  ✅ manifest.json');
+
+  // Step 5: Icons
+  const colorPng = createMinimalPNG(192, 192, 107, 70, 193);
+  const outlinePng = createMinimalPNG(32, 32, 107, 70, 193);
+  zipFiles.push({ path: 'color.png', content: colorPng });
+  zipFiles.push({ path: 'outline.png', content: outlinePng });
+  console.log('  ✅ color.png (192×192)');
+  console.log('  ✅ outline.png (32×32)');
+
+  // Steps 1-2: Skills with Cowork-specific SKILL.md
+  for (const skill of validatedSkills) {
+    // Rewrite SKILL.md for Cowork (add metadata, category, icon, update paths)
+    const rewrittenSkillMd = rewriteSkillMdForCowork(
+      skill.content,
+      skill.originalCompanions,
+      skill.packagedCompanions,
+      skill.name
+    );
+
+    zipFiles.push({
+      path: `skills/${skill.name}/SKILL.md`,
+      content: rewrittenSkillMd,
+    });
+
+    // Copy companion files (already consolidated)
+    for (const companion of skill.packagedCompanions) {
+      zipFiles.push({
+        path: `skills/${skill.name}/${companion.relativePath}`,
+        content: companion.content,
+      });
+    }
+
+    console.log(`  ✅ skills/${skill.name}/ (${skill.packagedCompanions.length + 1} files)`);
+  }
+
+  // ── Step 6: Create ZIP ──
+  console.log('');
+  console.log('Step 3: Creating ZIP package...');
+
+  const outDir = path.resolve(out);
+  fs.mkdirSync(outDir, { recursive: true });
+  const zipPath = path.join(outDir, 'shikigami-cowork-plugin.zip');
+
+  if (fs.existsSync(zipPath)) {
+    fs.unlinkSync(zipPath);
+  }
+
+  createZip(zipPath, zipFiles);
+
+  const zipSize = fs.statSync(zipPath).size;
+  console.log('');
+  console.log('✅ Plugin package created!');
+  console.log('');
+  console.log(`  📦 ${zipPath}`);
+  console.log(`  📏 Size: ${(zipSize / 1024).toFixed(1)} KB`);
+  console.log(`  🔧 Skills: ${validatedSkills.length}`);
+  console.log(`  📋 Version: ${version}`);
+  console.log('');
+  console.log('Cross-platform compatibility:');
+  console.log('  ✅ GitHub Copilot CLI  — use `npx shikigami init`');
+  console.log('  ✅ VS Code Copilot    — same SKILL.md format');
+  console.log('  ✅ Copilot Cowork     — upload .zip to M365 Admin Center');
+  console.log('  ✅ Claude Code        — same SKILL.md format');
+  console.log('');
+  console.log('📝 Next steps (Copilot Cowork):');
+  console.log('  1. Open M365 Admin Center > Manage Apps > Upload Custom App');
+  console.log('  2. Upload shikigami-cowork-plugin.zip');
+  console.log('  3. Open Cowork > Sources & Skills to verify');
+  console.log('');
+  console.log('📖 https://learn.microsoft.com/microsoft-365/copilot/cowork/cowork-plugin-development');
+  console.log('');
+}
+
+build();