aircana 3.2.1 → 4.0.0.rc1

data/lib/aircana/configuration.rb

@@ -5,9 +5,9 @@ require "json"
 module Aircana
   class Configuration
     attr_accessor :global_dir, :project_dir, :stream, :output_dir,
-                  :claude_code_config_path, :claude_code_project_config_path, :agent_knowledge_dir,
+                  :claude_code_config_path, :claude_code_project_config_path, :kb_knowledge_dir,
                   :hooks_dir, :scripts_dir, :confluence_base_url, :confluence_username, :confluence_api_token,
-                  :plugin_root, :plugin_manifest_dir, :commands_dir, :agents_dir, :global_agents_dir
+                  :plugin_root, :plugin_manifest_dir, :commands_dir, :skills_dir
 
     def initialize
       setup_directory_paths
@@ -48,30 +48,17 @@ module Aircana
       File.basename(@plugin_root).downcase.gsub(/[^a-z0-9]+/, "-")
     end
 
-    # Returns the global knowledge directory path for an agent (runtime location)
-    # Format: ~/.claude/agents/<plugin-name>-<agent-name>/knowledge/
-    # Both local and remote agents use this path at runtime
-    def global_agent_knowledge_path(agent_name)
-      File.join(@global_agents_dir, "#{plugin_name}-#{agent_name}", "knowledge")
+    # Returns the knowledge directory path for a KB
+    # Format: .claude/skills/<kb-name>/
+    # All knowledge files stored directly in the skill directory
+    def kb_path(kb_name)
+      File.join(@skills_dir, kb_name)
     end
 
-    # Returns the local knowledge directory path for an agent (version-controlled source)
-    # Format: <plugin-root>/agents/<agent-name>/knowledge/
-    # Used only for local agents as the source that gets synced to global path
-    def local_agent_knowledge_path(agent_name)
-      File.join(@agents_dir, agent_name, "knowledge")
-    end
-
-    # Returns the appropriate knowledge directory path based on kb_type
-    # For runtime access, both local and remote agents use global_agent_knowledge_path
-    # Local agents are synced there via SessionStart hook from their version-controlled source
-    # kb_type can be "remote" or "local" but is not used (kept for backward compatibility)
-    def agent_knowledge_path(agent_name, _kb_type = nil)
-      # Both types use the global path at runtime
-      # The difference is how the content gets there:
-      # - Remote: via 'aircana agents refresh' from Confluence/web
-      # - Local: via SessionStart hook from version-controlled agents/<name>/knowledge/
-      global_agent_knowledge_path(agent_name)
+    # Returns the knowledge directory for a specific KB (same as kb_path for now)
+    # Kept for API compatibility during refactoring
+    def kb_knowledge_path(kb_name)
+      kb_path(kb_name)
     end
 
     private
@@ -88,18 +75,16 @@ module Aircana
       @plugin_root = ENV.fetch("AIRCANA_PLUGIN_ROOT", ENV.fetch("CLAUDE_PLUGIN_ROOT", @project_dir))
       @plugin_manifest_dir = File.join(@plugin_root, ".claude-plugin")
       @commands_dir = File.join(@plugin_root, "commands")
-      @agents_dir = File.join(@plugin_root, "agents")
+      @skills_dir = File.join(@plugin_root, ".claude", "skills")
       @hooks_dir = File.join(@plugin_root, "hooks")
       @scripts_dir = File.join(@plugin_root, "scripts")
-      @agent_knowledge_dir = File.join(@plugin_root, "agents")
+      @kb_knowledge_dir = @skills_dir
     end
 
     def setup_claude_code_paths
       @claude_code_config_path = File.join(Dir.home, ".claude")
       # For backward compatibility, keep this but plugin mode uses plugin_root
       @claude_code_project_config_path = File.join(Dir.pwd, ".claude")
-      # Global agents directory for knowledge bases (not version controlled)
-      @global_agents_dir = File.join(Dir.home, ".claude", "agents")
     end
 
     def setup_stream

data/lib/aircana/contexts/confluence.rb

@@ -24,22 +24,23 @@ module Aircana
         @local_storage = Local.new
       end
 
-      def fetch_pages_for(agent:, kb_type: "remote")
+      def fetch_pages_for(kb_name:, kb_type: "local", label: nil)
         validate_configuration!
         setup_httparty
 
-        pages = search_and_log_pages(agent)
+        label_to_search = label || kb_name
+        pages = search_and_log_pages(label_to_search)
         return { pages_count: 0, sources: [] } if pages.empty?
 
-        sources = process_pages_with_manifest(pages, agent, kb_type)
-        create_or_update_manifest(agent, sources, kb_type)
+        sources = process_pages_with_manifest(pages, kb_name, kb_type)
+        create_or_update_manifest(kb_name, sources, kb_type)
 
         { pages_count: pages.size, sources: sources }
       end
 
-      def refresh_from_manifest(agent:)
-        sources = Manifest.sources_from_manifest(agent)
-        kb_type = Manifest.kb_type_from_manifest(agent)
+      def refresh_from_manifest(kb_name:)
+        sources = Manifest.sources_from_manifest(kb_name)
+        kb_type = Manifest.kb_type_from_manifest(kb_name)
         return { pages_count: 0, sources: [] } if sources.empty?
 
         validate_configuration!
@@ -56,34 +57,34 @@ module Aircana
 
         return { pages_count: 0, sources: [] } if all_pages.empty?
 
-        updated_sources = process_pages_with_manifest(all_pages, agent, kb_type)
+        updated_sources = process_pages_with_manifest(all_pages, kb_name, kb_type)
 
         { pages_count: all_pages.size, sources: updated_sources }
       end
 
-      def search_and_log_pages(agent)
-        pages = ProgressTracker.with_spinner("Searching for pages labeled '#{agent}'") do
-          fetch_pages_by_label(agent)
+      def search_and_log_pages(label)
+        pages = ProgressTracker.with_spinner("Searching for pages labeled '#{label}'") do
+          fetch_pages_by_label(label)
         end
-        log_pages_found(pages.size, agent)
+        log_pages_found(pages.size, label)
         pages
       end
 
-      def process_pages(pages, agent, kb_type = "remote")
+      def process_pages(pages, kb_name, kb_type = "local")
         ProgressTracker.with_batch_progress(pages, "Processing pages") do |page, _index|
-          store_page_as_markdown(page, agent, kb_type)
+          store_page_as_markdown(page, kb_name, kb_type)
         end
       end
 
-      def process_pages_with_manifest(pages, agent, kb_type = "remote")
+      def process_pages_with_manifest(pages, kb_name, kb_type = "local")
         page_metadata = []
 
         ProgressTracker.with_batch_progress(pages, "Processing pages") do |page, _index|
-          store_page_as_markdown(page, agent, kb_type)
+          store_page_as_markdown(page, kb_name, kb_type)
           page_metadata << extract_page_metadata(page)
         end
 
-        build_source_metadata(agent, page_metadata)
+        build_source_metadata(kb_name, page_metadata)
       end
 
       private
@@ -98,26 +99,56 @@ module Aircana
       end
 
       def extract_page_metadata(page)
+        content = page&.dig("body", "storage", "value") || ""
+        markdown_content = convert_to_markdown(content)
+        summary = generate_summary(markdown_content, page["title"] || "Confluence page")
+
         {
-          "id" => page["id"]
+          "id" => page["id"],
+          "summary" => summary
         }
       end
 
-      def build_source_metadata(agent, page_metadata)
+      def generate_summary(content, title)
+        prompt = build_summary_prompt(content, title)
+        LLM::ClaudeClient.new.prompt(prompt).strip
+      rescue StandardError => e
+        Aircana.human_logger.warn("Failed to generate summary: #{e.message}")
+        # Fallback to title or truncated content
+        title || "#{content[0..80].gsub(/\s+/, " ").strip}..."
+      end
+
+      def build_summary_prompt(content, title)
+        truncated_content = content.length > 2000 ? "#{content[0..2000]}..." : content
+
+        <<~PROMPT
+          Generate a concise 8-12 word summary of the following documentation.
+          Title: #{title}
+
+          Content:
+          #{truncated_content}
+
+          The summary should describe what information this document contains in a way that helps
+          someone understand when they should read it. Focus on the key topics covered.
+
+          Respond with only the summary text, no additional explanation or formatting.
+        PROMPT
+      end
+
+      def build_source_metadata(_kb_name, page_metadata)
         [
           {
             "type" => "confluence",
-            "label" => agent,
             "pages" => page_metadata
           }
         ]
       end
 
-      def create_or_update_manifest(agent, sources, kb_type = "remote")
-        if Manifest.manifest_exists?(agent)
-          Manifest.update_manifest(agent, sources, kb_type: kb_type)
+      def create_or_update_manifest(kb_name, sources, kb_type = "local")
+        if Manifest.manifest_exists?(kb_name)
+          Manifest.update_manifest(kb_name, sources, kb_type: kb_type)
         else
-          Manifest.create_manifest(agent, sources, kb_type: kb_type)
+          Manifest.create_manifest(kb_name, sources, kb_type: kb_type)
         end
       end
 

data/lib/aircana/contexts/confluence_content.rb

@@ -17,18 +17,18 @@ module Aircana
         ReverseMarkdown.convert(html_content, github_flavored: true)
       end
 
-      def log_pages_found(count, agent)
-        Aircana.human_logger.info "Found #{count} pages for agent '#{agent}'"
+      def log_pages_found(count, kb_name)
+        Aircana.human_logger.info "Found #{count} pages for KB '#{kb_name}'"
       end
 
-      def store_page_as_markdown(page, agent, kb_type = "remote")
+      def store_page_as_markdown(page, kb_name, kb_type = "local")
         content = page&.dig("body", "storage", "value") || fetch_page_content(page&.[]("id"))
         markdown_content = convert_to_markdown(content)
 
         @local_storage.store_content(
           title: page&.[]("title"),
           content: markdown_content,
-          agent: agent,
+          kb_name: kb_name,
           kb_type: kb_type
         )
       end

data/lib/aircana/contexts/local.rb

@@ -5,27 +5,26 @@ require "fileutils"
 module Aircana
   module Contexts
     class Local
-      def store_content(title:, content:, agent:, kb_type: "remote")
-        agent_dir = create_agent_knowledge_dir(agent, kb_type)
+      def store_content(title:, content:, kb_name:, kb_type: "local") # rubocop:disable Lint/UnusedMethodArgument
+        kb_dir = create_kb_dir(kb_name)
         filename = sanitize_filename(title)
-        filepath = File.join(agent_dir, "#{filename}.md")
+        filepath = File.join(kb_dir, "#{filename}.md")
 
         File.write(filepath, content)
-        Aircana.human_logger.success "Stored '#{title}' for agent '#{agent}' at #{filepath}"
+        Aircana.human_logger.success "Stored '#{title}' for KB '#{kb_name}' at #{filepath}"
 
         filepath
       end
 
       private
 
-      def create_agent_knowledge_dir(agent, kb_type = "remote")
+      def create_kb_dir(kb_name)
         config = Aircana.configuration
-        # Route to appropriate directory based on kb_type
-        agent_dir = config.agent_knowledge_path(agent, kb_type)
+        kb_dir = config.kb_knowledge_path(kb_name)
 
-        FileUtils.mkdir_p(agent_dir)
+        FileUtils.mkdir_p(kb_dir)
 
-        agent_dir
+        kb_dir
       end
 
       def sanitize_filename(title)

data/lib/aircana/contexts/manifest.rb

@@ -7,33 +7,33 @@ module Aircana
   module Contexts
     class Manifest
       class << self
-        def create_manifest(agent, sources, kb_type: "remote")
+        def create_manifest(kb_name, sources, kb_type: "local")
           validate_sources(sources)
           validate_kb_type(kb_type)
 
-          manifest_path = manifest_path_for(agent)
-          manifest_data = build_manifest_data(agent, sources, kb_type)
+          manifest_path = manifest_path_for(kb_name)
+          manifest_data = build_manifest_data(kb_name, sources, kb_type)
 
           FileUtils.mkdir_p(File.dirname(manifest_path))
           File.write(manifest_path, JSON.pretty_generate(manifest_data))
 
-          Aircana.human_logger.info "Created knowledge manifest for agent '#{agent}' (kb_type: #{kb_type})"
+          Aircana.human_logger.info "Created knowledge manifest for '#{kb_name}' (kb_type: #{kb_type})"
           manifest_path
         end
 
-        def update_manifest(agent, sources, kb_type: nil)
+        def update_manifest(kb_name, sources, kb_type: nil)
           validate_sources(sources)
 
-          manifest_path = manifest_path_for(agent)
+          manifest_path = manifest_path_for(kb_name)
 
           if File.exist?(manifest_path)
             existing_data = JSON.parse(File.read(manifest_path))
             # Preserve existing kb_type unless explicitly provided
-            kb_type_to_use = kb_type || existing_data["kb_type"] || "remote"
+            kb_type_to_use = kb_type || existing_data["kb_type"] || "local"
             manifest_data = existing_data.merge({ "sources" => sources, "kb_type" => kb_type_to_use })
           else
-            kb_type_to_use = kb_type || "remote"
-            manifest_data = build_manifest_data(agent, sources, kb_type_to_use)
+            kb_type_to_use = kb_type || "local"
+            manifest_data = build_manifest_data(kb_name, sources, kb_type_to_use)
           end
 
           validate_kb_type(manifest_data["kb_type"])
@@ -42,8 +42,8 @@ module Aircana
           manifest_path
         end
 
-        def read_manifest(agent)
-          manifest_path = manifest_path_for(agent)
+        def read_manifest(kb_name)
+          manifest_path = manifest_path_for(kb_name)
           return nil unless File.exist?(manifest_path)
 
           begin
@@ -51,54 +51,54 @@ module Aircana
             validate_manifest(manifest_data)
             manifest_data
           rescue JSON::ParserError => e
-            Aircana.human_logger.warn "Invalid manifest for agent '#{agent}': #{e.message}"
+            Aircana.human_logger.warn "Invalid manifest for KB '#{kb_name}': #{e.message}"
             nil
           rescue ManifestError => e
-            Aircana.human_logger.warn "Manifest validation failed for agent '#{agent}': #{e.message}"
+            Aircana.human_logger.warn "Manifest validation failed for KB '#{kb_name}': #{e.message}"
             nil
           end
         end
 
-        def sources_from_manifest(agent)
-          manifest = read_manifest(agent)
+        def sources_from_manifest(kb_name)
+          manifest = read_manifest(kb_name)
           return [] unless manifest
 
           manifest["sources"] || []
         end
 
-        def kb_type_from_manifest(agent)
-          manifest = read_manifest(agent)
-          return "remote" unless manifest
+        def kb_type_from_manifest(kb_name)
+          manifest = read_manifest(kb_name)
+          return "local" unless manifest
 
-          manifest["kb_type"] || "remote"
+          manifest["kb_type"] || "local"
         end
 
-        def manifest_exists?(agent)
-          File.exist?(manifest_path_for(agent))
+        def manifest_exists?(kb_name)
+          File.exist?(manifest_path_for(kb_name))
         end
 
         private
 
-        def manifest_path_for(agent)
-          resolved_agent_path = resolve_agent_path(agent)
-          File.join(resolved_agent_path, "manifest.json")
+        def manifest_path_for(kb_name)
+          resolved_kb_path = resolve_kb_path(kb_name)
+          File.join(resolved_kb_path, "manifest.json")
         end
 
-        def resolve_agent_path(agent)
-          File.join(Aircana.configuration.agent_knowledge_dir, agent)
+        def resolve_kb_path(kb_name)
+          File.join(Aircana.configuration.kb_knowledge_dir, kb_name)
         end
 
-        def build_manifest_data(agent, sources, kb_type = "remote")
+        def build_manifest_data(kb_name, sources, kb_type = "local")
           {
             "version" => "1.0",
-            "agent" => agent,
+            "name" => kb_name,
             "kb_type" => kb_type,
             "sources" => sources
           }
         end
 
         def validate_manifest(manifest_data)
-          required_fields = %w[version agent sources]
+          required_fields = %w[version name sources]
 
           required_fields.each do |field|
             raise ManifestError, "Missing required field: #{field}" unless manifest_data.key?(field)
@@ -108,8 +108,8 @@ module Aircana
             raise ManifestError, "Unsupported manifest version: #{manifest_data["version"]}"
           end
 
-          # kb_type is optional for backward compatibility, defaults to "remote"
-          kb_type = manifest_data["kb_type"] || "remote"
+          # kb_type is optional for backward compatibility, defaults to "local"
+          kb_type = manifest_data["kb_type"] || "local"
           validate_kb_type(kb_type)
 
           validate_sources(manifest_data["sources"])
@@ -139,11 +139,21 @@ module Aircana
         end
 
         def validate_confluence_source(source)
-          raise ManifestError, "Confluence source missing required field: label" unless source.key?("label")
+          raise ManifestError, "Confluence source missing required field: pages" unless source.key?("pages")
 
-          return unless source.key?("pages") && !source["pages"].is_a?(Array)
+          raise ManifestError, "Confluence pages must be an array" unless source["pages"].is_a?(Array)
 
-          raise ManifestError, "Confluence pages must be an array"
+          source["pages"].each do |page_entry|
+            validate_confluence_page_entry(page_entry)
+          end
+        end
+
+        def validate_confluence_page_entry(page_entry)
+          raise ManifestError, "Each page entry must be a hash" unless page_entry.is_a?(Hash)
+
+          raise ManifestError, "Page entry missing required field: id" unless page_entry.key?("id")
+
+          raise ManifestError, "Page entry missing required field: summary" unless page_entry.key?("summary")
         end
 
         def validate_web_source(source)
@@ -160,6 +170,8 @@ 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: summary" unless url_entry.key?("summary")
         end
 
         def validate_kb_type(kb_type)

data/lib/aircana/contexts/web.rb

@@ -22,11 +22,11 @@ module Aircana
         @local_storage = Local.new
       end
 
-      def fetch_url_for(agent:, url:, kb_type: "remote")
+      def fetch_url_for(kb_name:, url:, kb_type: "local")
         validate_url!(url)
 
         page_data = fetch_and_process_url(url)
-        store_page_as_markdown(page_data, agent, kb_type)
+        store_page_as_markdown(page_data, kb_name, kb_type)
 
         build_url_metadata(page_data)
       rescue StandardError => e
@@ -34,14 +34,14 @@ module Aircana
         nil
       end
 
-      def fetch_urls_for(agent:, urls:, kb_type: "remote") # rubocop:disable Metrics/MethodLength
+      def fetch_urls_for(kb_name:, urls:, kb_type: "local") # rubocop:disable Metrics/MethodLength
         return { pages_count: 0, sources: [] } if urls.empty?
 
         pages_metadata = []
         successful_urls = []
 
         ProgressTracker.with_batch_progress(urls, "Fetching URLs") do |url, _index|
-          metadata = fetch_url_for(agent: agent, url: url, kb_type: kb_type)
+          metadata = fetch_url_for(kb_name: kb_name, url: url, kb_type: kb_type)
           if metadata
             pages_metadata << metadata
             successful_urls << url
@@ -50,16 +50,16 @@ module Aircana
 
         if successful_urls.any?
           sources = build_sources_metadata(successful_urls, pages_metadata)
-          update_or_create_manifest(agent, sources, kb_type)
+          update_or_create_manifest(kb_name, sources, kb_type)
           { pages_count: successful_urls.size, sources: sources }
         else
           { pages_count: 0, sources: [] }
         end
       end
 
-      def refresh_web_sources(agent:) # rubocop:disable Metrics/CyclomaticComplexity
-        sources = Manifest.sources_from_manifest(agent)
-        kb_type = Manifest.kb_type_from_manifest(agent)
+      def refresh_web_sources(kb_name:) # rubocop:disable Metrics/CyclomaticComplexity
+        sources = Manifest.sources_from_manifest(kb_name)
+        kb_type = Manifest.kb_type_from_manifest(kb_name)
         web_sources = sources.select { |s| s["type"] == "web" }
 
         return { pages_count: 0, sources: [] } if web_sources.empty?
@@ -67,7 +67,7 @@ module Aircana
         all_urls = web_sources.flat_map { |source| source["urls"]&.map { |u| u["url"] } || [] }
         return { pages_count: 0, sources: [] } if all_urls.empty?
 
-        fetch_urls_for(agent: agent, urls: all_urls, kb_type: kb_type)
+        fetch_urls_for(kb_name: kb_name, urls: all_urls, kb_type: kb_type)
       end
 
       private
@@ -201,21 +201,51 @@ module Aircana
         extract_text_content(html)
       end
 
-      def store_page_as_markdown(page_data, agent, kb_type = "remote")
+      def store_page_as_markdown(page_data, kb_name, kb_type = "local")
         @local_storage.store_content(
           title: page_data[:title],
           content: page_data[:content],
-          agent: agent,
+          kb_name: kb_name,
           kb_type: kb_type
         )
       end
 
       def build_url_metadata(page_data)
+        summary = generate_summary(page_data[:content], page_data[:title], page_data[:url])
+
         {
-          "url" => page_data[:url]
+          "url" => page_data[:url],
+          "summary" => summary
         }
       end
 
+      def generate_summary(content, title, url)
+        prompt = build_summary_prompt(content, title, url)
+        LLM::ClaudeClient.new.prompt(prompt).strip
+      rescue StandardError => e
+        Aircana.human_logger.warn("Failed to generate summary: #{e.message}")
+        # Fallback to title or truncated content
+        title || "#{content[0..80].gsub(/\s+/, " ").strip}..."
+      end
+
+      def build_summary_prompt(content, title, url)
+        truncated_content = content.length > 2000 ? "#{content[0..2000]}..." : content
+
+        <<~PROMPT
+          Generate a concise 8-12 word summary of the following web page.
+          URL: #{url}
+          Title: #{title}
+
+          Content:
+          #{truncated_content}
+
+          The summary should describe what information this page contains in a way that helps
+          someone understand when they should read it. Focus on the key topics covered.
+
+          Respond with only the summary text, no additional explanation or formatting.
+        PROMPT
+      end
+
       def build_sources_metadata(_urls, pages_metadata)
         [
           {
@@ -225,17 +255,17 @@ module Aircana
         ]
       end
 
-      def update_or_create_manifest(agent, new_sources, kb_type = "remote")
-        existing_sources = Manifest.sources_from_manifest(agent)
+      def update_or_create_manifest(kb_name, new_sources, kb_type = "local")
+        existing_sources = Manifest.sources_from_manifest(kb_name)
 
         # Remove existing web sources and add new ones
         other_sources = existing_sources.reject { |s| s["type"] == "web" }
         all_sources = other_sources + new_sources
 
-        if Manifest.manifest_exists?(agent)
-          Manifest.update_manifest(agent, all_sources, kb_type: kb_type)
+        if Manifest.manifest_exists?(kb_name)
+          Manifest.update_manifest(kb_name, all_sources, kb_type: kb_type)
         else
-          Manifest.create_manifest(agent, all_sources, kb_type: kb_type)
+          Manifest.create_manifest(kb_name, all_sources, kb_type: kb_type)
         end
       end