specweave 3.1.15 → 3.1.17

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -28,7 +28,7 @@ specweave init .
 
 ## SpecWithCode: the free workspace on top
 
-[SpecWithCode](https://spec-weave.com/code/) is a desktop app built on SpecWeave. Describe the work once and a coordinator splits it across Claude Code, Codex, Grok or Cursor workers on your own machines, with the spec, evidence and handoff in git. It is built for teams of 2–10 people and free: no markup, no token resale, no seat fee to run agents on your own machines. Early access, for Apple silicon Macs, Windows 10 and 11, and Linux. [Download SpecWithCode](https://spec-weave.com/code/download/) · [Pricing](https://spec-weave.com/pricing)
+[SpecWithCode](https://spec-weave.com/code/) is a desktop app built on SpecWeave. Describe the work once and a coordinator splits it across Claude Code, Codex, Grok or Cursor workers on your own machines, with the spec, evidence and handoff in git. It is free for every developer and team: no markup, no token resale, no seat fee to run agents on your own machines. Early access, for Apple silicon Macs, Windows 10 and 11, and Linux. [Download SpecWithCode](https://spec-weave.com/code/download/) · [Pricing](https://spec-weave.com/pricing)
 
 ## Keep your repositories where they are
 
@@ -183,7 +183,7 @@ Cursor tells AI "use Tailwind." SpecWeave tells AI "build a checkout flow agains
 
 **7 core skills, 4 optional, one source** — the same skills for Claude Code, Codex and Grok; see [Seven core skills, four optional](#seven-core-skills-four-optional).
 
-**Built for teams of 2–10 people** — Compliance audit trails. Brownfield analysis. Multi-repo workspaces.
+**For developers and teams** — Compliance audit trails. Brownfield analysis. Multi-repo workspaces.
 
 **Dashboard** — `specweave dashboard` shows intents, increments and evidence from local files, with no model calls.
 

package/bin/help.js

@@ -1,44 +1,26 @@
 export function registerHelp(program) {
-// Help text
+// Help text: the loop first, then a few everyday commands. Plumbing and legacy
+// commands are registered with { hidden: true } and still run.
 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('The loop:');
+  console.log('  $ specweave init                               # Set up SpecWeave in this folder');
+  console.log('  $ specweave create-increment "Add login form"  # Plan: fill spec.md (Problem, ACs, Tasks)');
+  console.log('  $ specweave task done T-01 --run "npm test"    # After the commit: run the task\'s Test, record it');
+  console.log('  $ specweave verify                             # Run the project\'s build/test/lint commands');
+  console.log('  $ specweave complete 0001                      # Close the increment');
+  console.log('  $ specweave handoff --reason "out of tokens"   # Stop here; another tool or account continues');
+  console.log('  $ specweave pickup                             # Continue handed-off work');
   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('Also:');
+  console.log('  $ specweave status                             # Increments and their progress');
+  console.log('  $ specweave task next                          # The next open task with its acceptance criteria');
+  console.log('  $ specweave sync setup                         # Connect GitHub Issues, Jira or Azure DevOps');
+  console.log('  $ specweave doctor                             # Check project health');
+  console.log('  $ specweave update                             # Update the CLI, instructions and skills');
   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');
+  console.log('Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI and any tool that reads AGENTS.md.');
+  console.log('More: https://spec-weave.com');
 });
 
 }

package/bin/specweave.js

@@ -23,7 +23,7 @@ const program = new Command();
 
 program
   .name('specweave')
-  .description('Spec-Driven Development framework with AI-powered autonomous agents')
+  .description('Spec-driven increments for AI coding agents: plan in spec.md, do each task, verify, close, hand off')
   .version(packageJson.version)
   .option('--workspace <root>', 'Select the planning workspace explicitly');
 
@@ -170,6 +170,7 @@ program
   .option('--accepted-by <who>', 'With accept-skip: the person who accepted the skip (required)')
   .option('--authorization <text>', 'With accept-skip: their words, quoted, or a message/thread reference (required)')
   .option('--accepted-at <date>', 'With accept-skip: when they accepted it, ISO-8601 (default: now)')
+  .option('--uncovered', 'With accept-skip: confirm skipping on an AC no task cites (it closes the whole AC)')
   .option('--no-commit', 'Skip the git.autoCommitIncrement commit of the increment files')
   .option('--json', 'Machine-readable output')
   .action(async (action, acOrIncrement, increment, options) => {
@@ -255,7 +256,7 @@ program
 // Create Increment command - Create template files for a new increment
 program
   .command('create-increment [title]')
-  .description('Create increment template files (metadata.json, spec.md, tasks.md). Short form: specweave create-increment "Add login form"')
+  .description('Create an increment: metadata.json and spec.md (Problem, Scope, ACs, Approach, Tasks). Short form: specweave create-increment "Add login form"')
   .option('--id <increment-id>', 'Increment ID (e.g., "0042-my-feature")')
   .option('--auto-id', 'Auto-generate next available increment ID (default when --id is absent)')
   .option('--name <name>', 'Increment name suffix (defaults to a slug of the title)')
@@ -381,7 +382,7 @@ program
   });
 
 program
-  .command('statusline')
+  .command('statusline', { hidden: true })
   .description('Claude Code status line that records usage for auto-handoff')
   .option('--wrap <command>', 'Print this status line command\'s output instead of the built-in line')
   .action(async (options) => {
@@ -390,7 +391,7 @@ program
   });
 
 program
-  .command('usage-guard')
+  .command('usage-guard', { hidden: true })
   .description('Stop hook: save a local checkpoint; at the auto-handoff threshold, suggest or ask for a handoff once')
   .option('--limit-hit', 'StopFailure hook: the turn hit the rate limit, so hand off now (or only save, in checkpoint-only mode)')
   .action(async (options) => {
@@ -400,7 +401,7 @@ program
 
 // Auto-compact window for Claude Code (400K keeps 1M-context turns small)
 program
-  .command('autocompact [action]')
+  .command('autocompact [action]', { hidden: true })
   .description('on | off | status: where Claude Code summarizes a long session (default 400k)')
   .option('--at <tokens>', 'Window for `on`, 100k to 1M (default 400k)')
   .option('--project', 'Write .claude/settings.json in this project instead of ~/.claude/settings.json')
@@ -456,7 +457,7 @@ program
 
 // Next ID command - Return the next available increment number
 program
-  .command('next-id')
+  .command('next-id', { hidden: true })
   .description('Return the next available increment number. Prefer: create-increment --auto-id')
   .option('--project <project-id>', 'Project ID for per-project collision prevention')
   .option('--project-root <path>', 'Override project root directory')
@@ -511,7 +512,7 @@ program
 
 // Save command - Smart save with auto-sync
 program
-  .command('save [message]')
+  .command('save [message]', { hidden: true })
   .description('Smart save - auto-generate commit message, sync with remote, commit and push')
   .option('-i, --interactive', 'Interactive mode - ask before each step')
   .option('--dry-run', 'Preview without executing')
@@ -558,7 +559,7 @@ program
 // Auto mode commands - Autonomous execution with stop hook feedback loop (v3.0)
 // No session files. No complex state. Just: "Are there active increments?"
 program
-  .command('auto [incrementIds...]')
+  .command('auto [incrementIds...]', { hidden: true })
   .description('Start autonomous execution (stop hook feedback loop)')
   .option('--dry-run', 'Preview without activating')
   .option('--all-backlog', 'Activate all backlog items')
@@ -587,7 +588,7 @@ program
   });
 
 program
-  .command('auto-status')
+  .command('auto-status', { hidden: true })
   .description('Check auto session status and progress')
   .option('--verbose', 'Show detailed information')
   .option('--json', 'Output as JSON')
@@ -601,7 +602,7 @@ program
   });
 
 program
-  .command('cancel-auto')
+  .command('cancel-auto', { hidden: true })
   .description('Cancel running auto session')
   .option('--force', 'Force cancel without confirmation')
   .action(async (options) => {
@@ -614,7 +615,7 @@ program
 
 // Team command - Launch Claude Code with native agent teams
 program
-  .command('team [description]')
+  .command('team [description]', { hidden: true })
   .description('Launch Claude Code with agent teams (tmux/iTerm2 split panes)')
   .option('--mode <mode>', 'Display mode: tmux (default) or in-process', 'tmux')
   .option('--no-increment', 'Launch without requiring a SpecWeave increment (free-form agent swarm)')
@@ -631,7 +632,7 @@ program
 
 // Update instructions command - Smart merge CLAUDE.md/AGENTS.md
 program
-  .command('update-instructions')
+  .command('update-instructions', { hidden: true })
   .description('Update CLAUDE.md and AGENTS.md with smart merge (preserves user content)')
   .option('--dry-run', 'Preview changes without writing')
   .option('-v, --verbose', 'Show detailed merge information')
@@ -660,7 +661,7 @@ program
 
 // Check discipline command - Validate increment discipline
 program
-  .command('check-discipline')
+  .command('check-discipline', { hidden: true })
   .description('Report increment status counts, advisory WIP note and metadata consistency')
   .option('-v, --verbose', 'Show detailed increment information')
   .option('--json', 'Output results as JSON')
@@ -676,7 +677,7 @@ program
 
 // GC command - purge junk from .specweave/state (dry-run by default)
 program
-  .command('gc')
+  .command('gc', { hidden: true })
   .description('Purge stale .specweave/state files (dry-run; --yes to delete), report .worktrees size and nested .specweave dirs, expire session checkpoints older than 7 days')
   .option('-y, --yes', 'Actually delete (default is dry-run)')
   .option('--json', 'Output as JSON')
@@ -688,7 +689,7 @@ program
 
 // QA command - Quality assessment
 program
-  .command('qa <increment-id>')
+  .command('qa <increment-id>', { hidden: true })
   .description('Run quality assessment on an increment')
   .option('--quick', 'Quick mode (default)')
   .option('--pre', 'Pre-implementation check')
@@ -707,7 +708,7 @@ program
 
 // Link PR - Link pull requests to external tickets (JIRA remote links, ADO hyperlinks)
 program
-  .command('link-pr')
+  .command('link-pr', { hidden: true })
   .description('Link a pull request to external tickets (JIRA, ADO)')
   .requiredOption('--increment <id>', 'Increment ID')
   .requiredOption('--pr-url <url>', 'Pull request URL')
@@ -720,7 +721,7 @@ program
 
 // Branch-name command - Compute branch name with optional external ticket key
 program
-  .command('branch-name <increment-id>')
+  .command('branch-name <increment-id>', { hidden: true })
   .description('Output the computed branch name for an increment (with optional JIRA/ADO ticket key)')
   .action(async (incrementId) => {
     const { branchNameCommand } = await import('../dist/src/cli/commands/branch-name.js');
@@ -736,7 +737,7 @@ async function runLspCommand(args) {
 
 // LSP command - Code intelligence operations
 const lspCmd = program
-  .command('lsp')
+  .command('lsp', { hidden: true })
   .description('LSP code intelligence (refs, def, hover, symbols, search)');
 
 lspCmd
@@ -864,7 +865,7 @@ syncCmd
 
 // Refresh plugins command - Copy first-party plugins to ~/.claude/commands/
 program
-  .command('refresh-plugins')
+  .command('refresh-plugins', { hidden: true })
   .description('Refresh SpecWeave plugins (core only by default, use --all for everything)')
   .option('--all', 'Install ALL plugins (not just core sw)')
   .option('--plugin <name>', 'Install a specific plugin by name')