specweave 2.2.3 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "2.2.3",
+  "version": "3.0.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": "3.0.0",
       "author": {
         "name": "Anton Abyzov",
         "email": "anton.abyzov@gmail.com"

package/CLAUDE.md

@@ -1,218 +1,6 @@
-<!-- SW:META template="claude" version="1.0.272" sections="header,lsp,start,autodetect,metarule,rules,workflow,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
+@AGENTS.md
 
-<!-- SW:SECTION:header version="1.0.272" -->
-**Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
-<!-- SW:END:header -->
+## Claude Code notes
 
-<!-- SW:SECTION:lsp version="1.0.272" -->
-## LSP (Code Intelligence)
-
-**Native LSP broken in v2.1.0+.** Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
-<!-- SW:END:lsp -->
-
-<!-- SW:SECTION:start version="1.0.272" -->
-## Getting Started
-
-Your first increment starts at `0001`. Just describe what you want to build:
-
-`/sw:increment "your-feature"`
-<!-- SW:END:start -->
-
-<!-- SW:SECTION:autodetect version="1.0.272" -->
-## Auto-Detection
-
-SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
-
-**Signals** (5+ = auto-route): Project name | Features list (3+) | Tech stack | Timeline/MVP | Problem statement | Business model
-
-**Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
-<!-- SW:END:autodetect -->
-
-<!-- SW:SECTION:metarule version="1.0.272" -->
-## Workflow Orchestration
-
-### 1. Plan mode first
-
-Enter plan mode (`EnterPlanMode`) before writing a spec, plan, or task breakdown, or before starting any non-trivial task (3+ steps or an architectural decision), and wait for approval before implementing — the spec is what the user approves, so writing code first makes the approval meaningless. `/sw:increment` starts in plan mode; do not skip it. Write the spec in enough detail that the ambiguity is resolved on paper rather than mid-task. If the approach turns out wrong mid-task, stop and re-plan.
-
-### 2. Subagent Strategy
-- Offload research, exploration, and parallel analysis to subagents — it keeps the main context clean
-- One task per subagent for focused execution
-- In team mode, sub-agents submit plans for team lead review before implementing
-
-### 3. Verification Before Done
-- Never mark a task complete without proving it works
-- Run tests, check logs, demonstrate correctness
-
-### 5. Auto-Closure After Implementation (MANDATORY)
-- When `/sw:do` completes all tasks, IMMEDIATELY invoke `/sw:done` — do NOT stop to ask for review
-- Quality gates (code-review, simplify, grill, judge-llm, PM validation) ARE the review — no user confirmation needed
-- If a gate fails, the increment stays open automatically. User can re-open if they disagree
-- **Anti-pattern**: "All tasks complete. Should I close?" — NEVER ask this. Just close it.
-
-### 4. Think-Before-Act (Dependencies)
-**Satisfy dependencies BEFORE dependent operations.**
-```
-Bad:  node script.js → Error → npm run build
-Good: npm run build → node script.js → Success
-```
-<!-- SW:END:metarule -->
-
-<!-- SW:SECTION:rules version="1.0.272" -->
-## Rules
-
-1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
-2. **Update immediately**: `Edit("tasks.md", "[ ] pending", "[x] completed")` + `Edit("spec.md", "[ ] AC-", "[x] AC-")`
-3. **Unique IDs**: Check ALL folders (active, archive, abandoned):
-   ```bash
-   find .specweave/increments -maxdepth 2 -type d -name "[0-9]*" | grep -oE '[0-9]{4}E?' | sort -u | tail -5
-   ```
-4. **Emergency**: "emergency mode" → 1 edit, 50 lines max, no agents
-5. **Initialization guard**: `.specweave/` folders MUST ONLY exist where `specweave init` was run
-6. **Plugin refresh**: Use `specweave refresh-plugins` CLI (not `scripts/refresh-marketplace.sh`)
-7. **Numbered folder collisions**: Before creating `docs/NN-*` folders, CHECK existing prefixes
-8. **Repository structure**: ALL repos MUST be at `repositories/{org}/{repo-name}/` — NEVER directly under `repositories/`. Every workspace uses this structure regardless of the number of repositories
-<!-- SW:END:rules -->
-
-<!-- SW:SECTION:workflow version="1.0.272" -->
-## Workflow
-
-`/sw:increment "X"` → `/sw:do` → `specweave status` → `/sw:done 0001`
-
-| Cmd | Action |
-|-----|--------|
-| `/sw:increment` | Plan feature |
-| `/sw:do` | Execute tasks |
-| `/sw:auto` | Autonomous execution |
-| `/sw:review` | Adversarial review before closing |
-| `/sw:done` | Close |
-| `/sw:sync` | Sync progress to GitHub / Jira / ADO |
-| `/sw:handoff` | Hand off to another tool or machine |
-| `/sw:qa` | Risk-scored quality assessment |
-| `specweave status` | Task completion overview |
-| `specweave verify <id>` | Run build/test/lint, write verify.json |
-| `specweave auto-status` / `cancel-auto` | Inspect / stop an auto session |
-
-**Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `specweave status` | "We're done" → `/sw:done` | "Ship while sleeping" → `/sw:auto`
-<!-- SW:END:workflow -->
-
-<!-- SW:SECTION:context version="1.0.272" -->
-## Context
-
-**Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
-
-**Load context**: `specweave docs` previews and validates the living docs
-<!-- SW:END:context -->
-
-<!-- SW:SECTION:structure version="1.0.272" -->
-## Structure
-
-```
-.specweave/
-├── increments/####-name/     # metadata.json, spec.md, plan.md, tasks.md
-├── docs/internal/specs/      # Living docs
-└── config.json
-```
-
-**Increment root**: ONLY `metadata.json`, `spec.md`, `plan.md`, `tasks.md`
-
-**Everything else → subfolders**: `reports/` | `logs/` | `scripts/` | `backups/`
-<!-- SW:END:structure -->
-
-<!-- SW:SECTION:taskformat version="1.0.272" -->
-## Task Format
-
-```markdown
-### T-001: Title
-**User Story**: US-001 | **Satisfies ACs**: AC-US1-01 | **Status**: [x] completed
-**Test**: Given [X] → When [Y] → Then [Z]
-```
-<!-- SW:END:taskformat -->
-
-<!-- SW:SECTION:secrets version="1.0.272" -->
-## Secrets
-
-Before CLI tools, check existing config (`grep -q` only — never display values).
-<!-- SW:END:secrets -->
-
-<!-- SW:SECTION:syncing version="1.0.272" -->
-## External Sync
-
-Primary: `/sw:sync`. Direct: `specweave sync push [id]`, `specweave sync status`, `specweave sync setup`. Mapping: Feature→Milestone | Story→Issue | Task→Checkbox.
-<!-- SW:END:syncing -->
-
-<!-- SW:SECTION:testing version="1.0.272" -->
-## Testing
-
-BDD in tasks.md | Unit >80% | `.test.ts` (Vitest) | ESM mocking: `vi.hoisted()` + `vi.mock()`
-<!-- SW:END:testing -->
-
-<!-- SW:SECTION:tdd version="1.0.272" -->
-## TDD
-
-When `testing.mode: "TDD"` in config.json: RED→GREEN→REFACTOR, described inside `/sw:do`. The standalone `tdd-cycle` skill moved to `skills-optional/` in 2.0: `npx vskill install anton-abyzov/specweave/skills-optional/tdd-cycle`.
-<!-- SW:END:tdd -->
-
-<!-- SW:SECTION:api version="1.0.272" -->
-<!-- SW:END:api -->
-
-<!-- SW:SECTION:limits version="1.0.272" -->
-## Limits
-
-**Max 1500 lines/file** — extract before adding
-<!-- SW:END:limits -->
-
-<!-- SW:SECTION:troubleshooting version="1.0.272" -->
-## Troubleshooting
-
-| Issue | Fix |
-|-------|-----|
-| Skills missing | Restart Claude Code |
-| Plugins outdated | `specweave refresh-plugins` |
-| Out of sync | `specweave sync push <id>` |
-| Session stuck | `rm -f .specweave/state/*.lock` + restart |
-<!-- SW:END:troubleshooting -->
-
-<!-- SW:SECTION:lazyloading version="1.0.272" -->
-## Plugin Auto-Loading
-
-Plugins load automatically. Manual: `specweave refresh-plugins` or `claude plugin install <name>@specweave`. Disable: `export SPECWEAVE_DISABLE_AUTO_LOAD=1`
-<!-- SW:END:lazyloading -->
-
-<!-- SW:SECTION:principles version="1.0.272" -->
-## Principles
-
-1. **Spec-first**: `/sw:increment` before coding
-2. **Docs = truth**: Specs guide implementation
-3. **Simplicity First**: Minimal code, minimal impact
-4. **Root causes**: fix the cause, not the symptom; no TODO-for-later
-5. **DRY**: Don't Repeat Yourself — flag and eliminate repetitions aggressively
-<!-- SW:END:principles -->
-
-<!-- SW:SECTION:linking version="1.0.272" -->
-## Bidirectional Linking
-
-Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
-
-Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
-<!-- SW:END:linking -->
-
-<!-- SW:SECTION:mcp version="1.0.272" -->
-## External Services
-
-CLI tools first (`gh`, `wrangler`, `supabase`) → MCP for complex integrations.
-<!-- SW:END:mcp -->
-
-<!-- SW:SECTION:auto version="1.0.272" -->
-## Auto Mode
-
-`/sw:auto` (start) | `specweave auto-status` (check) | `specweave cancel-auto` (emergency)
-
-Pattern: IMPLEMENT → TEST → FAIL? → FIX → PASS → NEXT. STOP & ASK if spec conflicts or ambiguity.
-<!-- SW:END:auto -->
-
-<!-- SW:SECTION:docs version="1.0.272" -->
-## Docs
-
-[spec-weave.com](https://spec-weave.com)
-<!-- SW:END:docs -->
+- Changes to hook behaviour: rebuild, then run `/reload-plugins` or restart Claude Code to load them.
+- Use a subagent for wide searches across `src/sync/` and `src/integrations/`; they are large.

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <strong>Change agents. Keep the thread.</strong><br/>
-  Portable intent, linked specifications, and verified progress across coding agents.
+  Plan work as small specs, hand it between Claude, Codex, Grok and any other tool in two words, and close it with evidence.
 </p>
 
 <p align="center">
@@ -22,64 +22,71 @@ cd your-project
 specweave init .
 ```
 
-## See the work
+`init` writes `AGENTS.md` (read by Codex, Grok, Cursor, Gemini and Copilot), a two-line `CLAUDE.md` that imports it, and the skills for Claude Code and Codex. Nothing else runs in the background.
 
-```bash
-specweave dashboard
+## Out of tokens? Say "hand off"
+
+```text
+you (in Claude, account 1):   hand off
+you (in Codex, or account 2): pick up
 ```
 
-Start with a short intent, see what is in progress, and open the linked specification and evidence. Small work can stay lightweight. The dashboard reads local project state without model calls; card movement does not manufacture verified completion.
+That is the whole handoff. "Hand off" runs `specweave handoff`: it releases your task claims, records why you stopped, and pushes your branch plus a snapshot of your uncommitted edits. "Pick up" runs `specweave pickup` in any other tool, account, machine or cloud session (a Claude Code Projects thread, a Codex cloud task): it brings that work into the checkout and prints the next task with its acceptance criteria. Nothing to copy, no paths to paste.
 
-[Explore the product](https://spec-weave.com/product) · [Optional integrations](https://spec-weave.com/integrations)
+Running out mid-task? `specweave auto-handoff on`, once per machine, makes it automatic: when a session reaches 90% of your plan's 5-hour or weekly limit, it hands off by itself and tells you to say "pick up" elsewhere. Claude Code reads the limit through its status line (your own status line keeps working) and Codex through a Stop hook. Under the threshold it costs no tokens. `--at 85` changes the threshold and `off` undoes every change.
+
+`specweave report` writes an HTML timeline of who did what on an increment (tools, sessions, handoffs, pickups, test evidence), straight from the ledger.
 
 ## The loop
 
-| # | Command | Claude Code skill | What it does |
-|---|---------|-------------------|--------------|
-| 1 | `specweave create-increment "<title>"` | `/sw:increment` | `spec.md` with Problem, Scope, numbered ACs and an Approach. Resolve scope; continue within your authorization. |
-| 2 | `specweave task next` → `claim` → `done --run "<test>"` | `/sw:do` | Work the tasks. `done` refuses a failing test command. |
-| 3 | `specweave verify` | — | Runs your test/lint/build; writes `reports/verify.json`. |
-| 4 | — | `/sw:review` | Fresh-context adversarial review; every finding cites `path:line`. |
-| 5 | `specweave complete <id>` | `/sw:done` | Closes. Blocks only on a green `verify.json` (or `--reason`). |
-| 6 | `specweave handoff` | `/sw:handoff` | A portable one-page doc so any other tool can pick the work up. |
+| # | Say or run | What happens |
+|---|---|---|
+| 1 | "pick up" · `specweave pickup` | The open increment, the next task with its acceptance criteria, claims held by others, branch state, notes and project memory, in one read. |
+| 2 | `/sw:increment` · `specweave create-increment "<title>"` | One `spec.md`: Problem, Scope, Acceptance Criteria, Approach and the Tasks. |
+| 3 | `/sw:do` · `specweave task claim T-01` → `task done T-01 --run "<test>"` | Work a task. `done` refuses a failing test and stores the evidence in the ledger. |
+| 4 | `specweave verify` · `/sw:review` | Runs your test, lint and build; a fresh-context review cites `path:line`. |
+| 5 | `/sw:done` · `specweave complete <id>` | Closes on a green verify. Acceptance criteria are met when their tasks are done; nobody ticks boxes. |
+| 6 | "hand off" · `specweave handoff` | Stop anywhere; the next tool picks up. |
+
+An increment is one folder, `.specweave/increments/NNNN-slug/`, with one file you read (`spec.md`) and one the CLI appends to (`ledger.jsonl`). Increments from 2.x with a `tasks.md` keep working unchanged.
 
-Everything lives in `.specweave/increments/NNNN-slug/`: `spec.md`, `tasks.md` (+ the rendered `SW:BOARD`), `ledger.jsonl`, `handoff.md`, `reports/`.
+## Works the way Claude Code Projects work
+
+| Claude Code Projects | SpecWeave |
+|---|---|
+| A thread: one session, one branch, one PR | One increment |
+| The thread's checklist | The `## Tasks` of that increment's `spec.md`, state in `ledger.jsonl` |
+| Project memory (`MEMORY.md` + one file per fact) | `.specweave/memory/`, same format, committed, so every tool and account sees it |
+| Threads passing notes | `specweave note "<text>"` on another increment |
+
+Project memory in claude.ai stays with one account. `.specweave/memory/` travels with the code, so Codex, Grok and a second Claude subscription start from the same decisions.
 
 ## The eleven 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 runs in any tool or in CI. The skills expose it to coding agents: `/sw:<name>` in Claude Code, `sw-<name>` in `.claude/skills/` (for Projects threads, where plugins do not load) and `.agents/skills/` (Codex, Grok).
 
 | Skill | Use it for |
 |-------|------------|
-| `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. |
-| `sw:auto` | The same loop, unattended, until the tasks run out. |
-| `sw:team` | A worktree per agent, claims arbitrated by the ledger. |
-| `sw:review` | Fresh-context adversarial pass; findings cite `path:line`. |
-| `sw:qa` | Risk-scored assessment, blockers, verdict. |
-| `sw:done` | Verify, review check, `specweave complete`. |
-| `sw:sync` | GitHub, Jira and Azure DevOps: push, pull, status, setup. |
-| `sw:handoff` | A one-page, secret-scrubbed continuation doc. |
-| `sw:jev` | Closed-set decisions in ~250 ms via Jev (TypeSafe System One). |
-
-Five longer procedures (tdd-cycle, e2e, debug, diagrams, release-expert) live in `skills-optional/` and install on demand with [vskill](https://www.npmjs.com/package/vskill).
-
-## Upgrade to 2.0
+| `increment` | Plan the work as one `spec.md`. |
+| `do` | Claim a task, implement it, close it with evidence. |
+| `auto` | The same loop, unattended, until the tasks run out. |
+| `team` | A worktree per agent, claims arbitrated by the ledger. |
+| `review` | Fresh-context adversarial review; findings cite `path:line`. |
+| `done` | Verify, review check, `specweave complete`. |
+| `handoff` | "Hand off" and "pick up". |
+| `sync` | GitHub, Jira and Azure DevOps, only when you run it. |
+| `project` | Shared goals, artifacts and briefs across tools. |
+| `brainstorm` | Framed alternatives, ending in a pick. |
+| `jev` | Closed-set decisions in about 250 ms via Jev. |
+
+## Upgrade to 3.0
 
 ```bash
-npm i -g specweave@2
+npm i -g specweave@3
 specweave update
 ```
 
-`specweave update` is idempotent: it rewrites the managed sections of `CLAUDE.md`/`AGENTS.md` while preserving your own, migrates `config.json` in one pass, writes the `.gitignore`/`.gitattributes` entries 2.0 needs, and keeps backups under `.specweave/backups/`. Then run `specweave doctor`.
-
-2.0 removed a lot on purpose — the three-report closure pipeline, auto-generated living docs, 34 never-invoked skills, the queued sync mode. See **[What was removed, and why](https://spec-weave.com/docs/guides/specweave-2#what-was-removed-and-why)**.
-
-There is no alias routing: a 1.x slug simply has no skill behind it. The old-to-new map —
-every removed skill, the skill or CLI command that replaced it, and the ones that moved to
-`skills-optional/` — is `removedIn2_0` in
-[`plugins/specweave/marketplace.json`](https://github.com/anton-abyzov/specweave/blob/develop/plugins/specweave/marketplace.json).
+`specweave update` rewrites `AGENTS.md` into the lean form, turns `CLAUDE.md` into an import of it, keeps your own sections, and backs up the old files under `.specweave/backups/`. Existing increments need no migration. The **[3.0.0 changelog](https://github.com/anton-abyzov/specweave/blob/develop/CHANGELOG.md#300---2026-09-25)** lists what changed and what was removed. To have sessions hand off by themselves near the usage limit, run `specweave auto-handoff on` once.
 
 <br/>
 
@@ -125,7 +132,7 @@ Cursor tells AI "use Tailwind." SpecWeave tells AI "build a checkout flow agains
 
 ## Key Features
 
-**Spec-First Planning** — Every feature starts as `spec.md` (Problem, Scope, ACs, Approach) plus `tasks.md`. Configuration, not prompting.
+**Spec-First Planning** — Every feature starts as one `spec.md`: Problem, Scope, ACs, Approach and Tasks.
 
 **Evidence, not vibes** — `specweave task done --run "<test>"` refuses a failing command and stores the exit code and output tail in the ledger.
 
@@ -141,13 +148,13 @@ 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.
+**11 skills, one source** — the same skills for Claude Code, Codex and Grok; see [The eleven skills](#the-eleven-skills).
 
-**External Sync** — `specweave sync push|pull|status|setup`. GitHub is first-class; Jira and Azure DevOps are opt-in.
+**External Sync** — `specweave sync push|pull|status|setup`. GitHub is first-class; Jira and Azure DevOps are opt-in. Nothing calls a tracker unless you run sync.
 
 **Enterprise Ready** — Compliance audit trails. Brownfield analysis. Multi-repo workspaces.
 
-**Dashboard** — Built-in web dashboard for increment progress, analytics, cost tracking, and multi-project monitoring.
+**Dashboard** — `specweave dashboard` shows intents, increments and evidence from local files, with no model calls.
 
 <br/>
 
@@ -169,7 +176,7 @@ npx vskill eval run my-skill                  # Run eval suite
 
 ## Documentation
 
-**[spec-weave.com](https://spec-weave.com)** — [SpecWeave 2.0](https://spec-weave.com/docs/guides/specweave-2) · [commands](https://spec-weave.com/docs/reference/commands) · [skills](https://spec-weave.com/docs/reference/skills) · [configuration](https://spec-weave.com/docs/reference/configuration)
+**[spec-weave.com](https://spec-weave.com)** — [SpecWeave 3.0](https://spec-weave.com/docs/guides/specweave-3) · [handoff](https://spec-weave.com/docs/guides/cross-tool-handoff) · [commands](https://spec-weave.com/docs/reference/commands) · [skills](https://spec-weave.com/docs/reference/skills) · [configuration](https://spec-weave.com/docs/reference/configuration)
 
 ## Contributing
 

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,44 @@
+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 status                          # Show all increments status');
+  console.log('  $ specweave status --verbose                # Show detailed increment info');
+  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 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 sync setup --validate           # Validate tracker configuration + credentials');
+  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');
+});
+
+}