specweave 1.0.593 → 2.0.0

package/plugins/COMMANDS-VS-SKILLS-ANALYSIS.md

@@ -1,182 +0,0 @@
-# Commands vs Skills: Complete Analysis
-
-> Analysis date: 2026-01-24
-> Based on official Claude Code documentation: https://code.claude.com/docs/en/skills
-
-## Executive Summary
-
-**CRITICAL FINDING**: Commands and skills are now **unified** in Claude Code 2.1.3+.
-
-From the official docs:
-> "Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way."
-
-## Current State Analysis
-
-### SpecWeave Plugin Structure
-
-| Plugin | Commands | Skills | Status |
-|--------|----------|--------|--------|
-| specweave (core) | 70 | 25+ | Hybrid |
-| specweave-ado | 11 | 1 | Command-heavy |
-| specweave-github | 10 | 1 | Command-heavy |
-| specweave-jira | 11 | 1 | Command-heavy |
-| specweave-testing | 7 | 1 | Command-heavy |
-| specweave-frontend | 4 | 1 | Command-heavy |
-| specweave-backend | 3 | 1 | Command-heavy |
-| specweave-payments | 4 | 1 | Command-heavy |
-| specweave-kubernetes | 3 | 1 | Command-heavy |
-| specweave-ml | 4 | 2 | Command-heavy |
-| specweave-mobile | 3 | 1 | Command-heavy |
-| specweave-release | 5 | 1 | Command-heavy |
-| specweave-diagrams | 1 | 1 | Balanced |
-| specweave-kafka | 4 | 1 | Command-heavy |
-| specweave-confluent | 3 | 1 | Command-heavy |
-| Other plugins | ~25 | ~5 | Command-heavy |
-| **TOTAL** | **~168** | **~45** | |
-
-### Agents Status
-
-**All 35 agents successfully converted to skills with `context: fork`**:
-- No `agents/` folders remain
-- All converted skills have proper frontmatter
-- All use `context: fork` for isolated execution
-- All have `allowed-tools:` defined
-
-## Official Claude Code Frontmatter Reference
-
-| Field | Purpose | When to Use |
-|-------|---------|-------------|
-| `name` | Display name / command name | Always (defaults to directory name) |
-| `description` | What it does + when to use | **Always** (used for auto-activation) |
-| `disable-model-invocation` | Prevent Claude auto-loading | **Side-effect commands** (deploy, sync, commit) |
-| `user-invocable` | Hide from `/` menu | Background knowledge only |
-| `allowed-tools` | Restrict tool access | Security/safety constraints |
-| `model` | Override model | Performance optimization |
-| `context` | Set to `fork` for subagent | Isolated execution needed |
-| `agent` | Subagent type | With `context: fork` |
-| `hooks` | Lifecycle hooks | Advanced workflows |
-| `argument-hint` | Autocomplete hint | Commands with arguments |
-
-## Invocation Control Matrix
-
-| Frontmatter | User Can Invoke | Claude Can Invoke | Context Loading |
-|-------------|-----------------|-------------------|-----------------|
-| (default) | Yes | Yes | Description always loaded |
-| `disable-model-invocation: true` | Yes | **No** | Description NOT loaded |
-| `user-invocable: false` | **No** | Yes | Description always loaded |
-
-## The Decision Framework
-
-### Should Commands Be Migrated to Skills?
-
-**Short answer: NO - Commands work fine as-is.**
-
-From the official docs:
-> "Your existing `.claude/commands/` files keep working."
-
-However, skills offer **optional benefits**:
-1. Supporting files (scripts/, templates/, examples/)
-2. More organized directory structure
-3. Official "recommended" pattern
-
-### When Commands Should STAY as Commands
-
-Commands with **side effects** that users should control:
-
-| Command Type | Example | Should Remain Command |
-|--------------|---------|----------------------|
-| Git operations | `sw:save`, `/commit` | ✅ Yes |
-| Deployment | `sw:deploy`, `sw:npm` | ✅ Yes |
-| External sync | `sw-github:sync`, `sw-jira:sync` | ✅ Yes |
-| State changes | `sw:do`, `sw:done`, `sw:auto` | ✅ Yes |
-| Destructive | `sw:abandon`, `sw:archive` | ✅ Yes |
-
-**Recommendation**: Add `disable-model-invocation: true` to critical commands.
-
-### When Commands COULD Be Skills (Auto-activate)
-
-Informational or reference commands:
-
-| Command Type | Example | Could Be Skill |
-|--------------|---------|----------------|
-| Status/info | `sw:status`, `sw:progress` | ⚠️ Maybe |
-| Quality checks | `sw:validate`, `sw:qa` | ⚠️ Maybe |
-| TDD guidance | `sw:tdd-cycle` | ⚠️ Maybe |
-
-**Note**: These are borderline - they're often invoked intentionally.
-
-## Final Recommendation
-
-### 1. DO NOT mass-migrate commands to skills
-
-**Reason**: 168 commands is significant effort, and commands work fine.
-
-### 2. Agent-to-Skill conversion was CORRECT
-
-All 35 agents with `context: fork` are the right pattern for:
-- Domain expertise (frontend, backend, payments, etc.)
-- Isolated execution
-- Auto-activation on keywords
-
-### 3. Add `disable-model-invocation: true` to critical commands
-
-Should be updated (HIGH PRIORITY):
-
-```yaml
-# Example: do.md should have
----
-name: sw:do
-description: Execute increment implementation...
-disable-model-invocation: true  # <-- ADD THIS
-hooks:
-  PostToolUse: ...
----
-```
-
-Commands to update:
-- `sw:do` - Executes tasks (major side effects)
-- `sw:done` - Closes increments
-- `sw:auto` - Autonomous mode
-- `sw:save` - Git commit
-- `sw:npm` - NPM publish
-- `sw-github:sync`, `sw-github:push` - GitHub sync
-- `sw-jira:sync`, `sw-jira:push` - JIRA sync
-- `sw-ado:sync`, `sw-ado:push` - ADO sync
-
-### 4. Skills with `context: fork` are for domain expertise
-
-Pattern confirmed correct:
-```yaml
----
-name: frontend-architect
-description: Frontend architecture expert. Activates for React, Vue...
-context: fork        # ← Isolated subagent
-model: opus
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-```
-
-## Migration Decision Matrix
-
-| Current | Migration Needed? | Action |
-|---------|------------------|--------|
-| `agents/*/AGENT.md` | ✅ **DONE** | Converted to skills with `context: fork` |
-| `commands/*.md` | ❌ No | Keep, optionally add `disable-model-invocation` |
-| `skills/*/SKILL.md` | ❌ No | Already correct format |
-
-## Conclusion
-
-1. **Agents → Skills**: ✅ Complete (35 converted)
-2. **Commands → Skills**: ❌ Not needed (commands work fine)
-3. **Commands need update**: Add `disable-model-invocation: true` to side-effect commands
-
-The current hybrid structure (commands + skills) is **valid and recommended**:
-- **Commands**: User-invocable workflows with side effects
-- **Skills**: Auto-activating domain expertise with isolated context
-
-## Official Documentation Links
-
-- Skills: https://code.claude.com/docs/en/skills
-- Subagents: https://code.claude.com/docs/en/sub-agents
-- Hooks: https://code.claude.com/docs/en/hooks
-- Plugins: https://code.claude.com/docs/en/plugins

package/plugins/FINAL-AUDIT-RECOMMENDATIONS.md

@@ -1,265 +0,0 @@
-# SpecWeave Plugin Audit - Final Recommendations
-
-> **Audit Date**: 2026-01-24
-> **Validator**: LLM-as-Judge (Opus 4.5)
-> **Scope**: All plugins, skills, commands, agents
-
----
-
-## Executive Summary
-
-| Category | Finding | Priority | Action |
-|----------|---------|----------|--------|
-| **Agents → Skills** | ✅ Complete | - | 35 agents converted |
-| **`tools:` → `allowed-tools:`** | ✅ Fixed | HIGH | 6 files corrected |
-| **`context: fork` misuse** | ⚠️ 25 skills incorrect | MEDIUM | Remove from reference skills |
-| **Commands → Skills migration** | ❌ Not recommended | - | Keep as commands |
-| **Duplicates** | ✅ None found | - | Commands & skills are complementary |
-| **Unused files** | ✅ 1 deprecated | LOW | Remove `github-manager` skill |
-
----
-
-## 1. Context Fork Analysis (CRITICAL)
-
-### The Rule
-
-**`context: fork` should ONLY be used for skills with explicit task instructions.**
-
-Per official Claude Code docs, `context: fork` spawns an isolated subagent. This is for:
-- ✅ **Explicit tasks**: "Build X", "Generate Y", "Create Z"
-- ❌ **NOT for**: Reference knowledge, documentation, patterns
-
-### Skills INCORRECTLY Using `context: fork` (25 files)
-
-These are **knowledge/reference** skills that provide patterns and best practices but don't execute explicit tasks:
-
-| Skill | Type | Recommendation |
-|-------|------|----------------|
-| `architect` | Reference/knowledge | Remove `context: fork` |
-| `pm` | Reference/knowledge | Remove `context: fork` |
-| `tech-lead` | Reference/knowledge | Remove `context: fork` |
-| `security` | Reference/knowledge | Remove `context: fork` |
-| `sre` | Reference/knowledge | Remove `context: fork` |
-| `devops` | Reference/knowledge | Remove `context: fork` |
-| `performance` | Reference/knowledge | Remove `context: fork` |
-| `observability-engineer` | Reference/knowledge | Remove `context: fork` |
-| `network-engineer` | Reference/knowledge | Remove `context: fork` |
-| `mobile-architect` | Reference/knowledge | Remove `context: fork` |
-| `kafka-architect` | Reference/knowledge | Remove `context: fork` |
-| `kubernetes-architect` | Reference/knowledge | Remove `context: fork` |
-| `frontend-architect` | Reference/knowledge | Remove `context: fork` |
-| `database-optimizer` | Reference/knowledge | Remove `context: fork` |
-| `diagrams` | Reference/knowledge | Remove `context: fork` |
-| `payment-integration` | Reference/knowledge | Remove `context: fork` |
-| `dotnet-backend` | Reference/knowledge | Remove `context: fork` |
-| `python-backend` | Reference/knowledge | Remove `context: fork` |
-| `nodejs-backend` | Reference/knowledge | Remove `context: fork` |
-| `ml-engineer` | Reference/knowledge | Remove `context: fork` |
-| `data-scientist` | Reference/knowledge | Remove `context: fork` |
-| `ado-mapper` | Reference/knowledge | Remove `context: fork` |
-| `jira-mapper` | Reference/knowledge | Remove `context: fork` |
-| `release-manager` | Reference/knowledge | Remove `context: fork` |
-| `github-manager` | DEPRECATED | Delete entirely |
-
-### Skills CORRECTLY Using `context: fork` (21 files)
-
-These have **explicit task instructions** (e.g., "create tests", "generate code"):
-
-| Skill | Has Explicit Task? | Keep `context: fork`? |
-|-------|-------------------|----------------------|
-| `qa-engineer` (testing) | ✅ "Creates test suites ONE FILE AT A TIME" | ✅ Keep |
-| `tech-lead` | ✅ "Implements code ONE FILE AT A TIME" | ✅ Keep |
-| `docs-writer` | ✅ "Generates docs ONE SECTION AT A TIME" | ✅ Keep |
-| `devops` (infra) | ✅ "Generates IaC ONE LAYER AT A TIME" | ✅ Keep |
-| `increment` | ✅ Creates increment structure | ✅ Keep |
-| `test-aware-planner` | Merged into sw-planner agent | ❌ Removed |
-| `tdd-cycle` | ✅ Coordinates TDD workflow | ✅ Keep |
-| (etc.) | | |
-
-### Fix Script
-
-```bash
-#!/bin/bash
-# Remove context: fork from reference skills
-
-files=(
-  "plugins/specweave/skills/architect/SKILL.md"
-  "plugins/specweave/skills/pm/SKILL.md"
-  "plugins/specweave/skills/security/SKILL.md"
-  # ... add remaining 22 files
-)
-
-for file in "${files[@]}"; do
-  if [ -f "$file" ]; then
-    sed -i '' '/^context: fork$/d' "$file"
-    echo "Fixed: $file"
-  fi
-done
-```
-
----
-
-## 2. Commands vs Skills Analysis
-
-### Key Finding: Commands Should NOT Be Migrated to Skills
-
-**Why not migrate?**
-
-1. **Context Bloat**: Skills auto-activate on keywords → large files load into context
-   - Commands: Only loaded when explicitly invoked
-   - Skills: Auto-load when keywords match (unpredictable context usage)
-
-2. **Side Effects**: Commands with side effects should require explicit invocation
-   - `sw:do` - Executes tasks (major changes)
-   - `sw:save` - Git commit/push
-   - `sw:npm` - NPM publish
-   - `sw:done` - Closes increments
-
-3. **Predictability**: Users expect commands to require explicit invocation
-   - Auto-activation for "deploy", "sync", "publish" would be dangerous
-
-4. **Official Docs Confirm**: Commands and skills are unified but serve different purposes
-   - Commands: User-triggered workflows
-   - Skills: Auto-activating expertise
-
-### Commands That Should Add `disable-model-invocation: true`
-
-Critical side-effect commands (prevents accidental auto-trigger):
-
-```yaml
-# Add to frontmatter of these commands:
-disable-model-invocation: true
-```
-
-| Command | Reason |
-|---------|--------|
-| `sw:do` | Executes tasks (major side effects) |
-| `sw:done` | Closes increments |
-| `sw:auto` | Autonomous execution mode |
-| `sw:save` | Git commit/push |
-| `sw:npm` | NPM publish |
-| `sw-github:sync` | GitHub sync |
-| `sw-github:push` | GitHub push |
-| `sw-jira:sync` | JIRA sync |
-| `sw-ado:sync` | ADO sync |
-
----
-
-## 3. Duplicate Analysis
-
-### Potential Duplicates Investigated
-
-| Command | Skill | Relationship | Verdict |
-|---------|-------|--------------|---------|
-| `reflect.md` | `reflect/SKILL.md` | **Complementary** | Command is workflow, skill is knowledge |
-| `translate.md` | `translator/SKILL.md` | **Complementary** | Command is batch workflow, skill is expertise |
-| `qa.md` | `testing:qa` | **Complementary** | Command runs CLI, skill creates tests |
-| `plan.md` | `increment/SKILL.md` | **Complementary** | Command for existing, skill for new increments |
-| `tdd-cycle.md` | `tdd-cycle/SKILL.md` | **Complementary** | Command starts workflow, skill orchestrates |
-
-### Conclusion: No True Duplicates Found
-
-Commands and skills serve different purposes:
-- **Commands**: User-invocable workflows with specific execution steps
-- **Skills**: Auto-activating expertise that provides patterns and knowledge
-
----
-
-## 4. Unused/Deprecated Files
-
-### Files to Remove
-
-| File | Reason | Action |
-|------|--------|--------|
-| `plugins/specweave-github/skills/github-manager/SKILL.md` | Deprecated - superseded by commands | Delete |
-
-### Files Already Cleaned
-
-- All 35 `agents/` folders successfully converted to skills
-- No orphan agent folders remain
-
----
-
-## 5. Frontmatter Fixes Applied
-
-### Issue: Incorrect `tools:` Field (FIXED)
-
-Per official docs, the correct field is `allowed-tools:`, not `tools:`.
-
-**Files fixed** (6 total):
-1. ✅ `specweave-diagrams/skills/diagrams/SKILL.md`
-2. ✅ `specweave-backend/skills/python-backend/SKILL.md`
-3. ✅ `specweave-backend/skills/nodejs-backend/SKILL.md`
-4. ✅ `specweave-backend/skills/dotnet-backend/SKILL.md`
-5. ✅ `specweave-ado/skills/ado-mapper/SKILL.md`
-6. ✅ `specweave-jira/skills/jira-mapper/SKILL.md`
-
----
-
-## 6. Context Bloat Considerations
-
-### Current State
-
-| Type | Count | Avg Size | Auto-Load? | Context Impact |
-|------|-------|----------|------------|----------------|
-| Commands | 168 | ~200 lines | No (explicit `/command`) | Low (predictable) |
-| Skills (fork) | 47 | ~400 lines | Yes (keywords) | Isolated (subagent) |
-| Skills (no fork) | ~60 | ~150 lines | Yes (keywords) | Medium (main context) |
-
-### Recommendations
-
-1. **Large reference skills** (>500 lines): Consider chunking or progressive disclosure
-2. **Skills with `context: fork`**: Safe - runs in isolated subagent
-3. **Commands**: Keep as commands - predictable context usage
-
----
-
-## 7. Final Recommendations
-
-### HIGH Priority
-
-1. ✅ **DONE**: Fix `tools:` → `allowed-tools:` (6 files)
-2. 🔄 **TODO**: Remove `context: fork` from 25 reference skills
-3. 🔄 **TODO**: Add `disable-model-invocation: true` to 9 critical commands
-
-### MEDIUM Priority
-
-4. 🔄 **TODO**: Delete deprecated `github-manager` skill
-5. 🔄 **TODO**: Consider chunking large skills (>500 lines) for context efficiency
-
-### LOW Priority
-
-6. ⏳ **OPTIONAL**: Add descriptions to all frontmatter for better auto-activation
-7. ⏳ **OPTIONAL**: Document skill vs command usage patterns in CLAUDE.md
-
----
-
-## 8. Metrics Summary
-
-| Metric | Before | After | Change |
-|--------|--------|-------|--------|
-| Agents | 35 | 0 | -35 (converted to skills) |
-| Skills (total) | 107 | 107 | 0 |
-| Skills with `context: fork` | 47 | 22 | -25 (pending fix) |
-| Commands | 168 | 168 | 0 |
-| Files with wrong frontmatter | 6 | 0 | -6 (fixed) |
-| Deprecated files | 1 | 0 | -1 (pending delete) |
-
----
-
-## 9. Validation Checklist
-
-- [x] All agents converted to skills
-- [x] All `tools:` → `allowed-tools:` fixed
-- [x] No duplicate commands/skills found
-- [x] Commands vs skills analysis complete
-- [x] Context bloat impact assessed
-- [ ] Remove `context: fork` from 25 reference skills
-- [ ] Add `disable-model-invocation: true` to critical commands
-- [ ] Delete deprecated `github-manager` skill
-
----
-
-**Overall Assessment**: The plugin ecosystem is well-structured. The agent-to-skill conversion was successful. Commands and skills are properly differentiated. Minor fixes needed for `context: fork` usage and command safety flags.
-
-**Grade**: A- (Excellent with minor fixes needed)