solokit 0.1.1__py3-none-any.whl

solokit/templates/.claude/commands/start.md

@@ -0,0 +1,114 @@
+---
+description: Start a new development session with comprehensive briefing
+argument-hint: [work_item_id]
+---
+
+# Session Start
+
+## Step 1: Determine Work Item to Start
+
+**If user provided a work item ID in `$ARGUMENTS`:**
+- Skip to Step 3 and start that specific work item
+
+**If no work item ID provided:**
+- Continue to Step 2 for interactive selection
+
+## Step 2: Get Recommendations and Ask User
+
+Get the top 4 recommended work items:
+
+```bash
+python -m solokit.work_items.get_next_recommendations --limit 4
+```
+
+This will output ready-to-start work items in format:
+```
+work_item_id | type | title | priority
+```
+
+Parse the output and present options using `AskUserQuestion`:
+
+**Question: Which work item do you want to start?**
+- Question: "Select a work item to start working on:"
+- Header: "Work Item"
+- Multi-select: false
+- Options (up to 4):
+  - Label: "{work_item_id}: {title}", Description: "Type: {type} | Priority: {priority}"
+  - Label: "{work_item_id}: {title}", Description: "Type: {type} | Priority: {priority}"
+  - Label: "{work_item_id}: {title}", Description: "Type: {type} | Priority: {priority}"
+  - Label: "{work_item_id}: {title}", Description: "Type: {type} | Priority: {priority}"
+
+**Example option formatting:**
+- Label: "feature_auth: Add user authentication"
+- Description: "Type: feature | Priority: high"
+
+**If no ready work items found:**
+- The script will exit with error
+- Show message: "No work items ready to start. All items are blocked by dependencies or already in progress."
+- Display hint: "Use /work-list to see all work items and their status."
+- Exit without calling command
+
+## Step 3: Start Session
+
+Based on the selected work item ID (either from user argument or interactive selection):
+
+```bash
+sk start {work_item_id}
+```
+
+Replace `{work_item_id}` with:
+- The value from `$ARGUMENTS` if user provided it
+- The selected work item ID from Step 2 if interactive selection was used
+
+The briefing includes:
+- Complete project context (technology stack, directory tree, documentation)
+- **Previous work context** (for in-progress items) - commits made, files changed, quality gates from prior sessions
+- **Full work item specification from `.session/specs/{work_item_id}.md`** (source of truth)
+- Work item tracking details (title, type, priority, dependencies)
+- Spec validation warnings (if specification is incomplete)
+- **Top 10 relevant learnings** scored by keyword matching, type relevance, recency, and category
+- Milestone context and progress (if the work item belongs to a milestone)
+
+## Enhanced Briefings (Enhancement #11)
+
+For **in-progress work items**, briefings include a "Previous Work" section with:
+- All commits made in previous sessions (full messages, file stats)
+- Quality gate results from each session
+- Session dates and durations
+- This makes multi-session work practical by eliminating context loss
+
+**Learning relevance** uses multi-factor scoring:
+- Keyword matching from work item title and spec
+- Work item type matching
+- Tag overlap (legacy support)
+- Category bonuses (best_practices, patterns, architecture)
+- Recency weighting (recent learnings score higher)
+- Returns top 10 most relevant learnings (up from 5)
+
+## Spec-First Architecture (Phase 5.7)
+
+The spec file (`.session/specs/{work_item_id}.md`) is the **single source of truth** for work item content:
+- Contains complete implementation details, acceptance criteria, and testing strategy
+- Passed in full to Claude during session briefings (no compression)
+- Validated for completeness before session starts
+- If spec validation warnings appear, review and complete the spec before proceeding
+
+After generating the briefing:
+1. Display the complete briefing to the user
+2. Update the work item status to "in_progress" using the work item manager
+3. Begin implementation immediately following the guidelines below
+
+## Implementation Guidelines
+
+When implementing the work item, you MUST:
+
+1. **Follow the spec strictly** - The work item specification in the briefing is your complete implementation guide
+2. **Do not add features** - Only implement what is explicitly specified in the acceptance criteria
+3. **Do not make assumptions** - If anything is unclear or ambiguous, ask the user for clarification before proceeding
+4. **Check all requirements** - Ensure every acceptance criterion is met before considering the work complete
+5. **Respect validation criteria** - Follow testing, documentation, and quality requirements specified in the spec
+6. **Stay focused** - Do not deviate from the spec or add "helpful" extras unless explicitly requested
+
+The specification defines the exact scope and boundaries of the work. Stay within them.
+
+Now begin implementing the work item according to the specification.

solokit/templates/.claude/commands/status.md

@@ -0,0 +1,22 @@
+---
+description: Display current session status with progress overview
+---
+
+# Session Status
+
+Get a quick overview of the current session by running:
+
+```bash
+sk status
+```
+
+The status includes:
+- **Current Work Item**: What you're currently working on (title, type, priority)
+- **Time Elapsed**: How long the current session has been running
+- **Files Changed**: Number of files modified during this session
+- **Git Information**: Current branch and recent commits
+- **Milestone Progress**: Progress bar and completion percentage (if applicable)
+- **Next Work Items**: Upcoming tasks ready to start
+- **Quick Actions**: Suggested next steps
+
+Display the formatted status output to the user. This provides a quick snapshot of progress without interrupting the workflow.

solokit/templates/.claude/commands/validate.md

@@ -0,0 +1,27 @@
+---
+description: Validate current session meets quality standards without ending it
+---
+
+# Session Validate
+
+Run the validation script to check quality standards:
+
+```bash
+sk validate
+```
+
+To automatically fix linting and formatting issues:
+
+```bash
+sk validate --fix
+```
+
+The validation checks:
+- **Tests**: All test suites pass
+- **Linting**: Code passes linting rules (auto-fixable with --fix)
+- **Formatting**: Code is properly formatted (auto-fixable with --fix)
+- **Code Coverage**: Meets minimum coverage threshold
+- **Git Status**: Working directory is clean or has expected changes
+- **Acceptance Criteria**: Work item requirements are met
+
+Display the validation results to the user with a clear pass/fail status for each check. If linting or formatting fail, suggest using `sk validate --fix` to automatically fix the issues. This command allows checking quality during development without ending the session.

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

@@ -0,0 +1,119 @@
+---
+description: Delete a work item from the system
+argument-hint: <work_item_id>
+---
+
+# Work Item Delete
+
+Delete a work item from the Solokit system with dependency checking and interactive confirmation.
+
+## Usage
+
+```
+/work-delete <work_item_id>
+```
+
+## Instructions
+
+1. **Parse the work_item_id** from the command arguments
+
+   **If missing:**
+   - Show error: "Usage: /work-delete <work_item_id>"
+   - Exit
+
+2. **Load and display work item details** (optimized):
+   - Use `python -m solokit.work_items.get_metadata <work_item_id> --with-deps` for fast lookup
+   - If work item doesn't exist: Show error and suggest using `/work-list`
+   - Display current values:
+     ```
+     Work Item: {work_item_id}
+     - Title: {title}
+     - Type: {type}
+     - Status: {status}
+     - Dependencies: {dependencies or "(none)"}
+     ```
+
+3. **Check for dependents** (work items that depend on this one):
+   - **Use optimized script**: Run `python -m solokit.work_items.get_dependents <work_item_id>`
+   - This script efficiently finds all work items that depend on the given work item
+   - If dependents exist, show warning:
+     ```
+     ⚠️  WARNING: {count} work item(s) depend on this item:
+       - {dependent_id_1} [{type}] {title}
+       - {dependent_id_2} [{type}] {title}
+
+     Deleting this item will NOT update their dependencies.
+     You'll need to manually update them after deletion.
+     ```
+
+4. **Ask for confirmation** using `AskUserQuestion`:
+
+   **Question: Deletion Confirmation**
+   - Question: "How would you like to delete '{work_item_id}'?"
+   - Header: "Delete"
+   - Multi-select: false
+   - Options:
+     - Label: "Delete work item only (keep spec file)", Description: "Remove from work_items.json but keep .session/specs/{work_item_id}.md for reference"
+     - Label: "Delete work item and spec file", Description: "Permanently remove both the work item and its specification file"
+     - Label: "Cancel deletion", Description: "Do not delete anything"
+
+5. **Execute deletion** based on user selection:
+
+   **If "Delete work item only" selected:**
+   ```bash
+   sk work-delete <work_item_id> --keep-spec
+   ```
+
+   **If "Delete work item and spec file" selected:**
+   ```bash
+   sk work-delete <work_item_id> --delete-spec
+   ```
+
+   **If "Cancel deletion" selected:**
+   - Show message: "Deletion cancelled."
+   - Exit without calling command
+
+6. **Show the output** to the user:
+   - Confirmation of deletion
+   - If spec file was deleted, confirm that too
+   - If dependents exist, remind user to update them:
+     ```
+     ⚠️  Reminder: Update dependencies for these work items:
+       /work-update {dependent_1} remove-dependency
+       /work-update {dependent_2} remove-dependency
+     ```
+
+## Examples
+
+```bash
+sk work-delete feature_obsolete_item --keep-spec
+sk work-delete feature_test_item --delete-spec
+```
+
+## Error Handling
+
+If the command fails:
+- **Missing work_item_id**: Show usage
+- **Work item doesn't exist**: Show error and list available items
+- **Missing flag**: This should never happen (command file ensures flag is provided)
+
+## Important Notes
+
+1. **Deletion is permanent** - Work items cannot be recovered after deletion
+2. **Dependents are NOT modified** - If other work items depend on the deleted item, their dependencies are NOT automatically updated. User must manually update them.
+3. **Spec files are optional** - User can choose to keep the spec file for reference
+4. **Manual cleanup required** - After deleting a work item with dependents, remind user to update those dependencies using `/work-update <id> remove-dependency`
+
+## Safety Features
+
+- **Dependency checking**: Lists work items that depend on the item being deleted
+- **Interactive confirmation**: Requires user confirmation with clear options
+- **Metadata updates**: Automatically updates work item counts and statistics
+- **Validation**: Prevents deletion of non-existent work items
+- **Warnings**: Clear warnings about dependents that need manual updates
+
+## Related Commands
+
+- `/work-list` - List all work items to find items to delete
+- `/work-show <id>` - View work item details before deleting
+- `/work-update <id> remove-dependency` - Update dependencies after deleting a work item

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

@@ -0,0 +1,139 @@
+---
+description: Generate dependency graph visualization for work items
+argument-hint: [--format FORMAT] [--status STATUS] [--milestone MILESTONE] [--type TYPE] [--focus ID] [--critical-path] [--bottlenecks] [--stats] [--include-completed] [--output FILE]
+---
+
+# Work Item Graph
+
+Generate visual dependency graphs showing relationships between work items, with critical path highlighting and bottleneck analysis.
+
+## Usage
+
+Ask the user what type of graph they want to generate:
+
+1. **Format** - Ask: "What output format would you like?"
+   - Options: ascii (default, terminal display), dot (Graphviz), svg (requires Graphviz)
+   - Default to ascii if not specified
+
+2. **Filters** - Ask: "Any filters to apply? (or 'none' for all work items)"
+   - Status: only show items with specific status (not_started, in_progress, completed)
+   - Milestone: only show items in specific milestone
+   - Type: only show specific work item types
+   - Include completed: whether to show completed items (default: no)
+
+3. **Special views** - Ask: "Need any special analysis?"
+   - critical-path: Show only critical path items
+   - bottlenecks: Highlight bottleneck analysis
+   - stats: Show graph statistics
+   - focus <work_item_id>: Show neighborhood of specific item
+
+## After Collecting Information
+
+Run the appropriate command based on user input:
+
+**Basic usage:**
+```bash
+sk work-graph
+```
+
+**With format:**
+```bash
+sk work-graph --format dot
+sk work-graph --format svg --output graph.svg
+```
+
+**With filters:**
+```bash
+sk work-graph --status not_started
+sk work-graph --milestone "Phase 3"
+sk work-graph --type feature
+sk work-graph --include-completed
+```
+
+**Special views:**
+```bash
+sk work-graph --critical-path
+sk work-graph --bottlenecks
+sk work-graph --stats
+sk work-graph --focus feature_add_authentication
+```
+
+**Combined filters:**
+```bash
+sk work-graph --status not_started --milestone "Phase 3" --format svg --output phase3.svg
+```
+
+## Output
+
+The command will generate a visual graph showing:
+- Work items as nodes (with ID, title, status)
+- Dependencies as edges (arrows from dependency to dependent)
+- Critical path highlighted in red
+- Color coding by status and priority
+- Bottlenecks identified
+
+Display the output to the user and explain key insights:
+- Which items are on critical path (determines project timeline)
+- Which items are bottlenecks (blocking multiple other items)
+- Completion percentage
+- Next recommended items to work on
+
+## Examples
+
+### Example 1: Basic ASCII Graph
+```bash
+sk work-graph
+```
+Shows all incomplete work items with dependencies in terminal-friendly format.
+
+### Example 2: Critical Path Only
+```bash
+sk work-graph --critical-path
+```
+Shows only items on the critical path (longest dependency chain).
+
+### Example 3: Bottleneck Analysis
+```bash
+sk work-graph --bottlenecks
+```
+Lists items that block 2+ other items, sorted by impact.
+
+### Example 4: Milestone Planning
+```bash
+sk work-graph --milestone "Phase 3" --format svg --output phase3_dependencies.svg
+```
+Generate visual graph of Phase 3 dependencies for documentation.
+
+### Example 5: Focus on Specific Item
+```bash
+sk work-graph --focus feature_oauth
+```
+Show only feature_oauth and its dependency neighborhood (dependencies + dependents).
+
+### Example 6: Statistics
+```bash
+sk work-graph --stats
+```
+Show completion statistics and critical path length without rendering full graph.
+
+## Interpreting the Output
+
+**Node Colors:**
+- **Red**: Critical path items (determine project timeline)
+- **Green**: Completed items
+- **Blue**: In progress items
+- **Black/White**: Not started items
+- **Orange**: Blocked items
+
+**Arrows:**
+- Point from dependency → dependent
+- Bold red arrows = critical path connections
+
+**Bottlenecks:**
+- Items that block 2+ other items
+- Prioritize completing these to unblock downstream work
+
+**Critical Path:**
+- Longest chain of dependencies
+- Determines minimum project timeline
+- Focus here to minimize overall project duration

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

@@ -0,0 +1,26 @@
+---
+description: List all work items with optional filtering
+argument-hint: [--status STATUS] [--type TYPE] [--milestone MILESTONE]
+---
+
+# Work Item List
+
+List all work items, optionally filtered by status, type, or milestone.
+
+Run the following command:
+
+```bash
+sk work-list "$@"
+```
+
+The CLI will automatically parse and handle filters from `$ARGUMENTS`:
+- `--status not_started` → Filters by status
+- `--type feature` → Filters by type
+- `--milestone phase_2_mvp` → Filters by milestone
+
+Available filter values:
+- **Status**: `not_started`, `in_progress`, `blocked`, `completed`
+- **Type**: `feature`, `bug`, `refactor`, `security`, `integration_test`, `deployment`
+- **Milestone**: Any milestone name from the project
+
+Display the color-coded work item list with priority indicators (🔴 critical, 🟠 high, 🟡 medium, 🟢 low) and dependency status markers (✓ ready, 🚫 blocked).

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

@@ -0,0 +1,114 @@
+---
+description: Create a new work item interactively
+---
+
+# Work Item Create
+
+Create a new work item using rich interactive UI components.
+
+## Instructions
+
+1. **First, gather basic information** using the `AskUserQuestion` tool with these 3 questions:
+
+   **Question 1: Work Item Type**
+   - Question: "What type of work item would you like to create?"
+   - Header: "Type"
+   - Multi-select: false
+   - Options (limit: 4 options max):
+     - Label: "feature", Description: "Standard feature development - New functionality or enhancement"
+     - Label: "bug", Description: "Bug fix - Resolve an issue or defect"
+     - Label: "refactor", Description: "Code refactoring - Improve code structure without changing behavior"
+     - Label: "security", Description: "Security-focused work - Address security vulnerabilities or improvements"
+   - Note: User can select "Type something" to manually enter: integration_test or deployment
+
+   **Question 2: Title**
+   - Question: "Enter a brief, descriptive title for the work item:"
+   - Header: "Title"
+   - Multi-select: false
+   - Options: Provide 2-4 example titles based on the type selected in Question 1:
+     - If type=feature: "Add authentication system", "Implement search feature"
+     - If type=bug: "Fix database connection timeout", "Resolve login error"
+     - If type=refactor: "Refactor authentication module", "Simplify error handling"
+     - If type=security: "Fix SQL injection vulnerability", "Add input sanitization"
+   - Note: User will select "Type something" to enter their custom title
+
+   **Question 3: Priority**
+   - Question: "What is the priority level for this work item?"
+   - Header: "Priority"
+   - Multi-select: false
+   - Options:
+     - Label: "critical", Description: "Blocking issue or urgent requirement"
+     - Label: "high", Description: "Important work to be done soon (recommended default)"
+     - Label: "medium", Description: "Normal priority work"
+     - Label: "low", Description: "Nice to have, can be deferred"
+
+2. **Then, ask about dependencies** in a separate follow-up question (after you have the title):
+
+   **Question 4: Dependencies (separate AskUserQuestion call)**
+   - Question: "Does this work item depend on other work items? (Select all that apply)"
+   - Header: "Dependencies"
+   - Multi-select: true
+   - Options:
+     - **Use optimized script**: Run `python -m solokit.work_items.get_dependencies --title "<title_from_question_2>" --max 3`
+     - This script automatically:
+       - Excludes completed items (shows only: not_started, in_progress, blocked)
+       - Filters by relevance based on the title
+       - Returns up to 3 most relevant items
+     - Parse the output and create options:
+       - Format: Label: "{work_item_id}", Description: "[{priority}] [{type}] {title} ({status})"
+       - Always include: Label: "No dependencies", Description: "This work item has no dependencies"
+   - If more than 3 relevant items exist, user can select "Type something" to enter comma-separated IDs manually
+   - If NO incomplete work items exist (script returns "No available dependencies found"), only show "No dependencies" option
+
+2. **Validate inputs:**
+   - Ensure type is one of: feature, bug, refactor, security, integration_test, deployment
+   - Ensure title is not empty
+   - Ensure priority is one of: critical, high, medium, low
+   - Dependencies can be empty (no dependencies)
+
+3. **Create the work item** by running:
+
+```bash
+sk work-new --type <type> --title "<title>" --priority <priority> --dependencies "<dep1,dep2>"
+```
+
+Example:
+```bash
+sk work-new --type feature --title "Add user authentication" --priority high --dependencies "feature_database_setup,bug_session_timeout"
+```
+
+If no dependencies:
+```bash
+sk work-new --type feature --title "Add user authentication" --priority high --dependencies ""
+```
+
+4. **Show the output** to the user, which includes:
+   - Created work item ID
+   - Work item type and priority
+   - Status (will be "not_started")
+   - Dependencies (if any)
+   - Path to the specification file (`.session/specs/{work_item_id}.md`)
+
+## Error Handling
+
+If the command fails:
+- Check the error message
+- If dependency doesn't exist: Re-prompt with valid dependencies list
+- If work item already exists: Suggest using a different title or updating the existing item
+- If validation error: Re-prompt with corrected information
+
+## Next Step: Fill Out the Spec File
+
+**IMPORTANT:** After creating the work item, you must fill out the specification file:
+
+1. Open `.session/specs/{work_item_id}.md`
+2. Follow the template structure and inline guidance comments
+3. Complete all required sections for the work item type
+4. Remove HTML comment instructions when done
+
+The spec file is the **single source of truth** for work item content. All implementation details, acceptance criteria, and testing strategies should be documented in the spec file, not in `work_items.json`.
+
+For guidance on writing effective specs, see:
+- `docs/guides/writing-specs.md` - Best practices and examples
+- `docs/reference/spec-template-structure.md` - Template structure reference
+- `src/solokit/templates/{type}_spec.md` - Template examples for each work item type

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

@@ -0,0 +1,25 @@
+---
+description: Get the next recommended work item to start based on dependencies and priority
+---
+
+# Work Item Next
+
+Get an intelligent recommendation for the next work item to start:
+
+```bash
+sk work-next
+```
+
+The recommendation algorithm analyzes:
+- **Available Work Items**: All items with `not_started` status
+- **Dependency Blocking**: Filters out items blocked by incomplete dependencies
+- **Priority Sorting**: Ranks by priority (critical > high > medium > low)
+- **Smart Selection**: Recommends the highest priority unblocked item
+
+Display to the user:
+- **Recommended Work Item**: Full details (ID, title, type, priority)
+- **Selection Rationale**: Why this item was chosen
+- **Dependency Status**: Confirmation that all dependencies are satisfied
+- **Context**: Overview of other waiting items (both blocked and ready)
+
+This helps maintain efficient workflow by always suggesting the most important work that can be started immediately.

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

@@ -0,0 +1,24 @@
+---
+description: Show detailed information about a specific work item
+argument-hint: <work_item_id>
+---
+
+# Work Item Show
+
+Display detailed information for a specific work item by running:
+
+```bash
+sk work-show "$@"
+```
+
+The work item ID is provided in `$ARGUMENTS` and passed through `"$@"`.
+
+This displays comprehensive details:
+- **Work Item Info**: Type, status, priority, creation date
+- **Dependencies**: List of dependencies with their current status
+- **Session History**: All sessions where this work item was worked on
+- **Git Information**: Branch name and associated commits
+- **Specification Preview**: First 30 lines of the spec file
+- **Next Steps**: Suggested actions based on current status
+
+Show all information to the user in a clear, formatted display. This helps understand the full context of a work item before starting work on it.