specweave 0.28.20 → 0.28.24

package/plugins/specweave-github/commands/specweave-github-sync.md

@@ -83,7 +83,7 @@ Synchronize the current state of a SpecWeave increment with its GitHub issue acr
 - `--comment`: Post progress comment (default)
 - `--labels`: Update issue labels based on status
 - `--force`: Force sync even if up-to-date
-- `--direction`: Sync direction (`to-github`, `from-github`, `bidirectional` - **default: bidirectional**)
+- `--direction`: Sync direction (`to-github`, `from-github`, `two-way` - **default: two-way**)
 - `--all`: Sync all active increments
 
 ### Safety Options
@@ -92,17 +92,17 @@ Synchronize the current state of a SpecWeave increment with its GitHub issue acr
 
 ## Sync Direction
 
-**Default: Bidirectional** (two-way sync)
+**Default: Two-way** (both directions)
 
 SpecWeave syncs changes in **both directions** by default:
 
 | Direction | What It Does | Use When |
 |-----------|-------------|----------|
-| **`bidirectional`** (default) | SpecWeave ↔ GitHub<br>• Pull changes FROM GitHub (status, labels, comments)<br>• Push changes TO GitHub (tasks, progress, metadata) | **Always** (recommended for keeping both systems in sync) |
+| **`two-way`** (default) | SpecWeave ↔ GitHub<br>• Pull changes FROM GitHub (status, labels, comments)<br>• Push changes TO GitHub (tasks, progress, metadata) | **Always** (recommended for keeping both systems in sync) |
 | `to-github` | SpecWeave → GitHub only<br>• Push increment progress to GitHub<br>• Don't pull GitHub changes back | Read-only GitHub usage, or when GitHub is downstream |
 | `from-github` | GitHub → SpecWeave only<br>• Pull GitHub issue updates<br>• Don't push SpecWeave changes | Importing GitHub issues, or when SpecWeave is downstream |
 
-**Why Bidirectional?**
+**Why Two-way?**
 - ✅ Keep both systems synchronized automatically
 - ✅ GitHub status changes update SpecWeave (closed issue → completed increment)
 - ✅ SpecWeave task completion updates GitHub (task done → checklist updated)
@@ -121,16 +121,16 @@ SpecWeave syncs changes in **both directions** by default:
 ## Examples
 
 ```bash
-# Interactive bidirectional sync (default - two-way)
+# Interactive two-way sync (default - both directions)
 /specweave-github:sync 0004
 
-# Use specific profile (still bidirectional by default)
+# Use specific profile (still two-way by default)
 /specweave-github:sync 0004 --profile specweave-dev
 
-# Specify time range (bidirectional)
+# Specify time range (two-way)
 /specweave-github:sync 0004 --time-range 1M
 
-# Full bidirectional sync with all options
+# Full two-way sync with all options
 /specweave-github:sync 0004 --profile main --time-range 1M --tasks --labels
 
 # One-way sync examples (override default)
@@ -140,7 +140,7 @@ SpecWeave syncs changes in **both directions** by default:
 # Dry run to preview changes
 /specweave-github:sync 0004 --dry-run
 
-# Force sync all increments (bidirectional)
+# Force sync all increments (two-way)
 /specweave-github:sync --all --force
 ```
 
@@ -240,12 +240,12 @@ Continue with sync? [Y/n]:
 If confirmed, sync proceeds with progress updates:
 
 ```
-🔄 Bidirectional sync for increment 0004...
+🔄 Two-way sync for increment 0004...
 
 ✓ Profile loaded: specweave-dev
 ✓ GitHub repository: anton-abyzov/specweave
 ✓ Rate limit check: PASSED (4,850/5,000 remaining)
-✓ Sync direction: bidirectional (two-way)
+✓ Sync direction: Two-way (push & pull)
 
 Fetching increment state...
 ✓ Increment loaded: 0004-plugin-architecture
@@ -277,7 +277,7 @@ Syncing FROM GitHub...
 
 Rate limit after sync: 4,570/5,000 (91% available)
 
-✅ Bidirectional Sync Complete!
+✅ Two-way Sync Complete!
 
    SpecWeave ↔ GitHub synchronized
    • Pushed: 3 task updates, progress comment

package/plugins/specweave-github/commands/specweave-github-update-user-story.md

@@ -111,7 +111,7 @@ Progress: 3/6 tasks complete (50%)
 **Related Commands**:
 - `/specweave-github:sync-epic FS-031` - Sync entire epic (all user stories)
 - `/specweave-github:create-issue 0031` - Create issue for increment
-- `/specweave-github:sync 0031` - Bidirectional sync for increment
+- `/specweave-github:sync 0031` - Two-way sync for increment
 
 ---
 

package/plugins/specweave-github/skills/github-sync/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: github-sync
-description: Bidirectional synchronization between SpecWeave specs and GitHub Projects (two-way sync by default). Activates ONLY when user asks questions about GitHub integration or needs help configuring GitHub sync. Does NOT activate for slash commands. For syncing, use /specweave-github:sync-spec command instead.
+description: Two-way synchronization between SpecWeave specs and GitHub Projects (push & pull by default). Activates ONLY when user asks questions about GitHub integration or needs help configuring GitHub sync. Does NOT activate for slash commands. For syncing, use /specweave-github:sync-spec command instead.
 ---
 
-# GitHub Sync - Bidirectional Spec ↔ Project Synchronization
+# GitHub Sync - Two-way Spec ↔ Project Synchronization
 
 **Purpose**: Seamlessly synchronize SpecWeave specs with GitHub Projects for team visibility and project management.
 
-**Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
+**Default Behavior**: **Two-way sync** (push & pull) - Changes in either system are automatically synchronized
 
 **⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about GitHub sync. For actual syncing, users should use the `/specweave-github:sync-spec` command directly. This skill should NOT auto-activate when the command is being invoked.
 
@@ -203,7 +203,7 @@ Configure GitHub sync in `.specweave/config.json`:
       "specweave-github": {
         "repo": "owner/repo",
         "autoSyncSpecs": true,
-        "syncDirection": "bidirectional",
+        "syncDirection": "two-way",
         "defaultLabels": ["specweave", "spec"],
         "syncFrequency": "on-change"
       }

package/plugins/specweave-jira/commands/specweave-jira-sync.md

@@ -1,6 +1,6 @@
 ---
 name: specweave-jira:sync
-description: Sync SpecWeave increments with JIRA epics/stories. Supports import, export, bidirectional sync, and granular item operations
+description: Sync SpecWeave increments with JIRA epics/stories. Supports import, export, two-way sync, and granular item operations
 ---
 
 # Sync Jira Command
@@ -11,10 +11,10 @@ You are a Jira synchronization expert. Help the user sync between Jira and SpecW
 
 ### Epic-Level Operations
 
-**1. Bidirectional Sync (Default - Recommended)**
+**1. Two-way Sync (Default - Recommended)**
 ```
 /specweave-jira:sync 0003                    # Two-way sync (default)
-/specweave-jira:sync 0003 --direction bidirectional  # Explicit
+/specweave-jira:sync 0003 --direction two-way  # Explicit
 ```
 
 **2. Import Jira Epic as SpecWeave Increment**
@@ -31,9 +31,9 @@ You are a Jira synchronization expert. Help the user sync between Jira and SpecW
 
 ### Sync Direction Options
 
-**Default: `bidirectional`** (two-way sync - recommended)
+**Default: `two-way`** (both directions - recommended)
 
-- `--direction bidirectional`: SpecWeave ↔ Jira (default)
+- `--direction two-way`: SpecWeave ↔ Jira (default)
   - Pull changes FROM Jira (status, priority, comments)
   - Push changes TO Jira (tasks, progress, metadata)
 
@@ -175,7 +175,7 @@ When the user runs this command:
   | Task  | SCRUM-7  | Setup provider  |
   ```
 
-### Example 5: Bidirectional Sync (Default)
+### Example 5: Two-way Sync (Default)
 **User**: `/specweave-jira:sync 0003`
 **You**:
 - Read increment 0003
@@ -186,9 +186,9 @@ When the user runs this command:
 - FROM Jira: Status changes, priority updates, comments
 - FROM SpecWeave: Task completion, progress updates
 
-**Show bidirectional sync summary**:
+**Show two-way sync summary**:
 ```
-✅ Bidirectional Sync Complete: 0003 ↔ Jira
+✅ Two-way Sync Complete: 0003 ↔ Jira
 
 FROM Jira:
   • SCRUM-1: Status changed to In Progress
@@ -204,7 +204,7 @@ Conflicts: None
 **Handle conflicts if any**:
 - Show both versions (Jira vs SpecWeave)
 - Ask user which to keep or how to merge
-- Apply resolution bidirectionally
+- Apply resolution in both directions
 
 ### Example 6: Status Overview
 **User**: `/specweave-jira:sync status`
@@ -229,12 +229,12 @@ Conflicts: None
 
 ## Related Commands
 
-- `/specweave-github:sync` - Sync to GitHub issues (also bidirectional by default)
+- `/specweave-github:sync` - Sync to GitHub issues (also two-way by default)
 - `/specweave:increment` - Create new increment
 - `/specweave:validate` - Validate increment quality
 
 ---
 
-**Bidirectional by Default**: All sync operations are two-way unless you explicitly specify `--direction to-jira` or `--direction from-jira`. This keeps both systems synchronized automatically.
+**Two-way by Default**: All sync operations are two-way unless you explicitly specify `--direction to-jira` or `--direction from-jira`. This keeps both systems synchronized automatically.
 
 **Granular Control**: Unlike simple epic import/export, this command supports cherry-picking individual stories, bugs, and tasks for maximum flexibility.

package/plugins/specweave-jira/skills/specweave-jira-mapper/SKILL.md

@@ -328,7 +328,7 @@ JIRA Epic: PROJ-123
    ```yaml
    jira:
      last_sync: "2025-10-26T16:30:00Z"
-     sync_direction: "bidirectional"
+     sync_direction: "two-way"
      conflicts_resolved: 2
    ```
 
@@ -336,7 +336,7 @@ JIRA Epic: PROJ-123
 ```
 ✅ Synced with JIRA!
 
-Direction: Bidirectional
+Direction: Two-way
 Changes Applied:
   - SpecWeave → JIRA: 3 updates
   - JIRA → SpecWeave: 5 updates

package/plugins/specweave-release/commands/specweave-release-npm.md

@@ -1,6 +1,6 @@
 ---
 name: specweave-release:npm
-description: Bump patch version, create git tag, and trigger npm publish via GitHub Actions. Automates the complete release workflow with pre-flight checks, version bumping, tag creation, and GitHub Actions triggering. Use --only flag for quick local release (bumps version, builds, publishes to npm directly - NO git push, NO pipeline).
+description: Bump patch version, create git tag, and trigger npm publish via GitHub Actions. Automates the complete release workflow with pre-flight checks, version bumping, tag creation, and GitHub Actions triggering. Use --only flag for quick local release (bumps version, builds, publishes to npm directly - NO git push, NO pipeline). Add --push to --only for complete local release with git sync.
 ---
 
 # /specweave-release:npm - NPM Release Automation
@@ -9,17 +9,30 @@ You are the NPM Release Assistant. Your job is to automate the patch version rel
 
 ## Command Modes
 
-**Default mode** (no flags): Bump → Push to GitHub → GitHub Actions publishes to npm
-**Direct mode** (`--only`): Bump → Build → Publish to npm directly (NO git push, NO pipeline)
+| Command | Flow | Use Case |
+|---------|------|----------|
+| `/specweave-release:npm` | Bump → Push → **CI publishes** | Standard release (CI handles npm) |
+| `/specweave-release:npm --only` | Bump → Build → **Publish locally** → NO push | Quick local release, push later |
+| `/specweave-release:npm --only --push` | Bump → Build → **Publish locally** → Push | Complete local release + git sync |
 
 ## Detecting Mode
 
-First, check if the user provided `--only` flag:
-- Look at the command invocation (e.g., `/specweave-release:npm --only`)
-- Check conversation context for `--only` parameter
+Check flags in the command invocation:
 
-**If `--only` flag detected**: Use DIRECT MODE (skip to section "Direct Mode Workflow")
-**If no flag**: Use DEFAULT MODE (continue with steps below)
+```
+--only         → Direct publish to npm (bypass CI)
+--only --push  → Direct publish + push to git after
+(no flags)     → Default: push to git, CI publishes
+```
+
+**Flag Detection Order:**
+1. Check for `--only` flag
+2. If `--only` present, check for `--push` flag
+3. Route to appropriate workflow section
+
+**If `--only --push`**: Use DIRECT MODE WITH PUSH (section "Direct Mode + Push Workflow")
+**If `--only` only**: Use DIRECT MODE (section "Direct Mode Workflow")
+**If no flags**: Use DEFAULT MODE (continue with steps below)
 
 ## Your Task
 
@@ -228,3 +241,169 @@ Show the user:
 ✅ Package rebuilt
 ✅ Published to npm directly
 ⏸️ Git NOT pushed (manual sync later)
+
+---
+
+## DIRECT MODE + PUSH WORKFLOW (--only --push flags)
+
+Use this workflow when BOTH `--only` AND `--push` flags are detected. This is the **complete local release** - publishes to npm directly AND pushes to git.
+
+**Use case**: You want full control - publish immediately, then sync git. No CI involvement in npm publish.
+
+### 1. Pre-flight Checks
+
+```bash
+# Verify we're on develop branch
+git rev-parse --abbrev-ref HEAD
+
+# Check for uncommitted changes
+git status --porcelain
+
+# Verify current version
+node -p "require('./package.json').version"
+```
+
+**STOP if**:
+- Not on `develop` branch (ask user to switch)
+
+**If uncommitted changes exist → AUTO-COMMIT FIRST (Step 1b)**
+
+### 1b. Auto-Commit Uncommitted Changes (if any)
+
+When `--only --push` is used, uncommitted changes should be committed automatically before version bump.
+
+**Algorithm to generate commit message:**
+
+1. Run `git status --porcelain` and categorize files:
+   - `src/**` → code changes
+   - `*.md`, `docs/` → documentation
+   - `.specweave/docs/internal/**` → internal docs
+   - `plugins/**` → plugin changes
+   - `tests/**`, `*.test.ts` → test changes
+   - `package*.json`, `*.config.*` → config/deps
+
+2. Determine primary category (most files) and action (add/update/remove):
+   - New files (`??`, `A`) → "add"
+   - Modified (`M`) → "update"
+   - Deleted (`D`) → "remove"
+
+3. Generate concise message: `type: action description`
+
+**Examples:**
+- Many ADR renames + docs moves → `chore: reorganize internal docs structure`
+- Plugin command updates → `feat(release): add --push flag to npm release`
+- Mixed code + docs → `chore: update code and documentation`
+
+**Execute auto-commit:**
+```bash
+git add -A
+git commit -m "[generated message]"
+```
+
+Then continue with version bump.
+
+### 2. Bump Patch Version
+
+```bash
+# This creates commit + tag automatically
+npm version patch -m "chore: bump version to %s"
+```
+
+### 3. Extract New Version
+
+```bash
+# Get the new version
+node -p "require('./package.json').version"
+```
+
+### 4. Build Package
+
+```bash
+# Build the package before publishing
+npm run rebuild
+```
+
+**Critical**: Must rebuild to ensure dist/ is up-to-date before publishing.
+
+### 5. Publish to NPM Directly
+
+```bash
+# Publish directly to npm (bypasses GitHub Actions)
+npm publish
+```
+
+### 6. Push to Git (NEW!)
+
+```bash
+# Push commit and tag to sync with remote
+git push origin develop --follow-tags
+```
+
+**What this does**:
+- Syncs your version bump commit to GitHub
+- Pushes the version tag (vX.Y.Z)
+- Does NOT trigger CI npm publish (already published!)
+
+### 7. Report Results (Direct Mode + Push)
+
+Show the user:
+```markdown
+✅ **Complete local release!**
+
+📦 **Version**: vX.Y.Z
+🔗 **NPM**: https://www.npmjs.com/package/specweave
+🏷️ **Git Tag**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
+
+**What happened**:
+- ✅ Version bumped and committed
+- ✅ Git tag created
+- ✅ Package built (npm run rebuild)
+- ✅ Published to npm directly
+- ✅ Pushed to GitHub (commit + tag)
+
+**Verify**:
+- NPM: https://www.npmjs.com/package/specweave
+- Version: `npm view specweave version`
+- GitHub: Check releases page
+
+**Note**: This was a direct publish. GitHub Actions will NOT republish
+(the tag already exists, CI skips existing versions).
+```
+
+## Direct Mode + Push Safety Rules
+
+- ✅ ALWAYS rebuild before publishing
+- ✅ Publishes FIRST, then pushes (ensures npm has the version)
+- ✅ If push fails, npm already has the release (safe state)
+- ✅ CI will skip publishing for this version (tag already exists)
+- ⚠️ Use when you need immediate npm availability + git sync
+
+## Success Criteria (Direct Mode + Push)
+
+✅ Version bumped in package.json
+✅ Git commit created
+✅ Git tag created
+✅ Package rebuilt
+✅ Published to npm directly
+✅ Pushed to GitHub (commit + tag synced)
+
+---
+
+## Quick Reference
+
+```bash
+# Standard release (CI handles npm publish)
+/specweave-release:npm
+
+# Quick local publish, sync git later
+/specweave-release:npm --only
+
+# Complete local release (publish + push)
+/specweave-release:npm --only --push
+```
+
+| Scenario | Command | NPM Published By | Git Pushed |
+|----------|---------|------------------|------------|
+| Normal release | (no flags) | GitHub Actions | ✅ Yes |
+| Quick local, push later | `--only` | You (local) | ❌ No |
+| Complete local release | `--only --push` | You (local) | ✅ Yes |