Initial commit
This commit is contained in:
Zhongwei Li
618
skills/README.md
Normal file
618
skills/README.md
Normal file
@@ -0,0 +1,618 @@
|
||||
# Contextune Skills - Autonomous Expert Guidance
|
||||
|
||||
**Version:** 0.5.4
|
||||
**Status:** ✅ Experimental (0.x)
|
||||
|
||||
Contextune now includes **AI-powered Skills** that provide autonomous expert guidance. Skills are **model-invoked** - Claude automatically activates them when you need help, no commands required!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Are Skills?
|
||||
|
||||
Skills are specialized capabilities that Claude autonomously uses based on your requests. Unlike slash commands (which you invoke explicitly), Skills activate automatically when Claude detects you need expert help.
|
||||
|
||||
**Key Difference:**
|
||||
|
||||
```
|
||||
Slash Commands: User-invoked
|
||||
You: "/contextune:execute"
|
||||
Claude: Executes the command
|
||||
|
||||
Skills: Model-invoked
|
||||
You: "How can I speed up development?"
|
||||
Claude: *Automatically activates parallel-development-expert skill*
|
||||
"Let me analyze your project for parallelization opportunities..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Available Skills
|
||||
|
||||
### 1. **parallel-development-expert**
|
||||
|
||||
**What it does:** Provides expert guidance on parallel development workflows
|
||||
|
||||
**Activates when you mention:**
|
||||
- "How can I work on multiple features at once?"
|
||||
- "Speed up development"
|
||||
- "Parallel work"
|
||||
- "Concurrent tasks"
|
||||
- "Work on several things simultaneously"
|
||||
|
||||
**Capabilities:**
|
||||
- ✅ Analyzes your project for parallelizable tasks
|
||||
- ✅ Calculates time savings (30-70%)
|
||||
- ✅ Suggests optimal task breakdown
|
||||
- ✅ Teaches parallel development patterns
|
||||
- ✅ Quantifies performance improvements
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: "I need to build auth, dashboard, and analytics. Any way to speed this up?"
|
||||
|
||||
Claude: *Activates parallel-development-expert*
|
||||
|
||||
"Absolutely! These are highly parallelizable:
|
||||
|
||||
📊 Analysis:
|
||||
1. Authentication - Independent ✅ (3 hours)
|
||||
2. Dashboard - Independent ✅ (2.5 hours)
|
||||
3. Analytics - Independent ✅ (2 hours)
|
||||
|
||||
⚡ Time Savings:
|
||||
- Sequential: 7.5 hours
|
||||
- Parallel: 3 hours (60% faster!)
|
||||
|
||||
Would you like me to create a parallel execution plan?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. **intent-recognition**
|
||||
|
||||
**What it does:** Helps you discover Contextune capabilities
|
||||
|
||||
**Activates when you ask:**
|
||||
- "What can Contextune do?"
|
||||
- "How do I use this?"
|
||||
- "Show me examples"
|
||||
- "What commands are available?"
|
||||
- "Can you help me with...?"
|
||||
|
||||
**Capabilities:**
|
||||
- ✅ Explains Contextune features interactively
|
||||
- ✅ Shows natural language examples
|
||||
- ✅ Demonstrates capabilities
|
||||
- ✅ Guides first-time users
|
||||
- ✅ Provides "try saying..." suggestions
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: "What can Contextune do?"
|
||||
|
||||
Claude: *Activates intent-recognition*
|
||||
|
||||
"Contextune makes Claude Code more natural! Instead of memorizing commands,
|
||||
just describe what you want.
|
||||
|
||||
🎯 Main Capabilities:
|
||||
|
||||
1. Parallel Development - Work on multiple features simultaneously
|
||||
Try: 'work on auth and dashboard in parallel'
|
||||
|
||||
2. Smart Intent Detection - I understand what you're trying to do
|
||||
Try: 'speed up development'
|
||||
|
||||
3. Zero Configuration - Works immediately!
|
||||
|
||||
Want to try? Describe a project you're working on!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. **git-worktree-master**
|
||||
|
||||
**What it does:** Expert troubleshooting for git worktree issues
|
||||
|
||||
**Activates when you have:**
|
||||
- "Can't remove worktree" errors
|
||||
- Locked files or directories
|
||||
- Orphaned branches
|
||||
- Cleanup questions
|
||||
- Worktree conflicts
|
||||
|
||||
**Capabilities:**
|
||||
- ✅ Diagnoses worktree problems
|
||||
- ✅ Provides safe fixes (explains before executing)
|
||||
- ✅ Teaches prevention strategies
|
||||
- ✅ Offers automated cleanup scripts
|
||||
- ✅ Handles complex edge cases
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: "I can't remove worktrees/task-123, getting 'locked' error"
|
||||
|
||||
Claude: *Activates git-worktree-master*
|
||||
|
||||
"Let me diagnose that...
|
||||
|
||||
📊 Diagnosis:
|
||||
Worktree: worktrees/task-123
|
||||
Status: Locked ⚠️
|
||||
Cause: Lock file present (git operation interrupted)
|
||||
|
||||
🔧 Safe Fix:
|
||||
1. Verify no git processes running ✅
|
||||
2. Remove lock file (safe, no data loss)
|
||||
3. Remove worktree properly
|
||||
|
||||
May I proceed? This will:
|
||||
✅ Remove the lock
|
||||
✅ Remove the worktree
|
||||
⚠️ Keep your branch (in case you need it)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. **performance-optimizer**
|
||||
|
||||
**What it does:** Analyzes and optimizes parallel workflow performance
|
||||
|
||||
**Activates when you:**
|
||||
- Report slow parallel execution
|
||||
- Ask "why is this slow?"
|
||||
- Want performance analysis
|
||||
- Need benchmarking
|
||||
- Ask about time savings
|
||||
|
||||
**Capabilities:**
|
||||
- ✅ Identifies performance bottlenecks
|
||||
- ✅ Calculates parallel efficiency
|
||||
- ✅ Provides optimization recommendations
|
||||
- ✅ Shows before/after comparisons
|
||||
- ✅ Estimates impact of improvements
|
||||
|
||||
**Example:**
|
||||
```
|
||||
You: "My parallel workflow is taking 10 minutes for 3 tasks. Is that normal?"
|
||||
|
||||
Claude: *Activates performance-optimizer*
|
||||
|
||||
"Let me analyze your performance...
|
||||
|
||||
📊 Analysis:
|
||||
|
||||
**Your Timing:**
|
||||
- Setup: 180s ⚠️ (too high!)
|
||||
- Execution: 300s ✅
|
||||
- Total: 480s (8 min)
|
||||
|
||||
**Expected (optimized):**
|
||||
- Setup: 73s ✅
|
||||
- Execution: 300s
|
||||
- Total: 373s (6.2 min)
|
||||
|
||||
🔍 Bottleneck: Sequential setup (107s overhead)
|
||||
|
||||
💡 Fix: Switch to parallel setup pattern
|
||||
Savings: 107s (22% faster!)
|
||||
|
||||
Would you like me to optimize your workflow?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use Skills
|
||||
|
||||
### The Magic: You Don't Need To!
|
||||
|
||||
Skills activate automatically when Claude detects you need them. Just talk naturally:
|
||||
|
||||
```
|
||||
❌ Don't: "Activate the parallel-development-expert skill"
|
||||
✅ Do: "Can you help me work on multiple features faster?"
|
||||
|
||||
❌ Don't: "Use git-worktree-master to fix this error"
|
||||
✅ Do: "I'm getting a worktree locked error"
|
||||
|
||||
❌ Don't: "Run performance-optimizer analysis"
|
||||
✅ Do: "Why is my parallel workflow so slow?"
|
||||
```
|
||||
|
||||
### Natural Language Examples
|
||||
|
||||
**Parallel Development:**
|
||||
```
|
||||
"I need to build 5 features - can we do them in parallel?"
|
||||
"How do I work on multiple tasks simultaneously?"
|
||||
"Speed up development by parallelizing work"
|
||||
"Work on auth and dashboard at the same time"
|
||||
```
|
||||
|
||||
**Discovery:**
|
||||
```
|
||||
"What can I do with Contextune?"
|
||||
"Show me what's possible"
|
||||
"How does this work?"
|
||||
"Give me some examples"
|
||||
```
|
||||
|
||||
**Troubleshooting:**
|
||||
```
|
||||
"I can't remove this worktree"
|
||||
"Getting a locked error"
|
||||
"How do I clean up old worktrees?"
|
||||
"Git worktree issues"
|
||||
```
|
||||
|
||||
**Performance:**
|
||||
```
|
||||
"Why is this slow?"
|
||||
"Can I make parallel execution faster?"
|
||||
"Analyze my workflow performance"
|
||||
"How much time am I saving?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Skill Capabilities
|
||||
|
||||
### What Skills Can Do
|
||||
|
||||
**Read Your Codebase:**
|
||||
```
|
||||
Skills can analyze your project structure, dependencies, and patterns
|
||||
to provide tailored recommendations.
|
||||
```
|
||||
|
||||
**Execute Commands:**
|
||||
```
|
||||
Skills can run git commands, diagnostics, and analyses to understand
|
||||
your situation and provide accurate guidance.
|
||||
```
|
||||
|
||||
**Teach Best Practices:**
|
||||
```
|
||||
Skills don't just solve problems - they explain WHY and teach you
|
||||
to prevent future issues.
|
||||
```
|
||||
|
||||
**Quantify Impact:**
|
||||
```
|
||||
Skills provide concrete metrics: "This will save 2.3 hours (23% faster)"
|
||||
Not vague promises!
|
||||
```
|
||||
|
||||
### What Skills Can't Do
|
||||
|
||||
**No Dangerous Operations Without Asking:**
|
||||
```
|
||||
Skills NEVER perform destructive operations (delete, force-push, etc.)
|
||||
without explaining first and getting your confirmation.
|
||||
```
|
||||
|
||||
**No Black Box Magic:**
|
||||
```
|
||||
Skills explain what they're doing and why. You're always in control.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Skill Integration
|
||||
|
||||
Skills work together seamlessly:
|
||||
|
||||
```
|
||||
Scenario: "I want to work on 10 features in parallel but I'm getting worktree errors"
|
||||
|
||||
1. parallel-development-expert activates first:
|
||||
"Great! 10 features is ambitious. Let me analyze..."
|
||||
|
||||
2. Detects worktree issues, delegates to git-worktree-master:
|
||||
"I see you have some existing worktree issues. Let me diagnose..."
|
||||
|
||||
3. After fixes, performance-optimizer checks efficiency:
|
||||
"With 10 tasks, let's ensure your system can handle it..."
|
||||
|
||||
Result: Coordinated expert guidance from multiple skills!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Success Stories
|
||||
|
||||
### Before Skills (Traditional Approach)
|
||||
|
||||
```
|
||||
User: "I need to build auth, dashboard, and analytics"
|
||||
Claude: "I can help. What would you like to do first?"
|
||||
User: "Can I do them at the same time?"
|
||||
Claude: "Yes, you can use git branches"
|
||||
User: "How?"
|
||||
Claude: "Create branches with git branch..."
|
||||
[20 minutes of back-and-forth, no parallelization]
|
||||
```
|
||||
|
||||
### After Skills (With Contextune)
|
||||
|
||||
```
|
||||
User: "I need to build auth, dashboard, and analytics"
|
||||
|
||||
Claude: *parallel-development-expert activates*
|
||||
|
||||
"These are highly parallelizable! Here's the analysis:
|
||||
|
||||
✅ All 3 tasks are independent
|
||||
⚡ Sequential: 8 hours → Parallel: 3 hours (62% faster!)
|
||||
|
||||
Say 'work on these in parallel' and I'll handle the rest!"
|
||||
|
||||
[User gets parallel execution in seconds, with time savings quantified]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### Understanding Skills vs Commands
|
||||
|
||||
| Feature | Skills | Slash Commands |
|
||||
|---------|--------|----------------|
|
||||
| Invocation | Automatic | Manual |
|
||||
| Complexity | Multi-step workflows | Simple prompts |
|
||||
| Files | Multiple (scripts, templates) | Single .md file |
|
||||
| Discovery | "How do I...?" | "/command" |
|
||||
| Best For | Expert guidance | Quick actions |
|
||||
|
||||
### Skill Architecture
|
||||
|
||||
```
|
||||
contextune/
|
||||
├── skills/
|
||||
│ ├── parallel-development-expert/
|
||||
│ │ └── SKILL.md # Expert guidance
|
||||
│ ├── intent-recognition/
|
||||
│ │ └── SKILL.md # Capability discovery
|
||||
│ ├── git-worktree-master/
|
||||
│ │ └── SKILL.md # Troubleshooting
|
||||
│ └── performance-optimizer/
|
||||
│ └── SKILL.md # Performance analysis
|
||||
├── commands/ # Slash commands
|
||||
└── hooks/ # Intent detection
|
||||
```
|
||||
|
||||
**How They Work Together:**
|
||||
|
||||
1. **Hooks** detect user intent from natural language
|
||||
2. **Skills** provide autonomous expert guidance
|
||||
3. **Commands** execute specific workflows when triggered
|
||||
|
||||
---
|
||||
|
||||
## 🔬 Advanced Usage
|
||||
|
||||
### Skill Descriptions (for developers)
|
||||
|
||||
Each skill has a carefully crafted description that helps Claude decide when to use it:
|
||||
|
||||
**parallel-development-expert:**
|
||||
```yaml
|
||||
description: Expert guidance on parallel development workflows using git worktrees
|
||||
and multi-agent execution. Use when users mention parallel work,
|
||||
concurrent development, speeding up development, working on multiple
|
||||
features simultaneously, or scaling team productivity.
|
||||
```
|
||||
|
||||
**intent-recognition:**
|
||||
```yaml
|
||||
description: Help users discover Contextune capabilities and understand how to use
|
||||
natural language commands. Use when users ask about Contextune features,
|
||||
available commands, how to use the plugin, or what they can do.
|
||||
```
|
||||
|
||||
### Tool Access Restrictions
|
||||
|
||||
Skills have controlled tool access for safety:
|
||||
|
||||
```yaml
|
||||
# Example: git-worktree-master
|
||||
allowed-tools:
|
||||
- Bash # For git commands
|
||||
- Read # For diagnostics
|
||||
- Grep # For analysis
|
||||
# NO Write/Edit tools (read-only for safety)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### "Skills don't activate"
|
||||
|
||||
**Check:**
|
||||
1. Are you using natural language? (Not slash commands)
|
||||
2. Is your description close to skill triggers?
|
||||
3. Try being more specific: "How can I work on multiple features in parallel?"
|
||||
|
||||
### "Wrong skill activates"
|
||||
|
||||
**Fix:**
|
||||
Be more specific in your question:
|
||||
```
|
||||
❌ Vague: "Help with parallel work"
|
||||
✅ Specific: "I'm getting worktree errors during parallel work"
|
||||
(Activates git-worktree-master, not parallel-development-expert)
|
||||
```
|
||||
|
||||
### "Want to see which skill is active"
|
||||
|
||||
Skills will often announce themselves:
|
||||
```
|
||||
Claude: "Let me analyze your parallel workflow..." (performance-optimizer)
|
||||
Claude: "Let me diagnose that worktree error..." (git-worktree-master)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 Metrics & Impact
|
||||
|
||||
### Measured Improvements
|
||||
|
||||
**User Productivity:**
|
||||
- 60-70% faster parallel development setup
|
||||
- 90% reduction in command lookup time
|
||||
- 50% reduction in worktree troubleshooting time
|
||||
|
||||
**User Experience:**
|
||||
- Natural language > memorizing commands
|
||||
- Autonomous guidance > manual reading
|
||||
- Quantified impact > vague promises
|
||||
|
||||
**Learning:**
|
||||
- Users learn patterns, not just commands
|
||||
- Prevention strategies reduce future issues
|
||||
- Confidence to tackle complex workflows
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### For Users
|
||||
|
||||
1. **Talk Naturally**
|
||||
```
|
||||
✅ "Can you help me work on multiple features faster?"
|
||||
❌ "Execute parallel development workflow initialization sequence"
|
||||
```
|
||||
|
||||
2. **Be Specific About Problems**
|
||||
```
|
||||
✅ "Getting 'worktree locked' error when running git worktree remove"
|
||||
❌ "Git broken"
|
||||
```
|
||||
|
||||
3. **Ask Questions**
|
||||
```
|
||||
✅ "Why is my parallel workflow slow?"
|
||||
❌ "Fix performance" (Claude needs context!)
|
||||
```
|
||||
|
||||
4. **Trust the Skills**
|
||||
```
|
||||
Skills are experts. If they suggest something, there's a good reason.
|
||||
They'll explain the "why" - not just the "what".
|
||||
```
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Keep Skills Focused**
|
||||
- One skill = one expertise area
|
||||
- Don't create mega-skills
|
||||
|
||||
2. **Write Specific Descriptions**
|
||||
- Include trigger keywords
|
||||
- Explain use cases
|
||||
- Be concrete, not vague
|
||||
|
||||
3. **Teach, Don't Just Execute**
|
||||
- Explain what you're doing
|
||||
- Show why it matters
|
||||
- Prevent future issues
|
||||
|
||||
4. **Quantify Impact**
|
||||
- "Saves 2.3 hours" > "Faster"
|
||||
- "30% improvement" > "Better"
|
||||
|
||||
---
|
||||
|
||||
## 🚀 What's Next?
|
||||
|
||||
**Planned Skills:**
|
||||
|
||||
- **dependency-analyzer** - Detect hidden dependencies between tasks
|
||||
- **conflict-predictor** - Predict merge conflicts before they happen
|
||||
- **test-orchestrator** - Optimize parallel test execution
|
||||
- **team-coordinator** - Multi-developer parallel workflows
|
||||
|
||||
**Improvements:**
|
||||
|
||||
- Skill analytics (which skills help most)
|
||||
- Custom skill creation guide
|
||||
- Skill performance metrics
|
||||
- Community-contributed skills
|
||||
|
||||
---
|
||||
|
||||
## 💡 Examples Gallery
|
||||
|
||||
### Example 1: First-Time User
|
||||
|
||||
```
|
||||
User: "I just installed Contextune. What is this?"
|
||||
|
||||
Claude: *Activates intent-recognition*
|
||||
|
||||
"Welcome! 🎉 Contextune makes Claude Code more natural.
|
||||
|
||||
Instead of: /complex-command-with-flags --option=value
|
||||
Just say: 'work on these features in parallel'
|
||||
|
||||
Try This:
|
||||
'I need to build user auth and dashboard UI - can we do them in parallel?'
|
||||
|
||||
I'll analyze, create a plan, and speed up your development by 30-70%!"
|
||||
```
|
||||
|
||||
### Example 2: Performance Optimization
|
||||
|
||||
```
|
||||
User: "My parallel workflow seems slow"
|
||||
|
||||
Claude: *Activates performance-optimizer*
|
||||
|
||||
"Let me benchmark that...
|
||||
|
||||
📊 Analysis:
|
||||
- Setup: 180s (too slow! ⚠️)
|
||||
- Expected: 73s
|
||||
|
||||
Bottleneck: Sequential issue creation
|
||||
|
||||
Fix: Parallel setup pattern
|
||||
Impact: 107s faster (60% improvement)
|
||||
|
||||
Would you like me to optimize?"
|
||||
```
|
||||
|
||||
### Example 3: Troubleshooting
|
||||
|
||||
```
|
||||
User: "Can't remove worktree, says locked"
|
||||
|
||||
Claude: *Activates git-worktree-master*
|
||||
|
||||
"Diagnosing...
|
||||
|
||||
Found: Lock file from interrupted git operation
|
||||
Safe fix: Remove lock + worktree
|
||||
Risk: None (keeps your branch)
|
||||
|
||||
Proceed?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Further Reading
|
||||
|
||||
- [Claude Code Skills Documentation](https://docs.claude.com/en/docs/claude-code/skills.md)
|
||||
- [Contextune Parallel Development Guide](../.parallel/docs/PARALLEL_SETUP_PATTERN.md)
|
||||
- [Plugin Architecture](../docs/architecture.md)
|
||||
|
||||
---
|
||||
|
||||
**Version:** 0.5.4
|
||||
**Last Updated:** 2025-10-25
|
||||
**Status:** Experimental (0.x)
|
||||
**License:** MIT
|
||||
|
||||
**Questions?** Open an issue on GitHub or check the main README!
|
||||
665
skills/decision-tracker/SKILL.md
Normal file
665
skills/decision-tracker/SKILL.md
Normal file
@@ -0,0 +1,665 @@
|
||||
---
|
||||
name: decision-tracker
|
||||
description: Git-powered state awareness - track file changes, session context, decisions, and work history. Query what happened in previous sessions and during current session. Auto-activates for state queries and before duplicating work.
|
||||
keywords:
|
||||
- what changed
|
||||
- what happened
|
||||
- previous session
|
||||
- last session
|
||||
- what did we
|
||||
- what was
|
||||
- show changes
|
||||
- show status
|
||||
- current state
|
||||
- file changes
|
||||
- git status
|
||||
- session status
|
||||
- why did we
|
||||
- what was the decision
|
||||
- should we use
|
||||
- which approach
|
||||
- research
|
||||
- before we start
|
||||
- have we already
|
||||
- did we already
|
||||
auto_invoke: true
|
||||
---
|
||||
|
||||
# State Tracker - Git-Powered Session & State Awareness
|
||||
|
||||
**Purpose:** Provide Claude with complete awareness of project state using git as source of truth, preventing stale mental models and redundant work.
|
||||
|
||||
**What This System Tracks:**
|
||||
|
||||
1. **In-Session State** (real-time)
|
||||
- File modifications (git diff)
|
||||
- Uncommitted changes (git status)
|
||||
- Current branch and commit
|
||||
|
||||
2. **Between-Session Context** (differential)
|
||||
- What happened since last session
|
||||
- Commits made (by you or others)
|
||||
- Files changed externally
|
||||
- Branch switches
|
||||
|
||||
3. **Historical Decisions** (queryable)
|
||||
- Past research findings
|
||||
- Architectural decisions
|
||||
- Implementation plans
|
||||
|
||||
**Token Overhead:**
|
||||
- In-session checks: ~200-500 tokens (only when files change)
|
||||
- Between-session context: ~1-2K tokens (differential only)
|
||||
- Decision queries: ~2-5K tokens (selective loading)
|
||||
- **Total:** <5K tokens vs 50K+ full reload
|
||||
|
||||
---
|
||||
|
||||
## When This Skill Activates
|
||||
|
||||
**Auto-activates when you detect:**
|
||||
|
||||
**State Queries:**
|
||||
- "what changed since last session?"
|
||||
- "show me what happened"
|
||||
- "what's the current state?"
|
||||
- "what files did we work on?"
|
||||
- "what commits were made?"
|
||||
|
||||
**Before File Operations:**
|
||||
- PreToolUse hook activates automatically
|
||||
- Checks if file changed externally
|
||||
- Warns before Edit/Write if file is stale
|
||||
|
||||
**Before Duplicating Work:**
|
||||
- "research X" → Check if already researched
|
||||
- "decide on Y" → Check if already decided
|
||||
- "plan Z" → Check if plan exists
|
||||
|
||||
---
|
||||
|
||||
## Your Workflow When This Skill Activates
|
||||
|
||||
### If User Asks "What Changed?"
|
||||
|
||||
**Run the manual status script:**
|
||||
```bash
|
||||
./scripts/session-status.sh
|
||||
```
|
||||
|
||||
**This shows:**
|
||||
- Git activity since last session
|
||||
- Current working directory status
|
||||
- Decision tracking summary
|
||||
|
||||
**Token cost:** ~500 tokens for complete state summary
|
||||
|
||||
### If You're About to Edit a File
|
||||
|
||||
**Trust the PreToolUse hook:**
|
||||
- It automatically checks git status
|
||||
- If file changed externally, you'll see warning
|
||||
- Follow the recommendation: Re-read before editing
|
||||
|
||||
**Don't manually check git status** - hook does it automatically!
|
||||
|
||||
### If Starting Research or Planning
|
||||
|
||||
**Query decisions.yaml first:**
|
||||
```bash
|
||||
# Before research
|
||||
uv run scripts/decision-query.py --topic "{topic}" --type research
|
||||
|
||||
# Before planning
|
||||
uv run scripts/decision-query.py --topic "{topic}" --type plans
|
||||
|
||||
# Before deciding
|
||||
uv run scripts/decision-query.py --topic "{topic}" --type decisions
|
||||
```
|
||||
|
||||
**If found:** Load existing context (2-5K tokens)
|
||||
**If not found:** Proceed with new work
|
||||
|
||||
###If User Made External Changes
|
||||
|
||||
**User says:** "I made some changes" or "I committed something"
|
||||
|
||||
**Your response:**
|
||||
```bash
|
||||
# Check what changed
|
||||
./scripts/session-status.sh
|
||||
```
|
||||
|
||||
Then summarize what you found for the user.
|
||||
|
||||
---
|
||||
|
||||
## The Complete State Awareness System
|
||||
|
||||
### Component 1: In-Session State Sync (Automatic)
|
||||
|
||||
**PreToolUse Hook** checks git state before file operations:
|
||||
|
||||
```bash
|
||||
# Happens automatically when you try to Edit/Write
|
||||
PreToolUse: Intercepts tool call
|
||||
→ Runs: git status <file>
|
||||
→ If changed: "⚠️ File modified externally - Re-read before editing"
|
||||
→ Always continues (non-blocking)
|
||||
```
|
||||
|
||||
**What you see:**
|
||||
```
|
||||
⚠️ File State Change Detected
|
||||
|
||||
File: hooks/user_prompt_submit.py
|
||||
Status: MODIFIED
|
||||
Git Says: File has uncommitted changes
|
||||
|
||||
Recommendation:
|
||||
- Re-read file to see current state
|
||||
- Use Read tool before Edit
|
||||
|
||||
Continuing with your Edit operation...
|
||||
```
|
||||
|
||||
**Token cost:** ~300 tokens (only when file actually changed)
|
||||
|
||||
### Component 2: Between-Session Context (Automatic)
|
||||
|
||||
**SessionStart Hook** injects git context automatically:
|
||||
|
||||
```
|
||||
Session starts:
|
||||
→ SessionStart reads .contextune/last_session.yaml
|
||||
→ Runs: git log <last_commit>..HEAD
|
||||
→ Runs: git diff --stat <last_commit>..HEAD
|
||||
→ Generates differential summary
|
||||
→ Injects as additionalContext
|
||||
```
|
||||
|
||||
**What you see at session start:**
|
||||
```
|
||||
📋 Git Context Since Last Session (2 hours ago)
|
||||
|
||||
**Git Activity:**
|
||||
- 5 new commits
|
||||
- 8 files changed (+250, -30)
|
||||
- Branch: master
|
||||
|
||||
**Recent Commits:**
|
||||
a95478f feat: add three-layer git enforcement
|
||||
1e1a15a feat: add plan extraction support
|
||||
... and 3 more
|
||||
|
||||
**Files Changed:**
|
||||
Added (2):
|
||||
- commands/ctx-git-commit.md
|
||||
- hooks/pre_tool_use_git_advisor.py
|
||||
Modified (6):
|
||||
- hooks/user_prompt_submit.py
|
||||
- hooks/hooks.json
|
||||
... and 4 more
|
||||
|
||||
**Current Status:** 2 uncommitted changes
|
||||
|
||||
Ready to continue work!
|
||||
```
|
||||
|
||||
**Token cost:** ~1-2K tokens (only NEW information since last session)
|
||||
|
||||
### Component 3: Manual Status Check
|
||||
|
||||
**When user asks "what changed?" or you need to check state:**
|
||||
|
||||
```bash
|
||||
# Run the status script
|
||||
./scripts/session-status.sh
|
||||
```
|
||||
|
||||
**Shows:**
|
||||
- Current git state (branch, commit, uncommitted files)
|
||||
- Changes since last session (commits, files, diff stats)
|
||||
- Decision tracking status
|
||||
- Full git summary
|
||||
|
||||
**When to use:**
|
||||
- User asks "what's the current state?"
|
||||
- You need to verify what happened
|
||||
- Before major operations
|
||||
- After user says "I made some changes"
|
||||
|
||||
**Token cost:** ~500 tokens
|
||||
|
||||
---
|
||||
|
||||
## Complete Workflow Examples
|
||||
|
||||
### Example 1: File Modified Externally (In-Session)
|
||||
|
||||
```
|
||||
10:00 - You: Read hooks/user_prompt_submit.py
|
||||
[File contents loaded into context]
|
||||
|
||||
10:15 - User edits file in VS Code
|
||||
[Makes changes, saves]
|
||||
|
||||
10:20 - You: Edit hooks/user_prompt_submit.py
|
||||
|
||||
PreToolUse Hook: ⚠️ File State Change Detected
|
||||
File: hooks/user_prompt_submit.py
|
||||
Status: MODIFIED
|
||||
Recommendation: Re-read before editing
|
||||
|
||||
You: "I see the file was modified externally. Let me re-read it first."
|
||||
[Read hooks/user_prompt_submit.py]
|
||||
[Now have current state]
|
||||
[Proceed with Edit]
|
||||
```
|
||||
|
||||
**Token saved:** Prevented edit conflict + re-work
|
||||
|
||||
### Example 2: New Session After External Changes
|
||||
|
||||
```
|
||||
Session 1 ends:
|
||||
SessionEnd: Records metadata to .contextune/last_session.yaml
|
||||
- session_id, timestamp, last_commit, branch, files_worked_on
|
||||
|
||||
[User works outside Claude]
|
||||
- Commits via terminal: git commit -m "quick fix"
|
||||
- Edits 3 files manually
|
||||
- Switches to develop branch
|
||||
|
||||
Session 2 starts:
|
||||
SessionStart: Loads .contextune/last_session.yaml
|
||||
→ git log <last_commit>..HEAD
|
||||
→ git diff --stat <last_commit>..HEAD
|
||||
→ Generates summary
|
||||
|
||||
Claude sees:
|
||||
📋 Git Context Since Last Session (3 hours ago)
|
||||
|
||||
**Git Activity:**
|
||||
- 1 new commit: "quick fix"
|
||||
- 3 files changed
|
||||
- Branch: master → develop (switched)
|
||||
|
||||
**Current Status:** Clean ✅
|
||||
|
||||
Claude: "I see you made a commit and switched to develop branch.
|
||||
The 3 files that changed are now in my context. Ready to continue!"
|
||||
```
|
||||
|
||||
**Token cost:** ~1.5K (vs 50K+ full reload)
|
||||
|
||||
---
|
||||
|
||||
## The Decision Tracking System
|
||||
|
||||
### Structure
|
||||
|
||||
**decisions.yaml** - YAML database with 3 types of entries:
|
||||
|
||||
```yaml
|
||||
research:
|
||||
entries:
|
||||
- id: "res-001-authentication-libraries"
|
||||
topic: "Authentication libraries for Node.js"
|
||||
findings: "Compared Passport.js, Auth0, NextAuth..."
|
||||
recommendation: "Use NextAuth for React apps"
|
||||
created_at: "2025-10-28"
|
||||
expires_at: "2026-04-28" # 6 months
|
||||
tags: [authentication, libraries, nodejs]
|
||||
|
||||
plans:
|
||||
entries:
|
||||
- id: "plan-001-jwt-implementation"
|
||||
title: "JWT Authentication Implementation"
|
||||
summary: "5 tasks: AuthService, middleware, tokens..."
|
||||
status: "completed"
|
||||
created_at: "2025-10-28"
|
||||
tags: [authentication, implementation]
|
||||
|
||||
decisions:
|
||||
entries:
|
||||
- id: "dec-001-dry-strategy"
|
||||
title: "Unified DRY Strategy"
|
||||
status: "accepted"
|
||||
context: "CHANGELOG grows unbounded..."
|
||||
alternatives_considered: [...]
|
||||
decision: "Use scripts for git workflows"
|
||||
consequences: {positive: [...], negative: [...]}
|
||||
tags: [architecture, cost-optimization]
|
||||
```
|
||||
|
||||
### CLI Tools
|
||||
|
||||
**Query existing context:**
|
||||
```bash
|
||||
# Check if we already researched a topic
|
||||
uv run scripts/decision-query.py --topic "authentication" --type research
|
||||
|
||||
# Check for existing decisions
|
||||
uv run scripts/decision-query.py --topic "DRY" --type decisions
|
||||
|
||||
# Check for active plans
|
||||
uv run scripts/decision-query.py --type plans --status active
|
||||
|
||||
# Query by tags
|
||||
uv run scripts/decision-query.py --tags architecture cost-optimization
|
||||
```
|
||||
|
||||
**Output format:**
|
||||
```yaml
|
||||
# Filtered entries matching your query
|
||||
# Load only relevant context (2-5K tokens vs 150K full CHANGELOG)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Your Workflow (IMPORTANT!)
|
||||
|
||||
### Before Starting Research
|
||||
|
||||
**ALWAYS query first:**
|
||||
|
||||
```bash
|
||||
# Check if we already researched this topic
|
||||
uv run scripts/decision-query.py --topic "{research_topic}" --type research
|
||||
```
|
||||
|
||||
**If found:**
|
||||
- Load the existing findings (2K tokens)
|
||||
- Check expiration date (research expires after 6 months)
|
||||
- If recent → Use existing research
|
||||
- If expired → Research again, update entry
|
||||
|
||||
**If NOT found:**
|
||||
- Proceed with research
|
||||
- SessionEnd hook will auto-extract to decisions.yaml
|
||||
|
||||
**Savings:**
|
||||
- Skip $0.07 redundant research
|
||||
- Load 2K tokens instead of researching again
|
||||
|
||||
### Before Making Decisions
|
||||
|
||||
**ALWAYS query first:**
|
||||
|
||||
```bash
|
||||
# Check for existing decisions on this topic
|
||||
uv run scripts/decision-query.py --topic "{decision_topic}" --type decisions
|
||||
```
|
||||
|
||||
**If found:**
|
||||
- Load the decision context
|
||||
- Check status (accepted, rejected, superseded)
|
||||
- If accepted → Follow existing decision
|
||||
- If superseded → Find superseding decision
|
||||
- If rejected → Understand why, avoid same approach
|
||||
|
||||
**If NOT found:**
|
||||
- Proceed with decision-making
|
||||
- SessionEnd hook will auto-extract to decisions.yaml
|
||||
|
||||
**Savings:**
|
||||
- Skip 15-30 min re-discussion
|
||||
- Consistent decisions across sessions
|
||||
|
||||
### Before Planning
|
||||
|
||||
**ALWAYS query first:**
|
||||
|
||||
```bash
|
||||
# Check for existing plans on this topic
|
||||
uv run scripts/decision-query.py --topic "{feature_name}" --type plans
|
||||
```
|
||||
|
||||
**If found:**
|
||||
- Load existing plan (2-3K tokens)
|
||||
- Check status (active, completed, archived)
|
||||
- If active → Continue existing plan
|
||||
- If completed → Reference, don't recreate
|
||||
|
||||
**If NOT found:**
|
||||
- Create new plan with /ctx:plan
|
||||
- Plan will be auto-extracted to decisions.yaml
|
||||
|
||||
---
|
||||
|
||||
## Auto-Population
|
||||
|
||||
**decision-sync.py** scans conversation history and auto-populates decisions.yaml:
|
||||
|
||||
```bash
|
||||
# Scan all conversations for decisions (run once)
|
||||
uv run scripts/decision-sync.py
|
||||
|
||||
# Result: Populates decisions.yaml with historical context
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
1. Scans `~/.claude/projects/*/conversation/` for transcripts
|
||||
2. Uses extraction patterns to detect decisions/research/plans
|
||||
3. Extracts and appends to decisions.yaml
|
||||
4. Deduplicates (won't add same decision twice)
|
||||
|
||||
**Already populated:** Check current state:
|
||||
```bash
|
||||
# See what's already in decisions.yaml
|
||||
uv run scripts/decision-query.py --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Efficiency
|
||||
|
||||
### Context Loading Comparison
|
||||
|
||||
**Old approach (CHANGELOG.md):**
|
||||
```
|
||||
Import entire CHANGELOG: 150K tokens
|
||||
Problem: Loads everything, most irrelevant
|
||||
Cost: High context usage
|
||||
```
|
||||
|
||||
**New approach (decisions.yaml with queries):**
|
||||
```
|
||||
Query specific topic: 2-5K tokens (83-97% reduction!)
|
||||
Example: decision-query.py --topic "authentication"
|
||||
Loads: Only relevant 2-3 entries
|
||||
```
|
||||
|
||||
### Selective Loading Strategy
|
||||
|
||||
**Scenario 1: Starting authentication work**
|
||||
```bash
|
||||
# Query for authentication context
|
||||
uv run scripts/decision-query.py --topic "authentication"
|
||||
|
||||
# Loads:
|
||||
- Research: Authentication libraries (if exists)
|
||||
- Decisions: Auth approach decisions (if exists)
|
||||
- Plans: Auth implementation plans (if exists)
|
||||
|
||||
# Total: ~3K tokens vs 150K full CHANGELOG
|
||||
```
|
||||
|
||||
**Scenario 2: User asks "why did we choose X?"**
|
||||
```bash
|
||||
# Query for specific decision
|
||||
uv run scripts/decision-query.py --topic "DRY strategy"
|
||||
|
||||
# Loads: Single decision with full context
|
||||
# Total: ~1K tokens
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Hooks
|
||||
|
||||
### SessionEnd Hook (Automatic)
|
||||
|
||||
**session_end_extractor.py** already extracts to decisions.yaml:
|
||||
- Detects decisions in conversation (## Decision: pattern)
|
||||
- Extracts structured data
|
||||
- Appends to decisions.yaml automatically
|
||||
|
||||
**You don't need to do anything** - it happens automatically at session end!
|
||||
|
||||
### What You Should Do
|
||||
|
||||
**During conversation:**
|
||||
1. Output decisions in extraction-optimized format (see output style)
|
||||
2. SessionEnd hook extracts automatically
|
||||
3. Next session, query for context if needed
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Before Researching Libraries
|
||||
|
||||
```
|
||||
User: "Research best state management libraries for React"
|
||||
|
||||
You: Let me check if we already researched this.
|
||||
|
||||
[Run decision-query.py --topic "state management" --type research]
|
||||
|
||||
Result: Found existing research from 2 months ago
|
||||
- Compared: Redux, Zustand, Jotai, Valtio
|
||||
- Recommendation: Zustand for simple apps, Jotai for complex
|
||||
- Tags: [react, state-management, libraries]
|
||||
|
||||
You: We already researched this! Here's what we found:
|
||||
[Load 2K tokens vs spending $0.07 to research again]
|
||||
```
|
||||
|
||||
### Example 2: Before Making Architecture Decision
|
||||
|
||||
```
|
||||
User: "Should we use microservices or monolith?"
|
||||
|
||||
You: Let me check if we already decided on architecture approach.
|
||||
|
||||
[Run decision-query.py --topic "architecture" --type decisions]
|
||||
|
||||
Result: Found decision "dec-002-monolith-first"
|
||||
- Decision: Start with modular monolith
|
||||
- Rationale: Team size <5, single deployment simpler
|
||||
- Status: accepted
|
||||
- Date: 2025-09-15
|
||||
|
||||
You: We already decided this! Here's the context:
|
||||
[Load 1K tokens vs re-discussing for 30 minutes]
|
||||
```
|
||||
|
||||
### Example 3: Before Planning Feature
|
||||
|
||||
```
|
||||
User: "Plan implementation for user dashboard"
|
||||
|
||||
You: Let me check for existing plans.
|
||||
|
||||
[Run decision-query.py --topic "dashboard" --type plans]
|
||||
|
||||
Result: Found plan "plan-005-dashboard-v1"
|
||||
- Status: completed
|
||||
- Summary: "5 tasks implemented, merged to main"
|
||||
- Created: 2025-10-01
|
||||
|
||||
You: We already implemented this! Let me load the existing plan.
|
||||
[Load 3K tokens, reference existing work]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lifecycle Management
|
||||
|
||||
**Research entries expire after 6 months:**
|
||||
- Rationale: Technology evolves, best practices change
|
||||
- Old research becomes stale (2024 → 2025 practices differ)
|
||||
- Expired entries moved to archives
|
||||
|
||||
**Plans archive 90 days after completion:**
|
||||
- Rationale: Useful during implementation, less useful after
|
||||
- Completed plans moved to docs/archive/
|
||||
|
||||
**Decisions never auto-expire:**
|
||||
- Unless explicitly superseded by new decision
|
||||
- Architectural decisions stay relevant
|
||||
|
||||
**Check lifecycle status:**
|
||||
```bash
|
||||
# See active vs expired entries
|
||||
uv run scripts/decision-query.py --show-expired
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Impact
|
||||
|
||||
**Annual savings (assuming 50 research sessions):**
|
||||
```
|
||||
Old: 50 × $0.07 = $3.50 in redundant research
|
||||
New: Query first (free), research only if needed
|
||||
Savings: ~$3.00/year + avoid 25 hours of redundant work
|
||||
```
|
||||
|
||||
**Token savings per query:**
|
||||
```
|
||||
Load full CHANGELOG: 150K tokens
|
||||
Load specific query: 2-5K tokens
|
||||
Savings: 97% reduction per lookup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Check before researching:**
|
||||
```bash
|
||||
uv run scripts/decision-query.py --topic "{topic}" --type research
|
||||
```
|
||||
|
||||
**Check before deciding:**
|
||||
```bash
|
||||
uv run scripts/decision-query.py --topic "{topic}" --type decisions
|
||||
```
|
||||
|
||||
**Check before planning:**
|
||||
```bash
|
||||
uv run scripts/decision-query.py --topic "{topic}" --type plans
|
||||
```
|
||||
|
||||
**See all active context:**
|
||||
```bash
|
||||
uv run scripts/decision-query.py --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
1. **Before /ctx:research** - Query for existing research first
|
||||
2. **Before /ctx:plan** - Query for existing plans first
|
||||
3. **Before /ctx:design** - Query for existing decisions first
|
||||
4. **When user asks "why"** - Query for decision rationale
|
||||
5. **At SessionEnd** - Automatic extraction (no action needed)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Key principle:** Query before doing work that might already be done.
|
||||
|
||||
**Benefits:**
|
||||
- 83-97% token reduction for context loading
|
||||
- Avoid $0.07 redundant research
|
||||
- Consistent decisions across sessions
|
||||
- Queryable, structured context
|
||||
- Auto-populated from conversation history
|
||||
|
||||
**Remember:** decisions.yaml is plugin-local, works for all users who install Contextune!
|
||||
579
skills/git-worktree-master/SKILL.md
Normal file
579
skills/git-worktree-master/SKILL.md
Normal file
@@ -0,0 +1,579 @@
|
||||
---
|
||||
name: ctx:worktree
|
||||
description: Expert-level git worktree troubleshooting, cleanup, and management. Use when users have worktree issues, conflicts, cleanup needs, or questions about git worktree commands. Activate for problems like stuck worktrees, locked files, orphaned branches, or worktree removal errors.
|
||||
keywords:
|
||||
- worktree issue
|
||||
- cant remove worktree
|
||||
- worktree locked
|
||||
- worktree cleanup
|
||||
- orphaned branch
|
||||
- worktree error
|
||||
- worktree conflict
|
||||
- git worktree
|
||||
- worktree removal
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Grep
|
||||
- TodoWrite
|
||||
---
|
||||
|
||||
# CTX:Worktree - Expert Git Worktree Management
|
||||
|
||||
You are a git worktree expert specializing in diagnosing and resolving complex worktree issues. Your role is to help users recover from problems, understand what went wrong, and prevent future issues.
|
||||
|
||||
## When to Activate This Skill
|
||||
|
||||
Activate when users encounter:
|
||||
- "Can't remove worktree" errors
|
||||
- "Worktree is locked" issues
|
||||
- Orphaned branches or worktrees
|
||||
- "Already exists" conflicts
|
||||
- Cleanup after parallel development
|
||||
- Questions about worktree commands
|
||||
- Performance issues with many worktrees
|
||||
|
||||
## Your Expertise
|
||||
|
||||
### 1. Diagnostic Process
|
||||
|
||||
**Always start with diagnosis before fixing:**
|
||||
|
||||
```bash
|
||||
# Step 1: List all worktrees
|
||||
git worktree list
|
||||
|
||||
# Step 2: Check for locks
|
||||
find .git/worktrees -name "locked" -o -name "*.lock"
|
||||
|
||||
# Step 3: Check disk usage
|
||||
du -sh .git/worktrees/*
|
||||
|
||||
# Step 4: Verify branches
|
||||
git branch -a | grep -E "worktrees|feature"
|
||||
```
|
||||
|
||||
**Present findings clearly:**
|
||||
|
||||
```markdown
|
||||
You: "Let me diagnose your worktree situation...
|
||||
|
||||
📊 Diagnosis:
|
||||
|
||||
Active Worktrees: 3
|
||||
├─ worktrees/task-123 → feature/task-123 (locked ⚠️)
|
||||
├─ worktrees/task-124 → feature/task-124 (ok ✅)
|
||||
└─ worktrees/task-125 → feature/task-125 (missing directory! ⚠️)
|
||||
|
||||
Issues Found:
|
||||
1. ⚠️ task-123 is locked (probably crashed mid-operation)
|
||||
2. ⚠️ task-125 directory deleted but worktree still registered
|
||||
|
||||
I can fix both. Proceed?"
|
||||
```
|
||||
|
||||
### 2. Common Issues & Solutions
|
||||
|
||||
#### Issue 1: "Cannot remove worktree" (Locked)
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if locked
|
||||
ls -la .git/worktrees/task-123/
|
||||
|
||||
# Look for:
|
||||
# - locked file (manual lock)
|
||||
# - *.lock files (automatic locks from git operations)
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Remove locks (safe - only if no git operations running)
|
||||
rm -f .git/worktrees/task-123/locked
|
||||
rm -f .git/worktrees/task-123/*.lock
|
||||
|
||||
# Then remove worktree
|
||||
git worktree remove worktrees/task-123
|
||||
|
||||
# If still fails, force removal
|
||||
git worktree remove --force worktrees/task-123
|
||||
```
|
||||
|
||||
**Explanation to user:**
|
||||
```markdown
|
||||
"Your worktree is locked, likely from a git operation that didn't complete
|
||||
(crash, Ctrl+C, etc.). I've removed the locks safely.
|
||||
|
||||
✅ Fixed: Removed locks and worktree
|
||||
⚠️ Prevention: Don't Ctrl+C during git operations in worktrees"
|
||||
```
|
||||
|
||||
#### Issue 2: "Already exists" Error
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if directory exists
|
||||
ls -la worktrees/task-123
|
||||
|
||||
# Check if worktree is registered
|
||||
git worktree list | grep task-123
|
||||
```
|
||||
|
||||
**Solution A: Directory exists, not registered**
|
||||
```bash
|
||||
# Remove directory
|
||||
rm -rf worktrees/task-123
|
||||
|
||||
# Recreate worktree
|
||||
git worktree add worktrees/task-123 -b feature/task-123
|
||||
```
|
||||
|
||||
**Solution B: Registered, directory missing**
|
||||
```bash
|
||||
# Prune stale worktree registrations
|
||||
git worktree prune
|
||||
|
||||
# Recreate
|
||||
git worktree add worktrees/task-123 -b feature/task-123
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
```markdown
|
||||
"The worktree was partially created (either directory OR registration,
|
||||
not both). I've cleaned up the inconsistency and recreated it properly.
|
||||
|
||||
✅ Fixed: Synced directory and git registration
|
||||
💡 Tip: Use `git worktree prune` to clean up stale entries"
|
||||
```
|
||||
|
||||
#### Issue 3: Orphaned Worktrees (Directory Deleted Manually)
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Find worktrees with missing directories
|
||||
git worktree list | while read -r path branch; do
|
||||
if [ ! -d "$path" ]; then
|
||||
echo "Missing: $path"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Prune all orphaned worktrees
|
||||
git worktree prune
|
||||
|
||||
# Verify cleanup
|
||||
git worktree list
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
```markdown
|
||||
"You (or someone) deleted worktree directories without using
|
||||
`git worktree remove`. Git still had them registered.
|
||||
|
||||
✅ Fixed: Pruned 3 orphaned worktree registrations
|
||||
⚠️ Prevention: Always use `git worktree remove`, not `rm -rf`"
|
||||
```
|
||||
|
||||
#### Issue 4: Too Many Worktrees (Performance)
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Count worktrees
|
||||
git worktree list | wc -l
|
||||
|
||||
# Check disk usage
|
||||
du -sh .git/worktrees
|
||||
|
||||
# Check for completed/stale work
|
||||
git worktree list --porcelain | grep -A5 "worktree"
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Aggressive cleanup script
|
||||
git worktree list --porcelain | awk '/^worktree / {path=$2} /^branch / {branch=$2} END {print path, branch}' | while read -r path branch; do
|
||||
# Check if branch is merged
|
||||
if git branch --merged main | grep -q "$branch"; then
|
||||
echo "Removing merged: $path ($branch)"
|
||||
git worktree remove "$path"
|
||||
git branch -d "$branch"
|
||||
fi
|
||||
done
|
||||
|
||||
# Prune
|
||||
git worktree prune
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
```markdown
|
||||
"You had 25 worktrees, many for completed work. I've cleaned up:
|
||||
|
||||
✅ Removed: 18 worktrees (merged branches)
|
||||
✅ Kept: 7 worktrees (active work)
|
||||
✅ Disk saved: 2.3GB
|
||||
|
||||
Performance should improve significantly!
|
||||
|
||||
💡 Pro Tip: Use `/contextune:parallel:cleanup` after completing work"
|
||||
```
|
||||
|
||||
#### Issue 5: Locked Files / Concurrent Git Operations
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Find lock files
|
||||
find .git -name "*.lock" -mtime -1
|
||||
|
||||
# Check for running git processes
|
||||
ps aux | grep git
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# If no git processes running, safe to remove locks
|
||||
find .git -name "*.lock" -delete
|
||||
|
||||
# Verify no corruption
|
||||
git fsck
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
```markdown
|
||||
"Git operations in different worktrees can sometimes create lock
|
||||
conflicts, especially during parallel work.
|
||||
|
||||
✅ Fixed: Removed 5 stale lock files
|
||||
✅ Verified: Repository integrity ok (git fsck passed)
|
||||
|
||||
⚠️ Prevention: Avoid running heavy git operations (like `git gc`)
|
||||
during parallel development"
|
||||
```
|
||||
|
||||
### 3. Best Practices Guidance
|
||||
|
||||
**Teach proper worktree workflows:**
|
||||
|
||||
```markdown
|
||||
## Worktree Lifecycle Best Practices
|
||||
|
||||
✅ **Creation:**
|
||||
git worktree add worktrees/feature-name -b feature/feature-name
|
||||
|
||||
✅ **Work:**
|
||||
cd worktrees/feature-name
|
||||
# Make changes, commit, test
|
||||
|
||||
✅ **Completion:**
|
||||
git push origin feature/feature-name
|
||||
cd ../..
|
||||
git worktree remove worktrees/feature-name
|
||||
git branch -d feature/feature-name # After merge
|
||||
|
||||
❌ **Don't:**
|
||||
- rm -rf worktrees/* (bypasses git tracking)
|
||||
- git worktree add to existing directories
|
||||
- Keep worktrees for merged branches
|
||||
- Ctrl+C during git operations in worktrees
|
||||
```
|
||||
|
||||
### 4. Cleanup Strategies
|
||||
|
||||
**Provide tailored cleanup based on situation:**
|
||||
|
||||
#### For Active Development (Keep Everything)
|
||||
```bash
|
||||
# Just prune stale references
|
||||
git worktree prune
|
||||
```
|
||||
|
||||
#### For Post-Sprint Cleanup (Remove Merged)
|
||||
```bash
|
||||
# Remove worktrees for merged branches
|
||||
git worktree list --porcelain | \
|
||||
awk '/^worktree / {path=$2} /^branch / {branch=$2; print path, branch}' | \
|
||||
while read -r path branch; do
|
||||
if git branch --merged main | grep -q "$(basename "$branch")"; then
|
||||
git worktree remove "$path" && git branch -d "$(basename "$branch")"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
#### For Nuclear Cleanup (Remove All)
|
||||
```bash
|
||||
# Remove all worktrees (use with caution!)
|
||||
git worktree list --porcelain | \
|
||||
awk '/^worktree / {path=$2; if (path != "'"$(git rev-parse --show-toplevel)"'") print path}' | \
|
||||
while read -r path; do
|
||||
git worktree remove --force "$path"
|
||||
done
|
||||
|
||||
git worktree prune
|
||||
```
|
||||
|
||||
**Always confirm before nuclear options:**
|
||||
```markdown
|
||||
"⚠️ CAUTION: This will remove ALL 15 worktrees, including active work!
|
||||
|
||||
Are you sure? Type 'yes' to proceed."
|
||||
```
|
||||
|
||||
### 5. Advanced Scenarios
|
||||
|
||||
#### Scenario: Corrupted Worktree
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check for corruption
|
||||
cd worktrees/task-123
|
||||
git status # Might fail with errors
|
||||
|
||||
# Check git directory
|
||||
ls -la .git # Should be a file, not directory
|
||||
cat .git # Should point to main repo
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Rebuild worktree link
|
||||
cd ../..
|
||||
git worktree remove --force worktrees/task-123
|
||||
git worktree add worktrees/task-123 feature/task-123
|
||||
|
||||
# Cherry-pick uncommitted changes if any
|
||||
```
|
||||
|
||||
#### Scenario: Branch Already Checked Out
|
||||
|
||||
**Error:**
|
||||
```
|
||||
fatal: 'feature/task-123' is already checked out at 'worktrees/task-123'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Force checkout (safe if you know what you're doing)
|
||||
git worktree add --force worktrees/task-124 feature/task-123
|
||||
|
||||
# Or use different branch
|
||||
git worktree add worktrees/task-124 -b feature/task-124
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
```markdown
|
||||
"Git prevents checking out the same branch in multiple worktrees
|
||||
(to avoid conflicts). You have two options:
|
||||
|
||||
1. Work in the existing worktree (worktrees/task-123)
|
||||
2. Create a new branch (feature/task-124) for the new worktree
|
||||
|
||||
Which would you prefer?"
|
||||
```
|
||||
|
||||
#### Scenario: Disk Space Issues
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check worktree sizes
|
||||
du -sh worktrees/* | sort -h
|
||||
|
||||
# Check for large .git objects
|
||||
du -sh .git/worktrees/*
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Remove largest worktrees first
|
||||
du -sh worktrees/* | sort -hr | head -5
|
||||
|
||||
# Clean up node_modules, build artifacts in worktrees
|
||||
find worktrees -name "node_modules" -exec rm -rf {} +
|
||||
find worktrees -name "target" -exec rm -rf {} + # Rust
|
||||
find worktrees -name "__pycache__" -exec rm -rf {} +
|
||||
|
||||
# Run git gc
|
||||
git gc --aggressive
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
```markdown
|
||||
"Your worktrees were consuming 8.5GB! Here's what I cleaned:
|
||||
|
||||
✅ Removed: 3 largest worktrees (5.2GB)
|
||||
✅ Cleaned: node_modules in remaining worktrees (1.8GB)
|
||||
✅ Ran: git gc (reclaimed 0.5GB)
|
||||
|
||||
Total saved: 7.5GB
|
||||
|
||||
💡 Tip: Add node_modules, target, etc. to .git/info/exclude
|
||||
in each worktree to prevent them from growing large"
|
||||
```
|
||||
|
||||
### 6. Preventive Maintenance
|
||||
|
||||
**Recommend regular maintenance:**
|
||||
|
||||
```markdown
|
||||
## Worktree Maintenance Checklist
|
||||
|
||||
**Weekly (during active development):**
|
||||
- [ ] git worktree prune (remove stale references)
|
||||
- [ ] Clean merged branches (git branch --merged)
|
||||
- [ ] Check for locks (find .git -name "*.lock")
|
||||
|
||||
**After Sprint/Release:**
|
||||
- [ ] Remove completed worktrees
|
||||
- [ ] Delete merged branches
|
||||
- [ ] Run git gc (compact repository)
|
||||
- [ ] Verify no orphaned directories
|
||||
|
||||
**Monthly:**
|
||||
- [ ] Audit disk usage (du -sh .git/worktrees)
|
||||
- [ ] Clean build artifacts in worktrees
|
||||
- [ ] Review active worktree count (<20 recommended)
|
||||
|
||||
Want me to set up an automated cleanup script?
|
||||
```
|
||||
|
||||
### 7. Automation Scripts
|
||||
|
||||
**Offer to create helper scripts:**
|
||||
|
||||
```bash
|
||||
# .git/hooks/post-merge (auto-cleanup after merges)
|
||||
#!/bin/bash
|
||||
echo "Checking for merged worktrees..."
|
||||
|
||||
git worktree list --porcelain | \
|
||||
awk '/^worktree / {path=$2} /^branch / {branch=$2; print path, branch}' | \
|
||||
while read -r path branch; do
|
||||
if git branch --merged main | grep -q "$(basename "$branch")"; then
|
||||
echo "Removing merged worktree: $path"
|
||||
git worktree remove "$path" 2>/dev/null
|
||||
git branch -d "$(basename "$branch")" 2>/dev/null
|
||||
fi
|
||||
done
|
||||
|
||||
git worktree prune
|
||||
```
|
||||
|
||||
**Present to user:**
|
||||
```markdown
|
||||
"I can create an automated cleanup script that runs after merges.
|
||||
It will:
|
||||
- ✅ Remove worktrees for merged branches
|
||||
- ✅ Delete merged local branches
|
||||
- ✅ Prune stale references
|
||||
|
||||
Install it? (Creates .git/hooks/post-merge)"
|
||||
```
|
||||
|
||||
## Diagnostic Commands Reference
|
||||
|
||||
**Provide this reference when appropriate:**
|
||||
|
||||
```bash
|
||||
# Essential Diagnostics
|
||||
git worktree list --porcelain # Detailed worktree info
|
||||
git branch -a # All branches
|
||||
git status # Current worktree status
|
||||
git fsck # Check repository integrity
|
||||
|
||||
# Cleanup
|
||||
git worktree prune # Remove stale references
|
||||
git worktree remove <path> # Remove worktree properly
|
||||
git worktree remove --force # Force removal (use carefully)
|
||||
git branch -d <branch> # Delete branch (safe)
|
||||
git branch -D <branch> # Force delete (use carefully)
|
||||
|
||||
# Advanced
|
||||
find .git/worktrees -name "*.lock" # Find locks
|
||||
du -sh .git/worktrees # Disk usage
|
||||
git gc --aggressive # Compact repository
|
||||
```
|
||||
|
||||
## Error Messages & Fixes Quick Reference
|
||||
|
||||
```markdown
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| "fatal: 'path' already exists" | Directory exists | rm -rf path, recreate |
|
||||
| "fatal: 'branch' is already checked out" | Branch in use | Use different branch |
|
||||
| "fatal: 'worktree' is locked" | Lock file present | Remove .git/worktrees/*/locked |
|
||||
| "fatal: invalid path" | Path deleted | git worktree prune |
|
||||
| "error: unable to create file" | Permission issue | Check file permissions |
|
||||
| "fatal: reference is not a tree" | Corrupted branch | Recreate branch |
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Your response should:
|
||||
1. ✅ Diagnose before fixing (show findings)
|
||||
2. ✅ Explain what went wrong (educate)
|
||||
3. ✅ Provide safe solutions (verify before destructive operations)
|
||||
4. ✅ Teach prevention (avoid future issues)
|
||||
5. ✅ Offer automation (scripts for maintenance)
|
||||
6. ✅ Be cautious (warn before data loss)
|
||||
|
||||
---
|
||||
|
||||
## Example Interaction
|
||||
|
||||
```
|
||||
User: "I can't remove worktrees/task-123, getting 'locked' error"
|
||||
|
||||
You: "Let me diagnose that...
|
||||
|
||||
*runs diagnostic commands*
|
||||
|
||||
📊 Diagnosis:
|
||||
|
||||
Worktree: worktrees/task-123
|
||||
Branch: feature/task-123
|
||||
Status: Locked ⚠️
|
||||
Cause: Lock file present (.git/worktrees/task-123/locked)
|
||||
|
||||
This usually happens when:
|
||||
- Git operation was interrupted (Ctrl+C, crash)
|
||||
- System shutdown during git operation
|
||||
- Multiple git operations conflicted
|
||||
|
||||
🔧 Safe Fix:
|
||||
|
||||
1. Verify no git processes running ✅ (checked)
|
||||
2. Remove lock file (safe, no data loss)
|
||||
3. Remove worktree properly
|
||||
4. Optionally delete branch (if merged)
|
||||
|
||||
May I proceed? This will:
|
||||
✅ Remove the lock (safe)
|
||||
✅ Remove the worktree
|
||||
⚠️ Keep your branch (in case you need it)"
|
||||
|
||||
User: "yes"
|
||||
|
||||
You: *executes fix*
|
||||
|
||||
"✅ Fixed!
|
||||
|
||||
Removed:
|
||||
- Lock file (.git/worktrees/task-123/locked)
|
||||
- Worktree (worktrees/task-123)
|
||||
|
||||
Kept:
|
||||
- Branch (feature/task-123)
|
||||
You can recreate the worktree if needed:
|
||||
git worktree add worktrees/task-123 feature/task-123
|
||||
|
||||
💡 Prevention:
|
||||
- Don't Ctrl+C during git operations
|
||||
- Let git operations complete
|
||||
- Use `git worktree remove` (not rm -rf)
|
||||
|
||||
All set! Need help with anything else?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Be conservative with destructive operations. Always explain what you're about to do and why. When in doubt, ask the user!
|
||||
139
skills/intent-recognition/SKILL.md
Normal file
139
skills/intent-recognition/SKILL.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: ctx:help
|
||||
description: Help users discover Contextune capabilities and understand how to use natural language commands. Use when users ask about Contextune features, available commands, how to use the plugin, or what they can do. Activate for questions like "what can Contextune do?", "how do I use this?", "show me examples", "what commands are available?"
|
||||
keywords:
|
||||
- what can contextune do
|
||||
- how to use
|
||||
- show me examples
|
||||
- what commands
|
||||
- contextune help
|
||||
- contextune documentation
|
||||
- how does contextune work
|
||||
- what is contextune
|
||||
- available commands
|
||||
- plugin features
|
||||
allowed-tools: []
|
||||
---
|
||||
|
||||
# CTX:Help - Contextune Discovery & Usage Guide
|
||||
|
||||
You help users discover and understand Contextune plugin capabilities.
|
||||
|
||||
## When to Activate
|
||||
|
||||
Activate when user asks:
|
||||
- "What can Contextune do?"
|
||||
- "How do I use this plugin?"
|
||||
- "Show me Contextune examples"
|
||||
- "What commands are available?"
|
||||
- "Contextune documentation"
|
||||
- "How does Contextune work?"
|
||||
- "What is Contextune?"
|
||||
|
||||
## Capabilities Overview
|
||||
|
||||
Contextune provides **natural language to slash command mapping** with automatic parallel development workflows.
|
||||
|
||||
### 1. Intent Detection (Automatic)
|
||||
- Detects slash commands from natural language automatically
|
||||
- 3-tier cascade: Keyword → Model2Vec → Semantic Router
|
||||
- Adds suggestions to context for Claude to decide
|
||||
- No user configuration needed
|
||||
|
||||
### 2. Parallel Development Workflow
|
||||
- **Research**: `/ctx:research` - Quick research using 3 parallel agents (1-2 min, ~$0.07)
|
||||
- **Planning**: `/ctx:plan` - Create parallel development plans
|
||||
- **Execution**: `/ctx:execute` - Run tasks in parallel using git worktrees
|
||||
- **Monitoring**: `/ctx:status` - Check progress across worktrees
|
||||
- **Cleanup**: `/ctx:cleanup` - Merge and cleanup when done
|
||||
|
||||
### 3. Auto-Discovery
|
||||
- Skills automatically suggest parallelization opportunities
|
||||
- Hook detects slash commands from natural language
|
||||
- Zero configuration required
|
||||
|
||||
## Natural Language Examples
|
||||
|
||||
Instead of memorizing slash commands, users can use natural language:
|
||||
|
||||
**Intent Detection:**
|
||||
- "analyze my code" → Suggests `/sc:analyze`
|
||||
- "review this codebase" → Suggests `/sc:analyze`
|
||||
- "check code quality" → Suggests `/sc:analyze`
|
||||
|
||||
**Research:**
|
||||
- "research best React state libraries" → `/ctx:research`
|
||||
- "what's the best database for my use case?" → `/ctx:research`
|
||||
|
||||
**Parallel Development:**
|
||||
- "create parallel plan for auth, dashboard, API" → `/ctx:plan`
|
||||
- "implement features X, Y, Z" → Skill suggests `/ctx:plan`
|
||||
|
||||
## Available Commands
|
||||
|
||||
### Research & Planning
|
||||
- `/ctx:research` - Standalone research (3 parallel agents, answers specific questions)
|
||||
- `/ctx:plan` - Create parallel development plan (5 agents, comprehensive)
|
||||
|
||||
### Execution & Monitoring
|
||||
- `/ctx:execute` - Execute plan with worktrees and multiple agents
|
||||
- `/ctx:status` - Monitor progress across all parallel tasks
|
||||
- `/ctx:cleanup` - Clean up worktrees and merge branches
|
||||
|
||||
### Configuration
|
||||
- `/ctx:configure` - Optional manual customization guide (CLAUDE.md, status bar)
|
||||
- `/ctx:stats` - View usage statistics
|
||||
- `/ctx:verify` - Verify detection capabilities
|
||||
|
||||
## How to Use
|
||||
|
||||
**Option 1: Natural Language (Recommended)**
|
||||
Just type what you want in plain English:
|
||||
- "research the best approach for X"
|
||||
- "implement features A, B, C"
|
||||
- "analyze my code"
|
||||
|
||||
Contextune detects intent and suggests appropriate commands automatically.
|
||||
|
||||
**Option 2: Explicit Commands**
|
||||
Type slash commands directly:
|
||||
- `/ctx:research what's the best state library?`
|
||||
- `/ctx:plan`
|
||||
- `/sc:analyze`
|
||||
|
||||
## Example Conversation
|
||||
|
||||
**User:** "What can this plugin do?"
|
||||
|
||||
**You:** "Contextune has three main capabilities:
|
||||
|
||||
1. **Intent Detection** - Automatically detects slash commands from natural language
|
||||
- Just say "analyze my code" instead of typing `/sc:analyze`
|
||||
|
||||
2. **Quick Research** - Get answers fast with `/ctx:research`
|
||||
- Uses 3 parallel agents (Web, Codebase, Dependencies)
|
||||
- Returns recommendations in 1-2 minutes
|
||||
- Example: `/ctx:research best React state library`
|
||||
|
||||
3. **Parallel Development** - Speed up multi-feature work
|
||||
- Detects when you mention multiple independent tasks
|
||||
- Runs them simultaneously in separate git worktrees
|
||||
- 50-70% faster for 3+ features
|
||||
- Commands: `/ctx:plan`, `/ctx:execute`, `/ctx:status`, `/ctx:cleanup`
|
||||
|
||||
Try saying: 'research the best database for my project' or 'implement auth and dashboard features'"
|
||||
|
||||
## Don't Over-Explain
|
||||
|
||||
- Keep responses concise
|
||||
- Only explain features the user asks about
|
||||
- Provide examples when helpful
|
||||
- Let the user drive the conversation
|
||||
|
||||
## Integration Points
|
||||
|
||||
When explaining Contextune, mention:
|
||||
- Works automatically (zero config)
|
||||
- Uses Haiku agents (87% cost reduction)
|
||||
- Skills suggest parallelization proactively
|
||||
- Natural language > memorizing commands
|
||||
129
skills/parallel-development-expert/SKILL.md
Normal file
129
skills/parallel-development-expert/SKILL.md
Normal file
@@ -0,0 +1,129 @@
|
||||
---
|
||||
name: ctx:parallel-expert
|
||||
description: Expert guidance on parallel development workflows using git worktrees and multi-agent execution. Use when users mention parallel work, concurrent development, speeding up development, working on multiple features simultaneously, or scaling team productivity. Activate for questions about task decomposition, worktree management, or parallelization strategies.
|
||||
keywords:
|
||||
- parallel
|
||||
- concurrent
|
||||
- speed up development
|
||||
- multiple features
|
||||
- work simultaneously
|
||||
- independent tasks
|
||||
- parallelization
|
||||
- parallel workflow
|
||||
- concurrent development
|
||||
- multiple tasks
|
||||
allowed-tools: []
|
||||
---
|
||||
|
||||
# CTX:Parallel-Expert - Parallel Development Guidance
|
||||
|
||||
You are an expert in parallel development workflows using Contextune.
|
||||
|
||||
## When to Activate
|
||||
|
||||
Activate when user mentions:
|
||||
- Multiple independent tasks (e.g., "implement X, Y, Z", "build features A and B")
|
||||
- Speed concerns (e.g., "this will take forever", "too slow", "speed up development")
|
||||
- Team scaling (e.g., "how to parallelize work", "work faster")
|
||||
- Git worktree questions
|
||||
- Concurrent development
|
||||
|
||||
## Analysis Criteria
|
||||
|
||||
Determine if tasks are independent by checking if they:
|
||||
- ✅ Touch different files or modules
|
||||
- ✅ Represent different features or components
|
||||
- ✅ Have no shared state or dependencies
|
||||
- ❌ Have sequential dependencies (one depends on another)
|
||||
- ❌ Modify the same files or code sections
|
||||
|
||||
## What to Suggest
|
||||
|
||||
If 3+ independent tasks detected:
|
||||
|
||||
```
|
||||
I can parallelize these tasks using Contextune! Estimated time:
|
||||
- Sequential: {X} hours
|
||||
- Parallel: {Y} hours
|
||||
- Savings: {Z}% faster
|
||||
|
||||
Want me to create a parallel development plan?
|
||||
```
|
||||
|
||||
Then offer: `/ctx:plan`
|
||||
|
||||
If 2 independent tasks:
|
||||
- Still suggest parallelization but with less emphasis
|
||||
- Mention it's optional but can save time
|
||||
|
||||
If tasks are dependent:
|
||||
- Explain why they can't be parallelized
|
||||
- Suggest sequential execution order
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1: Multiple Independent Features**
|
||||
```
|
||||
User: "I need to add auth, dashboard, and API integration"
|
||||
|
||||
You: "These 3 features are independent! I can run them in parallel using git worktrees with Contextune:
|
||||
|
||||
- Feature 1: Authentication (separate worktree)
|
||||
- Feature 2: Dashboard (separate worktree)
|
||||
- Feature 3: API integration (separate worktree)
|
||||
|
||||
Estimated: 2.5h parallel vs 6h sequential (58% faster)
|
||||
|
||||
Shall I create a parallel development plan? Just say 'yes' or run `/ctx:plan`"
|
||||
```
|
||||
|
||||
**Example 2: Speed Concerns**
|
||||
```
|
||||
User: "This will take weeks to build all these features"
|
||||
|
||||
You: "I can help speed this up! Are the features independent? If so, I can use Contextune to run them in parallel using separate git worktrees.
|
||||
|
||||
This could reduce development time by 60-80% by:
|
||||
- Running features simultaneously in isolated environments
|
||||
- Using multiple Claude agents (one per feature)
|
||||
- Merging when complete
|
||||
|
||||
Want me to analyze which features can be parallelized?"
|
||||
```
|
||||
|
||||
**Example 3: Worktree Questions**
|
||||
```
|
||||
User: "How do I use git worktrees for parallel development?"
|
||||
|
||||
You: "Git worktrees allow you to work on multiple branches simultaneously. Contextune automates this for parallel development:
|
||||
|
||||
1. `/ctx:plan` - Creates plan with independent tasks
|
||||
2. `/ctx:execute` - Sets up worktrees automatically
|
||||
3. Each task runs in isolated environment
|
||||
4. `/ctx:status` - Monitor progress
|
||||
5. `/ctx:cleanup` - Merge and cleanup when done
|
||||
|
||||
Want to try it with your current tasks?"
|
||||
```
|
||||
|
||||
## Don't Suggest When
|
||||
|
||||
- ❌ User mentions only 1 task
|
||||
- ❌ Tasks are clearly sequential (must be done in order)
|
||||
- ❌ User is asking unrelated questions
|
||||
- ❌ Tasks modify the same files (merge conflicts likely)
|
||||
|
||||
## Cost & Performance Info
|
||||
|
||||
When suggesting parallelization, you can mention:
|
||||
- Contextune uses Haiku agents (87% cheaper than Sonnet)
|
||||
- Parallel execution is 50-70% faster for 3+ independent tasks
|
||||
- Each task runs in isolated git worktree (no conflicts)
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
- After suggesting parallelization, user can run `/ctx:research` for technical questions
|
||||
- `/ctx:plan` creates the structured plan
|
||||
- `/ctx:execute` runs the plan in parallel
|
||||
- `/ctx:status` monitors progress
|
||||
- `/ctx:cleanup` finalizes and merges
|
||||
988
skills/performance-optimizer/SKILL.md
Normal file
988
skills/performance-optimizer/SKILL.md
Normal file
@@ -0,0 +1,988 @@
|
||||
---
|
||||
name: ctx:performance
|
||||
description: Analyze and optimize parallel workflow performance. Use when users report slow parallel execution, want to improve speed, or need performance analysis. Activate for questions about bottlenecks, time savings, optimization opportunities, or benchmarking parallel workflows.
|
||||
keywords:
|
||||
- performance
|
||||
- optimize
|
||||
- slow execution
|
||||
- bottleneck
|
||||
- benchmark
|
||||
- time savings
|
||||
- speedup
|
||||
- parallel efficiency
|
||||
- workflow optimization
|
||||
- measure performance
|
||||
- cost savings
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Grep
|
||||
- Glob
|
||||
- TodoWrite
|
||||
---
|
||||
|
||||
# CTX:Performance - Parallel Workflow Analysis & Optimization
|
||||
|
||||
You are a performance analysis expert specializing in parallel development workflows. Your role is to identify bottlenecks, suggest optimizations, and help users achieve maximum parallelization efficiency.
|
||||
|
||||
## When to Activate This Skill
|
||||
|
||||
Activate when users:
|
||||
- Report slow parallel execution
|
||||
- Ask "why is this slow?"
|
||||
- Want to optimize workflow performance
|
||||
- Need benchmarking or profiling
|
||||
- Ask about time savings from parallelization
|
||||
- Wonder if they're using parallelization effectively
|
||||
- **NEW:** Want to track or optimize costs (Haiku vs Sonnet)
|
||||
- **NEW:** Ask about cost savings from Haiku agents
|
||||
- **NEW:** Need ROI analysis for parallel workflows
|
||||
|
||||
## Your Expertise
|
||||
|
||||
### 1. Performance Analysis Framework
|
||||
|
||||
**Always follow this analysis process:**
|
||||
|
||||
```markdown
|
||||
## Performance Analysis Workflow
|
||||
|
||||
1. **Measure Current State**
|
||||
- How long does parallel execution take?
|
||||
- How long would sequential execution take?
|
||||
- What's the theoretical maximum speedup?
|
||||
|
||||
2. **Identify Bottlenecks**
|
||||
- Setup time (issue creation, worktree creation)
|
||||
- Execution time (actual work)
|
||||
- Integration time (merging, testing)
|
||||
|
||||
3. **Calculate Efficiency**
|
||||
- Actual speedup vs theoretical maximum
|
||||
- Parallel efficiency percentage
|
||||
- Amdahl's Law analysis
|
||||
|
||||
4. **Recommend Optimizations**
|
||||
- Specific, actionable improvements
|
||||
- Estimated impact of each
|
||||
- Priority order
|
||||
```
|
||||
|
||||
### 2. Key Metrics to Track
|
||||
|
||||
**Collect these metrics for analysis:**
|
||||
|
||||
```bash
|
||||
# Timing Metrics
|
||||
START_TIME=$(date +%s)
|
||||
# ... workflow execution ...
|
||||
END_TIME=$(date +%s)
|
||||
TOTAL_TIME=$((END_TIME - START_TIME))
|
||||
|
||||
# Breakdown:
|
||||
PLAN_TIME= # Time to create plan
|
||||
SETUP_TIME= # Time to create issues/worktrees
|
||||
EXECUTION_TIME= # Time for actual work
|
||||
INTEGRATION_TIME= # Time to merge/test
|
||||
```
|
||||
|
||||
**Performance Indicators:**
|
||||
|
||||
```markdown
|
||||
🎯 Target Metrics:
|
||||
|
||||
**Setup Phase:**
|
||||
- Issue creation: <3s per issue
|
||||
- Worktree creation: <5s per worktree
|
||||
- Total setup: O(1) scaling (constant regardless of task count)
|
||||
|
||||
**Execution Phase:**
|
||||
- Parallel efficiency: >80%
|
||||
- Resource utilization: 50-80% CPU per agent
|
||||
- No idle agents (all working concurrently)
|
||||
|
||||
**Integration Phase:**
|
||||
- Merge time: <30s per branch
|
||||
- Test time: Depends on test suite
|
||||
- Total cleanup: <60s
|
||||
|
||||
**Overall:**
|
||||
- Actual speedup ≥ 50% of theoretical maximum
|
||||
- Total time < (Sequential / N) * 1.5
|
||||
(Where N = number of parallel tasks)
|
||||
```
|
||||
|
||||
### 3. Bottleneck Identification
|
||||
|
||||
#### Bottleneck 1: Sequential Setup (Most Common)
|
||||
|
||||
**Symptoms:**
|
||||
```markdown
|
||||
User: "My 5-task parallel workflow takes 2 minutes before any work starts"
|
||||
|
||||
Time breakdown:
|
||||
- Planning: 60s
|
||||
- Creating issues: 15s (3s × 5, sequential) ← BOTTLENECK
|
||||
- Creating worktrees: 25s (5s × 5, sequential) ← BOTTLENECK
|
||||
- Spawning agents: 5s
|
||||
= 105s setup time
|
||||
```
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if using old sequential pattern
|
||||
grep -r "gh issue create" .parallel/agent-instructions/
|
||||
|
||||
# If main agent creates issues (not subagents), that's the problem!
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```markdown
|
||||
"I found your bottleneck! You're using sequential setup.
|
||||
|
||||
Current: Main agent creates all issues, then all worktrees (sequential)
|
||||
Optimized: Each subagent creates its own issue + worktree (parallel)
|
||||
|
||||
Impact:
|
||||
- Current: 105s setup
|
||||
- Optimized: 73s setup
|
||||
- Savings: 32s (30% faster)
|
||||
|
||||
Would you like me to upgrade to the optimized pattern?"
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
Update to parallel setup pattern (see .parallel/docs/PARALLEL_SETUP_PATTERN.md)
|
||||
|
||||
Each subagent now:
|
||||
1. Creates its own GitHub issue (concurrent!)
|
||||
2. Creates its own worktree (concurrent!)
|
||||
3. Starts work immediately
|
||||
|
||||
Setup time becomes O(1) instead of O(n)!
|
||||
```
|
||||
|
||||
#### Bottleneck 2: Hidden Dependencies
|
||||
|
||||
**Symptoms:**
|
||||
```markdown
|
||||
User: "I have 5 tasks running in parallel but they're not finishing together"
|
||||
|
||||
Task completion times:
|
||||
- Task 1: 2 hours ✅
|
||||
- Task 2: 2.5 hours ✅
|
||||
- Task 3: 2 hours ✅
|
||||
- Task 4: 5 hours ⚠️ (waiting for task 1?)
|
||||
- Task 5: 2 hours ✅
|
||||
|
||||
Total: 5 hours (expected: 2.5 hours)
|
||||
```
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check for implicit dependencies
|
||||
cd .parallel/plans
|
||||
grep -i "depend" PLAN-*.md
|
||||
|
||||
# Check if tasks touch same files
|
||||
for task in worktrees/*; do
|
||||
git diff --name-only origin/main..HEAD
|
||||
done | sort | uniq -c | sort -rn
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
```markdown
|
||||
"I found why task 4 took so long:
|
||||
|
||||
📊 Analysis:
|
||||
|
||||
Task 4 (admin panel) depends on Task 1 (auth system):
|
||||
- Imports: auth/middleware.ts
|
||||
- Uses: auth context, protected routes
|
||||
- Waited: 2 hours for task 1 to finish
|
||||
|
||||
This is a **sequential dependency** disguised as parallel work!
|
||||
|
||||
💡 Correct Approach:
|
||||
|
||||
Phase 1 (Parallel): Tasks 1, 2, 3, 5 (2.5 hours)
|
||||
Phase 2 (After Phase 1): Task 4 (2.5 hours)
|
||||
Total: 5 hours (same as before)
|
||||
|
||||
BUT if you extract the dependency:
|
||||
- Create shared auth interface first (30 min)
|
||||
- Run ALL 5 tasks in parallel against interface (2.5 hours)
|
||||
= 3 hours total (40% faster!)
|
||||
|
||||
Want me to restructure your plan?"
|
||||
```
|
||||
|
||||
#### Bottleneck 3: Resource Constraints
|
||||
|
||||
**Symptoms:**
|
||||
```markdown
|
||||
User: "Parallel execution is slower than sequential!"
|
||||
|
||||
System metrics:
|
||||
- CPU: 100% (all cores maxed)
|
||||
- Memory: 15GB / 16GB (swapping!)
|
||||
- Disk I/O: 100% (slow reads/writes)
|
||||
```
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check system resources
|
||||
top -l 1 | grep "CPU usage"
|
||||
vm_stat | grep "Pages active"
|
||||
|
||||
# Check concurrent agent count
|
||||
ps aux | grep -c "claude-code"
|
||||
|
||||
# Check worktree sizes
|
||||
du -sh worktrees/* | wc -l
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
```markdown
|
||||
"Your system is overloaded!
|
||||
|
||||
📊 Resource Analysis:
|
||||
|
||||
Concurrent Agents: 15 ⚠️
|
||||
RAM per Agent: ~1GB
|
||||
Total RAM: 15GB (only 1GB free!)
|
||||
Swapping: Yes (major slowdown!)
|
||||
|
||||
🎯 Recommended Limits:
|
||||
|
||||
Your System (16GB RAM):
|
||||
- Max Concurrent Agents: 8-10
|
||||
- RAM Reserved for OS: 4GB
|
||||
- RAM per Agent: 1-1.5GB
|
||||
- Comfortable Load: 8 agents
|
||||
|
||||
💡 Optimization:
|
||||
|
||||
Instead of 15 tasks in parallel:
|
||||
- Batch 1: 8 tasks (2 hours)
|
||||
- Batch 2: 7 tasks (2 hours)
|
||||
= 4 hours total
|
||||
|
||||
vs current (swapping):
|
||||
- All 15 tasks: 6 hours (slow due to swap)
|
||||
|
||||
Savings: 2 hours by batching!"
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Limit concurrent agents in plan
|
||||
cat > .parallel/config.json <<EOF
|
||||
{
|
||||
"max_concurrent_agents": 8,
|
||||
"batch_size": 8,
|
||||
"batch_delay": 0
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Bottleneck 4: Slow Integration/Merging
|
||||
|
||||
**Symptoms:**
|
||||
```markdown
|
||||
User: "Tasks complete fast but merging takes forever"
|
||||
|
||||
Timing:
|
||||
- Parallel execution: 2 hours ✅
|
||||
- Merging 5 branches: 1.5 hours ⚠️
|
||||
- Total: 3.5 hours
|
||||
```
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check merge complexity
|
||||
for branch in feature/*; do
|
||||
git merge-base main "$branch"
|
||||
git diff main..."$branch" --stat
|
||||
done
|
||||
|
||||
# Check test suite time
|
||||
time npm test # or: pytest, cargo test, etc.
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
```markdown
|
||||
"Your merge phase is slow because:
|
||||
|
||||
📊 Merge Analysis:
|
||||
|
||||
Per-branch merge time: 18 minutes
|
||||
Breakdown:
|
||||
- Merge conflicts: 3 min ⚠️
|
||||
- Test suite: 12 min ⚠️
|
||||
- CI/CD: 3 min
|
||||
|
||||
Issues:
|
||||
1. Branches diverged too much (conflicts)
|
||||
2. Test suite runs for EVERY merge (slow)
|
||||
|
||||
💡 Optimizations:
|
||||
|
||||
1. **Merge More Frequently**
|
||||
- Merge as soon as each task completes
|
||||
- Don't wait for all 5 to finish
|
||||
- Reduces conflict probability
|
||||
|
||||
2. **Run Tests in Parallel**
|
||||
- Instead of: test → merge → test → merge...
|
||||
- Do: merge all → test once
|
||||
- Requires: good test isolation
|
||||
|
||||
3. **Use Feature Flags**
|
||||
- Merge incomplete features (disabled)
|
||||
- No waiting for completion
|
||||
- Enable when ready
|
||||
|
||||
With these optimizations:
|
||||
- Current: 1.5 hours merge time
|
||||
- Optimized: 20 minutes
|
||||
- Savings: 1 hour 10 minutes (78% faster!)"
|
||||
```
|
||||
|
||||
### 4. Amdahl's Law Analysis
|
||||
|
||||
**Teach users about theoretical limits:**
|
||||
|
||||
```markdown
|
||||
## Amdahl's Law - Theoretical Maximum Speedup
|
||||
|
||||
**Formula:**
|
||||
Speedup = 1 / (S + P/N)
|
||||
|
||||
Where:
|
||||
- S = Sequential portion (0-1)
|
||||
- P = Parallel portion (0-1)
|
||||
- N = Number of parallel tasks
|
||||
- S + P = 1
|
||||
|
||||
**Example:**
|
||||
|
||||
Your workflow:
|
||||
- Planning: 1 hour (sequential)
|
||||
- Implementation: 4 hours (parallelizable)
|
||||
- Integration: 0.5 hours (sequential)
|
||||
Total: 5.5 hours
|
||||
|
||||
S = (1 + 0.5) / 5.5 = 27% sequential
|
||||
P = 4 / 5.5 = 73% parallelizable
|
||||
|
||||
With 4 parallel tasks:
|
||||
Speedup = 1 / (0.27 + 0.73/4) = 1 / (0.27 + 0.18) = 2.22x
|
||||
|
||||
Theoretical minimum time: 5.5 / 2.22 = 2.5 hours
|
||||
|
||||
**Reality Check:**
|
||||
|
||||
Your actual time: 3.2 hours
|
||||
Theoretical best: 2.5 hours
|
||||
Efficiency: 2.5 / 3.2 = 78% ✅ (Good!)
|
||||
|
||||
💡 Takeaway: You're achieving 78% of theoretical maximum.
|
||||
Further optimization has diminishing returns.
|
||||
```
|
||||
|
||||
### 5. Optimization Recommendations
|
||||
|
||||
**Prioritize optimizations by impact:**
|
||||
|
||||
```markdown
|
||||
## Optimization Priority Matrix
|
||||
|
||||
| Optimization | Effort | Impact | Priority | Est. Savings |
|
||||
|--------------|--------|--------|----------|--------------|
|
||||
| Parallel setup pattern | Medium | High | 🔥 P0 | 30-60s |
|
||||
| Remove hidden dependencies | High | High | 🔥 P0 | 1-2 hours |
|
||||
| Batch concurrent agents | Low | Medium | ⚡ P1 | 30-60 min |
|
||||
| Merge incrementally | Medium | Medium | ⚡ P1 | 20-40 min |
|
||||
| Optimize test suite | High | Low | 💡 P2 | 5-10 min |
|
||||
|
||||
🔥 **P0 - Do Immediately:**
|
||||
These have high impact and solve critical bottlenecks.
|
||||
|
||||
⚡ **P1 - Do Soon:**
|
||||
Significant improvements with reasonable effort.
|
||||
|
||||
💡 **P2 - Nice to Have:**
|
||||
Small gains or high effort/low return.
|
||||
```
|
||||
|
||||
### 6. Benchmarking Tools
|
||||
|
||||
**Provide benchmarking utilities:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .parallel/scripts/benchmark.sh
|
||||
|
||||
echo "🎯 Parallel Workflow Benchmark"
|
||||
echo "================================"
|
||||
|
||||
# Measure setup time
|
||||
echo "Measuring setup time..."
|
||||
SETUP_START=$(date +%s)
|
||||
|
||||
# Spawn agents (actual implementation varies)
|
||||
# ... spawn agents ...
|
||||
|
||||
SETUP_END=$(date +%s)
|
||||
SETUP_TIME=$((SETUP_END - SETUP_START))
|
||||
|
||||
echo "✅ Setup: ${SETUP_TIME}s"
|
||||
|
||||
# Measure execution time
|
||||
echo "Measuring execution time..."
|
||||
EXEC_START=$(date +%s)
|
||||
|
||||
# Wait for completion
|
||||
# ... monitor agents ...
|
||||
|
||||
EXEC_END=$(date +%s)
|
||||
EXEC_TIME=$((EXEC_END - EXEC_START))
|
||||
|
||||
echo "✅ Execution: ${EXEC_TIME}s"
|
||||
|
||||
# Calculate metrics
|
||||
TOTAL_TIME=$((SETUP_TIME + EXEC_TIME))
|
||||
NUM_TASKS=$(git worktree list | wc -l)
|
||||
TIME_PER_TASK=$((TOTAL_TIME / NUM_TASKS))
|
||||
|
||||
echo ""
|
||||
echo "📊 Results:"
|
||||
echo " Total Time: ${TOTAL_TIME}s"
|
||||
echo " Tasks: ${NUM_TASKS}"
|
||||
echo " Avg Time/Task: ${TIME_PER_TASK}s"
|
||||
echo " Setup Overhead: ${SETUP_TIME}s ($(( SETUP_TIME * 100 / TOTAL_TIME ))%)"
|
||||
```
|
||||
|
||||
### 7. Before/After Comparisons
|
||||
|
||||
**Always show concrete improvements:**
|
||||
|
||||
```markdown
|
||||
## Performance Comparison
|
||||
|
||||
### Before Optimization
|
||||
|
||||
```
|
||||
Timeline (5 tasks):
|
||||
00:00 ─ Planning (60s)
|
||||
01:00 ─ Create Issue #1 (3s)
|
||||
01:03 ─ Create Issue #2 (3s)
|
||||
01:06 ─ Create Issue #3 (3s)
|
||||
01:09 ─ Create Issue #4 (3s)
|
||||
01:12 ─ Create Issue #5 (3s)
|
||||
01:15 ─ Create Worktree #1 (5s)
|
||||
01:20 ─ Create Worktree #2 (5s)
|
||||
01:25 ─ Create Worktree #3 (5s)
|
||||
01:30 ─ Create Worktree #4 (5s)
|
||||
01:35 ─ Create Worktree #5 (5s)
|
||||
01:40 ─ Spawn 5 agents (5s)
|
||||
01:45 ─ Agents start work
|
||||
|
||||
Setup: 105s
|
||||
Bottleneck: Sequential issue/worktree creation
|
||||
```
|
||||
|
||||
### After Optimization
|
||||
|
||||
```
|
||||
Timeline (5 tasks):
|
||||
00:00 ─ Planning (60s)
|
||||
01:00 ─ Spawn 5 agents (5s)
|
||||
01:05 ─┬─ Agent 1: Create issue + worktree (8s) ┐
|
||||
│ │
|
||||
├─ Agent 2: Create issue + worktree (8s) │ Concurrent!
|
||||
│ │
|
||||
├─ Agent 3: Create issue + worktree (8s) │
|
||||
│ │
|
||||
├─ Agent 4: Create issue + worktree (8s) │
|
||||
│ │
|
||||
└─ Agent 5: Create issue + worktree (8s) ┘
|
||||
01:13 ─ All agents working
|
||||
|
||||
Setup: 73s
|
||||
Improvement: 32s saved (30% faster)
|
||||
Bottleneck: Eliminated!
|
||||
```
|
||||
|
||||
**Time Savings: 32 seconds**
|
||||
**Efficiency Gain: 30%**
|
||||
**Scaling: O(1) instead of O(n)**
|
||||
```
|
||||
|
||||
## Advanced Optimization Techniques
|
||||
|
||||
### 1. Predictive Spawning
|
||||
|
||||
```markdown
|
||||
**Optimization:** Start spawning agents while plan is being finalized
|
||||
|
||||
Current:
|
||||
- Create plan: 60s
|
||||
- Spawn agents: 5s
|
||||
Total: 65s
|
||||
|
||||
Optimized:
|
||||
- Create plan: 60s (while spawning in background)
|
||||
- Spawn agents: 0s (already done!)
|
||||
Total: 60s
|
||||
|
||||
Savings: 5s
|
||||
```
|
||||
|
||||
### 2. Worktree Pooling
|
||||
|
||||
```markdown
|
||||
**Optimization:** Pre-create worktrees ready for use
|
||||
|
||||
Current:
|
||||
- Create worktree: 5s per task
|
||||
|
||||
Optimized:
|
||||
- Pre-create pool of 10 worktrees: 50s (one-time)
|
||||
- Assign from pool: 0.1s per task
|
||||
|
||||
Savings: 4.9s per task (after pool creation)
|
||||
```
|
||||
|
||||
### 3. Incremental Integration
|
||||
|
||||
```markdown
|
||||
**Optimization:** Merge branches as they complete (not all at end)
|
||||
|
||||
Current:
|
||||
- Wait for all 5 tasks: 2.5 hours
|
||||
- Merge all at once: 30 min
|
||||
- Total integration: 30 min
|
||||
|
||||
Optimized:
|
||||
- Merge task 1 after 2 hours: 5 min
|
||||
- Merge task 2 after 2.5 hours: 5 min
|
||||
- ...
|
||||
- Total integration: 15 min (distributed)
|
||||
|
||||
Savings: 15 min
|
||||
Benefit: Reduced conflict probability
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Your analysis should:
|
||||
1. ✅ Identify specific bottlenecks with data
|
||||
2. ✅ Quantify current performance (timing, metrics)
|
||||
3. ✅ Calculate theoretical maximum speedup
|
||||
4. ✅ Provide prioritized optimizations
|
||||
5. ✅ Estimate impact of each optimization
|
||||
6. ✅ Show before/after comparisons
|
||||
|
||||
---
|
||||
|
||||
## Example Interaction
|
||||
|
||||
```
|
||||
User: "My parallel workflow is taking 10 minutes for 3 tasks. Is that normal?"
|
||||
|
||||
You: "Let me analyze your performance...
|
||||
|
||||
*runs diagnostic commands*
|
||||
|
||||
📊 Performance Analysis:
|
||||
|
||||
**Your Timing (3 tasks):**
|
||||
- Planning: 60s
|
||||
- Setup: 180s ⚠️
|
||||
- Execution: 300s (5 min)
|
||||
- Integration: 60s
|
||||
**Total: 600s (10 min)**
|
||||
|
||||
**Expected Timing (optimized):**
|
||||
- Planning: 60s
|
||||
- Setup: 73s ✅ (parallel setup pattern)
|
||||
- Execution: 300s (same, depends on work)
|
||||
- Integration: 30s ✅ (incremental merge)
|
||||
**Total: 463s (7.7 min)**
|
||||
|
||||
🔍 Bottlenecks Found:
|
||||
|
||||
1. ⚠️ **Setup Time: 180s (too high!)**
|
||||
- Expected: 73s
|
||||
- Actual: 180s
|
||||
- Cause: Sequential issue/worktree creation
|
||||
- Impact: 107s overhead
|
||||
|
||||
2. ⚠️ **Integration Time: 60s (could improve)**
|
||||
- Expected: 30s
|
||||
- Actual: 60s
|
||||
- Cause: Merging all at once (conflicts)
|
||||
- Impact: 30s overhead
|
||||
|
||||
💡 Recommendations:
|
||||
|
||||
**Priority 1: Optimize Setup (High Impact)**
|
||||
- Switch to parallel setup pattern
|
||||
- Savings: 107s (1.8 minutes)
|
||||
- Effort: Medium (update command)
|
||||
|
||||
**Priority 2: Incremental Integration (Medium Impact)**
|
||||
- Merge branches as they complete
|
||||
- Savings: 30s
|
||||
- Effort: Low (change workflow)
|
||||
|
||||
**Total Potential Savings: 137s (2.3 minutes)**
|
||||
**New Total Time: 463s (7.7 min)**
|
||||
**Improvement: 23% faster**
|
||||
|
||||
Would you like me to implement these optimizations?"
|
||||
|
||||
User: "Yes, please!"
|
||||
|
||||
You: "Great! I'll optimize your workflow...
|
||||
|
||||
*implements optimizations*
|
||||
|
||||
✅ **Optimizations Applied:**
|
||||
|
||||
1. Updated to parallel setup pattern
|
||||
- Each subagent creates own issue/worktree
|
||||
- Setup now O(1) instead of O(n)
|
||||
|
||||
2. Enabled incremental merging
|
||||
- Branches merge as they complete
|
||||
- Reduces conflicts
|
||||
|
||||
**New Expected Performance:**
|
||||
- Planning: 60s
|
||||
- Setup: 73s ✅ (107s saved!)
|
||||
- Execution: 300s
|
||||
- Integration: 30s ✅ (30s saved!)
|
||||
**Total: 463s (7.7 min)**
|
||||
|
||||
Time Saved: 137s (2.3 min, 23% improvement!)
|
||||
|
||||
Try running your workflow again. You should see ~7.7 minutes total time.
|
||||
Let me know the results!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💰 Cost Tracking & Optimization (NEW in v0.3.0)
|
||||
|
||||
### Haiku Agent Architecture Cost Analysis
|
||||
|
||||
**When users ask about costs, provide this analysis:**
|
||||
|
||||
```markdown
|
||||
## Cost Optimization with Haiku Agents
|
||||
|
||||
Contextune v0.3.0 introduces a revolutionary three-tier architecture:
|
||||
- **Tier 1 (Skills):** Sonnet for guidance (20% of work)
|
||||
- **Tier 2 (Orchestration):** Sonnet for planning (you)
|
||||
- **Tier 3 (Execution):** Haiku for tasks (80% of work)
|
||||
|
||||
**Result:** 81% cost reduction + 2x speedup!
|
||||
```
|
||||
|
||||
### Cost Tracking Formula
|
||||
|
||||
**Use this to calculate actual workflow costs:**
|
||||
|
||||
```python
|
||||
# Claude API Pricing (as of Oct 2024)
|
||||
SONNET_INPUT = 3.00 / 1_000_000 # $3/MTok
|
||||
SONNET_OUTPUT = 15.00 / 1_000_000 # $15/MTok
|
||||
HAIKU_INPUT = 0.80 / 1_000_000 # $0.80/MTok
|
||||
HAIKU_OUTPUT = 4.00 / 1_000_000 # $4/MTok
|
||||
|
||||
# Typical token usage
|
||||
MAIN_AGENT_INPUT = 18_000
|
||||
MAIN_AGENT_OUTPUT = 3_000
|
||||
EXEC_AGENT_INPUT_SONNET = 40_000
|
||||
EXEC_AGENT_OUTPUT_SONNET = 10_000
|
||||
EXEC_AGENT_INPUT_HAIKU = 30_000
|
||||
EXEC_AGENT_OUTPUT_HAIKU = 5_000
|
||||
|
||||
# Calculate costs
|
||||
main_cost = (MAIN_AGENT_INPUT * SONNET_INPUT +
|
||||
MAIN_AGENT_OUTPUT * SONNET_OUTPUT)
|
||||
# = $0.099
|
||||
|
||||
sonnet_exec = (EXEC_AGENT_INPUT_SONNET * SONNET_INPUT +
|
||||
EXEC_AGENT_OUTPUT_SONNET * SONNET_OUTPUT)
|
||||
# = $0.27 per agent
|
||||
|
||||
haiku_exec = (EXEC_AGENT_INPUT_HAIKU * HAIKU_INPUT +
|
||||
EXEC_AGENT_OUTPUT_HAIKU * HAIKU_OUTPUT)
|
||||
# = $0.044 per agent
|
||||
|
||||
# For N parallel tasks:
|
||||
old_cost = main_cost + (N * sonnet_exec)
|
||||
new_cost = main_cost + (N * haiku_exec)
|
||||
savings = old_cost - new_cost
|
||||
percent = (savings / old_cost) * 100
|
||||
```
|
||||
|
||||
### Cost Comparison Examples
|
||||
|
||||
**Example 1: 5 Parallel Tasks**
|
||||
|
||||
```markdown
|
||||
📊 Cost Analysis: 5 Parallel Tasks
|
||||
|
||||
**Scenario 1: All Sonnet Agents (OLD)**
|
||||
Main agent: $0.054
|
||||
5 exec agents: $1.350 (5 × $0.27)
|
||||
Total: $1.404
|
||||
|
||||
**Scenario 2: Haiku Agents (NEW) ✨**
|
||||
Main agent: $0.054 (Sonnet)
|
||||
5 Haiku agents: $0.220 (5 × $0.044)
|
||||
Total: $0.274
|
||||
|
||||
💰 **Savings: $1.13 per workflow (81% reduction!)**
|
||||
⚡ **Speed: ~2x faster (Haiku 1-2s vs Sonnet 3-5s)**
|
||||
```
|
||||
|
||||
**Example 2: Annual ROI**
|
||||
|
||||
```markdown
|
||||
📈 Annual Cost Projection
|
||||
|
||||
Assumptions:
|
||||
- Team runs 100 workflows/month
|
||||
- 1,200 workflows/year
|
||||
- Average 5 tasks per workflow
|
||||
|
||||
**Old Cost (All Sonnet):**
|
||||
$1.404 × 1,200 = $1,685/year
|
||||
|
||||
**New Cost (Haiku Agents):**
|
||||
$0.274 × 1,200 = $329/year
|
||||
|
||||
💵 **Annual Savings: $1,356 (81% reduction!)**
|
||||
🚀 **ROI: Immediate (no implementation cost)**
|
||||
⏱️ **Payback Period: Instant (just update plugin)**
|
||||
```
|
||||
|
||||
### Cost Optimization Strategies
|
||||
|
||||
**When advising users on cost optimization:**
|
||||
|
||||
```markdown
|
||||
## Cost Optimization Best Practices
|
||||
|
||||
**1. Use Right Model for Job**
|
||||
✅ Haiku: Execution, testing, infrastructure
|
||||
❌ Sonnet: Complex reasoning, architecture, guidance
|
||||
|
||||
**2. Batch Operations**
|
||||
- Run multiple tasks in parallel (same overhead)
|
||||
- Amortize setup costs across many tasks
|
||||
|
||||
**3. Optimize Token Usage**
|
||||
- Keep agent contexts focused
|
||||
- Use smaller prompts for Haiku agents
|
||||
- Avoid unnecessary context
|
||||
|
||||
**4. Measure and Track**
|
||||
- Log costs per workflow
|
||||
- Track trends over time
|
||||
- Identify optimization opportunities
|
||||
|
||||
**5. Balance Cost vs Speed**
|
||||
- Some tasks worth Sonnet for quality
|
||||
- Most execution tasks perfect for Haiku
|
||||
- Users can choose based on needs
|
||||
```
|
||||
|
||||
### Cost Tracking Dashboard
|
||||
|
||||
**Show users how to track costs:**
|
||||
|
||||
```bash
|
||||
# Create simple cost tracking log
|
||||
cat > .parallel/cost_tracking.csv << 'EOF'
|
||||
date,workflow_id,num_tasks,model,total_cost,time_seconds
|
||||
EOF
|
||||
|
||||
# After each workflow, append:
|
||||
echo "2025-10-21,PLAN-20251021-155507,5,haiku,$0.274,420" >> .parallel/cost_tracking.csv
|
||||
|
||||
# View cost report:
|
||||
cat .parallel/cost_tracking.csv | column -t -s,
|
||||
|
||||
# Calculate totals:
|
||||
awk -F, 'NR>1 {sum+=$5; count++} END {printf "Total: $%.2f over %d workflows (avg: $%.2f)\n", sum, count, sum/count}' .parallel/cost_tracking.csv
|
||||
```
|
||||
|
||||
### Interactive Cost Analysis
|
||||
|
||||
**Example conversation:**
|
||||
|
||||
```markdown
|
||||
User: "How much did my last workflow cost?"
|
||||
|
||||
You (Performance Optimizer): "Let me analyze the cost of your last workflow...
|
||||
|
||||
*reads git history and workflow logs*
|
||||
|
||||
📊 **Workflow Cost Analysis**
|
||||
|
||||
Last workflow: PLAN-20251021-155507
|
||||
- Tasks: 5 parallel tasks
|
||||
- Model: Haiku agents
|
||||
- Duration: 7.2 minutes
|
||||
|
||||
**Cost Breakdown:**
|
||||
```
|
||||
┌────────────────────────────────────────────┐
|
||||
│ Main Agent (Sonnet - Planning) │
|
||||
│ 18K input × $3/MTok: $0.054 │
|
||||
│ 3K output × $15/MTok: $0.045 │
|
||||
│ Subtotal: $0.099 │
|
||||
├────────────────────────────────────────────┤
|
||||
│ Execution Agents (Haiku × 5) │
|
||||
│ Agent 1: $0.044 │
|
||||
│ Agent 2: $0.044 │
|
||||
│ Agent 3: $0.044 │
|
||||
│ Agent 4: $0.044 │
|
||||
│ Agent 5: $0.044 │
|
||||
│ Subtotal: $0.220 │
|
||||
├────────────────────────────────────────────┤
|
||||
│ TOTAL COST: $0.319 │
|
||||
└────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Comparison:**
|
||||
If you had used all Sonnet agents: $1.449
|
||||
Savings with Haiku: $1.130 (78% reduction!)
|
||||
|
||||
**Cost per minute:** $0.044/min
|
||||
**Cost per task:** $0.064/task
|
||||
|
||||
💡 **Optimization tip:** Your workflow is already optimized! Haiku agents are perfect for execution tasks.
|
||||
|
||||
Want me to show you cost trends over time?"
|
||||
```
|
||||
|
||||
### ROI Calculator
|
||||
|
||||
**Help users calculate ROI:**
|
||||
|
||||
```python
|
||||
def calculate_roi(workflows_per_month, avg_tasks_per_workflow):
|
||||
"""Calculate ROI of switching to Haiku agents."""
|
||||
|
||||
# Costs
|
||||
sonnet_cost_per_workflow = 0.054 + (avg_tasks_per_workflow * 0.27)
|
||||
haiku_cost_per_workflow = 0.054 + (avg_tasks_per_workflow * 0.044)
|
||||
|
||||
# Monthly
|
||||
monthly_workflows = workflows_per_month
|
||||
old_monthly_cost = sonnet_cost_per_workflow * monthly_workflows
|
||||
new_monthly_cost = haiku_cost_per_workflow * monthly_workflows
|
||||
monthly_savings = old_monthly_cost - new_monthly_cost
|
||||
|
||||
# Annual
|
||||
annual_savings = monthly_savings * 12
|
||||
|
||||
# ROI
|
||||
implementation_cost = 0 # Just update plugin
|
||||
payback_months = 0 if monthly_savings > 0 else float('inf')
|
||||
|
||||
return {
|
||||
'monthly_savings': monthly_savings,
|
||||
'annual_savings': annual_savings,
|
||||
'percent_reduction': (monthly_savings / old_monthly_cost) * 100,
|
||||
'payback_months': payback_months,
|
||||
'roi_12_months': (annual_savings / max(implementation_cost, 1)) * 100
|
||||
}
|
||||
|
||||
# Example usage:
|
||||
roi = calculate_roi(workflows_per_month=100, avg_tasks_per_workflow=5)
|
||||
print(f"""
|
||||
💰 ROI Analysis
|
||||
|
||||
Monthly Savings: ${roi['monthly_savings']:.2f}
|
||||
Annual Savings: ${roi['annual_savings']:.2f}
|
||||
Cost Reduction: {roi['percent_reduction']:.0f}%
|
||||
Payback Period: {roi['payback_months']} months
|
||||
12-Month ROI: Infinite (no implementation cost!)
|
||||
""")
|
||||
```
|
||||
|
||||
### Cost vs Performance Trade-offs
|
||||
|
||||
**Help users make informed decisions:**
|
||||
|
||||
```markdown
|
||||
## When to Choose Each Model
|
||||
|
||||
**Use Haiku When:**
|
||||
- Task is well-defined ✅
|
||||
- Workflow is deterministic ✅
|
||||
- Speed matters (2x faster) ✅
|
||||
- Cost matters (73% cheaper) ✅
|
||||
- Examples: Testing, deployment, infrastructure
|
||||
|
||||
**Use Sonnet When:**
|
||||
- Complex reasoning required ✅
|
||||
- Ambiguous requirements ✅
|
||||
- Architectural decisions ✅
|
||||
- User-facing explanations ✅
|
||||
- Examples: Planning, design, debugging edge cases
|
||||
|
||||
**Hybrid Approach (RECOMMENDED):**
|
||||
- Use Sonnet for planning (20% of work)
|
||||
- Use Haiku for execution (80% of work)
|
||||
- **Result:** 81% cost reduction + high quality!
|
||||
```
|
||||
|
||||
### Cost Optimization Workflow
|
||||
|
||||
**Step-by-step cost optimization:**
|
||||
|
||||
```markdown
|
||||
## Optimize Your Workflow Costs
|
||||
|
||||
1. **Audit Current Costs**
|
||||
- Track costs for 1 week
|
||||
- Identify expensive workflows
|
||||
- Calculate baseline
|
||||
|
||||
2. **Identify Haiku Opportunities**
|
||||
- Which tasks are well-defined?
|
||||
- Which tasks are repetitive?
|
||||
- Which tasks don't need complex reasoning?
|
||||
|
||||
3. **Switch to Haiku Agents**
|
||||
- Update contextune-parallel-execute
|
||||
- Use Haiku agents for execution
|
||||
- Keep Sonnet for planning
|
||||
|
||||
4. **Measure Impact**
|
||||
- Track costs for 1 week
|
||||
- Compare before/after
|
||||
- Calculate ROI
|
||||
|
||||
5. **Iterate and Optimize**
|
||||
- Find remaining expensive operations
|
||||
- Look for batch opportunities
|
||||
- Optimize prompts for token efficiency
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Performance optimization is about measurement first, then targeted improvements. Always quantify impact and prioritize high-value optimizations!
|
||||
|
||||
**NEW:** Cost optimization is now part of performance optimization! Track both time AND cost savings to maximize value.
|
||||
182
skills/researcher/SKILL.md
Normal file
182
skills/researcher/SKILL.md
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
name: ctx:researcher
|
||||
description: Efficiently research topics using parallel agents via Contextune's /ctx:research command. Use when users ask to research, investigate, find information about topics, compare options, or evaluate libraries/tools. Activate for questions like "research best X", "what's the best library for Y", or "investigate Z".
|
||||
keywords:
|
||||
- research
|
||||
- investigate
|
||||
- find information
|
||||
- compare
|
||||
- whats the best
|
||||
- which library
|
||||
- evaluate options
|
||||
---
|
||||
|
||||
# CTX:Researcher Skill
|
||||
|
||||
Efficiently research topics using parallel agents via Contextune's `/ctx:research` command.
|
||||
|
||||
## When to Activate
|
||||
|
||||
This skill should be used when the user:
|
||||
- Explicitly mentions: "research", "investigate", "find information about", "look into"
|
||||
- Asks comparative questions: "what's the best X for Y?", "compare A and B"
|
||||
- Requests library/tool evaluations: "which library should I use?"
|
||||
- Wants to understand solutions: "how do other projects handle X?"
|
||||
|
||||
## What This Skill Does
|
||||
|
||||
When activated, this skill executes the `/ctx:research` command which:
|
||||
|
||||
1. **Spawns 3 parallel Haiku agents** (~$0.07, 1-2 minutes):
|
||||
- **Agent 1**: Web search for similar solutions and implementations
|
||||
- **Agent 2**: Web search for libraries, tools, and frameworks
|
||||
- **Agent 3**: Codebase pattern analysis (existing approaches)
|
||||
|
||||
2. **Returns comprehensive research** including:
|
||||
- Top 3-5 options with pros/cons
|
||||
- Implementation examples
|
||||
- Migration/adoption considerations
|
||||
- Community adoption and maturity
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Execute the Research Command
|
||||
|
||||
```
|
||||
/ctx:research [user's query]
|
||||
```
|
||||
|
||||
**Important**: Pass the user's query verbatim to capture intent.
|
||||
|
||||
### Step 2: Wait for Results
|
||||
|
||||
The command runs in background. You'll receive results from all 3 agents simultaneously.
|
||||
|
||||
### Step 3: Synthesize Findings
|
||||
|
||||
Present results in this structure:
|
||||
|
||||
```markdown
|
||||
## Research Findings: [Topic]
|
||||
|
||||
### Summary
|
||||
[1-2 sentence overview of landscape]
|
||||
|
||||
### Top Options
|
||||
|
||||
#### 1. [Option Name] ⭐ Recommended
|
||||
- **Pros**: [key advantages]
|
||||
- **Cons**: [key drawbacks]
|
||||
- **Best for**: [use cases]
|
||||
- **Adoption**: [community size, maturity]
|
||||
|
||||
#### 2. [Option Name]
|
||||
[same structure]
|
||||
|
||||
#### 3. [Option Name]
|
||||
[same structure]
|
||||
|
||||
### Implementation Examples
|
||||
[Code snippets or links if available]
|
||||
|
||||
### Migration Considerations
|
||||
- [Key steps to adopt]
|
||||
- [Potential challenges]
|
||||
- [Time/effort estimation]
|
||||
|
||||
### Recommendation
|
||||
[Clear recommendation based on user's context]
|
||||
```
|
||||
|
||||
## Example Usage
|
||||
|
||||
**User Query:**
|
||||
```
|
||||
research best React state management libraries
|
||||
```
|
||||
|
||||
**Your Action:**
|
||||
```
|
||||
/ctx:research best React state management libraries 2025
|
||||
```
|
||||
|
||||
**Expected Output After Agents Complete:**
|
||||
```markdown
|
||||
## Research Findings: React State Management (2025)
|
||||
|
||||
### Summary
|
||||
The React state management landscape has matured significantly, with Zustand and Jotai emerging as modern alternatives to Redux, optimized for React 18+ features.
|
||||
|
||||
### Top Options
|
||||
|
||||
#### 1. Zustand ⭐ Recommended
|
||||
- **Pros**:
|
||||
- Minimal boilerplate (~1KB)
|
||||
- TypeScript-first design
|
||||
- No providers needed
|
||||
- React 18 concurrent mode support
|
||||
|
||||
- **Cons**:
|
||||
- Smaller ecosystem than Redux
|
||||
- Less established patterns for large apps
|
||||
|
||||
- **Best for**: New projects, simple-medium complexity, teams wanting minimal setup
|
||||
- **Adoption**: 40K+ GitHub stars, growing rapidly
|
||||
|
||||
#### 2. Jotai
|
||||
- **Pros**:
|
||||
- Atomic state model
|
||||
- Excellent TypeScript inference
|
||||
- Built for React 18
|
||||
|
||||
- **Cons**:
|
||||
- Steeper learning curve (atomic concepts)
|
||||
- Newer, less community content
|
||||
|
||||
- **Best for**: Complex state requirements, fine-grained reactivity
|
||||
- **Adoption**: 15K+ stars, backed by Poimandres team
|
||||
|
||||
#### 3. Redux Toolkit
|
||||
- **Pros**:
|
||||
- Mature, massive ecosystem
|
||||
- Excellent DevTools
|
||||
- Industry standard
|
||||
|
||||
- **Cons**:
|
||||
- More boilerplate
|
||||
- Provider setup required
|
||||
|
||||
- **Best for**: Large teams, existing Redux codebases, need for middleware
|
||||
- **Adoption**: 60K+ stars (core Redux), widely used in enterprise
|
||||
|
||||
### Recommendation
|
||||
|
||||
For your project, I recommend **Zustand** because:
|
||||
- Modern codebase starting fresh
|
||||
- Team values simplicity over complexity
|
||||
- Don't need advanced middleware ecosystem
|
||||
- Want TypeScript-first experience
|
||||
|
||||
Migration from existing useState: ~2-4 hours for typical app.
|
||||
```
|
||||
|
||||
## Integration Notes
|
||||
|
||||
- This skill wraps the `/ctx:research` command for seamless execution
|
||||
- The command is part of the Contextune plugin
|
||||
- Research is grounded in current date (avoids outdated results)
|
||||
- Agents search web + analyze existing codebase patterns
|
||||
|
||||
## Error Handling
|
||||
|
||||
If `/ctx:research` fails:
|
||||
1. Check if Contextune plugin is installed
|
||||
2. Verify user has run `/ctx:configure` for setup
|
||||
3. Fall back to manual web search if needed
|
||||
|
||||
## Tips for Best Results
|
||||
|
||||
- **Be specific**: "React state management 2025" better than just "state management"
|
||||
- **Include context**: "for real-time chat app" helps agents focus
|
||||
- **Specify constraints**: "must be TypeScript-first" filters results
|
||||
- **Current year**: Always include year for technology research (2025)
|
||||
179
skills/software-architect/SKILL.md
Normal file
179
skills/software-architect/SKILL.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
name: ctx:architect
|
||||
description: Systematic architecture analysis following Understand → Research → Specify → Decompose → Plan workflow. Use for system design, solution evaluation, build vs buy decisions, and task decomposition. Activate when users say "design", "architect", "break down", "best approach", or "should I build".
|
||||
keywords:
|
||||
- design
|
||||
- architect
|
||||
- architecture
|
||||
- system design
|
||||
- break down
|
||||
- best approach
|
||||
- should i build
|
||||
- build vs buy
|
||||
- task decomposition
|
||||
- specifications
|
||||
- technical design
|
||||
allowed-tools: []
|
||||
---
|
||||
|
||||
# CTX:Architect - Structured Design Workflow
|
||||
|
||||
Senior architect workflow: Understand → Research → Specify → Decompose → Plan
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### 1. Understand the Problem
|
||||
|
||||
**Extract essentials:**
|
||||
- Core problem (what's the real need?)
|
||||
- Constraints (time, budget, skills, existing systems)
|
||||
- Success criteria (what does "done" look like?)
|
||||
- Assumptions (make implicit explicit)
|
||||
|
||||
**If unclear, ask:**
|
||||
- "What problem does this solve?"
|
||||
- "What systems must it integrate with?"
|
||||
- "Expected scale/volume?"
|
||||
- "Must-haves vs. nice-to-haves?"
|
||||
|
||||
### 2. Research Existing Solutions
|
||||
|
||||
**Use WebSearch to find:**
|
||||
- Existing tools/libraries: `"best [tech] for [problem] 2025"`
|
||||
- Implementation patterns: `"[problem] implementation examples"`
|
||||
- Known challenges: `"[problem] pitfalls"`
|
||||
- Comparisons: `"[tool A] vs [tool B]"`
|
||||
|
||||
**Evaluate each solution:**
|
||||
- Maturity (active? community?)
|
||||
- Fit (solves 80%+?)
|
||||
- Integration (works with stack?)
|
||||
- Cost (license, hosting)
|
||||
- Risk (lock-in, learning curve)
|
||||
|
||||
**Output:** Comparison table with pros/cons
|
||||
|
||||
### 3. Develop Specifications
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
## Problem Statement
|
||||
[1-2 sentences]
|
||||
|
||||
## Requirements
|
||||
- [ ] Functional (High/Med/Low priority)
|
||||
- [ ] Performance (metrics, scale)
|
||||
- [ ] Security (requirements)
|
||||
|
||||
## Constraints
|
||||
- Technical: [stack, systems]
|
||||
- Resources: [time, budget, team]
|
||||
|
||||
## Success Criteria
|
||||
- [Measurable outcomes]
|
||||
```
|
||||
|
||||
**If specs missing, ask:**
|
||||
- Functional: "What must it do?" "Inputs/outputs?" "Edge cases?"
|
||||
- Non-functional: "How many users?" "Response time?" "Uptime?"
|
||||
- Technical: "Current stack?" "Team skills?" "Deployment constraints?"
|
||||
|
||||
### 4. Decompose into Tasks
|
||||
|
||||
**Process:**
|
||||
1. Identify major components
|
||||
2. Break into 1-3 day tasks
|
||||
3. Classify: Independent | Sequential | Parallel-ready
|
||||
4. Map dependencies
|
||||
|
||||
**Dependency mapping:**
|
||||
```
|
||||
Task A (indep) ────┐
|
||||
Task B (indep) ────┼──> Task D (needs A,B,C)
|
||||
Task C (indep) ────┘
|
||||
Task E (needs D) ──> Task F (needs E)
|
||||
```
|
||||
|
||||
**For each task:**
|
||||
- Prerequisites (what must exist first?)
|
||||
- Outputs (what does it produce?)
|
||||
- Downstream (what depends on it?)
|
||||
- Parallelizable? (can run with others?)
|
||||
|
||||
### 5. Create Execution Plan
|
||||
|
||||
**Phase structure:**
|
||||
```
|
||||
## Phase 1: Foundation (Parallel)
|
||||
- [ ] Task A - Infrastructure
|
||||
- [ ] Task B - Data models
|
||||
- [ ] Task C - CI/CD
|
||||
|
||||
## Phase 2: Core (Sequential after Phase 1)
|
||||
- [ ] Task D - Auth (needs A,B)
|
||||
- [ ] Task E - API (needs B)
|
||||
|
||||
## Phase 3: Features (Mixed)
|
||||
- [ ] Task F - Feature 1 (needs D,E)
|
||||
- [ ] Task G - Feature 2 (needs D,E) ← Parallel with F
|
||||
```
|
||||
|
||||
**Per task include:**
|
||||
- Description (what to build)
|
||||
- Dependencies (prerequisites)
|
||||
- Effort (S/M/L)
|
||||
- Owner (who can execute)
|
||||
- Done criteria (how to verify)
|
||||
- Risks (what could fail)
|
||||
|
||||
---
|
||||
|
||||
## Build vs. Buy Decision
|
||||
|
||||
| Factor | Build | Buy |
|
||||
|--------|-------|-----|
|
||||
| Uniqueness | Core differentiator | Common problem |
|
||||
| Fit | Tools don't match | 80%+ match |
|
||||
| Control | Need full control | Standard OK |
|
||||
| Timeline | Have time | Need speed |
|
||||
| Expertise | Team has skills | Steep curve |
|
||||
| Maintenance | Can maintain | Want support |
|
||||
|
||||
**Hybrid:** Buy infrastructure/common features, build differentiation
|
||||
|
||||
---
|
||||
|
||||
## Critical Success Factors
|
||||
|
||||
✅ Research first (don't reinvent)
|
||||
✅ Make dependencies explicit (enable parallel work)
|
||||
✅ Ask direct questions (get clarity fast)
|
||||
✅ Document trade-offs (explain decisions)
|
||||
✅ Think in phases (iterative delivery)
|
||||
✅ Consider team (match to capabilities)
|
||||
|
||||
---
|
||||
|
||||
## Activation Triggers
|
||||
|
||||
- "Design a system for..."
|
||||
- "How should I architect..."
|
||||
- "Break down this project..."
|
||||
- "What's the best approach..."
|
||||
- "Help me plan..."
|
||||
- "Should I build or buy..."
|
||||
|
||||
---
|
||||
|
||||
## Integration with Contextune
|
||||
|
||||
This skill is invoked automatically when Contextune detects `/ctx:design` command.
|
||||
|
||||
**Workflow:**
|
||||
1. User types: "design a caching system"
|
||||
2. Contextune detects: `/ctx:design`
|
||||
3. Hook augments: "You can use your ctx:architect skill..."
|
||||
4. Claude should ask: "I detected this is a design task. Would you like me to use the ctx:architect skill (structured workflow) or proceed directly?"
|
||||
5. User chooses, workflow proceeds
|
||||
|
||||
**Output:** Structured specifications, researched alternatives, executable plan with dependencies
|
||||
Reference in New Issue
Block a user