aidp 0.16.0 → 0.17.1

data/lib/aidp/workflows/guided_agent.rb

@@ -201,79 +201,10 @@ module Aidp
         goal
       end
 
-      def analyze_user_intent(user_goal)
-        display_message("\n🔍 Analyzing your request...", type: :info)
-
-        # Build the system prompt with AIDP capabilities
-        system_prompt = build_system_prompt
-
-        # Build the user prompt
-        user_prompt = build_analysis_prompt(user_goal)
-
-        # Call provider to analyze intent
-        response = call_provider_for_analysis(system_prompt, user_prompt)
-
-        # Parse the response
-        parse_recommendation(response)
-      end
-
-      def build_system_prompt
-        # Try to load from project dir first, fall back to gem's docs
-        capabilities_path = File.join(@project_dir, "docs", "AIDP_CAPABILITIES.md")
-        unless File.exist?(capabilities_path)
-          # Use the gem's copy
-          gem_root = File.expand_path("../../..", __dir__)
-          capabilities_path = File.join(gem_root, "docs", "AIDP_CAPABILITIES.md")
-        end
-
-        capabilities_doc = File.read(capabilities_path)
-
-        <<~PROMPT
-          You are an expert AI assistant helping users select the right AIDP workflow for their needs.
-
-          Your role:
-          1. Understand what the user wants to accomplish
-          2. Match their intent to AIDP's capabilities
-          3. Recommend the most appropriate workflow
-          4. Explain why this workflow fits their needs
-          5. Identify if custom steps or templates are needed
-
-          AIDP Capabilities Reference:
-          #{capabilities_doc}
-
-          Response Format:
-          Provide a JSON response with:
-          {
-            "mode": "analyze|execute|hybrid",
-            "workflow_key": "specific_workflow_key",
-            "reasoning": "brief explanation of why this fits",
-            "additional_steps": ["any", "custom", "steps", "if", "needed"],
-            "questions": ["any", "clarifying", "questions"],
-            "confidence": "high|medium|low"
-          }
-
-          Be concise to preserve the user's context window.
-        PROMPT
-      end
-
-      def build_analysis_prompt(user_goal)
-        <<~PROMPT
-          User Goal: #{user_goal}
-
-          Analyze this goal and recommend the most appropriate AIDP workflow.
-          Consider:
-          - Is this analysis or development?
-          - What level of rigor is needed?
-          - Are there any gaps in existing workflows?
-
-          Provide your recommendation in JSON format.
-        PROMPT
-      end
-
       def call_provider_for_analysis(system_prompt, user_prompt)
         attempts = 0
         max_attempts = (@provider_manager.respond_to?(:configured_providers) ? @provider_manager.configured_providers.size : 2)
-        max_attempts = 2 if max_attempts < 2 # at least one retry if a fallback exists
+        max_attempts = 2 if max_attempts < 2
 
         begin
           attempts += 1
@@ -283,7 +214,6 @@ module Aidp
             raise ConversationError, "No provider configured for guided workflow"
           end
 
-          # Create provider instance using ProviderFactory
           provider_factory = Aidp::Harness::ProviderFactory.new(@config_manager)
           provider = provider_factory.create_provider(provider_name, prompt: @prompt)
 
@@ -292,7 +222,7 @@ module Aidp
           end
 
           combined_prompt = "#{system_prompt}\n\n#{user_prompt}"
-          result = provider.send(prompt: combined_prompt)
+          result = provider.send_message(prompt: combined_prompt)
 
           if result.nil? || result.empty?
             raise ConversationError, "Provider request failed: empty response"
@@ -319,20 +249,6 @@ module Aidp
         end
       end
 
-      def parse_recommendation(response_text)
-        # Extract JSON from response (might be wrapped in markdown code blocks)
-        json_match = response_text.match(/```json\s*(\{.*?\})\s*```/m) ||
-          response_text.match(/(\{.*\})/m)
-
-        unless json_match
-          raise ConversationError, "Could not parse recommendation from response"
-        end
-
-        JSON.parse(json_match[1], symbolize_names: true)
-      rescue JSON::ParserError => e
-        raise ConversationError, "Invalid JSON in recommendation: #{e.message}"
-      end
-
       def validate_provider_configuration!
         configured = @provider_manager.configured_providers
         if configured.nil? || configured.empty?
@@ -349,232 +265,6 @@ module Aidp
         end
       end
 
-      def present_recommendation(recommendation)
-        display_message("\n✨ Recommendation", type: :highlight)
-        display_message("─" * 60, type: :muted)
-
-        mode = recommendation[:mode].to_sym
-        workflow_key = recommendation[:workflow_key].to_sym
-
-        # Get workflow details
-        workflow = Definitions.get_workflow(mode, workflow_key)
-
-        unless workflow
-          # Handle custom workflow or error
-          return handle_custom_workflow(recommendation)
-        end
-
-        # Display the recommendation
-        display_message("Mode: #{mode.to_s.capitalize}", type: :info)
-        display_message("Workflow: #{workflow[:name]}", type: :info)
-        display_message("\n#{workflow[:description]}", type: :muted)
-        display_message("\nReasoning: #{recommendation[:reasoning]}\n", type: :info)
-
-        # Show what's included
-        display_message("This workflow includes:", type: :highlight)
-        workflow[:details].each do |detail|
-          display_message("  • #{detail}", type: :info)
-        end
-
-        # Handle additional steps if needed
-        steps = workflow[:steps]
-        if recommendation[:additional_steps]&.any?
-          display_message("\nAdditional custom steps recommended:", type: :highlight)
-          recommendation[:additional_steps].each do |step|
-            display_message("  • #{step}", type: :info)
-          end
-          steps = workflow[:steps] + recommendation[:additional_steps]
-        end
-
-        # Ask for confirmation
-        display_message("")
-        confirmed = @prompt.yes?("Does this workflow fit your needs?")
-
-        if confirmed
-          {
-            mode: mode,
-            workflow_key: workflow_key,
-            workflow_type: workflow_key,
-            steps: steps,
-            user_input: @user_input,
-            workflow: workflow
-          }
-        else
-          # Offer alternatives
-          offer_alternatives(mode)
-        end
-      end
-
-      def handle_custom_workflow(recommendation)
-        display_message("\n💡 Custom Workflow Needed", type: :highlight)
-        display_message("The AI recommends creating a custom workflow:\n", type: :info)
-        display_message(recommendation[:reasoning], type: :muted)
-
-        if recommendation[:questions]&.any?
-          display_message("\nLet me gather some more information:\n", type: :highlight)
-          recommendation[:questions].each do |question|
-            answer = @prompt.ask(question)
-            @user_input[question.downcase.gsub(/\s+/, "_").to_sym] = answer
-          end
-        end
-
-        # Let user select from available steps
-        mode = recommendation[:mode].to_sym
-        display_message("\nLet's build a custom workflow by selecting specific steps:", type: :info)
-
-        steps = select_custom_steps(mode, recommendation[:additional_steps])
-
-        {
-          mode: mode,
-          workflow_key: :custom,
-          workflow_type: :custom,
-          steps: steps,
-          user_input: @user_input,
-          workflow: {
-            name: "Custom Workflow",
-            description: recommendation[:reasoning],
-            details: steps
-          }
-        }
-      end
-
-      def select_custom_steps(mode, suggested_steps = [])
-        # Get available steps for the mode
-        spec = case mode
-        when :analyze
-          Aidp::Analyze::Steps::SPEC
-        when :execute
-          Aidp::Execute::Steps::SPEC
-        when :hybrid
-          # Combine both
-          Aidp::Analyze::Steps::SPEC.merge(Aidp::Execute::Steps::SPEC)
-        else
-          {}
-        end
-
-        step_choices = spec.map do |step_key, step_spec|
-          {
-            name: "#{step_key} - #{step_spec["description"]}",
-            value: step_key
-          }
-        end
-
-        # Pre-select suggested steps
-        default_indices = suggested_steps.map do |step|
-          step_choices.index { |choice| choice[:value].to_s == step.to_s }
-        end.compact
-
-        selected_steps = @prompt.multi_select(
-          "Select steps for your custom workflow:",
-          step_choices,
-          default: default_indices,
-          per_page: 20
-        )
-
-        selected_steps.empty? ? suggested_steps : selected_steps
-      end
-
-      def offer_alternatives(current_mode)
-        display_message("\n🔄 Let's find a better fit", type: :highlight)
-
-        choices = [
-          {name: "Try a different #{current_mode} workflow", value: :different_workflow},
-          {name: "Switch to a different mode", value: :different_mode},
-          {name: "Build a custom workflow", value: :custom},
-          {name: "Start over", value: :restart}
-        ]
-
-        choice = @prompt.select("What would you like to do?", choices)
-
-        case choice
-        when :different_workflow
-          select_manual_workflow(current_mode)
-        when :different_mode
-          # Let user pick mode manually then workflow
-          new_mode = @prompt.select(
-            "Select mode:",
-            {
-              "🔬 Analyze Mode" => :analyze,
-              "🏗️  Execute Mode" => :execute,
-              "🔀 Hybrid Mode" => :hybrid
-            }
-          )
-          select_manual_workflow(new_mode)
-        when :custom
-          select_custom_steps(current_mode)
-        when :restart
-          select_workflow # Recursive call to start over
-        end
-      end
-
-      def select_manual_workflow(mode)
-        workflows = Definitions.workflows_for_mode(mode)
-
-        choices = workflows.map do |key, workflow|
-          {
-            name: "#{workflow[:icon]} #{workflow[:name]} - #{workflow[:description]}",
-            value: key
-          }
-        end
-
-        selected_key = @prompt.select("Choose a workflow:", choices, per_page: 15)
-        workflow = workflows[selected_key]
-
-        {
-          mode: mode,
-          workflow_key: selected_key,
-          workflow_type: selected_key,
-          steps: workflow[:steps],
-          user_input: @user_input,
-          workflow: workflow
-        }
-      end
-
-      def collect_workflow_details(workflow_selection)
-        # Collect additional information based on mode
-        case workflow_selection[:mode]
-        when :execute
-          collect_execute_details
-        when :analyze
-          # Analyze mode typically doesn't need much user input
-          @user_input[:analysis_goal] = @user_input[:original_goal]
-        when :hybrid
-          collect_execute_details # Hybrid often needs project details
-        end
-
-        # Update the workflow selection with collected input
-        workflow_selection[:user_input] = @user_input
-      end
-
-      def collect_execute_details
-        return if @user_input[:project_description] # Already collected
-
-        display_message("\n📝 Project Information", type: :highlight)
-        display_message("Let me gather some details for the PRD:\n", type: :info)
-
-        @user_input[:project_description] = @prompt.ask(
-          "Describe what you're building (can reference your original goal):",
-          default: @user_input[:original_goal]
-        )
-
-        @user_input[:tech_stack] = @prompt.ask(
-          "Tech stack (e.g., Ruby/Rails, Node.js, Python)? [optional]",
-          required: false
-        )
-
-        @user_input[:target_users] = @prompt.ask(
-          "Who will use this? [optional]",
-          required: false
-        )
-
-        @user_input[:success_criteria] = @prompt.ask(
-          "How will you measure success? [optional]",
-          required: false
-        )
-      end
-
-      # Plan-then-execute helper methods
-
       def build_planning_system_prompt
         <<~PROMPT
           You are a planning assistant helping gather requirements through clarifying questions.

data/lib/aidp/workstream_executor.rb

@@ -25,11 +25,17 @@ module Aidp
       keyword_init: true
     )
 
-    def initialize(project_dir: Dir.pwd, max_concurrent: 3)
+    # @param project_dir [String] root directory of the project
+    # @param max_concurrent [Integer] maximum number of concurrent workstreams (thread pool size)
+    # @param runner_factory [Proc] factory that builds a harness runner. Signature: (path, mode, options) => object responding to #run
+    def initialize(project_dir: Dir.pwd, max_concurrent: 3, runner_factory: nil)
       @project_dir = project_dir
       @max_concurrent = max_concurrent
       @results = Concurrent::Hash.new
       @start_times = Concurrent::Hash.new
+      @runner_factory = runner_factory || lambda do |path, mode, options|
+        Aidp::Harness::Runner.new(path, mode, options)
+      end
     end
 
     # Execute multiple workstreams in parallel
@@ -120,7 +126,7 @@ module Aidp
         Dir.chdir(workstream[:path])
 
         # Execute harness
-        runner = Aidp::Harness::Runner.new(
+        runner = @runner_factory.call(
           workstream[:path],
           options[:mode] || :execute,
           options

data/templates/skills/README.md

@@ -0,0 +1,334 @@
+# AIDP Skills System
+
+## Overview
+
+Skills define **WHO** the agent is (persona, expertise, capabilities), separate from templates/procedures which define **WHAT** task to execute.
+
+This separation allows for:
+
+- Reusable personas across multiple tasks
+- Provider-agnostic skill definitions
+- Clear distinction between agent identity and task execution
+- Easier customization and overriding of agent behaviors
+
+## Skill Structure
+
+Each skill is a directory containing a `SKILL.md` file:
+
+```text
+skills/
+└── repository_analyst/
+    └── SKILL.md
+```
+
+### SKILL.md Format
+
+Skills use YAML frontmatter for metadata and markdown for content:
+
+```markdown
+---
+id: repository_analyst
+name: Repository Analyst
+description: Expert in version control analysis and code evolution patterns
+version: 1.0.0
+expertise:
+  - version control system analysis (Git, SVN, etc.)
+  - code churn analysis and hotspots identification
+keywords:
+  - git
+  - metrics
+  - hotspots
+when_to_use:
+  - Analyzing repository history
+  - Identifying technical debt through metrics
+when_not_to_use:
+  - Writing new code
+  - Debugging runtime issues
+compatible_providers:
+  - anthropic
+  - openai
+  - cursor
+---
+
+# Repository Analyst
+
+You are a **Repository Analyst**, an expert in version control analysis...
+
+## Your Core Capabilities
+
+### Version Control Analysis
+- Analyze commit history...
+
+## Analysis Philosophy
+
+**Data-Driven**: Base all recommendations on actual repository metrics...
+```
+
+## Required Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | String | Unique identifier (lowercase, alphanumeric, underscores only) |
+| `name` | String | Human-readable name |
+| `description` | String | Brief one-line description |
+| `version` | String | Semantic version (X.Y.Z format) |
+
+## Optional Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `expertise` | Array | List of expertise areas |
+| `keywords` | Array | Search/filter keywords |
+| `when_to_use` | Array | Guidance for when to use this skill |
+| `when_not_to_use` | Array | Guidance for when NOT to use this skill |
+| `compatible_providers` | Array | Compatible provider names (empty = all) |
+
+## Skill Locations
+
+### Template Skills
+
+Located in `templates/skills/` in the AIDP gem. These are read-only templates installed with the AIDP gem and cover common use cases; they cannot be modified directly in your project.
+
+- **repository_analyst**: Version control and code evolution analysis
+- **product_strategist**: Product planning and requirements gathering
+- **architecture_analyst**: Architecture analysis and pattern identification
+- **test_analyzer**: Test suite analysis and quality assessment
+
+### Project Skills
+
+Located in `.aidp/skills/` for project-specific skills:
+
+```text
+.aidp/
+└── skills/
+    └── my_custom_skill/
+        └── SKILL.md
+```
+
+Project skills with matching IDs override template skills.
+
+## Using Skills
+
+### In Step Specifications
+
+Reference skills in step specs (e.g., [analyze/steps.rb](lib/aidp/analyze/steps.rb#L6-L60)):
+
+```ruby
+SPEC = {
+  "01_REPOSITORY_ANALYSIS" => {
+    "skill" => "repository_analyst",
+    "templates" => ["analysis/analyze_repository.md"],
+    "description" => "Repository mining",
+    "outs" => ["docs/analysis/repository_analysis.md"],
+    "gate" => false
+  }
+}
+```
+
+### Programmatic Access
+
+```ruby
+# Load skills registry
+registry = Aidp::Skills::Registry.new(project_dir: Dir.pwd)
+registry.load_skills
+
+# Find a skill
+skill = registry.find("repository_analyst")
+
+# Search skills
+matching_skills = registry.search("git")
+
+# Filter by keyword
+analysis_skills = registry.by_keyword("analysis")
+
+# Check provider compatibility
+compatible = registry.compatible_with("anthropic")
+```
+
+### Composing with Templates
+
+Skills are automatically composed with templates by the runner:
+
+```ruby
+# In runner
+skill = skills_registry.find(step_spec["skill"])
+template = File.read(template_path)
+
+# Compose skill + template
+composed_prompt = @skills_composer.compose(
+  skill: skill,
+  template: template,
+  options: { variable: "value" }
+)
+```
+
+The composition structure is:
+
+```text
+1. Skill content (persona, expertise, philosophy)
+2. Separator (---)
+3. "# Current Task" header
+4. Template content (task-specific instructions)
+```
+
+## Configuration
+
+Configure skills in `.aidp/aidp.yml`:
+
+```yaml
+skills:
+  search_paths: []  # Additional skill search paths (optional)
+  default_provider_filter: true  # Filter by provider compatibility
+  enable_custom_skills: true  # Enable custom skill overrides
+```
+
+## Provider Compatibility
+
+Skills can declare compatible providers in frontmatter:
+
+```yaml
+compatible_providers:
+  - anthropic
+  - openai
+```
+
+- Empty list = compatible with all providers
+- Registry filters skills by provider when initialized
+- Incompatible skills are skipped during loading
+
+## Best Practices
+
+### Skill Design
+
+1. **Focus on WHO, not WHAT**: Skills define agent identity, not task steps
+2. **Be specific**: Clearly describe expertise areas and capabilities
+3. **Provide guidance**: Use `when_to_use` and `when_not_to_use` to help with selection
+4. **Version carefully**: Use semantic versioning for tracking changes
+5. **Test compatibility**: Verify skills work with intended providers
+
+### Naming Conventions
+
+- **ID**: `lowercase_with_underscores` (e.g., `repository_analyst`)
+- **Name**: `Title Case` (e.g., `Repository Analyst`)
+- **Files**: Always name the file `SKILL.md` (uppercase)
+
+### Content Guidelines
+
+From the [LLM_STYLE_GUIDE](../docs/LLM_STYLE_GUIDE.md#L1-L202):
+
+- Use clear, professional language
+- Organize with markdown headers
+- Bullet points for lists of capabilities
+- Explain philosophy and approach
+- Provide concrete examples when helpful
+
+## Creating a New Skill
+
+1. **Create directory structure**:
+
+   ```bash
+   mkdir -p skills/my_skill
+   ```
+
+2. **Create SKILL.md**:
+
+   ```bash
+   touch skills/my_skill/SKILL.md
+   ```
+
+3. **Add frontmatter and content**:
+
+   ```markdown
+   ---
+   id: my_skill
+   name: My Skill Name
+   description: Brief description
+   version: 1.0.0
+   expertise:
+     - Area 1
+     - Area 2
+   keywords:
+     - keyword1
+   when_to_use:
+     - Situation 1
+   when_not_to_use:
+     - Situation 2
+   compatible_providers:
+     - anthropic
+   ---
+
+   # My Skill Name
+
+   You are a **My Skill Name**, an expert in...
+   ```
+
+4. **Reference in steps**:
+
+   ```ruby
+   "MY_STEP" => {
+     "skill" => "my_skill",
+     "templates" => ["path/to/template.md"],
+     ...
+   }
+   ```
+
+## Architecture
+
+### Core Components
+
+- **[Skill](lib/aidp/skills/skill.rb#L1-L187)**: Model representing a skill
+- **[Loader](lib/aidp/skills/loader.rb#L1-L179)**: Parses SKILL.md files
+- **[Registry](lib/aidp/skills/registry.rb#L1-L213)**: Manages available skills
+- **[Composer](lib/aidp/skills/composer.rb#L1-L162)**: Combines skills with templates
+
+### Integration Points
+
+- **[Analyze Runner](lib/aidp/analyze/runner.rb#L198-L236)**: Uses skills in analysis mode
+- **[Execute Runner](lib/aidp/execute/runner.rb#L320-L355)**: Uses skills in execution mode
+- **[Config](lib/aidp/config.rb#L166-L170)**: Skills configuration support
+
+## Future Enhancements
+
+Planned for future versions (out of scope for v1):
+
+- **Skill Inheritance**: Skills extending other skills
+- **Skill Composition**: Combining multiple skills for complex tasks
+- **AI-Powered Selection**: Automatically selecting best skill for a task
+- **Skill Marketplace**: Sharing skills across teams/organizations
+- **Dynamic Generation**: Creating skills from examples
+- **Execution Validation**: Checking if output matches skill expectations
+
+## Related Documentation
+
+- [PRD: Skills System](../docs/prd_skills_system.md) - Product requirements and architecture
+- [LLM Style Guide](../docs/LLM_STYLE_GUIDE.md) - Coding standards for skills content
+- [Issue #148](https://github.com/viamin/aidp/issues/148) - Original feature request
+
+## Troubleshooting
+
+### Skill Not Found
+
+If a skill is referenced but not found:
+
+1. Check the skill ID matches exactly (case-sensitive in SPEC, but lowercase in file)
+2. Verify the SKILL.md file exists in the correct directory
+3. Check for YAML syntax errors in frontmatter
+4. Review logs for loading errors
+
+### Provider Compatibility Issues
+
+If skills aren't loading for a provider:
+
+1. Check `compatible_providers` in frontmatter
+2. Verify provider name matches exactly
+3. Check `default_provider_filter` in config
+4. Review registry initialization logs
+
+### Validation Errors
+
+Common validation errors:
+
+- **"id must be lowercase"**: Use only lowercase letters, numbers, underscores
+- **"version must be in format X.Y.Z"**: Use semantic versioning (e.g., "1.0.0")
+- **"YAML frontmatter missing"**: Ensure `---` delimiters are present
+- **Missing required field**: Add required frontmatter fields (id, name, description, version)