specweave 0.18.0 → 0.20.0

package/plugins/specweave/commands/specweave-restore-feature.md

@@ -0,0 +1,90 @@
+---
+name: specweave-restore-feature
+description: Restore a feature or epic from archive back to active status
+---
+
+# Restore Feature or Epic from Archive
+
+Restore an archived feature or epic back to its active location. This also restores all project-specific folders and updates links throughout the codebase.
+
+## Usage
+
+```bash
+/specweave:restore-feature <feature-or-epic-id>
+```
+
+## Examples
+
+```bash
+# Restore a feature
+/specweave:restore-feature FS-001
+
+# Restore an epic
+/specweave:restore-feature EPIC-2024-Q4
+```
+
+## What Gets Restored
+
+### For Features:
+1. `_features/_archive/FS-XXX/` → `_features/FS-XXX/`
+2. `{project}/_archive/FS-XXX/` → `{project}/FS-XXX/` (all projects)
+3. All links updated from archive paths back to active paths
+
+### For Epics:
+1. `_epics/_archive/EPIC-XXX/` → `_epics/EPIC-XXX/`
+2. All links updated from archive paths back to active paths
+
+## Important Notes
+
+- Cannot restore if the item already exists in active location
+- Links are automatically updated throughout the codebase
+- Consider restoring related increments if needed
+
+## Implementation
+
+```typescript
+import { Task } from '@claude/types';
+
+const task = new Task('restore-feature', 'Restore feature or epic from archive');
+
+task.run(async () => {
+  const itemId = process.argv[3]; // Get the feature/epic ID
+
+  if (!itemId) {
+    console.error('❌ Please provide a feature or epic ID to restore');
+    console.log('Usage: /specweave:restore-feature <feature-or-epic-id>');
+    console.log('Example: /specweave:restore-feature FS-001');
+    process.exit(1);
+  }
+
+  const { FeatureArchiver } = await import('../../../dist/src/core/living-docs/feature-archiver.js');
+  const archiver = new FeatureArchiver(process.cwd());
+
+  try {
+    // Determine if it's a feature or epic
+    const isEpic = itemId.startsWith('EPIC-');
+
+    if (isEpic) {
+      // Restore epic (to be implemented)
+      await archiver.restoreEpic(itemId);
+      console.log(`✅ Restored epic ${itemId} from archive`);
+    } else {
+      // Restore feature
+      await archiver.restoreFeature(itemId);
+      console.log(`✅ Restored feature ${itemId} from archive`);
+    }
+
+    // Show current stats
+    const stats = await archiver.getArchiveStats();
+    console.log('\n📊 Current Archive Statistics:');
+    console.log(`  Features: ${stats.features.active} active, ${stats.features.archived} archived`);
+    console.log(`  Epics: ${stats.epics.active} active, ${stats.epics.archived} archived`);
+
+  } catch (error) {
+    console.error(`❌ Failed to restore ${itemId}: ${error.message}`);
+    process.exit(1);
+  }
+});
+
+export default task;
+```

package/plugins/specweave/commands/specweave-restore.md

@@ -0,0 +1,309 @@
+---
+name: specweave:restore
+description: Restore archived increments back to active folder
+---
+
+# Restore Increment from Archive
+
+Restore an archived increment back to the main increments folder. Useful when you need to reference, update, or continue work on an old increment.
+
+## Usage
+
+```bash
+# Restore specific increment
+/specweave:restore 0031
+
+# Restore multiple increments
+/specweave:restore 0001 0002 0003
+
+# List archived increments
+/specweave:restore --list
+```
+
+## Arguments
+
+- `<increment-ids>`: Increment IDs to restore (e.g., "1", "0001", "0031")
+- `--list`: List all archived increments without restoring
+
+## Examples
+
+### Example 1: Restore Specific Increment
+
+```bash
+/specweave:restore 0031
+```
+
+**Output**:
+```
+📦 Restoring increment from archive...
+
+Increment: 0031-external-tool-status-sync
+Source: .specweave/increments/_archive/0031-external-tool-status-sync/
+Target: .specweave/increments/0031-external-tool-status-sync/
+
+Checking target location...
+  ✓ Target location is empty
+
+✅ Restored: 0031-external-tool-status-sync
+   Location: .specweave/increments/0031-external-tool-status-sync/
+
+📊 Archive Statistics:
+   Active: 33 increments (+ 1 restored)
+   Archived: 30 increments (- 1)
+
+Next: /specweave:do 0031 (to continue work)
+```
+
+### Example 2: List Archived Increments
+
+```bash
+/specweave:restore --list
+```
+
+**Output**:
+```
+📦 Archived Increments:
+
+.specweave/increments/_archive/
+├── 0001-core-framework (152 days old)
+├── 0002-plugin-system (148 days old)
+├── 0003-auth-service (145 days old)
+├── 0004-payment-integration (142 days old)
+├── 0005-api-gateway (140 days old)
+...
+├── 0030-jira-integration (35 days old)
+└── 0031-external-tool-status-sync (12 days old)
+
+Total: 31 archived increments
+
+To restore: /specweave:restore <increment-id>
+```
+
+### Example 3: Restore Multiple Increments
+
+```bash
+/specweave:restore 0030 0031
+```
+
+**Output**:
+```
+📦 Restoring increments from archive...
+
+Restoring 0030-jira-integration...
+  ✅ Restored
+
+Restoring 0031-external-tool-status-sync...
+  ✅ Restored
+
+✅ Restored: 2 increments
+
+📊 Archive Statistics:
+   Active: 34 increments (+ 2 restored)
+   Archived: 29 increments (- 2)
+```
+
+## Error Handling
+
+### Increment Not Found in Archive
+
+```
+❌ Error: Increment 0031 not found in archive
+
+Archive location: .specweave/increments/_archive/
+
+Available archived increments:
+  • 0001-core-framework
+  • 0002-plugin-system
+  • 0003-auth-service
+  ...
+
+Use: /specweave:restore --list to see all
+```
+
+### Target Location Already Exists
+
+```
+❌ Error: Cannot restore 0031 - already exists in active folder
+
+Conflict:
+  Archive: .specweave/increments/_archive/0031-external-tool-status-sync/
+  Active: .specweave/increments/0031-external-tool-status-sync/
+
+Options:
+  1. Delete active version first (if it's a duplicate)
+  2. Resolve duplicates: /specweave:fix-duplicates
+  3. Archive active version: /specweave:archive 0031
+  4. Rename one version manually
+
+Recommended: /specweave:fix-duplicates (auto-resolves conflicts)
+```
+
+### Permission Errors
+
+```
+❌ Error: Permission denied
+
+Could not move:
+  From: .specweave/increments/_archive/0031-external-tool-status-sync/
+  To: .specweave/increments/0031-external-tool-status-sync/
+
+Check:
+  • File permissions
+  • Disk space
+  • Files not open in another program
+```
+
+## Safety Checks
+
+Before restoring, the system checks:
+- ✅ **Increment exists in archive**: Source folder exists
+- ✅ **Target location empty**: No conflict in main folder
+- ✅ **Valid increment structure**: Has required files (metadata.json)
+- ✅ **Disk space available**: Enough space for restored files
+
+## Related Commands
+
+- `/specweave:archive <increment-id>` - Archive completed increments
+- `/specweave:status` - View archive statistics
+- `/specweave:fix-duplicates` - Auto-resolve duplicate increments
+- `/specweave:do <increment-id>` - Resume work on restored increment
+
+## Implementation
+
+```typescript
+import { Task } from '@claude/types';
+
+const task = new Task('restore-increment', 'Restore increment from archive');
+
+task.run(async () => {
+  const { IncrementArchiver } = await import('../../../dist/src/core/increment/increment-archiver.js');
+  const archiver = new IncrementArchiver(process.cwd());
+
+  // Parse arguments
+  const args = process.argv.slice(2);
+
+  // List mode
+  if (args.includes('--list')) {
+    const archived = await archiver.listArchived();
+    console.log('\n📦 Archived Increments:\n');
+
+    if (archived.length === 0) {
+      console.log('No archived increments found.');
+      return;
+    }
+
+    console.log('.specweave/increments/_archive/');
+    archived.forEach(inc => {
+      console.log(`├── ${inc}`);
+    });
+    console.log(`\nTotal: ${archived.length} archived increments`);
+    console.log('\nTo restore: /specweave:restore <increment-id>');
+    return;
+  }
+
+  // Restore mode
+  const incrementIds = args.filter(arg => !arg.startsWith('--'));
+
+  if (incrementIds.length === 0) {
+    console.error('❌ Error: No increment IDs provided');
+    console.log('\nUsage:');
+    console.log('  /specweave:restore <increment-id>');
+    console.log('  /specweave:restore --list');
+    return;
+  }
+
+  // Restore each increment
+  let restored = 0;
+  let errors = 0;
+
+  for (const id of incrementIds) {
+    try {
+      // Normalize ID to 4-digit format
+      const normalizedId = id.padStart(4, '0');
+
+      // Find archived increment
+      const archived = await archiver.listArchived();
+      const match = archived.find(inc => inc.startsWith(normalizedId));
+
+      if (!match) {
+        console.error(`❌ Increment ${normalizedId} not found in archive`);
+        errors++;
+        continue;
+      }
+
+      // Restore increment
+      await archiver.restore(match);
+      console.log(`✅ Restored: ${match}`);
+      restored++;
+    } catch (error) {
+      console.error(`❌ Failed to restore ${id}: ${error.message}`);
+      errors++;
+    }
+  }
+
+  // Show statistics
+  if (restored > 0 || errors > 0) {
+    console.log('\n📊 Restore Summary:');
+    if (restored > 0) {
+      console.log(`   ✅ Restored: ${restored} increment${restored > 1 ? 's' : ''}`);
+    }
+    if (errors > 0) {
+      console.log(`   ❌ Errors: ${errors} increment${errors > 1 ? 's' : ''}`);
+    }
+
+    // Show updated stats
+    const stats = await archiver.getStats();
+    console.log('\n📊 Archive Statistics:');
+    console.log(`   Active: ${stats.active} increments`);
+    console.log(`   Archived: ${stats.archived} increments`);
+  }
+});
+
+export default task;
+```
+
+## Important Notes
+
+### Archive is Not Deletion
+
+**Archives are preserved history**, not deleted work. You can restore anytime:
+- ✅ Full increment structure preserved
+- ✅ All files, reports, and metadata intact
+- ✅ Git history preserved (if committed)
+- ✅ External tool links preserved in metadata
+
+### When to Restore
+
+Common scenarios for restoring from archive:
+- 🔍 **Reference old implementation** - Check how something was done
+- 🔄 **Resume abandoned work** - Pick up where you left off
+- 🐛 **Bug investigation** - Review completed increment for context
+- 📝 **Documentation** - Update reports or completion summaries
+- 🔗 **External sync recovery** - Re-sync to GitHub/JIRA if needed
+
+### After Restoring
+
+Once restored, the increment is back in the active folder:
+- ✅ Shows up in `/specweave:status`
+- ✅ Can be resumed with `/specweave:do`
+- ✅ Can be re-archived with `/specweave:archive`
+- ✅ Included in increment counts and WIP limits
+
+---
+
+**Best Practice**: Keep archives clean by only restoring when needed, then re-archiving when done.
+
+**Recommended Workflow**:
+```bash
+# 1. List archived increments
+/specweave:restore --list
+
+# 2. Restore specific increment
+/specweave:restore 0031
+
+# 3. Review or update the increment
+cat .specweave/increments/0031-external-tool-status-sync/spec.md
+
+# 4. Re-archive when done
+/specweave:archive 0031
+```

package/plugins/specweave/commands/specweave-resume.md

@@ -1,6 +1,6 @@
 ---
 name: specweave:resume
-description: Resume a paused increment
+description: Resume a paused or backlog increment
 usage: /specweave:resume <increment-id>
 ---
 
@@ -12,29 +12,41 @@ usage: /specweave:resume <increment-id>
 
 ## Purpose
 
-Resume a paused increment when:
-- **Blocker resolved** (API keys arrived, approval granted)
-- **Ready to continue** after deprioritization
-- **Prerequisite completed** (can now proceed)
+Resume a paused or backlog increment when:
+- **From Backlog**: Ready to start planned work
+- **From Paused**: Blocker resolved (API keys arrived, approval granted)
+- **From Paused**: Ready to continue after deprioritization
+- **From Paused**: Prerequisite completed (can now proceed)
 
 ---
 
 ## Behavior
 
-1. **Validates** increment exists and is "paused"
-2. **Calculates** pause duration (days, hours)
+1. **Validates** increment exists and is "paused" or "backlog"
+2. **Calculates** pause/backlog duration (days, hours)
 3. **Updates** metadata.json:
-   - `status`: "paused" → "active"
-   - Clears `pausedReason` and `pausedAt`
+   - `status`: "paused" or "backlog" → "active"
+   - Clears `pausedReason` and `pausedAt` (if paused)
+   - Clears `backlogReason` and `backlogAt` (if backlog)
    - Updates `lastActivity` timestamp
-4. **Displays** context (pause duration, last activity)
-5. **Suggests** next actions (`/specweave:do` to continue work)
+4. **Displays** context (duration, last activity)
+5. **Suggests** next actions (`/specweave:do` to continue/start work)
 
 ---
 
 ## Examples
 
-### Resume after a few days
+### Resume from backlog
+```bash
+/specweave:resume 0032
+
+✅ Increment 0032 activated from backlog
+📦 Was in backlog for: 5 days
+💡 Reason: Low priority, focus on 0031 first
+📋 Start work with: /specweave:do
+```
+
+### Resume paused work after a few days
 ```bash
 /specweave:resume 0006
 
@@ -44,7 +56,7 @@ Resume a paused increment when:
 📋 Continue with: /specweave:do
 ```
 
-### Resume after a few hours
+### Resume paused work after a few hours
 ```bash
 /specweave:resume 0007
 
@@ -114,14 +126,20 @@ if (metadata.status === IncrementStatus.COMPLETED) {
   throw new Error('Cannot resume completed increment');
 }
 
-// Calculate pause duration
-const pauseDuration = calculateDuration(metadata.pausedAt, new Date());
+// Calculate duration based on status
+let duration;
+if (metadata.status === IncrementStatus.PAUSED && metadata.pausedAt) {
+  duration = calculateDuration(metadata.pausedAt, new Date());
+  console.log(`Was paused for: ${duration}`);
+} else if (metadata.status === IncrementStatus.BACKLOG && metadata.backlogAt) {
+  duration = calculateDuration(metadata.backlogAt, new Date());
+  console.log(`Was in backlog for: ${duration}`);
+}
 
-// Update status
+// Update status to active
 MetadataManager.updateStatus(incrementId, IncrementStatus.ACTIVE);
 
 // Display context
-console.log(`Was paused for: ${pauseDuration}`);
 console.log(`Last activity: ${getLastActivity(incrementId)}`);
 ```
 
@@ -130,7 +148,9 @@ console.log(`Last activity: ${getLastActivity(incrementId)}`);
 ## Status Flow
 
 ```
-paused ──resume──> active
+backlog ──resume──> active (start work)
+   │
+paused ──resume──> active (continue work)
    │
 abandoned ──resume──> active (with confirmation)
 ```
@@ -139,10 +159,12 @@ abandoned ──resume──> active (with confirmation)
 
 ## Related Commands
 
-- `/pause <id>` - Pause active increment
-- `/status` - Show all increment statuses
-- `/status --paused` - Show only paused increments
-- `/do` - Continue work after resuming
+- `/specweave:pause <id>` - Pause active increment
+- `/specweave:backlog <id>` - Move increment to backlog
+- `/specweave:status` - Show all increment statuses
+- `/specweave:status --paused` - Show only paused increments
+- `/specweave:status --backlog` - Show only backlog increments
+- `/specweave:do` - Continue/start work after resuming
 
 ---
 
@@ -164,11 +186,17 @@ abandoned ──resume──> active (with confirmation)
 
 ## Automatic Suggestions
 
-When you run `/specweave:status`, stale paused increments trigger suggestions:
+When you run `/specweave:status`, stale paused/backlog increments trigger suggestions:
 
 ```bash
 /specweave:status
 
+🗂️  Backlog (2):
+  📦 0032-feature-a [feature]
+     In backlog: 5 days
+     Reason: Low priority
+     💡 Ready to start? → /specweave:resume 0032
+
 ⏸️  Paused (2):
   🔄 0006-stripe [feature]
      Paused: 3 days ago

package/plugins/specweave/commands/specweave-status.md

@@ -1,7 +1,7 @@
 ---
 name: specweave:status
-description: Show increment status overview with rich details (active, paused, completed, abandoned)
-usage: /specweave:status [--active|--paused|--completed|--abandoned|--stale]
+description: Show increment status overview with rich details (active, backlog, paused, completed, abandoned)
+usage: /specweave:status [--active|--backlog|--paused|--completed|--abandoned|--stale]
 ---
 
 # Increment Status Command
@@ -14,6 +14,7 @@ usage: /specweave:status [--active|--paused|--completed|--abandoned|--stale]
 
 Display comprehensive increment status overview:
 - **Active** increments (currently working)
+- **Backlog** increments (planned but not started)
 - **Paused** increments (blocked/deprioritized)
 - **Completed** increments (done)
 - **Abandoned** increments (obsolete)
@@ -42,6 +43,15 @@ Display comprehensive increment status overview:
      Age: 2 days
      Last: Created translation pipeline
 
+🗂️  Backlog (2):
+  📦 0032-feature-a [feature]
+     In backlog: 5 days
+     Reason: Low priority
+
+  📦 0033-feature-b [feature]
+     In backlog: 3 days
+     Reason: Waiting for decisions
+
 ⏸️  Paused (1):
   🔄 0007-stripe-integration [feature]
      Progress: 30% (6/20 tasks)
@@ -57,6 +67,7 @@ Display comprehensive increment status overview:
 
 📊 Summary:
   - Active: 2 increments (1 hotfix, 1 feature)
+  - Backlog: 2 increments (planned for future)
   - Paused: 1 increment
   - Completed: 4 increments
   - Context switching: 20-40% cost (2 active)
@@ -122,6 +133,7 @@ const allIncrements = MetadataManager.getAll();
 
 // Group by status
 const active = allIncrements.filter(m => m.status === IncrementStatus.ACTIVE);
+const backlog = allIncrements.filter(m => m.status === IncrementStatus.BACKLOG);
 const paused = allIncrements.filter(m => m.status === IncrementStatus.PAUSED);
 const completed = allIncrements.filter(m => m.status === IncrementStatus.COMPLETED);
 const abandoned = allIncrements.filter(m => m.status === IncrementStatus.ABANDONED);
@@ -148,6 +160,7 @@ if (active.length > 0) {
 // Summary with type limits (v0.7.0+)
 console.log('\n📊 Summary:');
 console.log(`  - Active: ${active.length} increments`);
+console.log(`  - Backlog: ${backlog.length} increments`);
 console.log(`  - Paused: ${paused.length} increments`);
 console.log(`  - Completed: ${completed.length} increments`);
 
@@ -263,6 +276,26 @@ Show only active increments
   🔧 0006-i18n [feature] (50% done)
 ```
 
+### --backlog
+
+Show only backlog increments
+
+```bash
+/specweave:status --backlog
+
+🗂️  Backlog (3):
+  📦 0032-feature-a [feature] (in backlog 5 days)
+     Reason: Low priority
+
+  📦 0033-feature-b [feature] (in backlog 3 days)
+     Reason: Waiting for decisions
+
+  📦 0034-feature-c [feature] (in backlog 1 day)
+     Reason: Multiple planned ideas
+
+💡 Start work: /specweave:resume <id>
+```
+
 ### --paused
 
 Show only paused increments
@@ -336,11 +369,12 @@ Show only stale increments (paused >7 days OR active >30 days)
 
 ## Related Commands
 
-- `/do` - Continue work on active increment
-- `/progress` - Detailed progress for current increment
-- `/pause <id>` - Pause active increment
-- `/resume <id>` - Resume paused increment
-- `/abandon <id>` - Abandon increment (move to _abandoned/)
+- `/specweave:do` - Continue work on active increment
+- `/specweave:progress` - Detailed progress for current increment
+- `/specweave:backlog <id>` - Move increment to backlog
+- `/specweave:pause <id>` - Pause active increment
+- `/specweave:resume <id>` - Resume paused or backlog increment
+- `/specweave:abandon <id>` - Abandon increment (move to _abandoned/)
 
 ---