kiro-agents 1.1.0 → 1.3.0

package/README.md

@@ -186,7 +186,7 @@ AI: Agent created! Activate now? [Yes/No]
 ### Switching Modes
 
 ```
-User: /mode spec
+User: /modes spec
 AI: [Loads spec mode protocols]
 AI: What feature do you want to work on?
 User: User authentication system
@@ -205,9 +205,9 @@ AI: [Asks clarifying questions about cache strategy, TTL, invalidation, etc.]
 ### Agent Coordination
 
 ```
-User: /mode spec
+User: /modes spec
 [Work on feature planning]
-User: /agent kiro-master
+User: /agents kiro-master
 [Use kiro-master capabilities while in spec mode]
 ```
 

package/build/npm/dist/agent-system.md

@@ -7,43 +7,12 @@ description: Generic agent activation system with instruction commands for seaml
 
 Generic agent activation and management system for Kiro using instruction commands with parameter support.
 
-## Instruction Alias with Parameters
-
-### Parameter Substitution Protocol
-
-When processing instructions, if you encounter an XML structure `<alias>` with variables in `{curly_braces}`:
-
-```xml
-<alias>
-  <trigger>COMMAND {param1} {param2}</trigger>
-  <definition>
-    Instructions with {param1} and {param2} placeholders
-  </definition>
-</alias>
-```
-
-**Processing steps:**
-1. **Extract parameter names** from `<trigger>` (e.g., `{param1}`, `{param2}`)
-2. **Match user command** - When user types matching command pattern
-3. **Extract parameter values** - Capture actual values from user input
-4. **Replace placeholders** - Substitute all `{param}` in `<definition>` with actual values
-5. **Execute instructions** - Run resulting instructions immediately
-
-### Example
-
-**Alias definition:**
-```xml
-<alias>
-  <trigger>/greet {name}</trigger>
-  <definition>Say hello to {name} enthusiastically!</definition>
-</alias>
-```
-
-**User types:** `/greet Alice`
-**System executes:** "Say hello to Alice enthusiastically!"
+**For complete documentation, examples, and troubleshooting, see `docs/agent-system-guide.md`**
 
 ## Agent Commands
 
+**Note:** This system uses the Instruction Alias pattern defined in `aliases.md`.
+
 ### Command 1: Activate Specific Agent
 
 <alias>
@@ -53,48 +22,11 @@ When processing instructions, if you encounter an XML structure `<alias>` with v
 
 You are now activating the **{agent_name}** agent.
 
-### 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.**
+**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
+4. Use `{agent_name}` as the agent identifier throughout the protocol
   </definition>
 </alias>
 
@@ -111,271 +43,69 @@ This provides a visual interface for:
 - Interactive: `/agents` (no parameters, loads `agents.md` steering file)
 - Direct: `/agents {name}` (with agent name, uses alias above)
 
-## Agent Activation Protocol
+## Quick Reference
 
-When `/agent {name}` is executed:
+### Activation Protocol Summary
 
-1. **Discover agent file**
-   - Check `.kiro/agents/{name}.md` exists
-   - If file missing, show error and suggest `/agents` command
+When `/agents {name}` is executed:
 
-2. **Load agent definition**
-   - Read `.kiro/agents/{name}.md` into context
-   - **Load `strict-mode.md`** steering document (enables `/strict` commands)
-   - Parse frontmatter metadata
-   - Understand agent capabilities and workflows
-   - Identify mandatory protocols
-   - Note interaction patterns
-   - Check integration requirements
+1. **Discover** - Check `.kiro/agents/{name}.md` exists
+2. **Load** - Read agent definition and `strict-mode.md`
+3. **Apply** - Follow mandatory protocols, load required steering
+4. **Assume** - Become agent completely, maintain role
+5. **Begin** - Start interaction per agent's protocol
 
-3. **Apply protocols**
-   - Follow all mandatory protocols from definition
-   - Load required steering documents
-   - Apply agent-specific overrides
-   - Set up agent context
+### Management Protocol Summary
 
-4. **Assume role**
-   - Become the agent completely
-   - Maintain role until user switches agents
-   - Apply agent personality and style
-   - Use agent-specific tools and workflows
-
-5. **Begin interaction**
-   - Start according to agent's interaction protocol
-   - Use agent's response structure
-   - Apply agent's formatting rules
-   - Maintain agent's focus and priorities
+When `/agents` is executed:
 
-## Agent Management Protocol
+1. **Activate chit-chat** - Load chit-chat.md, use diff blocks
+2. **Scan directory** - List `.md` files in `.kiro/agents/`
+3. **Present choices** - Show agents, offer operations
+4. **Handle operations** - Activation, creation, management, viewing
+5. **Maintain context** - Track progress, preserve decisions
 
-When `/agents` is executed:
+## Agent Definition Requirements
 
-1. **Activate chit-chat mode**
-   - Load chit-chat.md steering
-   - Use diff blocks for progress
-   - Provide numbered choices
-   - Maintain single focus
-
-2. **Scan agents directory**
-   - List all `.md` files in `.kiro/agents/`
-   - Exclude `.instructions.md` files
-   - Extract agent metadata
-   - Categorize agents by type
-
-3. **Present choices**
-   - Show available agents with descriptions
-   - Offer management operations
-   - Provide help and documentation
-   - Allow exit to normal mode
-
-4. **Handle operations**
-   - Agent activation → Execute `/agent {name}`
-   - Agent creation → Start creation wizard
-   - Agent management → Modify agent files
-   - Agent viewing → Display agent details
-   - Help → Explain agent system
-   - Exit → Return to normal mode
-
-5. **Maintain context**
-   - Use diff blocks to show progress
-   - Preserve user decisions
-   - Allow going back
-   - Enable canceling operations
-
-## Agent Directory Structure
-
-```
-.kiro/agents/
-└── {agent-name}.md              # Complete agent definition
-    ├── Frontmatter metadata
-    ├── Core responsibilities
-    ├── Capabilities and workflows
-    ├── Interaction protocols
-    ├── Mandatory protocols
-    ├── Examples and best practices
-    ├── Integration rules
-    └── Conflict priorities
-```
-
-### Agent Definition File (.md)
+**File location:** `.kiro/agents/{agent-name}.md`
 
 **Required sections:**
-- Frontmatter with name, type, metadata
+- Frontmatter (name, type, description, version)
 - Core Responsibilities
-- Capabilities (detailed list)
-- Interaction Protocol (how agent responds)
-- Mandatory Protocols (rules agent must follow)
-- Workflows (step-by-step processes)
-- Examples (interaction patterns)
+- Capabilities
+- Interaction Protocol
+- Mandatory Protocols
+- Workflows
+- Examples
 
 **Recommended sections:**
+- Integration Points
+- Conflict Priorities
 - Best Practices
-- Integration Points (with other agents/steering)
-- Conflict Priorities (ordered list)
 - Advanced Features
 - Error Handling
 - Success Metrics
 
 ## Initial Agent
 
-When auto-setup detects no agents exist, it creates the initial agent:
+When auto-setup detects no agents exist, it creates:
 
 **kiro-master** - Interactive Kiro feature management with CRUD operations for MCP servers, hooks, agents, specs, powers, and steering documents. Includes .kiro/ directory maintenance, steering optimization, refactoring, and comprehensive analysis capabilities
 
-This description is used when creating `.kiro/agents/kiro-master.md` during auto-setup.
-
-## Usage Examples
-
-### Activate Specific Agent
-
-```
-/agent refactor-architect
-```
-
-**Result:** AI immediately assumes refactor-architect role, loads agent files, applies protocols, and begins interaction according to agent's style.
-
-### Interactive Agent Management
+## Integration Notes
 
-```
-/agents
-```
-
-**Result:** Chit-chat mode activates, shows available agents, offers management options with numbered choices.
-
-### Switch Between Agents
-
-```
-/agent kiro-master
-```
-
-**Result:** Switch from current agent (e.g., refactor-architect) to kiro-master. Previous agent context is suspended, new agent context is loaded.
-
-### Create New Agent
-
-```
-/agents
-[Choose option 2: Create new agent]
-[Follow wizard prompts]
-```
-
-**Result:** Interactive agent creation wizard guides through agent setup, generates files, offers activation.
-
-## Integration with Existing System
-
-### Compatibility
-
-- **Works alongside steering documents** - Agents can load additional steering
-- **Compatible with chit-chat mode** - Agents can use chit-chat protocols
-- **Preserves ADHD-C optimizations** - Single focus, visual formatting maintained
-- **Maintains language rules** - Spanish chat, English files
-- **Respects user preferences** - Confirmation before changes, choice-based interaction
+- Works alongside steering documents
+- Compatible with chit-chat mode
+- Preserves ADHD-C optimizations
 - **Mode system** - Works seamlessly with modes (see `modes-system.md`)
 - **Context preservation** - File changes and conversation history persist across agent switches
 
-### Steering Document Loading
-
-Agents can specify required steering documents in their `.md` definition file:
-
-```markdown
-## Integration Points
-
-### Required Steering Documents
-- `[steering-name].md` - Always loaded when agent is active
-- `[another-steering].md` - Core rules for agent behavior
-
-### Optional Steering Documents
-- `[conditional-steering].md` - Loaded based on file context
-- `[manual-steering].md` - Loaded when explicitly needed
-```
-
-### Agent Coordination
-
-**Multiple agents can coordinate through:**
-- **Handoff procedures** - Agent A passes control to Agent B
-- **Context sharing** - Agents share relevant information
-- **Conflict resolution** - Priority rules determine behavior
-- **Collaborative workflows** - Agents work together on complex tasks
-
-## Best Practices
-
-### For Agent Users
-
-1. **Use `/agents` for discovery** - See what agents are available
-2. **Use `/agent {name}` for direct activation** - When you know which agent you need
-3. **Let agents maintain focus** - Don't switch agents mid-task unless necessary
-4. **Provide clear context** - Help agents understand your needs
-5. **Use agent capabilities** - Leverage agent-specific tools and workflows
-
-### For Agent Creators
-
-1. **Clear agent definition** - Comprehensive `.md` with all capabilities and protocols
-2. **Focused protocols** - Clear mandatory protocols section within `.md` file
-3. **Consistent interaction** - Follow established patterns (chit-chat mode, etc.)
-4. **Good examples** - Show how agent works in practice
-5. **Integration rules** - Specify required steering documents
-
-### For Agent Development
-
-1. **Start with template** - Use existing agents as reference
-2. **Test thoroughly** - Verify agent activates and functions correctly
-3. **Document well** - Clear descriptions and examples
-4. **Keep it simple** - Don't overcomplicate agent protocols
-5. **Iterate based on use** - Improve agent based on actual usage
-
-## Troubleshooting
-
-### Agent Not Activating
-
-**Problem:** `/agent {name}` doesn't work
-**Solutions:**
-- Check agent files exist in `.kiro/agents/`
-- Verify filename matches command (case-sensitive)
-- Ensure `.md` file contains all required sections
-- Try `/agents` to see available agents
-
-### Agent Behaving Incorrectly
-
-**Problem:** Agent doesn't follow expected protocols
-**Solutions:**
-- Review agent `.md` file for clarity in Mandatory Protocols section
-- Check for conflicting steering documents
-- Verify mandatory protocols are clear and comprehensive
-- Test agent in isolation
-
-### Agent Management Not Working
-
-**Problem:** `/agents` command doesn't activate
-**Solutions:**
-- Verify `agent-system.md` is in `.kiro/steering/`
-- Check `inclusion: always` in frontmatter
-- Ensure `chit-chat.md` exists
-- Try reloading steering documents
-
-## Future Enhancements
-
-Potential improvements to agent system:
-
-**Agent enhancements:**
-- **Agent parameters** - `/agent refactor-architect --mode=strict`
-- **Agent chaining** - `/agent kiro-master then refactor-architect`
-- **Agent templates** - Quick agent creation from templates
-- **Agent marketplace** - Share agents with community
-- **Agent versioning** - Track agent changes over time
-- **Agent testing** - Automated agent validation
-
-**Integration enhancements:**
-- **Task sessions** - Agents create sub-tasks with own context
-- **Session continuation** - Resume interrupted work with full context
-- **Enhanced mode integration** - Better coordination with modes system
-
-## Notes
+## System Notes
 
-- This system is a **prototype** - Kiro doesn't natively support agents
-- Commands are implemented via **Instruction Alias pattern**
-- System relies on **AI understanding and following instructions**
-- May need **iteration based on actual usage**
-- Consider **proposing as Kiro feature request** if successful
+- Prototype system using Instruction Alias pattern
+- Relies on AI understanding and following instructions
+- May need iteration based on actual usage
 
 ---
 
-**Agent system ready. Use `/agents` to begin or `/agent {name}` to activate specific agent.**
+**Agent system ready. Use `/agents` to begin or `/agents {name}` to activate specific agent.**

package/build/npm/dist/agents.md

@@ -8,139 +8,172 @@ keywords: ["agents", "management", "create", "activate", "interactive"]
 
 You are now in **agent management mode** using chit-chat interaction protocol.
 
-## Step 1: Load Chit-Chat Mode
+## 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 `{{{PROTOCOLS_PATH}}}/agent-creation.mdx` 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
+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 `{{{PROTOCOLS_PATH}}}/agent-creation.mdx` into context** - Load agent creation protocol
+- Follow all steps from the "Agent Creation Steps" section in agent-creation.mdx
+- 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 `{{{PROTOCOLS_PATH}}}/agent-creation.mdx` 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}}}
+
+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 Kiro 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.**
 
-Apply protocols from `chit-chat.md` steering document:
-- Use diff blocks to show progress
-- Provide numbered choice lists (4-6 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)
-
-## Step 2: Auto-Setup and 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.**
-
-**First, execute `listDirectory` on `.kiro/agents/`:**
-
-If directory doesn't exist OR directory is empty:
-1. Create `.kiro/agents/kiro-master.md` agent automatically using the description from "Initial Agent" section
-2. Show diff block indicating setup completion
-3. 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:**
-- Start agent creation workflow
-- Ask for agent type (code-focused, documentation, testing, etc.)
-- Collect agent name, description, capabilities
-- Generate `.md` file with all agent definition
-- Offer to activate new agent
-
-**Option 3 - Manage existing agent:**
-- 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
-
-**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
-- Display command syntax and brief description
-- Group by category (agents, modes, utilities)
-- Format as table for quick reference:
-
-```
-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 architecture
-- Show command usage examples
-- Describe agent file structure
-- Explain how to create custom agents
-- Document best practices
-
-**Option 7 - Exit:**
-- Confirm exit from agent management mode
-- Return to normal Kiro 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
 
 ## Initial Agent
 

package/build/npm/dist/aliases.md

@@ -0,0 +1,77 @@
+---
+inclusion: always
+description: Instruction alias system for creating custom commands with parameter substitution and literal responses
+---
+
+# Instruction Alias System
+
+System for creating custom commands using XML-based alias definitions with parameter support and literal response patterns.
+
+**For complete documentation, examples, and troubleshooting, see `docs/aliases-guide.md`**
+
+## Parameter Substitution
+
+When processing instructions, if you encounter an XML structure `<alias>` with variables in `{curly_braces}`:
+
+```xml
+<alias>
+  <trigger>COMMAND {param1} {param2}</trigger>
+  <definition>
+    Instructions with {param1} and {param2} placeholders
+  </definition>
+</alias>
+```
+
+**Processing steps:**
+1. **Extract parameter names** from `<trigger>` (e.g., `{param1}`, `{param2}`)
+2. **Match user command** - When user types matching command pattern
+3. **Extract parameter values** - Capture actual values from user input
+4. **Replace placeholders** - Substitute all `{param}` in `<definition>` with actual values
+5. **Execute instructions** - Run resulting instructions immediately
+
+### Example
+
+**Alias definition:**
+```xml
+<alias>
+  <trigger>/greet {name}</trigger>
+  <definition>Say hello to {name} enthusiastically!</definition>
+</alias>
+```
+
+User types: `/greet Alice` → Executes: "Say hello to Alice enthusiastically!"
+
+## Literal Response Pattern
+
+For outputting exact text without AI interpretation (e.g., triggering native IDE modes):
+
+````xml
+<alias>
+  <trigger>command</trigger>
+  <definition>
+Respond directly to the user with exactly and only the content of the following code block, AS-IS:
+```
+literal_text
+```
+  </definition>
+</alias>
+````
+
+**CRITICAL:** When you see this pattern, output ONLY the code block content. No explanations, no context, no other text.
+
+### Example
+
+**Alias definition:**
+````xml
+<alias>
+  <trigger>/spec</trigger>
+  <definition>
+Respond directly to the user with exactly and only the content of the following code block, AS-IS:
+```
+spec
+```
+  </definition>
+</alias>
+````
+
+User types: `/spec` → AI responds: `spec`

package/build/npm/dist/modes/kiro-spec-mode.md

@@ -216,7 +216,7 @@ When user requests task execution:
 ## Integration with Agent System
 
 Spec mode can be activated via:
-- `/mode spec` command (when mode-switching is enabled)
+- `/modes spec` command (when mode-switching is enabled)
 - Starting new conversation in Spec mode
 - Explicit instruction to assume Spec mode role
 

package/build/npm/dist/modes/kiro-vibe-mode.md

@@ -217,7 +217,7 @@ User: "Tests are failing"
 ## Integration with Agent System
 
 Vibe mode can be activated via:
-- `/mode vibe` command (when mode-switching enabled)
+- `/modes vibe` command (when mode-switching enabled)
 - Starting new conversation in Vibe mode
 - Explicit instruction to assume Vibe mode role
 
@@ -238,13 +238,13 @@ Vibe mode works alongside:
 ## Switching Between Modes
 
 **From Vibe to Spec:**
-- Use `/mode spec` when structure needed
+- Use `/modes spec` when structure needed
 - Transition to formal planning
 - Create requirements/design/tasks
 - Follow spec workflow
 
 **From Spec to Vibe:**
-- Use `/mode vibe` for flexibility
+- Use `/modes vibe` for flexibility
 - Continue working on same code
 - Drop formal structure
 - Iterate freely

package/build/npm/dist/modes-system.md

@@ -7,6 +7,8 @@ description: Kiro mode switching system for flexible interaction styles (vibe/sp
 
 Mode switching system for Kiro that enables different interaction styles and workflows.
 
+**For complete documentation, examples, and troubleshooting, see `docs/modes-system-guide.md`**
+
 ## Available Modes
 
 - **vibe** - Flexible, conversational development assistance
@@ -23,84 +25,11 @@ Mode switching system for Kiro that enables different interaction styles and wor
 
 You are now switching to **{mode_name} mode**.
 
-### Step 1: Load Mode Definition
-
-Read `kiro-{mode_name}-mode.md` from agent-system directory into context.
-
-This file contains:
-- Mode identity and purpose
-- Interaction protocols
-- Workflow patterns (if any)
-- Response style guidelines
-- Testing approaches
-- File organization rules
-- Integration points
-
-**Also load `strict-mode.md` steering document** to enable `/strict {state}` command for this mode. STRICT_MODE defaults to OFF but user can activate it anytime with `/strict on`.
-
-### Step 2: Assume Mode Role
-
-For this session, you are in **{mode_name} mode**.
-
-You will:
-- Follow ALL protocols and instructions from `kiro-{mode_name}-mode.md`
-- Apply mode-specific interaction patterns
-- Use capabilities defined in the mode definition
-- Maintain this mode until user switches modes or ends session
-- Override any conflicting instructions with mode protocols
-
-### Step 3: Preserve Context and Check State
-
-**IMPORTANT:** Mode switching preserves:
-- All file changes made in previous mode
-- Conversation history and context
-- Current working state
-- User preferences and settings
-
-**WARNING:** Mode switching does NOT preserve:
-- Workflow state (e.g., which phase you're in)
-- Approval gate status
-- Phase-specific context
-
-**If switching FROM spec mode:**
-Before switching, display warning:
-```
-⚠️ Switching from Spec mode will reset workflow state.
-
-Current Spec state:
-- Phase: [current phase]
-- Requirements: [approved/not approved]
-- Design: [approved/not approved]
-- Tasks: [approved/not approved]
-
-If you return to Spec mode later, you'll need to re-approve documents.
-
-Continue switching to {mode_name} mode? [Yes] [No, stay in Spec mode]
-```
-
-Wait for user confirmation before proceeding.
-
-You are simply changing HOW you interact, not WHAT you're working on.
-
-### Step 4: Begin Interaction
-
-Start interaction according to **{mode_name} mode**'s protocols.
-
-**If switching to spec mode:**
-- Ask user what they want to work on
-- Offer to create new spec or update existing
-- Follow structured workflow (requirements → design → tasks)
-- Use approval gates between phases
-
-**If switching to vibe mode:**
-- Continue with flexible, conversational interaction
-- No formal workflow required
-- Make changes directly when clear
-- Iterate quickly on feedback
-
----
-
-**You are now in {mode_name} mode. Begin interaction.**
+**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
+4. Use `{mode_name}` as the mode identifier throughout the protocol
   </definition>
 </alias>
 
@@ -117,59 +46,25 @@ This provides a visual interface for:
 - Interactive: `/modes` (no parameters, loads `modes.md` steering file)
 - Direct: `/modes {name}` (with mode name, uses alias above)
 
-## Mode Activation Protocol
-
-When `/mode {name}` is executed:
-
-1. **Load mode definition**
-   - Read `kiro-{name}-mode.md` from agent-system directory
-   - Load `strict-mode.md` steering document
-   - Parse mode configuration
-   - Understand mode workflows
+## Quick Reference
 
-2. **Check current state**
-   - If switching FROM spec mode, show warning
-   - Wait for user confirmation if needed
-   - Preserve file changes and context
+### Activation Protocol Summary
 
-3. **Apply mode protocols**
-   - Follow mode-specific interaction patterns
-   - Use mode-defined workflows
-   - Apply mode response style
-   - Set up mode context
+When `/modes {name}` is executed:
 
-4. **Begin interaction**
-   - Start according to mode protocols
-   - Use mode-specific formatting
-   - Apply mode workflows
-   - Maintain mode focus
+1. **Load** - Read mode definition and parse configuration
+2. **Check** - If from spec mode, show warning and confirm
+3. **Apply** - Follow mode protocols, set up context
+4. **Begin** - Start interaction per mode's protocol
 
-## Mode Management Protocol
+### Management Protocol Summary
 
 When `/modes` is executed:
 
-1. **Activate chit-chat mode**
-   - Load chit-chat.md steering
-   - Use diff blocks for progress
-   - Provide numbered choices
-   - Maintain single focus
-
-2. **Detect available modes**
-   - Scan for `kiro-*-mode.md` files
-   - Extract mode metadata
-   - Identify current mode
-
-3. **Present choices**
-   - Show available modes
-   - Offer mode operations
-   - Provide help and comparison
-   - Allow staying in current mode
-
-4. **Handle operations**
-   - Mode switching → Execute `/mode {name}`
-   - View details → Show mode definition
-   - Comparison → Explain differences
-   - Help → Explain mode system
+1. **Activate chit-chat** - Load chit-chat.md, use diff blocks
+2. **Detect modes** - Scan for `kiro-*-mode.md` files
+3. **Present choices** - Show modes, offer operations
+4. **Handle operations** - Switching, viewing, comparison, help
 
 ## Mode and Agent Coordination
 
@@ -182,90 +77,15 @@ When `/modes` is executed:
 - Custom agents: Domain-specific expertise
 
 **They work together:**
-- Modes can activate agents: `/mode spec` then `/agent kiro-master`
+- Modes can activate agents: `/modes spec` then `/agents kiro-master`
 - Agents inherit mode protocols: Agent in spec mode follows spec workflow
 - Context preserved: Switch modes/agents without losing work
 - Layered capabilities: Mode + Agent + Strict mode all active simultaneously
 
-**Coordination patterns:**
-- **Mode transitions** - Switch from exploration (vibe) to planning (spec)
-- **Context sharing** - Modes and agents share relevant information
-- **Conflict resolution** - Priority rules determine behavior
-- **Workflow integration** - Agents work within mode workflows
-
-## Usage Examples
-
-### Switch Kiro Modes
-
-```
-/mode vibe
-```
-
-**Result:** AI switches to Vibe mode - flexible, conversational development. No formal workflows, quick iterations, direct changes.
-
-```
-/mode spec
-```
-
-**Result:** AI switches to Spec mode - structured feature development with requirements, design, and task planning.
-
-### Interactive Mode Management
-
-```
-/modes
-```
-
-**Result:** Chit-chat mode activates, shows available modes, offers comparison and switching options.
-
-### Combined with Agents
-
-```
-/mode spec
-[Work on structured feature planning]
-/agent kiro-master
-[Use kiro-master agent while in spec mode]
-```
-
-**Result:** Spec mode workflow + kiro-master agent capabilities working together.
-
-## Best Practices
-
-### For Mode Users
-
-1. **Choose appropriate mode** - Vibe for exploration, Spec for planning
-2. **Understand mode workflows** - Each mode has different interaction patterns
-3. **Use mode transitions** - Switch modes as your needs change
-4. **Combine with agents** - Modes and agents work together
-5. **Preserve context** - File changes persist across mode switches
-
-### For Mode Development
-
-1. **Clear mode definition** - Comprehensive `.md` with all protocols
-2. **Consistent interaction** - Follow established patterns
-3. **Good examples** - Show how mode works in practice
-4. **Integration rules** - Specify how mode works with agents
-5. **Test thoroughly** - Verify mode activates and functions correctly
-
-## Future Enhancements
-
-**Mode enhancements:**
-- **Custom modes** - User-defined modes beyond vibe/spec
-- **Mode parameters** - `/mode spec --strict --minimal-tests`
-- **Mode presets** - Save mode configurations
-- **Mode history** - Track mode usage patterns
-- **Automated transitions** - Suggest mode switch when appropriate
-
-**Integration enhancements:**
-- **Cross-mode workflows** - Explore in vibe, formalize in spec
-- **Mode-specific agents** - Agents optimized for specific modes
-- **Context preservation** - Enhanced state management across switches
-
-## Notes
+## System Notes
 
-- This system is a **prototype** - Kiro doesn't natively support modes
-- Commands are implemented via **Instruction Alias pattern**
-- System relies on **AI understanding and following instructions**
-- May need **iteration based on actual usage**
+- Prototype system using Instruction Alias pattern
+- Relies on AI understanding and following instructions
 - Works seamlessly with agent system
 
 ---
@@ -273,6 +93,6 @@ When `/modes` is executed:
 **Modes system ready.**
 
 **Quick start:**
-- `/mode vibe` - Flexible development
-- `/mode spec` - Structured planning
+- `/modes vibe` - Flexible development
+- `/modes spec` - Structured planning
 - `/modes` - Interactive mode management

package/build/npm/dist/protocols/agent-activation.mdx

@@ -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 `agent-system.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/dist/protocols/mode-switching.mdx

@@ -0,0 +1,84 @@
+# Mode Switching Protocol
+
+This file contains the detailed instructions for switching Kiro modes. It is referenced by the `/modes {mode_name}` alias in `modes-system.md`.
+
+## Mode Switch Steps
+
+When switching to mode `{mode_name}`:
+
+### Step 1: Load Mode Definition
+
+Read `kiro-{mode_name}-mode.md` from agent-system directory into context.
+
+This file contains:
+- Mode identity and purpose
+- Interaction protocols
+- Workflow patterns (if any)
+- Response style guidelines
+- Testing approaches
+- File organization rules
+- Integration points
+
+### Step 2: Assume Mode Role
+
+For this session, you are in **{mode_name} mode**.
+
+You will:
+- Follow ALL protocols and instructions from `kiro-{mode_name}-mode.md`
+- Apply mode-specific interaction patterns
+- Use capabilities defined in the mode definition
+- Maintain this mode until user switches modes or ends session
+- Override any conflicting instructions with mode protocols
+
+### Step 3: Preserve Context and Check State
+
+**IMPORTANT:** Mode switching preserves:
+- All file changes made in previous mode
+- Conversation history and context
+- Current working state
+- User preferences and settings
+
+**WARNING:** Mode switching does NOT preserve:
+- Workflow state (e.g., which phase you're in)
+- Approval gate status
+- Phase-specific context
+
+**If switching FROM spec mode:**
+Before switching, display warning:
+```
+⚠️ Switching from Spec mode will reset workflow state.
+
+Current Spec state:
+- Phase: [current phase]
+- Requirements: [approved/not approved]
+- Design: [approved/not approved]
+- Tasks: [approved/not approved]
+
+If you return to Spec mode later, you'll need to re-approve documents.
+
+Continue switching to {mode_name} mode? [Yes] [No, stay in Spec mode]
+```
+
+Wait for user confirmation before proceeding.
+
+You are simply changing HOW you interact, not WHAT you're working on.
+
+### Step 4: Begin Interaction
+
+Start interaction according to **{mode_name} mode**'s protocols.
+
+**If switching to spec mode:**
+- Ask user what they want to work on
+- Offer to create new spec or update existing
+- Follow structured workflow (requirements → design → tasks)
+- Use approval gates between phases
+
+**If switching to vibe mode:**
+- Continue with flexible, conversational interaction
+- No formal workflow required
+- Make changes directly when clear
+- Iterate quickly on feedback
+
+---
+
+**You are now in {mode_name} mode. Begin interaction.**

package/build/npm/dist/strict-mode.md

@@ -62,13 +62,14 @@ State changed. Response Protocol now applies.
 ### Command 2: Interactive Control
 
 For interactive strict mode control, use the `/strict` slash command (without parameters).
-This provides a visual interface with buttons to:
+This provides a numbered choice interface to:
 - Enable strict mode
 - Disable strict mode
 - Learn more about strict mode
+- Check current state
 
 **Usage:**
-- Interactive: `/strict` (no parameters, loads `strict.md` steering file with userInput buttons)
+- Interactive: `/strict` (no parameters, loads `strict.md` steering file with numbered options)
 - Direct: `/strict on` or `/strict off` (with state)
 
 ## Use Case Guidelines

package/build/npm/dist/strict.md

@@ -1,12 +1,12 @@
 ---
 inclusion: manual
-description: "Interactive strict mode control with visual buttons for enabling/disabling precision mode"
+description: "Interactive strict mode control with numbered options for enabling/disabling precision mode"
 keywords: ["strict", "precision", "mode", "control"]
 ---
 
 # Strict Mode Control
 
-Interactive control for STRICT_MODE using userInput tool.
+Interactive control for STRICT_MODE using numbered choice pattern.
 
 ## Current State Check
 
@@ -14,11 +14,10 @@ First, determine the current STRICT_MODE state from context.
 
 ## Present Interactive Options
 
-Use userInput tool to show interactive buttons:
+Display the question with numbered options:
 
-```typescript
-userInput({
-  question: `# Strict Mode Control
+```markdown
+# Strict Mode Control
 
 **Current State**: STRICT_MODE = ${current_state}
 
@@ -29,31 +28,16 @@ Strict mode blocks execution on ambiguous input and requires explicit clarificat
 - New component creation establishing patterns
 - Debugging propagated errors from incorrect assumptions
 
-**What would you like to do?**`,
-  options: [
-    {
-      title: "🟢 Enable Strict Mode",
-      description: "Activate precision mode - blocks execution on ambiguous input, requires explicit clarification",
-      recommended: current_state === "OFF"
-    },
-    {
-      title: "🔴 Disable Strict Mode",
-      description: "Return to normal mode - allows reasonable assumptions, faster iteration",
-      recommended: current_state === "ON"
-    },
-    {
-      title: "ℹ️ Learn More",
-      description: "Understand when and how to use strict mode effectively"
-    },
-    {
-      title: "📊 Check Current State",
-      description: "Show current strict mode configuration and status"
-    }
-  ],
-  reason: "strict-mode-control"
-})
+**What would you like to do?**
+
+1. **🟢 Enable Strict Mode** - Activate precision mode - blocks execution on ambiguous input, requires explicit clarification
+2. **🔴 Disable Strict Mode** - Return to normal mode - allows reasonable assumptions, faster iteration
+3. **ℹ️ Learn More** - Understand when and how to use strict mode effectively
+4. **📊 Check Current State** - Show current strict mode configuration and status
 ```
 
+**Note**: Recommend option 1 when current_state is "OFF", recommend option 2 when current_state is "ON".
+
 ## Handle User Selection
 
 Based on user's choice:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-agents",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "AI agent system for Kiro IDE",
   "type": "module",
   "bin": {
@@ -17,7 +17,9 @@
     "test": "bun run scripts/test.ts",
     "clean": "bun run scripts/clean.ts",
     "snapshot": "bun run scripts/snapshot.ts",
-    "finalize": "bun run scripts/finalize.ts",
+    "finalize": "bun run scripts/finalize.ts analyze",
+    "finalize:analyze": "bun run scripts/finalize.ts analyze",
+    "finalize:commit": "bun run scripts/finalize.ts commit",
     "release": "bun run scripts/release.ts"
   },
   "keywords": [