kiro-agents 1.7.1 → 1.9.0

package/build/npm/power/POWER.md

@@ -0,0 +1,266 @@
+---
+name: "kiro-protocols"
+displayName: "Kiro Protocols"
+description: "Reusable protocol library for AI agents - Load step-by-step workflows on-demand for agent management, mode switching, and interactive patterns"
+keywords: ["protocols", "workflows", "agents", "modes", "procedures", "instructions"]
+author: "R. Beltran"
+version: "1.0.0"
+---
+
+# Kiro Protocols
+
+## Overview
+
+A comprehensive library of reusable protocols (step-by-step workflows) that can be loaded on-demand by AI agents, steering documents, and other Kiro Powers. Each protocol provides detailed instructions for specific tasks like agent management, mode switching, and interactive patterns.
+
+**What are Protocols?**
+
+Protocols are detailed, step-by-step instruction documents that guide AI through complex workflows. Instead of embedding these instructions directly in every steering document, protocols are loaded dynamically only when needed, reducing context overhead and improving maintainability.
+
+**Key Benefits:**
+- **On-Demand Loading** - Protocols load only when needed, minimizing context
+- **Single Source of Truth** - One protocol, many consumers
+- **Reusable Across Powers** - Any power can reference these protocols
+- **Maintainable** - Update once, affects all consumers
+- **Extensible** - Easy to add new protocols
+
+## Available Protocols
+
+This power provides the following protocols as steering files:
+
+### Agent System Protocols
+
+- **agent-activation** - Protocol for activating and assuming agent roles
+  - Loads agent definition
+  - Applies agent protocols
+  - Begins agent interaction
+
+- **agent-management** - Interactive agent management workflow
+  - Chit-chat mode interface
+  - Agent directory scanning
+  - Create, activate, manage, and view agents
+
+- **agent-creation** - Step-by-step agent creation wizard
+  - Gather agent information
+  - Generate agent definition
+  - Validate and finalize
+
+### Mode System Protocols
+
+- **mode-switching** - Protocol for switching between Kiro modes
+  - Load mode definition
+  - Preserve context
+  - Handle workflow state transitions
+
+- **mode-management** - Interactive mode management workflow
+  - Mode selection interface
+  - Mode comparison
+  - Help and documentation
+
+## How to Use Protocols
+
+### Method 1: Direct Steering File Load (Recommended)
+
+Use Kiro's built-in power tools to load protocols on-demand:
+
+```markdown
+**Load protocol:**
+1. Call kiroPowers action="activate" with powerName="kiro-protocols"
+2. Call kiroPowers action="readSteering" with powerName="kiro-protocols", steeringFile="agent-activation.md"
+3. Follow all steps from the loaded protocol
+```
+
+**Example in steering document:**
+```markdown
+When user activates agent:
+1. Load agent-activation protocol from kiro-protocols power
+2. Execute protocol steps with agent name as parameter
+3. Agent assumes role and begins interaction
+```
+
+### Method 2: Instruction Alias Pattern
+
+Create reusable aliases that load protocols:
+
+```markdown
+<alias>
+  <trigger>/protocol {protocol_name}</trigger>
+  <definition>
+## Load Protocol: {protocol_name}
+
+**Execute protocol loading:**
+1. Call kiroPowers action="activate" with powerName="kiro-protocols"
+2. Call kiroPowers action="readSteering" with powerName="kiro-protocols", steeringFile="{protocol_name}.md"
+3. Follow all steps from the loaded protocol
+  </definition>
+</alias>
+```
+
+### Method 3: Programmatic Reference
+
+Reference protocols in your steering documents:
+
+```markdown
+**When creating new agent:**
+- Load `agent-creation.md` protocol from kiro-protocols power
+- Follow wizard steps to gather information
+- Generate agent definition file
+- Validate and offer activation
+```
+
+## Protocol Structure
+
+Each protocol follows a consistent structure:
+
+```markdown
+# Protocol Name
+
+Brief description of what this protocol does.
+
+## Protocol Steps
+
+### Step 1: [Action Name]
+
+Detailed instructions for this step...
+
+### Step 2: [Action Name]
+
+Detailed instructions for this step...
+
+[Additional steps...]
+
+---
+
+**Protocol complete. [Next action guidance]**
+```
+
+## Best Practices
+
+### For Protocol Consumers
+
+1. **Load on-demand** - Only load protocols when needed
+2. **Follow steps sequentially** - Protocols are designed as ordered workflows
+3. **Preserve context** - Protocols may reference previous steps
+4. **Handle errors gracefully** - Protocols include error handling guidance
+
+### For Protocol Authors
+
+1. **Keep focused** - One protocol, one workflow
+2. **Be explicit** - Clear, actionable steps
+3. **Include examples** - Show expected inputs/outputs
+4. **Document dependencies** - List required context or prerequisites
+5. **Version carefully** - Breaking changes affect all consumers
+
+## Creating Custom Protocols
+
+Want to add your own protocols to this power?
+
+1. **Fork the repository** - https://github.com/Theadd/kiro-agents
+2. **Add protocol file** - Create `.md` file in `src/core/protocols/`
+3. **Follow structure** - Use existing protocols as templates
+4. **Build and test** - Run build script and test in Kiro IDE
+5. **Submit PR** - Contribute back to the community
+
+## Integration Examples
+
+### Example 1: Agent System
+
+```markdown
+# agents.md (steering document)
+
+When user types `/agents {name}`:
+1. Load agent-activation protocol
+2. Pass agent name as parameter
+3. Execute protocol steps
+4. Agent activates and assumes role
+```
+
+### Example 2: Mode System
+
+```markdown
+# modes.md (steering document)
+
+When user types `/modes {mode}`:
+1. Load mode-switching protocol
+2. Pass mode name as parameter
+3. Check for workflow state preservation
+4. Execute mode switch
+```
+
+### Example 3: Custom Power
+
+```markdown
+# my-custom-power/steering/workflow.md
+
+When complex workflow needed:
+1. Load agent-management protocol from kiro-protocols
+2. Use interactive chit-chat pattern
+3. Guide user through multi-step process
+4. Apply custom power logic
+```
+
+## Troubleshooting
+
+### Protocol Not Found
+
+**Problem:** Error loading protocol file
+
+**Solutions:**
+1. Verify kiro-protocols power is installed
+2. Check protocol name spelling (case-sensitive)
+3. Ensure protocol exists in available list above
+4. Try reloading power: Kiro Powers panel → Reload
+
+### Protocol Outdated
+
+**Problem:** Protocol references old paths or commands
+
+**Solutions:**
+1. Update kiro-protocols power to latest version
+2. Check GitHub releases for breaking changes
+3. Review protocol changelog in repository
+
+### Context Overflow
+
+**Problem:** Too many protocols loaded at once
+
+**Solutions:**
+1. Load protocols only when needed (not upfront)
+2. Use on-demand loading pattern
+3. Consider splitting complex workflows
+4. Unload unused protocols from context
+
+## Version Compatibility
+
+This power follows semantic versioning:
+
+- **Major version** - Breaking changes to protocol structure
+- **Minor version** - New protocols added
+- **Patch version** - Bug fixes and clarifications
+
+**Current Version:** 1.0.0
+
+**Compatibility:**
+- Kiro IDE: All versions with Powers support
+- kiro-agents: v1.6.0+
+
+## Contributing
+
+Contributions welcome! See repository for guidelines:
+- https://github.com/Theadd/kiro-agents
+
+**Ways to contribute:**
+1. Report issues with existing protocols
+2. Suggest new protocols
+3. Improve protocol documentation
+4. Submit protocol enhancements
+
+## License
+
+MIT License - See repository for full license text
+
+---
+
+**Power:** kiro-protocols  
+**Repository:** https://github.com/Theadd/kiro-agents  
+**Version:** 1.0.0

package/build/npm/power/mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/build/npm/power/steering/agent-activation.md

@@ -0,0 +1,50 @@
+# Agent Activation Protocol
+
+This file contains the detailed instructions for activating an agent. It is referenced by the `/agents {agent_name}` alias in `aliases.md`.
+
+## Agent Activation Steps
+
+When activating agent `{agent_name}`:
+
+### Step 1: Load Agent Definition and Strict Mode
+
+Read `.kiro/agents/{agent_name}.md` into context.
+
+This file contains:
+- Agent capabilities and responsibilities
+- Interaction protocols and workflows
+- Mandatory protocols and rules
+- Examples and best practices
+- Integration requirements
+
+**Also load `strict-mode.md` steering document** to enable `/strict {state}` command for this agent session. STRICT_MODE defaults to OFF but user can activate it anytime with `/strict on`.
+
+### Step 2: Assume Agent Role
+
+For this session, you are **{agent_name}**.
+
+You will:
+- Follow ALL protocols and instructions from `.kiro/agents/{agent_name}.md`
+- Apply agent-specific interaction patterns
+- Use capabilities defined in the agent definition
+- Maintain this role until user switches agents or ends session
+- Override any conflicting instructions with agent protocols
+
+### Step 3: Begin Interaction
+
+Start interaction according to **{agent_name}**'s protocols defined in the `.md` file.
+
+If the agent uses **chit-chat mode**:
+- Begin with diff block showing current state
+- Provide numbered choice list (4-6 options, up to 16 if needed)
+- Maintain single focus per message
+- Use visual formatting (bold, code blocks)
+
+Otherwise:
+- Begin according to the agent's defined interaction protocol
+- Follow agent-specific response structure
+- Apply agent-specific formatting rules
+
+---
+
+**You are now {agent_name}. Begin interaction.**

package/build/npm/power/steering/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.**