aircana 3.0.0 → 3.2.0

data/lib/aircana/contexts/manifest.rb

@@ -7,31 +7,36 @@ module Aircana
   module Contexts
     class Manifest
       class << self
-        def create_manifest(agent, sources)
+        def create_manifest(agent, sources, kb_type: "remote")
           validate_sources(sources)
+          validate_kb_type(kb_type)
 
           manifest_path = manifest_path_for(agent)
-          manifest_data = build_manifest_data(agent, sources)
+          manifest_data = build_manifest_data(agent, 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}'"
+          Aircana.human_logger.info "Created knowledge manifest for agent '#{agent}' (kb_type: #{kb_type})"
           manifest_path
         end
 
-        def update_manifest(agent, sources)
+        def update_manifest(agent, sources, kb_type: nil)
           validate_sources(sources)
 
           manifest_path = manifest_path_for(agent)
 
           if File.exist?(manifest_path)
             existing_data = JSON.parse(File.read(manifest_path))
-            manifest_data = existing_data.merge({ "sources" => sources })
+            # Preserve existing kb_type unless explicitly provided
+            kb_type_to_use = kb_type || existing_data["kb_type"] || "remote"
+            manifest_data = existing_data.merge({ "sources" => sources, "kb_type" => kb_type_to_use })
           else
-            manifest_data = build_manifest_data(agent, sources)
+            kb_type_to_use = kb_type || "remote"
+            manifest_data = build_manifest_data(agent, sources, kb_type_to_use)
           end
 
+          validate_kb_type(manifest_data["kb_type"])
           FileUtils.mkdir_p(File.dirname(manifest_path))
           File.write(manifest_path, JSON.pretty_generate(manifest_data))
           manifest_path
@@ -61,6 +66,13 @@ module Aircana
           manifest["sources"] || []
         end
 
+        def kb_type_from_manifest(agent)
+          manifest = read_manifest(agent)
+          return "remote" unless manifest
+
+          manifest["kb_type"] || "remote"
+        end
+
         def manifest_exists?(agent)
           File.exist?(manifest_path_for(agent))
         end
@@ -76,10 +88,11 @@ module Aircana
           File.join(Aircana.configuration.agent_knowledge_dir, agent)
         end
 
-        def build_manifest_data(agent, sources)
+        def build_manifest_data(agent, sources, kb_type = "remote")
           {
             "version" => "1.0",
             "agent" => agent,
+            "kb_type" => kb_type,
             "sources" => sources
           }
         end
@@ -95,6 +108,10 @@ 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"
+          validate_kb_type(kb_type)
+
           validate_sources(manifest_data["sources"])
         end
 
@@ -144,6 +161,13 @@ module Aircana
 
           raise ManifestError, "URL entry missing required field: url" unless url_entry.key?("url")
         end
+
+        def validate_kb_type(kb_type)
+          valid_types = %w[remote local]
+          return if valid_types.include?(kb_type)
+
+          raise ManifestError, "Invalid kb_type: #{kb_type}. Must be one of: #{valid_types.join(", ")}"
+        end
       end
     end
 

data/lib/aircana/contexts/web.rb

@@ -22,11 +22,11 @@ module Aircana
         @local_storage = Local.new
       end
 
-      def fetch_url_for(agent:, url:)
+      def fetch_url_for(agent:, url:, kb_type: "remote")
         validate_url!(url)
 
         page_data = fetch_and_process_url(url)
-        store_page_as_markdown(page_data, agent)
+        store_page_as_markdown(page_data, agent, kb_type)
 
         build_url_metadata(page_data)
       rescue StandardError => e
@@ -34,14 +34,14 @@ module Aircana
         nil
       end
 
-      def fetch_urls_for(agent:, urls:) # rubocop:disable Metrics/MethodLength
+      def fetch_urls_for(agent:, urls:, kb_type: "remote") # 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)
+          metadata = fetch_url_for(agent: agent, url: url, kb_type: kb_type)
           if metadata
             pages_metadata << metadata
             successful_urls << url
@@ -50,7 +50,7 @@ module Aircana
 
         if successful_urls.any?
           sources = build_sources_metadata(successful_urls, pages_metadata)
-          update_or_create_manifest(agent, sources)
+          update_or_create_manifest(agent, sources, kb_type)
           { pages_count: successful_urls.size, sources: sources }
         else
           { pages_count: 0, sources: [] }
@@ -59,6 +59,7 @@ module Aircana
 
       def refresh_web_sources(agent:) # rubocop:disable Metrics/CyclomaticComplexity
         sources = Manifest.sources_from_manifest(agent)
+        kb_type = Manifest.kb_type_from_manifest(agent)
         web_sources = sources.select { |s| s["type"] == "web" }
 
         return { pages_count: 0, sources: [] } if web_sources.empty?
@@ -66,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)
+        fetch_urls_for(agent: agent, urls: all_urls, kb_type: kb_type)
       end
 
       private
@@ -200,11 +201,12 @@ module Aircana
         extract_text_content(html)
       end
 
-      def store_page_as_markdown(page_data, agent)
+      def store_page_as_markdown(page_data, agent, kb_type = "remote")
         @local_storage.store_content(
           title: page_data[:title],
           content: page_data[:content],
-          agent: agent
+          agent: agent,
+          kb_type: kb_type
         )
       end
 
@@ -223,7 +225,7 @@ module Aircana
         ]
       end
 
-      def update_or_create_manifest(agent, new_sources)
+      def update_or_create_manifest(agent, new_sources, kb_type = "remote")
         existing_sources = Manifest.sources_from_manifest(agent)
 
         # Remove existing web sources and add new ones
@@ -231,9 +233,9 @@ module Aircana
         all_sources = other_sources + new_sources
 
         if Manifest.manifest_exists?(agent)
-          Manifest.update_manifest(agent, all_sources)
+          Manifest.update_manifest(agent, all_sources, kb_type: kb_type)
         else
-          Manifest.create_manifest(agent, all_sources)
+          Manifest.create_manifest(agent, all_sources, kb_type: kb_type)
         end
       end
 

data/lib/aircana/generators/agents_generator.rb

@@ -5,7 +5,7 @@ require_relative "../generators"
 module Aircana
   module Generators
     class AgentsGenerator < BaseGenerator
-      attr_reader :agent_name, :short_description, :description, :model, :color, :default_agent
+      attr_reader :agent_name, :short_description, :description, :model, :color, :default_agent, :kb_type
 
       AVAILABLE_DEFAULT_AGENTS = %w[planner jira sub-agent-coordinator executor reviewer apply_feedback].freeze
 
@@ -25,7 +25,7 @@ module Aircana
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         agent_name:, short_description: nil, description: nil, model: nil, color: nil,
-        file_in: nil, file_out: nil, default_agent: false
+        file_in: nil, file_out: nil, default_agent: false, kb_type: "remote"
       )
         @agent_name = agent_name
         @short_description = short_description
@@ -33,6 +33,7 @@ module Aircana
         @model = model
         @color = color
         @default_agent = default_agent
+        @kb_type = kb_type
 
         super(
           file_in: file_in || default_template_path,
@@ -68,7 +69,9 @@ module Aircana
       end
 
       def knowledge_path
-        # Use global agents directory with plugin prefix
+        # Both local and remote agents use the same runtime path in ~/.claude/agents/
+        # Local agents: Synced from version control (agents/<name>/knowledge/) via SessionStart hook
+        # Remote agents: Fetched from Confluence/web via 'aircana agents refresh'
         "~/.claude/agents/#{plugin_prefix}-#{agent_name}/knowledge/"
       end
     end

data/lib/aircana/templates/hooks/sync_local_knowledge.erb

@@ -0,0 +1,86 @@
+#!/bin/bash
+# Sync local agent knowledge bases to ~/.claude on session start
+# Compatible with macOS and Linux
+
+set -e
+
+# Create log directory
+mkdir -p ~/.aircana
+LOG_FILE="$HOME/.aircana/hooks.log"
+
+# Get plugin root from environment
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
+
+if [ -z "$PLUGIN_ROOT" ]; then
+    echo "$(date): Warning - CLAUDE_PLUGIN_ROOT not set, skipping knowledge sync" >> "$LOG_FILE"
+    echo "{}"
+    exit 0
+fi
+
+# Source: version-controlled local knowledge in plugin
+# Target: ~/.claude/agents/<plugin-name>-<agent-name>/knowledge/
+LOCAL_AGENTS_DIR="${PLUGIN_ROOT}/agents"
+CLAUDE_AGENTS_DIR="$HOME/.claude/agents"
+
+# Only proceed if agents directory exists
+if [ ! -d "$LOCAL_AGENTS_DIR" ]; then
+    echo "{}"
+    exit 0
+fi
+
+# Read plugin name from plugin.json
+PLUGIN_NAME=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "${PLUGIN_ROOT}/.claude-plugin/plugin.json" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+if [ -z "$PLUGIN_NAME" ]; then
+    echo "$(date): Warning - Could not read plugin name" >> "$LOG_FILE"
+    echo "{}"
+    exit 0
+fi
+
+SYNCED_COUNT=0
+
+# Iterate through each agent directory
+for agent_dir in "$LOCAL_AGENTS_DIR"/*; do
+    if [ ! -d "$agent_dir" ]; then
+        continue
+    fi
+
+    agent_name=$(basename "$agent_dir")
+    manifest_file="${agent_dir}/manifest.json"
+
+    # Check if manifest exists and has kb_type: local
+    if [ -f "$manifest_file" ]; then
+        kb_type=$(grep -o '"kb_type"[[:space:]]*:[[:space:]]*"[^"]*"' "$manifest_file" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+        if [ "$kb_type" = "local" ]; then
+            # Source: version-controlled knowledge in plugin
+            source_knowledge="${agent_dir}/knowledge"
+
+            # Target: ~/.claude/agents/<plugin-name>-<agent-name>/knowledge/
+            target_knowledge="${CLAUDE_AGENTS_DIR}/${PLUGIN_NAME}-${agent_name}/knowledge"
+
+            if [ -d "$source_knowledge" ]; then
+                # Create target directory
+                mkdir -p "$target_knowledge"
+
+                # Sync knowledge files (rsync if available, fallback to cp)
+                if command -v rsync &> /dev/null; then
+                    rsync -a --delete "$source_knowledge/" "$target_knowledge/"
+                else
+                    # Fallback: remove old files and copy new ones
+                    rm -rf "$target_knowledge"/*
+                    cp -R "$source_knowledge"/* "$target_knowledge/" 2>/dev/null || true
+                fi
+
+                SYNCED_COUNT=$((SYNCED_COUNT + 1))
+                echo "$(date): Synced local knowledge for agent: ${agent_name}" >> "$LOG_FILE"
+            fi
+        fi
+    fi
+done
+
+if [ $SYNCED_COUNT -gt 0 ]; then
+    echo "$(date): Synced ${SYNCED_COUNT} local agent knowledge base(s)" >> "$LOG_FILE"
+fi
+
+echo "{}"

data/lib/aircana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aircana
-  VERSION = "3.0.0"
+  VERSION = "3.2.0"
 end

data/{agents → spec_target_1760656566_428/agents}/test-agent/manifest.json

@@ -1,6 +1,7 @@
 {
   "version": "1.0",
   "agent": "test-agent",
+  "kb_type": "remote",
   "sources": [
     {
       "type": "confluence",

data/spec_target_1760656588_38/agents/test-agent/manifest.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0",
+  "agent": "test-agent",
+  "kb_type": "remote",
+  "sources": [
+    {
+      "type": "confluence",
+      "label": "test-agent",
+      "pages": [
+        {
+          "id": "123"
+        }
+      ]
+    }
+  ]
+}

data/spec_target_1760656647_612/agents/test-agent/manifest.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0",
+  "agent": "test-agent",
+  "kb_type": "remote",
+  "sources": [
+    {
+      "type": "confluence",
+      "label": "test-agent",
+      "pages": [
+        {
+          "id": "123"
+        }
+      ]
+    }
+  ]
+}

data/spec_target_1760656660_113/agents/test-agent/manifest.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0",
+  "agent": "test-agent",
+  "kb_type": "remote",
+  "sources": [
+    {
+      "type": "confluence",
+      "label": "test-agent",
+      "pages": [
+        {
+          "id": "123"
+        }
+      ]
+    }
+  ]
+}

data/spec_target_1760656689_268/agents/test-agent/manifest.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0",
+  "agent": "test-agent",
+  "kb_type": "remote",
+  "sources": [
+    {
+      "type": "confluence",
+      "label": "test-agent",
+      "pages": [
+        {
+          "id": "123"
+        }
+      ]
+    }
+  ]
+}

data/spec_target_1760656710_387/agents/test-agent/manifest.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0",
+  "agent": "test-agent",
+  "kb_type": "remote",
+  "sources": [
+    {
+      "type": "confluence",
+      "label": "test-agent",
+      "pages": [
+        {
+          "id": "123"
+        }
+      ]
+    }
+  ]
+}

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: aircana
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Weston Dransfield
 bindir: exe
 cert_chain: []
-date: 2025-10-13 00:00:00.000000000 Z
+date: 2025-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -115,13 +115,6 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
-- agents/apply_feedback.md
-- agents/executor.md
-- agents/jira.md
-- agents/planner.md
-- agents/reviewer.md
-- agents/sub-agent-coordinator.md
-- agents/test-agent/manifest.json
 - commands/apply-feedback.md
 - commands/ask-expert.md
 - commands/execute.md
@@ -195,9 +188,16 @@ files:
 - lib/aircana/templates/hooks/rspec_test.erb
 - lib/aircana/templates/hooks/rubocop_pre_commit.erb
 - lib/aircana/templates/hooks/session_start.erb
+- lib/aircana/templates/hooks/sync_local_knowledge.erb
 - lib/aircana/templates/hooks/user_prompt_submit.erb
 - lib/aircana/version.rb
 - sig/aircana.rbs
+- spec_target_1760656566_428/agents/test-agent/manifest.json
+- spec_target_1760656588_38/agents/test-agent/manifest.json
+- spec_target_1760656647_612/agents/test-agent/manifest.json
+- spec_target_1760656660_113/agents/test-agent/manifest.json
+- spec_target_1760656689_268/agents/test-agent/manifest.json
+- spec_target_1760656710_387/agents/test-agent/manifest.json
 homepage: https://github.com/westonkd/aircana
 licenses:
 - MIT

data/agents/apply_feedback.md

@@ -1,92 +0,0 @@
----
-name: apply-feedback
-description: Applies code review feedback by making recommended changes and amending the HEAD commit
-model: inherit
-color: cyan
----
-
-INSTRUCTIONS IMPORTANT: You are a Code Review Feedback Application Agent that implements recommended changes from code reviews and amends the HEAD commit.
-
-MANDATORY WORKFLOW:
-
-STEP 1: CREATE TODO LIST FILE
-First, create a todo list file with the following tasks enumerated in order:
-
-1. Parse review feedback from conversation context
-2. Create prioritized todo list of changes (critical first, then important, then suggestions)
-3. Present change plan to user for approval
-4. Apply approved changes using appropriate tools
-5. Re-run unit tests to verify changes
-6. Fix any test failures
-7. Amend HEAD commit with improvements
-8. Summarize changes made
-
-STEP 2: EXECUTE EACH TASK IN ORDER
-Work through each task in the todo list sequentially:
-- Mark each task as 'in_progress' when you start it
-- Mark each task as 'completed' when finished
-- Continue until all tasks are done
-
-TASK DETAILS:
-
-1. PARSE FEEDBACK: Extract review feedback from conversation:
-   - Look for review output from previous /review command
-   - Parse feedback organized by severity (Critical / Important / Suggestions)
-   - Extract actionable items with file, line, issue, and recommendation
-   - If no review feedback found in context, inform user and exit
-
-2. CHANGE PLANNING: Create prioritized implementation plan:
-   - List all critical issues to fix (must be addressed)
-   - List all important improvements (should be addressed)
-   - List suggestions (optional, ask user if they want these)
-   - Organize by file for efficient editing
-   - Enter Claude Code planning mode for this step
-   - Create clear, actionable todo items
-
-3. USER APPROVAL: Present plan and get confirmation:
-   - Show organized list of changes to be made
-   - Ask if user wants to include suggestions or just critical/important
-   - Explicitly ask for approval before proceeding
-   - Wait for user confirmation
-
-4. APPLY CHANGES: Implement approved feedback:
-   - Use appropriate tools (Read, Edit, Write, Bash)
-   - Work through changes file by file
-   - Mark each change as completed after applying
-   - Preserve existing code style and patterns
-   - Make targeted changes without unnecessary refactoring
-
-5. TEST EXECUTION: Verify changes don't break tests:
-   - Run project's test command (e.g., bundle exec rspec, npm test, etc.)
-   - Check if all tests pass
-   - If tests pass, proceed to commit
-
-6. FIX TEST FAILURES: Address any failing tests:
-   - If tests fail, analyze failures
-   - Fix implementation issues causing failures
-   - Re-run tests until all pass
-   - Do not proceed to commit until tests pass
-
-7. AMEND COMMIT: Update HEAD commit with improvements:
-   - Run: git add -A to stage all changes
-   - Run: git commit --amend --no-edit to amend HEAD commit
-   - This preserves original commit message while incorporating improvements
-   - Verify commit was successfully amended
-
-8. SUMMARY: Report what was done:
-   - List all changes applied by category (critical/important/suggestions)
-   - Note any feedback items not addressed and why
-   - Confirm HEAD commit was amended with improvements
-   - Mention that commit now includes both implementation and review improvements
-
-IMPORTANT INSTRUCTIONS:
-- ALWAYS start by creating the todo list file before doing any other work
-- Execute tasks in the exact order specified in the todo list
-- Prioritize critical issues - must be fixed
-- Get user approval before making changes
-- Ensure tests pass before amending commit
-- Use 'git commit --amend --no-edit' to preserve original commit message
-- Focus on implementing review feedback, not redesigning code
-
-
-Always check your knowledge base first for code improvement and refactoring best practices.

data/agents/executor.md

@@ -1,85 +0,0 @@
----
-name: executor
-description: Implementation execution agent that reads plans from Jira and executes them with user approval
-model: inherit
-color: green
----
-
-INSTRUCTIONS IMPORTANT: You are an Implementation Execution Agent that reads strategic implementation plans from Jira tickets and executes them with user approval.
-
-MANDATORY WORKFLOW:
-
-STEP 1: CREATE TODO LIST FILE
-First, create a todo list file with the following tasks enumerated in order:
-
-1. Use Task tool with subagent_type 'jira' to read the implementation plan from the specified Jira ticket
-2. Review and validate plan structure (should contain frontmatter and todo checklist)
-3. Enter Claude Code planning mode to create detailed execution todo list from strategic plan
-4. Present execution plan to user for approval
-5. Execute approved implementation tasks sequentially
-6. Write unit tests (delegate to test-writing sub-agent if available)
-7. Run unit tests to verify implementation
-8. Create git commit (delegate to git-ops sub-agent if available)
-
-STEP 2: EXECUTE EACH TASK IN ORDER
-Work through each task in the todo list sequentially:
-- Mark each task as 'in_progress' when you start it
-- Mark each task as 'completed' when finished
-- Continue until all tasks are done
-
-TASK DETAILS:
-
-1. JIRA INTEGRATION: Always delegate Jira operations to the 'jira' sub-agent using Task tool with subagent_type 'jira'. Request the full implementation plan content including:
-   - Plan frontmatter (consulted sub-agents, relevant files)
-   - Strategic implementation steps (todo checklist format)
-   - Any architectural decisions or trade-offs documented
-
-2. PLAN VALIDATION: Verify the plan contains:
-   - Proper markdown frontmatter with metadata
-   - Implementation steps in todo checklist format using `[ ]`
-   - Clear actionable items
-   - If plan is missing or malformed, inform user and exit
-
-3. EXECUTION PLANNING: Transform strategic plan into detailed execution todos:
-   - Break down high-level plan steps into specific implementation tasks
-   - Add file paths and line numbers where relevant
-   - Include testing and verification steps
-   - Sequence tasks logically with dependencies
-   - Enter Claude Code planning mode for this step
-
-4. USER APPROVAL: Present the detailed execution plan and explicitly ask for user approval before proceeding. Wait for confirmation.
-
-5. IMPLEMENTATION EXECUTION: Once approved, work through execution todos:
-   - Use appropriate tools (Read, Write, Edit, Bash, etc.)
-   - Mark each execution task as completed after finishing
-   - Create commits at logical checkpoints
-   - Focus on implementing the WHAT defined in the strategic plan
-
-6. TEST WRITING: Write unit tests for the implementation:
-   - Check if a test-writing sub-agent exists (look for agents with 'test' in name/description)
-   - If found, delegate test writing to that sub-agent using Task tool
-   - Provide implementation context: files changed, new functionality added, edge cases to cover
-   - If no test sub-agent exists, write tests directly following project conventions
-
-7. TEST EXECUTION: Run unit tests to verify implementation:
-   - Use project's test command (e.g., bundle exec rspec, npm test, etc.)
-   - Fix any failing tests
-   - Ensure all tests pass before marking work complete
-
-8. GIT COMMIT: Create a git commit for the implementation:
-   - Check if a git-ops sub-agent exists (look for agents with 'git' in name/description)
-   - If found, delegate commit creation to that sub-agent using Task tool
-   - Provide context: Jira ticket key, summary of changes, files modified
-   - If no git-ops agent exists, create commit directly using Bash tool
-   - Commit message should reference Jira ticket and describe implementation
-   - After successful commit, suggest user runs '/review' command to review changes
-
-IMPORTANT INSTRUCTIONS:
-- ALWAYS start by creating the todo list file before doing any other work
-- Execute tasks in the exact order specified in the todo list
-- The strategic plan tells you WHAT to do, you determine HOW to do it
-- Focus on implementation, not redesign - follow the plan's architecture decisions
-- Get user approval before executing implementation tasks
-
-
-Always check your knowledge base first for execution-specific guidance and best practices.