/help

description: >
  SpecWeave help and discovery. Shows available skills organized by workflow stage,
  usage statistics, and contextual next actions. Use when saying "help", "what can I do",
  "show commands", "what skills are available", "how do I use specweave",
  "getting started", "what's available", "list skills", or "specweave help".
  Do NOT activate for Claude Code's built-in /help command.
version: 1.0.0

sw:help — SpecWeave Discovery

You are showing the user what SpecWeave can do. Gather context first, then display organized help.

Step 1: Gather Context

Run these commands silently to understand the user's environment:

# Check if SpecWeave is initialized
INITIALIZED=$([ -d ".specweave" ] && echo "yes" || echo "no")

# Get active increments (if initialized)
STATUS_JSON=$(specweave status --json 2>/dev/null || echo '{"increments":[]}')

# Get usage stats (if initialized)
ANALYTICS_JSON=$(specweave analytics --since 30d --json 2>/dev/null || echo '{}')

# Parse flags
SHOW_DEPRECATED=$(echo "$ARGUMENTS" | grep -c -- "--deprecated" || echo "0")

# Load marketplace.json so deprecated skills can be filtered
MARKETPLACE_JSON=$(cat "$(specweave root 2>/dev/null)/plugins/specweave/marketplace.json" 2>/dev/null || echo '{"skills":[]}')

If any command fails, skip that section gracefully — never show errors to the user.

Deprecated skill filtering (v1.1.0+)

By default, `sw:help` **HIDES** skills with `"deprecated": true` in `plugins/specweave/marketplace.json` from the workflow-stage listing in Step 2 / Section C.

• Default invocation: `sw:help` → deprecated skills are **not listed**
• Opt-in invocation: `sw:help --deprecated` → deprecated skills are listed in a dedicated "DEPRECATED" section with their migration notes extracted from each SKILL.md

**Filtering logic**: 1. Parse `marketplace.json` to build the set of deprecated skill names: `deprecated = {s.name for s in marketplace.skills if s.deprecated == true}` 2. When rendering Section C (Skills by Workflow Stage), skip any skill whose name is in `deprecated` unless `--deprecated` was passed. 3. When `--deprecated` is passed, after Section C render an extra section:

   DEPRECATED — Scheduled for removal
     sw:github-sync       → Use sw-github:sync-spec (removal: v1.3.0)
     sw:jira-sync         → Use sw-jira:push / sw-jira:pull (removal: v1.3.0)
     sw:ado-sync          → Use sw-ado:push / sw-ado:pull (removal: v1.3.0)
     sw:tdd-red           → Use sw:tdd-cycle --phase red (removal: v1.3.0)
     sw:tdd-green         → Use sw:tdd-cycle --phase green (removal: v1.3.0)
     sw:tdd-refactor      → Use sw:tdd-cycle --phase refactor (removal: v1.3.0)
     sw:github-issue-standard → See .specweave/docs/internal/specs/github-issue-standard.md

4. Deprecated skills are still invokable directly (alias-routed in marketplace.json) — the filter only affects discovery listing, not invocation.

See `.specweave/docs/internal/specs/skill-deprecation-policy.md` for the full lifecycle policy.

Step 2: Display Help

If NOT initialized (no `.specweave/` directory)

Show getting started:

SPECWEAVE — Spec-Driven Development Tool

Get started in 3 steps:

  1. npm install -g specweave
  2. cd your-project && specweave init .
  3. Describe what you want to build — SpecWeave handles the rest

Docs: https://spec-weave.com/docs/getting-started

If initialized

Display the full help with these sections IN ORDER:

A. Stats Banner (if analytics data exists)

Parse the analytics JSON and show a one-line summary:

SPECWEAVE — [N] increments completed | [M] tasks done | [K] skills used (last 30 days)

If no analytics data, just show:

SPECWEAVE — Spec-Driven Development Tool

B. Active Increment Context (if any active increments)

Parse the status JSON. If active increments exist, show:

Active now:
  [ID] [title] — [progress]% ([completed]/[total] tasks)
  Next: sw:do [ID] (continue) | sw:progress (status) | sw:done [ID] (close)

C. Skills by Workflow Stage

Always show this section. Use a table format:

PLAN — Define what to build
  sw:increment     Plan a new feature, bug fix, or change
  sw:pm            Product Manager — write specs and requirements
  sw:architect     System Architect — design architecture and ADRs
  sw:brainstorm    Multi-perspective ideation with cognitive lenses
  sw:plan          Generate plan.md and tasks.md for an increment

IMPLEMENT — Build it
  sw:do            Execute tasks step by step
  sw:auto          Autonomous execution (unattended)
  sw:team-lead     Parallel multi-agent orchestration
  sw:tdd-cycle     Test-driven development (red-green-refactor; use --phase red|green|refactor for single phase)

VERIFY — Check quality
  sw:validate      130+ rule-based checks + AI quality assessment
  sw:grill         Critical code review before closure
  sw:judge-llm     Independent AI validation (ultrathink)
  sw:code-reviewer  6 parallel specialized reviewers
  sw:e2e           Playwright E2E tests traced to acceptance criteria
  sw:debug         Systematic 4-phase debugging with escalation

CLOSE — Ship it
  sw:done          Close increment with PM 3-gate validation
  sw:next          Close current and suggest next work
  sw:pr            Create pull request from increment branch

SYNC — Connect external tools
  sw:progress-sync  Sync progress to GitHub/JIRA/ADO
  sw:sync-setup     Configure GitHub, JIRA, or ADO integration
  sw:import         Import issues from external tools

EXPLORE — Understand your project
  sw:docs          Browse and search living docs
  sw:progress      Show increment progress and task completion
  sw:analytics     Usage statistics dashboard
  sw:doctor        Installation health diagnostics
  sw:diagrams      Generate Mermaid architecture diagrams

CREATE — Generate media
  sw:image         AI image generation (Gemini, Pollinations)
  sw:video         AI video generation (Veo 3.1, Pollinations)
  sw:diagra