@qazuor/claude-code-config 0.1.0

package/templates/commands/planning/cleanup-issues.md

@@ -0,0 +1,248 @@
+---
+name: cleanup-issues
+description: Clean up stale, closed, or orphaned issues from workflow automation
+type: planning
+category: planning
+config_required:
+  issue_tracker: "Issue tracking system name"
+  issue_tracker_token_env: "Auth token environment variable"
+  issue_tracker_owner_env: "Owner/org environment variable"
+  issue_tracker_repo_env: "Repository environment variable"
+  tracking_file: "Issue tracking data file"
+  closed_days_default: "Default days for closed issue cleanup (e.g., 30)"
+  stale_days_default: "Default days for stale issue detection (e.g., 90)"
+---
+
+# Cleanup Issues
+
+Clean up stale, closed, or orphaned issues created by workflow automation.
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `issue_tracker` | Issue tracking system | `{{ISSUE_TRACKER}}` |
+| `issue_tracker_token_env` | Auth token variable | `{{ISSUE_TRACKER_TOKEN}}` |
+| `issue_tracker_owner_env` | Owner variable | `{{ISSUE_TRACKER_OWNER}}` |
+| `issue_tracker_repo_env` | Repository variable | `{{ISSUE_TRACKER_REPO}}` |
+| `tracking_file` | Tracking data file | `{{TRACKING_FILE}}` |
+| `closed_days_default` | Days for closed cleanup | `{{CLOSED_DAYS}}` |
+| `stale_days_default` | Days for stale detection | `{{STALE_DAYS}}` |
+
+## Usage
+
+```bash
+/cleanup-issues [--closed-days N] [--stale-days N]
+```
+
+## When to Use
+
+- After completing major feature
+- To remove stale/obsolete issues
+- When cleaning up cancelled features
+- During project maintenance
+- Before milestones or releases
+
+## Process
+
+### Step 1: Identify Scope
+
+Cleanup options:
+
+- **Closed issues:** Closed > N days ago
+- **Orphaned issues:** No planning session/TODO
+- **Stale issues:** No activity for N days
+- **Specific session:** Single planning session
+- **All issues:** Full cleanup (requires confirmation)
+
+### Step 2: Get Configuration
+
+Required:
+
+- `{{ISSUE_TRACKER_TOKEN}}`
+- `{{ISSUE_TRACKER_OWNER}}`
+- `{{ISSUE_TRACKER_REPO}}`
+
+### Step 3: Scan Candidates
+
+Scan for cleanup candidates:
+
+- Closed issues older than threshold
+- Stale issues with no activity
+- Orphaned issues (no source)
+
+### Step 4: Preview Cleanup
+
+```text
+🔍 Cleanup Preview
+
+Issues to clean:
+   • {n} closed (>{n} days ago)
+   • {n} stale (no activity >{n} days)
+   • {n} orphaned (no source)
+
+Details:
+
+Closed Issues:
+   • #{n}: Task name (closed {n} days ago)
+
+Stale Issues:
+   • #{n}: TODO in old file (no updates {n} days)
+
+Orphaned Issues:
+   • #{n}: Task with deleted session
+   • #{n}: TODO from removed code
+
+⚠️ WARNING: Permanently removes issue references from tracking.
+Issues remain in {{ISSUE_TRACKER}} (can be manually deleted).
+
+Continue? (yes/no)
+```
+
+### Step 5: Execute Cleanup
+
+If confirmed:
+
+- Remove references from tracking
+- Archive issue data
+- Update tracking file
+
+### Step 6: Report Results
+
+```text
+✅ Cleanup completed!
+
+Statistics:
+   • {n} references removed
+   • {n} issues archived
+   • {n} skipped
+   • {n} failed
+
+Updated Files:
+   • {{TRACKING_FILE}} (updated)
+   • {{TRACKING_FILE}}.archive (archived)
+
+Next Steps:
+   1. Review archived references
+   2. Manually delete issues if needed
+   3. Commit tracking files
+```
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| Missing config | Set environment variables |
+| No issues found | Issue tracker is clean |
+| Confirmation required | Type 'yes' to confirm |
+| API errors | Check token and permissions |
+
+## Advanced Options
+
+### Specific Session
+
+```typescript
+{ sessionPath: '{{PLANNING_PATH}}/{session}' }
+```
+
+### Archive Instead of Delete
+
+```typescript
+{ archiveIssues: true }
+```
+
+### Custom Thresholds
+
+```typescript
+{
+  closedDays: 7,
+  staleDays: 60
+}
+```
+
+### Delete from Tracker
+
+```typescript
+{
+  deleteFromTracker: true,
+  requireConfirmation: true
+}
+```
+
+## Cleanup Strategies
+
+### Conservative
+
+For important history:
+
+```typescript
+{
+  closedDays: 180,    // 6 months
+  staleDays: 365,     // 1 year
+  includeOrphaned: false,
+  archiveIssues: true
+}
+```
+
+### Aggressive
+
+For active projects:
+
+```typescript
+{
+  closedDays: 14,     // 2 weeks
+  staleDays: 30,      // 1 month
+  includeOrphaned: true,
+  deleteFromTracker: true
+}
+```
+
+### Orphan-Only
+
+```typescript
+{ orphanedOnly: true }
+```
+
+## What Gets Cleaned
+
+### Closed Issues
+
+Must meet ALL:
+
+- Issue closed
+- Closed > N days ago
+- No recent activity
+- Not pinned/locked
+
+### Stale Issues
+
+Must meet ALL:
+
+- Issue open
+- No activity > N days
+- Not labeled 'keep' or 'important'
+- Not in active milestone
+
+### Orphaned Issues
+
+Must meet ANY:
+
+- Planning session deleted
+- TODO comment removed
+- Tracking reference corrupted
+- Source file deleted
+
+## Important Notes
+
+- **Dry run first:** Always preview before cleanup
+- **Archive by default:** References archived, not deleted
+- **Issues remain:** Tracker issues not deleted unless specified
+- **Recoverable:** Archives can be restored
+- **Safe:** Won't delete issues with recent activity
+- **Backup:** Consider backing up tracking file first
+
+## Related Commands
+
+- `/sync-planning` - Sync planning to tracker
+- `/sync-todos` - Sync code TODOs
+- `/check-completed` - Auto-close completed

package/templates/commands/planning/planning-cleanup.md

@@ -0,0 +1,251 @@
+---
+name: planning-cleanup
+description: Archive completed planning sessions to keep workspace organized
+type: planning
+category: planning
+config_required:
+  planning_path: "Base path for planning sessions"
+  archive_path: "Path for archived sessions (organized by year/month)"
+  registry_file: "Code registry file path"
+---
+
+# Planning Cleanup Command
+
+Archive completed planning sessions to keep workspace organized.
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `planning_path` | Active planning sessions directory | `{{PLANNING_PATH}}` |
+| `archive_path` | Archive directory | `{{ARCHIVE_PATH}}` |
+| `registry_file` | Code registry file | `{{REGISTRY_FILE}}` |
+
+## Usage
+
+### Interactive Mode (Default)
+
+```bash
+/planning-cleanup
+```
+
+**Flow:** Scan → Show list → User selects → Confirm → Archive → Report
+
+### Auto Mode
+
+```bash
+/planning-cleanup --auto
+```
+
+**Flow:** Scan → Archive ALL → Report
+
+### Dry-Run Mode
+
+```bash
+/planning-cleanup --dry-run
+```
+
+**Flow:** Show what WOULD be archived → No changes
+
+## Process
+
+### 1. Detection
+
+**Completed session criteria:**
+
+- Status in {{REGISTRY_FILE}} is "completed"
+- OR all tasks in TODOs.md marked completed
+- OR checkpoint shows final phase completed
+
+### 2. Selection (Interactive)
+
+```text
+Found 2 completed planning sessions:
+
+[ ] P-001-feature-name (completed: 2024-10-28)
+    - 15 tasks completed
+    - Duration: 45 hours
+
+Select sessions to archive (space to toggle, enter to confirm):
+```
+
+### 3. Archive
+
+For each session:
+
+1. Create archive directory: `{{ARCHIVE_PATH}}/{year}/{month}/{session}/`
+2. Move all files
+3. Generate COMPLETION-REPORT.md
+4. Update {{REGISTRY_FILE}}
+
+### 4. Report
+
+```text
+✅ Archive Complete
+
+Archived Sessions: {n}
+- {session-1} → archived/{year}/{month}/
+- {session-2} → archived/{year}/{month}/
+
+Updated:
+- {{REGISTRY_FILE}} ({n} sessions marked archived)
+- Active sessions: {n} remaining
+
+Location: {{ARCHIVE_PATH}}/{year}/{month}/
+```
+
+## File Structure
+
+**Before:**
+
+```text
+{{PLANNING_PATH}}/
+├── {{REGISTRY_FILE}}
+├── P-001-feature-name/
+├── P-002-other-feature/
+└── P-003-active-feature/
+```
+
+**After:**
+
+```text
+{{PLANNING_PATH}}/
+├── {{REGISTRY_FILE}} (updated)
+├── P-003-active-feature/
+└── archived/
+    └── {year}/
+        └── {month}/
+            ├── P-001-feature-name/
+            │   ├── PDR.md
+            │   ├── TODOs.md
+            │   └── COMPLETION-REPORT.md (new)
+            └── P-002-other-feature/
+                └── ...
+```
+
+## Completion Report
+
+Generated for each archived session:
+
+```markdown
+# Completion Report: {Code} - {Title}
+
+**Completed:** {date}
+**Duration:** {actual}h (estimated: {estimated}h)
+**Tasks:** {completed}/{total} completed
+**Coverage:** {coverage}%
+
+## Summary
+Brief overview of deliverables.
+
+## Deliverables
+- ✅ Deliverable 1
+- ✅ Deliverable 2
+
+## Metrics
+- Total commits: {n}
+- Files changed: {n}
+- Test coverage: {n}%
+
+## Lessons Learned
+### What Went Well
+- Point 1
+
+### What Could Be Improved
+- Point 1
+```
+
+## Safety
+
+**Protections:**
+
+- Cannot archive active/in-progress sessions
+- Cannot archive with uncommitted changes
+- Cannot overwrite existing archives
+- All operations logged
+- Can be undone manually (files moved, not deleted)
+
+## Undo Archive
+
+Manual recovery:
+
+```bash
+mv {{ARCHIVE_PATH}}/{year}/{month}/{session} {{PLANNING_PATH}}/
+
+# Update registry: change status back to "completed"
+```
+
+## Execution Modes
+
+| Mode | Trigger | Interaction | Best For |
+|------|---------|-------------|----------|
+| Interactive | `/planning-cleanup` | User selects | Selective cleanup |
+| Auto | Script/command | None | Quick cleanup |
+| CI/CD | Scheduled action | None | Maintenance-free |
+
+## When to Run
+
+- After completing Phase 4 (Finalization)
+- Before starting new planning sessions
+- Monthly manual cleanup (interactive)
+- Weekly automatic cleanup (CI/CD)
+
+## Examples
+
+### Interactive
+
+```bash
+/planning-cleanup
+
+Found 1 completed session:
+[x] P-001-feature-name (completed: 2024-10-28)
+
+Archive? (y/n): y
+
+✅ Archived P-001 → archived/2024/10/
+```
+
+### Auto
+
+```bash
+/planning-cleanup --auto
+
+Found 2 completed sessions:
+- P-001-feature-name
+- P-002-other-feature
+
+Archiving...
+✅ Complete: 2 sessions archived
+```
+
+### Dry Run
+
+```bash
+/planning-cleanup --dry-run
+
+Would archive:
+- P-001-feature-name → archived/2024/10/
+
+No changes made (dry run)
+```
+
+## Best Practices
+
+1. **Regular Cleanup:** Weekly review, monthly archive
+2. **Before Archiving:** All criteria met, commits pushed, tests passing
+3. **Completion Reports:** Include lessons learned and metrics
+4. **Recovery:** Archives can be unarchived manually
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Uncommitted changes | Commit or stash before archiving |
+| Archive exists | Rename or remove old archive |
+| Registry out of sync | Regenerate registry |
+
+## Related Commands
+
+- `/start-feature-plan` - Create planning session
+- `/sync-planning` - Sync to issue tracker
+- `/quality-check` - Validate before completion

package/templates/commands/planning/sync-planning-github.md

@@ -0,0 +1,133 @@
+---
+name: sync-planning-github
+description: Synchronize planning session to GitHub Issues
+type: planning
+category: planning
+config_required:
+  github_token_env: "Environment variable for GitHub token (e.g., GITHUB_TOKEN)"
+  github_owner_env: "Environment variable for repository owner"
+  github_repo_env: "Environment variable for repository name"
+  planning_path: "Base path for planning sessions"
+  tracking_file: "GitHub tracking file path"
+---
+
+# Sync Planning to GitHub
+
+Synchronize planning session to GitHub Issues, creating parent and sub-issues for all tasks.
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `github_token_env` | GitHub token environment variable | `{{GITHUB_TOKEN}}` |
+| `github_owner_env` | Repository owner env variable | `{{GITHUB_OWNER}}` |
+| `github_repo_env` | Repository name env variable | `{{GITHUB_REPO}}` |
+| `planning_path` | Planning sessions directory | `{{PLANNING_PATH}}` |
+| `tracking_file` | GitHub tracking data file | `{{TRACKING_FILE}}` |
+
+## Usage
+
+```bash
+/sync-planning-github [session_path]
+```
+
+## When to Use
+
+- After completing planning phase with user approval
+- To create trackable GitHub issues
+- When working across multiple devices
+- Before starting implementation
+
+## Process
+
+### Step 1: Identify Session
+
+Auto-detect or ask user for session path.
+
+**Expected:** `{{PLANNING_PATH}}/{session-name}/`
+
+### Step 2: Verify Files
+
+Required files:
+
+- PDR.md
+- TODOs.md
+
+### Step 3: Get Configuration
+
+Required environment variables:
+
+- `{{GITHUB_TOKEN}}` - Personal Access Token with repo permissions
+- `{{GITHUB_OWNER}}` - Repository owner
+- `{{GITHUB_REPO}}` - Repository name
+
+### Step 4: Execute Sync
+
+- Create parent issue
+- Create sub-issues for tasks
+- Update existing issues (idempotent)
+- Add labels and metadata
+
+### Step 5: Report Results
+
+```text
+✅ Planning synced to GitHub!
+
+Parent Issue: {title}
+   URL: {url}
+   Number: #{number}
+
+Statistics:
+   • {n} tasks created
+   • {n} tasks updated
+   • {n} skipped
+   • {n} failed
+
+Next Steps:
+   1. TODOs.md updated with issue links
+   2. Commit changes (TODOs.md, {{TRACKING_FILE}})
+   3. View: {repo_url}/issues
+   4. Use /check-completed when done
+```
+
+## Error Handling
+
+| Error | Message | Solution |
+|-------|---------|----------|
+| Missing config | Configuration missing | Set environment variables |
+| Files not found | Planning files not found | Run /start-feature-plan first |
+| API error | Failed to sync | Check token, permissions, rate limits |
+
+## Advanced Options
+
+### Dry Run
+
+```typescript
+{ dryRun: true }
+```
+
+### Custom Tracking
+
+```typescript
+{ trackingPath: '.custom/tracking.json' }
+```
+
+### Skip Updates
+
+```typescript
+{ updateExisting: false }
+```
+
+## Important Notes
+
+- **Idempotent:** Safe to run multiple times
+- **Tracking:** {{TRACKING_FILE}} maps tasks to issues
+- **Labels:** Auto-generated from task metadata
+- **Enrichment:** Issues include planning context
+
+## Related Commands
+
+- `/start-feature-plan` - Create planning
+- `/check-completed` - Auto-close completed
+- `/sync-todos-github` - Sync code TODOs
+- `/cleanup-issues` - Clean stale issues