npm - specweave - Versions diffs - 0.18.1 → 0.20.0 - Mend

specweave 0.18.1 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (384) hide show

package/plugins/specweave-github/commands/specweave-github-sync-epic.md DELETED Viewed

@@ -1,248 +0,0 @@
----
-name: specweave-github-sync-epic
-description: Sync SpecWeave Epic folder to GitHub (Milestone + Issues). Implements Universal Hierarchy architecture - Epic → Milestone, Increments → Issues.
----
-# Sync Epic to GitHub (Universal Hierarchy)
-**Architecture**: Hierarchical sync using Epic folder structure
-- **Epic (FS-001)** → **GitHub Milestone**
-- **Increment (0001-core-framework)** → **GitHub Issue** (linked to Milestone)
-## Usage
-```bash
-/specweave-github:sync-epic <epic-id>
-```
-## What It Does
-**Hierarchical Sync Process**:
-1. **Load Epic folder** from `.specweave/docs/internal/specs/FS-XXX-name/`
-2. **Parse Epic README.md** to get Epic metadata (title, increments, status)
-3. **Create or update GitHub Milestone**:
-   - Title: `[FS-001] Epic Title`
-   - Description: Epic overview + progress stats
-   - State: Open (active/planning) or Closed (complete)
-4. **Sync each increment as GitHub Issue**:
-   - Title: `[INC-0001-core-framework] Title`
-   - Body: Increment overview + link to tasks.md
-   - Milestone: Linked to Epic Milestone
-   - Labels: `increment`, `epic-sync`
-5. **Update frontmatter** in Epic README.md and increment files
-## Examples
-### Sync Epic FS-001 (Core Framework Architecture)
-```bash
-/specweave-github:sync-epic FS-001
-```
-**Output**:
-```
-🔄 Syncing Epic FS-001 to GitHub...
-   📦 Epic: Core Framework Architecture
-   📊 Increments: 4
-   🚀 Creating GitHub Milestone...
-   ✅ Created Milestone #10
-   📝 Syncing 4 increments...
-   ✅ Created Issue #130 for 0001-core-framework
-   ✅ Created Issue #131 for 0002-core-enhancements
-   ✅ Created Issue #132 for 0004-plugin-architecture
-   ✅ Created Issue #133 for 0005-cross-platform-cli
-✅ Epic sync complete!
-   Milestone: https://github.com/owner/repo/milestone/10
-   Issues created: 4
-   Issues updated: 0
-```
-### Sync Epic with short ID
-```bash
-/specweave-github:sync-epic 031
-# Resolves to FS-031
-```
-### Re-sync Epic (updates existing Milestone/Issues)
-```bash
-/specweave-github:sync-epic FS-001
-```
-**Output**:
-```
-🔄 Syncing Epic FS-001 to GitHub...
-   ♻️  Updating existing Milestone #10...
-   ✅ Updated Milestone #10
-   📝 Syncing 4 increments...
-   ♻️  Updated Issue #130 for 0001-core-framework
-   ♻️  Updated Issue #131 for 0002-core-enhancements
-   ♻️  Updated Issue #132 for 0004-plugin-architecture
-   ♻️  Updated Issue #133 for 0005-cross-platform-cli
-✅ Epic sync complete!
-   Milestone: https://github.com/owner/repo/milestone/10
-   Issues created: 0
-   Issues updated: 4
-```
-## Arguments
-- `<epic-id>` - Epic ID (e.g., `FS-001` or just `001`)
-## What Gets Created
-### GitHub Milestone (Epic-level)
-```
-Title: [FS-001] Core Framework Architecture
-Description:
-  Epic: Core Framework Architecture
-  Progress: 4/4 increments (100%)
-  Priority: P0
-  Status: complete
-State: Closed (if complete) or Open (if active/planning)
-```
-### GitHub Issues (Increment-level)
-```markdown
-Title: [INC-0001-core-framework] Core Framework
-# Core Framework
-Foundation framework with CLI, plugin system, and agent architecture...
----
-**Increment**: 0001-core-framework
-**Milestone**: See milestone for Epic progress
-🤖 Auto-created by SpecWeave Epic Sync
-```
-**Labels**: `increment`, `epic-sync`
-**Milestone**: Linked to Epic Milestone
-## Frontmatter Updates
-### Epic README.md (after sync)
-```yaml
----
-id: FS-001
-title: "Core Framework Architecture"
-external_tools:
-  github:
-    type: milestone
-    id: 10                              # ← Added
-    url: https://github.com/.../milestone/10  # ← Added
-increments:
-  - id: 0001-core-framework
-    external:
-      github: 130                       # ← Added
-  - id: 0002-core-enhancements
-    external:
-      github: 131                       # ← Added
----
-```
-### Increment file (0001-core-framework.md)
-```yaml
----
-id: 0001-core-framework
-epic: FS-001
-external:
-  github:
-    issue: 130                          # ← Added
-    url: https://github.com/.../issues/130  # ← Added
----
-```
-## Benefits
-✅ **Hierarchical tracking**: GitHub Milestones group related increments
-✅ **Epic-level progress**: See completion percentage in Milestone
-✅ **Automatic linking**: All Issues linked to Milestone
-✅ **Idempotent**: Safe to re-run (updates existing Milestone/Issues)
-✅ **Brownfield-ready**: Links existing GitHub Milestones/Issues
-## Requirements
-1. **GitHub CLI** (`gh`) installed and authenticated
-2. **Git repository** with GitHub remote
-3. **Write access** to repository (for creating Milestones/Issues)
-4. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
-## Architecture: Why Milestones?
-**GitHub's Hierarchy**:
-- GitHub Milestones = Epic-level grouping
-- GitHub Issues = Increment-level work items
-- GitHub Projects = Optional (cross-Epic tracking)
-**Comparison with JIRA/ADO**:
-- JIRA: Epic → Epic, Increment → Story (with Epic Link field)
-- ADO: Epic → Feature, Increment → User Story (with Parent link)
-- GitHub: Epic → Milestone, Increment → Issue (with Milestone link)
-All three implement the same Universal Hierarchy, just with different terminology.
-## Troubleshooting
-**"Epic FS-001 not found"**:
-- Check Epic folder exists: `ls .specweave/docs/internal/specs/`
-- Verify Epic ID format: `FS-001-epic-name/`
-**"Epic README.md missing YAML frontmatter"**:
-- Ensure Epic was migrated with `migrate-to-epic-folders.ts`
-- Frontmatter must start with `---` on line 1
-**"Failed to create GitHub Milestone"**:
-- Check GitHub CLI auth: `gh auth status`
-- Verify write access: `gh repo view`
-- Check rate limits: `gh api rate_limit`
-**"Could not extract issue number"**:
-- GitHub CLI output format may have changed
-- Check CLI version: `gh --version` (need v2.0.0+)
-## Related Commands
-- `/specweave-github:sync-spec` - OLD (flat spec → project) - DEPRECATED for Epic architecture
-- `/specweave-jira:sync-epic` - Sync to JIRA Epic + Stories
-- `/specweave-ado:sync-epic` - Sync to ADO Feature + User Stories
-## Implementation
-**File**: `plugins/specweave-github/lib/github-epic-sync.ts`
-**Core Class**: `GitHubEpicSync`
-**Methods**:
-- `syncEpicToGitHub(epicId)` - Main sync logic
-- `createMilestone(epic)` - Create GitHub Milestone
-- `updateMilestone(number, epic)` - Update existing Milestone
-- `createIssue(increment, milestone)` - Create GitHub Issue
-- `updateIssue(number, increment, milestone)` - Update existing Issue
-- `updateEpicReadme(path, github)` - Update frontmatter
-- `updateIncrementExternalLink(...)` - Update increment frontmatter
-## Next Steps
-After syncing Epic to GitHub:
-1. **View Milestone progress**: `gh milestone view 10`
-2. **List Issues in Milestone**: `gh issue list --milestone 10`
-3. **Track completion**: GitHub automatically calculates Milestone progress
-4. **Close Milestone**: When all increments complete, Milestone auto-closes

package/plugins/specweave-github/commands/specweave-github-sync-from.md DELETED Viewed

@@ -1,147 +0,0 @@
----
-name: specweave-github:sync-from
-description: Sync state from GitHub to SpecWeave (bidirectional sync). Fetches issue state, comments, and detects conflicts.
----
-# Sync from GitHub to SpecWeave
-Bidirectional sync - pull changes from GitHub issue back to SpecWeave increment.
-## Usage
-```bash
-/specweave-github:sync-from <incrementId>
-```
-## What It Does
-1. **Fetches GitHub Issue State**:
-   - Issue status (open/closed)
-   - Comments
-   - Labels, assignees, milestones
-   - Last updated timestamp
-2. **Detects Conflicts**:
-   - GitHub closed but SpecWeave active
-   - SpecWeave completed but GitHub open
-   - GitHub abandoned but issue open
-3. **Syncs Comments**:
-   - Saves GitHub comments to `.specweave/increments/<id>/logs/github-comments.md`
-   - Only syncs new comments (tracks IDs)
-4. **Updates Metadata**:
-   - Updates `metadata.json` with latest GitHub state
-   - Tracks last sync timestamp
-## Examples
-### Basic Sync
-```bash
-/specweave-github:sync-from 0015-hierarchical-sync
-```
-**Output**:
-```
-🔄 Syncing from GitHub for increment: 0015-hierarchical-sync
-   Syncing from anton-abyzov/specweave#29
-✅ No conflicts - GitHub and SpecWeave in sync
-📝 Syncing 3 new comment(s)
-✅ Comments saved to: logs/github-comments.md
-✅ Metadata updated
-✅ Bidirectional sync complete
-```
-### Conflict Detection
-```bash
-/specweave-github:sync-from 0015-hierarchical-sync
-```
-**Output**:
-```
-🔄 Syncing from GitHub for increment: 0015-hierarchical-sync
-   Syncing from anton-abyzov/specweave#29
-⚠️  Detected 1 conflict(s)
-⚠️  Conflict detected: status
-   GitHub: closed
-   SpecWeave: active
-⚠️  **CONFLICT**: GitHub issue closed but SpecWeave increment still active!
-   Recommendation: Run /specweave:done 0015-hierarchical-sync to close increment
-   Or reopen issue on GitHub if work is not complete
-✅ Bidirectional sync complete
-```
-## When to Use
-Use this command when:
-- ✅ Someone closed/reopened the GitHub issue
-- ✅ Comments were added on GitHub (want to import them)
-- ✅ Want to check if GitHub and SpecWeave are in sync
-- ✅ Resolving conflicts between GitHub and SpecWeave state
-## Requirements
-- GitHub CLI (`gh`) installed and authenticated
-- GitHub issue linked in metadata.json
-- Repository has GitHub remote configured
-## Conflict Resolution
-### GitHub Closed, SpecWeave Active
-**Resolution**: Close SpecWeave increment
-```bash
-/specweave:done 0015-hierarchical-sync
-```
-**Or**: Reopen GitHub issue if work not complete
-```bash
-gh issue reopen 29
-```
-### SpecWeave Completed, GitHub Open
-**Resolution**: Close GitHub issue
-```bash
-gh issue close 29 --comment "Increment completed in SpecWeave"
-```
-### SpecWeave Abandoned, GitHub Open
-**Resolution**: Close GitHub issue with reason
-```bash
-gh issue close 29 --comment "Increment abandoned: Requirements changed"
-```
-## Files Modified
-- `.specweave/increments/<id>/logs/github-comments.md` - GitHub comments
-- `.specweave/increments/<id>/metadata.json` - Sync metadata
-## Related Commands
-- `/specweave-github:sync` - One-way sync (SpecWeave → GitHub)
-- `/specweave-github:create-issue` - Create GitHub issue
-- `/specweave-github:close-issue` - Close GitHub issue
-- `/specweave-github:status` - Check sync status
-## Automation
-For automatic bidirectional sync, add to cron or CI/CD:
-```bash
-# Sync all active increments hourly
-0 * * * * cd /path/to/project && \
-  for inc in $(ls .specweave/increments/ | grep -v _backlog); do \
-    /specweave-github:sync-from $inc; \
-  done
-```
-## Implementation
-Invokes `github-sync-bidirectional` agent with conflict detection and resolution logic.

package/plugins/specweave-github/commands/specweave-github-sync-spec.md DELETED Viewed

@@ -1,208 +0,0 @@
----
-name: specweave-github-sync-spec
-description: Sync SpecWeave spec to GitHub Project (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with GitHub Projects for permanent feature tracking.
----
-# Sync Spec to GitHub Project
-**CORRECT ARCHITECTURE**: This command syncs `.specweave/docs/internal/specs/spec-*.md` files (PERMANENT living docs) to GitHub Projects, NOT increments to issues.
-## Usage
-```bash
-/specweave-github:sync-spec <spec-id> [--direction <to-github|from-github|bidirectional>]
-```
-## What It Does
-**Architecture**:
-- **Spec → GitHub Project** (not increment → issue!)
-- **User Story → GitHub Issue** (linked to project)
-- **Acceptance Criteria → Checklist** (in issue body)
-**Sync Process**:
-1. **Load spec** from `.specweave/docs/internal/specs/spec-{id}.md`
-2. **Detect repository** from git remote
-3. **Create or update GitHub Project**:
-   - Title: `[SPEC-001] Feature Title`
-   - Description: Spec overview + progress
-   - Status: Matches spec status
-4. **Sync user stories as issues**:
-   - Create issues for new user stories
-   - Update existing issues
-   - Close issues for completed user stories
-5. **Link spec to project** (update frontmatter)
-## Examples
-### Sync spec to GitHub (create or update)
-```bash
-/specweave-github:sync-spec spec-001
-```
-**Output**:
-```
-🔄 Syncing spec spec-001 to GitHub Project...
-   Creating new GitHub Project...
-   ✅ Created GitHub Project #5: https://github.com/owner/repo/projects/5
-   Syncing 35 user stories...
-   ✅ Created US-001 → Issue #130
-   ✅ Created US-002 → Issue #131
-   ...
-✅ Sync complete!
-   Created: 35 user stories
-   GitHub Project: https://github.com/owner/repo/projects/5
-```
-### Sync FROM GitHub to spec (bidirectional)
-```bash
-/specweave-github:sync-spec spec-001 --direction from-github
-```
-**Output**:
-```
-🔄 Syncing FROM GitHub to spec spec-001...
-   Fetching GitHub Project #5...
-   ⚠️  Detected 3 conflict(s)
-   🔄 Resolving: US-002 marked done in GitHub (GitHub wins)
-   🔄 Resolving: US-005 marked in-progress in GitHub (GitHub wins)
-✅ Sync FROM GitHub complete!
-   Updated: 3 user stories
-```
-### Bidirectional sync (default)
-```bash
-/specweave-github:sync-spec spec-001 --direction bidirectional
-```
-## Arguments
-- `<spec-id>` - Spec ID (e.g., `spec-001` or just `001`)
-- `--direction <mode>` - Sync direction (default: `to-github`)
-  - `to-github` - Push local spec to GitHub
-  - `from-github` - Pull GitHub state to spec
-  - `bidirectional` - Sync both ways (conflict resolution)
-## Conflict Resolution
-When syncing FROM GitHub, conflicts are resolved as follows:
-**GitHub wins** (default):
-- User story status changes → update spec
-- Acceptance criteria status → update spec
-- Issue closure → mark user story done
-**Local wins** (future):
-- Spec changes take precedence
-- Push to GitHub
-## Requirements
-1. **GitHub CLI** (`gh`) installed and authenticated
-2. **Git repository** with GitHub remote
-3. **Write access** to repository (for creating projects/issues)
-4. **Spec file exists** at `.specweave/docs/internal/specs/spec-{id}.md`
-## What Gets Synced
-### Spec → GitHub Project
-- ✅ Title: `[SPEC-001] Feature Area Title`
-- ✅ Description: Overview + progress stats
-- ✅ Status: Open/Closed based on spec completion
-### User Story → GitHub Issue
-- ✅ Title: `[US-001] As a user, I want...`
-- ✅ Body: User story + acceptance criteria checklist
-- ✅ Labels: `user-story`, `spec:spec-001`, `priority:P1`
-- ✅ State: Open (todo/in-progress) or Closed (done)
-### Acceptance Criteria → Checklist
-```markdown
-## Acceptance Criteria
-- [x] User can log in with email/password
-- [ ] Invalid credentials show error message
-- [ ] Account locks after 5 failed attempts
-```
-## Architecture
-**Why This Architecture?**
-✅ **Permanent tracking**: Specs never deleted, GitHub links remain valid
-✅ **Feature-level granularity**: One GitHub Project per feature (not per increment)
-✅ **PM-friendly**: Stakeholders see progress in GitHub Projects
-✅ **Brownfield-ready**: Existing GitHub Projects map to specs
-**What's WRONG?**
-❌ Increment → GitHub Issue (increments are temporary!)
-❌ Tasks → GitHub Issues (too granular, implementation details)
-❌ Multiple issues per feature (split across increments)
-## Metadata
-After sync, spec frontmatter is updated:
-```yaml
----
-id: spec-001
-title: Core Framework Architecture
-status: in-progress
-priority: P0
-externalLinks:
-  github:
-    projectId: 5
-    projectUrl: https://github.com/owner/repo/projects/5
-    syncedAt: "2025-11-10T12:00:00Z"
-    owner: owner
-    repo: repo
----
-```
-## Troubleshooting
-**"Could not detect GitHub repository"**:
-- Ensure you're in a git repo with GitHub remote
-- Run: `git remote -v` to check
-**"Spec not found"**:
-- Check spec exists: `ls .specweave/docs/internal/specs/`
-- Use correct ID: `spec-001` or `001`
-**"GraphQL query failed"**:
-- Check GitHub CLI auth: `gh auth status`
-- Re-authenticate: `gh auth login`
-**"No user stories to sync"**:
-- Add user stories to spec.md:
-  ```markdown
-  **US-001**: As a user, I want...
-  - [ ] **AC-001-01**: Acceptance criteria 1
-  ```
-## Related
-- `/specweave-github:sync` - OLD command (increment-based, DEPRECATED)
-- `/specweave-jira:sync-spec` - Sync to Jira Epic
-- `/specweave-ado:sync-spec` - Sync to Azure DevOps Feature
-- `/specweave:sync-docs` - Sync living docs from increments to specs
-## Implementation
-**File**: `plugins/specweave-github/lib/github-spec-sync.ts`
-**Core Class**: `GitHubSpecSync`
-**Methods**:
-- `syncSpecToGitHub(specId)` - Push to GitHub
-- `syncFromGitHub(specId)` - Pull from GitHub
-- `detectConflicts(spec, project)` - Compare states
-- `resolveConflicts(spec, conflicts)` - Apply resolution strategy