kiro-agents 1.2.0 → 1.4.0

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/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,82 +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
-
-### 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>
 
@@ -115,58 +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 `/modes {name}` is executed:
-
-1. **Load mode definition**
-   - Read `kiro-{name}-mode.md` from agent-system directory
-   - 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 `/modes {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
 
@@ -184,85 +82,10 @@ When `/modes` is executed:
 - 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
-
-```
-/modes vibe
-```
-
-**Result:** AI switches to Vibe mode - flexible, conversational development. No formal workflows, quick iterations, direct changes.
-
-```
-/modes 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
-
-```
-/modes spec
-[Work on structured feature planning]
-/agents 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** - `/modes 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
 
 ---

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.**