specweave 0.10.1 → 0.12.0

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -6,23 +6,33 @@
 
 **Tools**: Read, Write, Edit, Bash (GitHub CLI)
 
+**Default Behavior**: **Bidirectional sync** (two-way) - Synchronizes changes in both directions automatically
+
 ---
 
 ## Capabilities
 
 As the GitHub Manager agent, I specialize in:
 
-### 1. Issue Management
+### 1. Bidirectional Synchronization (Default)
+- **Two-Way Sync**: Keep SpecWeave and GitHub synchronized automatically
+  - **FROM GitHub**: Pull status changes, labels, comments, state updates
+  - **TO GitHub**: Push task completion, progress updates, metadata
+- **Conflict Resolution**: Detect and resolve conflicts between systems
+- **Smart Merging**: Merge changes from both directions intelligently
+- **Change Detection**: Track what changed in both systems since last sync
+
+### 2. Issue Management
 - **Create Issues**: Generate well-formatted GitHub issues from increment specs
-- **Update Issues**: Sync progress, add comments, update labels
+- **Update Issues**: Sync progress, add comments, update labels (bidirectional)
 - **Close Issues**: Close issues with completion summaries
 - **Link Issues**: Connect related issues, PRs, and increments
 - **Bulk Operations**: Batch create/update/close issues
 
-### 2. Progress Tracking
+### 3. Progress Tracking
 - **Task Checklists**: Generate and update task checklists in issues
 - **Progress Comments**: Post detailed task completion comments
-- **Status Updates**: Real-time sync of increment status to GitHub
+- **Status Updates**: Bidirectional sync of increment status ↔ GitHub issue state
 - **Time Tracking**: Track estimated vs actual time per task
 - **Milestone Progress**: Update milestone completion percentages
 

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

@@ -26,32 +26,64 @@ 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`)
+- `--direction`: Sync direction (`to-github`, `from-github`, `bidirectional` - **default: bidirectional**)
 - `--all`: Sync all active increments
 
 ### Safety Options
 - `--dry-run`: Preview changes without applying
 - `--skip-rate-check`: Skip rate limit validation (not recommended)
 
+## Sync Direction
+
+**Default: Bidirectional** (two-way sync)
+
+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) |
+| `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?**
+- ✅ Keep both systems synchronized automatically
+- ✅ GitHub status changes update SpecWeave (closed issue → completed increment)
+- ✅ SpecWeave task completion updates GitHub (task done → checklist updated)
+- ✅ Team members can work in either tool
+- ✅ No data loss from changes in either system
+
+**Override if needed:**
+```bash
+# Push only (one-way to GitHub)
+/specweave-github:sync 0004 --direction to-github
+
+# Pull only (one-way from GitHub)
+/specweave-github:sync 0004 --direction from-github
+```
+
 ## Examples
 
 ```bash
-# Interactive sync (select profile + time range)
+# Interactive bidirectional sync (default - two-way)
 /specweave-github:sync 0004
 
-# Use specific profile
+# Use specific profile (still bidirectional by default)
 /specweave-github:sync 0004 --profile specweave-dev
 
-# Specify time range
+# Specify time range (bidirectional)
 /specweave-github:sync 0004 --time-range 1M
 
-# Full sync with all options
+# Full bidirectional sync with all options
 /specweave-github:sync 0004 --profile main --time-range 1M --tasks --labels
 
+# One-way sync examples (override default)
+/specweave-github:sync 0004 --direction to-github     # Push only
+/specweave-github:sync 0004 --direction from-github   # Pull only
+
 # Dry run to preview changes
 /specweave-github:sync 0004 --dry-run
 
-# Force sync all increments
+# Force sync all increments (bidirectional)
 /specweave-github:sync --all --force
 ```
 
@@ -151,35 +183,52 @@ Continue with sync? [Y/n]:
 If confirmed, sync proceeds with progress updates:
 
 ```
-🔄 Syncing increment 0004 to GitHub...
+🔄 Bidirectional 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)
 
 Fetching increment state...
 ✓ Increment loaded: 0004-plugin-architecture
 ✓ GitHub issue: #130
 ✓ Last synced: 30 minutes ago
 
-Detecting changes...
+Detecting changes (both directions)...
+
+FROM GitHub:
+✓ Issue status changed: open → closed
+✓ Label added: ready-for-release
+✓ 2 new comments from team
+
+FROM SpecWeave:
 ✓ 3 new tasks completed (T-005, T-006, T-007)
 ✓ Progress: 4/48 → 7/48 (15%)
 ✓ Current task: T-008
 
-Syncing to GitHub...
+Syncing TO GitHub...
 ✓ Posted progress comment (ID: 1234567)
 ✓ Updated task checklist (7 tasks marked complete)
 ✓ Updated labels: +in-progress
 ✓ Metadata updated
 
+Syncing FROM GitHub...
+✓ Updated increment status: active → completed
+✓ Applied label: ready-for-release
+✓ Imported 2 team comments to increment notes
+
 Rate limit after sync: 4,570/5,000 (91% available)
 
-✅ Sync Complete!
+✅ Bidirectional Sync Complete!
+
+   SpecWeave ↔ GitHub synchronized
+   • Pushed: 3 task updates, progress comment
+   • Pulled: Status change, label, 2 comments
 
 GitHub Issue: https://github.com/anton-abyzov/specweave/issues/130
 Last synced: just now
-Next sync: Use /specweave-github:sync 0004 when ready
+Next sync: Automatic (hook-based) or manual when ready
 ```
 
 ## Key Features

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

@@ -1,12 +1,14 @@
 ---
 name: github-sync
-description: Bidirectional synchronization between SpecWeave increments and GitHub Issues. Creates issues from increments, tracks progress via comments, updates increment status from issue state, and closes issues when increments complete. Activates for GitHub sync, issue creation, increment tracking, GitHub integration, issue management, sync to GitHub.
+description: Bidirectional synchronization between SpecWeave increments and GitHub Issues (two-way sync by default). Creates issues from increments, tracks progress via comments, updates increment status from issue state, syncs changes in both directions automatically. Activates for GitHub sync, issue creation, increment tracking, GitHub integration, issue management, sync to GitHub, bidirectional sync.
 ---
 
 # GitHub Sync - Bidirectional Increment ↔ Issue Synchronization
 
 **Purpose**: Seamlessly synchronize SpecWeave increments with GitHub Issues for team visibility and project management.
 
+**Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
+
 **When to Use**:
 - Creating new increments (auto-create GitHub issue)
 - Syncing increment progress to GitHub (comments with task completion %)

package/plugins/specweave-jira/agents/jira-manager/AGENT.md

@@ -6,31 +6,41 @@
 
 **Tools**: Read, Write, Edit, Bash (curl for Jira API)
 
+**Default Behavior**: **Bidirectional sync** (two-way) - Synchronizes changes in both directions automatically
+
 ---
 
 ## Capabilities
 
 As the Jira Manager agent, I specialize in:
 
-### 1. Epic Management
+### 1. Bidirectional Synchronization (Default)
+- **Two-Way Sync**: Keep SpecWeave and Jira synchronized automatically
+  - **FROM Jira**: Pull status changes, priority updates, sprint assignments, comments
+  - **TO Jira**: Push task completion, progress updates, story points, metadata
+- **Conflict Resolution**: Detect and resolve conflicts between systems
+- **Smart Merging**: Merge changes from both directions intelligently
+- **Change Detection**: Track what changed in both systems since last sync
+
+### 2. Epic Management
 - **Create Epics**: Generate Jira Epics from SpecWeave increments
-- **Update Epics**: Sync progress, update status, add comments
+- **Update Epics**: Bidirectional sync of progress, status, comments
 - **Close Epics**: Close epics with completion summaries
 - **Link Epics**: Connect related epics, stories, and tasks
 - **Custom Fields**: Handle custom fields, labels, versions
 
-### 2. Story & Task Management
+### 3. Story & Task Management
 - **Create Stories**: Map SpecWeave specs to Jira Stories (PRD or RFC)
 - **Create Tasks**: Map SpecWeave tasks to Jira Tasks
-- **Update Status**: Real-time sync of task completion
+- **Update Status**: Bidirectional sync of task completion
 - **Subtasks**: Handle Jira subtasks and dependencies
 - **Bulk Operations**: Batch create/update stories and tasks
 
-### 3. Progress Tracking
-- **Sprint Progress**: Track epic progress within sprints
+### 4. Progress Tracking
+- **Sprint Progress**: Track epic progress within sprints (bidirectional)
 - **Story Points**: Calculate and update story points
-- **Status Updates**: Sync status changes bidirectionally
-- **Comments**: Post task completion comments
+- **Status Updates**: Bidirectional sync of status changes
+- **Comments**: Post task completion comments and import Jira comments
 - **Time Tracking**: Track estimated vs actual time
 
 ### 4. Jira API Operations

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

@@ -11,39 +11,60 @@ You are a Jira synchronization expert. Help the user sync between Jira and SpecW
 
 ### Epic-Level Operations
 
-**1. Import Jira Epic as SpecWeave Increment**
+**1. Bidirectional Sync (Default - Recommended)**
 ```
-/specweave:sync-jira import SCRUM-123
+/specweave-jira:sync 0003                    # Two-way sync (default)
+/specweave-jira:sync 0003 --direction bidirectional  # Explicit
 ```
 
-**2. Sync existing linked Increment with Jira**
+**2. Import Jira Epic as SpecWeave Increment**
 ```
-/specweave:sync-jira sync 0003
+/specweave-jira:sync import SCRUM-123        # One-time pull
+/specweave-jira:sync SCRUM-123 --direction from-jira  # Same as import
 ```
 
 **3. Export SpecWeave Increment to Jira**
 ```
-/specweave:sync-jira export 0001
+/specweave-jira:sync export 0001             # One-time push
+/specweave-jira:sync 0001 --direction to-jira  # Same as export
 ```
 
+### Sync Direction Options
+
+**Default: `bidirectional`** (two-way sync - recommended)
+
+- `--direction bidirectional`: SpecWeave ↔ Jira (default)
+  - Pull changes FROM Jira (status, priority, comments)
+  - Push changes TO Jira (tasks, progress, metadata)
+
+- `--direction to-jira`: SpecWeave → Jira only
+  - Push increment progress to Jira
+  - Don't pull Jira changes back
+  - Same as `export` operation
+
+- `--direction from-jira`: Jira → SpecWeave only
+  - Pull Jira issue updates
+  - Don't push SpecWeave changes
+  - Same as `import` operation
+
 ### Granular Item Operations
 
 **4. Add specific Story/Bug/Task to existing Increment**
 ```
-/specweave:sync-jira add SCRUM-1 to 0003
-/specweave:sync-jira add SCRUM-1              # Adds to current increment
+/specweave-jira:sync add SCRUM-1 to 0003
+/specweave-jira:sync add SCRUM-1              # Adds to current increment
 ```
 
 **5. Create Increment from specific items (cherry-pick)**
 ```
-/specweave:sync-jira create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7
-/specweave:sync-jira create "Bug Fixes Sprint 1" from SCRUM-10 SCRUM-15 SCRUM-20
+/specweave-jira:sync create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7
+/specweave-jira:sync create "Bug Fixes Sprint 1" from SCRUM-10 SCRUM-15 SCRUM-20
 ```
 
 **6. Show sync status**
 ```
-/specweave:sync-jira status
-/specweave:sync-jira status 0003              # Status of specific increment
+/specweave-jira:sync status
+/specweave-jira:sync status 0003              # Status of specific increment
 ```
 
 ## Your Task
@@ -154,19 +175,39 @@ When the user runs this command:
   | Task  | SCRUM-7  | Setup provider  |
   ```
 
-### Example 5: Sync Existing Increment
-**User**: `/specweave:sync-jira sync 0003`
+### Example 5: Bidirectional Sync (Default)
+**User**: `/specweave-jira:sync 0003`
 **You**:
 - Read increment 0003
 - Find linked Jira items (from spec.md frontmatter.work_items)
 - Fetch current state from Jira
-- Detect changes (status, priority, description)
-- Show conflicts if any
-- Apply sync bidirectionally
-- Display: "✅ Synced 0003 | Updated: 2 items | SCRUM-1 → in-progress, SCRUM-10 → completed"
+
+**Detect changes (both directions)**:
+- FROM Jira: Status changes, priority updates, comments
+- FROM SpecWeave: Task completion, progress updates
+
+**Show bidirectional sync summary**:
+```
+✅ Bidirectional Sync Complete: 0003 ↔ Jira
+
+FROM Jira:
+  • SCRUM-1: Status changed to In Progress
+  • SCRUM-10: Priority raised to P1
+
+FROM SpecWeave:
+  • 3 tasks completed (T-005, T-006, T-007)
+  • Progress: 60% → 75%
+
+Conflicts: None
+```
+
+**Handle conflicts if any**:
+- Show both versions (Jira vs SpecWeave)
+- Ask user which to keep or how to merge
+- Apply resolution bidirectionally
 
 ### Example 6: Status Overview
-**User**: `/specweave:sync-jira status`
+**User**: `/specweave-jira:sync status`
 **You**:
 - Scan all increments for Jira metadata
 - Show table:
@@ -188,10 +229,12 @@ When the user runs this command:
 
 ## Related Commands
 
-- `/specweave:sync-github` - Sync to GitHub issues
+- `/specweave-github:sync` - Sync to GitHub issues (also bidirectional 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.
+
 **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/jira-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jira-sync
-description: Sync SpecWeave increments with JIRA epics/stories. Activates for JIRA sync, create JIRA issue, import from JIRA, sync to JIRA. Coordinates with specweave-jira-mapper agent.
+description: Bidirectional sync between SpecWeave increments and JIRA epics/stories (two-way sync by default). Activates for JIRA sync, create JIRA issue, import from JIRA, sync to JIRA, bidirectional JIRA sync. Coordinates with specweave-jira-mapper agent.
 allowed-tools: Read, Write, Edit, Task, Bash
 ---
 
@@ -8,11 +8,13 @@ allowed-tools: Read, Write, Edit, Task, Bash
 
 Coordinates JIRA synchronization by delegating to `specweave-jira-mapper` agent.
 
+**Default Behavior**: **Bidirectional (two-way) sync** - Changes synchronized in both directions automatically
+
 ## Responsibilities
 
-1. Detect sync requests (export, import, bidirectional)
+1. Detect sync requests (bidirectional by default, or export/import if specified)
 2. Validate prerequisites (JIRA credentials, increment structure)
-3. Invoke `specweave-jira-mapper` agent
+3. Invoke `specweave-jira-mapper` agent with sync direction
 4. Handle errors gracefully
 
 ---

package/plugins/specweave/skills/translator/SKILL.md.bak

@@ -1,172 +0,0 @@
----
-name: translator
-description: LLM-native translation skill for SpecWeave content. Activates when translation is needed for CLI messages, templates, documentation, or living docs. Uses the current LLM session for zero-cost translation. Keywords: translate, translation, language, multilingual, i18n, internationalization, Russian, Spanish, Chinese, German, French, localization, translate to.
-allowed-tools: Read, Write, Edit, Grep, Glob
----
-
-# Translator Skill
-
-I am a translation specialist for SpecWeave content. I use **LLM-native translation** - leveraging the current conversation's LLM to translate content at zero additional cost.
-
-## Core Capabilities
-
-### 1. **In-Session Translation** (Zero Cost!)
-- Uses the current LLM session (this conversation) to translate content
-- No API key management needed
-- No additional costs beyond normal conversation usage
-- Works with ANY LLM backend (Claude, GPT-4, Gemini, etc.)
-
-### 2. **Context-Aware Translation**
-- Preserves markdown formatting
-- Keeps code blocks unchanged
-- Maintains SpecWeave framework terms in English (e.g., "increment", "spec.md", "tasks.md")
-- Keeps technical terms in English when appropriate (e.g., "TypeScript", "npm", "git")
-
-### 3. **Content Type Handling**
-- **CLI Messages**: Short prompts, error messages, success messages
-- **Templates**: CLAUDE.md, AGENTS.md, README.md templates
-- **Documentation**: User guides, architecture docs
-- **Living Docs**: Strategic documents, ADRs, RFCs
-
-## Supported Languages
-
-- 🇬🇧 English (en) - Default
-- 🇷🇺 Russian (ru) - Русский
-- 🇪🇸 Spanish (es) - Español
-- 🇨🇳 Chinese (zh) - 中文
-- 🇩🇪 German (de) - Deutsch
-- 🇫🇷 French (fr) - Français
-- 🇯🇵 Japanese (ja) - 日本語
-- 🇰🇷 Korean (ko) - 한국어
-- 🇧🇷 Portuguese (pt) - Português
-
-## When I Activate
-
-I auto-activate when you mention:
-- "Translate to [language]"
-- "Convert to [language]"
-- "Multilingual support"
-- "i18n" or "internationalization"
-- Specific language names (Russian, Spanish, Chinese, etc.)
-- "Localization" or "locale"
-
-## How to Use Me
-
-### Simple Translation
-
-```
-User: "Translate this error message to Russian: File not found"
-Me: "Файл не найден"
-```
-
-### Template Translation
-
-```
-User: "Translate the CLAUDE.md template to Spanish"
-Me: *Reads template, translates while preserving structure, writes back*
-```
-
-### Living Docs Translation
-
-```
-User: "Translate the PRD to German"
-Me: *Translates spec.md, preserves framework terms, maintains formatting*
-```
-
-## Translation Rules
-
-### ✅ **Always Translate**:
-- User-facing messages
-- Documentation prose
-- Instructions and explanations
-- Success/error messages
-
-### ⏸️ **Keep in English**:
-- Framework terms: "increment", "spec.md", "plan.md", "tasks.md", "COMPLETION-SUMMARY.md"
-- SpecWeave commands: "/specweave:inc", "/specweave:do", "/specweave:progress"
-- Technical terms: "TypeScript", "npm", "git", "API", "CLI"
-- File names and paths: `.specweave/`, `src/`, `CLAUDE.md`
-- Code blocks and examples
-
-### 🔧 **Context-Dependent**:
-- Variable names in code (usually keep English)
-- Comments in code (translate if requested)
-- Technical acronyms (HTTP, JSON, REST - keep English)
-
-## Example Translations
-
-### CLI Message (English → Russian)
-
-**English**: "✅ Increment created successfully! Next: Run /specweave:do to start implementation."
-
-**Russian**: "✅ Increment успешно создан! Далее: Запустите /specweave:do для начала реализации."
-
-**Note**: "Increment" kept in English (framework term), "/specweave:do" kept as-is (command)
-
-### Documentation (English → Spanish)
-
-**English**: 
-```markdown
-## Increment Lifecycle
-
-An increment is a complete feature with:
-- spec.md - WHAT and WHY
-- plan.md - HOW to implement
-- tasks.md - WORK to do
-```
-
-**Spanish**:
-```markdown
-## Ciclo de Vida del Increment
-
-Un increment es una funcionalidad completa con:
-- spec.md - QUÉ y POR QUÉ
-- plan.md - CÓMO implementar
-- tasks.md - TRABAJO a realizar
-```
-
-**Note**: "Increment", "spec.md", "plan.md", "tasks.md" kept in English (framework terms)
-
-## Quality Guidelines
-
-1. **Accuracy**: Translate meaning, not just words
-2. **Natural**: Sound like a native speaker wrote it
-3. **Consistency**: Use same terms throughout
-4. **Context**: Understand SpecWeave concepts before translating
-5. **Formatting**: Preserve markdown, code blocks, links
-
-## Workflow
-
-When you ask me to translate:
-
-1. **Detect Context**: What type of content is this?
-2. **Read Source**: If it's a file, I'll read it first
-3. **Apply Rules**: Follow translation rules above
-4. **Translate**: Use the current LLM session (this conversation)
-5. **Preserve Structure**: Maintain formatting, code blocks, etc.
-6. **Write Back**: If requested, save translated content
-
-## Limitations
-
-**What I DON'T Do**:
-- ❌ Use external translation APIs (everything is LLM-native)
-- ❌ Translate code itself (only comments/strings if requested)
-- ❌ Change framework structure or behavior
-- ❌ Translate incrementally (full content at once for consistency)
-
-**What I DO Best**:
-- ✅ Translate documentation and user-facing content
-- ✅ Maintain technical accuracy
-- ✅ Preserve SpecWeave conventions
-- ✅ Work with ANY LLM (Claude, GPT-4, Gemini, etc.)
-
-## Tips for Best Results
-
-1. **Be Specific**: "Translate CLAUDE.md to Russian" > "Translate this"
-2. **Provide Context**: Mention if it's CLI, docs, or living docs
-3. **Request Preservation**: "Keep framework terms in English" (I do this by default)
-4. **Batch Translate**: Give me multiple files at once for consistency
-
----
-
-**Remember**: I'm using the current LLM session for translation, so there are **zero additional costs** beyond the normal conversation. This is the power of LLM-native multilingual support!