specweave 1.0.0-rc.2 → 1.0.0

package/dist/src/init/team/types.d.ts

@@ -45,13 +45,51 @@ export declare const TeamRecommendationSchema: z.ZodObject<{
     required: z.ZodBoolean;
     reason: z.ZodString;
     size: z.ZodString;
-    skills: z.ZodArray<z.ZodString>;
+    skills: z.ZodArray<z.ZodString, "many">;
     serverlessAlternative: z.ZodOptional<z.ZodObject<{
         service: z.ZodString;
         costSavings: z.ZodNumber;
-        tradeoffs: z.ZodArray<z.ZodString>;
+        tradeoffs: z.ZodArray<z.ZodString, "many">;
         pricingModel: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
+    }, "strip", z.ZodTypeAny, {
+        service?: string;
+        costSavings?: number;
+        tradeoffs?: string[];
+        pricingModel?: string;
+    }, {
+        service?: string;
+        costSavings?: number;
+        tradeoffs?: string[];
+        pricingModel?: string;
+    }>>;
     priority: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
+}, "strip", z.ZodTypeAny, {
+    skills?: string[];
+    reason?: string;
+    priority?: number;
+    size?: string;
+    role?: string;
+    teamName?: string;
+    required?: boolean;
+    serverlessAlternative?: {
+        service?: string;
+        costSavings?: number;
+        tradeoffs?: string[];
+        pricingModel?: string;
+    };
+}, {
+    skills?: string[];
+    reason?: string;
+    priority?: number;
+    size?: string;
+    role?: string;
+    teamName?: string;
+    required?: boolean;
+    serverlessAlternative?: {
+        service?: string;
+        costSavings?: number;
+        tradeoffs?: string[];
+        pricingModel?: string;
+    };
+}>;
 //# sourceMappingURL=types.d.ts.map

package/dist/src/init/team/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/init/team/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IAEpB,oCAAoC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IAEjB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAElB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAE9C,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;iBAcnC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/init/team/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IAEpB,oCAAoC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IAEjB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAElB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAE9C,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAcnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/hooks/universal/hook-wrapper.cmd

@@ -1,26 +1,26 @@
-@echo off
-REM hook-wrapper.cmd - Windows resilient hook launcher
-REM Prevents crashes when dispatcher.mjs is temporarily unavailable
-
-setlocal enabledelayedexpansion
-
-set "HOOK_TYPE=%~1"
-if "%HOOK_TYPE%"=="" set "HOOK_TYPE=unknown"
-
-set "SCRIPT_DIR=%~dp0"
-set "DISPATCHER=%SCRIPT_DIR%dispatcher.mjs"
-
-REM Check if dispatcher exists
-if not exist "%DISPATCHER%" (
-    echo {"continue":true,"systemMessage":"Hook skipped: dispatcher.mjs not found"}
-    exit /b 0
-)
-
-REM Run dispatcher with error suppression
-node "%DISPATCHER%" "%HOOK_TYPE%" 2>nul
-if errorlevel 1 (
-    echo {"continue":true,"systemMessage":"Hook error, continuing"}
-    exit /b 0
-)
-
-exit /b 0
+@echo off
+REM hook-wrapper.cmd - Windows resilient hook launcher
+REM Prevents crashes when dispatcher.mjs is temporarily unavailable
+
+setlocal enabledelayedexpansion
+
+set "HOOK_TYPE=%~1"
+if "%HOOK_TYPE%"=="" set "HOOK_TYPE=unknown"
+
+set "SCRIPT_DIR=%~dp0"
+set "DISPATCHER=%SCRIPT_DIR%dispatcher.mjs"
+
+REM Check if dispatcher exists
+if not exist "%DISPATCHER%" (
+    echo {"continue":true,"systemMessage":"Hook skipped: dispatcher.mjs not found"}
+    exit /b 0
+)
+
+REM Run dispatcher with error suppression
+node "%DISPATCHER%" "%HOOK_TYPE%" 2>nul
+if errorlevel 1 (
+    echo {"continue":true,"systemMessage":"Hook error, continuing"}
+    exit /b 0
+)
+
+exit /b 0

package/plugins/specweave/hooks/universal/session-start.cmd

@@ -1,16 +1,16 @@
-@echo off
-:: Universal Session Start Hook for Windows
-:: Calls the Node.js dispatcher
-
-:: Find node.exe
-where node >nul 2>&1
-if %ERRORLEVEL% neq 0 (
-    echo {"continue": true, "error": "Node.js not found"}
-    exit /b 0
-)
-
-:: Get the directory of this script
-set "SCRIPT_DIR=%~dp0"
-
-:: Run the dispatcher
-node "%SCRIPT_DIR%dispatcher.mjs" session-start
+@echo off
+:: Universal Session Start Hook for Windows
+:: Calls the Node.js dispatcher
+
+:: Find node.exe
+where node >nul 2>&1
+if %ERRORLEVEL% neq 0 (
+    echo {"continue": true, "error": "Node.js not found"}
+    exit /b 0
+)
+
+:: Get the directory of this script
+set "SCRIPT_DIR=%~dp0"
+
+:: Run the dispatcher
+node "%SCRIPT_DIR%dispatcher.mjs" session-start

package/plugins/specweave/hooks/universal/session-start.ps1

@@ -1,16 +1,16 @@
-# Universal Session Start Hook for Windows PowerShell
-# Calls the Node.js dispatcher for cross-platform compatibility
-
-# Find node.exe
-$nodePath = Get-Command node -ErrorAction SilentlyContinue
-
-if (-not $nodePath) {
-    Write-Host '{"continue": true, "error": "Node.js not found"}'
-    exit 0
-}
-
-# Get script directory
-$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-
-# Run the dispatcher
-& node "$scriptDir\dispatcher.mjs" session-start
+# Universal Session Start Hook for Windows PowerShell
+# Calls the Node.js dispatcher for cross-platform compatibility
+
+# Find node.exe
+$nodePath = Get-Command node -ErrorAction SilentlyContinue
+
+if (-not $nodePath) {
+    Write-Host '{"continue": true, "error": "Node.js not found"}'
+    exit 0
+}
+
+# Get script directory
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Run the dispatcher
+& node "$scriptDir\dispatcher.mjs" session-start

package/plugins/specweave-github/commands/clone.md

@@ -0,0 +1,509 @@
+---
+name: sw-github:clone
+description: Clone GitHub repositories to local workspace. Use after init if cloning was skipped, to resume interrupted cloning, or to add repos later. Already-cloned repos are automatically skipped.
+---
+
+# Clone GitHub Repositories Command
+
+You are a GitHub repository cloning expert. Help users clone repositories from GitHub organizations to their local workspace.
+
+## Purpose
+
+This command clones GitHub repositories **after** initial SpecWeave setup (`specweave init`). Use when:
+- User skipped cloning during init
+- **Resuming interrupted cloning** (already-cloned repos are skipped!)
+- Adding repositories from organization
+- Selective cloning with pattern filtering
+- Retrying after partial failures
+
+## CRITICAL: NEVER-STOP BEHAVIOR
+
+**This command NEVER stops on individual repo failures!**
+- Each repo failure is logged but cloning continues
+- Already-cloned repos are automatically skipped (resume = re-run!)
+- Final status: `completed` (all success) or `completed_with_warnings` (some failed)
+- Failed repos are listed in result.json for easy retry
+
+## Command Syntax
+
+```bash
+# Interactive mode (prompts for everything)
+/sw-github:clone
+
+# Clone from specific org
+/sw-github:clone --org "mycompany"
+
+# With pattern filter (glob)
+/sw-github:clone --pattern "api-*"
+
+# Regex pattern
+/sw-github:clone --pattern "regex:^frontend-.*$"
+
+# Dry-run (preview only)
+/sw-github:clone --dry-run
+
+# Resume/retry - just run again! Already cloned repos are skipped
+/sw-github:clone
+```
+
+## Your Task
+
+When the user runs this command:
+
+### Step 1: Check Prerequisites
+
+```typescript
+import { readEnvFile, parseEnvFile } from '../../../src/utils/env-file.js';
+import chalk from 'chalk';
+
+const projectPath = process.cwd();
+
+// Check for GitHub token
+const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+
+if (!token) {
+  // Try .env file
+  const envContent = readEnvFile(projectPath);
+  if (envContent) {
+    const parsed = parseEnvFile(envContent);
+    if (parsed.GH_TOKEN || parsed.GITHUB_TOKEN) {
+      // Token found in .env
+    } else {
+      console.log(chalk.red('❌ No GitHub token found.'));
+      console.log(chalk.gray('   Set GH_TOKEN or GITHUB_TOKEN environment variable.'));
+      console.log(chalk.gray('   Or add to .env file: GH_TOKEN=ghp_xxxx'));
+      return;
+    }
+  } else {
+    console.log(chalk.red('❌ No GitHub token found.'));
+    console.log(chalk.gray('   Set GH_TOKEN or GITHUB_TOKEN environment variable.'));
+    return;
+  }
+}
+
+console.log(chalk.blue('\n📦 GitHub Repository Cloning\n'));
+console.log(chalk.green('   ✓ GitHub token found'));
+```
+
+### Step 2: Get Organization
+
+```typescript
+import { input } from '@inquirer/prompts';
+
+let org = args.org;
+
+if (!org) {
+  // Try to detect from config
+  const configPath = path.join(projectPath, '.specweave', 'config.json');
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (config.github?.org) {
+      org = config.github.org;
+      console.log(chalk.gray(`   Organization: ${org} (from config)`));
+    }
+  }
+
+  if (!org) {
+    // Try to detect from git remote
+    const { execSync } = await import('child_process');
+    try {
+      const remote = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+      const match = remote.match(/github\.com[:/]([^/]+)/);
+      if (match) {
+        org = match[1];
+        console.log(chalk.gray(`   Detected org from git remote: ${org}`));
+      }
+    } catch {}
+  }
+
+  if (!org) {
+    org = await input({
+      message: 'Enter GitHub organization or username:',
+      validate: v => v.trim() ? true : 'Organization required'
+    });
+  }
+}
+
+console.log(chalk.gray(`   Organization: ${org}`));
+```
+
+### Step 3: Fetch Repositories
+
+```typescript
+console.log(chalk.gray('\n   Fetching repositories...'));
+
+// Fetch repos from GitHub API with pagination
+const pat = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+const allRepos = [];
+let page = 1;
+const perPage = 100;
+
+while (true) {
+  // Try org repos first, fall back to user repos
+  let response = await fetch(
+    `https://api.github.com/orgs/${encodeURIComponent(org)}/repos?per_page=${perPage}&page=${page}`,
+    {
+      headers: {
+        'Authorization': `Bearer ${pat}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28'
+      }
+    }
+  );
+
+  if (response.status === 404) {
+    // Try as user
+    response = await fetch(
+      `https://api.github.com/users/${encodeURIComponent(org)}/repos?per_page=${perPage}&page=${page}`,
+      {
+        headers: {
+          'Authorization': `Bearer ${pat}`,
+          'Accept': 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28'
+        }
+      }
+    );
+  }
+
+  if (!response.ok) {
+    console.log(chalk.red(`❌ Failed to fetch repos: ${response.status}`));
+    const error = await response.text();
+    console.log(chalk.gray(`   ${error}`));
+    return;
+  }
+
+  const batch = await response.json();
+  if (batch.length === 0) break;
+
+  allRepos.push(...batch);
+
+  if (batch.length < perPage) break;
+  page++;
+
+  // Progress for large orgs
+  if (allRepos.length % 100 === 0) {
+    console.log(chalk.gray(`   Fetched ${allRepos.length} repos...`));
+  }
+}
+
+if (allRepos.length === 0) {
+  console.log(chalk.yellow('\n⚠️  No repositories found.'));
+  return;
+}
+
+console.log(chalk.green(`   ✓ Found ${allRepos.length} repositories in ${org}`));
+```
+
+### Step 4: Check Already Cloned (Resume Detection)
+
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Check which repos already exist
+const alreadyCloned = [];
+const needsCloning = [];
+
+for (const repo of allRepos) {
+  const repoPath = path.join(projectPath, repo.name, '.git');
+  if (fs.existsSync(repoPath)) {
+    alreadyCloned.push(repo);
+  } else {
+    needsCloning.push(repo);
+  }
+}
+
+if (alreadyCloned.length > 0) {
+  console.log(chalk.cyan(`\n   📂 Already cloned: ${alreadyCloned.length} repos (will be skipped)`));
+  if (alreadyCloned.length <= 5) {
+    alreadyCloned.forEach(r => console.log(chalk.gray(`      ✓ ${r.name}`)));
+  } else {
+    alreadyCloned.slice(0, 3).forEach(r => console.log(chalk.gray(`      ✓ ${r.name}`)));
+    console.log(chalk.gray(`      ... and ${alreadyCloned.length - 3} more`));
+  }
+}
+
+console.log(chalk.blue(`\n   📦 Need to clone: ${needsCloning.length} repos`));
+```
+
+### Step 5: Apply Pattern Filter
+
+```typescript
+import { filterRepositoriesByPattern } from '../../../src/cli/helpers/selection-strategy.js';
+import { select, input } from '@inquirer/prompts';
+
+let filteredRepos = needsCloning;
+let patternDescription = 'all';
+
+if (args.pattern) {
+  const isRegex = args.pattern.startsWith('regex:');
+  const pattern = isRegex ? args.pattern.slice(6) : args.pattern;
+
+  const clonePattern = {
+    strategy: isRegex ? 'pattern-regex' : 'pattern-glob',
+    pattern: pattern,
+    isRegex
+  };
+
+  filteredRepos = filterRepositoriesByPattern(needsCloning, clonePattern);
+  patternDescription = `matching "${pattern}"`;
+
+  console.log(chalk.gray(`   Pattern: ${args.pattern}`));
+  console.log(chalk.gray(`   Matched: ${filteredRepos.length} of ${needsCloning.length} repos\n`));
+} else if (needsCloning.length > 0) {
+  const strategy = await select({
+    message: 'How do you want to select repositories?',
+    choices: [
+      { name: 'All - Clone all repositories', value: 'all' },
+      { name: 'Pattern (glob) - e.g., "api-*", "*-backend"', value: 'pattern-glob' },
+      { name: 'Pattern (regex) - e.g., "^api-.*$"', value: 'pattern-regex' }
+    ]
+  });
+
+  if (strategy !== 'all') {
+    const pattern = await input({
+      message: 'Enter pattern:',
+      validate: v => v.trim() ? true : 'Pattern required'
+    });
+
+    const clonePattern = {
+      strategy,
+      pattern: pattern.trim(),
+      isRegex: strategy === 'pattern-regex'
+    };
+
+    filteredRepos = filterRepositoriesByPattern(needsCloning, clonePattern);
+    patternDescription = `matching "${pattern.trim()}"`;
+  }
+}
+
+if (filteredRepos.length === 0) {
+  if (alreadyCloned.length > 0) {
+    console.log(chalk.green(`\n✅ All ${alreadyCloned.length} repos already cloned. Nothing to do!`));
+  } else {
+    console.log(chalk.yellow(`\n⚠️  No repositories ${patternDescription}.`));
+  }
+  return;
+}
+```
+
+### Step 6: Preview and Confirm
+
+```typescript
+import { confirm } from '@inquirer/prompts';
+
+console.log(chalk.blue(`\n📦 Repositories to clone (${filteredRepos.length}):\n`));
+
+// Show preview (max 20)
+filteredRepos.slice(0, 20).forEach(repo => {
+  console.log(chalk.gray(`   • ${repo.name}`));
+});
+
+if (filteredRepos.length > 20) {
+  console.log(chalk.gray(`   ... and ${filteredRepos.length - 20} more\n`));
+}
+
+if (args.dryRun) {
+  console.log(chalk.cyan('\n🔎 DRY RUN: No repositories will be cloned.\n'));
+  console.log(chalk.gray('   Remove --dry-run to actually clone.'));
+  return;
+}
+
+const confirmed = await confirm({
+  message: `Clone ${filteredRepos.length} repositories to current directory?`,
+  default: true
+});
+
+if (!confirmed) {
+  console.log(chalk.gray('\n⏭️  Cloning cancelled.\n'));
+  return;
+}
+```
+
+### Step 7: Start Background Cloning
+
+```typescript
+import { triggerGitHubRepoCloning } from '../../../src/cli/helpers/init/github-repo-cloning.js';
+
+// Build selection
+const githubRepoSelection = {
+  org,
+  pat: process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+};
+
+// Build clonePattern
+const clonePatternResult = args.pattern
+  ? {
+      strategy: args.pattern.startsWith('regex:') ? 'pattern-regex' : 'pattern-glob',
+      pattern: args.pattern.startsWith('regex:') ? args.pattern.slice(6) : args.pattern
+    }
+  : { strategy: 'all' };
+
+// Trigger background cloning
+const jobId = await triggerGitHubRepoCloning(projectPath, githubRepoSelection, clonePatternResult);
+
+if (jobId) {
+  console.log(chalk.green('\n✅ Clone job started successfully!\n'));
+  console.log(chalk.blue('📋 Key Points:'));
+  console.log(chalk.gray('   • Cloning runs in background - you can continue working'));
+  console.log(chalk.gray('   • Already-cloned repos are automatically skipped'));
+  console.log(chalk.gray('   • Individual failures do NOT stop the job'));
+  console.log(chalk.gray('   • To resume after interruption: just run /sw-github:clone again!\n'));
+
+  console.log(chalk.blue('🔧 Commands:'));
+  console.log(chalk.cyan(`   /sw:jobs                    → Check progress`));
+  console.log(chalk.cyan(`   /sw:jobs --follow ${jobId.slice(0, 8)} → Follow live`));
+  console.log(chalk.cyan(`   /sw:jobs --logs ${jobId.slice(0, 8)}   → View logs`));
+}
+```
+
+## Examples
+
+### Example 1: Fresh Clone
+**User**: `/sw-github:clone --org olympusnova`
+
+**Output**:
+```
+📦 GitHub Repository Cloning
+
+   ✓ GitHub token found
+   Organization: olympusnova
+
+   Fetching repositories...
+   ✓ Found 512 repositories in olympusnova
+
+   📦 Need to clone: 512 repos
+
+How do you want to select repositories?
+> All - Clone all repositories
+
+📦 Repositories to clone (512):
+
+   • api-gateway
+   • frontend-web
+   • mobile-app
+   ... and 509 more
+
+Clone 512 repositories to current directory? (Y/n)
+
+🔄 Starting background clone for 512 repositories...
+
+   ✓ Clone job started in background (PID: 12345)
+
+✅ Clone job started successfully!
+
+📋 Key Points:
+   • Cloning runs in background - you can continue working
+   • Already-cloned repos are automatically skipped
+   • Individual failures do NOT stop the job
+   • To resume after interruption: just run /sw-github:clone again!
+
+🔧 Commands:
+   /sw:jobs                    → Check progress
+   /sw:jobs --follow abc12345  → Follow live
+   /sw:jobs --logs abc12345    → View logs
+```
+
+### Example 2: Resume After Interruption
+**User**: `/sw-github:clone` (after previous job was interrupted at 87/512)
+
+**Output**:
+```
+📦 GitHub Repository Cloning
+
+   ✓ GitHub token found
+   Organization: olympusnova (from config)
+
+   Fetching repositories...
+   ✓ Found 512 repositories in olympusnova
+
+   📂 Already cloned: 87 repos (will be skipped)
+      ✓ api-gateway
+      ✓ frontend-web
+      ✓ mobile-app
+      ... and 84 more
+
+   📦 Need to clone: 425 repos
+
+Clone 425 repositories to current directory? (Y/n)
+
+🔄 Resuming clone for 425 remaining repositories...
+```
+
+### Example 3: Pattern Filter
+**User**: `/sw-github:clone --pattern "api-*"`
+
+**Output**:
+```
+📦 GitHub Repository Cloning
+
+   Pattern: api-*
+   Matched: 45 of 512 repos
+
+📦 Repositories to clone (45):
+
+   • api-gateway
+   • api-auth
+   • api-payments
+   ...
+```
+
+### Example 4: Dry Run
+**User**: `/sw-github:clone --dry-run`
+
+**Output**:
+```
+📦 Repositories to clone (512):
+
+   • api-gateway
+   • frontend-web
+   ...
+
+🔎 DRY RUN: No repositories will be cloned.
+   Remove --dry-run to actually clone.
+```
+
+## Important Notes
+
+### Resume = Just Re-run!
+**There's no special resume command.** Just run `/sw-github:clone` again:
+- Already-cloned repos are detected via `.git` folder
+- They're automatically skipped (instant, no API calls)
+- Only remaining repos are queued for cloning
+
+### Never Stops on Failure
+- Each repo cloned independently
+- Failures logged but don't stop the job
+- Final status: `completed_with_warnings` if any failed
+- Failed repo list saved to `result.json`
+
+### Retry Failed Repos
+After job completes with warnings:
+```bash
+# Check which repos failed
+cat .specweave/state/jobs/<jobId>/result.json
+
+# Just run clone again - it skips successful ones!
+/sw-github:clone
+```
+
+## Related Commands
+
+- `/sw:init` - Initial SpecWeave setup (includes repo cloning option)
+- `/sw:jobs` - Monitor background jobs
+- `/sw:jobs --follow <id>` - Watch progress live
+- `/sw-github:sync` - Sync with GitHub Issues
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| No GitHub token | Missing env var | Set `GH_TOKEN` or `GITHUB_TOKEN` |
+| 401 Unauthorized | Invalid token | Check token has `repo` scope |
+| 404 Not Found | Wrong org name | Verify organization/username |
+| Rate limit | Too many API calls | Wait and retry, or use pagination |
+| Clone failure | Permission/network | Job continues, repo listed in failures |
+
+---
+
+**Multi-Repo Support**: Perfect for microservices architectures with many GitHub repositories.