kiro-agents 1.6.0 → 1.7.0

package/README.md

@@ -2,6 +2,8 @@
 
 AI agent system for Kiro IDE. Create specialized agents, switch interaction modes, and reduce cognitive load during development.
 
+> For just <kbd>~0.9K</kbd> of **base context** overheat
+
 ```bash
 npx kiro-agents
 ```
@@ -21,13 +23,16 @@ npx kiro-agents
 ```
 Installs to `~/.kiro/steering/kiro-agents/` - available in all workspaces.
 
-<!--
-**Workspace (Kiro Power):**
-1. Open Powers panel in Kiro IDE
-2. Add from GitHub: `https://github.com/theadd/kiro-agents`
+**Kiro Powers (recommended):**
+
+This repository provides multiple Kiro Powers that can be installed independently:
+
+1. **kiro-protocols** - Reusable protocol library for AI agents
+   - Install via Kiro IDE Powers panel
+   - Add repository: `https://github.com/theadd/kiro-agents`
+   - Select "Kiro Protocols" power
 
-Installs to `.kiro/powers/kiro-agents/` - auto-updates, workspace-specific.
--->
+See [powers/README.md](powers/README.md) for detailed power documentation.
 
 ## Quick Start
 

package/build/npm/dist/agents.md

@@ -6,6 +6,26 @@ keywords: ["agents", "management", "create", "activate", "interactive"]
 
 # Agent Management
 
+## Parameter Detection
+
+**CRITICAL: Check if user provided agent name as parameter**
+
+If the user's message contains `/agents {agent_name}` with a specific agent name (e.g., `/agents kiro-master`):
+
+1. **DO NOT execute the interactive management flow below**
+2. **INSTEAD, execute the instruction alias for agent activation:**
+   - Read `.kiro/agents/{agent_name}.md` into context
+   - Read #[[file:protocols/agent-activation.md]] into context
+   - Follow all steps from the "Agent Activation Steps" section in agent-activation.md
+   - Use `{agent_name}` as the agent identifier throughout the protocol
+3. **Stop processing this document** - The agent activation protocol takes over
+
+**Only continue with interactive management flow below if user typed `/agents` without parameters.**
+
+---
+
+## Interactive Management Mode
+
 You are now in **agent management mode** using chit-chat interaction protocol.
 
 ## Agent Management Steps
@@ -37,9 +57,9 @@ Begin with a diff block showing:
 Execute `listDirectory` on `.kiro/agents/`:
 
 **If directory doesn't exist OR directory is empty:**
-1. **Read `~/.kiro/steering/kiro-agents/protocols/agent-creation.mdx` into context** - Load agent creation protocol
+1. **Read #[[file:protocols/agent-creation.md]] into context** - Load agent creation protocol
 2. Create `.kiro/agents/kiro-master.md` agent automatically using the description from "Initial Agent" section
-3. Follow the agent definition structure from agent-creation.mdx protocol
+3. Follow the agent definition structure from agent-creation.md protocol
 4. Show diff block indicating setup completion
 5. Continue to Step 3 with kiro-master as available agent
 
@@ -89,8 +109,8 @@ Based on user selection:
 
 #### Option 2 - Create New Agent
 
-- **Read `~/.kiro/steering/kiro-agents/protocols/agent-creation.mdx` into context** - Load agent creation protocol
-- Follow all steps from the "Agent Creation Steps" section in agent-creation.mdx
+- **Read #[[file:protocols/agent-creation.md]] into context** - Load agent creation protocol
+- Follow all steps from the "Agent Creation Steps" section in agent-creation.md
 - Start agent creation workflow with interactive wizard
 - Ask for agent type (code-focused, documentation, testing, etc.)
 - Collect agent name, description, capabilities
@@ -100,7 +120,7 @@ Based on user selection:
 
 #### Option 3 - Manage Existing Agent
 
-- **Read `~/.kiro/steering/kiro-agents/protocols/agent-creation.mdx` into context** - Load agent structure reference
+- **Read #[[file:protocols/agent-creation.md]] into context** - Load agent structure reference
 - Show numbered list of available agents
 - User selects agent to manage
 - Offer management options:

package/build/npm/dist/aliases.md

@@ -89,8 +89,8 @@ You are now activating the **{agent_name}** agent.
 
 **Load and execute activation protocol:**
 1. Read `.kiro/agents/{agent_name}.md` into context
-2. Read `~/.kiro/steering/kiro-agents/protocols/agent-activation.mdx` into context
-3. Follow all steps from the "Agent Activation Steps" section in agent-activation.mdx
+2. Read #[[file:protocols/agent-activation.md]] into context
+3. Follow all steps from the "Agent Activation Steps" section in agent-activation.md
 4. Use `{agent_name}` as the agent identifier throughout the protocol
   </definition>
 </alias>
@@ -110,8 +110,8 @@ You are now switching to **{mode_name} mode**.
 
 **Load and execute mode switching protocol:**
 1. Read `kiro-{mode_name}-mode.md` from agent-system directory into context
-2. Read `~/.kiro/steering/kiro-agents/protocols/mode-switching.mdx` into context
-3. Follow all steps from the "Mode Switch Steps" section in mode-switching.mdx
+2. Read #[[file:protocols/mode-switching.md]] into context
+3. Follow all steps from the "Mode Switch Steps" section in mode-switching.md
 4. Use `{mode_name}` as the mode identifier throughout the protocol
   </definition>
 </alias>

package/build/npm/dist/protocols/agent-creation.md

@@ -0,0 +1,282 @@
+# Agent Creation Protocol
+
+This file contains the detailed instructions for creating new agents. It is referenced during agent creation workflow in agent management mode.
+
+## Agent Creation Steps
+
+When creating a new agent:
+
+### Step 1: Initialize Creation Wizard
+
+Use chit-chat mode for the creation process:
+
+```diff
+  👉 Agent creation wizard
+  ⏳ Gathering agent information
+```
+
+**Current Focus**: Creating new agent
+
+### Step 2: Collect Agent Information
+
+Guide user through agent definition with numbered choices:
+
+#### 2.1: Agent Type Selection
+
+**What type of agent would you like to create?**
+
+1. **Specialist** - Focused on specific domain (e.g., refactoring, testing)
+   - Deep expertise in narrow area
+   - Clear boundaries of responsibility
+   - Best for: Specialized tasks requiring domain expertise
+
+2. **Generalist** - Broad capabilities across domains
+   - Flexible and adaptable
+   - Good for exploration and discovery
+   - Best for: General-purpose assistance
+
+3. **Coordinator** - Manages other agents
+   - Orchestrates complex workflows
+   - Handles agent handoffs
+   - Best for: Multi-agent workflows
+
+#### 2.2: Agent Name
+
+**What should we name this agent?**
+
+Requirements:
+- Lowercase with hyphens (e.g., `refactor-architect`)
+- No spaces or special characters
+- Descriptive of agent's purpose
+- Must be unique (check `.kiro/agents/` directory)
+
+#### 2.3: Agent Description
+
+**Provide a brief description (1-2 sentences):**
+
+This will be shown in agent listings and help users understand when to use this agent.
+
+Example: "Specialized in code refactoring with focus on design patterns, SOLID principles, and maintainability improvements."
+
+#### 2.4: Core Responsibilities
+
+**What are the agent's primary responsibilities? (3-5 items)**
+
+Example:
+- Analyze code structure and identify refactoring opportunities
+- Apply design patterns appropriately
+- Improve code maintainability and readability
+- Ensure SOLID principles compliance
+
+#### 2.5: Capabilities
+
+**What specific capabilities should this agent have?**
+
+Group by category. Example:
+
+**Code Analysis:**
+- Detect code smells and anti-patterns
+- Identify coupling and cohesion issues
+- Analyze complexity metrics
+
+**Refactoring:**
+- Extract methods and classes
+- Apply design patterns
+- Simplify conditional logic
+
+#### 2.6: Interaction Protocol
+
+**How should this agent interact with users?**
+
+1. **Formal** - Professional, structured responses
+2. **Casual** - Conversational, friendly tone
+3. **Technical** - Precise, detailed explanations
+4. **Chit-chat mode** - Interactive with diff blocks and numbered choices
+
+**Confirmation requirements:**
+- Always confirm before changes
+- Never confirm (trusted operations)
+- Confirm only risky operations
+
+#### 2.7: Mandatory Protocols
+
+**What rules MUST this agent follow?**
+
+Example:
+1. **Always analyze before refactoring** - Never refactor without understanding impact
+2. **Preserve functionality** - Ensure tests pass after refactoring
+3. **Document changes** - Explain why refactoring was done
+
+#### 2.8: Workflows
+
+**Define step-by-step processes for common tasks:**
+
+Example workflow:
+
+**Refactor Code:**
+1. Analyze current code structure
+2. Identify refactoring opportunities
+3. Propose refactoring plan
+4. Get user confirmation
+5. Apply refactoring
+6. Verify tests pass
+7. Document changes
+
+### Step 3: Generate Agent Definition File
+
+Create `.kiro/agents/{agent-name}.md` with this structure:
+
+```markdown
+---
+name: {agent-name}
+type: {specialist|generalist|coordinator}
+description: {brief description}
+version: 1.0.0
+---
+
+# {Agent Name}
+
+{Brief overview of agent purpose and capabilities}
+
+## Core Responsibilities
+
+{List of primary responsibilities}
+
+## Capabilities
+
+{Detailed list organized by category}
+
+## Interaction Protocol
+
+{How agent responds to user input}
+
+**Response Style:** {formal|casual|technical|chit-chat}
+
+**Formatting Preferences:**
+- {Code blocks, lists, tables, etc.}
+
+**Confirmation Requirements:**
+- {Always, never, when risky}
+
+**Error Handling:**
+- {How agent handles errors}
+
+## Mandatory Protocols
+
+{Rules agent MUST follow with rationale}
+
+## Workflows
+
+{Step-by-step processes for common tasks}
+
+## Examples
+
+### Example 1: {Scenario Name}
+
+**User:** {Example user input}
+**Agent:** {Example agent response}
+
+### Example 2: {Scenario Name}
+
+**User:** {Example user input}
+**Agent:** {Example agent response}
+
+## Integration Points
+
+### Required Steering Documents
+- `{steering-name}.md` - {Why it's required}
+
+### Optional Steering Documents
+- `{steering-name}.md` - {When to load}
+
+## Conflict Priorities
+
+When conflicts arise, this agent prioritizes:
+
+1. User safety and data integrity
+2. Agent mandatory protocols
+3. Project-specific requirements
+4. Performance and efficiency
+5. Code style and conventions
+
+## Best Practices
+
+- {Best practice 1 for using this agent}
+- {Best practice 2 for using this agent}
+- {Best practice 3 for using this agent}
+
+## Advanced Features
+
+- {Advanced feature 1 description}
+- {Advanced feature 2 description}
+
+## Error Handling
+
+- **Syntax errors** - {Approach description}
+- **Logic errors** - {Approach description}
+- **Ambiguous input** - {Approach description}
+
+## Success Metrics
+
+- {Metric 1 description}
+- {Metric 2 description}
+```
+
+### Step 4: Validate Agent Definition
+
+Check that the generated agent file:
+
+1. **Has valid YAML frontmatter** with required fields
+2. **Contains all required sections**:
+   - Core Responsibilities
+   - Capabilities
+   - Interaction Protocol
+   - Mandatory Protocols
+   - Workflows
+   - Examples
+3. **Has no syntax errors** in markdown
+4. **Follows naming conventions** (lowercase with hyphens)
+5. **Is unique** (no existing agent with same name)
+
+### Step 5: Confirm and Finalize
+
+Show summary to user:
+
+```diff
+  👉 Agent creation complete
+  ✅ Agent definition created
+```
+
+**Agent Created:** `{agent-name}`
+
+**Location:** `.kiro/agents/{agent-name}.md`
+
+**Summary:**
+- Type: {type}
+- Responsibilities: {count} defined
+- Capabilities: {count} defined
+- Workflows: {count} defined
+
+**What would you like to do next?**
+
+1. **Activate this agent** - Start using it immediately
+2. **View agent definition** - Review the generated file
+3. **Edit agent** - Make modifications
+4. **Create another agent** - Start new creation wizard
+5. **Return to agent management** - Back to main menu
+6. **Exit** - Return to normal mode
+
+### Step 6: Post-Creation Actions
+
+Based on user choice:
+
+- **Activate**: Execute `/agents {agent-name}` command
+- **View**: Display full agent definition with formatting
+- **Edit**: Open agent file for modifications
+- **Create another**: Restart creation wizard
+- **Return**: Go back to agent management menu
+- **Exit**: Return to normal interaction
+
+---
+
+**Agent creation wizard ready. Begin collecting information.**

package/build/npm/dist/protocols/agent-management.md

@@ -0,0 +1,173 @@
+# Agent Management Protocol
+
+This file contains the detailed instructions for interactive agent management. It is referenced when `/agents` is executed without parameters.
+
+## Agent Management Steps
+
+When entering agent management mode:
+
+### Step 1: Activate Chit-Chat Mode
+
+Load and apply protocols from `chit-chat.md` steering document:
+
+- **Use diff blocks** to show progress and current state
+- **Provide numbered choice lists** (4-8 options, up to 16 if needed)
+- **Maintain single focus** per message
+- **Use visual formatting** (bold, code blocks, lists)
+- **Optimize for ADHD-C** (minimal cognitive load)
+
+Begin with a diff block showing:
+```diff
+  👉 Agent management mode
+  ⏳ [Current operation]
+```
+
+### Step 2: Scan Agents Directory
+
+**CRITICAL: You MUST execute `listDirectory` tool on `.kiro/agents/` to get the actual list of agents.**
+
+**DO NOT rely on open editor files or context - always scan the directory explicitly.**
+
+Execute `listDirectory` on `.kiro/agents/`:
+
+**If directory doesn't exist OR directory is empty:**
+1. **Read #[[file:protocols/agent-creation.md]] into context** - Load agent creation protocol
+2. Create `.kiro/agents/kiro-master.md` agent automatically using the description from "Initial Agent" section
+3. Follow the agent definition structure from agent-creation.md protocol
+4. Show diff block indicating setup completion
+5. Continue to Step 3 with kiro-master as available agent
+
+**If directory exists with agents:**
+1. **Execute `listDirectory` tool** to get complete list of `.md` files
+2. Extract agent names from filenames (remove `.md` extension)
+3. Read frontmatter metadata for descriptions
+4. Categorize by agent type if metadata available
+5. **List ALL agents found** - do not filter or assume based on context
+
+### Step 3: Present Agent Selection
+
+Use this response structure:
+
+```diff
+  👉 Agent management mode
+  ⏳ Agent selection or management
+```
+
+**Current Focus**: Agent selection and management
+
+**Available agents in `.kiro/agents/`:**
+
+[List each agent with format:]
+- **{agent-name}** - {description from frontmatter or .md}
+
+**What would you like to do?**
+
+1. **Activate agent** - Choose agent to activate immediately
+2. **Create new agent** - Start agent creation wizard
+3. **Manage existing agent** - Modify agent configuration
+4. **View agent details** - Show full agent definition
+5. **List all commands** - Show available slash commands
+6. **Agent system help** - Explain how agents work
+7. **Exit** - Return to normal mode
+
+### Step 4: Handle User Choice
+
+Based on user selection:
+
+#### Option 1 - Activate Agent
+
+- Show numbered list of available agents
+- User selects agent by number
+- Execute `/agents {selected_agent_name}` command
+- Agent activates immediately
+
+#### Option 2 - Create New Agent
+
+- **Read #[[file:protocols/agent-creation.md]] into context** - Load agent creation protocol
+- Follow all steps from the "Agent Creation Steps" section in agent-creation.md
+- Start agent creation workflow with interactive wizard
+- Ask for agent type (code-focused, documentation, testing, etc.)
+- Collect agent name, description, capabilities
+- Generate `.md` file with all agent definition following protocol structure
+- Validate agent definition per protocol
+- Offer to activate new agent
+
+#### Option 3 - Manage Existing Agent
+
+- **Read #[[file:protocols/agent-creation.md]] into context** - Load agent structure reference
+- Show numbered list of available agents
+- User selects agent to manage
+- Offer management options:
+  - Modify capabilities
+  - Update instructions
+  - Change interaction protocol
+  - Add/remove integrations
+  - Delete agent
+- Use agent definition structure from protocol as reference for modifications
+- Apply changes to agent `.md` file
+- Validate changes against protocol requirements
+- Reload agent if currently active
+
+#### Option 4 - View Agent Details
+
+- Show numbered list of available agents
+- User selects agent to view
+- Display full `.md` content with formatting
+- Show agent protocols and capabilities summary
+- Offer to activate or manage agent
+
+#### Option 5 - List All Commands
+
+Show all available slash commands in the system:
+
+```
+Available Commands:
+
+AGENT COMMANDS
+  /agents {name}    Activate specific agent
+  /agents           Interactive agent management
+
+MODE COMMANDS (see modes-system.md)
+  /modes {name}     Switch Kiro mode (vibe/spec)
+  /modes            Interactive mode management
+  /strict {state}   Control strict mode (on/off)
+  /strict           Interactive strict mode control
+
+Note: Commands are defined in steering documents.
+New commands can be added via Instruction Alias pattern.
+```
+
+#### Option 6 - Agent System Help
+
+Explain agent system:
+- Agent system architecture
+- Command usage examples
+- Agent file structure
+- How to create custom agents
+- Best practices for agent usage
+
+#### Option 7 - Exit
+
+- Confirm exit from agent management mode
+- Return to normal interaction
+- Preserve any changes made
+
+### Step 5: Maintain Chit-Chat Mode
+
+Continue using diff blocks and numbered choices throughout agent management session.
+
+After each action:
+- Update diff block with progress
+- Show current focus
+- Provide next action choices
+- Allow going back or canceling
+
+**Context Preservation:**
+- Use diff blocks to show progress
+- Preserve user decisions
+- Allow going back to previous step
+- Enable canceling operations
+
+---
+
+**Agent management mode active. Present choices to user.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-agents",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Advanced AI agent system for Kiro IDE - Create specialized AI agents, switch interaction modes, and enhance development workflows with minimal cognitive overhead",
   "homepage": "https://github.com/Theadd/kiro-agents#readme",
   "repository": {
@@ -21,6 +21,8 @@
   "scripts": {
     "build": "bun run scripts/build.ts npm",
     "build:power": "bun run scripts/build.ts power",
+    "build:powers": "bun run scripts/build-powers.ts",
+    "validate:powers": "bun run scripts/validate-powers.ts",
     "dev": "bun run scripts/build.ts dev",
     "test": "bun run scripts/test.ts",
     "clean": "bun run scripts/clean.ts",