specweave 0.6.7 → 0.7.0

package/src/templates/AGENTS.md.template

@@ -44,7 +44,7 @@ This is a **SpecWeave project** where specifications and documentation are the s
 .claude/                     # Claude Code components (if using Claude)
 ├── agents/                  # Specialized roles (PM, Architect, DevOps, etc.)
 ├── skills/                  # Capabilities (increment-planner, context-loader, etc.)
-└── commands/                # Slash commands (/inc, /do, /done)
+└── commands/                # Slash commands (/specweave:increment, /specweave:do, /specweave:done)
 
 plugins/                     # Optional plugins (extended capabilities)
 └── specweave-{name}/
@@ -205,6 +205,439 @@ cat plugins/specweave-github/commands/github-sync.md
 
 ---
 
+## 🚀 SpecWeave Commands (Executable Workflows)
+
+**⚡ CRITICAL FOR NON-CLAUDE TOOLS**: Commands are NOT automatic in GitHub Copilot, Cursor, or other tools. You MUST manually discover and execute them.
+
+### What Are Commands?
+
+Commands are **executable workflows** defined as `.md` files in `plugins/specweave/commands/`. Each file contains:
+- Command name (from filename, e.g., `specweave-increment.md` → `/specweave:increment`)
+- Complete workflow instructions
+- Parameters and usage examples
+- Step-by-step execution guide
+
+**Think of them as runnable scripts** - when user requests a command, you read the file and execute the workflow.
+
+### Command Discovery (MANDATORY!)
+
+**At the start of EVERY session**, discover available commands:
+
+```bash
+# List all core commands
+ls plugins/specweave/commands/
+
+# Common output:
+# specweave-increment.md  - Plan new increment (/specweave:increment "feature")
+# specweave-do.md         - Execute implementation (/specweave:do)
+# specweave-done.md       - Close increment (/specweave:done 0001)
+# specweave-validate.md   - Validate increment (/specweave:validate 0001)
+# specweave-progress.md   - Check status (/specweave:progress)
+# specweave-sync-docs.md  - Sync living docs (/specweave:sync-docs)
+# specweave-next.md       - Smart increment transition (/specweave:next)
+# specweave-costs.md      - Display AI cost dashboard (/specweave:costs)
+# specweave-translate.md  - Translate content (/specweave:translate)
+# tdd-*.md        - TDD workflow commands
+# ... (17 commands total)
+```
+
+**For plugin commands** (if plugins/ folder exists):
+
+```bash
+# List plugin commands
+ls plugins/specweave-github/commands/
+
+# Example output:
+# github-create-issue.md
+# github-sync.md
+# github-close-issue.md
+# github-status.md
+```
+
+### How to Execute Commands (Step-by-Step)
+
+**When user says**: "create new increment for user auth" or "run /specweave:increment user auth"
+
+**You should**:
+
+1. **Identify the command**:
+   - Keywords match: "create increment" → `specweave-increment.md`
+   - Explicit slash: "/specweave:increment" → `specweave-increment.md`
+   - Map request to command file
+
+2. **Read the command file**:
+   ```bash
+   cat plugins/specweave/commands/specweave-increment.md
+   ```
+
+3. **Parse the workflow**:
+   - Read YAML frontmatter for metadata
+   - Read markdown body for steps
+   - Note required parameters
+   - Understand expected output
+
+4. **Execute the workflow**:
+   - Follow instructions EXACTLY as written
+   - Use parameters from user request
+   - Reference related files (spec templates, etc.)
+   - Show progress as you work
+
+5. **Provide output**:
+   - Confirm completion
+   - Show created files
+   - Suggest next steps
+
+### Example: Executing /specweave:increment Command
+
+**User says**: "create new increment for user authentication"
+
+**Your workflow**:
+
+```bash
+# Step 1: Identify command
+# "create increment" → specweave-increment.md
+
+# Step 2: Read command file
+cat plugins/specweave/commands/specweave-increment.md
+```
+
+**After reading specweave-increment.md, you learn**:
+- This is PM-led increment planning
+- Requires: feature description
+- Creates: spec.md, plan.md, tasks.md, tests.md
+- Location: `.specweave/increments/####-feature-name/`
+
+**Step 3: Execute workflow from inc.md**:
+
+```markdown
+# You see these instructions in inc.md:
+
+1. **Detect tech stack** (TypeScript, Python, Go, etc.)
+2. **PM-led planning**:
+   - Market research
+   - Create spec.md (WHAT & WHY)
+   - Create plan.md (HOW)
+   - Auto-generate tasks.md from plan
+   - Create tests.md (test strategy)
+3. **Strategic agent review**:
+   - Architect designs system
+   - Security reviews threats
+   - QA defines test strategy
+4. **User review checkpoint**
+5. **Ready to build**
+```
+
+**Step 4: Execute those steps**:
+
+```
+📂 Creating increment 0001-user-authentication...
+
+🔍 Tech stack detected: TypeScript + Node.js + PostgreSQL
+
+👔 Adopting PM role to create spec.md...
+   ✓ Market research: Auth requirements
+   ✓ User stories: Login, Register, Password Reset
+   ✓ Acceptance criteria: TC-0001 to TC-0015
+   ✓ Created spec.md (WHAT & WHY, technology-agnostic)
+
+🏗️ Adopting Architect role to create plan.md...
+   ✓ Architecture: JWT + bcrypt + Prisma
+   ✓ API contracts: POST /auth/login, /auth/register
+   ✓ Data model: User table schema
+   ✓ Created plan.md (HOW, technology-specific)
+
+📋 Auto-generating tasks.md from plan.md...
+   ✓ Generated 42 tasks with model hints
+   ✓ Estimated: 3-4 weeks
+
+🧪 Creating tests.md (QA strategy)...
+   ✓ 12 test cases, 85% coverage target
+
+✅ Increment 0001-user-authentication ready!
+
+Next: /specweave:do (execute implementation)
+```
+
+**Step 5: Confirm completion**:
+
+```
+✅ Created increment 0001-user-authentication
+
+Files:
+  • .specweave/increments/0001-user-authentication/spec.md
+  • .specweave/increments/0001-user-authentication/plan.md
+  • .specweave/increments/0001-user-authentication/tasks.md
+  • .specweave/increments/0001-user-authentication/tests.md
+
+Next steps:
+  1. Review generated files
+  2. Run: /specweave:do (execute implementation)
+```
+
+### Core Command Reference
+
+**Most Common** (use these daily):
+
+| Command | File | Purpose | Example |
+|---------|------|---------|---------|
+| `/specweave:increment` | `specweave-increment.md` | Plan new increment | `/specweave:increment "user auth"` |
+| `/specweave:do` | `specweave-do.md` | Execute implementation | `/specweave:do` |
+| `/specweave:done` | `specweave-done.md` | Close increment | `/specweave:done 0001` |
+| `/specweave:validate` | `specweave-validate.md` | Validate quality | `/specweave:validate 0001` |
+| `/specweave:progress` | `specweave-progress.md` | Check status | `/specweave:progress` |
+
+**Specialized** (use when needed):
+
+| Command | File | Purpose | Example |
+|---------|------|---------|---------|
+| `/specweave:sync-docs` | `specweave-sync-docs.md` | Sync living docs | `/specweave:sync-docs update` |
+| `/specweave:next` | `specweave-next.md` | Smart increment transition | `/specweave:next` |
+| `/specweave:costs` | `specweave-costs.md` | AI cost dashboard | `/specweave:costs 0001` |
+| `/specweave:translate` | `specweave-translate.md` | Translate content | `/specweave:translate ru` |
+| `/specweave:tdd-cycle` | `specweave-tdd-cycle.md` | TDD workflow | `/specweave:tdd-cycle` |
+
+**Plugin Commands** (when plugins installed):
+
+| Command | File | Purpose | Plugin |
+|---------|------|---------|--------|
+| `/github:sync` | `plugins/specweave-github/commands/github-sync.md` | Sync to GitHub | specweave-github |
+| `/github:create-issue` | `plugins/specweave-github/commands/github-create-issue.md` | Create GitHub issue | specweave-github |
+| `/sync-tasks` | `commands/sync-tasks.md` | Sync tasks.md status | specweave (core) |
+
+---
+
+### 🚨 CRITICAL: Task Completion Tracking
+
+**Problem**: Commands like `/progress`, `/validate`, `/done` rely on `tasks.md` status being accurate.
+If tasks.md shows "1/24 complete" but you've actually finished 24 tasks, everything breaks!
+
+**Solution**: Update `tasks.md` after EACH task completes.
+
+#### For Claude Code Users (Automatic ✅)
+
+**Good news**: This happens automatically via `post-task-completion.sh` hook!
+
+When you complete a task (mark todo as done), the hook:
+1. ✅ Detects completion
+2. ✅ Updates corresponding task in tasks.md
+3. ✅ Recalculates progress %
+4. ✅ Syncs to GitHub issue (if enabled)
+
+**You don't need to do anything manually!**
+
+#### For Other AI Tools (Manual ⚠️)
+
+**⚠️ IMPORTANT**: After completing EACH task, manually update tasks.md:
+
+**Step-by-Step**:
+
+```bash
+# Example: You just completed T-001
+
+# 1. Open tasks.md
+vim .specweave/increments/0007-feature-name/tasks.md
+
+# 2. Find the task you completed
+#### T-001: Implement authentication service
+
+# 3. Change status from pending to completed
+**Status**: [ ] pending
+# ↓ Change to ↓
+**Status**: [x] completed
+
+# 4. Update progress counters at the top
+**Completed**: 0  # ← Increment this (0 → 1)
+**Progress**: 0%  # ← Recalculate (1/24 = 4%)
+
+# 5. Save and commit
+git add .specweave/increments/0007-feature-name/tasks.md
+git commit -m "chore: mark T-001 as complete"
+```
+
+**Why This Matters**:
+- `/progress` shows accurate completion % ✅
+- `/validate` checks pass ✅
+- `/done` can close the increment ✅
+- Team knows real status ✅
+
+**Validation Check**:
+```bash
+# Verify tasks.md is in sync
+/sync-tasks --validate
+
+# If out of sync:
+/sync-tasks  # Auto-fix from GitHub or git history
+```
+
+**Quick Reference Card** (print and keep handy):
+
+```
+┌────────────────────────────────────────────────┐
+│  AFTER EACH TASK: Update tasks.md Status      │
+├────────────────────────────────────────────────┤
+│  1. Open: .specweave/increments/XXXX/tasks.md │
+│  2. Find: #### T-XXX                           │
+│  3. Change: [ ] pending → [x] completed        │
+│  4. Update: Completed count & Progress %       │
+│  5. Commit: git commit -m "chore: mark done"   │
+└────────────────────────────────────────────────┘
+```
+
+---
+
+### Command Execution Pattern (Template)
+
+Use this pattern for ANY command execution:
+
+```bash
+# 1. User request
+# User: "sync to GitHub"
+
+# 2. Identify command
+# Keywords: "sync", "GitHub" → github-sync.md
+
+# 3. Read command file
+cat plugins/specweave-github/commands/github-sync.md
+
+# 4. Parse workflow
+# - Requires: increment ID, GitHub token
+# - Creates: GitHub issue
+# - Syncs: tasks, progress, labels
+
+# 5. Execute workflow
+# Follow steps in github-sync.md:
+#   - Load increment
+#   - Create/update GitHub issue
+#   - Sync task checklist
+#   - Add labels and milestone
+#   - Post comment with summary
+
+# 6. Confirm completion
+# "✅ Synced increment 0001 to GitHub issue #42"
+```
+
+### Why This Matters (Claude Code vs Other Tools)
+
+**Claude Code** (automatic):
+- Commands work via native slash syntax: `/inc "feature"`
+- No manual reading needed
+- Commands execute automatically
+
+**Other Tools** (manual):
+- ❌ No native command support
+- ✅ **Solution**: Read command .md file and execute workflow
+- Commands become "pseudo-executable" via this pattern
+- Same workflows, just manual discovery
+
+**GitHub Copilot Example**:
+
+```
+User: "create increment for payments"
+
+Copilot (you):
+1. Recognize command request: "create increment" → /inc
+2. Read: cat plugins/specweave/commands/inc.md
+3. Execute: Follow PM-led workflow from inc.md
+4. Create: spec.md, plan.md, tasks.md in .specweave/increments/0002-payments/
+5. Confirm: "✅ Increment 0002-payments created"
+
+User gets SAME result as Claude Code, just via manual execution!
+```
+
+### Command Discovery Checklist (Session Start)
+
+**MANDATORY for non-Claude tools**:
+
+```bash
+# 1. Discover core commands
+ls plugins/specweave/commands/
+# Note: 17 commands available (inc, do, done, validate, etc.)
+
+# 2. Check for plugin commands
+if [ -d "plugins/specweave-github" ]; then
+  ls plugins/specweave-github/commands/
+  # Note: 4 GitHub commands available
+fi
+
+# 3. Document available commands
+echo "Session Context:
+- Core commands: 17 available (inc, do, done, validate, ...)
+- Plugin commands: 4 GitHub commands (if plugin installed)
+- Command execution: Read .md file → Execute workflow
+"
+
+# 4. Ready to execute commands when requested
+```
+
+### Advanced: Batch Command Execution
+
+Some workflows require multiple commands:
+
+**Example**: Complete increment lifecycle
+
+```bash
+# User: "Plan, build, and close user auth feature"
+
+# Step 1: Execute /inc
+cat plugins/specweave/commands/inc.md
+# → Create spec.md, plan.md, tasks.md
+
+# Step 2: Execute /do
+cat plugins/specweave/commands/do.md
+# → Execute all 42 tasks
+
+# Step 3: Execute /validate
+cat plugins/specweave/commands/validate.md
+# → Quality checks
+
+# Step 4: Execute /done
+cat plugins/specweave/commands/done.md
+# → PM validation and closure
+```
+
+### Troubleshooting
+
+**Command file not found?**
+
+```bash
+# Check if command exists
+ls plugins/specweave/commands/ | grep inc
+# If not found, command doesn't exist
+
+# Check plugin commands
+ls plugins/specweave-*/commands/
+```
+
+**Command syntax unclear?**
+
+```bash
+# Read command README
+cat plugins/specweave/commands/README.md
+# Contains overview of all commands
+```
+
+**Command fails during execution?**
+
+- Re-read command file for missed steps
+- Check required files exist (spec.md, plan.md, etc.)
+- Verify parameters are correct
+- Check error messages for hints
+
+### Summary: Making Commands Work Without Claude Code
+
+**The Key Insight**: Commands are just markdown files with workflows!
+
+1. **Discover**: `ls plugins/specweave/commands/`
+2. **Read**: `cat plugins/specweave/commands/{command}.md`
+3. **Execute**: Follow the workflow in the file
+4. **Confirm**: Show completion and next steps
+
+**Result**: GitHub Copilot, Cursor, and other tools get the SAME SpecWeave command capabilities as Claude Code, just via manual execution instead of slash syntax.
+
+**This is CRITICAL** - without command execution, you're missing 90% of SpecWeave's automation!
+
+---
+
 ## Available Agents (Specialized Roles)
 
 SpecWeave uses role-based development. When working on tasks, adopt the appropriate role:
@@ -716,6 +1149,224 @@ Only **Claude Code** has automatic hooks that remind you to update docs.
 
 ---
 
+## 🔗 External Tracker Sync (CRITICAL FOR NON-CLAUDE TOOLS)
+
+**IMPORTANT**: Claude Code has automatic hooks that sync to external trackers (GitHub Issues, Jira, Azure DevOps) after each task completion. **GitHub Copilot, Cursor, and other tools DO NOT have these hooks!**
+
+### You MUST Manually Sync to External Trackers After Every Task
+
+When you complete ANY task, you MUST sync progress to external trackers if they are enabled for the project.
+
+#### Step 1: Detect Which Trackers Are Enabled
+
+Check the current increment's `metadata.json`:
+
+```bash
+# Find current increment (latest non-backlog increment)
+CURRENT_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog" | head -1)
+
+# Check metadata
+cat .specweave/increments/$CURRENT_INCREMENT/metadata.json
+```
+
+**Example metadata.json**:
+```json
+{
+  "id": "0007-smart-increment-discipline",
+  "title": "Increment Management v2.0",
+  "status": "active",
+  "github": {
+    "issue": 4,
+    "url": "https://github.com/anton-abyzov/specweave/issues/4"
+  },
+  "jira": {
+    "issue": "PROJ-123",
+    "url": "https://company.atlassian.net/browse/PROJ-123"
+  },
+  "ado": {
+    "item": 456,
+    "url": "https://dev.azure.com/org/project/_workitems/edit/456"
+  }
+}
+```
+
+#### Step 2: Sync to Each Enabled Tracker
+
+**For GitHub** (if `github.issue` exists):
+
+```bash
+# Get issue number
+GITHUB_ISSUE=$(jq -r '.github.issue' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
+
+# Post progress comment
+gh issue comment "$GITHUB_ISSUE" --body "Progress update: Task T-XXX completed in increment $CURRENT_INCREMENT
+
+Details:
+- Task: [Task description]
+- Status: Completed
+- Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+Next: [Next task or completion status]
+"
+```
+
+**For Jira** (if `jira.issue` exists):
+
+```bash
+# Get issue key
+JIRA_ISSUE=$(jq -r '.jira.issue' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
+
+# Add comment (requires jira CLI: https://github.com/ankitpokhrel/jira-cli)
+jira issue comment add "$JIRA_ISSUE" "Progress update: Task T-XXX completed
+
+Details:
+- Task: [Task description]
+- Status: Completed
+- Increment: $CURRENT_INCREMENT
+"
+
+# Update status if task is major milestone
+# jira issue move "$JIRA_ISSUE" "In Progress" / "Review" / "Done"
+```
+
+**For Azure DevOps** (if `ado.item` exists):
+
+```bash
+# Get work item ID
+ADO_ITEM=$(jq -r '.ado.item' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
+
+# Add comment (requires az CLI: https://aka.ms/azure-cli)
+az boards work-item update --id "$ADO_ITEM" --discussion "Progress update: Task T-XXX completed
+
+Details:
+- Task: [Task description]
+- Status: Completed
+- Increment: $CURRENT_INCREMENT
+"
+```
+
+#### Step 3: When to Sync
+
+**After EVERY task completion**, sync to all enabled trackers:
+
+```bash
+# Example workflow after completing T-003:
+
+# 1. Mark task complete in tasks.md
+vim .specweave/increments/0007-feature/tasks.md
+# Change: - [ ] T003: Task → - [x] T003: Task ✅
+
+# 2. Update increment documentation (plan.md, etc.)
+# [See "Documentation Updates" section above]
+
+# 3. Sync to external trackers
+gh issue comment 4 --body "✅ T-003 Complete: Create test-aware-planner structure
+
+Directory structure created at plugins/specweave/agents/test-aware-planner/
+
+Next: T-004 - Write test-aware-planner AGENT.md prompt
+"
+
+# 4. Continue to next task
+```
+
+#### Step 4: Update Task Checklist in GitHub/Jira
+
+**For GitHub Issues with task checklists**:
+
+The issue body likely contains a task checklist:
+
+```markdown
+## Tasks
+- [x] T-001: Update plan.md
+- [x] T-002: Add auto-sync hook
+- [ ] T-003: Create test-aware-planner structure
+- [ ] T-004: Write AGENT.md prompt
+```
+
+**Update the checklist** after each task:
+
+```bash
+# Get current issue body
+gh issue view 4 --json body -q .body > issue-body.md
+
+# Edit the checklist (mark T-003 as done)
+vim issue-body.md
+# Change: - [ ] T-003 → - [x] T-003
+
+# Update issue
+gh issue edit 4 --body-file issue-body.md
+```
+
+**For Jira** (subtasks):
+
+If tasks are represented as subtasks:
+
+```bash
+# List subtasks
+jira issue list --parent PROJ-123
+
+# Update subtask status
+jira issue move PROJ-123-SUB1 "Done"
+```
+
+#### Step 5: Sync Increment Status Changes
+
+When increment status changes (active → paused → completed), sync that too:
+
+```bash
+# Example: Increment completed
+gh issue comment 4 --body "🎉 INCREMENT COMPLETED!
+
+All 24 tasks finished. Increment 0007-smart-increment-discipline is now complete.
+
+See completion report: .specweave/increments/0007-smart-increment-discipline/reports/COMPLETION-SUMMARY.md
+"
+
+# Close the issue
+gh issue close 4 --comment "Increment completed and merged to main branch."
+```
+
+### Why This Matters
+
+**Without external tracker sync**:
+- ❌ Stakeholders don't see progress
+- ❌ Team members work in isolation
+- ❌ No audit trail of work done
+- ❌ GitHub/Jira becomes stale and useless
+
+**With external tracker sync**:
+- ✅ Real-time visibility into progress
+- ✅ Team stays informed
+- ✅ Stakeholders can track without asking
+- ✅ Complete audit trail
+- ✅ GitHub/Jira remains the source of truth
+
+### Tools That Need Manual Sync
+
+These tools **DO NOT** have automatic external tracker sync:
+- GitHub Copilot (all versions)
+- Cursor
+- Windsurf
+- Gemini CLI
+- Generic AI tools (ChatGPT, Claude web, etc.)
+
+Only **Claude Code** has automatic hooks (via `post-task-completion.sh`) that sync to external trackers.
+
+### Summary Checklist (After Every Task)
+
+When you complete a task in non-Claude tools:
+
+1. ✅ Mark task complete in tasks.md
+2. ✅ Update living docs (see "Documentation Updates" section)
+3. ✅ **Sync to GitHub/Jira/ADO** (this section)
+4. ✅ Update RFC if applicable (if task implements architecture decision)
+5. ✅ Continue to next task
+
+**Remember**: In Claude Code, steps 3-4 happen automatically via hooks. In other tools, YOU must do them manually!
+
+---
+
 ## Security Considerations
 
 - Never commit secrets (use `.env` files, gitignored)