lite-kits 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

lite_kits/kits/dev/README.md

@@ -0,0 +1,241 @@
+# Dev Kit
+
+**Status**: ✅ Recommended (Default)
+
+Essential development utilities for solo developers using spec-kit. Combines project management commands with git workflow automation.
+
+## What It Adds
+
+### Commands (AI Agents)
+
+| Command | Claude Code | GitHub Copilot | Description |
+|---------|-------------|----------------|-------------|
+| `/orient` | ✅ | ✅ | Agent orientation protocol (most essential!) |
+| `/commit` | ✅ | ✅ | Smart commit with staging and message generation |
+| `/pr` | ✅ | ✅ | Pull request creation with auto-push |
+| `/review` | ✅ | ✅ | Code review helper for staged changes |
+| `/cleanup` | ✅ | ✅ | Safe branch cleanup (delete merged branches) |
+| `/audit` | 🚧 | 🚧 | Security & quality audit (coming soon) |
+| `/stats` | 🚧 | 🚧 | Project statistics (coming soon) |
+
+✅ = Implemented | 🚧 = Coming Soon
+
+## Installation
+
+### As recommended kit (default):
+```bash
+lite-kits add  # Installs dev-kit
+```
+
+### Individually:
+```bash
+lite-kits add --kit dev
+```
+
+## What Gets Installed
+
+```
+your-project/
+├── .claude/commands/              # If Claude Code detected
+│   ├── orient.md                  # ✅ Essential!
+│   ├── commit.md                  # ✅ Smart commits
+│   ├── pr.md                      # ✅ PR creation
+│   ├── review.md                  # ✅ Code review
+│   ├── cleanup.md                 # ✅ Branch cleanup
+│   ├── audit.md                   # 🚧 Coming Soon
+│   └── stats.md                   # 🚧 Coming Soon
+└── .github/prompts/               # If GitHub Copilot detected
+    ├── orient.prompt.md           # ✅ Essential!
+    ├── commit.prompt.md           # ✅ Smart commits
+    ├── pr.prompt.md               # ✅ PR creation
+    ├── review.prompt.md           # ✅ Code review
+    ├── cleanup.prompt.md          # ✅ Branch cleanup
+    ├── audit.prompt.md            # 🚧 Coming Soon
+    └── stats.prompt.md            # 🚧 Coming Soon
+```
+
+**Note**: Vanilla spec-kit files are **never modified** - only new files are added.
+
+## Commands
+
+### `/orient` - Agent Orientation ⭐ ESSENTIAL
+
+**Purpose**: Help AI agents quickly understand project context before starting work.
+
+**What it does**:
+1. Detects installed kits
+2. Determines agent role
+3. Reads project documentation (`.github/copilot-instructions.md`, `.specify/memory/constitution.md`)
+4. Checks current git state (branch, recent commits, changes)
+5. Reviews active spec work
+6. Outputs concise summary (~150 words max)
+
+**Example usage**:
+```
+/orient
+
+## Orientation Complete
+
+**Installed Kits**: dev
+
+**I am**: claude-sonnet-4.5 @ Claude Code (Primary)
+**Project**: Lite-kits - Lightweight enhancement kits for spec-driven development
+**Stack**: Python 3.11+, typer, rich
+**Branch**: develop
+**Recent work**: Merged PR #16 (kit refactor)
+**Uncommitted changes**: 12 files
+**Active feature**: None
+**Coordination**: Solo work
+
+**Next suggested action**: Review uncommitted changes with /review
+```
+
+**Why this is essential**: Every AI agent should run `/orient` at the start of each session to get up to speed quickly without wasting tokens.
+
+---
+
+### `/commit` - Smart Commit
+
+**Purpose**: Intelligent commit workflow with staging proposals and message generation.
+
+**What it does**:
+- Analyzes unstaged changes
+- Proposes files to stage
+- Generates conventional commit message
+- Shows combined staging + message for approval
+- Supports multi-commit suggestions for large changesets
+
+---
+
+### `/pr` - Pull Request Creation
+
+**Purpose**: Create pull request with automatic branch push.
+
+**What it does**:
+- Checks for existing PR (prevents duplicates)
+- Pushes current branch to remote
+- Generates PR description from commits
+- Creates PR via `gh pr create`
+- Shows PR URL when complete
+
+---
+
+### `/review` - Code Review
+
+**Purpose**: Review staged changes against project conventions and best practices.
+
+**What it does**:
+- Analyzes staged changes (`git diff --staged`)
+- Checks against constitution principles
+- Identifies common code smells
+- Suggests improvements
+- Verifies test coverage
+
+---
+
+### `/cleanup` - Branch Cleanup
+
+**Purpose**: Safely delete merged branches.
+
+**What it does**:
+- Lists merged branches
+- Excludes current branch, base branches (main/develop)
+- Confirms before deletion
+- Optional remote deletion (`--remote` flag)
+- Protected branch safety
+
+---
+
+### `/audit` - Security & Quality Audit (Coming Soon)
+
+**Purpose**: Scan for security issues and quality problems.
+
+**Planned features**:
+- Scan for hardcoded secrets/credentials
+- Check for common vulnerabilities (SQL injection, XSS, CSRF)
+- Analyze dependencies for known CVEs
+- Verify input validation
+- Check file permissions
+
+---
+
+### `/stats` - Project Statistics (Coming Soon)
+
+**Purpose**: Show project health metrics.
+
+**Planned features**:
+- Lines of code by language
+- Test coverage percentage
+- Git activity with agent attribution
+- Complexity metrics
+- Dependency count
+- Health score
+
+---
+
+## Use Cases
+
+### Solo Developer with AI Agent
+**Install**: `lite-kits add` (includes dev-kit)
+**Use**: `/orient` at start of every session, `/commit` and `/pr` for git workflow
+
+### Pair Programming with Claude Code
+**Install**: `lite-kits add`
+**Use**: `/orient` → `/review` → `/commit` → `/pr` workflow
+
+### Security-Focused Project
+**Install**: `lite-kits add --kit dev`
+**Use**: `/audit` regularly for security scans (when implemented)
+
+---
+
+## Configuration
+
+No configuration needed - works out of the box.
+
+**Optional customization**:
+- Edit `.github/copilot-instructions.md` - Affects `/orient` output
+- Edit `.specify/memory/constitution.md` - Project principles for `/review`
+
+---
+
+## Dependencies
+
+**None** - dev-kit is standalone.
+
+**Optional pairing**: Works great with multiagent-kit for team coordination.
+
+---
+
+## Compatibility
+
+- ✅ **Agents**: Claude Code, GitHub Copilot
+- ✅ **Platforms**: Linux, macOS, Windows
+- ✅ **Shells**: Bash, PowerShell
+- ✅ **Vanilla safe**: Only adds new files, never modifies existing
+
+---
+
+## Uninstall
+
+```bash
+lite-kits remove --kit dev
+```
+
+Removes:
+- `.claude/commands/{orient,commit,pr,review,cleanup,audit,stats}.md`
+- `.github/prompts/{orient,commit,pr,review,cleanup,audit,stats}.prompt.md`
+
+---
+
+## Future Enhancements
+
+Considering for dev-kit:
+- `/docs` - Generate/update documentation
+- `/history` - Show project timeline
+- `/dependencies` - Dependency analysis
+- `/performance` - Performance profiling
+- `/status` - Optimized git status command
+- Template library (api, cli, library, frontend feature templates)
+
+Suggest more in [GitHub Discussions](https://github.com/tmorgan181/lite-kits/discussions).

lite_kits/kits/dev/commands/.claude/audit.md

@@ -0,0 +1,143 @@
+---
+description: Perform security analysis on dependencies and code patterns
+---
+
+# Security Audit Helper
+
+**Purpose**: Quick security analysis for AI agents working on features involving authentication, data handling, or external dependencies.
+
+## Execution Steps
+
+Execute the following steps to perform a security audit:
+
+### 1. Detect Project Type and Dependencies
+
+```bash
+# Check for Python dependencies
+ls requirements.txt pyproject.toml setup.py 2>/dev/null
+
+# Check for Node.js dependencies
+ls package.json package-lock.json 2>/dev/null
+
+# Check for Rust dependencies
+ls Cargo.toml Cargo.lock 2>/dev/null
+
+# Check for Go dependencies
+ls go.mod go.sum 2>/dev/null
+```
+
+### 2. Run Dependency Vulnerability Scan
+
+**Python projects**:
+```bash
+# Check if pip-audit is available
+command -v pip-audit >/dev/null 2>&1
+
+# If available, run scan
+pip-audit
+
+# If not available, suggest installation
+echo "Install pip-audit: pip install pip-audit"
+```
+
+**Node.js projects**:
+```bash
+# npm audit is built-in
+npm audit
+
+# Or use yarn
+yarn audit
+```
+
+**Other languages**: Suggest appropriate tools (cargo audit, go list, etc.)
+
+### 3. Scan for Common Security Anti-Patterns
+
+Check source code for security issues:
+
+```bash
+# Look for potential hardcoded secrets
+grep -r "API_KEY\s*=\s*['\"]" src/ 2>/dev/null | head -5
+grep -r "PASSWORD\s*=\s*['\"]" src/ 2>/dev/null | head -5
+grep -r "SECRET\s*=\s*['\"]" src/ 2>/dev/null | head -5
+
+# Look for weak crypto patterns (Python)
+grep -r "md5\|sha1" src/ 2>/dev/null | head -5
+
+# Look for SQL injection risks
+grep -r "execute.*%\|execute.*+" src/ 2>/dev/null | head -5
+```
+
+**Common patterns to flag**:
+- Hardcoded API keys, passwords, tokens
+- Weak cryptographic algorithms (MD5, SHA1)
+- SQL string concatenation
+- Eval/exec with user input
+- Insecure file permissions
+
+### 4. Generate Concise Report
+
+Provide analysis in this format (~150 words max):
+
+```markdown
+## Security Audit
+
+**Dependencies**: N scanned, M vulnerabilities found
+
+**Vulnerabilities** (if any):
+- package-name==version: [SEVERITY] - Brief description
+- Link to advisory for details
+
+**Code Patterns** (if any):
+- file.py:line: [PATTERN] - Recommendation
+
+**Next Action**: [Fix CVE-XXXX / Update package / Review auth code]
+```
+
+## Important Notes
+
+- **Graceful fallbacks**: If audit tools not installed, do basic pattern checks only
+- **Be concise**: Target <150 words total output
+- **Prioritize**: Show highest severity issues first
+- **Avoid false positives**: Note that manual review may be needed
+- **No dependencies**: Report "No dependencies to audit" gracefully
+- **Cross-platform**: Use commands available on Windows, macOS, Linux
+
+## Edge Cases
+
+- **No dependency files**: "No dependencies found. This appears to be a dependency-free project."
+- **Tool not installed**: Provide installation command, run basic grep checks
+- **No vulnerabilities**: "✅ No known vulnerabilities found! Consider reviewing auth/data handling patterns."
+- **Too many issues**: Sample top 5, note total count
+
+## Example Output
+
+```markdown
+## Security Audit
+
+**Dependencies**: 12 scanned, 2 vulnerabilities found
+
+**Vulnerabilities**:
+- requests==2.25.0: MEDIUM - CVE-2023-32681 (Proxy-Auth header leak)
+  Update to: requests>=2.31.0
+
+**Code Patterns**:
+- src/auth.py:42: Hardcoded API key detected
+- src/db.py:103: SQL string concatenation (injection risk)
+
+**Next Action**: Update requests package, move API key to environment variables, use parameterized queries
+```
+
+```markdown
+## Security Audit
+
+**Dependencies**: pip-audit not installed
+
+**Tool Not Available**:
+Install pip-audit for vulnerability scanning:
+`pip install pip-audit`
+
+**Code Patterns**: Basic grep checks performed, no obvious issues found
+
+**Next Action**: Install pip-audit and re-run for comprehensive dependency scan
+```

lite_kits/kits/{git/claude/commands → dev/commands/.claude}/cleanup.md

@@ -297,13 +297,13 @@ dev/004-cleanup-command
 $ git branch --merged develop
   dev/001-starter-kits
   dev/002-installer-polish
-  dev/003-git-kit-enhancements
+  dev/003-dev-kit-enhancements
 
 # Agent presents options
 Merged branches available for cleanup:
 1. dev/001-starter-kits (2 days ago)
 2. dev/002-installer-polish (1 day ago)
-3. dev/003-git-kit-enhancements (2 hours ago)
+3. dev/003-dev-kit-enhancements (2 hours ago)
 
 Delete which branches? (y/n/e): e
 

lite_kits/kits/{git/claude/commands → dev/commands/.claude}/commit.md

@@ -260,7 +260,7 @@ Message:
 9. ?? docs/new-guide.md
 
 Message:
-  docs(004): update documentation for git-kit
+  docs(004): update documentation for dev-kit
 
   Added git workflow documentation and updated README
   with new command examples.
@@ -274,7 +274,7 @@ Message:
 Message:
   chore(004): update implementation status tracking
 
-  Marked git-kit as complete in status docs.
+  Marked dev-kit as complete in status docs.
 
 ---
 

lite_kits/kits/{project/claude/commands → dev/commands/.claude}/orient.md

@@ -15,19 +15,11 @@ Execute the following steps to gather orientation information:
 Check for kit marker files to determine what's installed:
 
 ```bash
-# Initialize kit detection variables
-PROJECT_KIT=false
-GIT_KIT=false
-MULTIAGENT_KIT=false
-
-# Check for project-kit markers
-[ -f .claude/commands/review.md ] && PROJECT_KIT=true
-
-# Check for git-kit markers
-[ -f .claude/commands/commit.md ] && GIT_KIT=true
-
-# Check for multiagent-kit markers
-[ -f .specify/memory/pr-workflow-guide.md ] && MULTIAGENT_KIT=true
+# Check all kits in one command
+KITS_INSTALLED=""
+[ -f .claude/commands/orient.md ] && KITS_INSTALLED="${KITS_INSTALLED}dev "
+[ -f .specify/memory/pr-workflow-guide.md ] && KITS_INSTALLED="${KITS_INSTALLED}multiagent "
+KITS_INSTALLED="${KITS_INSTALLED:-vanilla only}"
 ```
 
 ### 2. Determine Agent Role
@@ -58,17 +50,11 @@ Extract:
 ### 4. Check Git State
 
 ```bash
-# Current branch
-git branch --show-current
-
-# Recent commits (last 5)
-git log --oneline -5
-
-# Uncommitted changes
-git status --short
-
-# Untracked files count
-git ls-files --others --exclude-standard | wc -l
+# Efficient single-command git status check
+# Get branch, recent commits, and changes in one go
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "(not in git repo)")
+RECENT_COMMITS=$(git log --oneline -3 2>/dev/null | head -1 || echo "(no commits)")
+CHANGES=$(git status --short 2>/dev/null | wc -l || echo "0")
 ```
 
 ### 5. Check Active Work
@@ -76,29 +62,25 @@ git ls-files --others --exclude-standard | wc -l
 Look for active feature work:
 
 ```bash
-# List specs directories
-ls -1d specs/*/ 2>/dev/null | tail -3
-
-# Check for current spec/plan/tasks
-CURRENT_BRANCH=$(git branch --show-current)
-if [[ "$CURRENT_BRANCH" =~ ^[0-9]+ ]]; then
-  SPEC_DIR="specs/$CURRENT_BRANCH"
-  [ -f "$SPEC_DIR/spec.md" ] && echo "✓ Spec exists"
-  [ -f "$SPEC_DIR/plan.md" ] && echo "✓ Plan exists"
-  [ -f "$SPEC_DIR/tasks.md" ] && echo "✓ Tasks exist"
+# Check if current branch matches a spec directory
+if [[ "$CURRENT_BRANCH" =~ ^[0-9]+ ]] || [[ "$CURRENT_BRANCH" =~ ^dev/[0-9]+ ]]; then
+  # Extract spec number from branch name
+  SPEC_NUM=$(echo "$CURRENT_BRANCH" | grep -oE '[0-9]+' | head -1)
+  SPEC_DIR="specs/$SPEC_NUM-*"
+  # Check for spec files efficiently
+  SPEC_FILES=$(ls -1 $SPEC_DIR/{spec,plan,tasks}.md 2>/dev/null | wc -l)
 fi
 ```
 
 ### 6. Check Multi-Agent Coordination (if multiagent-kit installed)
 
-If `MULTIAGENT_KIT=true`:
-
 ```bash
-# Check for active sessions
-find specs/*/collaboration/active/sessions/ -name "*.md" 2>/dev/null | wc -l
-
-# Check for pending handoffs
-find specs/*/collaboration/active/decisions/ -name "handoff-*.md" 2>/dev/null | head -1
+# Only check if multiagent kit is installed
+if [[ "$KITS_INSTALLED" == *"multiagent"* ]]; then
+  # Efficient check for collaboration activity
+  ACTIVE_SESSIONS=$(find specs/*/collaboration/active/sessions/ -name "*.md" 2>/dev/null | wc -l)
+  PENDING_HANDOFF=$(find specs/*/collaboration/active/decisions/ -name "handoff-*.md" 2>/dev/null | head -1)
+fi
 ```
 
 ### 7. Generate Concise Output
@@ -108,15 +90,15 @@ Provide a **concise summary** (~150 words max) in this format:
 ```
 ## Orientation Complete
 
-**Installed Kits**: [list detected kits or "vanilla only"]
+**Installed Kits**: [KITS_INSTALLED]
 
 **I am**: [AGENT_ROLE from step 2]
 **Project**: [project name from docs]
 **Stack**: [main technologies]
-**Branch**: [current branch]
-**Recent work**: [summary of last 1-2 commits]
-**Uncommitted changes**: [count of modified files]
-**Active feature**: [current spec if on feature branch]
+**Branch**: [CURRENT_BRANCH]
+**Recent work**: [RECENT_COMMITS - just the message]
+**Uncommitted changes**: [CHANGES count]
+**Active feature**: [current spec if SPEC_FILES > 0]
 **Coordination**: [solo work / handoff pending / etc]
 
 **Next suggested action**: [based on state analysis below]
@@ -133,7 +115,7 @@ Based on the state you discovered, suggest the next logical action:
 - **Plan exists, no tasks** → "Run `/tasks` to break down into tasks"
 - **Tasks exist** → "Run `/implement` to start coding"
 - **Handoff detected** (multiagent) → "Review handoff in `specs/[feature]/collaboration/active/decisions/`"
-- **Uncommitted changes** → "Review changes and consider running `/commit`" (if git-kit installed)
+- **Uncommitted changes** → "Review changes and consider running `/commit`" (if dev-kit installed)
 
 ## Important Notes
 
@@ -148,7 +130,7 @@ Based on the state you discovered, suggest the next logical action:
 ```
 ## Orientation Complete
 
-**Installed Kits**: project, git
+**Installed Kits**: dev
 
 **I am**: claude-sonnet-4.5 @ Claude Code (Primary)
 **Project**: Blog Platform API (TypeScript/Node.js)

lite_kits/kits/{git/claude/commands → dev/commands/.claude}/pr.md

@@ -341,7 +341,7 @@ Implements Phase 1 MVP with `/orient` command and modular kit system for multi-a
 ## Changes
 
 ### Features
-- Add `/orient` command for agent orientation (project-kit)
+- Add `/orient` command for agent orientation (dev-kit)
 - Implement kit-aware installer with --kit flag support
 - Add modular kit structure (project, git, multiagent)
 - Auto-dependency inclusion (multiagent → project + git)