specweave 2.2.3 → 2.3.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "Portable intent, specifications, task evidence, and handoffs across AI coding tools.",
   "owner": {
     "name": "Anton Abyzov",
@@ -12,7 +12,7 @@
       "description": "SpecWeave unified plugin — increment lifecycle (plan, work the ledger, verify, review, complete), cross-tool handoff, GitHub/Jira/ADO sync",
       "source": "./plugins/specweave",
       "category": "development",
-      "version": "2.2.3",
+      "version": "2.3.0",
       "author": {
         "name": "Anton Abyzov",
         "email": "anton.abyzov@gmail.com"

package/README.md

@@ -2,12 +2,12 @@
 
 <p align="center">
   <strong>Change agents. Keep the thread.</strong><br/>
-  Portable intent, linked specifications, and verified progress across coding agents.
+  Portable projects, shared context, and verified progress across AI tools.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/specweave"><img src="https://img.shields.io/npm/v/specweave?color=brightgreen" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/skills-11-8B5CF6" alt="11 skills" />
+  <img src="https://img.shields.io/badge/skills-12-8B5CF6" alt="12 skills" />
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT" /></a>
   <a href="https://discord.gg/UYg4BGJ65V"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
 </p>
@@ -32,6 +32,22 @@ Start with a short intent, see what is in progress, and open the linked specific
 
 [Explore the product](https://spec-weave.com/product) · [Optional integrations](https://spec-weave.com/integrations)
 
+## Any project, any agent
+
+Code, research, content and operations can share the same portable project hub. Git is optional.
+
+```bash
+mkdir research-project && cd research-project
+specweave project init --name "Research" --goal "Produce a sourced decision brief"
+specweave project work-add --title "Compare options" --summary "Use primary sources"
+specweave project brief --harness codex
+specweave dashboard
+```
+
+The hub keeps goals, shared context, artifact references and reusable routines in `.specweave/project/hub.json`; assignments reuse the intent board. Fresh worker briefs carry current context into Codex, Claude Code or another tool. The host launches agents and schedules routines when authorized. Saving a routine does not start a schedule.
+
+Codex native skills install under `.agents/skills/sw-*`. Existing legacy skills remain in place, and changed native installations are backed up. See [portable projects](https://spec-weave.com/docs/guides/portable-projects) for migration, CLI examples and boundaries.
+
 ## The loop
 
 | # | Command | Claude Code skill | What it does |
@@ -45,12 +61,13 @@ Start with a short intent, see what is in progress, and open the linked specific
 
 Everything lives in `.specweave/increments/NNNN-slug/`: `spec.md`, `tasks.md` (+ the rendered `SW:BOARD`), `ledger.jsonl`, `handoff.md`, `reports/`.
 
-## The eleven skills
+## The twelve skills
 
-The CLI is the product and it runs in any AI tool or in CI. These eleven focused skills expose the workflow to compatible coding tools. Install domain expertise separately when it helps.
+The CLI is the product and it runs in any AI tool or in CI. These twelve focused skills expose the workflow to compatible coding tools. Install domain expertise separately when it helps.
 
 | Skill | Use it for |
 |-------|------------|
+| `sw:project` | Shared project context, artifacts, routines and worker briefs. |
 | `sw:brainstorm` | Framed alternatives, ending in a pick. |
 | `sw:increment` | Plan the work: `spec.md` with ACs, plus `tasks.md`. |
 | `sw:do` | Claim a task, implement it, close it with evidence. |
@@ -141,7 +158,7 @@ Cursor tells AI "use Tailwind." SpecWeave tells AI "build a checkout flow agains
 
 **LSP Code Intelligence** — 198x faster than grep, 0 false positives. Semantic references, definitions, and types.
 
-**11 skills, not 51** — see [The eleven skills](#the-eleven-skills) above. Plus six standalone skills for non-Claude tools.
+**12 focused skills** — see [The twelve skills](#the-twelve-skills) above. Plus six standalone skills for non-Claude tools.
 
 **External Sync** — `specweave sync push|pull|status|setup`. GitHub is first-class; Jira and Azure DevOps are opt-in.
 

package/bin/check-build.js

@@ -0,0 +1,43 @@
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+// ESM equivalents for __dirname and __filename
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================================
+// DEVELOPMENT GUARD: Check if dist/ is built (prevents silent hangs)
+// ============================================================================
+// This only matters for developers running from source. NPM users always get
+// a pre-built package via prepublishOnly hook.
+// ============================================================================
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const distCliPath = join(__dirname, '..', 'dist', 'src', 'cli', 'commands', 'init.js');
+const isDevEnvironment = existsSync(join(__dirname, '..', 'tsconfig.json'));
+
+if (isDevEnvironment && !existsSync(distCliPath)) {
+  const RED = '\x1b[31m';
+  const YELLOW = '\x1b[33m';
+  const CYAN = '\x1b[36m';
+  const BOLD = '\x1b[1m';
+  const RESET = '\x1b[0m';
+  const DIM = '\x1b[2m';
+
+  console.error('');
+  console.error(`${RED}${BOLD}╔══════════════════════════════════════════════════════════════════╗${RESET}`);
+  console.error(`${RED}${BOLD}║  SpecWeave is not built! Run: npm run rebuild                    ║${RESET}`);
+  console.error(`${RED}${BOLD}╚══════════════════════════════════════════════════════════════════╝${RESET}`);
+  console.error('');
+  console.error(`${YELLOW}  Missing:${RESET}  ${DIM}dist/src/cli/commands/init.js${RESET}`);
+  console.error('');
+  console.error(`${BOLD}Quick fix:${RESET}`);
+  console.error(`  ${CYAN}npm run rebuild${RESET}`);
+  console.error('');
+  console.error(`${DIM}  This happens when 'npm run clean' runs without 'npm run build'.${RESET}`);
+  console.error(`${DIM}  NPM users never see this - packages are pre-built before publish.${RESET}`);
+  console.error('');
+  process.exit(1);
+}
+

package/bin/check-node.js

@@ -0,0 +1,136 @@
+// ============================================================================
+// CRITICAL: Node.js Version Check (MUST run before ANY ESM imports)
+// ============================================================================
+// This check runs synchronously before any imports that use modern syntax
+// (like `import ... with { type: 'json' }`) which would crash on older Node.js
+// ============================================================================
+
+const MIN_NODE_VERSION = '20.12.0';
+const CURRENT_NODE_VERSION = process.versions.node;
+
+/**
+ * Compare semver versions
+ * @param {string} current - Current version (e.g., "18.17.0")
+ * @param {string} required - Required version (e.g., "20.12.0")
+ * @returns {boolean} true if current >= required
+ */
+function isVersionSatisfied(current, required) {
+  const currentParts = current.split('.').map(Number);
+  const requiredParts = required.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const curr = currentParts[i] || 0;
+    const req = requiredParts[i] || 0;
+    if (curr > req) return true;
+    if (curr < req) return false;
+  }
+  return true; // Equal versions
+}
+
+/**
+ * Get platform-specific Node.js upgrade instructions
+ */
+function getUpgradeInstructions() {
+  const platform = process.platform;
+  const isNvm = process.env.NVM_DIR || process.env.NVM_BIN;
+  const isFnm = process.env.FNM_DIR || process.env.FNM_MULTISHELL_PATH;
+  const isVolta = process.env.VOLTA_HOME;
+  const isAsdf = process.env.ASDF_DIR;
+
+  let instructions = [];
+
+  // Version manager detection (cross-platform)
+  if (isNvm) {
+    instructions.push('  Using nvm (detected):');
+    instructions.push('    nvm install 22');
+    instructions.push('    nvm use 22');
+    instructions.push('    nvm alias default 22');
+  } else if (isFnm) {
+    instructions.push('  Using fnm (detected):');
+    instructions.push('    fnm install 22');
+    instructions.push('    fnm use 22');
+    instructions.push('    fnm default 22');
+  } else if (isVolta) {
+    instructions.push('  Using Volta (detected):');
+    instructions.push('    volta install node@22');
+  } else if (isAsdf) {
+    instructions.push('  Using asdf (detected):');
+    instructions.push('    asdf install nodejs 22.0.0');
+    instructions.push('    asdf global nodejs 22.0.0');
+  } else {
+    // Platform-specific fallback
+    switch (platform) {
+      case 'darwin':
+        instructions.push('  macOS options:');
+        instructions.push('    # Using Homebrew:');
+        instructions.push('    brew install node@22');
+        instructions.push('');
+        instructions.push('    # Using nvm (recommended):');
+        instructions.push('    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash');
+        instructions.push('    nvm install 22 && nvm use 22');
+        break;
+      case 'linux':
+        instructions.push('  Linux options:');
+        instructions.push('    # Using nvm (recommended):');
+        instructions.push('    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash');
+        instructions.push('    nvm install 22 && nvm use 22');
+        instructions.push('');
+        instructions.push('    # Using NodeSource (Debian/Ubuntu):');
+        instructions.push('    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -');
+        instructions.push('    sudo apt-get install -y nodejs');
+        break;
+      case 'win32':
+        instructions.push('  Windows options:');
+        instructions.push('    # Using nvm-windows:');
+        instructions.push('    nvm install 22');
+        instructions.push('    nvm use 22');
+        instructions.push('');
+        instructions.push('    # Direct download:');
+        instructions.push('    https://nodejs.org/en/download/');
+        break;
+      default:
+        instructions.push('  Download Node.js 22+ from:');
+        instructions.push('    https://nodejs.org/en/download/');
+    }
+  }
+
+  return instructions.join('\n');
+}
+
+// Perform the version check
+if (!isVersionSatisfied(CURRENT_NODE_VERSION, MIN_NODE_VERSION)) {
+  // Use basic console methods (no chalk yet - it may fail to import)
+  const RED = '\x1b[31m';
+  const YELLOW = '\x1b[33m';
+  const CYAN = '\x1b[36m';
+  const BOLD = '\x1b[1m';
+  const RESET = '\x1b[0m';
+  const DIM = '\x1b[2m';
+  const UNDERLINE = '\x1b[4m';
+
+  console.error('');
+  console.error(`${RED}${BOLD}╔══════════════════════════════════════════════════════════════════╗${RESET}`);
+  console.error(`${RED}${BOLD}║  SpecWeave requires Node.js ${MIN_NODE_VERSION} or higher                     ║${RESET}`);
+  console.error(`${RED}${BOLD}╚══════════════════════════════════════════════════════════════════╝${RESET}`);
+  console.error('');
+  console.error(`${YELLOW}  Your version:${RESET}  ${RED}${CURRENT_NODE_VERSION}${RESET}`);
+  console.error(`${YELLOW}  Required:${RESET}      ${CYAN}≥${MIN_NODE_VERSION}${RESET} (Node.js 22 LTS recommended)`);
+  console.error('');
+  console.error(`${DIM}  Why? SpecWeave uses modern JavaScript features (ES2022+) including${RESET}`);
+  console.error(`${DIM}  import assertions which require Node.js 20.12.0+${RESET}`);
+  console.error('');
+  console.error(`${BOLD}Quick upgrade:${RESET}`);
+  console.error(getUpgradeInstructions());
+  console.error('');
+  console.error(`${BOLD}Full guide:${RESET}`);
+  console.error(`  ${CYAN}${UNDERLINE}https://spec-weave.com/docs/guides/troubleshooting/common-errors#node-version-error${RESET}`);
+  console.error('');
+  console.error(`${DIM}After upgrading, verify with: node --version${RESET}`);
+  console.error('');
+  process.exit(1);
+}
+
+// ============================================================================
+// Node.js version is OK - proceed with normal imports
+// ============================================================================
+

package/bin/help.js

@@ -0,0 +1,68 @@
+export function registerHelp(program) {
+// Help text
+program.on('--help', () => {
+  console.log('');
+  console.log('Examples:');
+  console.log('  $ specweave init my-saas                    # Create new project (auto-detect tool)');
+  console.log('  $ specweave init my-saas --adapter cursor   # Create project for Cursor');
+  console.log('  $ specweave init my-saas --language ru      # Create project with Russian language');
+  console.log('  $ specweave install pm --local              # Install PM agent locally');
+  console.log('  $ specweave install --global                # Install all (interactive)');
+  console.log('  $ specweave list                            # List all available components');
+  console.log('  $ specweave list --installed                # Show installed components');
+  console.log('  $ specweave status                          # Show all increments status');
+  console.log('  $ specweave status --verbose                # Show detailed increment info');
+  console.log('  $ specweave status-line                     # Display current increment progress');
+  console.log('  $ specweave status-line --json              # Output progress as JSON');
+  console.log('  $ specweave pause 0007 --reason "blocked"   # Pause increment 0007');
+  console.log('  $ specweave resume 0007                     # Resume increment 0007');
+  console.log('  $ specweave abandon 0007 --reason "obsolete" # Abandon increment 0007');
+  console.log('  $ specweave qa 0008                         # Quick quality check');
+  console.log('  $ specweave qa 0008 --pre                   # Pre-implementation check');
+  console.log('  $ specweave qa 0008 --gate --export         # Quality gate + export to tasks');
+  console.log('  $ specweave sync status                     # Token/account, provider health, sync gaps');
+  console.log('  $ specweave jobs                            # Show active background jobs');
+  console.log('  $ specweave jobs --follow <jobId>           # Follow job progress live');
+  console.log('  $ specweave jobs --logs <jobId>             # View worker logs');
+  console.log('  $ specweave jobs --resume <jobId>           # Resume paused job');
+  console.log('  $ specweave living-docs                     # Launch Living Docs (interactive)');
+  console.log('  $ specweave living-docs --depth deep-native # AI-powered analysis (FREE w/ MAX)');
+  console.log('  $ specweave living-docs --full-scan         # Full deep scan (all phases)');
+  console.log('  $ specweave living-docs --resume <jobId>    # Resume orphaned job');
+  console.log('  $ specweave sync push 0008                  # Push increment progress to GitHub/Jira/ADO');
+  console.log('  $ specweave sync pull --since 3             # Show external changes from the last 3 days');
+  console.log('  $ specweave cache                           # Show cache status');
+  console.log('  $ specweave cache --rebuild                 # Rebuild dashboard cache');
+  console.log('  $ specweave cache --debug                   # Show cache debug info');
+  console.log('  $ specweave sync setup --validate           # Validate tracker configuration + credentials');
+  console.log('  $ specweave docs                            # Preview internal docs (port 3015)');
+  console.log('  $ specweave docs public                     # Preview public docs (port 3016)');
+  console.log('  $ specweave docs build                      # Build internal site');
+  console.log('  $ specweave docs build --scope public       # Build public site');
+  console.log('  $ specweave docs validate                   # Check for docs errors');
+  console.log('  $ specweave docs status                     # Show docs status');
+  console.log('  $ specweave docs kill                       # Stop all docs servers');
+  console.log('  $ specweave doctor --fix-status             # Fix metadata/spec status desyncs');
+  console.log('  $ specweave refresh-plugins                 # Refresh core SpecWeave plugin');
+  console.log('  $ specweave refresh-plugins --all           # Refresh every installed plugin');
+  console.log('  $ specweave refresh-plugins --force         # Force reinstall (skip hash check)');
+  console.log('  $ specweave update                          # Update CLI + instructions + config');
+  console.log('  $ specweave update --plugins                # Also refresh marketplace plugins');
+  console.log('  $ specweave update --no-self                # Skip CLI update, only project files');
+  console.log('  $ specweave update --check                  # Dry run - preview changes');
+  console.log('');
+  console.log('Plugin Management (use Claude CLI commands):');
+  console.log('  $ claude plugin install sw@specweave        # Install core SpecWeave');
+  console.log('  $ claude plugin list                        # Show installed plugins');
+  console.log('  $ vskill install anton-abyzov/vskill --plugin mobile  # Install domain plugin');
+  console.log('');
+  console.log('Supported AI Tools:');
+  console.log('  - Claude Code (full automation) - Native skills, agents, hooks');
+  console.log('  - Cursor (semi-automation) - .cursorrules, @ shortcuts');
+  console.log('  - GitHub Copilot (basic) - Workspace instructions');
+  console.log('  - Generic (manual) - Works with ANY AI (ChatGPT, Gemini, etc.)');
+  console.log('');
+  console.log('For more information, visit: https://spec-weave.com');
+});
+
+}

package/bin/project.js

@@ -0,0 +1,28 @@
+export function registerProjectCommand(program) {
+  program.command('project <action>')
+    .description('Portable project hub: init, show, set, brief, work-add, work-update, work-record, artifact-add, artifact-remove, routine-add, routine-remove')
+    .option('--root <path>', 'Explicit project folder; otherwise resolve the enclosing umbrella')
+    .option('--name <name>', 'Project name')
+    .option('--goal <goal>', 'Project goal')
+    .option('--context-file <file>', 'Read shared context from a UTF-8 file')
+    .option('--revision <number>', 'Expected current hub or work revision', Number)
+    .option('--title <title>', 'Work, artifact or routine title')
+    .option('--summary <summary>', 'Work description')
+    .option('--state <state>', 'backlog, active, blocked, review or done (planning state)')
+    .option('--increment <id>', 'Link an existing increment')
+    .option('--intent <id>', 'Existing work item ID')
+    .option('--location <path-or-url>', 'Project-relative file or HTTPS URL; artifact ID for artifact-remove')
+    .option('--cadence <cadence>', 'Human-readable requested cadence; does not schedule execution')
+    .option('--instructions-file <file>', 'Read reusable routine instructions from a UTF-8 file')
+    .option('--routine <id>', 'Routine ID for brief or routine-remove')
+    .option('--harness <name>', 'Target codex, claude or generic; actual harness for work-record')
+    .option('--model <model>', 'Actual model identity, if known')
+    .option('--session <id>', 'Native session ID, if known')
+    .option('--effort <effort>', 'Actual reasoning effort, if known')
+    .option('--note <note>', 'Execution evidence or handoff note')
+    .option('--json', 'JSON output, including errors')
+    .action(async (action, options) => {
+      const { projectCommand } = await import('../dist/src/cli/commands/project.js');
+      await projectCommand(action, options);
+    });
+}