sqlew 3.9.1 → 4.0.1

package/assets/sample-commands/sqw-plan.md

@@ -1,7 +1,35 @@
+---
+description: Comprehensive planning - architect considers decisions, scrum master breaks down into tasks
+---
+
 # Sqlew Plan Workflow
 
 Comprehensive planning workflow - invokes architect for architectural consideration, then scrum master for task breakdown.
 
+## Agent Invocation
+
+This workflow uses two specialized sqlew agents in sequence:
+
+```
+Phase 1: Task tool → subagent_type: "sqlew-architect" (opus)
+Phase 2: Task tool → subagent_type: "scrum-master" (sonnet)
+```
+
+**Example:**
+```typescript
+// Phase 1: Architectural consideration
+Task({
+  subagent_type: "sqlew-architect",
+  prompt: "Analyze architectural implications for: [user requirement]. Check existing decisions, document new decisions if needed, establish constraints."
+})
+
+// Phase 2: Task breakdown
+Task({
+  subagent_type: "scrum-master",
+  prompt: "Based on the architectural decisions, break down the work into tasks with dependencies, layers, and priorities."
+})
+```
+
 ## Purpose
 
 Transform ideas or requirements into documented decisions and actionable task plans. A two-phase workflow combining architectural thinking with agile task management.
@@ -9,10 +37,11 @@ Transform ideas or requirements into documented decisions and actionable task pl
 ## What It Does
 
 ### Phase 1: Architectural Consideration (Architect Agent)
-1. Checks for related decisions
+1. Checks for related decisions (using `suggest`)
 2. Discusses architectural implications
 3. Documents key decisions if needed
-4. Establishes constraints if needed
+4. **Reviews auto-suggested constraints** (v4.0) - decision.set returns related constraints
+5. Establishes constraints if needed (with duplicate checking via `suggest`)
 
 ### Phase 2: Task Breakdown (Scrum Master Agent)
 1. Breaks work into manageable tasks
@@ -25,15 +54,15 @@ Transform ideas or requirements into documented decisions and actionable task pl
 
 ### Interactive Mode
 ```bash
-/sqlew-plan
+/sqw-plan
 ```
 Prompts for feature/requirement details and guides through both phases.
 
 ### With Arguments
 ```bash
-/sqlew-plan implement user authentication
-/sqlew-plan add caching layer
-/sqlew-plan migrate to microservices
+/sqw-plan implement user authentication
+/sqw-plan add caching layer
+/sqw-plan migrate to microservices
 ```
 
 ## Workflow
@@ -41,10 +70,12 @@ Prompts for feature/requirement details and guides through both phases.
 ### Phase 1: Architect Considers Architecture
 
 **Architect checks:**
-- Are there existing decisions about this area?
+- Are there existing decisions about this area? (using `suggest.by_key`, `suggest.by_tags`)
 - What architectural patterns apply?
+- What constraints already exist? (v4.0: using `suggest.by_context` with `target: "constraint"`)
 - What constraints should govern this work?
 - What decisions need to be documented?
+- Are there related constraints? (v4.0: auto-suggested when recording decisions)
 
 **Example interaction:**
 
@@ -54,6 +85,10 @@ Prompts for feature/requirement details and guides through both phases.
 > - "api-authentication-method" - JWT tokens
 > - "session-management-strategy" - stateless sessions
 >
+> **Related Constraints Found** (v4.0):
+> - "All API endpoints must verify JWT tokens" (security, priority 4)
+> - "Token refresh must use rotation strategy" (security, priority 3)
+>
 > Your requirement is to "add OAuth2 social login support"
 >
 > This extends existing JWT authentication. I recommend documenting:
@@ -61,9 +96,9 @@ Prompts for feature/requirement details and guides through both phases.
 > 2. How OAuth2 tokens map to JWT tokens
 > 3. User account linking strategy
 >
-> Should I document these decisions?
+> These new decisions should comply with existing constraints. Should I document these decisions?
 
-**You discuss and architect documents decisions.**
+**You discuss and architect documents decisions. The system auto-suggests related constraints for review.**
 
 ### Phase 2: Scrum Master Creates Tasks
 
@@ -113,16 +148,16 @@ Prompts for feature/requirement details and guides through both phases.
 
 ## When to Use
 
-Use `/sqlew-plan` when:
+Use `/sqw-plan` when:
 - Starting a new feature or capability
 - Architectural decisions are unclear or need documentation
 - You need a complete plan from concept to implementation
 - You want both strategic (decisions) and tactical (tasks) planning
 
 **Don't use when:**
-- Only documenting decisions (use `/sqlew-decide` instead)
-- Only creating tasks (use `/sqlew-scrum` instead)
-- Researching existing plans (use `/sqlew-research` instead)
+- Only documenting decisions (use `/sqw-documentor` instead)
+- Only creating tasks (use `/sqw-scrum` instead)
+- Researching existing plans (use `/sqw-research` instead)
 
 ## Two-Phase Benefits
 
@@ -131,12 +166,14 @@ Use `/sqlew-plan` when:
 Without architectural consideration:
 - Tasks may conflict with existing decisions
 - Important constraints may be overlooked
+- Existing constraints may be violated unknowingly
 - Architectural implications not documented
 - Future developers lack context
 
 With architect phase:
 - Decisions documented before implementation
-- Constraints established upfront
+- **Related constraints auto-discovered** (v4.0) - ensures compliance
+- New constraints established with duplicate checking
 - Tasks aligned with architecture
 - Context preserved for future work
 
@@ -157,16 +194,20 @@ With scrum master phase:
 ## Example: Complete Planning Session
 
 ```bash
-/sqlew-plan add Redis caching layer
+/sqw-plan add Redis caching layer
 ```
 
 ### Phase 1: Architect
 
 > **Architect**: Let me check for caching decisions...
 >
-> No existing caching decisions found. Let me check performance constraints...
+> *Runs suggest({ action: "by_key", key: "caching" }) - no results*
+> *Runs suggest({ action: "by_context", target: "constraint", text: "caching", tags: ["performance"] })*
+>
+> No existing caching decisions found. Checking performance constraints...
 >
-> Found constraint: "API response time must be <200ms" (performance, priority 4)
+> **Found Constraint** (via suggest):
+> - "API response time must be <200ms" (performance, priority 4, score: 72)
 >
 > Your requirement to "add Redis caching layer" has architectural implications:
 >
@@ -176,14 +217,16 @@ With scrum master phase:
 > 3. What to cache (endpoints, database queries, computed results)
 > 4. Cache TTL policies
 >
-> **Constraints to establish:**
+> **Constraints to establish** (will check for duplicates first):
 > 1. All cache keys must use namespace prefixes
 > 2. Cache failures must not break application
 > 3. Cache metrics must be monitored
 >
 > Let's document these decisions...
 
-*Architect documents 4 decisions and creates 3 constraints*
+*Architect documents 4 decisions (each returns related_constraints for review)*
+*Architect checks for duplicate constraints using suggest({ target: "constraint" }) before creating*
+*Creates 3 new constraints (no duplicates found)*
 
 > **Architect**: Decisions and constraints documented. Handing off to scrum master for task breakdown...
 
@@ -221,13 +264,13 @@ With scrum master phase:
 ## Integration with Other Workflows
 
 This workflow combines:
-- `/sqlew-decide` - Decision documentation (architect phase)
-- `/sqlew-scrum` - Task management (scrum master phase)
+- `/sqw-documentor` - Decision documentation (architect phase)
+- `/sqw-scrum` - Task management (scrum master phase)
 
 Use with:
-- **Before**: `/sqlew-research` to understand existing context
+- **Before**: `/sqw-research` to understand existing context
 - **During**: Architect and scrum master handle the planning
-- **After**: Implement tasks, use `/sqlew-review` to validate
+- **After**: Implement tasks, use `/sqw-review` to validate
 
 ## Token Efficiency
 
@@ -235,14 +278,17 @@ This workflow is more token-efficient than separate operations:
 
 **Separate workflows**:
 - Research: 2k tokens
-- Decide: 5k tokens
+- Document decisions: 5k tokens
+- Constraint search: 2k tokens
 - Create tasks: 3k tokens
-- Total: 10k tokens
+- Total: 12k tokens
 
-**Combined /sqlew-plan**:
-- Single context: 7k tokens (30% savings)
+**Combined /sqw-plan (v4.0)**:
+- Single context: 7k tokens (40% savings)
 - Architect→Scrum handoff preserves context
 - No redundant searches
+- Auto-suggested constraints reduce queries
+- Constraint duplicate checking integrated
 
 **Estimated Token Usage**: 7,000-15,000 tokens per planning session
 
@@ -255,33 +301,34 @@ This workflow is more token-efficient than separate operations:
 
 1. **Provide clear requirements** - the more specific, the better the plan
 2. **Trust the architect** - let them identify architectural implications
-3. **Review task breakdown** - verify priorities and dependencies make sense
-4. **Adjust before creation** - easier to modify plan before tasks created
-5. **Link everything** - architect and scrum master will link decisions→constraints→tasks
+3. **Review suggested constraints** (v4.0) - architect shows related constraints automatically
+4. **Review task breakdown** - verify priorities and dependencies make sense
+5. **Adjust before creation** - easier to modify plan before tasks created
+6. **Link everything** - architect and scrum master will link decisions→constraints→tasks
 
 ## Comparison with Other Workflows
 
-### /sqlew-decide
+### /sqw-documentor
 - **Focus**: Decision documentation only
 - **Use when**: You know what decision to document
 - **Phases**: 1 (architect)
 
-### /sqlew-scrum
+### /sqw-scrum
 - **Focus**: Task management only
 - **Use when**: Decisions already documented
 - **Phases**: 1 (scrum master)
 
-### /sqlew-plan
+### /sqw-plan
 - **Focus**: Complete planning (decisions + tasks)
 - **Use when**: Starting new work, unclear architecture
 - **Phases**: 2 (architect → scrum master)
 
-### /sqlew-research
+### /sqw-research
 - **Focus**: Historical context analysis
 - **Use when**: Understanding existing state
 - **Phases**: 1 (researcher)
 
-### /sqlew-review
+### /sqw-review
 - **Focus**: Validation and consistency
 - **Use when**: Verifying completed work
 - **Phases**: 2 (researcher → architect)

package/assets/sample-commands/sqw-research.md

@@ -1,4 +1,30 @@
-# Sqlew Research Agent
+---
+description: Query historical decisions, analyze patterns, and retrieve insights from project context
+---
+
+# Sqlew Research Workflow
+
+Research workflow for querying historical decisions, analyzing patterns, and extracting insights from project context.
+
+## Agent Invocation
+
+This workflow uses the specialized sqlew-researcher agent:
+
+```
+Task tool → subagent_type: "sqlew-researcher" (haiku)
+```
+
+**Example:**
+```typescript
+Task({
+  subagent_type: "sqlew-researcher",
+  prompt: "Research the following topic: [user query]. Search decisions, constraints, and tasks to provide comprehensive context."
+})
+```
+
+---
+
+**Agent Instructions (for sqlew-researcher):**
 
 You are an expert research analyst specializing in querying historical context, analyzing patterns, and presenting findings from the sqlew MCP shared context server.
 
@@ -8,11 +34,17 @@ Search and analyze historical decisions, tasks, constraints, and patterns to pro
 
 ## Available Tools
 
-- **mcp__sqlew__suggest**: Intelligent similarity-based discovery
-  - **by_key**: Find decisions by key pattern matching
-  - **by_tags**: Find decisions sharing tags
-  - **by_context**: Find decisions with similar tags and context
-  - **check_duplicate**: Verify if similar decisions already exist
+- **mcp__sqlew__suggest**: Intelligent similarity-based discovery (v4.0)
+  - **Decision search** (default: `target: "decision"`):
+    - **by_key**: Find decisions by key pattern matching
+    - **by_tags**: Find decisions sharing tags
+    - **by_context**: Find decisions with similar tags and context
+    - **check_duplicate**: Verify if similar decisions already exist
+  - **Constraint search** (`target: "constraint"`):
+    - **by_text**: Find constraints by text similarity
+    - **by_tags**: Find constraints sharing tags
+    - **by_context**: Find constraints with similar tags, layer, and text
+    - **check_duplicate**: Verify if similar constraints already exist
 
 - **mcp__sqlew__decision**: Decision queries and history
   - **get**: Retrieve specific decision by key
@@ -23,12 +55,13 @@ Search and analyze historical decisions, tasks, constraints, and patterns to pro
   - **list_decision_contexts**: Show decision relationships
 
 - **mcp__sqlew__task**: Task queries and analytics
-  - **list**: Query tasks with powerful filters (status, agent, layer, tags, priority)
+  - **list**: Query tasks with powerful filters (status, layer, tags, priority)
   - **get**: Retrieve specific task details
   - **get_dependencies**: Visualize task dependency graphs
 
 - **mcp__sqlew__constraint**: Constraint queries
   - **get**: Retrieve constraints by category or ID
+  - **add**: Create new constraints (use suggest first to check duplicates)
 
 ## Workflow
 
@@ -89,21 +122,33 @@ When analyzing work patterns:
    task({ action: "get_dependencies", task_id: 42 })
    ```
 
-### 3. Constraint Analysis
+### 3. Constraint Analysis (v4.0 Enhanced)
 
 When researching architectural rules:
 
-1. **Query by category**:
+1. **Similarity search** (most efficient, NEW in v4.0):
+   ```typescript
+   suggest({ action: "by_text", target: "constraint", text: "authentication" })
+   suggest({ action: "by_tags", target: "constraint", tags: ["security", "api"] })
+   suggest({ action: "by_context", target: "constraint", text: "JWT tokens", tags: ["security"], layer: "business" })
+   ```
+
+2. **Query by category**:
    ```typescript
    constraint({ action: "get", category: "security" })
    constraint({ action: "get", category: "performance" })
    ```
 
-2. **Check specific constraint**:
+3. **Check specific constraint**:
    ```typescript
    constraint({ action: "get", constraint_id: 5 })
    ```
 
+4. **Check for duplicate constraints** before creating:
+   ```typescript
+   suggest({ action: "check_duplicate", target: "constraint", text: "All API endpoints must verify JWT" })
+   ```
+
 ### 4. Cross-Context Analysis
 
 When connecting multiple contexts:
@@ -127,16 +172,16 @@ When connecting multiple contexts:
 
 ### Interactive Mode
 ```bash
-/sqlew-research
+/sqw-research
 ```
 Prompts you through research queries.
 
 ### With Arguments
 ```bash
-/sqlew-research authentication decisions
-/sqlew-research blocked tasks
-/sqlew-research security constraints
-/sqlew-research backend agent workload
+/sqw-research authentication decisions
+/sqw-research blocked tasks
+/sqw-research security constraints
+/sqw-research backend agent workload
 ```
 
 ## Best Practices
@@ -200,6 +245,18 @@ constraint({ action: "get", category: "architecture" })
 decision({ action: "search_layer", layer: "business" })
 ```
 
+### "What constraints relate to topic X?" (v4.0)
+```typescript
+suggest({ action: "by_text", target: "constraint", text: "authentication" })
+suggest({ action: "by_context", target: "constraint", text: "user login", tags: ["security"] })
+```
+
+### "Does a similar constraint already exist?" (v4.0)
+```typescript
+suggest({ action: "check_duplicate", target: "constraint", text: "All passwords must be hashed" })
+// Returns exact_match (true/false) and similar constraints with scores
+```
+
 ## Example Session
 
 ```markdown
@@ -247,8 +304,10 @@ Would you like me to:
 ## Token Efficiency Tips
 
 **High Efficiency** (< 1k tokens):
-- `suggest.by_key` - Smart pattern matching
-- `suggest.by_tags` - Tag-based discovery
+- `suggest.by_key` - Smart pattern matching (decisions)
+- `suggest.by_tags` - Tag-based discovery (decisions/constraints)
+- `suggest.by_text` - Text similarity search (constraints, v4.0)
+- `suggest.by_context` - Multi-factor similarity (decisions/constraints, v4.0)
 - `decision.get` - Specific decision retrieval
 - `task.get` - Specific task retrieval
 - `constraint.get` - Specific constraint retrieval
@@ -258,10 +317,12 @@ Would you like me to:
 - `decision.search_layer` - Layer-based search
 - `task.list` with filters - Targeted task queries
 - `decision.versions` - Decision history
+- `suggest.check_duplicate` - Duplicate detection (decisions/constraints)
 
 **Low Efficiency** (5k+ tokens, use sparingly):
 - `decision.list` - All decisions (use only when necessary)
 - `task.list` without filters - All tasks (use only when necessary)
+- `constraint.get` without filters - All constraints
 
 ## Error Handling
 

package/assets/sample-commands/sqw-review.md

@@ -1,7 +1,35 @@
+---
+description: Validate architectural consistency - research context, then verify decisions and constraints
+---
+
 # Sqlew Review Workflow
 
 Validation and consistency checking workflow - invokes researcher for context analysis, then architect for validation.
 
+## Agent Invocation
+
+This workflow uses two specialized sqlew agents in sequence:
+
+```
+Phase 1: Task tool → subagent_type: "sqlew-researcher" (haiku)
+Phase 2: Task tool → subagent_type: "sqlew-architect" (opus)
+```
+
+**Example:**
+```typescript
+// Phase 1: Research context
+Task({
+  subagent_type: "sqlew-researcher",
+  prompt: "Research context for: [review target]. Analyze decisions, constraints, and tasks. Identify patterns and inconsistencies."
+})
+
+// Phase 2: Architectural validation
+Task({
+  subagent_type: "sqlew-architect",
+  prompt: "Based on the research findings, validate architectural consistency. Check constraint compliance and recommend corrections."
+})
+```
+
 ## Purpose
 
 Verify architectural consistency, validate decision implementation, and ensure constraints are followed. A two-phase workflow combining historical analysis with expert validation.
@@ -10,9 +38,10 @@ Verify architectural consistency, validate decision implementation, and ensure c
 
 ### Phase 1: Research Context (Research Agent)
 1. Analyzes relevant decisions, constraints, and tasks
-2. Identifies patterns and relationships
-3. Detects gaps or inconsistencies
-4. Provides evidence-based findings
+2. **Uses constraint suggest** (v4.0) to find related constraints efficiently
+3. Identifies patterns and relationships
+4. Detects gaps or inconsistencies
+5. Provides evidence-based findings
 
 ### Phase 2: Architectural Validation (Architect Agent)
 1. Reviews research findings
@@ -25,16 +54,16 @@ Verify architectural consistency, validate decision implementation, and ensure c
 
 ### Interactive Mode
 ```bash
-/sqlew-review
+/sqw-review
 ```
 Prompts for what to review and guides through both phases.
 
 ### With Arguments
 ```bash
-/sqlew-review authentication implementation
-/sqlew-review security decisions
-/sqlew-review performance constraints
-/sqlew-review backend agent work
+/sqw-review authentication implementation
+/sqw-review security decisions
+/sqw-review performance constraints
+/sqw-review backend agent work
 ```
 
 ## Workflow
@@ -42,8 +71,9 @@ Prompts for what to review and guides through both phases.
 ### Phase 1: Researcher Analyzes Context
 
 **Researcher examines:**
-- Related decisions and their versions
-- Relevant constraints
+- Related decisions and their versions (using `suggest.by_key`, `suggest.by_tags`)
+- Relevant constraints (v4.0: using `suggest.by_context` with `target: "constraint"`)
+- Constraint compliance with decisions
 - Implementation tasks (completed, in-progress, blocked)
 - Cross-references and relationships
 
@@ -51,14 +81,17 @@ Prompts for what to review and guides through both phases.
 
 > **Researcher**: Analyzing authentication implementation...
 >
+> *Runs suggest({ action: "by_key", key: "authentication" })*
+> *Runs suggest({ action: "by_context", target: "constraint", text: "authentication", tags: ["security"] })*
+>
 > **Decisions Found** (3):
 > 1. "api-authentication-method" - JWT tokens (v2, last updated 3 days ago)
 > 2. "jwt-token-expiration-policy" - 15min access, 7d refresh (v1)
 > 3. "session-management-strategy" - stateless sessions (v1)
 >
-> **Constraints Found** (2):
-> 1. "All API endpoints must verify JWT tokens" (security, priority 4)
-> 2. "Token refresh must use rotation strategy" (security, priority 3)
+> **Constraints Found** (2) via suggest (v4.0):
+> 1. "All API endpoints must verify JWT tokens" (security, priority 4, score: 85)
+> 2. "Token refresh must use rotation strategy" (security, priority 3, score: 72)
 >
 > **Implementation Tasks** (8):
 > - ✅ 6 completed: JWT service, middleware, token rotation, tests
@@ -103,7 +136,7 @@ Prompts for what to review and guides through both phases.
 
 ## When to Use
 
-Use `/sqlew-review` when:
+Use `/sqw-review` when:
 - Verifying implementation follows decisions
 - Checking architectural consistency
 - Auditing constraint compliance
@@ -111,9 +144,9 @@ Use `/sqlew-review` when:
 - Investigating potential issues
 
 **Don't use when:**
-- Creating new decisions (use `/sqlew-decide` instead)
-- Planning new work (use `/sqlew-plan` instead)
-- Just querying history (use `/sqlew-research` instead)
+- Creating new decisions (use `/sqw-documentor` instead)
+- Planning new work (use `/sqw-plan` instead)
+- Just querying history (use `/sqw-research` instead)
 
 ## Review Types
 
@@ -152,13 +185,16 @@ Verify agents have:
 ## Example: Complete Review Session
 
 ```bash
-/sqlew-review security architecture
+/sqw-review security architecture
 ```
 
 ### Phase 1: Researcher
 
 > **Researcher**: Analyzing security architecture...
 >
+> *Runs suggest({ action: "by_tags", tags: ["security"] })*
+> *Runs suggest({ action: "by_context", target: "constraint", tags: ["security"], layer: "cross-cutting" })*
+>
 > **Security Decisions** (5):
 > 1. "api-authentication-method" - JWT tokens
 > 2. "api-authorization-approach" - role-based access control
@@ -166,11 +202,11 @@ Verify agents have:
 > 4. "https-enforcement-strategy" - HTTPS-only in production
 > 5. "security-headers-policy" - strict CSP, HSTS, X-Frame-Options
 >
-> **Security Constraints** (4):
-> 1. "All passwords must be hashed with bcrypt" (security, priority 4)
-> 2. "All API endpoints must verify authentication" (security, priority 4)
-> 3. "Production must enforce HTTPS" (security, priority 4)
-> 4. "All responses must include security headers" (security, priority 3)
+> **Security Constraints Found** (4) via suggest (v4.0):
+> 1. "All passwords must be hashed with bcrypt" (security, priority 4, score: 88)
+> 2. "All API endpoints must verify authentication" (security, priority 4, score: 85)
+> 3. "Production must enforce HTTPS" (security, priority 4, score: 80)
+> 4. "All responses must include security headers" (security, priority 3, score: 72)
 >
 > **Security Tasks** (12 total):
 > - ✅ 9 completed
@@ -236,8 +272,8 @@ Verify agents have:
 ## Integration with Other Workflows
 
 This workflow combines:
-- `/sqlew-research` - Context analysis (researcher phase)
-- `/sqlew-decide` - Decision updates (architect phase)
+- `/sqw-research` - Context analysis (researcher phase)
+- `/sqw-documentor` - Decision updates (architect phase)
 
 Use with:
 - **Before review**: Complete implementation work
@@ -256,10 +292,11 @@ This workflow is efficient for comprehensive validation:
 - Validate: 3k tokens
 - Total: 14k tokens
 
-**Combined /sqlew-review**:
-- Research phase: 6k tokens (automated queries)
+**Combined /sqw-review (v4.0)**:
+- Research phase: 5k tokens (using suggest for constraints)
 - Architect phase: 4k tokens (validation)
-- **Total**: 10k tokens (30% savings)
+- **Total**: 9k tokens (35% savings)
+- Constraint suggest reduces query overhead significantly
 
 **Estimated Token Usage**: 10,000-20,000 tokens per review session
 
@@ -314,7 +351,7 @@ The workflow automatically checks:
 
 ## Review Triggers
 
-Consider running `/sqlew-review` when:
+Consider running `/sqw-review` when:
 - Completing a major feature
 - Before starting related work
 - After significant decision changes