aircana 1.5.0 → 2.0.0.rc1

data/lib/aircana/templates/agents/defaults/sub-agent-coordinator.erb

@@ -0,0 +1,90 @@
+---
+name: sub-agent-coordinator
+description: Analyzes questions and coordinates multiple sub-agents to provide comprehensive expert answers by identifying relevant domains and orchestrating parallel consultations
+model: inherit
+color: purple
+---
+
+<%= helpers.model_instructions("You are a Sub-Agent Coordinator responsible for analyzing questions and orchestrating responses from multiple specialized sub-agents to provide comprehensive, expert-level answers.
+
+CORE RESPONSIBILITIES:
+
+1. QUESTION ANALYSIS
+   - Parse and understand the context, domain, and scope of questions
+   - Identify key technical areas, frameworks, and expertise domains involved
+   - Determine the complexity level and breadth of knowledge required
+
+2. AGENT DISCOVERY & SELECTION
+   - Scan available Claude Code sub-agents in the file system
+   - Evaluate each agent's relevance to the question based on their descriptions
+   - Prioritize agents most likely to provide valuable domain-specific insights
+   - Consider both direct expertise and adjacent knowledge areas
+
+3. COORDINATION STRATEGY
+   - Determine optimal consultation approach (parallel vs sequential)
+   - Formulate specific, targeted questions for each relevant sub-agent
+   - Ensure comprehensive coverage while avoiding redundancy
+   - Plan response synthesis methodology
+
+4. RESPONSE ORCHESTRATION
+   - Present clear rationale for agent selection decisions
+   - Provide specific guidance for parallel Task tool invocations
+   - Suggest follow-up questions if initial responses need clarification
+   - Coordinate timing and dependencies between agent consultations
+
+WORKFLOW FOR QUESTION HANDLING:
+
+STEP 1: Question Assessment
+- Analyze the question's technical domains and scope
+- Identify primary and secondary areas of expertise needed
+- Determine if the question requires architectural, implementation, or domain-specific knowledge
+
+STEP 2: Agent Identification
+- List all available sub-agents by scanning the Claude Code configuration
+- Score relevance of each agent (High/Medium/Low) with brief rationale
+- Select 2-5 most relevant agents to avoid information overload
+- Document why specific agents were chosen or excluded
+
+STEP 3: Consultation Planning
+- For each selected agent, craft a specific question or prompt
+- Ensure questions leverage each agent's unique expertise
+- Plan for parallel execution when agents have independent domains
+- Identify any sequential dependencies between agent consultations
+
+STEP 4: Execution Guidance
+- Provide clear instructions for using Task tool with appropriate subagent_types
+- Specify whether consultations should be parallel or sequential
+- Include fallback plans if certain agents are unavailable
+- Suggest timeout considerations for complex queries
+
+STEP 5: Response Synthesis Strategy
+- Outline how responses from different agents should be integrated
+- Identify potential conflicts or contradictions to watch for
+- Suggest approaches for reconciling different expert perspectives
+- Plan for follow-up questions based on initial responses
+
+IMPORTANT GUIDELINES:
+- Always explain your reasoning for agent selection decisions
+- Focus on actionable coordination rather than attempting to answer the question yourself
+- Leverage the collective expertise rather than relying on single sources
+- Provide clear, executable instructions for the coordination process
+- Consider the user's context and technical level when planning consultations
+
+EXAMPLE OUTPUT FORMAT:
+```
+Question Analysis: [Brief analysis of domains and expertise needed]
+
+Selected Agents:
+1. [Agent Name] (High relevance) - [Specific reason and question to ask]
+2. [Agent Name] (Medium relevance) - [Specific reason and question to ask]
+
+Consultation Strategy:
+- Execute agents 1 and 2 in parallel using Task tool
+- Follow up with [specific approach] based on responses
+- Synthesize responses focusing on [key integration points]
+
+Execution Instructions:
+[Specific Task tool invocations and coordination steps]
+```", important: true) %>
+
+Remember: Your role is coordination and orchestration, not direct problem-solving. Your value comes from leveraging the collective knowledge of specialized agents effectively.

data/lib/aircana/templates/commands/ask_expert.erb

@@ -0,0 +1,44 @@
+<%= helpers.model_instructions(
+    "You are coordinating expert consultation to answer a question by leveraging multiple specialized sub-agents. Follow this precise workflow:
+
+STEP 1: QUESTION VALIDATION
+#{$ARGUMENTS.nil? || $ARGUMENTS.empty? ? 'Ask the user: \"What is your question?\" and wait for their response before proceeding.' : "Question to analyze: \"#{$ARGUMENTS}\""}
+
+STEP 2: COORDINATION PHASE
+Use the Task tool with subagent_type 'sub-agent-coordinator' to analyze the question and identify relevant sub-agents. Provide the coordinator with the complete question context.
+
+STEP 3: PARALLEL EXPERT CONSULTATION
+Based on the coordinator's recommendations, use the Task tool to consult each identified relevant sub-agent in parallel. For each agent:
+- Use the appropriate subagent_type for each recommended agent
+- Provide the original question plus any agent-specific context the coordinator suggested
+- Execute multiple Task tool calls in a single message for parallel processing
+
+STEP 4: SYNTHESIS AND RESPONSE
+After receiving responses from all consulted agents:
+- Analyze and synthesize the expert feedback
+- Identify common themes, conflicting viewpoints, and complementary insights
+- Provide a comprehensive answer that leverages the collective expertise
+- Cite which agents contributed specific insights where relevant
+- Note any areas where experts disagreed and provide your assessment
+
+STEP 5: FOLLOW-UP GUIDANCE
+If the question requires further clarification or the expert responses suggest additional considerations:
+- Suggest specific follow-up questions
+- Recommend additional agents to consult if needed
+- Provide guidance on next steps based on the expert consensus
+
+IMPORTANT EXECUTION NOTES:
+- Always start with the sub-agent-coordinator for proper agent selection
+- Use parallel Task tool execution when consulting multiple agents (single message with multiple tool calls)
+- Ensure each agent receives context appropriate to their expertise domain
+- Synthesize responses rather than simply concatenating them
+- Maintain focus on providing actionable, comprehensive answers
+
+EXAMPLE PARALLEL EXECUTION:
+If coordinator recommends agents A, B, and C, send one message with three Task tool calls:
+1. Task(subagent_type='agent-A', prompt='[question + A-specific context]')
+2. Task(subagent_type='agent-B', prompt='[question + B-specific context]')
+3. Task(subagent_type='agent-C', prompt='[question + C-specific context]')
+
+This approach ensures you leverage the full expertise available while maintaining efficient coordination."
+) %>

data/lib/aircana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aircana
-  VERSION = "1.5.0"
+  VERSION = "2.0.0.rc1"
 end

data/lib/aircana.rb

@@ -37,8 +37,6 @@ module Aircana
     def initialize!
       return if @initialized
 
-      create_dir_if_needed(configuration.relevant_project_files_dir)
-
       @initialized = true
     end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: aircana
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0.rc1
 platform: ruby
 authors:
 - Weston Dransfield
 bindir: exe
 cert_chain: []
-date: 2025-09-28 00:00:00.000000000 Z
+date: 2025-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -118,15 +118,11 @@ files:
 - lib/aircana.rb
 - lib/aircana/cli.rb
 - lib/aircana/cli/app.rb
-- lib/aircana/cli/commands/add_directory.rb
-- lib/aircana/cli/commands/add_files.rb
 - lib/aircana/cli/commands/agents.rb
-- lib/aircana/cli/commands/clear_files.rb
 - lib/aircana/cli/commands/doctor.rb
 - lib/aircana/cli/commands/doctor_checks.rb
 - lib/aircana/cli/commands/doctor_helpers.rb
 - lib/aircana/cli/commands/dump_context.rb
-- lib/aircana/cli/commands/files.rb
 - lib/aircana/cli/commands/generate.rb
 - lib/aircana/cli/commands/hooks.rb
 - lib/aircana/cli/commands/install.rb
@@ -142,18 +138,16 @@ files:
 - lib/aircana/contexts/confluence_setup.rb
 - lib/aircana/contexts/local.rb
 - lib/aircana/contexts/manifest.rb
-- lib/aircana/contexts/relevant_files.rb
 - lib/aircana/contexts/web.rb
 - lib/aircana/fzf_helper.rb
 - lib/aircana/generators.rb
 - lib/aircana/generators/agents_generator.rb
+- lib/aircana/generators/ask_expert_command_generator.rb
 - lib/aircana/generators/base_generator.rb
 - lib/aircana/generators/helpers.rb
 - lib/aircana/generators/hooks_generator.rb
 - lib/aircana/generators/plan_command_generator.rb
 - lib/aircana/generators/project_config_generator.rb
-- lib/aircana/generators/relevant_files_command_generator.rb
-- lib/aircana/generators/relevant_files_verbose_results_generator.rb
 - lib/aircana/generators/write_plan_command_generator.rb
 - lib/aircana/human_logger.rb
 - lib/aircana/initializers.rb
@@ -164,7 +158,8 @@ files:
 - lib/aircana/templates/agents/base_agent.erb
 - lib/aircana/templates/agents/defaults/jira.erb
 - lib/aircana/templates/agents/defaults/planner.erb
-- lib/aircana/templates/commands/add_relevant_files.erb
+- lib/aircana/templates/agents/defaults/sub-agent-coordinator.erb
+- lib/aircana/templates/commands/ask_expert.erb
 - lib/aircana/templates/commands/plan.erb
 - lib/aircana/templates/commands/write_plan.erb
 - lib/aircana/templates/hooks/bundle_install.erb
@@ -175,7 +170,6 @@ files:
 - lib/aircana/templates/hooks/rubocop_pre_commit.erb
 - lib/aircana/templates/hooks/session_start.erb
 - lib/aircana/templates/hooks/user_prompt_submit.erb
-- lib/aircana/templates/relevant_files_verbose_results.erb
 - lib/aircana/version.rb
 - sig/aircana.rbs
 homepage: https://github.com/westonkd/aircana

data/lib/aircana/cli/commands/add_directory.rb

@@ -1,148 +0,0 @@
-# frozen_string_literal: true
-
-require "tty-prompt"
-require_relative "../../contexts/relevant_files"
-
-module Aircana
-  module CLI
-    module AddDirectory
-      class << self
-        def run(directory_path)
-          return unless directory_valid?(directory_path)
-
-          selected_files = collect_files_recursively(directory_path)
-          return log_no_files_found(directory_path) if selected_files.empty?
-
-          return unless confirm_large_operation?(selected_files.size, directory_path)
-
-          process_files(directory_path, selected_files)
-        end
-
-        private
-
-        def directory_valid?(directory_path)
-          unless File.directory?(directory_path)
-            Aircana.human_logger.error "Directory not found: #{directory_path}"
-            return false
-          end
-
-          unless File.readable?(directory_path)
-            Aircana.human_logger.error "Directory not readable: #{directory_path}"
-            return false
-          end
-
-          true
-        end
-
-        def log_no_files_found(directory_path)
-          Aircana.human_logger.info "No files found in directory: #{directory_path}"
-        end
-
-        def confirm_large_operation?(file_count, directory_path)
-          return true if file_count <= 50
-
-          show_large_operation_warning(file_count, directory_path)
-          TTY::Prompt.new.yes?("Continue with adding #{file_count} files?")
-        end
-
-        def show_large_operation_warning(file_count, directory_path)
-          estimated_size = estimate_total_size(directory_path, file_count)
-          Aircana.human_logger.warn "Large directory operation detected:"
-          Aircana.human_logger.info "  Directory: #{directory_path}"
-          Aircana.human_logger.info "  Files: #{file_count}"
-          Aircana.human_logger.info "  Estimated size: #{estimated_size}"
-          Aircana.human_logger.warn "  This may result in high token usage with Claude"
-        end
-
-        def estimate_total_size(directory_path, file_count)
-          sample_files = get_sample_files(directory_path, file_count)
-          return "Unknown" if sample_files.empty?
-
-          total_bytes = calculate_sample_size(sample_files)
-          estimated_total = extrapolate_total_size(total_bytes, sample_files.size, file_count)
-          format_file_size(estimated_total)
-        end
-
-        def get_sample_files(directory_path, file_count)
-          Dir.glob(File.join(directory_path, "**", "*"))
-             .reject { |f| File.directory?(f) }
-             .sample([file_count, 10].min)
-        end
-
-        def calculate_sample_size(sample_files)
-          sample_files.sum do |f|
-            File.size(f)
-          rescue StandardError
-            0
-          end
-        end
-
-        def extrapolate_total_size(total_bytes, sample_size, file_count)
-          avg_size = total_bytes / sample_size.to_f
-          (avg_size * file_count).to_i
-        end
-
-        def format_file_size(bytes)
-          units = %w[B KB MB GB]
-          size = bytes.to_f
-          unit_index = 0
-
-          while size >= 1024 && unit_index < units.length - 1
-            size /= 1024
-            unit_index += 1
-          end
-
-          "#{size.round(1)} #{units[unit_index]}"
-        end
-
-        def process_files(directory_path, selected_files)
-          file_count = selected_files.length
-          Aircana.human_logger.info "Found #{file_count} files in directory: #{directory_path}"
-
-          ProgressTracker.with_spinner("Adding #{file_count} files to context") do
-            Contexts::RelevantFiles.add(selected_files)
-          end
-
-          Aircana.human_logger.success "Successfully added #{file_count} files from directory"
-        end
-
-        def log_token_warning(file_count)
-          Aircana.human_logger.warn "Large number of files (#{file_count}) may result in high token usage"
-        end
-
-        def collect_files_recursively(directory_path)
-          Dir.glob(File.join(directory_path, "**", "*"), File::FNM_DOTMATCH)
-             .reject { |path| File.directory?(path) }
-             .reject { |path| should_ignore_file?(path) }
-        end
-
-        def should_ignore_file?(file_path)
-          ignore_patterns.any? { |pattern| file_path.match?(pattern) }
-        end
-
-        def ignore_patterns
-          directory_patterns + file_patterns
-        end
-
-        def directory_patterns
-          [
-            %r{/\.git/}, %r{/node_modules/}, %r{/\.vscode/}, %r{/\.idea/},
-            %r{/coverage/}, %r{/dist/}, %r{/build/}, %r{/tmp/}, %r{/vendor/},
-            %r{/\.bundle/}, %r{/\.rvm/}, %r{/\.rbenv/}
-          ]
-        end
-
-        def file_patterns
-          [
-            %r{/\.DS_Store$}, %r{/log/.*\.log$},
-            /\.(jpg|jpeg|png|gif|bmp|tiff|svg|ico|webp)$/i,
-            /\.(mp4|avi|mkv|mov|wmv|flv|webm)$/i,
-            /\.(mp3|wav|flac|aac|ogg)$/i,
-            /\.(zip|tar|gz|rar|7z|bz2)$/i,
-            /\.(exe|dll|so|dylib)$/i
-          ]
-        end
-      end
-    end
-  end
-end

data/lib/aircana/cli/commands/add_files.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../shell_command"
-require_relative "../../contexts/relevant_files"
-
-module Aircana
-  module CLI
-    module AddFiles
-      class << self
-        def run
-          selected_files = FzfHelper.select_files_interactively(
-            header: "Select files for Claude context (Ctrl+A: select all, ?: toggle preview)"
-          )
-
-          if selected_files.empty?
-            Aircana.human_logger.info "No files selected. Exiting."
-            return
-          end
-
-          Aircana.human_logger.success "Selected #{selected_files.size} files for context"
-          Contexts::RelevantFiles.add(selected_files)
-        end
-      end
-    end
-  end
-end

data/lib/aircana/cli/commands/clear_files.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../shell_command"
-require_relative "../../contexts/relevant_files"
-
-module Aircana
-  module CLI
-    module ClearFiles
-      class << self
-        def run
-          Contexts::RelevantFiles.remove_all
-        end
-      end
-    end
-  end
-end

data/lib/aircana/cli/commands/files.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "add_files"
-require_relative "add_directory"
-require_relative "clear_files"
-require_relative "../../contexts/relevant_files"
-
-module Aircana
-  module CLI
-    module Files
-      class << self
-        def add
-          AddFiles.run
-        end
-
-        def add_dir(directory_path)
-          AddDirectory.run(directory_path)
-        end
-
-        def clear
-          ClearFiles.run
-        end
-
-        def list
-          relevant_files_dir = Aircana.configuration.relevant_project_files_dir
-          return print_no_directory_message unless Dir.exist?(relevant_files_dir)
-
-          files = get_tracked_files(relevant_files_dir)
-          return print_no_files_message if files.empty?
-
-          print_files_list(files)
-        end
-
-        private
-
-        def print_no_directory_message
-          Aircana.human_logger.info(
-            "No relevant files directory found. Use 'aircana files add' to start tracking files."
-          )
-        end
-
-        def print_no_files_message
-          Aircana.human_logger.info("No relevant files currently tracked.")
-        end
-
-        def get_tracked_files(relevant_files_dir)
-          Dir.glob("#{relevant_files_dir}/*").map do |link|
-            File.readlink(link)
-          rescue StandardError
-            link
-          end
-        end
-
-        def print_files_list(files)
-          Aircana.human_logger.info("Current relevant files:")
-          files.each_with_index do |file, index|
-            relative_path = file.start_with?(Dir.pwd) ? file.gsub("#{Dir.pwd}/", "") : file
-            Aircana.human_logger.info("  #{index + 1}. #{relative_path}")
-          end
-          Aircana.human_logger.info("\nTotal: #{files.length} files")
-        end
-      end
-    end
-  end
-end

data/lib/aircana/contexts/relevant_files.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module Aircana
-  module Contexts
-    class RelevantFiles
-      class << self
-        # TODO: Honor the provided verbose flag
-        def print(_verbose: false)
-          verbose_generator(default_stream: true).generate
-        end
-
-        def add(files)
-          files = Array(files)
-
-          return if files.empty?
-
-          Aircana.create_dir_if_needed(Aircana.configuration.relevant_project_files_dir)
-
-          files.each do |file|
-            absolute_file_path = File.expand_path(file)
-            link_path = "#{Aircana.configuration.relevant_project_files_dir}/#{File.basename(file)}"
-
-            FileUtils.rm_f(link_path)
-            File.symlink(absolute_file_path, link_path)
-          end
-
-          rewrite_verbose_file
-        end
-
-        def remove(files)
-          files = Array(files)
-
-          return if files.empty?
-
-          Aircana.create_dir_if_needed(Aircana.configuration.relevant_project_files_dir)
-
-          files.each do |file|
-            link_path = "#{Aircana.configuration.relevant_project_files_dir}/#{File.basename(file)}"
-            FileUtils.rm_f(link_path)
-          end
-
-          rewrite_verbose_file
-        end
-
-        def remove_all
-          return unless directory_exists?
-
-          Dir.glob("#{Aircana.configuration.relevant_project_files_dir}/*").each do |file|
-            FileUtils.rm_f(file)
-          end
-
-          return unless Dir.empty?(Aircana.configuration.relevant_project_files_dir)
-
-          Dir.rmdir(Aircana.configuration.relevant_project_files_dir)
-        end
-
-        private
-
-        def rewrite_verbose_file
-          verbose_generator.generate
-
-          # TODO: If the verbose file uses too many tokens, warn and instead use only
-          # the summary generatior or do something smart like summarize file contents
-        end
-
-        def verbose_generator(default_stream: false)
-          Generators::RelevantFilesVerboseResultsGenerator.new(
-            file_out: default_stream ? Aircana.configuration.stream : nil
-          )
-        end
-
-        def directory_exists?
-          Dir.exist?(Aircana.configuration.relevant_project_files_dir)
-        end
-      end
-    end
-  end
-end

data/lib/aircana/generators/relevant_files_verbose_results_generator.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../generators"
-
-module Aircana
-  module Generators
-    class RelevantFilesVerboseResultsGenerator < BaseGenerator
-      def initialize(file_in: nil, file_out: nil)
-        super(
-          file_in: file_in || default_template_path,
-          file_out: file_out || default_output_path
-        )
-      end
-
-      private
-
-      def locals
-        super.merge({ relevant_files: })
-      end
-
-      def relevant_files
-        Dir.glob("#{Aircana.configuration.relevant_project_files_dir}/*")
-      end
-
-      def default_template_path
-        File.join(File.dirname(__FILE__), "..", "templates", "relevant_files_verbose_results.erb")
-      end
-
-      def default_output_path
-        File.join(Aircana.configuration.relevant_project_files_dir, "relevant_files.md")
-      end
-    end
-  end
-end

data/lib/aircana/templates/commands/add_relevant_files.erb

@@ -1,3 +0,0 @@
-<%= helpers.model_instructions(
-    "Read `#{relevant_project_files_path}`, which contains critical context for the current task."
-) %>

data/lib/aircana/templates/relevant_files_verbose_results.erb

@@ -1,18 +0,0 @@
-# Relevant Files
-<%=
-    helpers.model_instructions(
-        <<~INSTRUCTIONS
-          The following files are considered important for the current task.
-
-          Use them for:
-            - Understanding task context
-            - Examples of how to structure your solutions
-        INSTRUCTIONS
-    )
-%>
-<% relevant_files.each do |file_path| %>
-## File: <%= File.realpath(file_path) %>
-```
-<%= File.read(file_path) %>
-```
-<% end %>