devflow-kit 0.1.0

package/src/claude/commands/devflow/devlog.md

@@ -0,0 +1,370 @@
+---
+allowed-tools: Bash, Read, Grep, Glob, Write, TodoWrite, Task
+description: Create a development log entry capturing current project state and context
+---
+
+## Your task
+
+Create a comprehensive development log entry that captures the current state of the project, recent work, decisions made, and what's left to do. This serves as a time capsule for any developer (including yourself) returning to this project later.
+
+### Step 1: Capture Agent's Internal Todo List
+
+**CRITICAL FIRST STEP**: Before doing anything else, capture the agent's current internal todo list state.
+
+Use TodoWrite to dump the current todo list, then immediately document it:
+
+```bash
+# This will be the current todo list that needs to be preserved
+# The agent should use TodoWrite to get their current state
+```
+
+**MANDATORY**: Document ALL current todos with their exact status:
+- content (exact task description)
+- status (pending/in_progress/completed)
+- activeForm (present tense description)
+
+This state MUST be preserved so future sessions can recreate the todo list exactly.
+
+### Step 2: Gather Context
+
+Determine the current date/time and project information:
+
+```bash
+# Get current date in DD-MM-YYYY format
+DATE=$(date +"%d-%m-%Y")
+TIME=$(date +"%H%M")
+TIMESTAMP="${DATE}_${TIME}"
+
+# Get project name from current directory
+PROJECT_NAME=$(basename $(pwd))
+
+# Create docs directory if it doesn't exist
+mkdir -p .docs/status
+```
+
+### Step 3: Analyze Current Conversation
+
+Review the current conversation context to understand:
+- What was being worked on
+- What problems were solved
+- What decisions were made
+- What's still pending
+
+### Step 4: Gather Project State
+
+Analyze the current project state:
+
+```bash
+# Recent git activity
+git log --oneline -10 2>/dev/null || echo "No git history"
+
+# Current branch and status
+git branch --show-current 2>/dev/null
+git status --short 2>/dev/null
+
+# Recent file changes
+find . -type f -mtime -1 -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/venv/*" -not -path "*/target/*" -not -path "*/build/*" 2>/dev/null | head -20
+
+# Check for TODO/FIXME comments across common source file extensions
+grep -r "TODO\|FIXME\|HACK\|XXX" \
+  --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" \
+  --include="*.py" --include="*.go" --include="*.rs" --include="*.java" \
+  --include="*.c" --include="*.cpp" --include="*.h" --include="*.hpp" \
+  --include="*.rb" --include="*.php" --include="*.swift" --include="*.kt" \
+  -l 2>/dev/null | head -10
+```
+
+### Step 5: Check Documentation
+
+Look for existing project documentation to understand:
+- Architecture decisions (ARCHITECTURE.md, ADR/)
+- README status
+- API documentation
+- Any existing notes
+
+### Step 6: Generate Comprehensive Status Document
+
+Create `.docs/status/{timestamp}.md` with the following structure:
+
+```markdown
+# Project Status - {PROJECT_NAME}
+**Date**: {DATE}
+**Time**: {TIME}
+**Author**: Claude (AI Assistant)
+**Session Context**: {Brief description of what was being worked on}
+
+---
+
+## 🎯 Current Focus
+
+### What We Were Working On
+{Detailed description of the current task/feature being developed}
+
+### Problems Solved Today
+1. {Problem 1 and solution}
+2. {Problem 2 and solution}
+3. {Problem 3 and solution}
+
+### Decisions Made
+- **Decision**: {What was decided}
+  **Rationale**: {Why this approach}
+  **Alternatives Considered**: {Other options that were rejected}
+
+---
+
+## 📊 Project State
+
+### Recent Changes
+```
+{Git log showing recent commits}
+```
+
+### Files Modified Recently
+- `path/to/file1` - {What was changed and why}
+- `path/to/file2` - {What was changed and why}
+
+### Current Branch
+- Branch: `{branch_name}`
+- Status: {Clean/Dirty with uncommitted changes}
+
+---
+
+## 🏗️ Architecture & Design
+
+### Key Architectural Decisions
+1. {Pattern/Decision 1}
+   - Why: {Rationale}
+   - Impact: {How it affects the codebase}
+
+2. {Pattern/Decision 2}
+   - Why: {Rationale}
+   - Impact: {How it affects the codebase}
+
+### Technology Stack
+- **Language**: {Primary programming language}
+- **Framework**: {Main framework or runtime}
+- **Data Storage**: {Database or storage system}
+- **Key Dependencies**: {Critical libraries or packages}
+
+### Design Patterns in Use
+- {Pattern 1}: {Where and why}
+- {Pattern 2}: {Where and why}
+
+---
+
+## ⚠️ Known Issues & Technical Debt
+
+### Critical Issues
+1. {Issue description}
+   - Location: `file/path`
+   - Impact: {High/Medium/Low}
+   - Suggested Fix: {Approach}
+
+### Technical Debt
+1. {Debt item}
+   - Why it exists: {Historical reason}
+   - Cost of fixing: {Estimate}
+   - Priority: {High/Medium/Low}
+
+### TODOs in Codebase
+```
+{List of files with TODO/FIXME comments}
+```
+
+---
+
+## 📋 Agent Todo List State
+
+**CRITICAL**: This section preserves the agent's internal todo list state for session continuity.
+
+### Current Todo List (for recreation)
+```json
+{Exact TodoWrite JSON with all current todos}
+```
+
+### Todo Summary
+- **Total tasks**: {count}
+- **Pending**: {count of pending tasks}
+- **In Progress**: {count of in_progress tasks}
+- **Completed**: {count of completed tasks}
+
+### Key Active Tasks
+- 🔄 **In Progress**: {current active task}
+- ⏳ **Next Priority**: {next pending task}
+
+---
+
+## 🚀 Next Steps
+
+### Immediate (Next Session)
+- [ ] **FIRST**: Recreate agent todo list using TodoWrite with preserved state above
+- [ ] {Task 1 from conversation}
+- [ ] {Task 2 from conversation}
+- [ ] {Task 3 from conversation}
+
+### Short Term (This Week)
+- [ ] {Goal 1}
+- [ ] {Goal 2}
+
+### Long Term (This Month)
+- [ ] {Major milestone 1}
+- [ ] {Major milestone 2}
+
+---
+
+## 💡 Context for Future Developer
+
+### Things to Know
+1. **Gotcha #1**: {Something non-obvious}
+2. **Gotcha #2**: {Another tricky thing}
+3. **Convention**: {Project-specific convention}
+
+### Where to Start
+If you're picking this up later, here's where to begin:
+1. Check {specific file/area}
+2. Review {documentation}
+3. Run {command} to verify setup
+
+### Key Files to Understand
+- `path/to/important/file1` - {Why it's important}
+- `path/to/important/file2` - {Why it's important}
+
+### Testing Strategy
+- How to run tests: `{command}`
+- Test coverage: {status}
+- Critical test files: {list}
+
+---
+
+## 🔗 Related Documents
+
+### Project Documentation
+- README.md - {Status: Updated/Outdated/Missing}
+- CONTRIBUTING.md - {Status}
+- ARCHITECTURE.md - {Status}
+
+### Previous Status Notes
+{Link to previous status documents if they exist}
+
+---
+
+## 📝 Raw Session Notes
+
+### What the User Asked For
+{Original user request}
+
+### Approach Taken
+{Step-by-step what was done}
+
+### Challenges Encountered
+{Any difficulties and how they were resolved}
+
+### Time Spent
+- Estimated session duration: {from timestamp data if available}
+- Complexity level: {Simple/Medium/Complex}
+
+---
+
+## 🤖 AI Assistant Metadata
+
+### Model Used
+- Model: {Claude model version}
+- Capabilities: {What tools were available}
+- Limitations encountered: {Any AI limitations that affected work}
+
+### Commands/Tools Used
+- {Tool 1}: {How it was used}
+- {Tool 2}: {How it was used}
+
+---
+
+## 📌 Final Thoughts
+
+{A brief paragraph of final thoughts, advice, or warnings for whoever picks this up next. Written in first person as if leaving a note to your future self or a colleague.}
+
+**Remember**: This is a snapshot in time. The project will have evolved since this was written. Use this as a starting point for understanding, not as gospel truth.
+
+---
+*This document was auto-generated by the `/devlog` command*
+*To generate a new status report, run `/devlog` in Claude Code*
+```
+
+### Step 7: Create Compact Version
+
+Create a compact summary at `.docs/status/compact/{timestamp}.md`:
+
+```markdown
+# Compact Status - {DATE}
+
+**Focus**: {One-line summary of what was worked on}
+
+**Key Accomplishments**:
+- {Accomplishment 1}
+- {Accomplishment 2}
+- {Accomplishment 3}
+
+**Critical Decisions**:
+- {Decision 1}: {Brief rationale}
+- {Decision 2}: {Brief rationale}
+
+**Next Priority Actions**:
+- [ ] {Top priority task}
+- [ ] {Second priority task}
+- [ ] {Third priority task}
+
+**Critical Issues**:
+- {Blocker 1}: {One-line description}
+- {Blocker 2}: {One-line description}
+
+**Key Files Modified**:
+- `{file1}` - {Brief change description}
+- `{file2}` - {Brief change description}
+- `{file3}` - {Brief change description}
+
+**Context Notes**:
+{2-3 sentences of essential context for future sessions}
+
+---
+*Quick summary of [full status](./../{timestamp}.md)*
+```
+
+### Step 8: Create Summary Index
+
+Also update or create `.docs/status/INDEX.md` to list all status documents:
+
+```markdown
+# Status Document Index
+
+## Quick Reference
+- [Latest Catch-Up Summary](../CATCH_UP.md) - For getting back up to speed
+
+## Recent Status Reports
+
+| Date | Time | Focus | Full | Compact |
+|------|------|-------|------|---------|
+| {DATE} | {TIME} | {Brief description} | [Full](./{timestamp}.md) | [Quick](./compact/{timestamp}.md) |
+{Previous entries...}
+
+## Usage
+- **Starting a session?** → Use `/catch-up` command or check latest compact status
+- **Ending a session?** → Use `/devlog` to document progress
+- **Need full context?** → Read the full status documents
+- **Quick reference?** → Use compact versions
+```
+
+### Step 9: Confirm Creation
+
+After creating the document, provide confirmation:
+- Full path to the created document
+- Brief summary of what was captured
+- Suggestion to review and edit if needed
+
+### Important Considerations
+
+1. **Be Honest**: Include both successes and failures
+2. **Be Specific**: Use actual file paths and function names
+3. **Be Helpful**: Write as if explaining to someone unfamiliar with recent work
+4. **Be Concise**: Balance detail with readability
+5. **Include Context**: Explain the "why" behind decisions
+
+The goal is to create a time capsule that will be genuinely useful when someone (maybe you!) returns to this project after weeks or months away.

package/src/claude/commands/devflow/plan-next-steps.md

@@ -0,0 +1,212 @@
+---
+allowed-tools: TodoWrite, Read, Write, Edit, MultiEdit, Bash, Grep, Glob, Task
+description: Extract actionable next steps from current discussion and save to todo list
+---
+
+## Your task
+
+Analyze the current discussion and convert it into specific, actionable next steps that can be saved to the agent's internal todo list using TodoWrite. This command bridges the gap between talking about what to do and actually tracking concrete steps.
+
+**🎯 FOCUS**: Turn discussion into trackable action items for the agent's internal todo list.
+
+### Step 1: Extract Next Steps from Discussion
+
+**FOCUS**: Look at the current discussion and identify concrete next steps that emerged from the conversation.
+
+**What to Extract**:
+- **Immediate tasks** mentioned or implied in the discussion
+- **Code changes** that were discussed or agreed upon
+- **Files** that need to be created, modified, or reviewed
+- **Dependencies** that need to be installed or configured
+- **Tests** that need to be written or updated
+- **Documentation** that needs updating
+- **Investigations** or research tasks mentioned
+- **Decisions** that need to be made before proceeding
+
+**Look for phrases like**:
+- "We should..."
+- "Next, I'll..."
+- "Let me..."
+- "I need to..."
+- "We could..."
+- "First, we'll..."
+
+### Step 2: Convert to Actionable Todo Items
+
+Transform the extracted items into specific todo tasks that can be tracked:
+
+**Good todo items**:
+- ✅ "Add authentication middleware to routes in `/src/middleware/auth`"
+- ✅ "Write unit tests for user registration in `/tests/auth_test`"
+- ✅ "Install password hashing library dependency"
+- ✅ "Research API schema design for user endpoints"
+- ✅ "Update README.md with new authentication setup instructions"
+
+**Bad todo items**:
+- ❌ "Improve authentication" (too vague)
+- ❌ "Add better error handling" (not specific)
+- ❌ "Make it more secure" (not actionable)
+
+### Step 3: Save to Todo List with TodoWrite
+
+**IMMEDIATELY** use TodoWrite to save the action items to the agent's internal todo list. Each task should:
+- Be specific and testable
+- Include file paths when relevant
+- Be completable in 15-30 minutes
+- Have clear success criteria
+- Start as "pending" status
+
+Example todo structure:
+```json
+[
+  {
+    "content": "Install password hashing library dependency",
+    "status": "pending",
+    "activeForm": "Installing password hashing library"
+  },
+  {
+    "content": "Create authentication middleware in src/middleware/auth",
+    "status": "pending",
+    "activeForm": "Creating authentication middleware"
+  },
+  {
+    "content": "Add password hashing to user registration in src/routes/users",
+    "status": "pending",
+    "activeForm": "Adding password hashing to user registration"
+  },
+  {
+    "content": "Write unit tests for auth middleware in tests/auth_test",
+    "status": "pending",
+    "activeForm": "Writing unit tests for auth middleware"
+  },
+  {
+    "content": "Update API documentation for new auth endpoints",
+    "status": "pending",
+    "activeForm": "Updating API documentation"
+  }
+]
+```
+
+### Step 4: Prioritize the Todo Items
+
+Arrange the todo items in logical order:
+1. **Dependencies first** (installations, setup)
+2. **Core implementation** (main functionality)
+3. **Tests and validation** (verification)
+4. **Documentation** (updates, guides)
+5. **Follow-up tasks** (optimizations, research)
+
+### Step 5: Present the Todo List
+
+Show the developer what was extracted and saved:
+
+```markdown
+## 📋 Next Steps Added to Todo List
+
+Based on our discussion, I've identified and saved these action items:
+
+### Immediate Tasks (Dependencies)
+- [ ] {Task 1}
+- [ ] {Task 2}
+
+### Core Implementation
+- [ ] {Task 3}
+- [ ] {Task 4}
+- [ ] {Task 5}
+
+### Testing & Validation
+- [ ] {Task 6}
+- [ ] {Task 7}
+
+### Documentation
+- [ ] {Task 8}
+
+**Total: {X} tasks added to internal todo list**
+**Ready to begin? The agent can now start working through these systematically.**
+```
+
+---
+
+## Usage Examples
+
+### Example 1: After Feature Discussion
+```
+Human: "Add user authentication to our web application"
+AI: "I can help with that. What type of auth do you prefer?"
+Human: "Token-based auth, and we need password reset functionality"
+AI: "Got it. Should I use a password hashing library?"
+Human: "Yes, and integrate with our existing database"
+Developer: "/standup"
+
+Result: AI extracts action items from discussion:
+- Install password hashing and token libraries
+- Create user authentication middleware
+- Set up password reset email functionality
+- Create database migration for user auth tables
+- Write unit tests for auth endpoints
+- Update API documentation
+
+📋 6 tasks added to internal todo list
+```
+
+### Example 2: After Bug Investigation
+```
+Human: "Users are reporting slow page loads on the dashboard"
+AI: "Let me investigate the dashboard queries. I found the issue - it's doing N+1 queries on user data."
+Human: "Can you fix that?"
+AI: "Yes, I'll add proper joins and implement pagination."
+Developer: "/plan-next-steps"
+
+Result: AI creates specific action items:
+- Add eager loading to user dashboard query
+- Implement pagination for dashboard data
+- Add database indexes for performance
+- Write performance test for dashboard endpoint
+- Update frontend to handle paginated data
+
+📋 5 tasks added to internal todo list
+```
+
+### Example 3: After Planning Discussion
+```
+Human: "I want to migrate our REST API to a query-based API"
+AI: "That's a big change. Should we do it gradually?"
+Human: "Yes, start with user endpoints but keep REST for compatibility"
+AI: "I'll create a hybrid approach with both API styles."
+Developer: "/standup"
+
+Result: AI saves implementation steps:
+- Install query API framework dependencies
+- Create API schema for user types
+- Implement user query resolvers
+- Set up query endpoint alongside REST
+- Write integration tests for new API
+- Update documentation for new endpoints
+
+📋 6 tasks added to internal todo list
+```
+
+---
+
+## Command Behavior Rules
+
+### ALWAYS Do These:
+- ✅ Extract concrete action items from the discussion
+- ✅ Use TodoWrite to save tasks to internal todo list
+- ✅ Break tasks into 15-30 minute chunks
+- ✅ Include file paths and specific details
+- ✅ Prioritize tasks in logical order
+
+### NEVER Do These:
+- ❌ Create vague or untestable tasks
+- ❌ Skip obvious implementation steps
+- ❌ Forget to use TodoWrite to save the list
+- ❌ Make tasks too large or complex
+- ❌ Ignore dependencies or prerequisites
+
+### Focus Areas:
+- 🎯 **Extract**: Pull concrete next steps from discussion
+- 🎯 **Clarify**: Make each task specific and actionable
+- 🎯 **Save**: Use TodoWrite to store in agent's todo list
+- 🎯 **Present**: Show what was captured for verification
+

package/src/claude/commands/devflow/pre-commit.md

@@ -0,0 +1,138 @@
+---
+description: Review uncommitted changes before committing using specialized sub-agents
+allowed-tools: Task, Bash, Read, Write, Grep, Glob
+---
+
+## Your Task
+
+Perform a comprehensive review of uncommitted changes by orchestrating multiple specialized sub-agents in parallel. This provides quick feedback before committing changes.
+
+### Step 1: Analyze Current Changes
+
+First, check what changes are available for review:
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+
+# Get the diff of uncommitted changes
+if git diff --quiet HEAD; then
+    echo "No uncommitted changes to review"
+    exit 0
+fi
+
+# Show summary of changes
+echo "=== CHANGES TO REVIEW ==="
+git diff --stat HEAD
+echo ""
+```
+
+### Step 2: Launch Specialized Sub-Agents in Parallel
+
+Launch these sub-agents in parallel:
+
+1. audit-security sub-agent
+2. audit-performance sub-agent
+3. audit-architecture sub-agent
+4. audit-tests sub-agent
+5. audit-complexity sub-agent
+
+### Step 3: Synthesize Review Findings
+
+After all sub-agents complete their analysis:
+
+1. **Collect Results**: Gather findings from all sub-agents
+2. **Prioritize Issues**: Categorize as Critical/High/Medium/Low
+3. **Create Unified Review**: Synthesize into coherent review document
+4. **Generate Action Items**: Provide specific next steps
+
+### Step 4: Save Review Document
+
+Create a comprehensive review document at `.docs/reviews/diff-{YYYY-MM-DD_HHMM}.md`:
+
+```markdown
+# Code Review - Uncommitted Changes
+**Date**: {current_date}
+**Time**: {current_time}
+**Type**: Differential Review (uncommitted changes)
+**Reviewer**: AI Sub-Agent Orchestra
+
+---
+
+## 📊 Review Summary
+
+**Files Changed**: {number}
+**Lines Added**: {number}
+**Lines Removed**: {number}
+
+### Issues Found
+- 🔴 **Critical**: {count} issues requiring immediate attention
+- 🟠 **High**: {count} issues should be addressed before commit
+- 🟡 **Medium**: {count} improvements recommended
+- 🔵 **Low**: {count} minor suggestions
+
+---
+
+## 🔍 Detailed Analysis
+
+### Security Review (audit-security)
+{security findings with file:line references}
+
+### Performance Review (audit-performance)
+{performance findings with specific optimizations}
+
+### Architecture Review (audit-architecture)
+{design pattern and structure analysis}
+
+### Test Coverage Review (audit-tests)
+{test gaps and quality assessment}
+
+### Complexity Review (audit-complexity)
+{maintainability and refactoring suggestions}
+
+---
+
+## 🎯 Action Items
+
+### Before Committing (Critical/High)
+- [ ] {action 1} in {file:line}
+- [ ] {action 2} in {file:line}
+
+### Future Improvements (Medium/Low)
+- [ ] {improvement 1}
+- [ ] {improvement 2}
+
+---
+
+## 📈 Code Quality Metrics
+
+**Overall Assessment**: {Excellent/Good/Needs Work/Poor}
+**Commit Recommendation**: {✅ Safe to commit / ⚠️ Address issues first / 🚫 Do not commit}
+
+---
+
+*Review generated by DevFlow sub-agent orchestration*
+```
+
+### Step 5: Provide Interactive Summary
+
+Give the developer a clear summary and next steps:
+
+```
+🔍 UNCOMMITTED CHANGES REVIEW COMPLETE
+
+Changes analyzed: {X} files, {Y} lines modified
+Issues found: {Critical} critical, {High} high, {Medium} medium, {Low} low
+
+📋 COMMIT READINESS ASSESSMENT:
+{✅ SAFE TO COMMIT | ⚠️ ISSUES TO ADDRESS | 🚫 DO NOT COMMIT}
+
+🎯 TOP PRIORITY ACTIONS:
+1. {Most critical issue and fix}
+2. {Second most critical issue and fix}
+3. {Third most critical issue and fix}
+
+📄 Full review saved to: .docs/reviews/diff-{timestamp}.md
+
+💡 TIP: Run `/review-branch` before creating PR for comprehensive feature review
+```