specweave 0.18.0 → 0.20.0

package/plugins/specweave/commands/specweave-archive-increments.md

@@ -0,0 +1,82 @@
+---
+name: specweave-archive-increments
+description: Archive completed increments to keep workspace clean
+---
+
+# Archive Increments Command
+
+Archives completed increments to `_archive/` folder, keeping only the most recent N increments in the main folder.
+
+## Usage
+
+```bash
+# Interactive mode - prompts for options
+/specweave:archive-increments
+
+# Keep last 5 increments, archive the rest
+/specweave:archive-increments --keep-last 5
+
+# Archive specific increments
+/specweave:archive-increments --increments 0001,0002,0003
+
+# Dry run - see what would be archived without moving
+/specweave:archive-increments --dry-run
+
+# Archive all completed increments older than 30 days
+/specweave:archive-increments --older-than 30d
+
+# Keep only active/paused, archive all completed
+/specweave:archive-increments --archive-completed
+```
+
+## Default Behavior
+
+- Keeps last 10 increments by default
+- Preserves all active/paused increments
+- Never archives abandoned increments (they stay in `_abandoned/`)
+- Creates `_archive/` folder if it doesn't exist
+- Preserves increment structure and all contents
+
+## Smart Detection
+
+The command intelligently:
+- Checks increment status from metadata.json
+- Preserves increments with active GitHub/JIRA/ADO issues
+- Warns before archiving increments with uncommitted changes
+- Groups related increments (e.g., all v0.8.0 stabilization increments)
+
+## Configuration
+
+Set defaults in `.specweave/config.json`:
+
+```json
+{
+  "archiving": {
+    "keepLast": 10,
+    "autoArchive": true,
+    "archiveAfterDays": 60,
+    "preserveActive": true,
+    "archiveCompleted": true
+  }
+}
+```
+
+## Examples
+
+### Keep workspace clean
+```bash
+# Archive all but last 5 increments
+/specweave:archive-increments --keep-last 5
+```
+
+### Prepare for release
+```bash
+# Archive all v0.7.x increments after v0.8.0 release
+/specweave:archive-increments --pattern "v0.7"
+```
+
+### Clean old work
+```bash
+# Archive increments older than 2 months
+/specweave:archive-increments --older-than 60d
+```

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

@@ -0,0 +1,363 @@
+---
+name: specweave:archive
+description: Manually archive completed increments - NEVER auto-archives, explicit user action only
+---
+
+# Archive Increments (Manual Only)
+
+**CRITICAL POLICY**: Increments are **NEVER** auto-archived. Archiving is **MANUAL ONLY** and requires explicit user action via this command.
+
+## Philosophy
+
+**Keep recent work visible** - Completed increments remain in the main folder for easy reference until you explicitly archive them. This allows:
+- ✅ Quick reference to recent implementations
+- ✅ Easy linking in new increments
+- ✅ Visible completion history
+- ✅ ~10-20 completed increments available without searching archives
+
+## Usage
+
+```bash
+# Archive specific increment
+/specweave:archive 0031
+
+# Archive multiple increments
+/specweave:archive 0001 0002 0003
+
+# Archive all completed increments older than N days
+/specweave:archive --older-than 90
+
+# Keep last N increments, archive the rest
+/specweave:archive --keep-last 10
+
+# Archive by pattern
+/specweave:archive --pattern "auth-*"
+
+# Dry run (preview without archiving)
+/specweave:archive --dry-run --older-than 90
+```
+
+## Options
+
+- `<increment-ids>`: Specific increment IDs to archive (e.g., "1", "0001", "0031")
+- `--older-than <days>`: Archive increments older than N days
+- `--keep-last <n>`: Keep last N increments, archive the rest (default: 10)
+- `--pattern <regex>`: Archive increments matching pattern
+- `--archive-completed`: Archive all completed increments (use with caution!)
+- `--preserve-active`: Never archive active/paused increments (default: true)
+- `--dry-run`: Show what would be archived without moving files
+
+## Archive Rules
+
+### Increments are archived when:
+1. Explicitly specified by ID (e.g., `/specweave:archive 0031`)
+2. Match age criteria (e.g., `--older-than 90`)
+3. Match pattern criteria (e.g., `--pattern "old-*"`)
+4. Not in last N increments (e.g., `--keep-last 10`)
+
+### Safety Checks (Always Applied):
+- ✅ **Active/paused protection**: Never archive active or paused increments
+- ✅ **External sync protection**: Skip increments with open GitHub/JIRA/ADO issues
+- ✅ **Uncommitted changes**: Warn if git has uncommitted changes
+- ✅ **Duplicate prevention**: Refuse if increment already exists in archive
+
+### Archive Structure:
+```
+.specweave/increments/
+├── 0030-recent-work/           # Active/recent increments
+├── 0031-recent-work/           # Stay visible for reference
+├── 0032-recent-work/
+├── 0033-recent-work/
+│
+├── _archive/                   # Archived increments
+│   ├── 0001-old-work/          # Manually archived
+│   ├── 0002-old-work/
+│   └── 0003-old-work/
+│
+└── _abandoned/                 # Abandoned work (separate)
+    └── 0004-abandoned-work/
+```
+
+## Examples
+
+### Example 1: Archive Specific Increment
+
+```bash
+/specweave:archive 0031
+```
+
+**Output**:
+```
+📦 Archiving increments...
+
+Checking increment 0031-external-tool-status-sync...
+  ✓ Status: completed
+  ✓ No active external sync
+  ✓ No uncommitted changes
+  ✓ Not already in archive
+
+✅ Archived: 0031-external-tool-status-sync
+   Location: .specweave/increments/_archive/0031-external-tool-status-sync/
+
+📊 Archive Statistics:
+   Active: 32 increments
+   Archived: 31 increments (+ 1 new)
+
+Next: /specweave:restore 0031 (if you need to unarchive)
+```
+
+### Example 2: Archive Old Increments (Keep Last 10)
+
+```bash
+/specweave:archive --keep-last 10
+```
+
+**Output**:
+```
+📦 Archiving increments (keeping last 10)...
+
+Found 33 total increments
+Keeping: 0024-0033 (last 10)
+Candidates for archive: 0001-0023 (23 increments)
+
+Filtering by status and safety checks...
+  ✓ 0001-core-framework (completed, no blockers)
+  ✓ 0002-plugin-system (completed, no blockers)
+  ...
+  ⚠ 0015-auth-service (GitHub issue still open) - SKIPPED
+  ✓ 0016-payment-integration (completed, no blockers)
+  ...
+
+✅ Archived: 22 increments
+⚠️  Skipped: 1 increment (external sync active)
+
+📊 Archive Statistics:
+   Active: 11 increments (10 recent + 1 with open issue)
+   Archived: 53 increments (+ 22 new)
+   Total size: 245 MB
+```
+
+### Example 3: Dry Run (Preview)
+
+```bash
+/specweave:archive --older-than 90 --dry-run
+```
+
+**Output**:
+```
+🔍 DRY RUN - No files will be moved
+
+Increments older than 90 days:
+  [DRY RUN] Would archive: 0001-core-framework (152 days old)
+  [DRY RUN] Would archive: 0002-plugin-system (148 days old)
+  [DRY RUN] Would archive: 0003-auth-service (145 days old)
+  [DRY RUN] Would skip: 0004-payment (GitHub issue open)
+
+Summary:
+  Would archive: 18 increments
+  Would skip: 5 increments (active sync)
+  Total size: 180 MB
+
+Run without --dry-run to proceed:
+  /specweave:archive --older-than 90
+```
+
+### Example 4: Archive by Pattern
+
+```bash
+/specweave:archive --pattern "auth-|payment-|legacy-"
+```
+
+**Output**:
+```
+📦 Archiving increments matching pattern: auth-|payment-|legacy-
+
+Found matches:
+  ✓ 0015-auth-service
+  ✓ 0016-payment-integration
+  ✓ 0007-legacy-migration
+  ⚠ 0025-auth-enhancements (still active) - SKIPPED
+
+✅ Archived: 3 increments
+⚠️  Skipped: 1 increment (active)
+
+📊 Archive Statistics:
+   Active: 30 increments
+   Archived: 34 increments (+ 3 new)
+```
+
+## Error Handling
+
+### Increment Already Archived
+
+```
+❌ Error: Increment 0031 already exists in archive
+
+Location: .specweave/increments/_archive/0031-external-tool-status-sync/
+
+Options:
+  1. Delete from archive first, then retry
+  2. Restore from archive: /specweave:restore 0031
+  3. Resolve duplicates: /specweave:fix-duplicates
+```
+
+### Active Increment Protection
+
+```
+⚠️  Cannot archive active increments
+
+Skipped:
+  • 0032-duplicate-prevention (status: active)
+  • 0033-current-work (status: in-progress)
+
+Recommendation:
+  1. Close increments first: /specweave:done 0032
+  2. Then archive: /specweave:archive 0032
+```
+
+### External Sync Active
+
+```
+⚠️  Cannot archive increments with active external sync
+
+Skipped:
+  • 0031-external-tool-sync (GitHub issue #45 still open)
+  • 0030-jira-integration (JIRA PROJ-123 In Progress)
+
+Recommendation:
+  1. Close external issues first
+  2. Then retry: /specweave:archive 0031 0030
+
+Or force archive (not recommended):
+  /specweave:archive 0031 --force
+```
+
+## Related Commands
+
+- `/specweave:restore <increment-id>` - Restore increment from archive
+- `/specweave:done <increment-id>` - Close increment (does NOT archive!)
+- `/specweave:archive-features` - Archive features/epics (separate system)
+- `/specweave:status` - View archive statistics
+
+## Important Notes
+
+### ⚠️ Manual Only Policy
+
+**Increments are NEVER auto-archived!** This is a deliberate design decision:
+- ✅ `/specweave:done` closes increments but leaves them visible
+- ✅ You control when increments are archived
+- ✅ Keep ~10-20 recent increments visible for reference
+- ✅ Archive older work when you're ready
+
+### 🔗 Feature Archiving (Automatic)
+
+**Features/epics ARE auto-archived** when all their increments are archived:
+- After archiving increment 0031, run: `/specweave:archive-features`
+- This updates living docs and archives orphaned features
+- Keeps feature docs in sync with increment archives
+
+### 📦 Archive is Local Only
+
+Archives are **NOT** synced to GitHub/JIRA/ADO. They're local file management only.
+
+## Implementation
+
+```typescript
+import { Task } from '@claude/types';
+
+const task = new Task('archive-increments', 'Archive completed increments');
+
+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);
+  const incrementIds = args.filter(arg => !arg.startsWith('--'));
+
+  // Parse options
+  const options = {
+    increments: incrementIds.length > 0 ? incrementIds : undefined,
+    olderThanDays: parseOption(args, '--older-than'),
+    keepLast: parseOption(args, '--keep-last') || 10,
+    archiveCompleted: args.includes('--archive-completed'),
+    preserveActive: !args.includes('--no-preserve-active'),
+    pattern: parseOption(args, '--pattern'),
+    dryRun: args.includes('--dry-run')
+  };
+
+  // Execute archiving
+  const result = await archiver.archive(options);
+
+  // Display results
+  if (options.dryRun) {
+    console.log('\n🔍 DRY RUN - No files will be moved\n');
+  }
+
+  console.log(`✅ Archived: ${result.archived.length} increments`);
+  if (result.skipped.length > 0) {
+    console.log(`⚠️  Skipped: ${result.skipped.length} increments`);
+  }
+  if (result.errors.length > 0) {
+    console.error(`❌ Errors: ${result.errors.length} increments`);
+  }
+
+  // Show statistics
+  const stats = await archiver.getStats();
+  console.log('\n📊 Archive Statistics:');
+  console.log(`   Active: ${stats.active} increments`);
+  console.log(`   Archived: ${stats.archived} increments`);
+  console.log(`   Abandoned: ${stats.abandoned} increments`);
+  console.log(`   Total archive size: ${formatSize(stats.totalSize)}`);
+
+  // Suggest next steps
+  if (result.archived.length > 0 && !options.dryRun) {
+    console.log('\n💡 Next: Run /specweave:archive-features to sync feature docs');
+  }
+});
+
+function parseOption(args: string[], flag: string): number | string | undefined {
+  const index = args.indexOf(flag);
+  if (index !== -1 && index + 1 < args.length) {
+    const value = args[index + 1];
+    return isNaN(Number(value)) ? value : Number(value);
+  }
+  return undefined;
+}
+
+function formatSize(bytes: number): string {
+  const mb = bytes / (1024 * 1024);
+  return mb < 1 ? `${Math.round(bytes / 1024)} KB` : `${Math.round(mb)} MB`;
+}
+
+export default task;
+```
+
+## Configuration
+
+No configuration needed - all options are provided via command-line flags.
+
+Default behavior:
+- Preserves active/paused increments
+- Skips increments with open external issues
+- Warns about uncommitted changes
+- Requires explicit user action (no auto-archiving)
+
+---
+
+**Best Practice**: Archive completed increments periodically (e.g., monthly or quarterly) to keep your workspace clean while preserving all history.
+
+**Recommended Workflow**:
+```bash
+# 1. Check what would be archived
+/specweave:archive --keep-last 10 --dry-run
+
+# 2. Archive old increments
+/specweave:archive --keep-last 10
+
+# 3. Archive related features
+/specweave:archive-features
+
+# 4. Check results
+/specweave:status
+```

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

@@ -0,0 +1,211 @@
+---
+name: specweave:backlog
+description: Move an increment to backlog (planned but not ready to start)
+usage: /specweave:backlog <increment-id> --reason="<reason>"
+---
+
+# Backlog Increment Command
+
+**Usage**: `/specweave:backlog <increment-id> --reason="<reason>"`
+
+---
+
+## Purpose
+
+Move an increment to backlog when:
+- **Planned** but not ready to start yet
+- **Low priority** compared to other work
+- **Waiting** for decisions or approvals before starting
+- **Multiple ideas** you want to plan without violating WIP limits
+
+**Key Difference**:
+- **Backlog** = Never started, planned for future (does NOT count towards WIP)
+- **Paused** = Started but blocked (does NOT count towards WIP)
+
+---
+
+## Behavior
+
+1. **Validates** increment exists and is "active"
+2. **Prompts** for reason if not provided via --reason flag
+3. **Updates** metadata.json:
+   - `status`: "active" → "backlog"
+   - `backlogReason`: User-provided reason
+   - `backlogAt`: Current timestamp
+4. **Displays** confirmation message
+5. **Suggests** next actions (`/specweave:resume` to start work)
+
+---
+
+## Examples
+
+### Move to backlog with reason
+```bash
+/specweave:backlog 0032 --reason="Low priority, focus on 0031 first"
+
+✅ Increment 0032 moved to backlog
+📝 Reason: Low priority, focus on 0031 first
+🗂️  No longer counts toward WIP limits
+💡 Start work with: /specweave:resume 0032
+```
+
+### Move to backlog without reason (prompts)
+```bash
+/specweave:backlog 0032
+
+❓ Why are you moving this to backlog?
+   1. Low priority
+   2. Waiting for decisions/approvals
+   3. Multiple planned ideas
+   4. Other (type reason)
+
+> 1
+
+✅ Increment 0032 moved to backlog
+📝 Reason: Low priority
+💡 Start work with: /specweave:resume 0032
+```
+
+---
+
+## Edge Cases
+
+### Already in Backlog
+```bash
+/specweave:backlog 0032 --reason="Different reason"
+
+⚠️  Increment 0032 is already in backlog
+   Previous reason: Low priority
+   New reason: Different reason
+
+Update reason? [Y/n]: y
+
+✅ Reason updated
+📝 New reason: Different reason
+```
+
+### Cannot Backlog Completed
+```bash
+/specweave:backlog 0005
+
+❌ Cannot move increment 0005 to backlog
+   Status: completed
+   Completed increments cannot be moved to backlog
+```
+
+### Cannot Backlog Paused
+```bash
+/specweave:backlog 0008
+
+❌ Cannot move increment 0008 to backlog
+   Status: paused
+   Paused work should be resumed or abandoned, not moved to backlog
+   Resume it: /specweave:resume 0008
+```
+
+### Increment Not Found
+```bash
+/specweave:backlog 9999
+
+❌ Increment not found: 9999
+💡 Check available increments: /specweave:status
+```
+
+---
+
+## Implementation
+
+This command uses the MetadataManager to update increment status:
+
+```typescript
+import { MetadataManager, IncrementStatus } from '../src/core/increment/metadata-manager';
+
+// Read current metadata
+const metadata = MetadataManager.read(incrementId);
+
+// Validate can move to backlog
+if (metadata.status !== IncrementStatus.ACTIVE) {
+  throw new Error(`Cannot move increment with status: ${metadata.status}`);
+}
+
+// Update status
+MetadataManager.updateStatus(incrementId, IncrementStatus.BACKLOG, reason);
+```
+
+---
+
+## Status Flow
+
+```
+active ──backlog──> backlog
+   │
+   └──resume──> active
+```
+
+---
+
+## Related Commands
+
+- `/specweave:resume <id>` - Move from backlog to active (start work)
+- `/specweave:pause <id>` - Pause active work (different from backlog)
+- `/specweave:status` - Show all increment statuses including backlog
+- `/specweave:abandon <id>` - Abandon increment (permanent)
+
+---
+
+## Best Practices
+
+✅ **Use backlog for planning** - Plan multiple increments without violating WIP
+
+✅ **Prioritize backlog regularly** - Review and reorder based on value
+
+✅ **Clear reasons** - Helps with prioritization decisions
+
+✅ **Start when ready** - Use `/specweave:resume` to move from backlog to active
+
+❌ **Don't confuse with paused** - Backlog = never started, Paused = started but blocked
+
+❌ **Don't let backlog grow unbounded** - Review and abandon obsolete items
+
+---
+
+## Backlog vs Paused
+
+| Aspect | Backlog | Paused |
+|--------|---------|--------|
+| **Definition** | Planned but not started | Started but blocked |
+| **WIP Count** | NO | NO |
+| **Use Case** | Low priority, future work | Blocked, deprioritized |
+| **Resume** | Start from beginning | Continue where left off |
+
+---
+
+## Warning: Large Backlog
+
+If your backlog grows too large (10+ increments), `/specweave:status` will warn:
+
+```bash
+/specweave:status
+
+🗂️  Backlog (12):
+  📦 0032-feature-a [feature] - Low priority
+  📦 0033-feature-b [feature] - Waiting for decisions
+  📦 0034-feature-c [feature] - Multiple planned ideas
+  ... (9 more)
+
+⚠️  Large backlog! Consider:
+   - Abandoning obsolete items
+   - Consolidating similar features
+   - Reviewing priorities
+
+💡 Actions:
+   /specweave:resume <id>  # Start work on highest priority
+   /specweave:abandon <id> # Remove obsolete items
+```
+
+---
+
+**Command**: `/specweave:backlog`
+**Plugin**: specweave (core)
+**Version**: v0.19.0+
+**Part of**: Backlog Support Feature