sqlew 3.8.1 → 3.9.0

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

@@ -0,0 +1,298 @@
+# Sqlew Research Agent
+
+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
+  - **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__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, agent, 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
+
+## 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
+
+When researching architectural rules:
+
+1. **Query by category**:
+   ```typescript
+   constraint({ action: "get", category: "security" })
+   constraint({ action: "get", category: "performance" })
+   ```
+
+2. **Check specific constraint**:
+   ```typescript
+   constraint({ action: "get", constraint_id: 5 })
+   ```
+
+### 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
+/sqlew-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
+```
+
+## 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" })
+```
+
+## 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
+- `suggest.by_tags` - Tag-based discovery
+- `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
+
+**Low Efficiency** (5k+ tokens, use sparingly):
+- `decision.list` - All decisions (use only when necessary)
+- `task.list` without filters - All tasks (use only when necessary)
+
+## 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.

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

@@ -0,0 +1,340 @@
+# Sqlew Review Workflow
+
+Validation and consistency checking workflow - invokes researcher for context analysis, then architect for validation.
+
+## Purpose
+
+Verify architectural consistency, validate decision implementation, and ensure constraints are followed. A two-phase workflow combining historical analysis with expert validation.
+
+## What It Does
+
+### 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
+
+### Phase 2: Architectural Validation (Architect Agent)
+1. Reviews research findings
+2. Validates decision consistency
+3. Checks constraint compliance
+4. Recommends corrections or updates
+5. Documents new decisions if needed
+
+## Usage
+
+### Interactive Mode
+```bash
+/sqlew-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
+```
+
+## Workflow
+
+### Phase 1: Researcher Analyzes Context
+
+**Researcher examines:**
+- Related decisions and their versions
+- Relevant constraints
+- Implementation tasks (completed, in-progress, blocked)
+- Cross-references and relationships
+
+**Example interaction:**
+
+> **Researcher**: Analyzing authentication implementation...
+>
+> **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)
+>
+> **Implementation Tasks** (8):
+> - ✅ 6 completed: JWT service, middleware, token rotation, tests
+> - ⏳ 1 in-progress: Add OAuth2 social login
+> - ❌ 1 blocked: None
+>
+> **Potential Issues Detected**:
+> 1. Decision "jwt-token-expiration-policy" doesn't mention refresh token rotation, but constraint requires it
+> 2. OAuth2 task not linked to authentication decisions
+> 3. No constraint for OAuth2 token-to-JWT mapping
+>
+> Handing off to architect for validation...
+
+### Phase 2: Architect Validates
+
+**Architect reviews findings:**
+
+> **Architect**: Reviewing authentication consistency...
+>
+> **Issue 1: Decision-Constraint Mismatch**
+> - Decision: "jwt-token-expiration-policy" (missing rotation details)
+> - Constraint: "Token refresh must use rotation strategy" (requires rotation)
+> - **Action**: Update decision to include rotation strategy, or document as separate decision
+>
+> **Issue 2: Missing Task Links**
+> - Task: "Add OAuth2 social login" (in-progress)
+> - Missing link to: "api-authentication-method" decision
+> - **Action**: Link task to decision for traceability
+>
+> **Issue 3: Missing OAuth2 Constraint**
+> - OAuth2 implementation starting
+> - No constraint for token mapping strategy
+> - **Action**: Create constraint "OAuth2 tokens must be converted to internal JWT format"
+>
+> **Recommendations**:
+> 1. Version "jwt-token-expiration-policy" to v2 with rotation details
+> 2. Link OAuth2 task to authentication decisions
+> 3. Create OAuth2-to-JWT mapping constraint
+> 4. Consider documenting OAuth2 provider selection as decision
+>
+> Should I implement these recommendations?
+
+## When to Use
+
+Use `/sqlew-review` when:
+- Verifying implementation follows decisions
+- Checking architectural consistency
+- Auditing constraint compliance
+- Validating completed work
+- 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)
+
+## Review Types
+
+### Decision Consistency Review
+Verify decisions are:
+- Complete and well-documented
+- Consistent with each other
+- Implemented by tasks
+- Compliant with constraints
+- Properly versioned
+
+### Implementation Review
+Verify tasks:
+- Linked to decisions they implement
+- Following constraint guidelines
+- Properly prioritized
+- Not blocked unnecessarily
+- Completed work matches decisions
+
+### Constraint Compliance Review
+Verify constraints are:
+- Clear and actionable
+- Reflected in decisions
+- Enforced by task acceptance criteria
+- Not conflicting with each other
+- Appropriate priority level
+
+### Agent Workload Review
+Verify agents have:
+- Balanced workload
+- Clear task assignments
+- No prolonged blocked tasks
+- Consistent work patterns
+- Appropriate expertise matches
+
+## Example: Complete Review Session
+
+```bash
+/sqlew-review security architecture
+```
+
+### Phase 1: Researcher
+
+> **Researcher**: Analyzing security architecture...
+>
+> **Security Decisions** (5):
+> 1. "api-authentication-method" - JWT tokens
+> 2. "api-authorization-approach" - role-based access control
+> 3. "password-hashing-algorithm" - bcrypt with work factor 12
+> 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 Tasks** (12 total):
+> - ✅ 9 completed
+> - ⏳ 2 in-progress: HTTPS redirect middleware, CSP configuration
+> - ❌ 1 blocked: Security audit (waiting for external auditor)
+>
+> **Cross-Layer Analysis**:
+> - Presentation: 3 tasks (HTTPS, CSP, HSTS)
+> - Business: 4 tasks (auth, authz, password hashing)
+> - Cross-cutting: 5 tasks (security middleware, logging)
+>
+> **Findings**:
+> 1. ✅ All decisions have implementing tasks
+> 2. ✅ All constraints aligned with decisions
+> 3. ⚠️ CSP configuration task in-progress for 5 days (possible stale)
+> 4. ⚠️ No decision documented for session timeout policy
+> 5. ⚠️ HTTPS redirect task not linked to "https-enforcement-strategy" decision
+>
+> Handing to architect for validation...
+
+### Phase 2: Architect
+
+> **Architect**: Security architecture validation...
+>
+> **Overall Assessment**: Strong security foundation with minor gaps
+>
+> **Issue 1: Stale CSP Configuration Task**
+> - Task in-progress for 5 days without updates
+> - **Action**: Check if task is blocked, move to waiting_review, or reassign
+>
+> **Issue 2: Missing Session Timeout Decision**
+> - Multiple authentication decisions but no session timeout policy
+> - Constraint: "All API endpoints must verify authentication" implies timeout needed
+> - **Action**: Document "session-timeout-policy" decision
+>
+> **Issue 3: Missing Task Link**
+> - HTTPS redirect task not linked to HTTPS enforcement decision
+> - **Action**: Link task to decision for traceability
+>
+> **Issue 4: Password Reset Security Not Addressed**
+> - Password hashing documented but not reset/recovery security
+> - **Action**: Consider documenting "password-reset-security" decision
+>
+> **Constraint Compliance**: ✅ All active
+> - Password hashing: ✅ Implemented (bcrypt work factor 12)
+> - Authentication verification: ✅ Middleware in place
+> - HTTPS enforcement: ⏳ In progress (nearly complete)
+> - Security headers: ⏳ In progress (CSP configuration)
+>
+> **Recommendations**:
+> 1. Investigate CSP configuration task (5 days stale)
+> 2. Document session timeout policy decision
+> 3. Link HTTPS redirect task to enforcement decision
+> 4. Consider password reset security decision
+> 5. Create constraint for session timeout after decision documented
+>
+> **Priority Actions** (next 24 hours):
+> 1. Check CSP task status (possibly blocked?)
+> 2. Document session timeout decision (closes security gap)
+>
+> Should I implement these recommendations?
+
+## Integration with Other Workflows
+
+This workflow combines:
+- `/sqlew-research` - Context analysis (researcher phase)
+- `/sqlew-decide` - Decision updates (architect phase)
+
+Use with:
+- **Before review**: Complete implementation work
+- **During review**: Researcher → architect validation
+- **After review**: Implement recommendations, create corrective tasks
+
+## Token Efficiency
+
+This workflow is efficient for comprehensive validation:
+
+**Manual validation**:
+- Query decisions: 3k tokens
+- Query constraints: 2k tokens
+- Query tasks: 4k tokens
+- Cross-reference: 2k tokens
+- Validate: 3k tokens
+- Total: 14k tokens
+
+**Combined /sqlew-review**:
+- Research phase: 6k tokens (automated queries)
+- Architect phase: 4k tokens (validation)
+- **Total**: 10k tokens (30% savings)
+
+**Estimated Token Usage**: 10,000-20,000 tokens per review session
+
+**AI Time Estimate**:
+- Research phase: 10-20 minutes
+- Architect phase: 15-25 minutes
+- **Total**: 25-45 minutes
+
+## Review Checklist
+
+The workflow automatically checks:
+
+### Decision Quality
+- [ ] Key decisions documented
+- [ ] Rationale provided
+- [ ] Alternatives considered
+- [ ] Tradeoffs acknowledged
+- [ ] Properly tagged
+- [ ] Appropriate layer assigned
+
+### Decision Consistency
+- [ ] No conflicting decisions
+- [ ] Versions tracked properly
+- [ ] Related decisions linked
+- [ ] Decision context complete
+
+### Implementation Coverage
+- [ ] Decisions have implementing tasks
+- [ ] Tasks linked to decisions
+- [ ] Acceptance criteria match decisions
+- [ ] No orphaned implementations
+
+### Constraint Compliance
+- [ ] Constraints documented
+- [ ] Constraints aligned with decisions
+- [ ] Tasks follow constraints
+- [ ] Priorities appropriate
+
+### Task Health
+- [ ] No stale in-progress tasks
+- [ ] Blocked tasks have valid reasons
+- [ ] Dependencies logical
+- [ ] Agent assignments appropriate
+
+## Tips
+
+1. **Be specific about review scope** - "authentication" vs "entire security architecture"
+2. **Review regularly** - catch issues early (weekly for active projects)
+3. **Act on findings** - researcher + architect provide actionable recommendations
+4. **Document corrections** - update decisions when inconsistencies found
+5. **Link everything** - tasks ↔ decisions ↔ constraints for traceability
+
+## Review Triggers
+
+Consider running `/sqlew-review` when:
+- Completing a major feature
+- Before starting related work
+- After significant decision changes
+- Investigating quality issues
+- Onboarding new team members
+- Preparing for code review
+- Quarterly architecture audits
+
+## Error Recovery
+
+If research finds too many issues:
+- Break review into smaller scopes
+- Prioritize critical issues first
+- Create corrective tasks via scrum master
+- Schedule follow-up review
+
+If architect validation is unclear:
+- Request more specific research
+- Break complex issues into sub-reviews
+- Consult original decision authors
+- Document uncertainty as new decision
+
+You get comprehensive validation combining data-driven research with expert architectural analysis.