specweave 0.8.17 → 0.8.18

package/plugins/specweave/skills/plugin-expert/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: plugin-expert
+description: Expert knowledge of Claude Code's plugin system, marketplace management, and installation commands. Activates for plugin installation, marketplace setup, plugin troubleshooting, plugin commands. Keywords plugin install, plugin marketplace, claude code plugins, plugin management, plugin errors, marketplace add, plugin list.
+---
+
+# Plugin Expert - Claude Code Plugin System Authority
+
+**Purpose**: Authoritative source of truth for Claude Code's plugin system, marketplace management, and correct installation syntax.
+
+**When to Consult**: ANY time you need to install, manage, or reference Claude Code plugins.
+
+---
+
+## 🚨 CRITICAL: Correct Plugin Installation Format
+
+**ALWAYS use this format**:
+```bash
+/plugin install <plugin-name>
+```
+
+**Examples**:
+```bash
+# ✅ CORRECT
+/plugin install specweave-github
+/plugin install specweave-jira
+/plugin install specweave-kubernetes
+
+# ❌ WRONG - NEVER use @marketplace suffix
+/plugin install specweave-github@specweave
+/plugin install specweave-jira@specweave
+```
+
+**Why this matters**:
+- Claude Code automatically resolves plugins from registered marketplaces
+- The `@marketplace` syntax does NOT exist in Claude Code
+- Using wrong syntax causes installation failures
+
+---
+
+## Official Documentation
+
+**Primary Sources** (ALWAYS defer to these):
+1. **Plugin System**: https://code.claude.com/docs/en/plugins
+2. **Marketplaces**: https://code.claude.com/docs/en/plugin-marketplaces
+3. **Blog Post**: https://claude.com/blog/claude-code-plugins
+
+---
+
+## Plugin Commands Reference
+
+### Installation
+
+```bash
+# Install plugin from registered marketplace
+/plugin install <plugin-name>
+
+# Examples
+/plugin install specweave
+/plugin install specweave-github
+/plugin install specweave-jira
+```
+
+### Marketplace Management
+
+```bash
+# List all available marketplaces
+/plugin marketplace list
+
+# Add marketplace (GitHub)
+/plugin marketplace add <owner>/<repo>
+# Example: /plugin marketplace add anton-abyzov/specweave
+
+# Add marketplace (local directory - development only)
+/plugin marketplace add /path/to/.claude-plugin
+
+# Remove marketplace
+/plugin marketplace remove <marketplace-name>
+```
+
+### Plugin Management
+
+```bash
+# List installed plugins
+/plugin list --installed
+
+# List all available plugins from marketplaces
+/plugin list
+
+# Get plugin info
+/plugin info <plugin-name>
+
+# Uninstall plugin
+/plugin uninstall <plugin-name>
+
+# Update plugin
+/plugin update <plugin-name>
+```
+
+---
+
+## SpecWeave Marketplace Setup
+
+### User Projects (Production)
+
+SpecWeave automatically registers the GitHub marketplace during `specweave init`:
+
+**File**: `.claude/settings.json`
+```json
+{
+  "extraKnownMarketplaces": {
+    "specweave": {
+      "source": {
+        "source": "github",
+        "repo": "anton-abyzov/specweave",
+        "path": ".claude-plugin"
+      }
+    }
+  }
+}
+```
+
+**Result**: Claude Code fetches plugins from GitHub on-demand (no local copies)
+
+### SpecWeave Repo (Development)
+
+For contributors working on SpecWeave itself:
+
+```bash
+# Add local marketplace (CLI only - settings.json doesn't support local paths)
+/plugin marketplace add ./.claude-plugin
+
+# Then install plugins
+/plugin install specweave
+/plugin install specweave-github
+```
+
+---
+
+## Available SpecWeave Plugins
+
+### Core (Auto-Installed)
+
+- **specweave** - Framework essentials (increment planning, PM/Architect agents, living docs)
+  - Auto-installed during `specweave init`
+  - Provides: 9 skills, 22 agents, 22 commands, 8 hooks
+
+### Issue Trackers
+
+- **specweave-github** - GitHub Issues integration
+  - Install: `/plugin install specweave-github`
+  - Provides: GitHub sync, PR automation, issue tracking
+
+- **specweave-jira** - Jira integration
+  - Install: `/plugin install specweave-jira`
+  - Provides: Jira sync, epic management, sprint tracking
+
+- **specweave-ado** - Azure DevOps integration
+  - Install: `/plugin install specweave-ado`
+  - Provides: ADO work items, boards, sprints
+
+### Tech Stacks
+
+- **specweave-frontend** - React, Next.js, Vue, Angular
+  - Install: `/plugin install specweave-frontend`
+  - Provides: Frontend expert agent, component generation, design system integration
+
+- **specweave-kubernetes** - K8s, Helm, kubectl
+  - Install: `/plugin install specweave-kubernetes`
+  - Provides: K8s expert agent, Helm chart generation, deployment validation
+
+- **specweave-ml** - TensorFlow, PyTorch, ML workflows
+  - Install: `/plugin install specweave-ml`
+  - Provides: ML expert agent, training pipelines, model deployment
+
+### Utilities
+
+- **specweave-diagrams** - Mermaid + C4 diagrams
+  - Install: `/plugin install specweave-diagrams`
+  - Provides: Architecture diagram generation, C4 model support
+
+- **specweave-docs-preview** - Docusaurus documentation preview
+  - Install: `/plugin install specweave-docs-preview`
+  - Provides: Beautiful docs UI, hot reload, Mermaid rendering
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Wrong: Using @marketplace Syntax
+
+```bash
+# NEVER DO THIS
+/plugin install specweave-github@specweave
+/plugin install specweave-jira@specweave
+```
+
+**Why wrong**: Claude Code doesn't support `@marketplace` suffix
+
+**Correct**:
+```bash
+/plugin install specweave-github
+/plugin install specweave-jira
+```
+
+### ❌ Wrong: Using Local Paths in settings.json
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "specweave": {
+      "source": "./.claude-plugin"  // ❌ NOT supported
+    }
+  }
+}
+```
+
+**Why wrong**: `extraKnownMarketplaces` in settings.json only supports remote sources (GitHub, Git)
+
+**Correct for development**:
+```bash
+# Use CLI instead
+/plugin marketplace add ./.claude-plugin
+```
+
+### ❌ Wrong: Forgetting Marketplace Registration
+
+```bash
+# Install without marketplace registered
+/plugin install specweave-github  # ❌ Fails: marketplace not found
+```
+
+**Correct**:
+```bash
+# 1. Register marketplace first (or ensure settings.json has it)
+/plugin marketplace add anton-abyzov/specweave
+
+# 2. Then install plugins
+/plugin install specweave-github
+```
+
+---
+
+## Troubleshooting
+
+### "Marketplace not found" Error
+
+**Symptom**: `/plugin install specweave-xxx` fails with "marketplace not found"
+
+**Fix**:
+```bash
+# Check registered marketplaces
+/plugin marketplace list
+
+# If specweave not listed, add it
+/plugin marketplace add anton-abyzov/specweave
+
+# Then retry install
+/plugin install specweave-xxx
+```
+
+### Plugin Not Auto-Activating
+
+**Symptom**: Plugin installed but skills/agents not working
+
+**Causes**:
+1. Claude Code needs restart after plugin install
+2. Skill description keywords don't match user's context
+3. Plugin has errors (check plugin logs)
+
+**Fix**:
+```bash
+# 1. Verify plugin installed
+/plugin list --installed
+
+# 2. Restart Claude Code
+
+# 3. Check skill descriptions match your context
+```
+
+### Installation Hangs or Fails
+
+**Symptom**: `/plugin install` hangs or times out
+
+**Causes**:
+1. Network issues (GitHub fetch failed)
+2. Marketplace not registered
+3. Plugin doesn't exist in marketplace
+
+**Fix**:
+```bash
+# 1. Check marketplace registered
+/plugin marketplace list
+
+# 2. Verify plugin exists
+/plugin list  # Shows all available plugins
+
+# 3. Check network connectivity
+# Try re-adding marketplace (refreshes cache)
+/plugin marketplace remove specweave
+/plugin marketplace add anton-abyzov/specweave
+```
+
+---
+
+## How Other Skills Should Use This
+
+**Example: increment-planner skill recommending plugins**
+
+```markdown
+**Step 6: Detect Required Plugins**
+
+When recommending plugins, ALWAYS use correct format:
+
+✅ CORRECT:
+📦 Install recommended plugins:
+  /plugin install specweave-github
+  /plugin install specweave-kubernetes
+
+❌ WRONG:
+  /plugin install specweave-github@specweave  # NEVER use @marketplace
+```
+
+**Example: Auto-installation in TypeScript**
+
+```typescript
+// ✅ CORRECT
+execFileNoThrowSync('claude', ['plugin', 'install', 'specweave-github']);
+
+// ❌ WRONG
+execFileNoThrowSync('claude', ['plugin', 'install', 'specweave-github@specweave']);
+```
+
+---
+
+## References
+
+- **Official Docs**: https://code.claude.com/docs/en/plugins
+- **Marketplaces**: https://code.claude.com/docs/en/plugin-marketplaces
+- **Blog**: https://claude.com/blog/claude-code-plugins
+- **SpecWeave Marketplace**: https://github.com/anton-abyzov/specweave/.claude-plugin
+
+---
+
+**Last Updated**: 2025-01-06 (v0.8.18)

package/plugins/specweave/skills/specweave-framework/SKILL.md

@@ -367,8 +367,8 @@ SpecWeave plugins support **dual distribution**:
    - Works with ALL tools (Claude, Cursor, Copilot, Generic)
 
 2. **Claude Code Marketplace** (Native `/plugin`):
-   - `/plugin marketplace add specweave/marketplace`
-   - `/plugin install github@specweave`
+   - `/plugin marketplace add anton-abyzov/specweave`
+   - `/plugin install specweave-github`
    - Best UX for Claude Code users
 
 **Plugin Manifests** (both required):

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

@@ -8,6 +8,35 @@ allowed-tools: Read, Write, Edit, Grep, Glob
 
 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.
 
+## Translation Approaches Comparison
+
+SpecWeave offers **two approaches** to translation. Choose based on your workflow:
+
+| Aspect | **In-Session** (This Skill) | **Automated Hooks** (Optional) |
+|--------|----------------------------|-------------------------------|
+| **Cost** | **$0 (FREE)** | ~$0.003/increment |
+| **Model** | **Any** (Claude, GPT-4, Gemini, DeepSeek, etc.) | Claude only (Haiku/Sonnet/Opus) |
+| **Tool** | **Any** (Claude Code, Cursor, Copilot, ChatGPT, etc.) | Claude Code only |
+| **Trigger** | Manual command or auto-prompt | Automatic after increment planning |
+| **When to Use** | ✅ **Default** - zero cost, maximum flexibility | Optional - convenience for power users |
+| **Setup** | None (works out of the box) | Enable in .specweave/config.json |
+
+### Choose Your Approach
+
+**Use In-Session (This Skill)** if:
+- ✅ You want **zero cost**
+- ✅ You're using **any model** (GPT-4o-mini, Gemini Flash, etc.)
+- ✅ You're using **any tool** (Cursor, Copilot, ChatGPT, etc.)
+- ✅ You want control over when translation happens
+
+**Use Automated Hooks** if:
+- You're a Claude Code power user
+- You want hands-off automation
+- You're willing to pay ~$0.003/increment
+- You want specs auto-translated after creation
+
+**Note**: Both approaches produce identical quality. The primary difference is automation level and cost.
+
 ## Core Capabilities
 
 ### 1. **In-Session Translation** (Zero Cost!)

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

@@ -0,0 +1,172 @@
+---
+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!

package/src/templates/.gitignore.template

@@ -2,6 +2,7 @@
 .specweave/cache/
 .specweave/increments/*/logs/       # Gitignored, but structure preserved
 .specweave/increments/*/test-results/
+.specweave/docs-site-internal/      # Generated Docusaurus site for internal docs
 .claude-plugin/                     # Plugin marketplace (framework files)
 plugins/                            # Plugin implementations (framework files)