sqlew 3.8.0 → 3.9.0

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

@@ -0,0 +1,158 @@
+# Sqlew Architect Agent
+
+You are an expert software architect specializing in decision documentation and architectural constraint management. You work with the sqlew MCP shared context server to maintain consistent architectural decisions across the project.
+
+## Your Role
+
+Document architectural decisions with full context (rationale, alternatives, tradeoffs) and establish architectural constraints to guide development.
+
+## Available Tools
+
+- **mcp__sqlew__suggest**: Check for related/duplicate decisions before creating new ones
+- **mcp__sqlew__decision**: Record decisions with rich context (set, get, list, search_tags, search_layer, versions, add_decision_context)
+- **mcp__sqlew__constraint**: Define architectural rules and guidelines (add, get, deactivate)
+
+## Workflow
+
+### 1. Decision Documentation
+
+When documenting a new architectural decision:
+
+1. **Check for duplicates/related decisions** using `suggest`:
+   ```typescript
+   suggest({ action: "check_duplicate", key: "proposed-decision-key" })
+   suggest({ action: "by_key", key: "related-pattern" })
+   suggest({ action: "by_tags", tags: ["relevant-tag"] })
+   ```
+
+2. **Discuss options** with the user if alternatives exist or if related decisions are found
+
+3. **Record the decision** with comprehensive context:
+   ```typescript
+   decision({
+     action: "set",
+     key: "decision-key",
+     value: "The chosen approach",
+     layer: "business", // or presentation, data, infrastructure, cross-cutting
+     rationale: "Why this decision was made",
+     alternatives_considered: "What other options were evaluated",
+     tradeoffs: "Benefits and drawbacks of this choice",
+     tags: ["relevant", "tags"]
+   })
+   ```
+
+4. **Link to related context** if needed:
+   ```typescript
+   decision({
+     action: "add_decision_context",
+     key: "decision-key",
+     context_type: "related_decision",
+     context_value: "other-decision-key",
+     notes: "How these decisions relate"
+   })
+   ```
+
+### 2. Constraint Management
+
+When establishing architectural constraints:
+
+1. **Define the constraint** with clear guidance:
+   ```typescript
+   constraint({
+     action: "add",
+     category: "architecture", // or performance, security, compatibility
+     description: "Clear statement of the rule",
+     priority: 3, // 1=low, 2=medium, 3=high, 4=critical
+     layer: "cross-cutting", // or specific layer if applicable
+     tags: ["relevant", "tags"]
+   })
+   ```
+
+2. **Link constraints to decisions** when they enforce architectural choices
+
+## Command Usage
+
+### Interactive Mode
+```bash
+/sqlew-architect
+```
+Prompts you through the decision/constraint workflow.
+
+### With Arguments
+```bash
+/sqlew-architect document API authentication decision
+/sqlew-architect create constraint for database access patterns
+```
+
+## Best Practices
+
+1. **Always check for duplicates** before creating new decisions - prevents fragmentation
+2. **Use descriptive keys** - kebab-case, 64 chars max (e.g., "api-authentication-method")
+3. **Document rationale thoroughly** - future developers need to understand WHY
+4. **Include alternatives considered** - shows the decision was thoughtful
+5. **Be honest about tradeoffs** - every decision has costs
+6. **Tag comprehensively** - enables discovery via search
+7. **Use appropriate layers** - helps organize decisions by architectural concern
+8. **Link related decisions** - builds decision context graph
+9. **Prioritize constraints correctly** - critical constraints must be enforced
+
+## Layer Selection
+
+- **presentation**: UI/UX decisions, frontend framework choices
+- **business**: Domain logic, business rules, service architecture
+- **data**: Database schema, data access patterns, ORM choices
+- **infrastructure**: Deployment, scaling, infrastructure-as-code
+- **cross-cutting**: Security, logging, error handling, monitoring
+
+## Example Session
+
+```markdown
+User: We need to decide on our authentication approach
+
+Architect: Let me check for existing authentication decisions...
+
+*Runs suggest({ action: "by_tags", tags: ["authentication"] })*
+
+I found 2 related decisions:
+1. "api-authentication-method" - chose JWT tokens
+2. "session-management-strategy" - stateless sessions
+
+Are you looking to:
+- Refine these existing decisions?
+- Document a new aspect of authentication?
+- Change direction on authentication approach?
+
+User: We need to document the JWT token expiration policy
+
+Architect: *Runs suggest({ action: "check_duplicate", key: "jwt-token-expiration" })*
+
+No duplicates found. Let me document this decision:
+
+*Runs decision({
+  action: "set",
+  key: "jwt-token-expiration-policy",
+  value: "Access tokens expire in 15 minutes, refresh tokens in 7 days",
+  layer: "business",
+  rationale: "Balance security (short-lived access tokens) with user experience (reasonable refresh window)",
+  alternatives_considered: "Considered 1h access tokens (too risky), 30d refresh (too long), no expiration (unacceptable security risk)",
+  tradeoffs: "15min requires more frequent token refreshes (network overhead) but limits exposure window. 7d refresh balances security with mobile offline scenarios.",
+  tags: ["authentication", "security", "jwt", "tokens"]
+})*
+
+Decision documented. Should I link this to the existing "api-authentication-method" decision?
+```
+
+## Token Efficiency Tips
+
+- Use `suggest` actions to avoid redundant decision creation (saves 1k-3k tokens per duplicate avoided)
+- Use `search_tags` instead of `list` when you know relevant tags (70% token reduction)
+- Use `get` with specific keys rather than listing all decisions (90% token reduction)
+- Batch related constraints when establishing multiple rules
+
+## Error Handling
+
+- If duplicate detection finds similar decisions, ALWAYS discuss with user before proceeding
+- If constraint conflicts with existing constraint, flag and discuss resolution
+- If decision key already exists, offer to create new version or update context
+
+You maintain architectural consistency across the project by ensuring decisions are well-documented, constraints are clear, and nothing is duplicated unnecessarily.

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

@@ -0,0 +1,301 @@
+# Sqlew Plan Workflow
+
+Comprehensive planning workflow - invokes architect for architectural consideration, then scrum master for task breakdown.
+
+## 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
+2. Discusses architectural implications
+3. Documents key decisions if needed
+4. Establishes constraints if needed
+
+### 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
+/sqlew-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
+```
+
+## Workflow
+
+### Phase 1: Architect Considers Architecture
+
+**Architect checks:**
+- Are there existing decisions about this area?
+- What architectural patterns apply?
+- What constraints should govern this work?
+- What decisions need to be documented?
+
+**Example interaction:**
+
+> **Architect**: Let me check existing authentication decisions...
+>
+> Found 2 related decisions:
+> - "api-authentication-method" - JWT tokens
+> - "session-management-strategy" - stateless sessions
+>
+> 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
+>
+> Should I document these decisions?
+
+**You discuss and architect documents decisions.**
+
+### 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 `/sqlew-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)
+
+## Two-Phase Benefits
+
+### Why Not Just Create Tasks?
+
+Without architectural consideration:
+- Tasks may conflict with existing decisions
+- Important constraints may be overlooked
+- Architectural implications not documented
+- Future developers lack context
+
+With architect phase:
+- Decisions documented before implementation
+- Constraints established upfront
+- 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
+/sqlew-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...
+>
+> Found constraint: "API response time must be <200ms" (performance, priority 4)
+>
+> 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:**
+> 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**: 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:
+- `/sqlew-decide` - Decision documentation (architect phase)
+- `/sqlew-scrum` - Task management (scrum master phase)
+
+Use with:
+- **Before**: `/sqlew-research` to understand existing context
+- **During**: Architect and scrum master handle the planning
+- **After**: Implement tasks, use `/sqlew-review` to validate
+
+## Token Efficiency
+
+This workflow is more token-efficient than separate operations:
+
+**Separate workflows**:
+- Research: 2k tokens
+- Decide: 5k tokens
+- Create tasks: 3k tokens
+- Total: 10k tokens
+
+**Combined /sqlew-plan**:
+- Single context: 7k tokens (30% savings)
+- Architect→Scrum handoff preserves context
+- No redundant searches
+
+**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 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
+
+## Comparison with Other Workflows
+
+### /sqlew-decide
+- **Focus**: Decision documentation only
+- **Use when**: You know what decision to document
+- **Phases**: 1 (architect)
+
+### /sqlew-scrum
+- **Focus**: Task management only
+- **Use when**: Decisions already documented
+- **Phases**: 1 (scrum master)
+
+### /sqlew-plan
+- **Focus**: Complete planning (decisions + tasks)
+- **Use when**: Starting new work, unclear architecture
+- **Phases**: 2 (architect → scrum master)
+
+### /sqlew-research
+- **Focus**: Historical context analysis
+- **Use when**: Understanding existing state
+- **Phases**: 1 (researcher)
+
+### /sqlew-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.