solokit 0.1.1__py3-none-any.whl

solokit/templates/.claude/commands/end.md

@@ -0,0 +1,109 @@
+---
+description: Complete the current development session with quality gates and summary
+---
+
+# Session End
+
+Before completing the session, **capture learnings** from the work done:
+
+## Step 1: Generate Learnings
+
+Review the session work and create 2-5 key learnings. You have two ways to capture learnings:
+
+### Option A: Commit Message LEARNING Tags (Recommended)
+
+Include `LEARNING:` annotations in your commit messages. These will be automatically extracted during session completion:
+
+```bash
+git commit -m "Implement calculator add function
+
+Added TypeScript add function with comprehensive tests.
+
+LEARNING: TypeScript number type handles both integers and decimals seamlessly
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### Option B: Temporary Learnings File
+
+Write learnings to `.session/temp_learnings.txt` (one learning per line):
+
+```bash
+cat > .session/temp_learnings.txt << 'EOF'
+[Learning 1]
+[Learning 2]
+[Learning 3]
+EOF
+```
+
+**What makes a good learning:**
+- Technical insights discovered during implementation
+- Gotchas or edge cases encountered
+- Best practices or patterns that worked well
+- Architecture decisions and their rationale
+- Performance or security considerations
+- Things to remember for future work
+
+## Step 2: Ask About Work Item Completion
+
+Before completing the session, ask the user about the work item completion status using `AskUserQuestion`:
+
+**Question: Work Item Completion Status**
+- Question: "Is this work item complete?"
+- Header: "Completion"
+- Multi-select: false
+- Options:
+  - Label: "Yes - Mark as completed", Description: "Work item is done. Will not auto-resume in next session."
+  - Label: "No - Keep as in-progress", Description: "Work is ongoing. Will auto-resume when you run /start in the next session."
+  - Label: "Cancel", Description: "Don't end session. Continue working."
+
+**Important**: Display the work item title in the question text so the user knows which item they're completing.
+
+## Step 3: Complete Session
+
+Based on the user's selection:
+
+**If "Yes - Mark as completed" selected:**
+```bash
+sk end --complete --learnings-file .session/temp_learnings.txt
+```
+
+**If "No - Keep as in-progress" selected:**
+```bash
+sk end --incomplete --learnings-file .session/temp_learnings.txt
+```
+
+**If "Cancel" selected:**
+- Show message: "Session end cancelled. You can continue working."
+- Exit without calling command
+
+This script validates quality gates:
+- All tests pass
+- Linting passes
+- Git changes are committed
+- Work item status is updated
+- Learnings are captured
+
+The script automatically updates project context files (stack.py and tree.py) after validation passes.
+
+## Step 4: Show Results
+
+Show the user:
+- Session summary with work accomplished
+- **Commit details** (full messages + file change statistics) - Enhancement #11
+- Quality gate results (pass/fail for each check)
+- Learnings captured
+- Work item completion status (completed or in-progress)
+- Suggested next steps
+
+If any quality gates fail, display the specific errors and guide the user on what needs to be fixed before the session can be completed. Do not proceed with session completion until all quality gates pass.
+
+## Enhanced Session Summaries (Enhancement #11)
+
+Session summaries now include comprehensive commit details:
+- **Full commit messages** (multi-line messages preserved)
+- **File change statistics** from `git diff --stat` (files changed, insertions, deletions)
+- Each commit listed with short SHA and message
+
+This enriched session summary serves as the **single source of truth** for "Previous Work" sections in future session briefings when resuming in-progress work items.

solokit/templates/.claude/commands/init.md

@@ -0,0 +1,159 @@
+---
+description: Initialize a new Session-Driven Development project with template-based setup
+---
+
+# Template-Based Project Initialization
+
+Initialize a new Solokit project with guided template selection for production-ready setup.
+
+## Interactive Template Selection (4 Questions)
+
+Use the **AskUserQuestion tool** to collect all configuration:
+
+### Question 1: Project Category
+
+**Question**: "What type of project are you building?"
+**Header**: "Category"
+**Multi-Select**: false
+
+**Options**:
+1. **Label**: "SaaS Application"
+   **Description**: "T3 stack with Next.js, Prisma, tRPC - Full-featured web apps with auth, payments, multi-tenancy"
+
+2. **Label**: "ML/AI Tooling"
+   **Description**: "FastAPI with Python ML libraries - Machine learning APIs, data pipelines, model serving"
+
+3. **Label**: "Internal Dashboard"
+   **Description**: "Refine with React admin framework - Admin panels, analytics dashboards, internal tools"
+
+4. **Label**: "Full-Stack Product"
+   **Description**: "Next.js with full-stack capabilities - General purpose web applications"
+
+---
+
+### Question 2: Quality Gates Tier
+
+**Question**: "What level of quality gates do you want?"
+**Header**: "Quality Tier"
+**Multi-Select**: false
+
+**Options**:
+1. **Label**: "Essential"
+   **Description**: "Linting, formatting, type-check, basic tests (fastest setup)"
+
+2. **Label**: "Standard"
+   **Description**: "+ Pre-commit hooks, security scanning (recommended for most projects)"
+
+3. **Label**: "Comprehensive"
+   **Description**: "+ Coverage reports, integration tests, mutation testing (production-ready)"
+
+4. **Label**: "Production-Ready"
+   **Description**: "+ Performance monitoring, error tracking, deployment safety (enterprise-grade)"
+
+---
+
+### Question 3: Testing Coverage Target
+
+**Question**: "What testing coverage level do you want to enforce?"
+**Header**: "Coverage"
+**Multi-Select**: false
+
+**Options**:
+1. **Label**: "Basic (60%)"
+   **Description**: "Minimal coverage for prototypes and MVPs"
+
+2. **Label**: "Standard (80%)"
+   **Description**: "Industry standard for production code (recommended)"
+
+3. **Label**: "Strict (90%)"
+   **Description**: "High-reliability applications and mission-critical systems"
+
+---
+
+### Question 4: Additional Options
+
+**Question**: "Select additional features to include:"
+**Header**: "Add-ons"
+**Multi-Select**: true
+
+**Options** (all optional, user can select multiple):
+1. **Label**: "GitHub Actions CI/CD"
+   **Description**: "Automated testing and deployment workflows"
+
+2. **Label**: "Docker Support"
+   **Description**: "Containerization with docker-compose"
+
+3. **Label**: "Pre-commit Hooks"
+   **Description**: "Automated code quality checks before commits"
+
+4. **Label**: "Environment Templates"
+   **Description**: ".env files and .editorconfig for all editors"
+
+---
+
+## Run Initialization
+
+After collecting all answers via AskUserQuestion, run the Python CLI with the appropriate arguments:
+
+```bash
+sk init --template=<category> --tier=<tier> --coverage=<coverage> --options=<options>
+```
+
+**Mapping user selections to CLI arguments:**
+
+**Category mapping:**
+- "SaaS Application" → `--template=saas_t3`
+- "ML/AI Tooling" → `--template=ml_ai_fastapi`
+- "Internal Dashboard" → `--template=dashboard_refine`
+- "Full-Stack Product" → `--template=fullstack_nextjs`
+
+**Tier mapping:**
+- "Essential" → `--tier=tier-1-essential`
+- "Standard" → `--tier=tier-2-standard`
+- "Comprehensive" → `--tier=tier-3-comprehensive`
+- "Production-Ready" → `--tier=tier-4-production`
+
+**Coverage mapping:**
+- "Basic (60%)" → `--coverage=60`
+- "Standard (80%)" → `--coverage=80`
+- "Strict (90%)" → `--coverage=90`
+- Custom value from "Type something" → `--coverage=<value>`
+
+**Options mapping:**
+- "GitHub Actions CI/CD" → `ci_cd`
+- "Docker Support" → `docker`
+- "Pre-commit Hooks" → `pre_commit`
+- "Environment Templates" → `env_templates`
+
+Combine multiple options with commas: `--options=ci_cd,docker,pre_commit`
+
+**Important:** The Python command handles ALL validation and setup deterministically:
+- Pre-flight checks (blank project, git init, environment validation)
+- Template installation
+- Dependency installation
+- All file generation
+
+---
+
+## After Successful Init
+
+Show the user the success output from the script, then explain:
+
+"Your project is now set up with production-ready tooling!
+
+**Next steps:**
+1. Review `README.md` for stack-specific getting started guide
+2. Create your first work item: `/sk:work-new`
+3. Start working: `/sk:start`"
+
+---
+
+## Error Handling
+
+If the `sk init` command fails, show the error message from the CLI output. The Python script provides clear error messages for common issues:
+- Already initialized
+- Not a blank project
+- Missing environment requirements
+- etc.
+
+Do not retry automatically - let the user address the issue and run `/sk:init` again.

solokit/templates/.claude/commands/learn-curate.md

@@ -0,0 +1,88 @@
+---
+description: Run learning curation process
+argument-hint: [--dry-run]
+---
+
+# Curate Learnings
+
+Run automatic categorization, similarity detection, and merging of learnings.
+
+## What Curation Does
+
+The curation process:
+1. **Categorizes** uncategorized learnings using AI-powered keyword analysis
+2. **Detects duplicates** using Jaccard and containment similarity algorithms
+3. **Merges similar learnings** to reduce redundancy
+4. **Archives old learnings** (learnings older than 50 sessions)
+5. **Updates metadata** (last_curated timestamp)
+
+## Usage
+
+### Normal Curation (Save Changes)
+
+```bash
+sk learn-curate
+```
+
+This will:
+- Process all learnings
+- Save changes to learnings.json
+- Display summary of actions taken
+
+### Dry-Run Mode (Preview Only)
+
+```bash
+sk learn-curate --dry-run
+```
+
+This will:
+- Show what changes would be made
+- NOT save any changes
+- Useful for previewing curation results
+
+## When to Run Curation
+
+Manual curation is useful when:
+- You've captured many learnings and want to organize them
+- You want to check for duplicate learnings
+- You want to preview what auto-curation would do
+- You're testing the curation process
+
+Note: Curation also runs automatically every N sessions (configurable in .session/config.json).
+
+## Output Format
+
+Display the curation summary showing:
+- Initial learning count
+- Number of learnings categorized
+- Number of duplicates merged
+- Number of learnings archived
+- Final learning count
+
+Example output:
+```
+=== Learning Curation ===
+
+Initial learnings: 45
+
+✓ Categorized 8 learnings
+✓ Merged 3 duplicate learnings
+✓ Archived 2 old learnings
+
+Final learnings: 42
+
+✓ Learnings saved
+```
+
+## Understanding the Process
+
+**Categorization:** Uses keyword analysis to assign learnings to one of 6 categories:
+- architecture_patterns, gotchas, best_practices, technical_debt, performance_insights, security
+
+**Similarity Detection:** Uses two algorithms:
+- **Jaccard similarity:** Measures word overlap (threshold: 0.6)
+- **Containment similarity:** Detects if one learning contains another (threshold: 0.8)
+
+**Merging:** Combines tags and tracks merge history when duplicates are found.
+
+**Archiving:** Moves learnings older than 50 sessions to archive (preserves them but removes from active view).

solokit/templates/.claude/commands/learn-search.md

@@ -0,0 +1,62 @@
+---
+description: Search learnings by keyword
+argument-hint: <query>
+---
+
+# Search Learnings
+
+Full-text search across all learning content, tags, and context.
+
+## Usage
+
+Extract the search query from $ARGUMENTS and run:
+
+```bash
+sk learn-search "$@"
+```
+
+### How Search Works
+
+The search looks for matches in:
+- Learning content (main text)
+- Tags
+- Context/notes
+- Category names
+
+Search is case-insensitive and finds partial matches.
+
+### Examples
+
+Search for "CORS":
+```bash
+sk learn-search "CORS"
+```
+
+Search for "FastAPI middleware":
+```bash
+sk learn-search "FastAPI middleware"
+```
+
+Search for "authentication":
+```bash
+sk learn-search "authentication"
+```
+
+## Display Format
+
+Show matching learnings with:
+- Learning content with matched text highlighted
+- Category and tags
+- Session where captured
+- Relevance score or match indicator
+- Learning ID
+
+Present results in order of relevance, grouped by category.
+
+## Tips for Users
+
+Suggest to users:
+- Use specific keywords for better results
+- Try tag names if searching by topic
+- Use category names to narrow results
+- Combine with `/learn-show --category` for focused browsing

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

@@ -0,0 +1,69 @@
+---
+description: Browse and filter learnings
+argument-hint: [--category CATEGORY] [--tag TAG] [--session SESSION]
+---
+
+# Show Learnings
+
+View captured learnings with optional filtering.
+
+## Usage
+
+Parse $ARGUMENTS for filters and run the show-learnings command:
+
+```bash
+sk learn-show "$@"
+```
+
+### Filter Options
+
+- `--category <category>` - Filter by category:
+  - `architecture_patterns` - Design decisions and patterns
+  - `gotchas` - Edge cases and pitfalls
+  - `best_practices` - Effective approaches
+  - `technical_debt` - Areas needing improvement
+  - `performance_insights` - Optimization learnings
+  - `security` - Security-related discoveries
+
+- `--tag <tag>` - Filter by specific tag (e.g., `python`, `fastapi`, `cors`)
+
+- `--session <number>` - Show learnings from specific session number
+
+### Examples
+
+Show all learnings:
+```bash
+sk learn-show
+```
+
+Show only gotchas:
+```bash
+sk learn-show --category gotchas
+```
+
+Show learnings tagged with "fastapi":
+```bash
+sk learn-show --tag fastapi
+```
+
+Show learnings from session 5:
+```bash
+sk learn-show --session 5
+```
+
+Combine filters (gotchas from session 5):
+```bash
+sk learn-show --category gotchas --session 5
+```
+
+## Display Format
+
+The command will display learnings in organized format showing:
+- Category grouping
+- Learning content
+- Tags (if any)
+- Session number where captured
+- Timestamp
+- Learning ID
+
+Present the output to the user in a clear, readable format.

solokit/templates/.claude/commands/learn.md

@@ -0,0 +1,136 @@
+---
+description: Capture a learning during development session
+---
+
+# Learning Capture
+
+Record insights, gotchas, and best practices discovered during development.
+
+## Step 1: Analyze Session and Generate Learning Suggestions
+
+Review what was accomplished in the current session:
+- What code was written/changed
+- What problems were solved
+- What patterns or approaches were used
+- What technical insights were discovered
+- What gotchas or edge cases were encountered
+
+Generate 2-3 learning suggestions based on the session work. Good learnings are:
+- Specific technical insights (not generic)
+- Actionable and memorable
+- About tools, patterns, or gotchas encountered
+- Clear and concise (1-2 sentences)
+
+## Step 2: Ask User to Select Learnings
+
+Use `AskUserQuestion` with multi-select to let user choose learnings:
+
+**Question: Select Learnings from This Session**
+- Question: "I've identified some potential learnings from this session. Select all that apply, or add your own:"
+- Header: "Learnings"
+- Multi-select: true
+- Options (up to 4 total):
+  - Option 1: [Your generated learning suggestion 1]
+  - Option 2: [Your generated learning suggestion 2]
+  - Option 3: [Your generated learning suggestion 3] (if applicable)
+  - Option 4: [Your generated learning suggestion 4] (if applicable)
+
+**Example Options:**
+- "TypeScript enums are type-safe at compile time but add runtime overhead"
+- "Zod schemas can be inferred as TypeScript types using z.infer<>"
+- "React useCallback dependencies must include all values used inside the callback"
+
+## Step 3: For Each Selected Learning, Determine Category
+
+For each learning the user selected (or entered), automatically suggest the most appropriate category:
+
+**Categories:**
+- `architecture_patterns` - Design decisions, patterns used, architectural approaches
+- `gotchas` - Edge cases, pitfalls, bugs discovered
+- `best_practices` - Effective approaches, recommended patterns
+- `technical_debt` - Areas needing improvement, refactoring needed
+- `performance_insights` - Optimization learnings, performance improvements
+- `security` - Security-related discoveries, vulnerabilities fixed
+
+Use your judgment to auto-assign the category based on the learning content. You can briefly explain your categorization choice to the user.
+
+## Step 4: Save Each Learning
+
+For each learning selected/entered by the user:
+
+1. Get the current session number from `.session/tracking/status_update.json`
+2. Run the add-learning command:
+
+```bash
+sk learn add-learning \
+  --content "{{content}}" \
+  --category "{{category}}" \
+  --session "{{current_session}}"
+```
+
+Replace:
+- `{{content}}` with the learning content (use quotes, escape if needed)
+- `{{category}}` with the auto-assigned category
+- `{{current_session}}` with session number from status_update.json
+
+**Optional flags:**
+- Add `--tags "tag1,tag2"` if relevant tags can be inferred from the learning
+- Add `--context "..."` if there's specific file/session context
+
+3. After adding all learnings, display a summary:
+
+```
+✓ Captured 3 learnings:
+  1. [gotchas] TypeScript enums are type-safe at compile time but add runtime overhead
+  2. [best_practices] Zod schemas can be inferred as TypeScript types using z.infer<>
+  3. [architecture_patterns] Repository pattern separates data access from business logic
+
+All learnings will be auto-curated and made available in future sessions.
+```
+
+## Example Workflow
+
+**Scenario:** User runs `/learn` after working on FastAPI CORS configuration
+
+**Step 1:** Claude analyzes session and generates suggestions:
+- "FastAPI middleware order matters for CORS - app.add_middleware() calls must be in reverse order of execution"
+- "CORSMiddleware must be added after other middleware to work correctly"
+
+**Step 2:** AskUserQuestion shows:
+```
+I've identified some potential learnings from this session. Select all that apply, or add your own:
+
+☐ FastAPI middleware order matters for CORS - app.add_middleware() calls must be in reverse order of execution
+☐ CORSMiddleware must be added after other middleware to work correctly
+☐ Type something - Add custom learnings (one per line)
+```
+
+User selects first two options.
+
+**Step 3:** Claude auto-categorizes:
+- Learning 1 → `gotchas` (middleware ordering gotcha)
+- Learning 2 → `best_practices` (correct configuration approach)
+
+**Step 4:** Claude runs commands:
+```bash
+sk learn add-learning \
+  --content "FastAPI middleware order matters for CORS - app.add_middleware() calls must be in reverse order of execution" \
+  --category "gotchas" \
+  --tags "fastapi,cors,middleware" \
+  --session "5"
+
+sk learn add-learning \
+  --content "CORSMiddleware must be added after other middleware to work correctly" \
+  --category "best_practices" \
+  --tags "fastapi,cors,middleware" \
+  --session "5"
+```
+
+**Output to user:**
+```
+✓ Captured 2 learnings:
+  1. [gotchas] FastAPI middleware order matters for CORS - app.add_middleware() calls must be in reverse order of execution
+  2. [best_practices] CORSMiddleware must be added after other middleware to work correctly
+
+All learnings will be auto-curated and made available in future sessions.
+```