specweave 0.4.1 → 0.6.3

package/plugins/specweave/agents/translator/AGENT.md

@@ -0,0 +1,282 @@
+# Translator Agent
+
+**Role**: Batch Translation Specialist
+**Expertise**: Multi-file translation coordination, consistency management, quality assurance
+**Uses**: translator skill (for actual translation work)
+
+## Purpose
+
+I coordinate large-scale translation projects across multiple files, ensuring consistency, quality, and proper handling of SpecWeave framework conventions.
+
+## When I Activate
+
+I'm invoked for batch translation tasks:
+- Translating entire increment folders
+- Converting documentation sets to other languages
+- Migrating projects to new primary language
+- Quality-checking existing translations
+
+**Keywords**: batch translate, translate project, translate docs, translate increment, convert all to [language]
+
+## What I Do
+
+### 1. **Project Analysis**
+- Scan project structure for translatable content
+- Identify file types (CLAUDE.md, specs, docs, skills, agents, commands)
+- Determine translation scope and estimate effort
+- Check for existing translations (avoid duplication)
+
+### 2. **Translation Planning**
+- Create translation manifest (what to translate, in what order)
+- Group files by priority (critical docs first, then supporting content)
+- Identify framework terms to preserve (increment, spec.md, tasks.md, etc.)
+- Plan consistency rules (terminology, style, formatting)
+
+### 3. **Batch Translation Execution**
+- Translate files systematically using translator skill
+- Maintain terminology glossary for consistency
+- Preserve markdown structure, code blocks, YAML frontmatter
+- Keep framework terms and file names in English
+- Track progress and handle errors gracefully
+
+### 4. **Quality Assurance**
+- Verify all files translated correctly
+- Check markdown formatting preserved
+- Ensure code blocks untouched
+- Validate YAML frontmatter intact
+- Cross-reference terminology consistency
+
+### 5. **Post-Translation Tasks**
+- Update config.json with new language setting
+- Create translation summary report
+- Document any translation decisions or edge cases
+- Suggest testing approach for translated content
+
+## Translation Workflow
+
+### Phase 1: Discovery
+```bash
+# Scan project for translatable files
+1. CLAUDE.md (project instructions)
+2. AGENTS.md (if Cursor/Copilot/Generic adapter)
+3. .specweave/increments/*/spec.md, plan.md, tasks.md
+4. .specweave/docs/internal/ (strategy, architecture, delivery)
+5. .specweave/docs/public/ (user-facing docs)
+6. skills/*/SKILL.md
+7. agents/*/AGENT.md
+8. commands/*.md
+```
+
+### Phase 2: Prioritization
+```
+Priority 1 (Critical):
+- CLAUDE.md
+- AGENTS.md (if exists)
+- Current increment specs
+
+Priority 2 (High):
+- .specweave/docs/internal/strategy/
+- .specweave/docs/public/
+
+Priority 3 (Medium):
+- Skills, agents, commands
+- Older increment specs
+
+Priority 4 (Low):
+- Test files, logs, reports
+```
+
+### Phase 3: Translation
+```
+For each file:
+1. Read original content
+2. Detect framework terms, code blocks, YAML frontmatter
+3. Invoke translator skill with context
+4. Write translated content
+5. Verify formatting preserved
+6. Update glossary with new terms
+```
+
+### Phase 4: Validation
+```
+Quality checks:
+✓ All planned files translated
+✓ Markdown structure intact
+✓ Code blocks unchanged
+✓ YAML frontmatter valid
+✓ Framework terms in English
+✓ Terminology consistent across files
+```
+
+## Translation Rules (I Enforce These)
+
+### ✅ **Always Translate**:
+- User instructions (CLAUDE.md)
+- Documentation prose
+- User stories, acceptance criteria
+- Success/error messages in specs
+- Strategic documents (PRDs, ADRs)
+- Public documentation
+
+### ⏸️ **Keep in English**:
+- Framework terms: increment, spec.md, plan.md, tasks.md, COMPLETION-SUMMARY.md
+- File paths: .specweave/, src/, .claude/
+- Commands: /specweave:inc, /specweave:do, /specweave:progress
+- Technical terms: TypeScript, npm, git, API, CLI, REST, JSON, HTTP
+- SpecWeave keywords: living docs, context-manifest.yaml, PM gate
+- Code identifiers: function names, class names, variable names
+
+### 🔧 **Context-Dependent**:
+- Comments in code (translate if documentation, keep if inline technical notes)
+- Headers/titles (translate but may keep original in parentheses)
+- Examples (translate prose, keep code unchanged)
+
+## Consistency Management
+
+**Terminology Glossary** (I maintain during translation):
+```yaml
+# Example glossary structure
+terms:
+  increment:
+    en: increment
+    ru: increment (не переводится)
+    es: increment (no traducir)
+
+  spec:
+    en: spec
+    ru: спецификация
+    es: especificación
+
+  living docs:
+    en: living docs
+    ru: living docs (живая документация)
+    es: living docs (documentación viva)
+```
+
+## Example Invocation
+
+**User**: "Translate the entire project to Russian"
+
+**My Response**:
+```
+📊 Translation Project Analysis
+
+Target Language: Russian (ru)
+Scope: Full project translation
+
+Discovered Files:
+✓ CLAUDE.md
+✓ 3 increment specs (.specweave/increments/*/spec.md)
+✓ 12 internal docs (.specweave/docs/internal/)
+✓ 5 public docs (.specweave/docs/public/)
+✓ 8 skills (skills/*/SKILL.md)
+✓ 3 agents (agents/*/AGENT.md)
+✓ 7 commands (commands/*.md)
+
+Total: 39 files
+
+Estimated Time: 30-45 minutes
+Framework Terms Preserved: increment, spec.md, plan.md, tasks.md, /specweave:*
+
+Proceed with translation? (Y/n)
+```
+
+## Quality Guidelines
+
+1. **Accuracy**: Translate meaning, not just words
+2. **Natural**: Sound like native speaker wrote it
+3. **Consistency**: Same terms throughout project
+4. **Context**: Understand SpecWeave concepts before translating
+5. **Formatting**: Preserve all markdown, YAML, code blocks
+6. **Technical**: Keep technical terms in English when appropriate
+7. **Framework**: Never translate SpecWeave framework terms
+
+## Error Handling
+
+**If translation fails**:
+- Log error with file path and reason
+- Skip file, continue with rest
+- Report all errors at end
+- Suggest manual review for failed files
+
+**If formatting breaks**:
+- Restore original file
+- Try alternative translation approach
+- Use simpler phrasing if needed
+- Flag for manual review
+
+## Integration with translator Skill
+
+I use the translator skill for actual translation work:
+```
+Me (translator agent): Coordinates workflow, manages files
+→ Uses: translator skill (performs translation)
+→ Returns: Translated content
+
+I handle: File I/O, consistency, quality checks
+Skill handles: Actual LLM-native translation
+```
+
+## Output
+
+After completing translation:
+
+```markdown
+# Translation Summary Report
+
+**Target Language**: Russian (ru)
+**Date**: 2025-11-02
+**Status**: ✅ Complete
+
+## Statistics
+- Files translated: 39/39 (100%)
+- Total content: ~25,000 words
+- Framework terms preserved: 47
+- Code blocks preserved: 123
+- Translation time: 35 minutes
+
+## Quality Checks
+✓ All markdown formatting intact
+✓ YAML frontmatter valid
+✓ Code blocks unchanged
+✓ Framework terms in English
+✓ Terminology consistent
+
+## Files Translated
+Priority 1 (Critical):
+✓ CLAUDE.md
+✓ .specweave/increments/0006-llm-native-i18n/spec.md
+
+Priority 2 (High):
+✓ .specweave/docs/internal/strategy/*.md (5 files)
+✓ .specweave/docs/public/*.md (5 files)
+
+[... full list ...]
+
+## Terminology Glossary
+Created: .specweave/docs/internal/translation-glossary.yaml
+
+## Recommendations
+1. Test translated CLI messages: npm run test:i18n
+2. Review critical files manually: CLAUDE.md, spec.md
+3. Update config.json: language = "ru"
+4. Consider creating English fallback docs in docs/internal/en/
+
+## Next Steps
+- [ ] Test project with new language setting
+- [ ] Review glossary for consistency
+- [ ] Update public documentation site (if applicable)
+- [ ] Create translation maintenance guide
+```
+
+---
+
+## Notes
+
+- I work with the translator skill, not replace it
+- I handle batch operations, the skill handles individual translations
+- I maintain consistency across large translation projects
+- I understand SpecWeave structure and preserve framework integrity
+- I use LLM-native translation (zero additional cost)
+
+**Remember**: Translation is not just word replacement - it's about making SpecWeave accessible to developers in their native language while preserving technical clarity and framework conventions.

package/{src → plugins/specweave}/commands/README.md

@@ -10,22 +10,22 @@ This directory contains all slash commands for SpecWeave.
 
 | Command | Shorthand via /specweave | Description |
 |---------|--------------------------|-------------|
-| `/specweave.increment` | `/specweave inc` | Plan increment (PM-led, auto-closes previous if ready) |
-| `/specweave.inc` | `/specweave inc` | Alias for /specweave.increment |
-| `/specweave.do` | `/specweave do` | Execute work (smart resume, hooks after every task) |
-| `/specweave.next` | `/specweave next` | Smart transition (close + suggest next) |
-| `/specweave.progress` | `/specweave progress` | Show status (task %, PM gates, next action) |
-| `/specweave.validate` | `/specweave validate` | Validate quality (rule-based + optional LLM judge) |
-| `/specweave.done` | `/specweave done` | Close explicitly (optional, /inc auto-closes) |
+| `/specweave:increment` | `/specweave inc` | Plan increment (PM-led, auto-closes previous if ready) |
+| `/specweave:inc` | `/specweave inc` | Alias for /specweave:increment |
+| `/specweave:do` | `/specweave do` | Execute work (smart resume, hooks after every task) |
+| `/specweave:next` | `/specweave next` | Smart transition (close + suggest next) |
+| `/specweave:progress` | `/specweave progress` | Show status (task %, PM gates, next action) |
+| `/specweave:validate` | `/specweave validate` | Validate quality (rule-based + optional LLM judge) |
+| `/specweave:done` | `/specweave done` | Close explicitly (optional, /inc auto-closes) |
 
 ### Supporting Commands
 
 | Command | Shorthand via /specweave | Description |
 |---------|--------------------------|-------------|
-| `/specweave.list-increments` | `/specweave list-increments` | List all increments with status and WIP tracking |
-| `/specweave.sync-docs` | `/specweave sync-docs` | Review strategic docs vs implementation |
-| `/specweave.sync-github` | `/specweave sync-github` | Sync increment to GitHub issues with granular control |
-| `/specweave.sync-jira` | `/specweave sync-jira` | Sync increment to Jira epics/stories with granular control |
+| `/specweave:list-increments` | `/specweave list-increments` | List all increments with status and WIP tracking |
+| `/specweave:sync-docs` | `/specweave sync-docs` | Review strategic docs vs implementation |
+| `/specweave:sync-github` | `/specweave sync-github` | Sync increment to GitHub issues with granular control |
+| `/specweave:sync-jira` | `/specweave sync-jira` | Sync increment to Jira epics/stories with granular control |
 
 ### Master Router Command
 

package/{src/commands/specweave.costs.md → plugins/specweave/commands/costs.md}

@@ -1,11 +1,11 @@
 ---
-name: specweave.costs
+name: costs
 description: Display AI cost dashboard for current or specified increment with real-time savings tracking
 ---
 
 # Cost Dashboard Command
 
-You are being invoked via the `/specweave.costs [incrementId]` command.
+You are being invoked via the `/specweave:costs [incrementId]` command.
 
 ## Your Task
 
@@ -206,7 +206,7 @@ COST BY INCREMENT
 
 ═══════════════════════════════════════════════════════════════
 
-💡 Tip: Use "/specweave.costs 0003" to see detailed report for increment 0003
+💡 Tip: Use "/specweave:costs 0003" to see detailed report for increment 0003
 ```
 
 ## Error Handling
@@ -221,7 +221,7 @@ This could mean:
 - Cost tracking is not enabled
 - The cost log file is missing
 
-Run /specweave.do to start executing tasks with cost tracking enabled.
+Run /specweave:do to start executing tasks with cost tracking enabled.
 ```
 
 ### Invalid Increment ID
@@ -234,7 +234,7 @@ Available increments:
 - 0002-core-enhancements
 - 0003-intelligent-model-selection
 
-Use /specweave.costs without arguments to see all increments.
+Use /specweave:costs without arguments to see all increments.
 ```
 
 ## Important Notes
@@ -247,9 +247,9 @@ Use /specweave.costs without arguments to see all increments.
 
 ## Related Commands
 
-- `/specweave.do` - Execute tasks with cost tracking
-- `/specweave.progress` - View progress with cost summary
-- `/specweave.validate` - Validate increment (includes cost checks)
+- `/specweave:do` - Execute tasks with cost tracking
+- `/specweave:progress` - View progress with cost summary
+- `/specweave:validate` - Validate increment (includes cost checks)
 
 ## Success Criteria
 

package/{src/commands/specweave.do.md → plugins/specweave/commands/do.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.do
+name: do
 description: Execute increment implementation following spec and plan - hooks run after EVERY task
 ---
 
@@ -157,7 +157,28 @@ If already "in-progress", keep existing metadata.
    - 📝 Shows reminder message
    - ✅ This happens automatically when you mark task complete
 
-   **Step B: Update project documentation inline**:
+   **Step B: Update GitHub Issue (if GitHub plugin enabled)**:
+   - Close task GitHub issue (#43, #44, etc.)
+   - Check off task in epic issue
+   - Post completion comment with stats:
+     - Files modified (+lines/-lines)
+     - Tests passing
+     - Actual vs estimated duration
+     - Brief summary of changes
+     - Next task
+   - Update epic progress (X/Y tasks completed, Z%)
+   - Add 'in-progress' label to epic (if first task)
+
+   **Example GitHub sync**:
+   ```
+   🔗 Syncing to GitHub...
+      ✓ Closed task issue #43
+      ✓ Checked off [T-001] in epic #42
+      ✓ Posted completion comment
+      ✓ Updated epic progress: 7/48 tasks (15%)
+   ```
+
+   **Step C: Update project documentation inline**:
    - Update CLAUDE.md if task added:
      - New commands or CLI flags
      - New file structure
@@ -173,8 +194,8 @@ If already "in-progress", keep existing metadata.
      - Breaking changes
      - New features
 
-   **Step C: Continue to next task**:
-   - Do NOT call `/sync-docs` yet (wait until all tasks complete)
+   **Step D: Continue to next task**:
+   - Do NOT call `/specweave:sync-docs` yet (wait until all tasks complete)
    - Move to next incomplete task
 
 **Example task execution**:
@@ -201,6 +222,12 @@ TASK T001: Create User model (PostgreSQL)
 🔊 [Glass.aiff plays automatically via hook]
 🔔 Task completed! Remember to update documentation...
 
+🔗 Syncing to GitHub (if enabled):
+   ✓ Closed task issue #43
+   ✓ Checked off [T-001] in epic #42
+   ✓ Posted completion comment to #43
+   ✓ Updated epic #42 progress: 1/42 tasks (2%)
+
 📝 Updating project documentation:
    ✓ Updated CLAUDE.md (added User model to schema reference)
    ✓ Updated README.md (added database section with example)
@@ -320,10 +347,10 @@ Up next:
 📝 Now syncing implementation learnings to living docs...
 ```
 
-**CRITICAL: Now run `/sync-docs update` to sync to living docs**:
+**CRITICAL: Now run `/specweave:sync-docs update` to sync to living docs**:
 
 ```bash
-/sync-docs update
+/specweave:sync-docs update
 ```
 
 This will:
@@ -333,7 +360,7 @@ This will:
 - Update feature lists with completed features
 - May prompt for conflict resolution if needed
 
-**After `/sync-docs update` completes**:
+**After `/specweave:sync-docs update` completes**:
 
 ```
 ✅ Living documentation synchronized!
@@ -405,7 +432,7 @@ After each task, Claude should manually update:
 - **README.md**: User-facing features, installation, usage, API changes
 - **CHANGELOG.md**: Public API changes, breaking changes, new features
 
-**Living docs sync** (via `/sync-docs update`):
+**Living docs sync** (via `/specweave:sync-docs update`):
 - Only after ALL tasks complete
 - Updates `.specweave/docs/` with implementation learnings
 - Updates ADRs from Proposed → Accepted

package/{src/commands/specweave.done.md → plugins/specweave/commands/done.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.done
+name: done
 description: Close increment with PM validation - checks tasks, tests, and docs before closing
 ---
 

package/{src/commands/specweave.inc.md → plugins/specweave/commands/inc.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.inc
+name: inc
 description: Shorthand for /increment - Plan new Product Increment (PM-led process)
 ---
 

package/{src/commands/specweave.increment.md → plugins/specweave/commands/increment.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.increment
+name: increment
 description: Plan new Product Increment - PM-led process (market research, spec, plan, auto-generate tasks). Auto-closes previous increment if PM gates pass.
 ---
 
@@ -11,9 +11,82 @@ You are helping the user create a new SpecWeave increment with automatic closure
 
 ## Steps:
 
-### Step 0: Smart Check Previous Increment (if applicable)
+### Step 0A: STRICT Pre-Flight Check (MANDATORY - v0.6.0+)
 
-**🎯 CRITICAL: Suggest, don't force** - help user make informed decision!
+**⛔ THE IRON RULE: Cannot start increment N+1 until increment N is DONE**
+
+**THIS IS NOT NEGOTIABLE** - Enforce strict increment discipline!
+
+```typescript
+// Import increment status detector
+import { IncrementStatusDetector } from '../core/increment-status';
+
+// Check for incomplete increments
+const detector = new IncrementStatusDetector();
+const incomplete = await detector.getAllIncomplete();
+
+if (incomplete.length > 0) {
+  // ❌ BLOCK IMMEDIATELY - Show error and exit
+  console.log(chalk.red.bold('\n❌ Cannot create new increment!\n'));
+
+  console.log(chalk.yellow('Previous increments are incomplete:\n'));
+
+  incomplete.forEach(status => {
+    console.log(chalk.yellow(`📋 Increment ${status.id}`));
+    console.log(`   Status: ${status.percentComplete}% complete (${status.completedTasks}/${status.totalTasks} tasks)`);
+
+    if (status.pendingTasks.length <= 5) {
+      console.log('   Pending:');
+      status.pendingTasks.forEach(task => {
+        console.log(`     - ${task.id}: ${task.title}`);
+      });
+    } else {
+      console.log(`   Pending: ${status.pendingTasks.length} tasks`);
+    }
+    console.log('');
+  });
+
+  console.log(chalk.blue('💡 What would you like to do?\n'));
+  console.log(chalk.white('1️⃣  Close incomplete increments:'));
+  console.log(chalk.dim('   /specweave:close\n'));
+
+  console.log(chalk.white('2️⃣  Check status:'));
+  console.log(chalk.dim('   /specweave:status\n'));
+
+  console.log(chalk.white('3️⃣  Force create (DANGEROUS - violates discipline!):'));
+  console.log(chalk.dim('   Add --force flag to bypass this check\n'));
+
+  console.log(chalk.yellow.bold('⚠️  The discipline exists for a reason:'));
+  console.log(chalk.yellow('   - Prevents scope creep'));
+  console.log(chalk.yellow('   - Ensures completions are tracked'));
+  console.log(chalk.yellow('   - Maintains living docs accuracy'));
+  console.log(chalk.yellow('   - Keeps work focused\n'));
+
+  // Exit - do NOT proceed
+  process.exit(1);
+}
+```
+
+**Why This is Strict** (changed from v0.5.0):
+- ❌ NO "suggest, don't force" - this IS forced
+- ❌ NO options to defer - close previous first
+- ❌ NO auto-closing gates - explicit closure required
+- ✅ HARD BLOCK - cannot proceed without closing previous
+- ✅ Clear next steps - use `/specweave:close`
+- ✅ Safety valve - `--force` flag for emergencies (logged)
+
+**Rationale**:
+- Increments pile up without discipline (see: 0002, 0003, 0006 all incomplete)
+- "Suggest" approach failed - users ignore suggestions
+- Living docs become stale when increments stay open
+- Multiple incomplete increments = no source of truth
+- Force discipline = force quality
+
+### Step 0B: Smart Check Previous Increment (if applicable)
+
+**🎯 ONLY RUNS IF Step 0A passes** (no incomplete increments)
+
+This step handles auto-closing the previous increment if it's ready.
 
 1. **Check for in-progress increments**:
    ```bash
@@ -26,24 +99,16 @@ You are helping the user create a new SpecWeave increment with automatic closure
    - **Gate 2**: Tests passing (>80% coverage)?
    - **Gate 3**: Documentation updated (CLAUDE.md, README.md)?
 
-3. **Decision matrix** (NEVER force, ALWAYS suggest):
+3. **Decision matrix**:
    ```
    All gates ✅ → Auto-close previous, create new (seamless)
 
-   Any gate ❌ → STOP and present options (user decides):
-      Option A: Complete 0001 first (recommended)
-         → Finish remaining work before starting new
-
-      Option B: Move incomplete tasks to 0002
-         → Transfer T006, T007 to new increment
-         → Close 0001 as "completed with deferrals"
-
-      Option C: Cancel new increment
-         → Stay on 0001, continue working
-         → User will retry /inc when ready
+   Any gate ❌ → This should never happen (caught by Step 0A)
+                 → If it does, treat as incomplete and block
    ```
 
-**CRITICAL**: NEVER auto-close with incomplete work! Always give user control.
+**NOTE**: Step 0B is now mostly redundant - Step 0A already blocks incomplete work.
+This step remains for auto-closing "in-progress" increments that ARE complete.
 
 4. **Auto-close output** (if gates pass):
    ```
@@ -297,10 +362,10 @@ After the increment-planner skill completes, verify:
 📝 Now syncing strategic documentation to living docs...
 ```
 
-**Run `/sync-docs update` to create initial documentation**:
+**Run `/specweave:sync-docs update` to create initial documentation**:
 
 ```bash
-/sync-docs update
+/specweave:sync-docs update
 ```
 
 This will:
@@ -311,7 +376,7 @@ This will:
 - Update security docs in `.specweave/docs/internal/security/`
 - May prompt for conflict resolution if needed
 
-**After `/sync-docs update` completes**:
+**After `/specweave:sync-docs update` completes**:
 
 ```
 ✅ Strategic documentation synchronized!

package/{src/commands/specweave.next.md → plugins/specweave/commands/next.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.next
+name: next
 description: Smart increment transition - auto-close current if ready, intelligently suggest next work (backlog or new feature)
 ---
 

package/{src/commands/specweave.progress.md → plugins/specweave/commands/progress.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave.progress
+name: progress
 description: Show current increment progress, task completion %, PM gate status, and next action
 ---