specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/jira-import-boards.md

@@ -1,330 +0,0 @@
----
-description: Import JIRA boards from a project and map them to SpecWeave projects. Creates 2-level directory structure with board-based organization.
----
-
-# Import JIRA Boards Command
-
-You are a JIRA integration expert. Help the user import boards from a JIRA project and map them to SpecWeave projects.
-
-## Command Usage
-
-```bash
-sw-jira:import-boards                      # Interactive mode (prompts for project)
-sw-jira:import-boards --project CORE       # Specific JIRA project
-sw-jira:import-boards --dry-run            # Preview without creating directories
-```
-
-## Your Task
-
-When the user runs this command:
-
-### Step 1: Validate Prerequisites
-
-1. **Check JIRA credentials** exist in `.env`:
-   - `JIRA_API_TOKEN`
-   - `JIRA_EMAIL`
-   - `JIRA_DOMAIN`
-
-2. **Check config.json** for existing board mapping:
-   - If `sync.profiles.*.config.boardMapping` exists, warn user
-
-### Step 2: Get Project Key
-
-**If `--project` flag provided:**
-- Use the provided project key
-
-**If no flag (interactive mode):**
-```
-📋 JIRA Board Import
-
-Enter the JIRA project key to import boards from:
-> CORE
-
-Fetching boards from project CORE...
-```
-
-### Step 3: Fetch and Display Boards
-
-```typescript
-import { JiraClient } from '../../../src/integrations/jira/jira-client';
-import { fetchBoardsForProject } from '../lib/jira-board-resolver';
-
-const client = new JiraClient({
-  domain: process.env.JIRA_DOMAIN,
-  email: process.env.JIRA_EMAIL,
-  apiToken: process.env.JIRA_API_TOKEN,
-  instanceType: 'cloud'
-});
-
-const boards = await fetchBoardsForProject(client, 'CORE');
-```
-
-**Display boards:**
-```
-Found 5 boards in project CORE:
-
-  1. ☑ Frontend Board (Scrum, 23 active items)
-  2. ☑ Backend Board (Kanban, 45 active items)
-  3. ☑ Mobile Board (Scrum, 12 active items)
-  4. ☐ Platform Board (Kanban, 3 active items)
-  5. ☐ Archive Board (Simple, 0 items) [deselected - archive]
-
-Select boards to import (Space to toggle, Enter to confirm)
-```
-
-### Step 4: Map Boards to SpecWeave Projects
-
-For each selected board, prompt for SpecWeave project ID:
-
-```
-🏷️  Mapping boards to SpecWeave projects:
-
-Board "Frontend Board" → SpecWeave project ID: [fe]
-  → Keywords for auto-classification (optional): frontend, ui, react, css
-
-Board "Backend Board" → SpecWeave project ID: [be]
-  → Keywords for auto-classification (optional): api, server, database
-
-Board "Mobile Board" → SpecWeave project ID: [mobile]
-  → Keywords for auto-classification (optional): ios, android, react-native
-```
-
-**Project ID validation:**
-- Must be lowercase, alphanumeric with hyphens
-- Must not collide with existing project IDs
-- If collision detected, suggest prefixed version: `core-fe` instead of `fe`
-
-### Step 5: Create Directory Structure
-
-Create 2-level directory structure:
-
-```
-.specweave/docs/internal/specs/
-└── JIRA-CORE/                  ← Level 1: JIRA project
-    ├── fe/                     ← Level 2: SpecWeave project
-    │   └── .gitkeep
-    ├── be/
-    │   └── .gitkeep
-    └── mobile/
-        └── .gitkeep
-```
-
-### Step 6: Update config.json
-
-Add board mapping to config:
-
-```json
-{
-  "sync": {
-    "profiles": {
-      "jira-default": {
-        "provider": "jira",
-        "config": {
-          "domain": "example.atlassian.net",
-          "boardMapping": {
-            "projectKey": "CORE",
-            "boards": [
-              {
-                "boardId": 123,
-                "boardName": "Frontend Board",
-                "specweaveProject": "fe",
-                "boardType": "scrum",
-                "keywords": ["frontend", "ui", "react", "css"]
-              },
-              {
-                "boardId": 456,
-                "boardName": "Backend Board",
-                "specweaveProject": "be",
-                "boardType": "kanban",
-                "keywords": ["api", "server", "database"]
-              },
-              {
-                "boardId": 789,
-                "boardName": "Mobile Board",
-                "specweaveProject": "mobile",
-                "boardType": "scrum",
-                "keywords": ["ios", "android", "react-native"]
-              }
-            ]
-          }
-        }
-      }
-    }
-  },
-  "multiProject": {
-    "enabled": true,
-    "activeProject": "fe",
-    "projects": {
-      "fe": {
-        "name": "Frontend",
-        "externalTools": {
-          "jira": {
-            "boardId": 123,
-            "projectKey": "CORE"
-          }
-        }
-      },
-      "be": {
-        "name": "Backend",
-        "externalTools": {
-          "jira": {
-            "boardId": 456,
-            "projectKey": "CORE"
-          }
-        }
-      },
-      "mobile": {
-        "name": "Mobile",
-        "externalTools": {
-          "jira": {
-            "boardId": 789,
-            "projectKey": "CORE"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### Step 7: Display Summary
-
-```
-✅ JIRA Boards Import Complete!
-
-📋 JIRA Project: CORE
-📁 Created: .specweave/docs/internal/specs/JIRA-CORE/
-
-Boards imported:
-  ✓ Frontend Board (scrum) → fe
-    Keywords: frontend, ui, react, css
-  ✓ Backend Board (kanban) → be
-    Keywords: api, server, database
-  ✓ Mobile Board (scrum) → mobile
-    Keywords: ios, android, react-native
-
-💡 Next steps:
-  1. Use sw:switch-project fe to switch active project
-  2. Create increment: sw:increment "feature name"
-  3. User stories will auto-sync to the correct board based on keywords
-
-📖 Documentation: .specweave/docs/internal/architecture/adr/0143-jira-ado-multi-level-project-mapping.md
-```
-
-## Examples
-
-### Example 1: Interactive Import
-```
-User: sw-jira:import-boards
-
-You:
-📋 JIRA Board Import
-
-Enter the JIRA project key: CORE
-Fetching boards...
-
-Found 3 boards:
-  ☑ Frontend Board (scrum)
-  ☑ Backend Board (kanban)
-  ☐ Archive (simple) [deselected]
-
-Mapping to SpecWeave projects:
-  Frontend Board → fe
-  Backend Board → be
-
-✅ Import complete! 2 boards mapped.
-```
-
-### Example 2: Dry Run
-```
-User: sw-jira:import-boards --project CORE --dry-run
-
-You:
-📋 JIRA Board Import (DRY RUN)
-
-Would import from project: CORE
-
-Would create:
-  .specweave/docs/internal/specs/JIRA-CORE/
-  .specweave/docs/internal/specs/JIRA-CORE/fe/
-  .specweave/docs/internal/specs/JIRA-CORE/be/
-
-Would update config.json with board mapping.
-
-No changes made (dry run).
-```
-
-### Example 3: Already Configured
-```
-User: sw-jira:import-boards
-
-You:
-⚠️  Board mapping already exists for project CORE
-
-Current mappings:
-  Frontend Board → fe
-  Backend Board → be
-
-Do you want to:
-  1. Add more boards
-  2. Replace existing mapping
-  3. Cancel
-
-> 1
-
-Fetching additional boards...
-  ☐ Frontend Board (already mapped)
-  ☐ Backend Board (already mapped)
-  ☑ Mobile Board (new)
-  ☐ Archive (deselected)
-
-Added Mobile Board → mobile
-
-✅ Updated! Now 3 boards mapped.
-```
-
-## Error Handling
-
-**Missing credentials:**
-```
-❌ JIRA credentials not found
-
-Please add to .env:
-  JIRA_API_TOKEN=your_token
-  JIRA_EMAIL=your_email@example.com
-  JIRA_DOMAIN=your-company.atlassian.net
-
-Or run: specweave init . (to configure JIRA)
-```
-
-**Project not found:**
-```
-❌ JIRA project "INVALID" not found
-
-Available projects you have access to:
-  - CORE (Core Development)
-  - INFRA (Infrastructure)
-  - MOBILE (Mobile Team)
-
-Tip: Use sw-jira:import-boards --project CORE
-```
-
-**No boards found:**
-```
-⚠️  No boards found in project CORE
-
-This could mean:
-  1. The project uses classic projects (no boards)
-  2. You don't have access to boards in this project
-
-Suggestions:
-  - Use sw-jira:import-projects for project-based sync
-  - Ask your JIRA admin about board access
-```
-
-## Related Commands
-
-- `sw-jira:import-projects` - Import multiple JIRA projects (not boards)
-- `sw-jira:sync` - Sync increments with JIRA
-- `sw:switch-project` - Switch active SpecWeave project
-- `sw:init-multiproject` - Initialize multi-project mode

package/plugins/specweave/commands/jira-import-projects-full.md

@@ -1,297 +0,0 @@
----
-description: Import additional JIRA projects post-init with filtering, resume support, and dry-run preview
----
-
-# Import JIRA Projects Command
-
-You are a JIRA project import expert. Help users add additional JIRA projects to their SpecWeave workspace after initial setup.
-
-## Purpose
-
-This command allows users to import additional JIRA projects **after** initial SpecWeave setup (`specweave init`), with advanced filtering, resume capability, and dry-run preview.
-
-**Use Cases**:
-- Adding new JIRA projects to existing workspace
-- Importing archived/paused projects later
-- Selective import with filters (active only, specific types, custom JQL)
-
-## Command Syntax
-
-```bash
-# Basic import (interactive)
-sw-jira:import-projects
-
-# With filters
-sw-jira:import-projects --filter active
-sw-jira:import-projects --type agile --lead "john.doe@company.com"
-sw-jira:import-projects --jql "project IN (BACKEND, FRONTEND) AND status != Archived"
-
-# Dry-run (preview)
-sw-jira:import-projects --dry-run
-
-# Resume interrupted import
-sw-jira:import-projects --resume
-
-# Combined
-sw-jira:import-projects --filter active --dry-run
-```
-
-## Your Task
-
-When the user runs this command:
-
-### Step 1: Validate Prerequisites
-```typescript
-import { readEnvFile, parseEnvFile } from '../../../src/utils/env-file.js';
-
-// 1. Check if Jira credentials exist
-const envContent = readEnvFile(process.cwd());
-const parsed = parseEnvFile(envContent);
-
-if (!parsed.JIRA_API_TOKEN || !parsed.JIRA_EMAIL || !parsed.JIRA_DOMAIN) {
-  console.log('❌ Missing Jira credentials. Run `specweave init` first.');
-  return;
-}
-
-// 2. Get existing projects
-const existingProjects = parsed.JIRA_PROJECTS?.split(',') || [];
-console.log(`\n📋 Current projects: ${existingProjects.join(', ') || 'None'}\n`);
-```
-
-### Step 2: Fetch Available Projects
-```typescript
-import { getProjectCount } from '../../../src/cli/helpers/project-count-fetcher.js';
-import { AsyncProjectLoader } from '../../../src/cli/helpers/async-project-loader.js';
-
-// Count check (< 1 second)
-const countResult = await getProjectCount({
-  provider: 'jira',
-  credentials: {
-    domain: parsed.JIRA_DOMAIN,
-    email: parsed.JIRA_EMAIL,
-    token: parsed.JIRA_API_TOKEN,
-    instanceType: 'cloud'
-  }
-});
-
-console.log(`✓ Found ${countResult.accessible} accessible projects`);
-
-// Fetch all projects (with smart pagination)
-const loader = new AsyncProjectLoader(
-  {
-    domain: parsed.JIRA_DOMAIN,
-    email: parsed.JIRA_EMAIL,
-    token: parsed.JIRA_API_TOKEN,
-    instanceType: 'cloud'
-  },
-  'jira',
-  {
-    batchSize: 50,
-    updateFrequency: 5,
-    showEta: true
-  }
-);
-
-const result = await loader.fetchAllProjects(countResult.accessible);
-let allProjects = result.projects;
-```
-
-### Step 3: Apply Filters (if specified)
-```typescript
-import { FilterProcessor } from '../../../src/integrations/jira/filter-processor.js';
-
-const options = {
-  filter: args.filter,       // 'active' | 'all'
-  type: args.type,           // 'agile' | 'software' | 'business'
-  lead: args.lead,           // Email address
-  jql: args.jql              // Custom JQL
-};
-
-const filterProcessor = new FilterProcessor({ domain: parsed.JIRA_DOMAIN, token: parsed.JIRA_API_TOKEN });
-const filteredProjects = await filterProcessor.applyFilters(allProjects, options);
-
-console.log(`\n🔍 Filters applied:`);
-if (options.filter === 'active') console.log(`   • Active projects only`);
-if (options.type) console.log(`   • Type: ${options.type}`);
-if (options.lead) console.log(`   • Lead: ${options.lead}`);
-if (options.jql) console.log(`   • JQL: ${options.jql}`);
-console.log(`\n📊 Results: ${filteredProjects.length} projects (down from ${allProjects.length})\n`);
-```
-
-### Step 4: Exclude Existing Projects
-```typescript
-const newProjects = filteredProjects.filter(p => !existingProjects.includes(p.key));
-
-if (newProjects.length === 0) {
-  console.log('✅ No new projects to import. All filtered projects are already configured.');
-  return;
-}
-
-console.log(`📥 ${newProjects.length} new project(s) available for import:\n`);
-newProjects.forEach(p => {
-  console.log(`   ✨ ${p.key} - ${p.name} (${p.projectTypeKey}, lead: ${p.lead?.displayName || 'N/A'})`);
-});
-```
-
-### Step 5: Dry-Run or Execute
-```typescript
-if (args.dryRun) {
-  console.log('\n🔎 DRY RUN: No changes will be made.\n');
-  console.log('The following projects would be imported:');
-  newProjects.forEach(p => {
-    const status = p.archived ? '⏭️  (archived - skipped)' : '✨';
-    console.log(`   ${status} ${p.key} - ${p.name}`);
-  });
-  console.log(`\nTotal: ${newProjects.filter(p => !p.archived).length} projects would be imported\n`);
-  return;
-}
-
-// Confirm import
-const { confirmed } = await inquirer.prompt([{
-  type: 'confirm',
-  name: 'confirmed',
-  message: `Import ${newProjects.length} project(s)?`,
-  default: true
-}]);
-
-if (!confirmed) {
-  console.log('⏭️  Import cancelled.');
-  return;
-}
-```
-
-### Step 6: Merge with Existing
-```typescript
-import { updateEnvFile, mergeProjectList } from '../../../src/utils/env-manager.js';
-
-const newKeys = newProjects.map(p => p.key);
-const mergedProjects = mergeProjectList(existingProjects, newKeys);
-
-// Update .env file (atomic write)
-await updateEnvFile('JIRA_PROJECTS', mergedProjects.join(','));
-
-console.log('\n✅ Projects imported successfully!\n');
-console.log(`Updated: ${existingProjects.length} → ${mergedProjects.length} projects`);
-console.log(`\nCurrent projects:\n   ${mergedProjects.join(', ')}\n`);
-```
-
-### Step 7: Resume Support
-```typescript
-if (args.resume) {
-  const { CacheManager } = await import('../../../src/core/cache/cache-manager.js');
-  const cacheManager = new CacheManager(process.cwd());
-
-  const importState = await cacheManager.get('jira-import-state');
-
-  if (!importState) {
-    console.log('⚠️  No import state found. Use without --resume to start fresh.');
-    return;
-  }
-
-  console.log(`\n📂 Resuming from: ${importState.lastProject} (${importState.completed}/${importState.total})`);
-
-  // Skip already-imported projects
-  const remainingProjects = allProjects.filter(p => !importState.succeeded.includes(p.key));
-
-  // Continue import with remaining projects
-  // (use same logic as Step 6)
-}
-```
-
-## Examples
-
-### Example 1: Basic Import
-**User**: `sw-jira:import-projects`
-
-**Output**:
-```
-📋 Current projects: BACKEND, FRONTEND
-
-✓ Found 127 accessible projects
-📥 5 new project(s) available for import:
-
-   ✨ MOBILE - Mobile App (agile, lead: John Doe)
-   ✨ INFRA - Infrastructure (software, lead: Jane Smith)
-   ✨ QA - Quality Assurance (business, lead: Bob Wilson)
-   ✨ DOCS - Documentation (business, lead: Alice Cooper)
-   ✨ LEGACY - Legacy System (archived - skipped)
-
-Import 5 project(s)? (Y/n)
-
-✅ Projects imported successfully!
-
-Updated: 2 → 6 projects
-
-Current projects:
-   BACKEND, FRONTEND, MOBILE, INFRA, QA, DOCS
-```
-
-### Example 2: Filter Active Only
-**User**: `sw-jira:import-projects --filter active`
-
-**Output**:
-```
-🔍 Filters applied:
-   • Active projects only
-
-📊 Results: 120 projects (down from 127)
-
-📥 4 new project(s) available for import:
-   (LEGACY project excluded because it's archived)
-```
-
-### Example 3: Dry-Run
-**User**: `sw-jira:import-projects --dry-run`
-
-**Output**:
-```
-🔎 DRY RUN: No changes will be made.
-
-The following projects would be imported:
-   ✨ MOBILE - Mobile App
-   ✨ INFRA - Infrastructure
-   ✨ QA - Quality Assurance
-   ⏭️  LEGACY - Legacy System (archived - skipped)
-
-Total: 3 projects would be imported
-```
-
-### Example 4: Custom JQL Filter
-**User**: `sw-jira:import-projects --jql "project IN (MOBILE, INFRA) AND status != Archived"`
-
-**Output**:
-```
-🔍 Filters applied:
-   • JQL: project IN (MOBILE, INFRA) AND status != Archived
-
-📊 Results: 2 projects (down from 127)
-
-📥 2 new project(s) available for import:
-   ✨ MOBILE - Mobile App
-   ✨ INFRA - Infrastructure
-```
-
-## Important Notes
-
-- **Merge Logic**: No duplicates. Existing projects are preserved.
-- **Atomic Updates**: Uses temp file + rename to prevent corruption.
-- **Progress Tracking**: Shows progress bar for large imports (> 50 projects).
-- **Resume Support**: Interrupted imports can be resumed with `--resume`.
-- **Backup**: Creates `.env.backup` before modifying `.env`.
-
-## Related Commands
-
-- `sw:init` - Initial SpecWeave setup
-- `sw-jira:sync` - Sync increments with Jira epics
-- `sw-jira:refresh-cache` - Clear cached project data
-
-## Error Handling
-
-- **Missing Credentials**: Prompt user to run `specweave init` first
-- **API Errors**: Show clear error message with suggestion
-- **No New Projects**: Inform user all projects already imported
-- **Permission Errors**: Check `.env` file permissions
-
----
-
-**Post-Init Flexibility**: This command provides flexibility to add projects after initial setup, supporting evolving team structures and project lifecycles.

package/plugins/specweave/commands/jira-import-projects.md

@@ -1,96 +0,0 @@
----
-description: Import additional JIRA projects post-init with smart filtering, resume, and dry-run support
----
-
-# JIRA Project Import Command
-
-Import additional JIRA projects after initial setup with advanced filtering and merge capabilities.
-
-## Usage
-
-```bash
-# Import all active projects
-sw-jira:import-projects --filter active
-
-# Import with preset filter
-sw-jira:import-projects --preset production
-
-# Import with custom JQL
-sw-jira:import-projects --jql "project NOT IN (TEST, SANDBOX)"
-
-# Dry-run preview (no changes)
-sw-jira:import-projects --dry-run
-
-# Resume interrupted import
-sw-jira:import-projects --resume
-```
-
-## Options
-
-- `--filter <type>` - Filter by status (active, archived, all)
-- `--type <types>` - Filter by project type (software, business, service_desk)
-- `--lead <email>` - Filter by project lead
-- `--jql <query>` - Custom JQL filter
-- `--preset <name>` - Use saved filter preset
-- `--dry-run` - Preview without making changes
-- `--resume` - Resume interrupted import
-- `--no-progress` - Disable progress tracking
-
-## Examples
-
-### Import Active Projects Only
-
-```bash
-sw-jira:import-projects --filter active
-```
-
-Filters out archived projects, shows preview, prompts for confirmation, merges with existing.
-
-### Import with Production Preset
-
-```bash
-sw-jira:import-projects --preset production
-```
-
-Uses the "production" preset filter (active + software + excludes TEST/SANDBOX).
-
-### Custom JQL Filter
-
-```bash
-sw-jira:import-projects --jql "lead = currentUser() AND status != Archived"
-```
-
-Imports projects where you are the lead and not archived.
-
-### Dry-Run Preview
-
-```bash
-sw-jira:import-projects --filter active --dry-run
-```
-
-Shows which projects would be imported without making any changes.
-
-## Features
-
-- **Smart Filtering**: Filter by status, type, lead, or custom JQL
-- **Merge with Existing**: Automatically merges with existing projects (no duplicates)
-- **Progress Tracking**: Real-time progress with ETA and cancelation support
-- **Resume Support**: Resume interrupted imports with `--resume`
-- **Dry-Run Mode**: Preview changes before applying
-- **Filter Presets**: Use saved filter combinations
-
-## Implementation
-
-This command:
-
-1. Reads existing projects from `.env` (JIRA_PROJECTS)
-2. Fetches available projects from JIRA API
-3. Applies selected filters using FilterProcessor
-4. Shows preview with project count and reduction percentage
-5. Prompts for confirmation
-6. Batch imports with AsyncProjectLoader (50-project limit)
-7. Shows progress with ETA
-8. Merges with existing projects (no duplicates)
-9. Updates `.env` file atomically
-
-Handles Ctrl+C gracefully with import state saving for resume.