specweave 1.0.521 → 1.0.523

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -111,7 +111,30 @@ Skip increment pre-flight entirely. Brainstorm doesn't need a spec — it explor
 1. Create team: `TeamCreate({ team_name: "brainstorm-{slug}", description: "Brainstorm: {topic}" })`
 2. Read agent templates from `agents/brainstorm-advocate.md`, `agents/brainstorm-critic.md`, `agents/brainstorm-pragmatist.md`
 3. Replace `[BRAINSTORM_QUESTION]` with the user's question/topic
-4. Spawn all 3 agents in parallel via `Task()` with `mode: "bypassPermissions"`
+4. Spawn all 3 agents in parallel — each call MUST include `team_name` so agents join the team (and get tmux panes):
+   ```
+   Task({
+     team_name: "brainstorm-{slug}",
+     name: "brainstorm-advocate",
+     subagent_type: "general-purpose",
+     mode: "bypassPermissions",
+     prompt: <replaced brainstorm-advocate.md content>
+   })
+   Task({
+     team_name: "brainstorm-{slug}",
+     name: "brainstorm-critic",
+     subagent_type: "general-purpose",
+     mode: "bypassPermissions",
+     prompt: <replaced brainstorm-critic.md content>
+   })
+   Task({
+     team_name: "brainstorm-{slug}",
+     name: "brainstorm-pragmatist",
+     subagent_type: "general-purpose",
+     mode: "bypassPermissions",
+     prompt: <replaced brainstorm-pragmatist.md content>
+   })
+   ```
 5. **PASSIVE WAIT (CRITICAL)**: Do NOT apply §8b stuck detection to brainstorm agents.
    Brainstorm agents send `STATUS:` heartbeats (not task-granularity `T-{N}/{total}`).
    Wait patiently for `PERSPECTIVE_COMPLETE:` messages — expected 2-5 minutes per agent.
@@ -144,7 +167,23 @@ Planning mode runs PM and Architect agents in parallel for richer, faster spec c
 2. **Spawn PM + Architect in parallel** (TRUE parallelism):
    - Read `agents/pm.md`, replace `[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`, `[FEATURE_DESCRIPTION]`
    - Read `agents/architect.md`, replace `[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`
-   - **Spawn BOTH via `Task()` with `mode: "bypassPermissions"` in a single step**
+   - **Spawn BOTH in a single step — each call MUST include `team_name`:**
+     ```
+     Task({
+       team_name: "plan-{feature-slug}",
+       name: "pm-agent",
+       subagent_type: "general-purpose",
+       mode: "bypassPermissions",
+       prompt: <replaced pm.md content>
+     })
+     Task({
+       team_name: "plan-{feature-slug}",
+       name: "architect-agent",
+       subagent_type: "general-purpose",
+       mode: "bypassPermissions",
+       prompt: <replaced architect.md content>
+     })
+     ```
    - PM writes spec.md with user stories and ACs
    - Architect starts codebase exploration immediately (does NOT need spec.md for this)
    - Architect polls for spec.md, reads it when PM finishes, then designs architecture
@@ -196,7 +235,16 @@ Skip increment pre-flight. Research is exploratory — no spec needed.
    - Multi-faceted topic: spawn 2-3 researchers with different scopes
      (e.g., "research auth" → one agent on OAuth providers, one on session management, one on security best practices)
 3. Replace `[RESEARCH_TOPIC]` and `[RESEARCH_SCOPE]` in each agent prompt
-4. Spawn all researchers in parallel via `Task()` with `mode: "bypassPermissions"`
+4. Spawn all researchers in parallel — each call MUST include `team_name`:
+   ```
+   Task({
+     team_name: "research-{slug}",
+     name: "researcher-{scope}",
+     subagent_type: "general-purpose",
+     mode: "bypassPermissions",
+     prompt: <replaced researcher.md content>
+   })
+   ```
 5. Collect `RESEARCH_COMPLETE:` messages
 6. Merge findings into a unified research report:
    - Cross-reference findings between agents
@@ -223,7 +271,23 @@ Testing mode requires an increment (it needs to know WHAT to test).
    - **Unit test agent**: read `agents/testing.md`, override scope to unit tests only
    - **E2E test agent**: read `agents/testing.md`, override scope to E2E tests only
    - Split scope via the agent prompt, not via separate templates
-4. Spawn both in parallel via `Task()` with `mode: "bypassPermissions"`
+4. Spawn both in parallel — each call MUST include `team_name`:
+   ```
+   Task({
+     team_name: "test-{id}",
+     name: "unit-test-agent",
+     subagent_type: "general-purpose",
+     mode: "bypassPermissions",
+     prompt: <replaced testing.md content with unit-test scope>
+   })
+   Task({
+     team_name: "test-{id}",
+     name: "e2e-test-agent",
+     subagent_type: "general-purpose",
+     mode: "bypassPermissions",
+     prompt: <replaced testing.md content with e2e scope>
+   })
+   ```
 5. Collect `COMPLETION:` messages
 6. Run test suites to verify: `npx vitest run` + `npx playwright test`
 7. Report results: pass/fail counts, coverage, uncovered ACs

package/scripts/check-node-version.js

@@ -116,7 +116,7 @@ if (!isVersionSatisfied(CURRENT_NODE_VERSION, MIN_NODE_VERSION)) {
   console.error(getUpgradeInstructions());
   console.error('');
   console.error(`${BOLD}Full guide:${RESET}`);
-  console.error(`  ${CYAN}${UNDERLINE}https://verified-skill.com/docs/guides/troubleshooting/common-errors#node-version-error${RESET}`);
+  console.error(`  ${CYAN}${UNDERLINE}https://spec-weave.com/docs/guides/troubleshooting/common-errors#node-version-error${RESET}`);
   console.error('');
   console.error(`${DIM}After upgrading, run: npm install -g specweave${RESET}`);
   console.error('');

package/src/templates/AGENTS.md.template

@@ -57,13 +57,13 @@ Never mark a task complete without proving it works:
 - Code compiles/builds successfully
 - Run tests after every task: `npx vitest run` + `npx playwright test`
 - Review code quality before committing — check for duplication, readability issues, and inefficiencies (Claude Code: `/simplify`; other tools: manual review or linter)
-- `/sw:grill` writes `grill-report.json` — CLI blocks closure without it
-- `/sw:judge-llm` writes `judge-llm-report.json` — WAIVED if consent denied
+- `sw:grill` writes `grill-report.json` — CLI blocks closure without it
+- `sw:judge-llm` writes `judge-llm-report.json` — WAIVED if consent denied
 - Acceptance criteria actually satisfied
 
 ### 2b. Auto-Closure (MANDATORY)
 
-When ALL tasks are complete, IMMEDIATELY run `/sw:done` — do NOT stop to ask for user confirmation. Quality gates (grill, judge-llm, PM validation) ARE the review. If gates fail, the increment stays open. User can re-open if they disagree with closure.
+When ALL tasks are complete, IMMEDIATELY run `sw:done` — do NOT stop to ask for user confirmation. Quality gates (grill, judge-llm, PM validation) ARE the review. If gates fail, the increment stays open. User can re-open if they disagree with closure.
 
 ### 4. Large-Scale Changes
 
@@ -126,8 +126,8 @@ Good: npm run build → node script.js → Success
 
 ### Test Before Ship
 - Tests pass at every step — unit after each task, E2E before close, no exceptions
-- `/sw:increment` generates BDD test plans during design via the sw-planner agent — verify they exist before `/sw:do`
-- TDD cycle: `/sw:tdd-red` → `/sw:tdd-green` → `/sw:tdd-refactor`
+- `sw:increment` generates BDD test plans during design via the sw-planner agent — verify they exist before `sw:do`
+- TDD cycle: `sw:tdd-red` → `sw:tdd-green` → `sw:tdd-refactor`
 - E2E with Playwright CLI (`npx playwright test`) is a blocking closure gate
 <!-- /SECTION -->
 
@@ -136,20 +136,30 @@ Good: npm run build → node script.js → Success
 <!-- SECTION:commands required -->
 ## Commands Reference
 
+Commands are shown as `sw:<name>`. How you invoke them depends on your AI tool:
+
+| Tool | Invocation | Example |
+|------|-----------|---------|
+| **Claude Code** | Slash command | `/sw:do` |
+| **Cursor / Windsurf** | Type in chat | `sw:do` or describe the action |
+| **Copilot / ChatGPT** | Describe in chat | "Execute increment tasks" |
+| **Gemini CLI / Codex** | Reference in prompt | "Run sw:do on my increment" |
+| **Any tool** | SpecWeave CLI (where available) | `specweave validate 0001` |
+
 | Command | Purpose |
 |---------|---------|
-| `/sw:increment "name"` | Plan new feature (PM-led) |
-| `/sw:do` | Execute tasks from active increment |
-| `/sw:done 0001` | Close increment (validates gates) |
-| `/sw:progress` | Show task completion status |
-| `/sw:validate 0001` | Quality check before closing |
-| `/sw:progress-sync` | Sync tasks.md with reality |
-| `/sw:sync-docs update` | Sync to living docs |
-| `/sw-github:sync 0001` | Sync increment to GitHub issue |
-| `/sw-jira:sync 0001` | Sync to Jira |
-| `/sw-ado:sync 0001` | Sync to Azure DevOps |
-| `/sw:sync-setup` | Connect GitHub/Jira/ADO integration |
-| `/sw:import` | Import issues from external tools |
+| `sw:increment "name"` | Plan new feature (PM-led) |
+| `sw:do` | Execute tasks from active increment |
+| `sw:done 0001` | Close increment (validates gates) |
+| `sw:progress` | Show task completion status |
+| `sw:validate 0001` | Quality check before closing |
+| `sw:progress-sync` | Sync tasks.md with reality |
+| `sw:sync-docs update` | Sync to living docs |
+| `sw-github:sync 0001` | Sync increment to GitHub issue |
+| `sw-jira:sync 0001` | Sync to Jira |
+| `sw-ado:sync 0001` | Sync to Azure DevOps |
+| `sw:sync-setup` | Connect GitHub/Jira/ADO integration |
+| `sw:import` | Import issues from external tools |
 <!-- /SECTION -->
 
 ---
@@ -178,21 +188,21 @@ Claude Code has automatic hooks and orchestration. Other tools must do these man
 1. Update tasks.md: `[ ] pending` → `[x] completed`
 2. Update spec.md ACs if satisfied: `[ ] AC` → `[x] AC`
 3. Review code quality: check for duplication, readability, performance issues (Claude Code: `/simplify`)
-4. Run `/sw:progress-sync`
-5. Run `/sw-github:sync <id>` (if GitHub configured)
+4. Run `sw:progress-sync`
+5. Run `sw-github:sync <id>` (if GitHub configured)
 
 **After all ACs for a User Story are done:**
-- Run `/sw:sync-docs update`
+- Run `sw:sync-docs update`
 
 **After increment completion:**
-1. `/sw:validate <id>`
-2. `/sw:sync-docs update`
-3. `/sw-github:close-issue <id>`
+1. `sw:validate <id>`
+2. `sw:sync-docs update`
+3. `sw-github:close-issue <id>`
 
 **Session start:**
 1. `specweave jobs` (check background jobs)
-2. `/sw:progress` (check current state)
-3. `/sw:do` (continue work)
+2. `sw:progress` (check current state)
+3. `sw:do` (continue work)
 
 **Background jobs**: Monitor with `specweave jobs` (clone-repos, import-issues, living-docs-builder, sync-external).
 <!-- /SECTION -->
@@ -207,8 +217,8 @@ Claude Code has automatic hooks and orchestration. Other tools must do these man
 | Level | Location | Update Method |
 |-------|----------|---------------|
 | **Source** | tasks.md + spec.md | Edit directly |
-| **Derived** | .specweave/docs/internal/specs/ | `/sw:sync-docs update` |
-| **Mirror** | GitHub/Jira/ADO | `/sw-github:sync`, `/sw-jira:sync`, `/sw-ado:sync` |
+| **Derived** | .specweave/docs/internal/specs/ | `sw:sync-docs update` |
+| **Mirror** | GitHub/Jira/ADO | `sw-github:sync`, `sw-jira:sync`, `sw-ado:sync` |
 
 **Update order**: ALWAYS tasks.md/spec.md FIRST → progress-sync → sync-docs → external tools
 
@@ -216,12 +226,12 @@ Claude Code has automatic hooks and orchestration. Other tools must do these man
 
 | Command | When to Run |
 |---------|-------------|
-| `/sw:progress-sync` | After editing tasks.md |
-| `/sw:sync-docs update` | After US complete |
-| `/sw-github:sync <id>` | After each task |
-| `/sw-github:close-issue <id>` | On increment done |
-| `/sw-jira:sync <id>` | After each task |
-| `/sw-ado:sync <id>` | After each task |
+| `sw:progress-sync` | After editing tasks.md |
+| `sw:sync-docs update` | After US complete |
+| `sw-github:sync <id>` | After each task |
+| `sw-github:close-issue <id>` | On increment done |
+| `sw-jira:sync <id>` | After each task |
+| `sw-ado:sync <id>` | After each task |
 <!-- /SECTION -->
 
 ---
@@ -392,7 +402,7 @@ specweave context projects
 5. Create `tasks.md` (task checklist with BDD tests)
 6. Optional: `plan.md` for complex features
 7. **Verify** tasks.md has `**Test Plan**:` for every task with testable ACs
-8. **Verify** E2E scenarios exist for user-facing user stories — re-run `/sw:plan --force` if missing
+8. **Verify** E2E scenarios exist for user-facing user stories — re-run `sw:plan --force` if missing
 
 ### Completing Tasks
 1. Implement the task
@@ -408,8 +418,8 @@ specweave context projects
 ### Closing Increment (AUTO — do NOT stop to ask)
 1. Full test suite: `npx vitest run`
 2. Full E2E: `npx playwright test`
-3. `/sw:grill <id>` — writes `grill-report.json` (CLI requires it)
-4. `/sw:done <id>` — validates report files + PM 3 gates (tasks, tests, docs) + syncs to GitHub/Jira/ADO
+3. `sw:grill <id>` — writes `grill-report.json` (CLI requires it)
+4. `sw:done <id>` — validates report files + PM 3 gates (tasks, tests, docs) + syncs to GitHub/Jira/ADO
 
 **CRITICAL**: When all tasks are done, IMMEDIATELY chain to closure. Quality gates (grill, judge-llm, PM validation) ARE the review. Never stop to ask "should I close?" — just close it. If a gate fails, the increment stays open. User can re-open if they disagree.
 <!-- /SECTION -->
@@ -422,9 +432,9 @@ specweave context projects
 | Issue | Fix |
 |-------|-----|
 | Commands not working (non-Claude) | Read `plugins/specweave/commands/<name>.md`, follow manually |
-| GitHub/Jira not updating | `/sw:progress-sync` → `/sw:sync-docs update` → `/sw-github:sync <id>` |
+| GitHub/Jira not updating | `sw:progress-sync` → `sw:sync-docs update` → `sw-github:sync <id>` |
 | .md files in project root | `mv *.md .specweave/increments/<current>/reports/` |
-| Progress % wrong | Update tasks.md manually or `/sw:progress-sync` |
+| Progress % wrong | Update tasks.md manually or `sw:progress-sync` |
 | Tool crashes on start | Load only active increment's spec.md + tasks.md, not entire docs/ |
 | Missing **Project**: field | `specweave context projects`, add `**Project**:` to every US |
 | Skills not activating (non-Claude) | Expected — read SKILL.md from `plugins/specweave*/skills/` |

package/src/templates/CLAUDE.md.template

@@ -320,4 +320,6 @@ Pattern: IMPLEMENT → TEST → FAIL? → FIX → PASS → NEXT. STOP & ASK if s
 ## Using SpecWeave with Other AI Tools
 
 See **AGENTS.md** for Cursor, Copilot, Windsurf, Aider instructions.
+
+**Command format note**: This file uses `/sw:do` (Claude Code slash-command format). AGENTS.md uses `sw:do` (tool-agnostic format). Both refer to the same commands.
 <!-- /SECTION -->

package/src/templates/README.md.template

@@ -10,23 +10,25 @@ Your project is initialized! Now describe what you want to build.
 
 1. **Open your AI assistant** (Claude Code, Cursor, Windsurf, or any AI-powered IDE)
 
-2. **Use SpecWeave slash commands** to start building:
+2. **Use SpecWeave commands** to start building:
 
-```bash
+```
 # Plan a new feature
-/sw:increment "user authentication with JWT"
+sw:increment "user authentication with JWT"
 
 # Execute the implementation
-/sw:do
+sw:do
 
 # Check progress
-/sw:progress
+sw:progress
 
 # Close when done
-/sw:done 0001
+sw:done 0001
 ```
 
-3. **Or describe your project** in natural language (works with slash command workflows):
+> **Invocation varies by tool**: Claude Code uses `/sw:do`, Cursor/Copilot users type `sw:do` or describe the action. See AGENTS.md for details.
+
+3. **Or describe your project** in natural language (works with command workflows):
 
 ```
 "Build a real estate listing platform with search, images, and admin dashboard"
@@ -42,7 +44,7 @@ Your project is initialized! Now describe what you want to build.
    - Guide implementation
    - Generate tests
 
-That's it! All components ready - just use `/sw:increment` to start!
+That's it! All components ready - just use `sw:increment` to start!
 
 ---
 
@@ -52,7 +54,7 @@ That's it! All components ready - just use `/sw:increment` to start!
 {{PROJECT_NAME}}/
 ├── .specweave/             # SpecWeave framework
 │   ├── config.json         # Project configuration
-│   ├── increments/         # Features (created via /sw:increment)
+│   ├── increments/         # Features (created via sw:increment)
 │   │   └── 0001-feature/
 │   │       ├── spec.md     # WHAT & WHY
 │   │       ├── plan.md     # HOW
@@ -71,7 +73,7 @@ That's it! All components ready - just use `/sw:increment` to start!
 
 SpecWeave is a specification-first development framework where:
 - **Specifications are the source of truth** (code follows specs, not reverse)
-- **Slash commands drive workflow** (`/sw:increment` → `/sw:do` → `/sw:done`)
+- **Commands drive workflow** (`sw:increment` → `sw:do` → `sw:done`)
 - **AI agents work autonomously** (PM, Architect, Security, QA, DevOps)
 - **Works with ANY tech stack** (TypeScript, Python, Go, Rust, Java, .NET, etc.)
 - **Works with multiple AI assistants** (Claude Code, Cursor, Windsurf, etc.)
@@ -81,20 +83,20 @@ SpecWeave is a specification-first development framework where:
 ## Core Workflow
 
 ```
-/sw:increment "feature" → /sw:do → /sw:progress → /sw:done → repeat
+sw:increment "feature" → sw:do → sw:progress → sw:done → repeat
 ```
 
 | Command | Purpose | When to Use |
 |---------|---------|-------------|
-| `/sw:increment "feature"` | Plan new increment | Starting new feature |
-| `/sw:do` | Execute tasks | Ready to implement |
-| `/sw:progress` | Check status | Want to see progress |
-| `/sw:validate 0001` | Validate quality | Before completion |
-| `/sw:done 0001` | Close increment | Feature finished |
-| `/sw:team-lead "feature"` | Parallel agents | Complex multi-domain features |
-| `/sw:progress-sync` | Sync to external tools | Export to GitHub/JIRA/ADO |
+| `sw:increment "feature"` | Plan new increment | Starting new feature |
+| `sw:do` | Execute tasks | Ready to implement |
+| `sw:progress` | Check status | Want to see progress |
+| `sw:validate 0001` | Validate quality | Before completion |
+| `sw:done 0001` | Close increment | Feature finished |
+| `sw:team-lead "feature"` | Parallel agents | Complex multi-domain features |
+| `sw:progress-sync` | Sync to external tools | Export to GitHub/JIRA/ADO |
 
-For complex features spanning frontend, backend, and database — `/sw:team-lead` splits work across parallel agents for faster delivery. [Learn more](https://verified-skill.com/docs/guides/agent-teams-and-swarms).
+For complex features spanning frontend, backend, and database — `sw:team-lead` splits work across parallel agents for faster delivery. [Learn more](https://verified-skill.com/docs/guides/agent-teams-and-swarms).
 
 See `CLAUDE.md` for complete workflow guide.
 
@@ -121,10 +123,10 @@ project-root/
 ## AI Assistant Compatibility
 
 SpecWeave works with:
-- **Claude Code** (recommended) - Full slash command support
-- **Cursor** - Slash commands via composer
+- **Claude Code** (recommended) - Full command support with auto-activation
+- **Cursor** - Commands via composer
 - **Windsurf** - Cascade mode compatible
-- **Any AI IDE** - As long as it supports slash commands or custom prompts
+- **Any AI IDE** - Supports commands via prompts or native integrations
 
 **Setup**: See `CLAUDE.md` for AI assistant instructions.
 
@@ -142,7 +144,7 @@ SpecWeave works with:
 
 **Start with your first feature**:
 ```bash
-/sw:increment "describe your feature here"
+sw:increment "describe your feature here"
 ```
 
 Or just describe what you want to build, and SpecWeave will guide you through the process!

package/src/templates/lsp-plugin/plugin.json

@@ -4,7 +4,7 @@
   "description": "Auto-configured LSP servers for code intelligence (go-to-definition, find-references, hover)",
   "author": {
     "name": "SpecWeave",
-    "url": "https://verified-skill.com"
+    "url": "https://spec-weave.com"
   },
   "keywords": ["lsp", "typescript", "python", "code-intelligence"]
 }

package/src/templates/tasks.md.template

@@ -159,10 +159,10 @@ Before closing this increment, the following MUST be true:
 **Validation commands**:
 ```bash
 # Check AC coverage and task linkage
-/sw:validate {{INCREMENT_ID}}
+sw:validate {{INCREMENT_ID}}
 
 # Close increment (validates automatically)
-/sw:done {{INCREMENT_ID}}
+sw:done {{INCREMENT_ID}}
 ```
 
 ---