claudify-agent 0.0.0-stage → 1.0.0

package/.claude/skills/parallel-exploration/SKILL.md

@@ -0,0 +1,193 @@
+# SKILL.md: Parallel Exploration
+
+## Description
+Automatically launch multiple subagents in parallel for broad codebase exploration, reducing discovery time by 60-70%.
+
+## When to Use
+- Complex feature implementation (>5 files)
+- Large refactors
+- Bug investigation (root cause unknown)
+- New codebase unfamiliarity
+- Multi-part tasks
+
+## Automatic Triggers
+
+**Launch parallel subagents when**:
+- User request mentions >3 different areas
+- Task complexity: High (requires >10 steps)
+- Codebase unfamiliarity detected
+- Investigation phase taking >5 minutes
+
+## Parallel Exploration Patterns
+
+### Pattern 1: Feature Implementation
+
+```
+User: "Add user dashboard"
+
+Parallel Subagents (model="fast", run_in_background=true):
+1. "Find dashboard-like pages and layouts"
+2. "Find API route patterns for data fetching"
+3. "Find component structures for widgets"
+4. "Find existing chart/visualization libraries"
+
+Duration: 60s parallel (vs 240s sequential)
+Output: Consolidated findings → Plan creation
+```
+
+### Pattern 2: Bug Investigation
+
+```
+User: "Checkout randomly fails"
+
+Parallel Subagents:
+1. "Find checkout flow code (UI → API → DB)"
+2. "Find error handling in payment processing"
+3. "Find recent changes to checkout files"
+4. "Find similar issues/fixes in codebase"
+
+Duration: 90s parallel
+Output: Root cause hypothesis + fix locations
+```
+
+### Pattern 3: Large Refactor
+
+```
+User: "Migrate from JWT to sessions"
+
+Parallel Subagents:
+1. "Find all JWT validation code"
+2. "Find all token generation code"
+3. "Find all authentication middleware"
+4. "Find all tests using JWT"
+
+Duration: 120s parallel
+Output: Complete migration map + risk assessment
+```
+
+## Subagent Configuration
+
+```typescript
+// Optimal configuration for parallel exploration
+Task:
+  description="Explore [specific area]"
+  prompt="Find [specific pattern/code] in [target directory]"
+  subagent_type="explore"
+  model="fast"  // Cost optimization
+  readonly=true  // Safety
+  run_in_background=true  // Non-blocking
+```
+
+## Cost Optimization
+
+**Subagent Cost Hierarchy**:
+```
+explore (fast model): $ (Use for discovery)
+generalPurpose (fast): $$ (Use for analysis)
+generalPurpose (capable): $$$ (Use for complex reasoning)
+browser-use: $$$$ (Use only when browser needed)
+```
+
+**Mandatory Cost Rules**:
+1. **ALWAYS** use `model="fast"` for exploration subagents (90% of cases)
+2. **ONLY** use capable model for:
+   - Complex reasoning tasks
+   - Multi-step analysis
+   - Security-critical reviews
+3. **DOCUMENT** model choice in plan (justify if not "fast")
+4. Use `readonly=true` unless modification needed
+5. Use `run_in_background=true` for non-blocking
+6. Limit to 4 parallel subagents max (diminishing returns)
+7. Time-box to 120s max per subagent
+
+**Cost Impact**: Using `model="fast"` reduces exploration costs by 50-70%
+
+## Consolidation Strategy
+
+**After parallel exploration completes**:
+
+1. **Aggregate findings** from all subagents
+2. **Identify overlaps** (multiple agents found same thing)
+3. **Resolve conflicts** (contradictory findings)
+4. **Create unified map** of codebase areas
+5. **Generate plan** using consolidated knowledge
+
+**Example Consolidation**:
+```markdown
+## Exploration Results (4 subagents, 60s parallel)
+
+### Consensus Findings (found by multiple agents)
+- Page structure: `app/[feature]/page.tsx` pattern
+- API routes: `app/api/[resource]/route.ts`
+- Components: `components/[feature]/` directory
+
+### Unique Findings
+- Agent 1: Found layout pattern in `app/layout.tsx`
+- Agent 2: Found data fetching in `lib/fetcher.ts`
+- Agent 3: Found component examples in `components/`
+- Agent 4: Found chart library: Recharts in use
+
+### Next Steps
+- Follow `@app/profile/page.tsx` for page structure
+- Use `@lib/fetcher.ts` for API calls
+- Reference `@components/Card.tsx` for component pattern
+```
+
+## Examples
+
+### Example 1: New Feature
+
+User: "Add activity feed to user profile"
+
+Automatic parallel exploration:
+```
+Subagent 1: "Find profile page structure"
+Subagent 2: "Find feed/activity patterns"
+Subagent 3: "Find API patterns for real-time data"
+Subagent 4: "Find websocket/pubsub usage"
+
+Result: Complete implementation map in 60s
+```
+
+### Example 2: Complex Bug
+
+User: "User sessions expire prematurely"
+
+Automatic parallel exploration:
+```
+Subagent 1: "Find session management code"
+Subagent 2: "Find session expiration logic"
+Subagent 3: "Find recent changes to auth files"
+Subagent 4: "Find session-related tests"
+
+Result: Root cause identified in 90s
+```
+
+### Example 3: Large Refactor
+
+User: "Migrate from REST to GraphQL"
+
+Automatic parallel exploration:
+```
+Subagent 1: "Find all REST API calls"
+Subagent 2: "Find data fetching patterns"
+Subagent 3: "Find existing GraphQL usage"
+Subagent 4: "Find mutation operations"
+
+Result: Complete migration strategy in 120s
+```
+
+## Anti-Patterns
+
+❌ **Don't**:
+- Launch >4 parallel subagents (chaos)
+- Use capable model for simple exploration (waste)
+- Run subagents sequentially (defeats purpose)
+- Forget to consolidate findings (confusion)
+
+✅ **Do**:
+- Use `model="fast"` for exploration
+- Launch 2-4 subagents in parallel
+- Time-box to 120s max
+- Consolidate findings before planning
+- Reference specific files found

package/.claude/skills/plan-mode-mastery/SKILL.md

@@ -0,0 +1,263 @@
+# SKILL.md: Plan Mode Mastery
+
+## Description
+Comprehensive plan mode workflow with automatic research, validation, and execution monitoring.
+
+## When to Use
+- User requests Plan Mode
+- Large feature implementation
+- Complex refactoring
+- Ambiguous requirements
+- Multi-step tasks
+
+## Capabilities
+- Automatic pre-plan research
+- Tool-aware plan creation
+- Feasibility validation
+- Progress monitoring
+- Adaptive re-planning
+- Iteration loops
+
+## Commands
+/plan-mode-full: Complete optimized workflow
+/plan-mode-quick: Standard plan mode (no research)
+/plan-mode-validate: Validate existing plan
+
+## Workflows
+
+### Full Plan Mode Workflow
+
+1. **Pre-Plan Research** (2-3 minutes)
+   - SemanticSearch for patterns
+   - Parallel subagent exploration
+   - ReadLints check
+   - AskQuestion (batch) if needed
+
+2. **Plan Creation** (1-2 minutes)
+   - Enhanced structure with tools
+   - Risk assessment
+   - Checkpoint strategy
+   - Time estimation
+
+3. **Plan Validation** (1 minute)
+   - Feasibility subagent
+   - Tool availability check
+   - Dependency analysis
+
+4. **Execution Monitoring**
+   - TodoWrite tracking
+   - Automatic checkpoints
+   - Iteration loops
+   - Adaptive re-planning
+
+## Tool Integration
+
+### Research Phase Tools
+- **SemanticSearch**: Find existing patterns
+- **Task (explore)**: Parallel codebase exploration
+- **ReadLints**: Check code health
+- **AskQuestion**: Batch clarifications
+
+### Planning Phase Tools
+- **CreatePlan**: Structured plan creation
+- **TodoWrite**: Progress tracking setup
+- **Checkpoints**: Strategic rollback points
+
+### Execution Phase Tools
+- **Read/Write/StrReplace**: Implementation
+- **Shell**: Run tests and commands
+- **ReadLints**: Quality validation
+- **Task (subagents)**: Parallel work
+
+### Monitoring Tools
+- **TodoWrite**: Real-time progress
+- **/grind**: Iteration loops
+- **AskQuestion**: Blocker resolution
+
+## Examples
+
+### Example 1: Feature Implementation
+
+User: "Add user dashboard"
+
+Agent invokes /plan-mode-full:
+
+**Research Phase**:
+- SemanticSearch: "How are pages structured?"
+- Task (parallel):
+  - "Find dashboard-like features"
+  - "Find API route patterns"
+  - "Find component patterns"
+- ReadLints: Check current health
+- AskQuestion: "Which widgets for MVP?" (batched)
+
+**Plan Phase**:
+Creates enhanced plan with:
+- Files to create/modify with patterns
+- Tool strategy for each step
+- Risk mitigation (checkpoint before API changes)
+- Time estimate: 45 minutes
+
+**Validation Phase**:
+- Task: "Validate plan feasibility"
+- Check: All files accessible
+- Verify: Tool availability
+- Result: PASS
+
+**Execution Phase**:
+- TodoWrite: Track 7 steps
+- Checkpoint: Before API changes
+- /grind loop: Fix test failures
+- Progress updates: After each step
+
+### Example 2: Complex Refactor
+
+User: "Refactor authentication system"
+
+**Research Phase**:
+- SemanticSearch: "How is auth implemented?"
+- Task (parallel x4):
+  - "Find JWT validation logic"
+  - "Find session management"
+  - "Find OAuth integrations"
+  - "Find password hashing"
+- ReadLints: Check all auth files
+- AskQuestion: "Target auth method?"
+
+**Plan Phase**:
+- Summary: Migrate from JWT to sessions
+- Files: 8 files to modify
+- Steps: 12 steps with checkpoints
+- Risks: Breaking change, data migration
+- Time: 3 hours
+
+**Validation Phase**:
+- Task: Validate complexity
+- Warning: High risk, suggest phased approach
+- Result: PASS with warnings
+
+**Execution Phase**:
+- TodoWrite: 12 steps tracked
+- Checkpoints: 3 (before breaking changes)
+- Adaptive re-plan: Discovered legacy code
+- /grind: Fixed auth edge cases
+
+### Example 3: Bug Fix
+
+User: "Fix authentication bug #123"
+
+**Research Phase**:
+- SemanticSearch: "How does auth flow work?"
+- Task: "Investigate bug #123"
+- ReadLints: Check auth files
+- Result: Token expiration issue found
+
+**Plan Phase**:
+- Summary: Fix JWT expiration handling
+- Files: 2 files to modify
+- Steps: 4 steps
+- Time: 20 minutes
+
+**Validation Phase**:
+- Quick validation (simple fix)
+- Result: PASS
+
+**Execution Phase**:
+- TodoWrite: 4 steps
+- StrReplace: Fix expiration logic
+- Shell: Run auth tests
+- ReadLints: Verify quality
+- Complete: Bug fixed
+
+## Best Practices
+
+### 1. Always Research First
+- Never plan blind
+- Spend 2-3 min on research
+- Find patterns before coding
+- Ask questions in batches
+
+### 2. Validate Before Presenting
+- Use validation subagent
+- Check file accessibility
+- Verify time estimates
+- Flag risks explicitly
+
+### 3. Track Progress Religiously
+- Update todos immediately
+- One task in_progress at a time
+- Create checkpoints strategically
+- Report blockers early
+
+### 4. Iterate When Stuck
+- Use /grind for tests (max 5 iterations)
+- Update scratchpad
+- AskQuestion if blocked
+- Re-plan if >30% deviation
+
+### 5. Time-Box Research
+- Max 3 minutes for research
+- "Good enough" threshold
+- Progressive disclosure
+- Optimize for speed
+
+## Anti-Patterns
+
+### ❌ Planning Without Research
+Bad: "I'll create a plan immediately"
+Good: "Let me research existing patterns first"
+
+### ❌ Vague Plans
+Bad: "Implement authentication"
+Good: "Add JWT validation to /api/login following @src/auth/validateToken.ts pattern"
+
+### ❌ No Validation
+Bad: Present plan without checking
+Good: Validate feasibility before presenting
+
+### ❌ Skipping Progress Tracking
+Bad: Work without updating todos
+Good: Update TodoWrite after each step
+
+### ❌ No Checkpoints
+Bad: Risky changes without rollback
+Good: Checkpoint before breaking changes
+
+## Troubleshooting
+
+### Research Taking Too Long
+**Problem**: >5 minutes in research phase
+
+**Solutions**:
+- Time-box to 3 minutes max
+- Use model="fast" for subagents
+- Narrow target_directories
+- Accept "good enough" patterns
+
+### Validation Failing Repeatedly
+**Problem**: Plan fails validation multiple times
+
+**Solutions**:
+- Simplify the plan
+- Break into smaller phases
+- Add more fallback strategies
+- Revise time estimates
+
+### Tests Not Passing
+**Problem**: /grind loop failing after 5 iterations
+
+**Solutions**:
+- Report BLOCKED with details
+- AskQuestion for guidance
+- Re-plan approach
+- Check for missing dependencies
+
+### Plan Deviation
+**Problem**: Execution diverging >30% from plan
+
+**Solutions**:
+- Pause immediately
+- Create checkpoint
+- Assess what changed
+- Present updated plan
+- Get approval before continuing