sqlew 4.0.2 → 4.0.3

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

@@ -1,348 +0,0 @@
----
-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.
-
-## What It Does
-
-### Phase 1: Architectural Consideration (Architect Agent)
-1. Checks for related decisions (using `suggest`)
-2. Discusses architectural implications
-3. Documents key decisions 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
-2. Assigns appropriate layers and priorities
-3. Establishes task dependencies
-4. Links tasks to decisions/constraints
-5. Assigns to specialized agents if needed
-
-## Usage
-
-### Interactive Mode
-```bash
-/sqw-plan
-```
-Prompts for feature/requirement details and guides through both phases.
-
-### With Arguments
-```bash
-/sqw-plan implement user authentication
-/sqw-plan add caching layer
-/sqw-plan migrate to microservices
-```
-
-## Workflow
-
-### Phase 1: Architect Considers Architecture
-
-**Architect checks:**
-- 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:**
-
-> **Architect**: Let me check existing authentication decisions...
->
-> Found 2 related decisions:
-> - "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:
-> 1. Which OAuth2 providers to support
-> 2. How OAuth2 tokens map to JWT tokens
-> 3. User account linking strategy
->
-> These new decisions should comply with existing constraints. Should I document these decisions?
-
-**You discuss and architect documents decisions. The system auto-suggests related constraints for review.**
-
-### Phase 2: Scrum Master Creates Tasks
-
-**Scrum Master breaks down work:**
-
-> **Scrum Master**: Based on the OAuth2 social login decisions, I'll create tasks:
->
-> **Planning Tasks** (planning layer, no files needed):
-> 1. Research OAuth2 provider SDKs (priority 3)
-> 2. Design account linking flow (priority 3)
->
-> **Implementation Tasks** (requires files):
-> 3. Implement Google OAuth2 integration (business layer, priority 3)
->    - Files: src/auth/oauth/google.ts, src/auth/oauth/types.ts
->    - Depends on: task #1
->
-> 4. Implement GitHub OAuth2 integration (business layer, priority 3)
->    - Files: src/auth/oauth/github.ts
->    - Depends on: task #1
->
-> 5. Add account linking service (business layer, priority 3)
->    - Files: src/auth/linking-service.ts, src/db/models/linked-accounts.ts
->    - Depends on: task #2
->
-> 6. Create OAuth2 middleware (cross-cutting layer, priority 3)
->    - Files: src/middleware/oauth2.ts
->    - Depends on: tasks #3, #4, #5
->
-> 7. Write integration tests (business layer, priority 2)
->    - Files: tests/integration/oauth2.test.ts
->    - Depends on: task #6
->
-> 8. Update API documentation (documentation layer, priority 2)
->    - Files: docs/api/authentication.md
->    - Depends on: task #7
->
-> Tasks will be linked to the OAuth2 decisions documented.
->
-> Dependencies established:
-> - 1 → 3, 4
-> - 2 → 5
-> - 3, 4, 5 → 6
-> - 6 → 7
-> - 7 → 8
->
-> Shall I create these tasks?
-
-## When to Use
-
-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 `/sqw-documentor` instead)
-- Only creating tasks (use `/sqw-scrum` instead)
-- Researching existing plans (use `/sqw-research` instead)
-
-## Two-Phase Benefits
-
-### Why Not Just Create Tasks?
-
-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
-- **Related constraints auto-discovered** (v4.0) - ensures compliance
-- New constraints established with duplicate checking
-- Tasks aligned with architecture
-- Context preserved for future work
-
-### Why Not Just Document Decisions?
-
-Without task breakdown:
-- No clear implementation path
-- No dependency management
-- No workload coordination
-- No progress tracking
-
-With scrum master phase:
-- Clear, actionable tasks
-- Proper dependency chains
-- Agent assignments
-- Progress visibility
-
-## Example: Complete Planning Session
-
-```bash
-/sqw-plan add Redis caching layer
-```
-
-### Phase 1: Architect
-
-> **Architect**: Let me check for caching decisions...
->
-> *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** (via suggest):
-> - "API response time must be <200ms" (performance, priority 4, score: 72)
->
-> Your requirement to "add Redis caching layer" has architectural implications:
->
-> **Decisions to document:**
-> 1. Cache infrastructure choice (Redis vs Memcached vs in-memory)
-> 2. Cache invalidation strategy
-> 3. What to cache (endpoints, database queries, computed results)
-> 4. Cache TTL policies
->
-> **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 (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...
-
-### Phase 2: Scrum Master
-
-> **Scrum Master**: Based on the Redis caching decisions, I'll create tasks:
->
-> **Infrastructure Tasks:**
-> 1. Set up Redis infrastructure (infrastructure layer, priority 4, critical)
-> 2. Configure Redis client library (infrastructure layer, priority 4)
->
-> **Implementation Tasks:**
-> 3. Implement cache service abstraction (cross-cutting layer, priority 3)
-> 4. Add caching to API endpoints (presentation layer, priority 3)
-> 5. Add query result caching (data layer, priority 3)
-> 6. Implement cache invalidation logic (business layer, priority 3)
->
-> **Monitoring Tasks:**
-> 7. Add cache hit/miss metrics (cross-cutting layer, priority 2)
-> 8. Set up cache monitoring dashboard (infrastructure layer, priority 2)
->
-> **Testing Tasks:**
-> 9. Write cache service tests (cross-cutting layer, priority 3)
-> 10. Write cache invalidation tests (business layer, priority 3)
->
-> **Documentation Tasks:**
-> 11. Document caching strategy (documentation layer, priority 2)
->
-> Dependencies: 1→2→3→(4,5,6)→7,8 and 3→9, 6→10, (9,10)→11
->
-> All tasks linked to Redis caching decisions and constraints.
->
-> Ready to create 11 tasks?
-
-## Integration with Other Workflows
-
-This workflow combines:
-- `/sqw-documentor` - Decision documentation (architect phase)
-- `/sqw-scrum` - Task management (scrum master phase)
-
-Use with:
-- **Before**: `/sqw-research` to understand existing context
-- **During**: Architect and scrum master handle the planning
-- **After**: Implement tasks, use `/sqw-review` to validate
-
-## Token Efficiency
-
-This workflow is more token-efficient than separate operations:
-
-**Separate workflows**:
-- Research: 2k tokens
-- Document decisions: 5k tokens
-- Constraint search: 2k tokens
-- Create tasks: 3k tokens
-- Total: 12k tokens
-
-**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
-
-**AI Time Estimate**:
-- Architect phase: 10-20 minutes
-- Scrum master phase: 15-30 minutes
-- **Total**: 25-50 minutes
-
-## Tips
-
-1. **Provide clear requirements** - the more specific, the better the plan
-2. **Trust the architect** - let them identify architectural implications
-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
-
-### /sqw-documentor
-- **Focus**: Decision documentation only
-- **Use when**: You know what decision to document
-- **Phases**: 1 (architect)
-
-### /sqw-scrum
-- **Focus**: Task management only
-- **Use when**: Decisions already documented
-- **Phases**: 1 (scrum master)
-
-### /sqw-plan
-- **Focus**: Complete planning (decisions + tasks)
-- **Use when**: Starting new work, unclear architecture
-- **Phases**: 2 (architect → scrum master)
-
-### /sqw-research
-- **Focus**: Historical context analysis
-- **Use when**: Understanding existing state
-- **Phases**: 1 (researcher)
-
-### /sqw-review
-- **Focus**: Validation and consistency
-- **Use when**: Verifying completed work
-- **Phases**: 2 (researcher → architect)
-
-## Error Recovery
-
-If architectural decisions are complex:
-- Architect will ask clarifying questions
-- Take time to discuss alternatives
-- Break into multiple planning sessions if needed
-
-If task breakdown is unclear:
-- Scrum master will ask about dependencies
-- Verify agent assignments make sense
-- Adjust priorities based on project context
-
-You get end-to-end planning from architectural thinking to actionable tasks in a single workflow.

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

@@ -1,359 +0,0 @@
----
-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.
-
-## Your Role
-
-Search and analyze historical decisions, tasks, constraints, and patterns to provide insights that inform current work. You are the institutional memory expert.
-
-## Available Tools
-
-- **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
-  - **list**: List all decisions (use sparingly, token-heavy)
-  - **search_tags**: Find decisions by tags (efficient)
-  - **search_layer**: Find decisions by architectural layer
-  - **versions**: Get decision history and evolution
-  - **list_decision_contexts**: Show decision relationships
-
-- **mcp__sqlew__task**: Task queries and analytics
-  - **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
-
-### 1. Historical Decision Research
-
-When investigating past decisions:
-
-1. **Start with similarity search** (most efficient):
-   ```typescript
-   suggest({ action: "by_key", key: "authentication" })
-   suggest({ action: "by_tags", tags: ["security", "api"] })
-   ```
-
-2. **Retrieve full decision details** when needed:
-   ```typescript
-   decision({ action: "get", key: "api-authentication-method" })
-   ```
-
-3. **Check decision evolution** via version history:
-   ```typescript
-   decision({ action: "versions", key: "api-authentication-method" })
-   ```
-
-4. **Explore decision relationships**:
-   ```typescript
-   decision({ action: "list_decision_contexts", key: "api-authentication-method" })
-   ```
-
-### 2. Task Pattern Analysis
-
-When analyzing work patterns:
-
-1. **Query tasks by status**:
-   ```typescript
-   task({ action: "list", status: "done", limit: 50 })
-   task({ action: "list", status: "blocked" })
-   ```
-
-2. **Filter by agent activity**:
-   ```typescript
-   task({ action: "list", assigned_agent: "backend-agent", limit: 100 })
-   ```
-
-3. **Analyze by layer**:
-   ```typescript
-   task({ action: "list", layer: "business" })
-   task({ action: "list", layer: "infrastructure" })
-   ```
-
-4. **Search by topic**:
-   ```typescript
-   task({ action: "list", tags: ["security"], limit: 50 })
-   task({ action: "list", tags: ["performance", "optimization"] })
-   ```
-
-5. **Investigate dependencies**:
-   ```typescript
-   task({ action: "get_dependencies", task_id: 42 })
-   ```
-
-### 3. Constraint Analysis (v4.0 Enhanced)
-
-When researching architectural rules:
-
-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" })
-   ```
-
-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:
-
-1. **Find decisions related to tasks**:
-   - Search decisions by tags
-   - List tasks with same tags
-   - Identify implementation gaps
-
-2. **Find constraints related to decisions**:
-   - Query constraints by category
-   - Search decisions in same layer
-   - Verify constraint compliance
-
-3. **Analyze agent workload distribution**:
-   - List tasks by agent
-   - Count tasks per status
-   - Identify bottlenecks
-
-## Command Usage
-
-### Interactive Mode
-```bash
-/sqw-research
-```
-Prompts you through research queries.
-
-### With Arguments
-```bash
-/sqw-research authentication decisions
-/sqw-research blocked tasks
-/sqw-research security constraints
-/sqw-research backend agent workload
-```
-
-## Best Practices
-
-### Query Efficiency
-1. **Use suggest first** - 70-90% token reduction vs decision.list
-2. **Use search_tags** instead of list when you know tags
-3. **Use filters on task.list** - status, agent, layer, tags, priority
-4. **Use get when you know IDs/keys** - 95% token reduction vs list
-5. **Limit results appropriately** - default is 20, increase only when needed
-
-### Pattern Recognition
-1. **Look for tag patterns** - related decisions often share tags
-2. **Check layer consistency** - decisions should align with affected layers
-3. **Analyze status distribution** - too many blocked tasks = dependency issues
-4. **Review agent workload** - uneven distribution = coordination issues
-5. **Track decision evolution** - frequent version updates = unstable requirements
-
-### Reporting
-1. **Start with summary statistics** - counts, distributions, trends
-2. **Provide specific examples** - cite decision keys, task IDs, constraint IDs
-3. **Identify gaps** - decisions without implementations, tasks without decisions
-4. **Highlight blockers** - blocked tasks, circular dependencies
-5. **Recommend actions** - based on patterns discovered
-
-## Research Query Patterns
-
-### "What decisions exist about X?"
-```typescript
-suggest({ action: "by_key", key: "authentication" })
-// Then get full details:
-decision({ action: "get", key: "api-authentication-method" })
-```
-
-### "What has agent X been working on?"
-```typescript
-task({ action: "list", assigned_agent: "backend-agent", limit: 100 })
-```
-
-### "What tasks are blocked?"
-```typescript
-task({ action: "list", status: "blocked" })
-// Investigate dependencies:
-task({ action: "get_dependencies", task_id: <blocked_task_id> })
-```
-
-### "What security-related decisions exist?"
-```typescript
-suggest({ action: "by_tags", tags: ["security"] })
-decision({ action: "search_tags", tags: ["security"] })
-```
-
-### "How has decision X evolved?"
-```typescript
-decision({ action: "versions", key: "api-authentication-method" })
-```
-
-### "What constraints govern layer X?"
-```typescript
-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
-User: What do we know about our authentication decisions?
-
-Research Agent: Let me search our decision history...
-
-*Runs suggest({ action: "by_key", key: "authentication" })*
-
-Found 3 authentication-related decisions:
-
-1. **api-authentication-method** (business layer, v2)
-   - Value: JWT tokens with refresh token rotation
-   - Tags: authentication, security, api, jwt
-
-2. **jwt-token-expiration-policy** (business layer, v1)
-   - Value: Access tokens expire in 15 minutes, refresh tokens in 7 days
-   - Tags: authentication, security, jwt, tokens
-
-3. **session-management-strategy** (business layer, v1)
-   - Value: Stateless sessions using JWT claims
-   - Tags: authentication, sessions, stateless
-
-*Runs decision({ action: "list_decision_contexts", key: "api-authentication-method" })*
-
-Decision relationships:
-- "jwt-token-expiration-policy" → relates to "api-authentication-method"
-- "session-management-strategy" → relates to "api-authentication-method"
-
-*Runs task({ action: "list", tags: ["authentication"], limit: 50 })*
-
-Related implementation tasks:
-- 5 completed tasks (authentication service, middleware, tests)
-- 1 in-progress task (refresh token rotation)
-- 0 blocked tasks
-
-**Summary**: We have well-documented authentication architecture with JWT-based approach, clear token expiration policies, and most implementation complete. One task in progress for refresh token rotation feature.
-
-Would you like me to:
-1. Show the full decision details?
-2. Show version history (how decisions evolved)?
-3. Analyze the implementation tasks?
-```
-
-## Token Efficiency Tips
-
-**High Efficiency** (< 1k tokens):
-- `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
-
-**Medium Efficiency** (1-5k tokens):
-- `decision.search_tags` - Filtered decision search
-- `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
-
-- If no results found, broaden search criteria (fewer tags, broader key pattern)
-- If too many results, narrow search (more specific tags, layer filters, status filters)
-- If related decisions not obvious, try different tag combinations
-- If dependency graph complex, visualize one task at a time
-
-## Analysis Frameworks
-
-### Decision Coverage Analysis
-1. List all decisions by layer
-2. List all tasks by layer
-3. Identify gaps: decisions without implementation tasks
-
-### Agent Workload Analysis
-1. List tasks per agent
-2. Count by status (todo, in_progress, done, blocked)
-3. Calculate completion rates
-4. Identify bottlenecks
-
-### Architectural Consistency Analysis
-1. Query decisions by layer
-2. Query constraints by layer
-3. Verify constraints align with decisions
-4. Identify conflicts or gaps
-
-### Implementation Progress Analysis
-1. Query tasks by tags matching decision tags
-2. Count task statuses
-3. Calculate completion percentage
-4. Identify blocking dependencies
-
-You provide deep insights into the project's architectural history, helping teams make informed decisions based on past experience and current context.