aircana 2.0.0 → 3.0.0.rc2

data/CLAUDE.md

@@ -25,57 +25,88 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `bundle exec rake release` - Release new version (updates version, creates git tag, pushes to rubygems)
 
 ### Aircana CLI Commands
-- `aircana doctor` - Check system health and dependencies
-- `aircana doctor --verbose` - Show detailed dependency information
-- `aircana dump-context <agent_name>` - Dump context for specified agent
-- `aircana generate` - Generate all configured files
-- `aircana install` - Install generated files to Claude Code config
+
+**Plugin Management:**
+- `aircana init [DIRECTORY]` - Initialize a Claude Code plugin in specified directory (defaults to current)
+- `aircana init --plugin-name NAME` - Initialize with custom plugin name
+- `aircana plugin info` - Display plugin information
+- `aircana plugin update` - Update plugin metadata interactively
+- `aircana plugin version` - Show current version
+- `aircana plugin version bump [major|minor|patch]` - Bump semantic version
+- `aircana plugin version set` - Set specific version
+- `aircana plugin validate` - Validate plugin structure and manifests
+
+**Agent Management:**
 - `aircana agents create` - Create a new agent interactively
+- `aircana agents list` - List all configured agents
 - `aircana agents refresh <agent>` - Refresh agent knowledge from Confluence and web sources
 - `aircana agents refresh-all` - Refresh knowledge for all configured agents
 - `aircana agents add-url <agent> <url>` - Add a web URL to an agent's knowledge base
+
+**Hook Management:**
 - `aircana hooks list` - List all available hooks
 - `aircana hooks enable <hook>` - Enable a specific hook
 - `aircana hooks disable <hook>` - Disable a specific hook
 - `aircana hooks create` - Create custom hook
 - `aircana hooks status` - Show hook configuration status
 
+**System:**
+- `aircana doctor` - Check system health and dependencies
+- `aircana doctor --verbose` - Show detailed dependency information
+- `aircana generate` - Generate plugin components from templates
+- `aircana dump-context <agent_name>` - Dump context for specified agent
+
 ## Architecture
 
 ### Core Structure
-Aircana is a Ruby gem that provides context management and workflow utilities for AI agents, specifically Claude Code. The main components:
+Aircana is a Ruby gem that creates and manages Claude Code plugins. The main components:
 
 - **CLI Layer** (`lib/aircana/cli/`): Thor-based command line interface with subcommands
   - `app.rb`: Main Thor application defining all commands
   - `subcommand.rb`: Base class for subcommands
   - `shell_command.rb`: Shell command execution utilities
   - `commands/`: Individual command implementations
-- **Contexts** (`lib/aircana/contexts/`): Manages different types of context
+    - `init.rb`: Plugin initialization
+    - `plugin.rb`: Plugin metadata management
+    - `agents.rb`: Agent CRUD operations
+    - `hooks.rb`: Hook management
+- **Plugin Management**:
+  - `plugin_manifest.rb`: Manages `.claude-plugin/plugin.json`
+  - `hooks_manifest.rb`: Manages `hooks/hooks.json`
+- **Contexts** (`lib/aircana/contexts/`): Manages knowledge sources
   - `confluence.rb`: Handles Confluence page fetching and caching
   - `confluence_content.rb`: Processes Confluence content
   - `web.rb`: Handles web URL fetching and HTML to Markdown conversion
-  - `local.rb`: Local file context management
+  - `manifest.rb`: Tracks knowledge sources per agent
 - **Generators** (`lib/aircana/generators/`): Template generation system
   - `base_generator.rb`: Base class for all generators
   - `agents_generator.rb`: Generates agent configurations
-  - `hooks_generator.rb`: Generates hook configurations
-- **Configuration** (`lib/aircana/configuration.rb`): Centralized configuration management
+  - Command generators: Generate slash commands from templates
+- **Configuration** (`lib/aircana/configuration.rb`): Centralized configuration management with plugin-aware paths
 - **Support Classes**:
   - `human_logger.rb`: User-friendly logging output
   - `system_checker.rb`: Dependency validation
-  - `agent.rb`: Agent model and persistence
 
 ### Key Concepts
-- **Agents**: Knowledge encapsulation with domain expertise, Confluence sync, and model customization
-- **Hooks**: Claude Code integration points for automated workflows
-- **Context Management**: Integration with Claude Code through generated templates and configurations
+- **Plugins**: Distributable Claude Code extensions with manifests, agents, commands, and hooks
+- **Plugin Manifests**: JSON files defining plugin metadata (`.claude-plugin/plugin.json`)
+- **Agents**: Domain-specific experts with dedicated knowledge bases and context windows
+- **Knowledge Bases**: Curated documentation from Confluence and web sources
+- **Hooks**: Event-driven automation through `hooks/hooks.json`
+- **Commands**: Custom slash commands for workflow automation
 
 ### File Organization
-- Configuration files stored in `~/.aircana` (global) and `.aircana/` (project-local)
-- Claude Code integration through `~/.claude` and `./.claude` directories
-- Generated output goes to `~/.aircana/aircana.out` by default
-- Agent knowledge cached in `.aircana/agents/<agent_name>/`
-- Hooks stored in `.aircana/hooks/`
+- **Plugin Structure**:
+  - `.claude-plugin/plugin.json` - Plugin manifest with metadata and versioning
+  - `agents/` - Agent markdown files and their knowledge directories
+  - `commands/` - Slash command markdown files
+  - `hooks/` - Hook scripts and hooks.json manifest
+- **Configuration**:
+  - `~/.aircana` - Global Aircana configuration
+  - `~/.aircana/aircana.out` - Generated templates output directory
+- **Agent Knowledge**:
+  - `agents/<agent_name>/knowledge/` - Cached knowledge base content
+  - `agents/<agent_name>/manifest.json` - Tracks knowledge sources
 
 ### Dependencies
 - Thor (~> 0.19.1) for CLI framework
@@ -106,4 +137,4 @@ Agents can sync knowledge from multiple sources:
 **Unified Management:**
 - Both sources tracked in manifest.json for each agent
 - Refresh all sources with `aircana agents refresh <agent>`
-- Content stored as Markdown files in `.aircana/agents/<agent>/knowledge/`
+- Content stored as Markdown files in `.claude/agents/<agent>/knowledge/`

data/README.md

@@ -5,17 +5,19 @@
 
 ## Intro
 
-Aircana aims to be a "batteries-included" CLI for common needs of Instructure Engineering teams using agents in development. It provides:
+Aircana is a "batteries-included" CLI for creating and managing Claude Code plugins. It provides:
 
-Consistent artifact generation and updating of agent, slash command, and hook ERB templates.
+**Plugin Development**: Create distributable Claude Code plugins with proper manifests and structure.
 
-Subagent generation for improved context window management.
+**Knowledge Base Management**: Agent-accessible knowledge bases sourced from Confluence or public websites, with automatic syncing and caching.
 
-Agent-accessible knowledge bases sourced from Confluence or public websites, backed by manifest files.
+**Specialized Agents**: Generate domain-specific agents with dedicated knowledge bases for improved context management.
 
-Complete development workflow with five phases: plan, record, execute, review, and apply-feedback.
+**Complete Development Workflow**: Five-phase workflow (plan, record, execute, review, apply-feedback) for systematic feature development.
 
-SQS integration for features like Slack notifications and messages.
+**Hook Management**: Event-driven automation through Claude Code hooks with support for multiple hook types.
+
+**Plugin Distribution**: Create plugins that can be shared via Claude Code plugin marketplaces.
 
 While Aircana includes features beneficial in many agentic contexts (like knowledge base syncing), its primary tools are built on "human-in-the-loop" principles.
 
@@ -35,30 +37,70 @@ Verify installation and dependency setup:
 aircana doctor
 ```
 
-Install Aircana files into your repo:
+### Quick Start
+
+Create a new Claude Code plugin:
 
 ```bash
-cd ~/my/repo
-aircana install # This is a no-op if the repo already uses .aircana
+# Create a new plugin directory
+mkdir my-plugin
+cd my-plugin
+
+# Initialize the plugin
+aircana init
+
+# Or initialize with a custom name
+aircana init --plugin-name my-custom-plugin
 ```
 
-### Take it for a spin
+This creates a plugin structure with:
+- `.claude-plugin/plugin.json` - Plugin manifest
+- `agents/` - Specialized agents
+- `commands/` - Slash commands
+- `hooks/` - Event hooks
 
-If your project previously had Aircana agents set up, run the following to populate each defined agent's knowledge base:
+### Next Steps
 
+**1. Create a specialized agent:**
 ```bash
-aircana agents refresh-all
+aircana agents create
 ```
 
-To start using your agents with domain-specific knowledge, follow the agent workflow tutorial.
+**2. Add knowledge sources:**
+```bash
+# From Confluence (requires configuration)
+aircana agents refresh my-agent
+
+# From web URLs
+aircana agents add-url my-agent https://docs.example.com
+```
+
+**3. Manage your plugin:**
+```bash
+# View plugin information
+aircana plugin info
+
+# Update plugin metadata
+aircana plugin update
+
+# Bump version
+aircana plugin version bump patch
+
+# Validate plugin structure
+aircana plugin validate
+```
+
+**4. Install plugin in Claude Code:**
+- Copy your plugin directory to a location Claude Code can access
+- Use Claude Code's plugin installation commands to enable your plugin
 
 ### Things to try
 
-- Configure the Confluence integration and create your own domain-specific subagent
+- Configure the Confluence integration and create domain-specific agents
 
-- 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.
+- Use the `/air-ask-expert` command to consult multiple specialized agents
 
-- Set up the SQS integration to receive Slack messages when Claude Code needs your attention (documentation coming soon).
+- Set up the development workflow with plan, execute, review, and apply-feedback commands
 
 - Explore other tools by running `aircana --help`
 
@@ -166,21 +208,33 @@ This preserves the original commit message while incorporating review improvemen
 
 ## Key Concepts
 
-### Subagents
+### Plugins
+
+Aircana creates Claude Code plugins - portable, distributable packages that extend Claude Code with custom functionality. Each plugin includes:
+- **Manifest**: Metadata describing the plugin (name, version, author, etc.)
+- **Agents**: Specialized domain experts
+- **Commands**: Custom slash commands
+- **Hooks**: Event-driven automation
 
-Subagents are domain-specific agents to whom the primary Claude Code agent can delegate tasks and questions.
+Plugins can be shared with teams or published to plugin marketplaces for broader distribution.
 
-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.
+### Specialized Agents
 
-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.
+Agents are domain-specific experts to whom Claude Code can delegate tasks and questions. Each agent has:
+- **Dedicated context window**: Prevents context pollution and maintains focus
+- **Knowledge base**: Access to curated domain-specific documentation
+- **Custom configuration**: Model, color, and behavior settings
 
-Aircana allows easy generation of subagents and binds each to an agent-specific knowledge base with documents from Confluence or websites.
+Claude Code can run agents in parallel, creating a "swarm" of experts that can expedite planning and execution while considering broader context.
 
 ### Knowledge Bases
 
-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.
+Aircana provides each agent with a human-curated knowledge base stored within the plugin structure. This enables agents to:
+- Access domain-specific documentation automatically
+- Stay up-to-date with refreshable sources
+- Provide more relevant responses with less back-and-forth
 
-After initial agent creation, Aircana supports refreshing agents' knowledge bases with the latest versions of each source.
+Knowledge bases support multiple source types and can be refreshed to pull the latest content.
 
 #### Confluence
 
@@ -198,33 +252,45 @@ Websites are also refreshed when `aircana agent refresh <AGENT>` is used.
 
 #### Structure
 
-Knowledge bases are stored in the .aircana directory of each project. For example:
+Knowledge bases are stored within the plugin's agent directory. For example:
 
 ```
-.aircana
-├── agents
-│   ├── canvas-backend-account-expert
-│   │   ├── knowledge
-│   │   │   ├── Accounts.md
-│   │   │   └── Subdomains-&-Request-Routing.md
-│   │   └── manifest.json
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── agents/
+│   ├── backend-expert.md
+│   └── backend-expert/
+│       ├── knowledge/
+│       │   ├── API-Design.md
+│       │   └── Authentication.md
+│       └── manifest.json
+├── commands/
+│   └── ask-expert.md
+└── hooks/
+    ├── hooks.json
+    └── pre_tool_use.sh
 ```
 
-Agent files in the .claude/agents directory reference these files.
+Agent files and their knowledge bases are co-located in the plugin's `agents/` directory.
 
-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.
+**Version Control Considerations:**
 
-Knowledge bases may contain sensitive information that should not be public in an open-source project.
+In many cases, adding the actual knowledge base to version control is undesirable because:
+- Knowledge bases may contain numerous files, bloating repository size
+- Content may include sensitive information not suitable for public repos
+- Knowledge refreshes would create frequent, large commits
 
-Aircana manages a per-agent manifest.json file to address these concerns.
+Aircana manages a per-agent `manifest.json` file to track knowledge sources without committing the actual content. Team members can refresh knowledge bases using `aircana agents refresh`.
 
-### Consistent Artifacts
+### Plugin Artifacts
 
-Aircana maintains a set of ERB templates for generating Claude Code agents, hooks, and slash commands consistently.
+Aircana uses ERB templates to generate plugin components consistently:
+- **Agents**: Domain experts with knowledge base integration
+- **Commands**: Slash commands with parameter handling
+- **Hooks**: Event handlers for automation
 
-These templates promote best practices and help new users quickly create effective artifacts without extensive trial and error.
+These templates promote best practices and help create effective plugin components without extensive trial and error.
 
 ### SQS Integration (Slack Integration at Instructure)
 
@@ -294,7 +360,7 @@ The message template supports `{{message}}` placeholder which gets replaced with
 
 ```bash
 aircana generate
-aircana install
+aircana init
 aircana hooks enable notification_sqs
 ```
 
@@ -377,39 +443,42 @@ This refreshes both Confluence pages and web URLs associated with the agent.
 
 ## All Commands
 
-### Agent Management
+### Plugin Management
 ```bash
-aircana agents create     # Create new agent interactively
-aircana agents refresh [AGENT] # Sync agent knowledge from Confluence and web sources
-aircana agents add-url [AGENT] [URL] # Add a web URL to an agent's knowledge base
-aircana agents list       # List all configured agents
+aircana init [DIRECTORY]           # Initialize a new plugin (defaults to current directory)
+aircana init --plugin-name NAME    # Initialize with custom plugin name
+aircana plugin info                # Display plugin information
+aircana plugin update              # Update plugin metadata
+aircana plugin version             # Show current version
+aircana plugin version bump [TYPE] # Bump version (major, minor, or patch)
+aircana plugin version set         # Set specific version
+aircana plugin validate            # Validate plugin structure
 ```
 
-### Hook Management
+### Agent Management
 ```bash
-aircana hooks list        # List all available and installed hooks
-aircana hooks enable [HOOK] # Enable a specific hook
-aircana hooks disable [HOOK] # Disable a specific hook
-aircana hooks create      # Create custom hook
-aircana hooks status      # Show hook configuration status
+aircana agents create              # Create new agent interactively
+aircana agents refresh [AGENT]     # Sync agent knowledge from Confluence and web sources
+aircana agents refresh-all         # Refresh knowledge for all agents
+aircana agents add-url [AGENT] [URL] # Add a web URL to an agent's knowledge base
+aircana agents list                # List all configured agents
 ```
 
-### Project Management
+### Hook Management
 ```bash
-aircana project init     # Initialize multi-root project configuration
-aircana project add [PATH] # Add folder to multi-root configuration
-aircana project remove [PATH] # Remove folder from multi-root configuration
-aircana project list     # List all configured folders and agents
-aircana project sync     # Manually sync symlinks for multi-root agents
+aircana hooks list                 # List all available and installed hooks
+aircana hooks enable [HOOK]        # Enable a specific hook
+aircana hooks disable [HOOK]       # Disable a specific hook
+aircana hooks create               # Create custom hook
+aircana hooks status               # Show hook configuration status
 ```
 
 ### System
 ```bash
-aircana generate         # Generate Claude Code configuration files
-aircana install          # Install generated files to Claude Code
-aircana doctor           # Check system health and dependencies
-aircana doctor --verbose # Show detailed dependency information
-aircana dump-context [AGENT] # View current context for agent
+aircana generate                   # Generate plugin components from templates
+aircana doctor                     # Check system health and dependencies
+aircana doctor --verbose           # Show detailed dependency information
+aircana dump-context [AGENT]       # View current context for agent
 ```
 
 ## Development

data/agents/apply_feedback.md

@@ -0,0 +1,92 @@
+---
+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

@@ -0,0 +1,85 @@
+---
+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

@@ -0,0 +1,46 @@
+---
+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.