sqlew 4.0.2 → 4.0.3

package/docs/SPECIALIZED_AGENTS.md

@@ -1,88 +1,126 @@
-# Specialized Agents for sqlew
+# Specialized Agents (Deprecated)
 
-Claude Code agents that leverage sqlew's context management for development workflows.
+**Status**: Deprecated as of v4.1.0 - Replaced by unified `/sqlew` command
 
-## Usage
+This document is kept for reference. For current usage, see [SLASH_COMMANDS.md](SLASH_COMMANDS.md).
 
-Agents are **automatically invoked via slash commands**. See [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for the standard workflow:
+---
 
-```
-/sqw-plan → /sqw-scrum → /sqw-review
-```
+## Migration to /sqlew Command
 
-Direct invocation is also available with the `@` prefix:
+As of v4.1.0, the custom agent system has been superseded by the unified `/sqlew` command with automatic intent detection.
+
+### Old Approach (v4.0 and earlier)
 
 ```bash
+# Custom agents
 @sqlew-scrum-master "Create sprint plan"
 @sqlew-researcher "Find auth decisions"
 @sqlew-architect "Document OAuth2 decision"
 ```
 
----
+### New Approach (v4.1.0+)
 
-## Available Agents
-
-| Agent | Role | Model | Slash Command |
-|-------|------|-------|---------------|
-| **Scrum Master** | Task coordination, sprint planning, dependency management | Sonnet | `/sqw-scrum`, `/sqw-plan` |
-| **Researcher** | Query history, analyze patterns, find related decisions | Sonnet | `/sqw-research`, `/sqw-review` |
-| **Architect** | Document decisions, create constraints, validate compliance | Sonnet | `/sqw-documentor`, `/sqw-secretary`, `/sqw-plan`, `/sqw-review` |
+```bash
+# Unified command with intent detection
+/sqlew plan sprint implementation
+/sqlew search for auth decisions
+/sqlew record OAuth2 decision for authentication
+```
 
 ---
 
-## Agent Roles
+## Historical Agent System
 
-### Scrum Master (`sqlew-scrum-master`)
+For reference, the v4.0.0 system included:
 
-**Purpose**: Multi-agent coordination, task management, sprint planning
+| Agent | Role | Purpose |
+|-------|------|---------|
+| **Scrum Master** | Task coordination, sprint planning | Multi-agent task coordination |
+| **Researcher** | Query history, analyze patterns | Decision and constraint queries |
+| **Architect** | Document decisions, enforce constraints | Architectural decision documentation |
 
-- Creates tasks with dependencies
-- Coordinates parallel work
-- Tracks sprint progress
-- Detects stale tasks and blockers
+### Why the Change?
 
-### Researcher (`sqlew-researcher`)
+1. **Unified Interface**: Single `/sqlew` command instead of remembering three agent names
+2. **Automatic Intent Detection**: Command analyzes input and selects appropriate MCP tool
+3. **Natural Language**: No need to know about "agents" - just describe what you want
+4. **Better Discoverability**: One command in autocomplete instead of three agent references
+5. **Token Efficiency**: Reduced context overhead from agent system
 
-**Purpose**: Query historical context, analyze patterns
+---
 
-- Searches decisions by tags, layers, keys
-- Retrieves constraint rationale
-- Cross-references decisions ↔ tasks ↔ files
-- Tracks decision version history
+## Current Architecture (v4.1.0+)
 
-### Architect (`sqlew-architect`)
+The `/sqlew` command provides all the functionality of the previous agent system:
 
-**Purpose**: Document decisions, enforce constraints
+- **Intent Analysis** (replaces agent role selection)
+- **MCP Tool Invocation** (replaces direct agent calls)
+- **Automatic Routing** (replaces manual agent selection)
 
-- Creates rich decision records (rationale, alternatives, tradeoffs)
-- Establishes constraints linked to decisions
-- Validates architectural compliance
-- Uses decision-making frameworks
+See [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for current usage patterns.
 
 ---
 
-## Configuration
+## Configuration (Legacy - Not Used in v4.1.0+)
 
-Agents are configured in `.sqlew/config.toml`:
+The following configuration was used in v4.0 and is no longer applicable:
 
 ```toml
+# DEPRECATED - v4.0.0 and earlier
 [agents]
 scrum_master = true
 researcher = true
 architect = true
 ```
 
-**Recommendation**: Use all three agents. They are complementary specialists designed to work together via slash commands.
+All agent functionality is now handled by the `/sqlew` command with no additional configuration needed.
 
 ---
 
 ## Related Documentation
 
-- [SLASH_COMMANDS.md](SLASH_COMMANDS.md) - Standard workflow with slash commands
-- [TASK_OVERVIEW.md](TASK_OVERVIEW.md) - Task management overview
-- [DECISION_CONTEXT.md](DECISION_CONTEXT.md) - Decision documentation
+- [SLASH_COMMANDS.md](SLASH_COMMANDS.md) - Current `/sqlew` command documentation
+- [TOOL_REFERENCE.md](TOOL_REFERENCE.md) - MCP tools (underlying infrastructure)
+- [AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md) - Guidelines for AI agents using sqlew
+
+---
+
+## Legacy Reference
+
+### Scrum Master (Historical)
+
+**Purpose**: Multi-agent coordination, task management, sprint planning
+
+Provided by `/sqlew` commands:
+```bash
+/sqlew plan <feature>        # Replace: /sqw-scrum plan
+/sqlew execute              # Replace: /sqw-scrum implement
+```
+
+### Researcher (Historical)
+
+**Purpose**: Query historical context, analyze patterns
+
+Provided by `/sqlew` commands:
+```bash
+/sqlew search <topic>       # Replace: /sqw-research
+```
+
+### Architect (Historical)
+
+**Purpose**: Document decisions, enforce constraints
+
+Provided by `/sqlew` commands:
+```bash
+/sqlew record <decision>    # Replace: /sqw-secretary
+/sqlew update <decision>    # Replaces modifications
+```
 
 ---
 
-**Version:** 4.0.0
-**Last Updated:** 2025-11-27
+**Version**: 4.1.0
+**Status**: Deprecated
+**Last Updated**: 2025-12-04
+
+See [SLASH_COMMANDS.md](SLASH_COMMANDS.md) for current documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlew",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "MCP server that gives AI agents a shared SQL-backed context repository for decisions, constraints, and tasks",
   "main": "dist/index.js",
   "type": "module",

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

@@ -1,204 +0,0 @@
----
-description: Records architectural decisions and constraints with full context (rationale, alternatives, tradeoffs)
----
-
-# Sqlew Documentor Workflow
-
-Decision documentation workflow for recording architectural decisions and constraints with full context.
-
-## Agent Invocation
-
-This workflow uses the specialized sqlew-architect agent:
-
-```
-Task tool → subagent_type: "sqlew-architect" (opus)
-```
-
-**Example:**
-```typescript
-Task({
-  subagent_type: "sqlew-architect",
-  prompt: "Document the following architectural decision: [decision topic]. Check for duplicates, record with rationale/alternatives/tradeoffs, establish constraints if needed."
-})
-```
-
----
-
-**Agent Instructions (for sqlew-architect):**
-
-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 items before creating new ones (v4.0)
-  - **Decision search** (default: `target: "decision"`): by_key, by_tags, by_context, check_duplicate
-  - **Constraint search** (`target: "constraint"`): by_text, by_tags, by_context, check_duplicate
-- **mcp__sqlew__decision**: Record decisions with rich context (set, get, list, search_tags, search_layer, versions, add_decision_context)
-  - **Note**: `decision.set` automatically suggests related constraints (v4.0)
-- **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 (v4.0 Enhanced)
-
-When establishing architectural constraints:
-
-1. **Check for duplicates/similar constraints** using `suggest` (NEW in v4.0):
-   ```typescript
-   suggest({ action: "check_duplicate", target: "constraint", text: "All API endpoints must verify JWT" })
-   suggest({ action: "by_text", target: "constraint", text: "authentication required" })
-   suggest({ action: "by_tags", target: "constraint", tags: ["security", "api"] })
-   ```
-
-2. **Discuss options** with the user if similar constraints exist
-
-3. **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"]
-   })
-   ```
-
-4. **Link constraints to decisions** when they enforce architectural choices
-
-**Note**: When you create a decision using `decision.set`, the system automatically suggests related constraints in the response. Review these suggestions and link relevant constraints.
-
-## Command Usage
-
-### Interactive Mode
-```bash
-/sqw-documentor
-```
-Prompts you through the decision/constraint workflow.
-
-### With Arguments
-```bash
-/sqw-documentor document API authentication decision
-/sqw-documentor create constraint for database access patterns
-```
-
-## Best Practices
-
-1. **Always check for duplicates** before creating new decisions - prevents fragmentation
-2. **Always check for duplicate constraints** (v4.0) - use `suggest` with `target: "constraint"` before creating
-3. **Use descriptive keys** - kebab-case, 64 chars max (e.g., "api-authentication-method")
-4. **Document rationale thoroughly** - future developers need to understand WHY
-5. **Include alternatives considered** - shows the decision was thoughtful
-6. **Be honest about tradeoffs** - every decision has costs
-7. **Tag comprehensively** - enables discovery via search
-8. **Use appropriate layers** - helps organize decisions by architectural concern
-9. **Link related decisions** - builds decision context graph
-10. **Review related_constraints** (v4.0) - decision.set returns suggested constraints, review and link
-11. **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 `suggest` with `target: "constraint"` to avoid duplicate constraints (v4.0)
-- 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)
-- Review `related_constraints` in decision.set response (saves separate constraint queries)
-- Batch related constraints when establishing multiple rules
-
-## Error Handling
-
-- If duplicate detection finds similar decisions, ALWAYS discuss with user before proceeding
-- If similar constraints found (v4.0), discuss whether to reuse, modify, or create new
-- If constraint conflicts with existing constraint, flag and discuss resolution
-- If decision key already exists, offer to create new version or update context
-- If `related_constraints` returned by decision.set, review and link relevant ones
-
-You maintain architectural consistency across the project by ensuring decisions are well-documented, constraints are clear, and nothing is duplicated unnecessarily.