ccsetup 1.1.1 → 1.2.0

package/template/docs/ROADMAP.md

@@ -4,42 +4,6 @@
 
 High-level overview of the project, what it does, the main features
 
-## Development Workflow
-
-1. **Task Planning**
-   - Study the existing codebase and understand the current state
-   - Use the **planner** agent to break down complex problems and create implementation roadmaps
-   - Create a plan document in the `/plans` directory for complex features
-   - Update `ROADMAP.md` to include the new task under Development
-   - Priority tasks should be inserted after the last completed task
-
-2. **Ticket Creation**
-   - Study the existing codebase and understand the current state
-   - Create a new ticket file in the `/tickets` directory
-   - Name format: `TICKET-XXX-description.md` (e.g., `TICKET-001-user-auth.md`)
-   - Include high-level specifications, relevant files, acceptance criteria, and implementation steps
-   - Refer to last completed ticket in the `/tickets` directory for examples
-   - Note that completed tickets show checked boxes and summary of changes
-   - For new tickets, use empty checkboxes and no summary section
-
-3. **Task Implementation**
-   - Use the **coder** agent for implementing features, fixing bugs, and optimizing code
-   - Follow the specifications in the ticket file
-   - Implement features and functionality following project conventions
-   - Update step progress within the ticket file after each step
-   - Stop after completing each step and wait for further instructions
-
-4. **Quality Assurance**
-   - Use the **checker** agent for testing, security analysis, and code review
-   - Verify all acceptance criteria are met
-   - Run tests and ensure code quality standards
-   - Document any issues found and their resolutions
-
-5. **Roadmap Updates**
-   - Mark completed tasks with ✅ in the roadmap
-   - Add reference to the ticket file (e.g., `See: /tickets/TICKET-001-user-auth.md`)
-   - Update related plan documents if applicable
-
 ## Development
 
 ### Project Setup and Boilerplate

package/template/docs/agent-orchestration.md

@@ -1,152 +1,35 @@
-# Agent Orchestration Guide
+# Agent Orchestration
 
-## Overview
-This document defines the standard workflows for orchestrating multiple agents in Claude Code to complete complex tasks efficiently. Follow these patterns to ensure consistent and thorough task execution.
+Standard workflows for chaining agents on complex tasks. Always end with **Checker**.
 
-## Core Agent Workflows
+## Workflows
 
-### 1. Feature Development Workflow
-**Purpose**: Implement new features from conception to completion
+### Feature Development
+researcher → planner → coder → checker
 
-**Flow**:
-1. **Researcher Agent** → Gather requirements and understand existing codebase
-2. **Planner Agent** → Create detailed implementation plan and architecture
-3. **Coder Agent** → Implement the feature following the plan
-4. **Checker Agent** → Test, review, and validate the implementation
+### Bug Fix
+researcher → coder → checker
 
-**Example Prompt**:
-```
-"I need to add user authentication to the app. First use the researcher agent to understand the current architecture, then the planner to design the auth system, coder to implement it, and checker to validate."
-```
+### Refactoring
+researcher → planner → coder → checker
 
-### 2. Bug Fix Workflow
-**Purpose**: Systematically identify and fix bugs
+### API Development
+planner → backend → frontend (optional) → checker
 
-**Flow**:
-1. **Researcher Agent** → Investigate the bug and find root cause
-2. **Coder Agent** → Implement the fix
-3. **Checker Agent** → Verify fix and check for regressions
+### UI Component
+frontend → shadcn (if React) → checker
 
-### 3. Refactoring Workflow
-**Purpose**: Improve code quality without changing functionality
+### Blockchain
+planner → blockchain → checker
 
-**Flow**:
-1. **Researcher Agent** → Analyze current implementation and identify improvements
-2. **Planner Agent** → Design refactoring approach
-3. **Coder Agent** → Execute refactoring
-4. **Checker Agent** → Ensure functionality remains intact
+### QA
+researcher → checker → coder (fix issues) → checker
 
-### 4. API Development Workflow
-**Purpose**: Design and implement APIs
+## Rules
 
-**Flow**:
-1. **Planner Agent** → Design API architecture and endpoints
-2. **Backend Agent** → Implement server-side logic
-3. **Frontend Agent** → Create client integration (if needed)
-4. **Checker Agent** → Test API functionality and security
-
-### 5. UI Component Workflow
-**Purpose**: Create user interface components
-
-**Flow**:
-1. **Frontend Agent** → Design and implement UI components
-2. **Shadcn Agent** → Apply shadcn/ui styling (if using React)
-3. **Checker Agent** → Test accessibility and responsiveness
-
-### 6. Blockchain Development Workflow
-**Purpose**: Develop Web3 features and smart contracts
-
-**Flow**:
-1. **Planner Agent** → Design smart contract architecture
-2. **Blockchain Agent** → Implement contracts and Web3 integration
-3. **Checker Agent** → Security audit and testing
-
-## Orchestration Best Practices
-
-### 1. Always Start with Understanding
-- Use Researcher Agent first for non-trivial tasks
-- Understand existing code before making changes
-- Document findings in plans directory
-
-### 2. Plan Before Implementation
-- Use Planner Agent for complex features
-- Create detailed plans in `/plans` directory
-- Break down large tasks into smaller tickets
-
-### 3. Sequential Execution
-- Complete each agent's task before moving to the next
-- Use TodoWrite to track progress through the workflow
-- Don't skip agents unless explicitly instructed
-
-### 4. Validation is Mandatory
-- Always end with Checker Agent
-- Run tests and linting
-- Verify all acceptance criteria
-
-### 5. Documentation Updates
-- Update ROADMAP.md after completing workflows
-- Mark tickets as complete with summaries
-- Keep plans updated with outcomes
-
-## Workflow Triggers
-
-### When to use Feature Development Workflow:
-- Adding new functionality
-- Implementing user stories
-- Creating new modules or services
-
-### When to use Bug Fix Workflow:
-- Fixing reported issues
-- Addressing error messages
-- Resolving unexpected behavior
-
-### When to use Refactoring Workflow:
-- Improving code readability
-- Optimizing performance
-- Updating deprecated code
-
-### When to use API Development Workflow:
-- Creating new endpoints
-- Designing service interfaces
-- Building integrations
-
-### When to use UI Component Workflow:
-- Building new UI elements
-- Updating existing interfaces
-- Implementing design changes
-
-### When to use Blockchain Workflow:
-- Smart contract development
-- DeFi integrations
-- Web3 features
-
-## Example Multi-Agent Execution
-
-```
-User: "I need to add a payment processing feature"
-
-Claude's Response Flow:
-1. "I'll help you add payment processing. Let me start by using the researcher agent to understand your current architecture and any existing payment-related code."
-   [Uses Researcher Agent]
-
-2. "Based on my research, I'll now use the planner agent to design the payment processing system."
-   [Uses Planner Agent, creates plan in /plans]
-
-3. "With the plan ready, I'll use the backend agent to implement the server-side payment processing."
-   [Uses Backend Agent]
-
-4. "Now I'll use the frontend agent to create the payment UI components."
-   [Uses Frontend Agent]
-
-5. "Finally, let me use the checker agent to verify the implementation and ensure security."
-   [Uses Checker Agent]
-```
-
-## Workflow Customization
-
-You can create custom workflows by:
-1. Combining agents in different sequences
-2. Adding conditional paths based on findings
-3. Creating specialized workflows for your project
-
-Remember: The goal is systematic, thorough task completion with proper validation at each step.
+1. Use **Researcher** first for non-trivial tasks
+2. Use **Planner** before implementing complex features
+3. Execute agents sequentially — complete each step before the next
+4. Always finish with **Checker** for validation
+5. Track progress with TodoWrite
+6. Update ROADMAP.md and tickets after completing workflows

package/template/hooks/workflow-selector/index.js

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Environment variable toggle — exit early if not enabled
+// Enable with: export CCSETUP_WORKFLOW=1
+const enabled = process.env.CCSETUP_WORKFLOW;
+if (!enabled || (enabled !== '1' && enabled.toLowerCase() !== 'true')) {
+  console.log('{}');
+  process.exit(0);
+}
+
+// Simple workflow selector that reads from agent-orchestration.md
+class WorkflowSelector {
+  constructor() {
+    this.workflows = this.loadWorkflows();
+    this.availableAgents = this.getAvailableAgents();
+  }
+
+  loadWorkflows() {
+    const orchestrationPath = path.join(process.cwd(), 'docs', 'agent-orchestration.md');
+    
+    if (!fs.existsSync(orchestrationPath)) {
+      return this.getDefaultWorkflows();
+    }
+
+    try {
+      // First try to use Claude to extract workflows intelligently
+      const workflows = this.loadWorkflowsWithClaude(orchestrationPath);
+      if (workflows && Object.keys(workflows).length > 0) {
+        return workflows;
+      }
+    } catch (error) {
+      // Claude extraction failed, continue with regex
+    }
+
+    // Fallback to regex-based extraction
+    return this.loadWorkflowsWithRegex(orchestrationPath);
+  }
+
+  loadWorkflowsWithClaude(orchestrationPath) {
+    const { execSync } = require('child_process');
+    
+    try {
+      const content = fs.readFileSync(orchestrationPath, 'utf8');
+      
+      const extractPrompt = `
+Extract all workflows from this agent orchestration document.
+
+For each workflow, identify:
+1. The workflow name
+2. The sequence of agents used
+3. The purpose/description
+
+Return ONLY a JSON object with this structure:
+{
+  "workflow_key": {
+    "name": "Workflow Name",
+    "agents": ["agent1", "agent2", "agent3"],
+    "purpose": "Brief description"
+  }
+}
+
+Document content:
+${content}
+
+Extract all workflows and return valid JSON only.
+`;
+
+      const claudeResult = execSync(
+        `claude --print "${extractPrompt.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`,
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'], maxBuffer: 1024 * 1024 * 10 }
+      );
+
+      // Parse the JSON result
+      const parsed = JSON.parse(claudeResult);
+      
+      // Validate and normalize the workflows
+      const workflows = {};
+      for (const [key, workflow] of Object.entries(parsed)) {
+        if (workflow.name && Array.isArray(workflow.agents) && workflow.agents.length > 0) {
+          // Normalize agent names (remove "agent" suffix, lowercase)
+          const normalizedAgents = workflow.agents.map(agent => 
+            agent.toLowerCase().replace(/\s*agent\s*$/, '').trim()
+          );
+          
+          workflows[key] = {
+            name: workflow.name,
+            agents: normalizedAgents,
+            purpose: workflow.purpose || ''
+          };
+        }
+      }
+      
+      return workflows;
+    } catch (error) {
+      // Claude extraction failed
+      return null;
+    }
+  }
+
+  loadWorkflowsWithRegex(orchestrationPath) {
+    try {
+      const content = fs.readFileSync(orchestrationPath, 'utf8');
+      const workflows = {};
+      
+      // Enhanced regex patterns for better extraction
+      const workflowSections = this.extractWorkflowSections(content);
+      
+      for (const section of workflowSections) {
+        const workflow = this.parseWorkflowSection(section);
+        if (workflow) {
+          const key = workflow.name.toLowerCase().replace(/\s+/g, '_');
+          workflows[key] = workflow;
+        }
+      }
+      
+      // If no workflows found, return defaults
+      return Object.keys(workflows).length > 0 ? workflows : this.getDefaultWorkflows();
+    } catch (error) {
+      return this.getDefaultWorkflows();
+    }
+  }
+
+  extractWorkflowSections(content) {
+    const sections = [];
+    
+    // Split by workflow headers
+    const workflowRegex = /### \d+\.\s+(.+?)\s+Workflow([\s\S]*?)(?=### \d+\.|## |$)/g;
+    let match;
+    
+    while ((match = workflowRegex.exec(content)) !== null) {
+      sections.push({
+        name: match[1].trim(),
+        content: match[2].trim()
+      });
+    }
+    
+    return sections;
+  }
+
+  parseWorkflowSection(section) {
+    const workflow = {
+      name: section.name,
+      agents: []
+    };
+    
+    // Look for the Flow section
+    const flowMatch = section.content.match(/\*\*Flow\*\*:?\s*([\s\S]*?)(?=\*\*|###|$)/);
+    if (!flowMatch) return null;
+    
+    const flowContent = flowMatch[1];
+    
+    // Extract agents from various formats
+    const agents = this.extractAgentsFromFlow(flowContent);
+    
+    if (agents.length > 0) {
+      workflow.agents = agents;
+      return workflow;
+    }
+    
+    return null;
+  }
+
+  extractAgentsFromFlow(flowContent) {
+    const agents = [];
+    const lines = flowContent.split('\n');
+    
+    for (const line of lines) {
+      // Pattern 1: "1. **Agent Name** → Description"
+      let match = line.match(/^\d+\.\s*\*\*([^*→]+?)(?:\s+Agent)?\*\*/);
+      
+      // Pattern 2: "- Agent Name: Description"
+      if (!match) {
+        match = line.match(/^[-•]\s*\*\*([^*:]+?)(?:\s+Agent)?\*\*/);
+      }
+      
+      // Pattern 3: "Agent Name →"
+      if (!match) {
+        match = line.match(/^\s*([A-Za-z\s]+?)\s*(?:Agent\s*)?→/);
+      }
+      
+      if (match) {
+        const agent = match[1].toLowerCase()
+          .replace(/\s*agent\s*$/, '')
+          .trim();
+        
+        if (agent && !agents.includes(agent) && agent.length > 0) {
+          agents.push(agent);
+        }
+      }
+    }
+    
+    return agents;
+  }
+
+  getDefaultWorkflows() {
+    return {
+      feature_development: {
+        name: 'Feature Development',
+        agents: ['researcher', 'planner', 'coder', 'checker']
+      },
+      bug_fix: {
+        name: 'Bug Fix',
+        agents: ['researcher', 'coder', 'checker']
+      },
+      refactoring: {
+        name: 'Refactoring',
+        agents: ['researcher', 'planner', 'coder', 'checker']
+      },
+      api_development: {
+        name: 'API Development',
+        agents: ['planner', 'backend', 'frontend', 'checker']
+      },
+      ui_component: {
+        name: 'UI Component',
+        agents: ['frontend', 'shadcn', 'checker']
+      },
+      blockchain: {
+        name: 'Blockchain Development',
+        agents: ['planner', 'blockchain', 'checker']
+      },
+      qa: {
+        name: 'QA',
+        agents: ['researcher', 'checker', 'coder', 'checker']
+      }
+    };
+  }
+
+  getAvailableAgents() {
+    const agentsDir = path.join(process.cwd(), '.claude', 'agents');
+    
+    if (!fs.existsSync(agentsDir)) {
+      return [];
+    }
+    
+    try {
+      return fs.readdirSync(agentsDir)
+        .filter(file => file.endsWith('.md'))
+        .map(file => file.replace('.md', '').toLowerCase());
+    } catch (error) {
+      return [];
+    }
+  }
+
+  async selectWorkflow(prompt) {
+    const { execSync } = require('child_process');
+    
+    try {
+      // First, let's use Claude to analyze the prompt and understand the task type
+      const analyzePrompt = `
+Analyze this user prompt and determine the most appropriate workflow type.
+User prompt: "${prompt}"
+
+Available workflows:
+${Object.entries(this.workflows).map(([key, workflow]) => 
+  `- ${workflow.name}: uses agents [${workflow.agents.join(', ')}]`
+).join('\n')}
+
+Consider:
+1. What type of task is this? (feature, bug fix, refactoring, API work, UI work, testing, etc.)
+2. What agents would be most helpful?
+3. Match to the most appropriate workflow
+
+Respond with ONLY the workflow key (e.g., 'feature_development', 'bug_fix', etc.)
+`;
+
+      // Use Claude to analyze the prompt
+      const claudeAnalysis = execSync(
+        `claude --print "${analyzePrompt.replace(/"/g, '\\"')}"`,
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }
+      ).trim().toLowerCase().replace(/['"]/g, '');
+
+      // Validate the response is a valid workflow key
+      if (this.workflows[claudeAnalysis]) {
+        return this.workflows[claudeAnalysis];
+      }
+
+      // If Claude's response isn't valid, fall back to enhanced keyword matching
+      return this.enhancedKeywordMatching(prompt);
+      
+    } catch (error) {
+      // If Claude command fails, fall back to enhanced keyword matching
+      console.error('Claude analysis failed, using keyword matching:', error.message);
+      return this.enhancedKeywordMatching(prompt);
+    }
+  }
+
+  enhancedKeywordMatching(prompt) {
+    const promptLower = prompt.toLowerCase();
+    
+    // Score each workflow based on keyword matches
+    const scores = {};
+    
+    // Define keyword weights for each workflow
+    const workflowKeywords = {
+      bug_fix: {
+        keywords: ['fix', 'bug', 'error', 'issue', 'broken', 'crash', 'fail', 'debug', 'problem', 'wrong'],
+        weight: 2
+      },
+      refactoring: {
+        keywords: ['refactor', 'improve', 'optimize', 'clean', 'restructure', 'reorganize', 'simplify', 'enhance'],
+        weight: 2
+      },
+      api_development: {
+        keywords: ['api', 'endpoint', 'rest', 'graphql', 'backend', 'server', 'route', 'request', 'response'],
+        weight: 2
+      },
+      ui_component: {
+        keywords: ['ui', 'component', 'frontend', 'react', 'vue', 'interface', 'button', 'form', 'page', 'view'],
+        weight: 2
+      },
+      qa: {
+        keywords: ['test', 'qa', 'quality', 'testing', 'unit', 'integration', 'e2e', 'coverage', 'assert'],
+        weight: 2
+      },
+      feature_development: {
+        keywords: ['add', 'create', 'implement', 'build', 'develop', 'feature', 'new', 'functionality'],
+        weight: 1
+      },
+      blockchain: {
+        keywords: ['blockchain', 'smart contract', 'web3', 'ethereum', 'solidity', 'defi', 'crypto', 'wallet'],
+        weight: 3
+      }
+    };
+    
+    // Calculate scores for each workflow
+    Object.entries(workflowKeywords).forEach(([workflow, config]) => {
+      scores[workflow] = 0;
+      config.keywords.forEach(keyword => {
+        if (promptLower.includes(keyword)) {
+          scores[workflow] += config.weight;
+        }
+      });
+    });
+    
+    // Find the workflow with the highest score
+    let bestWorkflow = 'feature_development';
+    let highestScore = 0;
+    
+    Object.entries(scores).forEach(([workflow, score]) => {
+      if (score > highestScore && this.workflows[workflow]) {
+        highestScore = score;
+        bestWorkflow = workflow;
+      }
+    });
+    
+    return this.workflows[bestWorkflow] || this.workflows.feature_development || Object.values(this.workflows)[0];
+  }
+
+  filterAgentsByAvailability(agents) {
+    if (this.availableAgents.length === 0) {
+      return agents; // Return all if we can't check
+    }
+    
+    return agents.filter(agent => this.availableAgents.includes(agent));
+  }
+}
+
+// Main execution - reads from stdin as Claude Code provides
+if (require.main === module) {
+  let inputData = '';
+  
+  process.stdin.on('data', (chunk) => {
+    inputData += chunk;
+  });
+  
+  process.stdin.on('end', async () => {
+    try {
+      const input = JSON.parse(inputData);
+      const prompt = input.prompt || '';
+      
+      if (!prompt) {
+        console.log('{}');
+        return;
+      }
+      
+      const selector = new WorkflowSelector();
+      const workflow = await selector.selectWorkflow(prompt);
+      const agents = selector.filterAgentsByAvailability(workflow.agents);
+      
+      // Output suggestion — Claude should ask the user before applying
+      const output = {
+        workflow: workflow.name,
+        agents: agents,
+        message: `[Workflow Suggestion] Based on this prompt, the "${workflow.name}" workflow may be a good fit: ${agents.join(' → ')}. Ask the user if they'd like to follow this workflow or just proceed normally with Claude Code's default behavior.`
+      };
+
+      console.log(JSON.stringify(output));
+    } catch (error) {
+      // Silent fail - just return empty
+      console.log('{}');
+    }
+  });
+}
+
+module.exports = WorkflowSelector;