aircana 1.5.0 → 2.0.0.rc1

data/README.md

@@ -1,11 +1,27 @@
 # Aircana
 
-A Ruby CLI utility for context management and Claude Code integration. Aircana helps manage relevant files for development sessions, create specialized Claude Code agents, and optionally sync knowledge from Confluence.
-
 [![Ruby](https://github.com/westonkd/aircana/actions/workflows/main.yml/badge.svg)](https://github.com/westonkd/aircana/actions/workflows/main.yml)
 [![Gem Version](https://badge.fury.io/rb/aircana.svg)](https://badge.fury.io/rb/aircana)
 
-## Installation
+## Intro
+
+Aircana aims to be a "batteries-included" CLI for common needs of Instructure Engineering teams using agents in development. It provides:
+
+Consistent artifact generation and updating of agent, slash command, and hook ERB templates.
+
+Subagent generation for improved context window management.
+
+Agent-accessible knowledge bases sourced from Confluence or public websites, backed by manifest files.
+
+Development workflow with plan, record, and execute phases (record and execute phases are in progress).
+
+SQS integration for features like Slack notifications and messages.
+
+While Aircana includes features beneficial in many agentic contexts (like knowledge base syncing), its primary tools are built on "human-in-the-loop" principles.
+
+## How can I try it?
+
+### Installation
 
 Install the gem:
 
@@ -13,106 +29,108 @@ Install the gem:
 gem install aircana
 ```
 
-Or add to your Gemfile:
+Verify installation and dependency setup:
 
-```ruby
-gem 'aircana'
+```bash
+aircana doctor
 ```
 
-Then run:
+Install Aircana files into your repo:
 
 ```bash
-bundle install
+cd ~/my/repo
+aircana install # This is a no-op if the repo already uses .aircana
 ```
 
-Verify installation and check dependencies:
+### Take it for a spin
+
+If your project previously had Aircana agents set up, run the following to populate each defined agent's knowledge base:
 
 ```bash
-aircana doctor
+aircana agents refresh-all
 ```
 
-## Prerequisites
+To start using your agents with domain-specific knowledge, follow the agent workflow tutorial.
+
+### Things to try
+
+- Configure the Confluence integration and create your own domain-specific subagent
+
+- Launch Claude Code and view the hooks installed by Aircana (prefixed with air). The /air-ask-expert command is pretty handy once you set up some agents with knowledbases.
+
+- Set up the SQS integration to receive Slack messages when Claude Code needs your attention (documentation coming soon).
 
-### Required Dependencies
-- Ruby >= 3.3.0
-- `git` (version control operations)
-- `fzf` (interactive file selection)
+- Explore other tools by running `aircana --help`
 
-### Optional Dependencies
-- `bat` (enhanced file previews, falls back to `cat`)
-- `fd` (faster file searching, falls back to `find`)
+## Key Concepts
 
-### For Confluence Integration (Optional)
-- Access to a Confluence instance
-- Confluence API token
-- Appropriate permissions to read pages and labels
+### Subagents
 
-## Core Concepts
+Subagents are domain-specific agents to whom the primary Claude Code agent can delegate tasks and questions.
 
-Aircana provides two main independent features:
+Each subagent has its own context window. Effectively using subagents can keep the main context window and per-agent context windows smaller for longer, leading to much more usable results and reducing the need to remind agents of core principles and tasks.
 
-### 1. Relevant Files Management
-Track and manage a curated set of "relevant files" - the current working set of important files for your development session. This context is automatically available to Claude Code sessions.
+Claude Code can also run subagents in parallel. A "swarm" of appropriately designed subagents can expedite planning and execution tasks while considering a broader context.
 
-**This works completely independently from agents** - you can use relevant files without creating any agents.
+Aircana allows easy generation of subagents and binds each to an agent-specific knowledge base with documents from Confluence or websites.
 
-### 2. Specialized Agents (Optional)
-Create Claude Code agents with:
-- **Domain Knowledge**: Focused expertise in specific areas
-- **Confluence Integration**: Knowledge sync from labeled pages (requires Confluence setup)
-- **Customizable Models**: Choose from different Claude models and interface colors
+### Knowledge Bases
 
-**Agents work independently from relevant files** - you can create agents without managing relevant files.
+Aircana provides each subagent access to a human-curated knowledge base. This access enables Aircana-managed subagents to yield more relevant results, minimizing back-and-forth between the human operator and the agent.
 
-### Knowledge Sources
-- **Relevant Files**: Current working set managed by Aircana (independent feature)
-- **Confluence Pages**: Fetched based on agent labels (agent feature, requires setup)
-- **Web URLs**: Any web content added to agent knowledge bases (HTML converted to Markdown)
-- **Local Context**: Project-specific files and configurations
+After initial agent creation, Aircana supports refreshing agents' knowledge bases with the latest versions of each source.
 
-## What Aircana Does
+#### Confluence
 
-- **File Context Management**: Track and manage relevant files for Claude Code sessions
-- **Agent Configuration**: Create and configure specialized Claude Code agents
-- **Confluence Integration**: Sync knowledge from Confluence pages to agents (optional)
-- **Claude Code Shortcuts**: Quick-launch Claude Code with pre-configured agents
-- **System Health Checks**: Validate dependencies and configuration
+To add a Confluence page to an agent's knowledge base, label the desired page in Confluence, then run `aircana agent refresh <AGENT>`.
 
-## Quick Start
+Aircana will also pull any Confluence pages labeled with a matching agent name during initial agent creation (`aircana agent create`).
 
-1. **Install and verify**:
-   ```bash
-   gem install aircana
-   aircana doctor
-   ```
+See the Confluence setup guide or run `aircana doctor` for instructions on setting up Confluence integration.
 
-2. **Set up your project**:
-   ```bash
-   cd your-project
-   aircana generate
-   aircana install    # Set up Aircana integration in this project
-   ```
+#### Websites
 
-3. **Add files to context**:
-   ```bash
-   aircana files add    # Interactive selection
-   ```
+In addition to Confluence sources, Aircana allows adding arbitrary public websites to a knowledge base.
 
-   Then in Claude Code, include them whenever you want to reload the files into the current context:
-   ```
-   /add-relevant-files
-   ```
+Websites are also refreshed when `aircana agent refresh <AGENT>` is used.
 
-4. **Create an agent** (optional, but powerful with Confluence):
-   ```bash
-   aircana agents create    # Tag Confluence pages with the agent's name before or after creation to pull that knowledge into the agent's knowledge base. 
-   ```
+#### Structure
 
-5. **View your current context**:
-   ```bash
-   aircana files list     # See all tracked files
-   aircana agents list    # See all configured agents
-   ```
+Knowledge bases are stored in the .aircana directory of each project. For example:
+
+```
+.aircana
+├── agents
+│   ├── canvas-backend-account-expert
+│   │   ├── knowledge
+│   │   │   ├── Accounts.md
+│   │   │   └── Subdomains-&-Request-Routing.md
+│   │   └── manifest.json
+```
+
+Agent files in the .claude/agents directory reference these files.
+
+In many cases, adding the actual knowledge base to version control is undesirable because:
+
+There may be numerous files in the knowledge base, bloating repository size.
+
+Knowledge bases may contain sensitive information that should not be public in an open-source project.
+
+Aircana manages a per-agent manifest.json file to address these concerns.
+
+### Consistent Artifacts
+
+Aircana maintains a set of ERB templates for generating Claude Code agents, hooks, and slash commands consistently.
+
+These templates promote best practices and help new users quickly create effective artifacts without extensive trial and error.
+
+### SQS Integration (Slack Integration at Instructure)
+
+Aircana uses the "Notification" Claude Code hook to send messages to SQS.
+
+At Instructure this means you can easily configure Claude Code to send you slack messages when it needs your attention via Aircana
+
+(Instructions coming soon, send a message if you want help with this)
 
 ## Configuration (Optional)
 
@@ -257,14 +275,6 @@ This refreshes both Confluence pages and web URLs associated with the agent.
 
 ## All Commands
 
-### File Management
-```bash
-aircana files add         # Interactively select files to add to context
-aircana files add-dir [PATH] # Add all files from directory to context
-aircana files clear       # Clear current file context
-aircana files list        # Show current relevant files
-```
-
 ### Agent Management
 ```bash
 aircana agents create     # Create new agent interactively

data/lib/aircana/cli/app.rb

@@ -2,9 +2,6 @@
 
 require "thor"
 
-require_relative "commands/add_files"
-require_relative "commands/add_directory"
-require_relative "commands/clear_files"
 require_relative "commands/doctor"
 require_relative "commands/dump_context"
 require_relative "commands/generate"
@@ -15,7 +12,6 @@ require_relative "help_formatter"
 require_relative "commands/agents"
 require_relative "commands/hooks"
 require_relative "commands/project"
-require_relative "commands/files"
 
 module Aircana
   module CLI
@@ -49,28 +45,6 @@ module Aircana
         Install.run
       end
 
-      class FilesSubcommand < Subcommand
-        desc "add", "Interactively add files to current context"
-        def add
-          Files.add
-        end
-
-        desc "add-dir [DIRECTORY_PATH]", "Add all files from directory to context"
-        def add_dir(directory_path)
-          Files.add_dir(directory_path)
-        end
-
-        desc "clear", "Remove all files from current context"
-        def clear
-          Files.clear
-        end
-
-        desc "list", "Show current relevant files"
-        def list
-          Files.list
-        end
-      end
-
       class AgentsSubcommand < Subcommand
         desc "create", "Create a new agent"
         def create
@@ -91,6 +65,11 @@ module Aircana
         def add_url(agent, url)
           Agents.add_url(agent, url)
         end
+
+        desc "refresh-all", "Refresh knowledge for all configured agents"
+        def refresh_all
+          Agents.refresh_all
+        end
       end
 
       class HooksSubcommand < Subcommand
@@ -147,9 +126,6 @@ module Aircana
         end
       end
 
-      desc "files", "Manage relevant files for context"
-      subcommand "files", FilesSubcommand
-
       desc "agents", "Create and manage agents and their knowledgebases"
       subcommand "agents", AgentsSubcommand
 

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

@@ -101,6 +101,38 @@ module Aircana
           exit 1
         end
 
+        def refresh_all # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          agent_names = all_agents
+
+          if agent_names.empty?
+            Aircana.human_logger.info "No agents found to refresh."
+            return
+          end
+
+          Aircana.human_logger.info "Starting refresh for #{agent_names.size} agent(s)..."
+
+          results = {
+            total: agent_names.size,
+            successful: 0,
+            failed: 0,
+            total_pages: 0,
+            failed_agents: []
+          }
+
+          agent_names.each do |agent_name|
+            result = refresh_single_agent(agent_name)
+            if result[:success]
+              results[:successful] += 1
+              results[:total_pages] += result[:pages_count]
+            else
+              results[:failed] += 1
+              results[:failed_agents] << { name: agent_name, error: result[:error] }
+            end
+          end
+
+          print_refresh_all_summary(results)
+        end
+
         private
 
         def perform_refresh(normalized_agent)
@@ -329,6 +361,52 @@ module Aircana
         def find_available_editor
           %w[code subl atom nano vim vi].find { |cmd| system("which #{cmd} > /dev/null 2>&1") }
         end
+
+        def all_agents
+          agent_dir = Aircana.configuration.agent_knowledge_dir
+          return [] unless Dir.exist?(agent_dir)
+
+          find_agent_folders(agent_dir)
+        end
+
+        def refresh_single_agent(agent_name) # rubocop:disable Metrics/MethodLength
+          Aircana.human_logger.info "Refreshing agent '#{agent_name}'..."
+
+          begin
+            result = perform_manifest_aware_refresh(agent_name)
+            {
+              success: true,
+              pages_count: result[:pages_count],
+              sources: result[:sources]
+            }
+          rescue Aircana::Error => e
+            Aircana.human_logger.error "Failed to refresh agent '#{agent_name}': #{e.message}"
+            {
+              success: false,
+              pages_count: 0,
+              sources: [],
+              error: e.message
+            }
+          end
+        end
+
+        def print_refresh_all_summary(results) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          Aircana.human_logger.info ""
+          Aircana.human_logger.info "=== Refresh All Summary ==="
+          Aircana.human_logger.success "✓ Successful: #{results[:successful]}/#{results[:total]} agents"
+          Aircana.human_logger.success "✓ Total pages refreshed: #{results[:total_pages]}"
+
+          if results[:failed].positive?
+            Aircana.human_logger.error "✗ Failed: #{results[:failed]} agents"
+            Aircana.human_logger.info ""
+            Aircana.human_logger.info "Failed agents:"
+            results[:failed_agents].each do |failed_agent|
+              Aircana.human_logger.error "  - #{failed_agent[:name]}: #{failed_agent[:error]}"
+            end
+          end
+
+          Aircana.human_logger.info ""
+        end
       end
     end
   end

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

@@ -59,7 +59,6 @@ module Aircana
           check_directory("~/.aircana", "Global Aircana directory")
           check_directory(".aircana", "Project Aircana directory")
           check_agents_status
-          check_relevant_files_status
         end
 
         def check_agents_status
@@ -74,17 +73,6 @@ module Aircana
             log_remedy("Create agents with: aircana agents create")
           end
         end
-
-        def check_relevant_files_status
-          relevant_files_dir = File.join(Dir.pwd, ".aircana", "relevant_files")
-          if Dir.exist?(relevant_files_dir) && !Dir.empty?(relevant_files_dir)
-            file_count = Dir.glob(File.join(relevant_files_dir, "*")).size
-            log_success("relevant_files", "#{file_count} file(s) in context")
-          else
-            log_info("relevant_files", "No relevant files added yet")
-            log_remedy("Add files with: aircana add-files")
-          end
-        end
       end
 
       module OptionalIntegrations

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

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "../shell_command"
-require_relative "../../contexts/relevant_files"
 
 module Aircana
   module CLI
     module DumpContext
       class << self
-        def run(_agent_name:, verbose: true)
+        def run(_agent_name:, _verbose: true)
           Aircana.logger.level = Logger::ERROR
-          Contexts::RelevantFiles.print(verbose:)
+          Aircana.human_logger.info("Context dumping functionality has been removed.")
         end
 
         private

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

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "../../generators/relevant_files_command_generator"
-require_relative "../../generators/relevant_files_verbose_results_generator"
 require_relative "../../generators/plan_command_generator"
 require_relative "../../generators/write_plan_command_generator"
+require_relative "../../generators/ask_expert_command_generator"
 require_relative "../../generators/agents_generator"
 require_relative "../../generators/hooks_generator"
 require_relative "../../generators/project_config_generator"
@@ -14,10 +13,9 @@ module Aircana
       class << self
         def generators
           @generators ||= [
-            Aircana::Generators::RelevantFilesVerboseResultsGenerator.new,
-            Aircana::Generators::RelevantFilesCommandGenerator.new,
             Aircana::Generators::PlanCommandGenerator.new,
-            Aircana::Generators::WritePlanCommandGenerator.new
+            Aircana::Generators::WritePlanCommandGenerator.new,
+            Aircana::Generators::AskExpertCommandGenerator.new
           ]
         end
 

data/lib/aircana/configuration.rb

@@ -2,7 +2,7 @@
 
 module Aircana
   class Configuration
-    attr_accessor :global_dir, :project_dir, :relevant_project_files_dir, :stream, :output_dir,
+    attr_accessor :global_dir, :project_dir, :stream, :output_dir,
                   :claude_code_config_path, :claude_code_project_config_path, :agent_knowledge_dir,
                   :hooks_dir, :confluence_base_url, :confluence_username, :confluence_api_token
 
@@ -18,7 +18,6 @@ module Aircana
     def setup_directory_paths
       @global_dir = File.join(Dir.home, ".aircana")
       @project_dir = Dir.pwd
-      @relevant_project_files_dir = File.join(@project_dir, ".aircana", "relevant_files")
       @output_dir = File.join(@global_dir, "aircana.out")
       @agent_knowledge_dir = File.join(@project_dir, ".aircana", "agents")
       @hooks_dir = File.join(@project_dir, ".aircana", "hooks")

data/lib/aircana/contexts/confluence.rb

@@ -98,9 +98,7 @@ module Aircana
 
       def extract_page_metadata(page)
         {
-          "id" => page["id"],
-          "title" => page["title"],
-          "last_updated" => page.dig("version", "when") || Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+          "id" => page["id"]
         }
       end
 

data/lib/aircana/contexts/manifest.rb

@@ -27,10 +27,7 @@ module Aircana
 
           if File.exist?(manifest_path)
             existing_data = JSON.parse(File.read(manifest_path))
-            manifest_data = existing_data.merge({
-                                                  "last_updated" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
-                                                  "sources" => sources
-                                                })
+            manifest_data = existing_data.merge({ "sources" => sources })
           else
             manifest_data = build_manifest_data(agent, sources)
           end
@@ -87,13 +84,9 @@ module Aircana
         end
 
         def build_manifest_data(agent, sources)
-          timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
-
           {
             "version" => "1.0",
             "agent" => agent,
-            "created" => timestamp,
-            "last_updated" => timestamp,
             "sources" => sources
           }
         end
@@ -157,8 +150,6 @@ module Aircana
           raise ManifestError, "Each URL entry must be a hash" unless url_entry.is_a?(Hash)
 
           raise ManifestError, "URL entry missing required field: url" unless url_entry.key?("url")
-
-          raise ManifestError, "URL entry missing required field: title" unless url_entry.key?("title")
         end
       end
     end

data/lib/aircana/contexts/web.rb

@@ -210,9 +210,7 @@ module Aircana
 
       def build_url_metadata(page_data)
         {
-          "url" => page_data[:url],
-          "title" => page_data[:title],
-          "last_fetched" => page_data[:last_fetched]
+          "url" => page_data[:url]
         }
       end
 

data/lib/aircana/generators/agents_generator.rb

@@ -7,7 +7,7 @@ module Aircana
     class AgentsGenerator < BaseGenerator
       attr_reader :agent_name, :short_description, :description, :model, :color, :default_agent
 
-      AVAILABLE_DEFAULT_AGENTS = %w[planner jira].freeze
+      AVAILABLE_DEFAULT_AGENTS = %w[planner jira sub-agent-coordinator].freeze
 
       class << self
         def create_default_agent(agent_name)
@@ -44,7 +44,7 @@ module Aircana
 
       def locals
         super.merge({
-                      relevant_project_files_path:, agent_name:, short_description:, description:,
+                      agent_name:, short_description:, description:,
                       model:, color:, knowledge_path:
                     })
       end
@@ -63,10 +63,6 @@ module Aircana
         File.join(Aircana.configuration.claude_code_project_config_path, "agents", "#{agent_name}.md")
       end
 
-      def relevant_project_files_path
-        File.join(Aircana.configuration.relevant_project_files_dir, "relevant_files.md")
-      end
-
       def knowledge_path
         ".aircana/agents/#{agent_name}/knowledge/"
       end

data/lib/aircana/generators/{relevant_files_command_generator.rb → ask_expert_command_generator.rb}

@@ -4,7 +4,7 @@ require_relative "../generators"
 
 module Aircana
   module Generators
-    class RelevantFilesCommandGenerator < BaseGenerator
+    class AskExpertCommandGenerator < BaseGenerator
       def initialize(file_in: nil, file_out: nil)
         super(
           file_in: file_in || default_template_path,
@@ -12,24 +12,14 @@ module Aircana
         )
       end
 
-      protected
-
-      def locals
-        super.merge({ relevant_project_files_path: })
-      end
-
       private
 
       def default_template_path
-        File.join(File.dirname(__FILE__), "..", "templates", "commands", "add_relevant_files.erb")
+        File.join(File.dirname(__FILE__), "..", "templates", "commands", "ask_expert.erb")
       end
 
       def default_output_path
-        File.join(Aircana.configuration.output_dir, "commands", "air-add-relevant-files.md")
-      end
-
-      def relevant_project_files_path
-        File.join(Aircana.configuration.relevant_project_files_dir, "relevant_files.md")
+        File.join(Aircana.configuration.output_dir, "commands", "air-ask-expert.md")
       end
     end
   end

data/lib/aircana/generators.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "generators/base_generator"
-require_relative "generators/relevant_files_command_generator"
-require_relative "generators/relevant_files_verbose_results_generator"
 
 module Aircana
   module Generators