specweave 0.1.8 → 0.3.0

package/src/agents/devops/AGENT.md

@@ -47,23 +47,21 @@ This guide contains:
 
 ## 🌍 Environment Configuration (READ FIRST)
 
-**CRITICAL**: Before deploying ANY infrastructure, read the user's environment configuration from `.specweave/config.yaml`.
+**CRITICAL**: Before deploying ANY infrastructure, detect the deployment environment using auto-detection or prompt the user.
 
 ### Environment Detection Workflow
 
-**Step 1: Check if Environment Config Exists**
+**Step 1: Auto-Detect Environment**
 
 ```bash
-# Check for environment configuration
-if [ -f .specweave/config.yaml ]; then
-  # Parse environment definitions
-  # Use yq or similar YAML parser
-fi
+# Auto-detect from environment variables or project structure
+# Check for: .env files, deployment configs, cloud provider CLIs
+# Prompt user if multiple options detected
 ```
 
-**Step 2: Read Environment Strategy**
+**Step 2: Determine Environment Strategy**
 
-Load and parse `.specweave/config.yaml`:
+Environment configuration auto-detected or prompted:
 
 ```yaml
 # Example config structure
@@ -158,7 +156,7 @@ terraform {
 locals {
   environment = "staging"
 
-  # From .specweave/config.yaml environments.definitions[name=staging]
+  # From environment detection or user prompt
   deployment_provider = "hetzner"
   deployment_region   = "eu-central"
   requires_approval   = false
@@ -204,7 +202,7 @@ terraform {
 locals {
   environment = "production"
 
-  # From .specweave/config.yaml environments.definitions[name=production]
+  # From environment detection or user prompt
   deployment_provider = "hetzner"
   deployment_region   = "eu-central"
   requires_approval   = true
@@ -246,7 +244,7 @@ on:
     branches: [develop]
 
 env:
-  ENVIRONMENT: staging  # ← From config.yaml
+  ENVIRONMENT: staging  # ← From environment detection
 
 jobs:
   deploy:
@@ -273,12 +271,12 @@ on:
   workflow_dispatch:  # Manual trigger only
 
 env:
-  ENVIRONMENT: production  # ← From config.yaml
+  ENVIRONMENT: production  # ← From environment detection
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    environment: production  # Requires approval (from config.yaml)
+    environment: production  # Requires approval (from environment settings)
 
     steps:
       - uses: actions/checkout@v4
@@ -303,8 +301,8 @@ jobs:
 
 I see you want to deploy, but I need to know your environment setup first.
 
-Current environments in .specweave/config.yaml:
-- None found (config not set up)
+Current environments detected:
+- None found (not configured)
 
 How many environments will you need?
 
@@ -328,7 +326,7 @@ D) Custom (you specify)
    - Define your own environment pipeline
 ```
 
-**After user responds**, update `.specweave/config.yaml` and proceed with infrastructure generation.
+**After user responds**, save environment settings and proceed with infrastructure generation.
 
 ---
 
@@ -1175,7 +1173,7 @@ jobs:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v5
+        uses: docker/do-push-action@v5
         with:
           context: .
           push: true

package/src/agents/docs-writer/AGENT.md

@@ -1,6 +1,6 @@
 ---
 name: docs-writer
-description: Technical documentation writer for API documentation, user guides, developer guides, README files, architecture documentation, and knowledge base articles. Creates clear, comprehensive documentation using Markdown, OpenAPI/Swagger specs, Docusaurus, MkDocs, JSDoc, docstrings. Activates for: documentation, docs, README, API documentation, user guide, developer guide, technical writing, Markdown, OpenAPI, Swagger, JSDoc, docstring, documentation site, Docusaurus, MkDocs, GitBook, Notion docs, wiki, knowledge base, how-to guide, tutorial, reference docs, changelog, release notes.
+description: Technical documentation writer for API documentation, user guides, developer guides, README files, architecture documentation, and knowledge base articles. Creates clear, comprehensive documentation using Markdown, OpenAPI/Swagger specs, Docusaurus, JSDoc, docstrings. Activates for: documentation, docs, README, API documentation, user guide, developer guide, technical writing, Markdown, OpenAPI, Swagger, JSDoc, docstring, documentation site, Docusaurus, GitBook, Notion docs, wiki, knowledge base, how-to guide, tutorial, reference docs, changelog, release notes.
 tools: Read, Write, Edit
 model: claude-haiku-4-5-20251001
 ---
@@ -15,7 +15,7 @@ You are an expert technical writer with 8+ years of experience creating clear, c
 - **User Guides**: Step-by-step tutorials, how-to guides, quickstart guides
 - **Developer Docs**: Architecture docs, contribution guides, setup instructions
 - **Code Documentation**: JSDoc, Python docstrings, XML comments (C#)
-- **Documentation Sites**: Docusaurus, MkDocs, GitBook, VitePress
+- **Documentation Sites**: Docusaurus (primary), GitBook, VitePress
 - **Markdown**: GitHub-flavored Markdown, MDX
 - **Diagrams**: Mermaid, PlantUML, diagrams-as-code
 - **Style Guides**: Microsoft Writing Style Guide, Google developer docs style

package/src/agents/pm/AGENT.md

@@ -623,28 +623,7 @@ Output:
 
 ## Configuration
 
-```yaml
-# .specweave/config.yaml
-pm_agent:
-  enabled: true
-
-  # Prioritization framework
-  default_framework: "RICE"  # RICE, MoSCoW, Kano
-
-  # User story format
-  story_format: "agile"  # agile, gherkin, custom
 
-  # Estimation scale
-  estimation: "fibonacci"  # fibonacci, t-shirt, hours
-
-  # Output locations
-  specifications_dir: "specifications/modules/"
-  roadmap_file: "features/roadmap.md"
-
-  # Stakeholder communication
-  business_language: true  # Use non-technical language
-  include_roi: true        # Always calculate ROI
-```
 
 ## Testing
 
@@ -977,35 +956,7 @@ Create new increment for extra scope? [Y/n]
 
 ### Configuration
 
-```yaml
-# .specweave/config.yaml
-increment_closure:
-  pm_validation:
-    enabled: true           # MUST be true
-    strict_mode: true       # Require all 3 gates
-
-  gates:
-    tasks:
-      require_p1_complete: true
-      require_p2_complete: false
-      allow_scope_transfer: true
-
-    tests:
-      require_all_passing: true
-      min_coverage: 80
-      allow_skipped: false
-
-    documentation:
-      require_claude_md: true
-      require_readme: true
-      require_changelog: true
-      allow_inline_only: false
-
-  scope_creep:
-    detect: true
-    max_additional_tasks: 10
-    auto_transfer: true
-```
+
 
 ---
 

package/src/commands/README.md

@@ -1,155 +1,157 @@
 # SpecWeave Slash Commands
 
-This directory contains all slash commands for SpecWeave, including both full commands and short aliases.
+This directory contains all slash commands for SpecWeave.
 
-## Command Aliases
+## Available Commands (v0.2.0)
 
-SpecWeave provides short aliases for frequently used commands to speed up your workflow:
+**IMPORTANT**: All SpecWeave commands are now namespaced with `specweave.` notation to avoid collisions in brownfield projects.
 
-| Full Command | Alias | Description |
-|--------------|-------|-------------|
-| `/create-project` | `/init` | Initialize new SpecWeave project |
-| `/create-increment` | `/pi` | Plan Product Increment (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 |
+### Core Workflow Commands (Smart Workflow)
 
-## Usage
+| Command | Shorthand via /specweave | Description |
+|---------|--------------------------|-------------|
+| `/specweave.increment` | `/specweave inc` | Plan increment (PM-led, auto-closes previous if ready) |
+| `/specweave.inc` | `/specweave inc` | Alias for /specweave.increment |
+| `/specweave.do` | `/specweave do` | Execute work (smart resume, hooks after every task) |
+| `/specweave.next` | `/specweave next` | Smart transition (close + suggest next) |
+| `/specweave.progress` | `/specweave progress` | Show status (task %, PM gates, next action) |
+| `/specweave.validate` | `/specweave validate` | Validate quality (rule-based + optional LLM judge) |
+| `/specweave.done` | `/specweave done` | Close explicitly (optional, /inc auto-closes) |
 
-### Full Commands (Explicit)
+### Supporting Commands
 
-Use full commands when:
-- ✅ Writing scripts or automation
-- ✅ Documentation and tutorials
-- ✅ Sharing commands with team members
-- ✅ Clarity is more important than speed
+| Command | Shorthand via /specweave | Description |
+|---------|--------------------------|-------------|
+| `/specweave.list-increments` | `/specweave list-increments` | List all increments with status and WIP tracking |
+| `/specweave.sync-docs` | `/specweave sync-docs` | Review strategic docs vs implementation |
+| `/specweave.sync-github` | `/specweave sync-github` | Sync increment to GitHub issues with granular control |
+| `/specweave.sync-jira` | `/specweave sync-jira` | Sync increment to Jira epics/stories with granular control |
 
-**Example**:
-```bash
-/create-increment "User authentication with OAuth"
-/validate-increment 0001 --quality
-/close-increment 0001
-```
+### Master Router Command
 
-### Aliases (Quick)
+| Command | Description |
+|---------|-------------|
+| `/specweave` | Master router for all subcommands (use `/specweave <subcommand>`) |
 
-Use aliases when:
-- ✅ Active development (speed matters)
-- ✅ Iterative workflow (creating/validating frequently)
-- ✅ Command-line muscle memory
-- ✅ Personal productivity
+## Smart Workflow Features (v0.2.0)
 
-**Example**:
-```bash
-/ci "User authentication with OAuth"
-/vi 0001 --quality
-/done 0001
-```
+**What makes the workflow "smart"?**
+
+1. ✅ **Auto-resume**: `/specweave do` automatically finds next incomplete task (no manual tracking)
+2. ✅ **Auto-close**: `/specweave inc` auto-closes previous increment if PM gates pass (seamless)
+3. ✅ **Suggest-not-force**: `/specweave inc` presents options if previous incomplete (user control)
+4. ✅ **Progress visibility**: `/specweave progress` shows exactly where you are anytime
+5. ✅ **Natural flow**: finish → start next without administrative overhead
 
 ## Typical Workflow
 
-**Using aliases for speed**:
+**Natural append-only workflow** (0001 → 0002 → 0003):
+
 ```bash
-# 1. Initialize project
-/init my-saas
+# 1. Initialize project (CLI, before any AI session)
+npx specweave init my-saas
 
-# 2. Plan Product Increment (PI = Product Increment in Agile)
-/pi "User authentication"
+# 2. Plan your first increment (PM-led planning)
+/specweave inc "AI-powered customer support chatbot"
+# PM creates: spec.md + plan.md + tasks.md (auto-generated!) + tests.md
 
-# 3. Start working
-/si 0001
+# 3. Build it (smart resume)
+/specweave do
+# Auto-resumes from next incomplete task
+# Hooks run after EVERY task completion
 
-# 4. Add tasks as needed
-/at 0001 "Implement login endpoint"
-/at 0001 "Add password validation"
+# 4. Check progress anytime
+/specweave progress
+# Shows: 5/12 tasks (42%), next: T006, PM gates status
 
-# 5. Check progress
-/ls --status=in-progress
+# 5. Continue building
+/specweave do
+# Picks up where you left off automatically
 
-# 6. Validate before closing
-/vi 0001 --quality
+# 6. Start next feature (auto-closes previous!)
+/specweave inc "real-time chat dashboard"
+# Smart check:
+#   If 0001 complete (PM gates pass) → Auto-close, create 0002
+#   If 0001 incomplete → Present options (never forces)
 
-# 7. Close when done
-/done 0001
-```
+# 7. Keep building
+/specweave do
+# Auto-finds active increment 0002
 
-**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
+# Repeat: /specweave inc → /specweave do → /specweave progress → ...
 ```
 
-## All Available Commands
+## Namespaced Commands (Brownfield Safety)
 
-### Core Workflow Commands
+**Design decision**: All commands use `specweave.` notation for collision avoidance.
 
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/create-project` | `/init` | Bootstrap new SpecWeave project with auto-detection |
-| `/create-increment` | `/pi` | Plan Product 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 |
+- ✅ No conflicts with existing project commands
+- ✅ Clear ownership (framework vs. project commands)
+- ✅ Use master router `/specweave` for convenience
+- ✅ Brownfield projects can adopt SpecWeave without risk
 
-### Documentation & Review Commands
+**Most used workflow**:
+```bash
+/specweave inc "feature"     # ← Create new increment
+/specweave do             # ← Execute work
+/specweave progress          # ← Check status
+/specweave next              # ← Smart transition to next work
+```
 
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/review-docs` | - | Review strategic docs vs implementation |
-| `/generate-docs` | - | Generate documentation site (Docusaurus/MkDocs) |
+## Command Design Philosophy
 
-### Integration Commands
+### 1. Natural Flow Without Overhead
 
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/sync-github` | - | Sync increment to GitHub issues with subtasks |
+**Problem with traditional workflows**:
+- Manual task tracking ("which task am I on?")
+- Manual closure ("do I need to close this?")
+- Administrative overhead ("update project board")
 
-## Alias Design Philosophy
+**SpecWeave solution**:
+- `/do` auto-resumes (no tracking needed)
+- `/inc` auto-closes if ready (no manual /done needed)
+- `/progress` shows status anytime (no board updates)
 
-**Why separate files instead of symlinks?**
+### 2. Suggest, Never Force
 
-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
+**Critical principle**: User always in control.
 
-**Trade-off**: Slight content duplication, but improved UX and compatibility.
+**Example**: When starting new increment while previous incomplete:
+```
+/inc "new feature"
 
-## Creating Custom Aliases
+📊 Checking previous increment 0001-authentication...
+   Status: in-progress
+   PM Gates: ❌ 2 P1 tasks remaining
 
-You can create your own project-specific aliases:
+❌ Cannot auto-close 0001 (incomplete)
 
-**1. Create `.claude/commands/custom-alias.md`**:
-```markdown
----
-description: Your custom command description
----
+Options:
+  A) Complete 0001 first (recommended)
+     → Finish remaining work before starting new
 
-# Custom Alias
+  B) Move incomplete tasks to 0002
+     → Transfer T006, T007 to new increment
+     → Close 0001 as "completed with deferrals"
 
-This is a shorthand for `/some-long-command`.
+  C) Cancel new increment
+     → Stay on 0001, continue working
+     → Retry /inc when ready
 
-<!-- Paste full command content or reference it -->
+Your choice? _
 ```
 
-**2. Use it**:
-```bash
-/custom-alias
-```
+**Never**: "Auto-closed 0001 with incomplete work" (surprising, loses context)
+
+### 3. Progressive Disclosure
+
+**Only show complexity when needed**:
+- ✅ Happy path: `/inc` → Auto-close, create new (1 step)
+- ⚠️ Issues found: Show options, explain, let user decide
 
 ## Installation
 
-Aliases are automatically installed when you:
+Commands are automatically installed when you:
 - Run `specweave init` (new projects)
 - Install SpecWeave as dependency (`npm install specweave --save-dev`)
 
@@ -158,16 +160,37 @@ For manual installation:
 npm run install:commands
 ```
 
+## Creating Custom Commands
+
+You can create project-specific commands:
+
+**1. Create `.claude/commands/custom.md`**:
+```markdown
+---
+name: custom
+description: Your custom command description
+---
+
+# Custom Command
+
+[Your command implementation]
+```
+
+**2. Use it**:
+```bash
+/custom
+```
+
 ## Documentation
 
-- **Command Reference**: See `.claude/commands/` for all available commands
-- **CLAUDE.md**: Quick reference table with all commands and aliases
+- **Command Reference**: See `.claude/commands/` for all command implementations
+- **CLAUDE.md**: Quick reference table with all commands
 - **Official Docs**: https://spec-weave.com/docs/commands
 
 ---
 
-**💡 Pro Tip**: Learn the aliases - they'll save you hundreds of keystrokes per day!
+**💡 Pro Tip**: Master the smart workflow - natural append-only progression!
 
-**Most used**: `/pi`, `/si`, `/vi`, `/done`, `/ls`
+**Core cycle**: `/inc` (plan) → `/do` (implement) → `/progress` (check) → `/inc` (next)
 
-**PI** = Product Increment (standard Agile/Scrum terminology)
+**One alias to rule them all**: `/inc` (short for `/increment`)