aircana 3.0.0.rc1 → 3.0.0.rc3

data/agents/sub-agent-coordinator.md

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

data/agents/test-agent/manifest.json

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

data/commands/air-apply-feedback.md

@@ -0,0 +1,15 @@
+INSTRUCTIONS : Use the Task tool with subagent_type 'apply-feedback' to apply code review feedback from the previous /air-review command.
+
+Pass the review feedback from the conversation context to the apply-feedback agent.
+
+The apply-feedback agent will:
+1. Parse review feedback from the previous review
+2. Create todo list of changes prioritized by severity
+3. Present plan to user for approval
+4. Apply approved changes
+5. Re-run unit tests to verify changes
+6. Fix any test failures
+7. Amend the HEAD commit with improvements using 'git commit --amend --no-edit'
+8. Summarize changes made
+
+IMPORTANT: This command reads the review output from the conversation context, so it must be run in the same conversation as /air-review.

data/commands/air-ask-expert.md

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

data/commands/air-execute.md

@@ -0,0 +1,13 @@
+INSTRUCTIONS : Use the Task tool with subagent_type 'executor' to execute the implementation plan from a Jira ticket.
+
+INSTRUCTIONS FOR EXECUTOR AGENT:
+Ask the user to provide a Jira ticket key/ID to execute.
+
+The executor agent will:
+1. Read the plan from the Jira ticket via the 'jira' sub-agent
+2. Review and validate the plan structure
+3. Create a detailed execution todo list in Claude Code planning mode
+4. Present the plan for your approval
+5. Execute the approved implementation tasks
+
+IMPORTANT: All Jira operations are delegated to the 'jira' sub-agent using Task tool with subagent_type 'jira'.

data/commands/air-plan.md

@@ -0,0 +1,33 @@
+INSTRUCTIONS : First, ask the user to specify relevant files, directories, or areas of the codebase to examine for this planning task.
+
+Then use the Task tool with subagent_type 'planner' to invoke the planner agent with the following explicit instructions:
+
+STEP 1: CREATE TODO LIST FILE
+First, create a todo list file with the following tasks enumerated in order:
+
+1. Ask user for relevant files and context (if not already provided)
+2. Use Task tool with subagent_type 'jira' to verify Jira ticket information (or ask user to create/provide ticket)
+3. Perform targeted initial research on user-specified files
+4. Consult relevant sub-agents with research context (run in parallel when possible)
+5. Create high-level strategic implementation plan
+6. Iterate with user feedback
+7. Suggest user runs '/air-record' command to save the plan to Jira ticket
+
+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
+
+IMPORTANT CONTEXT-SHARING PROTOCOL:
+- When consulting sub-agents, explicitly provide: files already searched, files already read, key findings, and specific focus area
+- This prevents sub-agents from duplicating research work
+
+IMPORTANT PLAN CONSTRAINTS:
+- Focus on strategic, high-level implementation guidance
+- NO rollout plans, effort estimates, or exhaustive code implementations
+- Small code examples (5-10 lines) are OK to illustrate concepts
+
+User specified relevant files/areas: [User will specify]
+
+Ask the user to provide a Jira ticket or task description.

data/commands/air-record.md

@@ -0,0 +1,17 @@
+INSTRUCTIONS : Use the Task tool with subagent_type 'jira' to append the implementation plan to the Jira ticket description using Jira MCP tools.
+
+INSTRUCTIONS FOR JIRA AGENT:
+1. Read the implementation plan from the current context (look for recent planning output)
+2. Get the current ticket description using mcp__jira__getJiraIssue with fields=["description"]
+3. Append the plan to the existing description under a new "## Implementation Plan" heading
+4. Update the ticket using mcp__jira__editJiraIssue with the combined description
+5. Format the appended plan section with:
+   - Consulted sub-agents
+   - Relevant files analyzed
+   - Planning timestamp
+   - Implementation steps as todo list using `[ ]` format
+6. Provide the ticket URL for easy access
+
+CRITICAL: The jira sub-agent must append to the ticket description using mcp__jira__editJiraIssue (NOT create files or comments).
+
+IMPORTANT: Delegate all Jira operations to the 'jira' sub-agent using Task tool with subagent_type 'jira'. The Jira ticket key/ID is already in context.

data/commands/air-review.md

@@ -0,0 +1,12 @@
+INSTRUCTIONS : Use the Task tool with subagent_type 'reviewer' to conduct an adversarial code review of the HEAD commit.
+
+The reviewer agent will:
+1. Get HEAD commit details and changes
+2. Analyze changed files to identify technical domains
+3. Use the sub-agent-coordinator to select relevant expert agents
+4. Present changes to experts in parallel for review
+5. Synthesize feedback organized by severity
+6. Store review output for the apply-feedback command
+7. Suggest running '/air-apply-feedback' to apply recommended changes
+
+IMPORTANT: The review agent will automatically review the HEAD commit. No arguments needed.

data/commands/sample-command.md

@@ -0,0 +1 @@
+# Sample Command

data/hooks/hooks.json

@@ -0,0 +1,31 @@
+{
+  "PostToolUse": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.sh"
+        }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.sh"
+        }
+      ]
+    },
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/rubocop_pre_commit.sh"
+        }
+      ],
+      "matcher": "Bash"
+    }
+  ]
+}

data/lib/aircana/cli/app.rb

@@ -5,12 +5,13 @@ require "thor"
 require_relative "commands/doctor"
 require_relative "commands/dump_context"
 require_relative "commands/generate"
-require_relative "commands/install"
+require_relative "commands/init"
 
 require_relative "subcommand"
 require_relative "help_formatter"
 require_relative "commands/agents"
 require_relative "commands/hooks"
+require_relative "commands/plugin"
 
 module Aircana
   module CLI
@@ -39,9 +40,11 @@ module Aircana
         Generate.run
       end
 
-      desc "install", "Copies the generated files from `generate` to the proper directories in Claude Code config."
-      def install
-        Install.run
+      desc "init [DIRECTORY]",
+           "Initializes a Claude Code plugin in the specified directory (defaults to current directory)"
+      option :plugin_name, type: :string, desc: "Override the default plugin name"
+      def init(directory = nil)
+        Init.run(directory: directory, plugin_name: options[:plugin_name])
       end
 
       class AgentsSubcommand < Subcommand
@@ -103,6 +106,31 @@ module Aircana
 
       desc "hooks", "Manage Claude Code hooks"
       subcommand "hooks", HooksSubcommand
+
+      class PluginSubcommand < Subcommand
+        desc "info", "Display plugin information"
+        def info
+          Plugin.info
+        end
+
+        desc "update", "Update plugin metadata"
+        def update
+          Plugin.update
+        end
+
+        desc "version [ACTION] [TYPE]", "Manage plugin version (show, bump [major|minor|patch], or set)"
+        def version(action = nil, bump_type = nil)
+          Plugin.version(action, bump_type)
+        end
+
+        desc "validate", "Validate plugin structure and manifests"
+        def validate
+          Plugin.validate
+        end
+      end
+
+      desc "plugin", "Manage plugin metadata and configuration"
+      subcommand "plugin", PluginSubcommand
     end
   end
 end

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

@@ -185,13 +185,45 @@ module Aircana
           { pages_count: total_pages, sources: all_sources }
         end
 
-        def show_gitignore_recommendation
-          Aircana.human_logger.info ""
-          Aircana.human_logger.info "💡 Recommendation: Add knowledge directories to .gitignore:"
-          Aircana.human_logger.info "   echo \".claude/agents/*/knowledge/\" >> .gitignore"
-          Aircana.human_logger.info ""
-          Aircana.human_logger.info "   This keeps knowledge sources in version control while excluding"
-          Aircana.human_logger.info "   the actual knowledge content from your repository."
+        def ensure_gitignore_entry
+          gitignore_path = gitignore_file_path
+          pattern = gitignore_pattern
+
+          return if gitignore_has_pattern?(gitignore_path, pattern)
+
+          append_to_gitignore(gitignore_path, pattern)
+          Aircana.human_logger.success "Added knowledge directories to .gitignore"
+        rescue StandardError => e
+          Aircana.human_logger.warn "Could not update .gitignore: #{e.message}"
+          Aircana.human_logger.info "Manually add: #{pattern}"
+        end
+
+        def gitignore_file_path
+          File.join(Aircana.configuration.project_dir, ".gitignore")
+        end
+
+        def gitignore_pattern
+          ".claude/agents/*/knowledge/"
+        end
+
+        def gitignore_has_pattern?(gitignore_path, pattern)
+          return false unless File.exist?(gitignore_path)
+
+          content = File.read(gitignore_path)
+          if content.lines.any? { |line| line.strip == pattern }
+            Aircana.human_logger.info "Knowledge directories already in .gitignore"
+            true
+          else
+            false
+          end
+        end
+
+        def append_to_gitignore(gitignore_path, pattern)
+          existing_content = File.exist?(gitignore_path) ? File.read(gitignore_path) : ""
+          content_to_append = existing_content.empty? || existing_content.end_with?("\n") ? "" : "\n"
+          content_to_append += "#{pattern}\n"
+
+          File.open(gitignore_path, "a") { |f| f.write(content_to_append) }
         end
 
         def log_no_pages_found(normalized_agent)
@@ -237,7 +269,7 @@ module Aircana
           if prompt.yes?("Would you like to fetch knowledge for this agent from Confluence now?")
             Aircana.human_logger.info "Fetching knowledge from Confluence..."
             result = perform_refresh(normalized_agent_name)
-            show_gitignore_recommendation if result[:pages_count]&.positive?
+            ensure_gitignore_entry if result[:pages_count]&.positive?
           else
             Aircana.human_logger.info(
               "Skipping knowledge fetch. You can run 'aircana agents refresh #{normalized_agent_name}' later."
@@ -273,7 +305,7 @@ module Aircana
 
             if result[:pages_count].positive?
               Aircana.human_logger.success "Successfully fetched #{result[:pages_count]} URL(s)"
-              show_gitignore_recommendation
+              ensure_gitignore_entry
             else
               Aircana.human_logger.warn "No URLs were successfully fetched"
             end

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

@@ -47,7 +47,7 @@ module Aircana
             log_success(".claude", "Project Claude config directory exists")
           else
             log_warning(".claude", "Project Claude config directory not found")
-            log_remedy("Will be created when running 'aircana install'")
+            log_remedy("Will be created when running 'aircana init'")
           end
         end
       end
@@ -57,12 +57,11 @@ module Aircana
           Aircana.human_logger.info "\nAircana Configuration:"
 
           check_directory("~/.aircana", "Global Aircana directory")
-          check_directory(".aircana", "Project Aircana directory")
           check_agents_status
         end
 
         def check_agents_status
-          agents_dir = File.join(Dir.pwd, ".aircana", "agents")
+          agents_dir = File.join(Dir.pwd, ".claude", "agents")
           if Dir.exist?(agents_dir) && !Dir.empty?(agents_dir)
             agent_count = Dir.glob(File.join(agents_dir, "*.md")).size
             log_success("agents", "#{agent_count} agent(s) configured")

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

@@ -3,7 +3,7 @@
 require "json"
 require "tty-prompt"
 require_relative "../../generators/hooks_generator"
-require_relative "install"
+require_relative "init"
 
 module Aircana
   module CLI
@@ -40,7 +40,7 @@ module Aircana
           Aircana::Generators::HooksGenerator.create_default_hook(hook_name)
 
           # Install hooks to Claude settings
-          Install.run
+          Init.run
 
           Aircana.human_logger.success "Hook '#{hook_name}' has been enabled."
         end
@@ -56,7 +56,7 @@ module Aircana
           File.delete(hook_file)
 
           # Reinstall remaining hooks to update Claude settings
-          Install.run
+          Init.run
 
           Aircana.human_logger.success "Hook '#{hook_name}' has been disabled."
         end
@@ -152,7 +152,7 @@ module Aircana
           Aircana.human_logger.info "You may need to customize the hook script for your specific needs."
 
           # Install hooks to Claude settings
-          Install.run
+          Init.run
           Aircana.human_logger.success "Hook installed to Claude settings"
 
           # Optionally offer to open in editor