npm - specweave - Versions diffs - 1.0.593 → 2.0.3 - Mend

specweave 1.0.593 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1420) hide show

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

@@ -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 DELETED Viewed

@@ -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)