specweave 0.1.5 → 0.1.6

package/src/commands/README.md

@@ -0,0 +1,171 @@
+# SpecWeave Slash Commands
+
+This directory contains all slash commands for SpecWeave, including both full commands and short aliases.
+
+## Command Aliases
+
+SpecWeave provides short aliases for frequently used commands to speed up your workflow:
+
+| Full Command | Alias | Description |
+|--------------|-------|-------------|
+| `/create-project` | `/init` | Initialize new SpecWeave project |
+| `/create-increment` | `/ci` | Create new increment |
+| `/start-increment` | `/si` | Start working on increment |
+| `/add-tasks` | `/at` | Add tasks to increment |
+| `/validate-increment` | `/vi` | Validate increment quality |
+| `/close-increment` | `/done` | Close completed increment |
+| `/list-increments` | `/ls` | List all increments |
+
+## Usage
+
+### Full Commands (Explicit)
+
+Use full commands when:
+- ✅ Writing scripts or automation
+- ✅ Documentation and tutorials
+- ✅ Sharing commands with team members
+- ✅ Clarity is more important than speed
+
+**Example**:
+```bash
+/create-increment "User authentication with OAuth"
+/validate-increment 0001 --quality
+/close-increment 0001
+```
+
+### Aliases (Quick)
+
+Use aliases when:
+- ✅ Active development (speed matters)
+- ✅ Iterative workflow (creating/validating frequently)
+- ✅ Command-line muscle memory
+- ✅ Personal productivity
+
+**Example**:
+```bash
+/ci "User authentication with OAuth"
+/vi 0001 --quality
+/done 0001
+```
+
+## Typical Workflow
+
+**Using aliases for speed**:
+```bash
+# 1. Initialize project
+/init my-saas
+
+# 2. Create first increment
+/ci "User authentication"
+
+# 3. Start working
+/si 0001
+
+# 4. Add tasks as needed
+/at 0001 "Implement login endpoint"
+/at 0001 "Add password validation"
+
+# 5. Check progress
+/ls --status=in-progress
+
+# 6. Validate before closing
+/vi 0001 --quality
+
+# 7. Close when done
+/done 0001
+```
+
+**Using full commands for clarity**:
+```bash
+# Same workflow with explicit commands
+/create-project my-saas
+/create-increment "User authentication"
+/start-increment 0001
+/add-tasks 0001 "Implement login endpoint"
+/list-increments --status=in-progress
+/validate-increment 0001 --quality
+/close-increment 0001
+```
+
+## All Available Commands
+
+### Core Workflow Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/create-project` | `/init` | Bootstrap new SpecWeave project with auto-detection |
+| `/create-increment` | `/ci` | Create new increment with PM/Architect/QA planning |
+| `/start-increment` | `/si` | Start working on an increment (load context, create branch) |
+| `/add-tasks` | `/at` | Add tasks to existing increment |
+| `/validate-increment` | `/vi` | Validate increment (120 rules + optional LLM quality judge) |
+| `/close-increment` | `/done` | Close increment with leftover task handling |
+| `/list-increments` | `/ls` | List all increments with status and progress |
+
+### Documentation & Review Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/review-docs` | - | Review strategic docs vs implementation |
+| `/generate-docs` | - | Generate documentation site (Docusaurus/MkDocs) |
+
+### Integration Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/sync-github` | - | Sync increment to GitHub issues with subtasks |
+
+## Alias Design Philosophy
+
+**Why separate files instead of symlinks?**
+
+1. **Cross-platform compatibility** - Works on Windows, macOS, Linux, cloud IDEs
+2. **Clear documentation** - Each alias explains what it references
+3. **Consistent user experience** - Both commands work identically
+4. **Easy maintenance** - Update main command, aliases stay in sync via reference
+
+**Trade-off**: Slight content duplication, but improved UX and compatibility.
+
+## Creating Custom Aliases
+
+You can create your own project-specific aliases:
+
+**1. Create `.claude/commands/custom-alias.md`**:
+```markdown
+---
+description: Your custom command description
+---
+
+# Custom Alias
+
+This is a shorthand for `/some-long-command`.
+
+<!-- Paste full command content or reference it -->
+```
+
+**2. Use it**:
+```bash
+/custom-alias
+```
+
+## Installation
+
+Aliases are automatically installed when you:
+- Run `specweave init` (new projects)
+- Install SpecWeave as dependency (`npm install specweave --save-dev`)
+
+For manual installation:
+```bash
+npm run install:commands
+```
+
+## Documentation
+
+- **Command Reference**: See `.claude/commands/` for all available commands
+- **CLAUDE.md**: Quick reference table with all commands and aliases
+- **Official Docs**: https://spec-weave.com/docs/commands
+
+---
+
+**💡 Pro Tip**: Learn the aliases - they'll save you hundreds of keystrokes per day!
+
+**Most used**: `/ci`, `/si`, `/vi`, `/done`, `/ls`

package/src/commands/at.md

@@ -0,0 +1,114 @@
+---
+description: 🔥 Shorthand for /add-tasks - Add tasks to increment (Alias)
+---
+
+# Add Tasks (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/add-tasks`.
+
+Use this when you want to quickly add tasks to an increment without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/add-tasks`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/at <increment-id> <task-description>
+```
+
+**Examples**:
+```bash
+/at 0001 "Implement login endpoint"
+/at 0001 "Add password validation"
+/at 0001 "Write E2E tests for auth flow"
+```
+
+---
+
+## What This Does
+
+1. **Analyzes task** against spec/plan
+2. **Determines priority** (P1, P2, P3)
+3. **Estimates effort** (based on complexity)
+4. **Identifies dependencies** (from existing tasks)
+5. **Adds to tasks.md** with proper formatting
+6. **Updates progress** percentage
+
+---
+
+## Task Format
+
+Tasks are added with:
+- ✅ **Task ID** (auto-numbered: T001, T002, ...)
+- ✅ **Description** (clear, actionable)
+- ✅ **Priority** (P1/P2/P3)
+- ✅ **Estimated time** (based on analysis)
+- ✅ **Dependencies** (if any)
+- ✅ **Status** (Pending by default)
+
+**Example Output**:
+```markdown
+### T012: Implement login endpoint
+**Priority**: P1
+**Estimated**: 2 hours
+**Depends on**: T008
+**Status**: [ ] Pending
+
+**Implementation**:
+- Create POST /api/auth/login endpoint
+- Validate email and password
+- Return JWT token on success
+- Handle rate limiting
+```
+
+---
+
+## Bulk Add
+
+You can add multiple tasks by calling the command multiple times or providing a list:
+
+```bash
+/at 0001 "Task 1"
+/at 0001 "Task 2"
+/at 0001 "Task 3"
+```
+
+---
+
+## When to Add Tasks
+
+**During planning**:
+- Breaking down large features
+- After spec/plan review
+
+**During implementation**:
+- Discovered new requirements
+- Technical debt identified
+- Bug fixes needed
+
+**After review**:
+- Feedback from code review
+- QA findings
+- Security audit results
+
+---
+
+## Other Useful Aliases
+
+- `/ci` - Create increment (shorthand for `/create-increment`)
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/done` - Close increment (shorthand for `/close-increment`)
+- `/ls` - List increments (shorthand for `/list-increments`)
+
+---
+
+**💡 Tip**: Add tasks as you discover them - don't wait until sprint planning!

package/src/commands/ci.md

@@ -0,0 +1,63 @@
+---
+description: 🔥 Shorthand for /create-increment - Create new increment (Alias)
+---
+
+# Create Increment (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/create-increment`.
+
+Use this when you want to quickly create a new SpecWeave increment without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/create-increment`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/ci "Feature name"
+```
+
+**Example**:
+```bash
+/ci "User authentication"
+/ci "Payment processing"
+/ci "Admin dashboard"
+```
+
+---
+
+## What This Does
+
+1. **Auto-numbers** the increment (e.g., 0001, 0002, 0003...)
+2. **Creates folder** at `.specweave/increments/XXXX-feature-name/`
+3. **Generates files**:
+   - `spec.md` - WHAT & WHY (user stories, acceptance criteria)
+   - `plan.md` - HOW (architecture, implementation strategy)
+   - `tasks.md` - Implementation checklist
+   - `tests.md` - Test strategy and coverage matrix
+   - `context-manifest.yaml` - Context loading configuration
+4. **Invokes agents**:
+   - PM agent (requirements analysis)
+   - Architect agent (technical design)
+   - QA Lead agent (test strategy)
+
+---
+
+## Other Useful Aliases
+
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/done` - Close increment (shorthand for `/close-increment`)
+- `/ls` - List increments (shorthand for `/list-increments`)
+- `/at` - Add tasks (shorthand for `/add-tasks`)
+
+---
+
+**💡 Tip**: Use `/ci` for speed, `/create-increment` for clarity in scripts.

package/src/commands/done.md

@@ -0,0 +1,103 @@
+---
+description: 🔥 Shorthand for /close-increment - Close completed increment (Alias)
+---
+
+# Close Increment (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/close-increment`.
+
+Use this when you want to quickly close an increment without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/close-increment`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/done <increment-id>
+```
+
+**Examples**:
+```bash
+/done 0001
+/done 0042
+```
+
+---
+
+## What This Does
+
+1. **Validates completion**:
+   - ✅ All P1 tasks completed
+   - ✅ Tests passing
+   - ✅ Documentation updated
+   - ⚠️ Warns if incomplete
+
+2. **Handles leftover tasks**:
+   - Prompts to transfer incomplete tasks to new increment
+   - OR mark as deferred/cancelled
+   - Ensures no work is lost
+
+3. **Updates status** to `closed` in `tasks.md`
+
+4. **Archives increment** (if configured)
+
+5. **Suggests next steps**:
+   - Merge PR (if using git workflow)
+   - Deploy (if using CI/CD)
+   - Create release notes
+
+---
+
+## Before Closing Checklist
+
+**Required**:
+- [ ] All P1 tasks completed
+- [ ] Tests passing
+- [ ] Code reviewed
+- [ ] Documentation updated
+
+**Optional** (based on project):
+- [ ] Performance validated
+- [ ] Security reviewed
+- [ ] Accessibility tested
+- [ ] E2E tests passing
+
+---
+
+## Leftover Task Handling
+
+If you have incomplete tasks, you'll be prompted:
+
+```
+⚠️ Incomplete Tasks Found: 3
+
+Options:
+1. Transfer to new increment (recommended)
+2. Mark as deferred (with reason)
+3. Cancel tasks (not recommended)
+
+What would you like to do?
+```
+
+**Best Practice**: Transfer to new increment to maintain continuity.
+
+---
+
+## Other Useful Aliases
+
+- `/ci` - Create increment (shorthand for `/create-increment`)
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/ls` - List increments (shorthand for `/list-increments`)
+
+---
+
+**💡 Tip**: Always run `/vi --quality` before `/done` to ensure quality.

package/src/commands/init.md

@@ -0,0 +1,123 @@
+---
+description: 🔥 Shorthand for /create-project - Initialize SpecWeave project (Alias)
+---
+
+# Initialize Project (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/create-project`.
+
+Use this when you want to quickly initialize a new SpecWeave project without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/create-project`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/init [project-name] [--type=<stack>]
+```
+
+**Examples**:
+```bash
+/init                           # Interactive prompts
+/init my-saas                   # Auto-detect tech stack
+/init my-api --type=python      # Specify Python
+/init my-app --type=nextjs      # Specify Next.js
+```
+
+---
+
+## What This Does
+
+1. **Creates directory structure**:
+   ```
+   my-project/
+   ├── .specweave/
+   │   ├── config.yaml
+   │   ├── docs/
+   │   ├── increments/
+   │   └── tests/
+   ├── .claude/
+   │   ├── commands/
+   │   ├── skills/      # Auto-install on demand
+   │   └── agents/      # Auto-install on demand
+   ├── CLAUDE.md
+   └── README.md
+   ```
+
+2. **Detects tech stack** (or uses `--type` flag):
+   - TypeScript/JavaScript → Next.js, Node.js, React
+   - Python → FastAPI, Django, Flask
+   - Go → Gin, Echo, standard library
+   - .NET → ASP.NET Core
+   - Java → Spring Boot
+
+3. **Auto-installs components** based on your first request:
+   ```
+   User: "Create Next.js authentication"
+
+   📦 Installing required components...
+      ✅ nextjs skill
+      ✅ nodejs-backend skill
+      ✅ security agent
+      ✅ pm agent
+   ```
+
+4. **Initializes git** (if git available)
+
+5. **Shows next steps**
+
+---
+
+## Tech Stack Detection
+
+**Auto-detected from**:
+- `package.json` (JavaScript/TypeScript)
+- `requirements.txt`, `pyproject.toml` (Python)
+- `go.mod` (Go)
+- `*.csproj` (.NET)
+- `pom.xml`, `build.gradle` (Java)
+
+**Manual specification**:
+```bash
+/init --type=nextjs      # Next.js + TypeScript
+/init --type=python      # Python (FastAPI default)
+/init --type=django      # Django specifically
+/init --type=dotnet      # ASP.NET Core
+```
+
+---
+
+## After Initialization
+
+**Start building immediately**:
+```bash
+cd my-project
+/ci "User authentication"    # Create first increment
+```
+
+SpecWeave will:
+1. Detect you need auth components
+2. Auto-install: `security` agent, `nodejs-backend` skill
+3. Generate specs, plan, tasks
+4. Ready to implement!
+
+---
+
+## Other Useful Aliases
+
+- `/ci` - Create increment (shorthand for `/create-increment`)
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/ls` - List increments (shorthand for `/list-increments`)
+
+---
+
+**💡 Tip**: No need to pre-install components - they install on-demand!

package/src/commands/ls.md

@@ -0,0 +1,100 @@
+---
+description: 🔥 Shorthand for /list-increments - List all increments (Alias)
+---
+
+# List Increments (Short Alias)
+
+**⚡ Quick Alias**: This is a shorthand command for `/list-increments`.
+
+Use this when you want to quickly list increments without typing the full command name.
+
+---
+
+## Full Command
+
+For complete documentation, see `/list-increments`.
+
+This alias provides the exact same functionality as the full command.
+
+---
+
+## Usage
+
+```bash
+/ls [--status=<status>] [--format=<format>]
+```
+
+**Examples**:
+```bash
+/ls                          # All increments
+/ls --status=in-progress     # Only in-progress
+/ls --status=planned         # Only planned
+/ls --format=detailed        # Detailed view
+```
+
+---
+
+## What This Shows
+
+**Default View** (Summary):
+```
+📋 SpecWeave Increments
+
+Status: in-progress (2) | planned (3) | completed (5) | closed (4)
+
+In Progress:
+  0012-user-authentication     [████████░░] 80% (8/10 tasks)
+  0013-payment-integration     [███░░░░░░░] 30% (3/10 tasks)
+
+Planned:
+  0014-admin-dashboard         [░░░░░░░░░░]  0% (0/15 tasks)
+  0015-analytics-module        [░░░░░░░░░░]  0% (0/12 tasks)
+```
+
+**Detailed View** (`--format=detailed`):
+Shows full spec summary, architecture approach, test coverage, etc.
+
+---
+
+## Status Filters
+
+| Status | Description | Alias |
+|--------|-------------|-------|
+| `backlog` | Not yet planned | Ideas, proposals |
+| `planned` | Spec created, not started | Ready to work |
+| `in-progress` | Active work | Currently implementing |
+| `completed` | Tasks done, ready to close | Awaiting review/merge |
+| `closed` | Finished and archived | Done |
+
+---
+
+## Typical Usage
+
+**Quick check**:
+```bash
+/ls --status=in-progress     # What am I working on?
+```
+
+**Planning**:
+```bash
+/ls --status=planned         # What's next?
+```
+
+**Review**:
+```bash
+/ls --format=detailed        # Full increment overview
+```
+
+---
+
+## Other Useful Aliases
+
+- `/ci` - Create increment (shorthand for `/create-increment`)
+- `/si` - Start increment (shorthand for `/start-increment`)
+- `/vi` - Validate increment (shorthand for `/validate-increment`)
+- `/done` - Close increment (shorthand for `/close-increment`)
+- `/at` - Add tasks (shorthand for `/add-tasks`)
+
+---
+
+**💡 Tip**: Use `/ls` daily to track progress across all increments.