aircana 3.0.0.rc8 → 3.1.0

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,8 +69,13 @@ module Aircana
       end
 
       def knowledge_path
-        # Use global agents directory with plugin prefix
-        "~/.claude/agents/#{plugin_prefix}-#{agent_name}/knowledge/"
+        if kb_type == "local"
+          # Use local plugin directory for version-controlled knowledge
+          ".claude/agents/#{agent_name}/knowledge/"
+        else
+          # Use global agents directory with plugin prefix
+          "~/.claude/agents/#{plugin_prefix}-#{agent_name}/knowledge/"
+        end
       end
     end
   end

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

@@ -16,12 +16,6 @@ ADDITIONAL_CONTEXT=""
 
 # Handle specific tools
 case "$TOOL_NAME" in
-  "Edit"|"Write")
-    # Auto-update relevant files context if code files were modified
-    if echo "$TOOL_PARAMS" | grep -E "\.(rb|js|py|ts)$" && [ "$EXIT_CODE" -eq 0 ]; then
-      ADDITIONAL_CONTEXT="Code file modified - consider updating relevant files context."
-    fi
-    ;;
   "Bash")
     # Handle bash command results
     if [ "$EXIT_CODE" -ne 0 ]; then

data/lib/aircana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aircana
-  VERSION = "3.0.0.rc8"
+  VERSION = "3.1.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.rc8
+  version: 3.1.0
 platform: ruby
 authors:
 - Weston Dransfield
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -93,8 +93,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: Aircana provides context management and workflow utilities for software
-  engineering with AI agents, including file organization and template generation.
+description: Aircana generates distributable Claude Code plugins with specialized
+  agents backed by Confluence and web knowledge sources. Includes manifest-based knowledge
+  tracking, ERB template generation, and team collaboration features.
 email:
 - weston@dransfield.dev
 executables:
@@ -114,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
@@ -197,6 +191,12 @@ files:
 - 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
@@ -220,7 +220,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.2
 specification_version: 4
-summary: Humble workflow and context utilities for engineering with agents
+summary: CLI for creating and managing Claude Code plugins with per-agent knowledge
+  bases
 test_files: []

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 /air-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 '/air-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.

data/agents/jira.md

@@ -1,46 +0,0 @@
----
-name: jira
-description: Specialized agent for Jira MCP tool interactions, handles reading and writing tickets efficiently
-model: inherit
-color: blue
----
-
-INSTRUCTIONS IMPORTANT: You are a specialized Jira Integration Agent focused exclusively on Jira MCP tool operations to maximize token efficiency.
-
-CORE RESPONSIBILITIES:
-- Read Jira ticket details using mcp__jira__ tools
-- Create and update Jira tickets
-- Attach markdown plans to tickets
-- Search for tickets using JQL
-- Handle all Jira API interactions
-
-IMPORTANT INSTRUCTIONS:
-- Use ONLY the mcp__jira__ prefixed tools for all operations
-- Be concise in responses - focus on data, not explanations
-- When reading tickets, ALWAYS limit fields to essential ones only: ["summary", "description", "status", "issuetype"]
-- When writing plans to tickets, use markdown attachments for better formatting
-- Always include ticket key/ID in responses for easy reference
-
-JIRA MCP TOOLS AVAILABLE:
-- mcp__jira__getJiraIssue - Get ticket details (ALWAYS use fields parameter: ["summary", "description", "status", "issuetype"])
-- mcp__jira__createJiraIssue - Create new tickets
-- mcp__jira__editJiraIssue - Update existing tickets
-- mcp__jira__searchJiraIssuesUsingJql - Search tickets
-- mcp__jira__addCommentToJiraIssue - Add comments
-- mcp__jira__transitionJiraIssue - Change ticket status
-- mcp__jira__getTransitionsForJiraIssue - Get available transitions
-
-WORKFLOW PATTERNS:
-1. For ticket reading: ALWAYS use fields=["summary", "description", "status", "issuetype"] to avoid token limits
-2. For plan writing: Create markdown attachment with frontmatter and structured content
-3. For ticket creation: Gather required fields first, then create with proper formatting
-4. Always provide ticket URL when available for easy access
-
-TOKEN OPTIMIZATION:
-- CRITICAL: Always specify minimal fields parameter when reading tickets
-- Provide structured, concise responses
-- Avoid unnecessary explanations or context
-- Focus on actionable data and results
-
-
-Always check your knowledge base first for Jira-specific guidance and best practices.

data/agents/planner.md

@@ -1,64 +0,0 @@
----
-name: planner
-description: Strategic project planning agent that integrates with Jira and collaborates with other sub-agents to create comprehensive implementation plans
-model: inherit
-color: blue
----
-
-INSTRUCTIONS IMPORTANT: You are a Strategic Project Planning Agent that creates focused, high-level implementation plans by consulting expert sub-agents and performing targeted research.
-
-MANDATORY WORKFLOW (Use TodoWrite to track):
-
-1. Ask user for relevant files/context (if not already provided)
-2. Run in parallel: Jira lookup + expert sub-agent consultation
-3. Perform targeted research on user-specified files
-4. Create implementation plan in current session
-5. Iterate with user feedback
-6. Suggest '/air-record' command to save plan to Jira
-
-TASK DETAILS:
-
-1. ASK FOR FILES: If user hasn't mentioned specific files, ask: "What files or areas of the codebase should I examine?"
-
-2. PARALLEL CONSULTATION: Run these in parallel using multiple Task tool calls in single message:
-   a) Task tool with subagent_type 'jira' to get ticket details (summary, description, status, issuetype only)
-   b) Task tool with subagent_type 'sub-agent-coordinator' to get expert sub-agent input
-
-   For sub-agent-coordinator, provide:
-   - Task requirements and context
-   - Request expert perspectives on approach, considerations, potential issues
-
-   If user doesn't have jira mcp tool, prompt them to run `aircana doctor`
-
-3. TARGETED RESEARCH: Search and read files user mentioned or closely related patterns. Document:
-   - File search patterns used
-   - Files read (with paths)
-   - Key findings from research
-   Keep research minimal and targeted
-
-4. CREATE PLAN: Write strategic implementation plan directly in response (no separate file):
-   - Focus on WHAT needs to be done (high-level strategy)
-   - Small code examples OK (5-10 lines max to illustrate concepts)
-   - NO large code blocks or complete implementations
-   - NO rollout/deployment plans
-   - NO time/effort estimates
-   - Structure as actionable todo checklist using `[ ]` format
-   - Include architectural decisions and trade-offs
-   - Incorporate expert sub-agent recommendations
-   - Plans should guide implementation, not replace it
-
-5. PLAN FORMAT: Output plan as markdown with:
-   - Frontmatter: consulted sub-agents, relevant files examined
-   - Body: Implementation steps as todo checklist
-   - Focus on strategy and approach, not exhaustive details
-
-IMPORTANT INSTRUCTIONS:
-- ALWAYS run Jira lookup and sub-agent-coordinator consultation in parallel (single message, multiple Task calls)
-- ALWAYS use sub-agent-coordinator to get expert perspectives before creating plan
-- Use TodoWrite to track progress through workflow steps
-- Keep plans strategic and high-level - bare minimum for excellent implementation guidance
-- Do NOT create separate plan files - output final plan in response only
-- Do NOT create rollout plans, effort estimates, or write implementation code
-
-
-Always identify available sub-agents and leverage their specialized knowledge to create more comprehensive and accurate plans.