solokit 0.1.1__py3-none-any.whl

solokit/templates/.claude/commands/work-update.md

@@ -0,0 +1,141 @@
+---
+description: Update work item fields
+argument-hint: <work_item_id> <field>
+---
+
+# Work Item Update
+
+Update a specific field of an existing work item using interactive UI.
+
+## Usage
+
+```
+/work-update <work_item_id> <field>
+```
+
+**Fields:** priority, milestone, add-dependency, remove-dependency
+
+**Note:** Status changes are NOT allowed via this command. Status is managed automatically by session workflow (/start sets to in_progress, /end sets to completed).
+
+**Examples:**
+```
+/work-update bug_timeout priority
+/work-update feature_search milestone
+/work-update integration_test_api add-dependency
+/work-update feature_dashboard remove-dependency
+```
+
+## Instructions
+
+1. **Parse arguments** from the command:
+   - First argument: `work_item_id` (required)
+   - Second argument: `field` (required)
+
+   **If either is missing:**
+   - Show error: "Usage: /work-update <work_item_id> <field>"
+   - Show valid fields: priority, milestone, add-dependency, remove-dependency
+   - Exit
+
+   **If field = "status":**
+   - Show error: "Status changes are not allowed via /work-update. Status is managed by session workflow (/start, /end)."
+   - Exit
+
+2. **Load and display current work item details** (optimized - fast metadata-only lookup):
+   - Use `python -m solokit.work_items.get_metadata <work_item_id>` for fast metadata retrieval
+   - This script reads ONLY the work item metadata from JSON, not the full spec file (much faster!)
+   - If work item doesn't exist: Show error and suggest using `/work-list` to see available items
+   - Display current values concisely:
+     ```
+     Current: {work_item_id}
+     - Type: {type}
+     - Status: {status}
+     - Priority: {priority}
+     - Milestone: {milestone or "(none)"}
+     - Dependencies: {dependencies or "(none)"}
+     ```
+
+3. **Ask for the new value** based on field specified (use `AskUserQuestion`):
+
+   **If field = "priority":**
+   - Question: "Select new priority for {work_item_id}:"
+   - Header: "Priority"
+   - Multi-select: false
+   - Options:
+     - Label: "critical", Description: "Blocking issue or urgent requirement"
+     - Label: "high", Description: "Important work to be done soon"
+     - Label: "medium", Description: "Normal priority work"
+     - Label: "low", Description: "Nice to have, can be deferred"
+
+   **If field = "milestone":**
+   - Question: "Enter milestone name for {work_item_id}:"
+   - Header: "Milestone"
+   - Multi-select: false
+   - Options (provide examples, user selects "Type something"):
+     - Label: "Sprint 1", Description: "Example milestone"
+     - Label: "Q1 2025", Description: "Example milestone"
+
+   **If field = "add-dependency":**
+   - Query `.session/tracking/work_items.json` for available work items
+   - Filter to show only: not_started, in_progress, or blocked items (exclude completed and self)
+   - **Smart filtering**: Filter by relevance based on work item's title (e.g., if updating "feature_auth_ui", show auth-related items)
+   - Question: "Select work items to add as dependencies for {work_item_id}: (Select multiple)"
+   - Header: "Dependencies"
+   - **Multi-select: true** (allows selecting multiple dependencies at once)
+   - Options: Show up to 4 most relevant work items (prioritize: not_started > in_progress > blocked):
+     - Label: "{work_item_id}", Description: "[{priority}] [{type}] {title} ({status})"
+   - Note: User can select "Type something" to manually enter comma-separated IDs
+
+   **If field = "remove-dependency":**
+   - Use `python -m solokit.work_items.get_metadata <work_item_id> --with-deps` to get dependency details
+   - This returns dependency IDs WITH their type and title in ONE efficient call!
+   - If no dependencies: Show error "Work item has no dependencies to remove"
+   - Question: "Select dependencies to remove from {work_item_id}: (Select multiple)"
+   - Header: "Remove"
+   - **Multi-select: true** (allows removing multiple dependencies at once)
+   - Options: Show all current dependencies with details:
+     - Label: "{dependency_id}", Description: "[{type}] {title} ({status})"
+
+4. **Execute the update**:
+
+   **For all fields:**
+   ```bash
+   sk work-update <work_item_id> --<field> <value>
+   ```
+
+   **For dependencies** (if multiple selected, join with commas):
+   ```bash
+   sk work-update <work_item_id> --add-dependency "dep1,dep2,dep3"
+   sk work-update <work_item_id> --remove-dependency "dep1,dep2"
+   ```
+
+   Examples:
+   ```bash
+   sk work-update bug_timeout --priority critical
+   sk work-update feature_search --milestone "Sprint 2"
+   sk work-update integration_test_api --add-dependency feature_api_client
+   sk work-update integration_test_api --add-dependency "feature_api,feature_db,bug_auth"
+   sk work-update feature_dashboard --remove-dependency "bug_css_layout,feature_old"
+   ```
+
+5. **Show the output** to the user, which includes:
+   - Confirmation of the update
+   - Old value → New value
+   - Update timestamp
+
+## Error Handling
+
+If the command fails:
+- **Missing arguments**: Show usage and valid fields
+- **Invalid work_item_id**: Show error and list available work items
+- **Status field specified**: Show error explaining status is managed by session workflow
+- **Invalid field**: Show error and list valid fields (priority, milestone, add-dependency, remove-dependency)
+- **Invalid field value**: Re-prompt with valid options
+- **Dependency doesn't exist**: Re-prompt with valid dependencies
+- **No dependencies to remove**: Show error with message
+
+## Notes
+
+- Updates are automatically tracked in the work item's update_history
+- Each update records timestamp and the changes made
+- Status changes to "completed" trigger completion metadata
+- The field argument uses hyphens (add-dependency, remove-dependency) matching the CLI flags

solokit/templates/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project setup with Session-Driven Development
+
+### Changed
+
+### Fixed
+
+### Removed

solokit/templates/WORK_ITEM_TYPES.md

@@ -0,0 +1,141 @@
+# Work Item Types
+
+This document defines the work item types supported by the Session-Driven Development plugin.
+
+## Standard Work Item Types
+
+### feature
+Standard feature development work items.
+- **Template:** Feature specification
+- **Typical sessions:** 2-4
+- **Validation:** Tests pass, linting pass, documentation updated
+
+### bug
+Bug fix work items.
+- **Template:** Bug report
+- **Typical sessions:** 1-2
+- **Validation:** Tests pass, regression tests added, root cause documented
+
+### refactor
+Code refactoring work items.
+- **Template:** Refactor plan
+- **Typical sessions:** 1-3
+- **Validation:** Tests pass, no functionality changes, code quality improved
+
+### security
+Security-focused work items for vulnerabilities, hardening, and compliance.
+- **Template:** `templates/security_task.md`
+- **Typical sessions:** 1-2
+- **Priority:** Critical (by default)
+- **Validation:**
+  - Security scan required
+  - Penetration testing (for critical issues)
+  - Security review completed
+  - No new vulnerabilities introduced
+
+**Usage:**
+```json
+{
+  "type": "security",
+  "title": "Fix SQL Injection in User Login",
+  "priority": "critical",
+  "validation_criteria": {
+    "security_scan_required": true,
+    "penetration_test": true,
+    "security_review": true
+  }
+}
+```
+
+## Integration & Deployment Types (Phase 1.8)
+
+### integration_test
+Integration testing work items that validate multiple components working together.
+- **Template:** `templates/integration_test_spec.md`
+- **Typical sessions:** 1-2
+- **Validation:**
+  - Integration tests pass
+  - End-to-end tests pass
+  - Performance benchmarks met
+  - API contracts validated
+- **Dependencies:** Required (must specify what components are being integrated)
+
+**Usage:**
+```json
+{
+  "type": "integration_test",
+  "title": "Test OAuth + User Profile Integration",
+  "dependencies": ["feature_oauth", "feature_profile"],
+  "validation_criteria": {
+    "integration_tests_pass": true,
+    "e2e_tests_pass": true,
+    "performance_benchmarks_met": true,
+    "api_contracts_validated": true
+  }
+}
+```
+
+### deployment
+Deployment work items for releasing code to environments.
+- **Template:** `templates/deployment_spec.md`
+- **Typical sessions:** 1
+- **Validation:**
+  - Deployment successful
+  - Smoke tests pass
+  - Monitoring operational
+  - Rollback tested
+  - Documentation updated
+- **Dependencies:** Required (must specify what features/fixes are being deployed)
+
+**Usage:**
+```json
+{
+  "type": "deployment",
+  "title": "Deploy v1.2.0 to Production",
+  "dependencies": ["feature_oauth", "feature_profile", "integration_test_auth"],
+  "validation_criteria": {
+    "deployment_successful": true,
+    "smoke_tests_pass": true,
+    "monitoring_operational": true,
+    "rollback_tested": true,
+    "documentation_updated": true
+  }
+}
+```
+
+## Validation Rules
+
+### All Types
+- Must have a title
+- Must have a type from the list above
+- Must have a status (not_started, in_progress, completed)
+- Must have a priority (critical, high, medium, low)
+
+### security
+- **Priority should be critical or high** - Security issues are high priority by default
+- **Security validation required** - Must pass security scans and reviews
+- **May require external review** - Security team or penetration testing
+
+### integration_test and deployment
+- **Must have dependencies** - Cannot be created without specifying dependencies
+- **Phase-specific validation** - Additional validation criteria enforced
+- **Typical workflow:**
+  1. Complete all dependent work items
+  2. Create integration_test to validate integration
+  3. Complete integration tests
+  4. Create deployment to deploy to environment
+  5. Complete deployment with smoke tests
+
+## Work Item Lifecycle
+
+```
+not_started → in_progress → completed
+     ↓              ↓
+  blocked      blocked
+```
+
+**Status definitions:**
+- `not_started` - Ready to begin, dependencies satisfied
+- `in_progress` - Currently being worked on
+- `blocked` - Waiting on dependency or external factor
+- `completed` - Work finished and validated

solokit/templates/__init__.py

@@ -0,0 +1 @@
+"""Templates for work item specs, configuration, and test setup."""

solokit/templates/bug_spec.md

@@ -0,0 +1,217 @@
+# Bug: [Bug Title]
+
+<!--
+TEMPLATE INSTRUCTIONS:
+- Replace [Bug Title] with a concise description of the bug
+- Fill out all sections with specific details
+- Include code snippets, error messages, and screenshots where relevant
+- Document your investigation process in Root Cause Analysis
+- Remove these instructions before finalizing the spec
+-->
+
+## Description
+
+<!-- Clear, concise description of the bug and its impact on users/system -->
+
+Clear description of the bug and its impact.
+
+**Example:**
+> User authentication fails intermittently when logging in from mobile devices. Users see a "Session expired" error even though they just created a new session. This affects approximately 15% of mobile login attempts based on error logs.
+
+## Steps to Reproduce
+
+<!-- Detailed steps that reliably reproduce the bug -->
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Example:**
+1. Open the app on a mobile device (iOS or Android)
+2. Navigate to the login screen
+3. Enter valid credentials (test@example.com / Test123!)
+4. Tap "Login"
+5. Observe the error message: "Session expired. Please try again."
+6. Repeat steps 3-4 several times
+7. Bug occurs roughly 1 in 7 attempts
+
+**Environment:**
+- Device: iPhone 14 Pro, Samsung Galaxy S23
+- OS Version: iOS 17.0, Android 13
+- App Version: 2.3.1
+- Network: WiFi and 5G tested
+
+## Expected Behavior
+
+<!-- What should happen when the user performs the steps above -->
+
+**Example:**
+> User should be successfully authenticated and redirected to the dashboard. A valid session cookie should be set and remain valid for 7 days or until the user logs out.
+
+## Actual Behavior
+
+<!-- What actually happens, including error messages, logs, screenshots -->
+
+**Example:**
+> User sees an error toast: "Session expired. Please try again."
+
+**Error Log:**
+```
+[ERROR] 2025-10-18 14:23:45 - SessionManager: Session validation failed
+  sessionId: 7f8a9b2c-4d3e-4a1b-9c8d-1e2f3a4b5c6d
+  reason: Session not found in cache
+  userId: null
+  timestamp: 1697640225000
+```
+
+**Screenshot:** [Attach screenshot of error]
+
+## Impact
+
+<!-- Severity, affected users, business impact, and any available workarounds -->
+
+- **Severity:** High (affects core functionality but workaround exists)
+- **Affected Users:** ~15% of mobile users on iOS and Android
+- **Affected Versions:** 2.3.0 and 2.3.1
+- **Business Impact:** Reduced mobile conversion rate by ~8% over past week
+- **Workaround:** Users can retry login 2-3 times until it succeeds
+
+## Root Cause Analysis
+
+### Investigation
+
+<!-- Document what you did to investigate: logs reviewed, code analyzed, experiments run -->
+
+**Example:**
+1. Reviewed application logs for past 7 days (10,427 login attempts, 1,563 failures)
+2. Identified pattern: failures only occur on mobile devices
+3. Checked Redis cache metrics: intermittent connection timeouts to session store
+4. Analyzed session creation code in `auth/SessionManager.ts`
+5. Discovered race condition in session creation for mobile devices
+6. Reproduced locally with added latency to Redis connection
+
+**Key Findings:**
+- Mobile devices have ~200ms additional latency compared to web
+- Session write to Redis times out after 100ms (too aggressive)
+- When timeout occurs, client receives session ID but server hasn't finished writing
+- Subsequent validation fails because session doesn't exist in Redis yet
+
+### Root Cause
+
+<!-- The underlying technical cause of the bug -->
+
+**Example:**
+> Race condition in `SessionManager.createSession()` method. The method returns the session ID to the client before confirming the session was successfully written to Redis. On mobile devices with higher latency, the Redis write often exceeds the 100ms timeout, but the client already received a session ID and attempts to use it immediately.
+
+**Code:**
+```typescript
+// Current buggy code in auth/SessionManager.ts:47-52
+async createSession(userId: string): Promise<string> {
+  const sessionId = generateSessionId();
+  // Fire-and-forget write (BUG: doesn't await completion)
+  this.redis.set(`session:${sessionId}`, userData, 'EX', 604800);
+  return sessionId; // Returns before write completes!
+}
+```
+
+### Why It Happened
+
+<!-- Why was this bug introduced? What can we learn? -->
+
+**Example:**
+> The original implementation used fire-and-forget for Redis writes to optimize for perceived latency (avoiding await). This worked fine in the local development environment but failed to account for higher latency in production, especially on mobile networks.
+
+**Contributing Factors:**
+- Insufficient integration testing with realistic network latency
+- No monitoring/alerting on Redis write timeouts
+- Timeout value (100ms) too aggressive for production conditions
+- Lack of error handling for failed cache writes
+
+## Fix Approach
+
+<!-- How will this bug be fixed? Include code changes if relevant -->
+
+**Example:**
+> Await Redis write completion before returning session ID. Increase Redis timeout to 500ms. Add retry logic for failed writes. Add monitoring for session creation failures.
+
+**Code Changes:**
+```typescript
+// Fixed code in auth/SessionManager.ts:47-58
+async createSession(userId: string): Promise<string> {
+  const sessionId = generateSessionId();
+  const userData = { userId, createdAt: Date.now() };
+
+  try {
+    // WAIT for Redis write to complete
+    await this.redis.set(
+      `session:${sessionId}`,
+      JSON.stringify(userData),
+      'EX',
+      604800,
+      { timeout: 500 }  // Increased timeout
+    );
+    this.metrics.recordSessionCreated(userId);
+    return sessionId;
+  } catch (error) {
+    this.metrics.recordSessionCreationFailed(userId, error);
+    throw new SessionCreationError('Failed to create session', error);
+  }
+}
+```
+
+**Files Modified:**
+- `src/auth/SessionManager.ts` - Fix race condition
+- `src/config/redis.ts` - Increase default timeout to 500ms
+- `src/monitoring/metrics.ts` - Add session creation metrics
+
+## Acceptance Criteria
+
+<!-- Define specific, measurable criteria for considering this bug fixed -->
+<!-- Minimum 3 items required for spec validation -->
+
+- [ ] Root cause is identified and addressed (not just symptoms)
+- [ ] All reproduction steps no longer trigger the bug
+- [ ] Comprehensive tests added to prevent regression
+- [ ] No new bugs or regressions introduced by the fix
+- [ ] Edge cases identified in investigation are handled
+- [ ] All tests pass (unit, integration, and manual)
+- [ ] Documentation updated if behavior changed
+
+**Example criteria for a specific bug:**
+- [ ] Mobile login success rate improves to >99% (currently ~85%)
+- [ ] Session creation completes within 500ms on high-latency networks
+- [ ] Redis write failures are properly handled and logged
+- [ ] Monitoring alerts configured for session creation failures
+
+## Testing Strategy
+
+<!-- Comprehensive testing to verify the fix and prevent regression -->
+
+### Regression Tests
+- [ ] Add unit test for session creation with simulated Redis latency
+- [ ] Add integration test for mobile login flow with 200ms+ latency
+- [ ] Add test to verify session immediately usable after creation
+- [ ] Add test for Redis write failure handling
+
+### Manual Verification
+- [ ] Test on iPhone 14 Pro with test account
+- [ ] Test on Samsung Galaxy S23 with test account
+- [ ] Test on simulated slow network (3G, high latency)
+- [ ] Verify error monitoring captures failures
+- [ ] Confirm login success rate improves to >99%
+
+### Edge Cases
+- [ ] Test with Redis temporarily unavailable
+- [ ] Test with very high latency (1000ms+)
+- [ ] Test concurrent login attempts from same device
+- [ ] Test session creation during Redis failover
+
+## Prevention
+
+<!-- How can we prevent similar bugs in the future? -->
+
+**Example:**
+- Add integration tests with simulated network latency (100ms, 500ms, 1000ms)
+- Set up monitoring/alerting for Redis operation timeouts
+- Code review checklist: verify all async operations are properly awaited
+- Performance testing requirements for mobile devices

solokit/templates/config.schema.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/ankushdixit/solokit/schemas/config.json",
+  "title": "Solokit Configuration",
+  "description": "Configuration for Session-Driven Development workflows",
+  "type": "object",
+  "properties": {
+    "quality_gates": {
+      "type": "object",
+      "description": "Quality gate configuration",
+      "properties": {
+        "test": {
+          "type": "object",
+          "properties": {
+            "required": {"type": "boolean"},
+            "command": {"type": "string"},
+            "timeout": {"type": "integer", "minimum": 1}
+          },
+          "required": ["required"]
+        },
+        "lint": {
+          "type": "object",
+          "properties": {
+            "required": {"type": "boolean"},
+            "command": {"type": "string"},
+            "timeout": {"type": "integer", "minimum": 1}
+          },
+          "required": ["required"]
+        },
+        "security": {
+          "type": "object",
+          "properties": {
+            "required": {"type": "boolean"},
+            "severity": {
+              "type": "string",
+              "enum": ["critical", "high", "medium", "low"]
+            },
+            "timeout": {"type": "integer", "minimum": 1}
+          },
+          "required": ["required"]
+        },
+        "format": {
+          "type": "object",
+          "properties": {
+            "required": {"type": "boolean"},
+            "auto_fix": {"type": "boolean"},
+            "command": {"type": "string"},
+            "timeout": {"type": "integer", "minimum": 1}
+          }
+        },
+        "documentation": {
+          "type": "object",
+          "properties": {
+            "required": {"type": "boolean"},
+            "check_changelog": {"type": "boolean"},
+            "check_docstrings": {"type": "boolean"}
+          }
+        },
+        "spec_completeness": {
+          "type": "object",
+          "properties": {
+            "required": {"type": "boolean"}
+          }
+        }
+      }
+    },
+    "learning": {
+      "type": "object",
+      "description": "Learning system configuration",
+      "properties": {
+        "auto_curate_frequency": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Auto-curate every N sessions"
+        },
+        "similarity_threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Threshold for duplicate detection (Jaccard similarity)"
+        },
+        "containment_threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Threshold for containment-based duplicate detection"
+        }
+      }
+    },
+    "session": {
+      "type": "object",
+      "description": "Session management configuration",
+      "properties": {
+        "auto_commit": {
+          "type": "boolean",
+          "description": "Automatically commit changes on session end"
+        },
+        "require_work_item": {
+          "type": "boolean",
+          "description": "Require work item for session start"
+        }
+      }
+    },
+    "deployment": {
+      "type": "object",
+      "description": "Deployment configuration",
+      "properties": {
+        "pre_deployment_checks": {
+          "type": "object",
+          "properties": {
+            "integration_tests": {"type": "boolean"},
+            "security_scans": {"type": "boolean"},
+            "environment_validation": {"type": "boolean"}
+          }
+        },
+        "smoke_tests": {
+          "type": "object",
+          "properties": {
+            "enabled": {"type": "boolean"},
+            "timeout": {"type": "integer", "minimum": 1},
+            "retry_count": {"type": "integer", "minimum": 0}
+          }
+        },
+        "rollback": {
+          "type": "object",
+          "properties": {
+            "automatic": {"type": "boolean"},
+            "on_smoke_test_failure": {"type": "boolean"},
+            "on_error_threshold": {"type": "boolean"},
+            "error_threshold_percent": {"type": "integer", "minimum": 0, "maximum": 100}
+          }
+        },
+        "environments": {
+          "type": "object",
+          "description": "Per-environment deployment configuration",
+          "patternProperties": {
+            ".*": {
+              "type": "object",
+              "properties": {
+                "auto_deploy": {"type": "boolean"},
+                "require_approval": {"type": "boolean"}
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}