kiro-agents 1.3.0 → 1.5.0

package/README.md

@@ -1,266 +1,95 @@
 # kiro-agents
 
-Advanced AI agent system for Kiro IDE that enhances your development workflow with minimal cognitive overhead.
-
-## What is kiro-agents?
-
-kiro-agents is a steering document system that extends Kiro IDE with:
-
-- **Agent System** - Create and manage specialized AI agents with `/agent` and `/agents` commands
-- **Mode System** - Switch between interaction styles with `/mode` command (vibe/spec modes)
-- **Strict Mode** - Precision mode for experimental development with `/strict` command
-- **Interactive Workflows** - Choice-based interactions that minimize cognitive load
-- **Progressive Enhancement** - Start minimal, add agents as needed
-
-## Installation
-
-### Option 1: Global Installation (npm)
+AI agent system for Kiro IDE. Create specialized agents, switch interaction modes, and reduce cognitive load during development.
 
 ```bash
 npx kiro-agents
-# or
-bunx kiro-agents
-```
-
-This installs steering documents to `~/.kiro/steering/` (global, available in all workspaces).
-
-### Option 2: Workspace Installation (Kiro Power)
-
-1. Open Kiro IDE
-2. Open Powers panel (Ghosty icon ⚡)
-3. Click "Add power from GitHub"
-4. Enter: `https://github.com/theadd/kiro-agents`
-5. Click Install
-
-This installs to `.kiro/powers/kiro-agents/` (workspace-specific).
-
-**Differences:**
-- **npm**: Global installation, available in all workspaces
-- **Power**: Workspace-specific, auto-updates, better Kiro integration
-
-## Core Features
-
-### Agent System
-
-Create specialized AI agents for different tasks. Each agent has:
-
-- Defined capabilities and responsibilities
-- Custom interaction protocols
-- Specific workflows and tools
-- Integration with other agents
-
-**Commands:**
-- `/agents` - Interactive agent management (visual menu)
-- `/agents {name}` - Activate specific agent directly
-
-**Example workflow:**
-```
-User: /agents
-AI: [Shows available agents with numbered choices]
-User: 2 (Create new agent)
-AI: [Guides through agent creation wizard]
 ```
 
-Agents are stored in `.kiro/agents/` and can be:
-- Created interactively through wizard
-- Modified and updated
-- Activated on-demand
-- Coordinated with other agents
-
-### Mode System
-
-Switch between interaction styles based on your needs:
-
-**Vibe Mode** - Flexible, conversational development
-- Quick iterations and prototyping
-- Direct code changes
-- Exploratory development
-- Minimal ceremony
-
-**Spec Mode** - Structured feature development
-- Formal requirements (EARS/INCOSE compliant)
-- Design with correctness properties
-- Task-based implementation
-- Property-based testing focus
-
-**Commands:**
-- `/modes` - Interactive mode management (visual menu)
-- `/modes vibe` - Switch to flexible development
-- `/modes spec` - Switch to structured planning
-
-### Strict Mode
-
-Precision mode for experimental or critical development:
-
-- Blocks execution on ambiguous input
-- Requires explicit clarification
-- Prevents assumption propagation
-- Ideal for architectural decisions
-
-**Commands:**
-- `/strict` - Interactive control (visual buttons)
-- `/strict on` - Activate precision mode
-- `/strict off` - Return to normal mode
-
-### Interactive Workflows
-
-All interactions use choice-based patterns:
+## Features
 
-- Numbered options (typically 4-6, up to 16 when needed)
-- Visual progress indicators (diff blocks)
-- Single focus per interaction
-- Minimal cognitive load
+- **Agents** - Specialized AI personas with defined capabilities (`/agents`)
+- **Modes** - Switch between vibe (flexible) and spec (structured) workflows (`/modes`)
+- **Strict Mode** - Precision mode that blocks on ambiguity (`/strict`)
+- **Zero Config** - Works immediately after installation ⇨ <kbd>/agents</kbd>
 
-This design reduces decision fatigue and maintains context during long conversations.
-
-## How It Works
-
-kiro-agents provides steering documents that Kiro loads to enhance AI capabilities:
-
-**npm installation:**
-- Installs to `~/.kiro/steering/` (global)
-- Available in all workspaces
-- Manual updates via re-running npx/bunx
-
-**Power installation:**
-- Installs to `.kiro/powers/kiro-agents/` (workspace)
-- Auto-updates from GitHub
-- Better integration with Kiro ecosystem
-- Keyword-based activation
-
-Both methods provide:
-1. New slash commands (`/agents`, `/modes`, `/strict`)
-2. Protocols for AI behavior
-3. Agent and mode systems
-4. Optimized interactions for reduced cognitive load
-
-The system adds minimal overhead while enabling progressive enhancement.
-
-## File Structure After Installation
-
-**npm installation** (`~/.kiro/steering/`):
-```
-~/.kiro/steering/
-├── agent-system.md
-├── modes-system.md
-└── agent-system/
-    ├── strict-mode.md
-    ├── kiro-spec-mode.md
-    ├── kiro-vibe-mode.md
-    ├── interactions/
-    └── tools/
-```
+## Installation
 
-**Power installation** (`.kiro/powers/kiro-agents/`):
-```
-.kiro/powers/kiro-agents/
-├── POWER.md                     # Power metadata
-├── mcp.json                     # MCP server config (empty for now)
-└── steering/
-    ├── agent-system.md          # Core system (always loaded)
-    ├── agents.md                # Interactive menu (manual)
-    ├── modes-system.md          # Core system (always loaded)
-    ├── modes.md                 # Interactive menu (manual)
-    ├── strict-mode.md           # Core system (always loaded)
-    ├── strict.md                # Interactive control (manual)
-    ├── interactions/            # Interaction patterns
-    └── modes/                   # Mode definitions
+**Global (npm):**
+```bash
+npx kiro-agents
 ```
+Installs to `~/.kiro/steering/kiro-agents/` - available in all workspaces.
 
-npm files are read-only after installation. Power files managed by Kiro.
+<!--
+**Workspace (Kiro Power):**
+1. Open Powers panel in Kiro IDE
+2. Add from GitHub: `https://github.com/theadd/kiro-agents`
 
-## Usage Examples
+Installs to `.kiro/powers/kiro-agents/` - auto-updates, workspace-specific.
+-->
 
-### Creating a Custom Agent
+## Quick Start
 
+**Create an agent:**
 ```
-User: /agents
-AI: [Shows agent management options]
-User: 2 (Create new agent)
-AI: What type of agent? [Shows options]
-User: 1 (Code-focused agent)
-AI: [Collects name, capabilities, workflows]
-AI: Agent created! Activate now? [Yes/No]
+/agents
+→ Choose "Create new agent"
+→ Follow wizard
 ```
 
-### Switching Modes
-
-```
-User: /modes spec
-AI: [Loads spec mode protocols]
-AI: What feature do you want to work on?
-User: User authentication system
-AI: [Guides through requirements → design → tasks]
-```
-
-### Using Strict Mode
-
+**Switch modes:**
 ```
-User: /strict on
-AI: Strict mode activated
-User: Add caching to the API
-AI: [Asks clarifying questions about cache strategy, TTL, invalidation, etc.]
+/modes spec    # Structured feature development
+/modes vibe    # Flexible, conversational coding
 ```
 
-### Agent Coordination
-
+**Enable precision mode:**
 ```
-User: /modes spec
-[Work on feature planning]
-User: /agents kiro-master
-[Use kiro-master capabilities while in spec mode]
+/strict on     # Blocks on ambiguous input
 ```
 
-## Key Benefits
+## How It Works
 
-**Minimal Initial Overhead**
-- Core system adds small context footprint
-- Agents created progressively as needed
-- Only load what you use
+kiro-agents installs steering documents (markdown files with AI instructions) that extend Kiro's capabilities:
 
-**Reduced Cognitive Load**
-- Choice-based interactions
-- Visual progress tracking
-- Single focus per message
-- Clear context maintenance
+- **Agents** - Stored in `.kiro/agents/{name}.md`, activated via `/agents {name}`
+- **Modes** - Define interaction style (vibe = flexible, spec = structured)
+- **Strict Mode** - Requires explicit clarification before execution
 
-**Flexible Workflows**
-- Switch between modes as needs change
-- Combine modes with agents
-- Adapt to your working style
+All interactions use numbered choices to reduce cognitive load.
 
-**Extensible System**
-- Create custom agents for your needs
-- Define specialized workflows
-- Integrate with existing Kiro features
+## Use Cases
 
-## Advanced Features
+**Specialized Development:**
+- Create agents for frontend, backend, testing, DevOps
+- Each agent has domain-specific knowledge and workflows
+- Switch agents based on current task
 
-### Agent Coordination
+**Workflow Flexibility:**
+- Vibe mode for prototyping and exploration
+- Spec mode for production features with formal requirements
+- Combine modes with agents for maximum control
 
-Multiple agents can work together:
-- Handoff procedures between agents
-- Context sharing across agents
-- Conflict resolution protocols
-- Collaborative workflows
+**Precision Work:**
+- Enable strict mode for architectural decisions
+- Prevents AI from making assumptions
+- Forces explicit clarification on ambiguous requests
 
-### Mode + Agent Combinations
+## Why kiro-agents?
 
-Modes and agents work together:
-- Agents inherit mode protocols
-- Mode workflows use agent capabilities
-- Context preserved across switches
+Traditional AI assistants overwhelm you with context and options. kiro-agents:
+- Starts minimal, grows with your needs
+- Uses numbered choices instead of open-ended questions
+- Maintains single focus per interaction
+- Reduces decision fatigue during long sessions
 
-## Contributing
+## Links
 
-This is an experimental system that relies on AI understanding and following instructions. Feedback and improvements welcome!
+- [npm Package](https://www.npmjs.com/package/kiro-agents)
+- [GitHub](https://github.com/Theadd/kiro-agents)
+- [Kiro IDE](https://kiro.dev)
 
 ## License
 
 MIT
-
-## Links
-
-- [GitHub Repository](https://github.com/theadd/kiro-agents)
-- [npm Package](https://www.npmjs.com/package/kiro-agents)
-- [Kiro IDE](https://kiro.dev)

package/build/npm/bin/cli.js

@@ -27,8 +27,6 @@ var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname(__filename2);
 var INSTALL_DIR = join(homedir(), ".kiro", "steering", "kiro-agents");
 var FILES_TO_INSTALL = [
-  "agent-system.md",
-  "modes-system.md",
   "strict-mode.md",
   "agents.md",
   "modes.md",

package/build/npm/dist/aliases.md

@@ -75,3 +75,46 @@ spec
 ````
 
 User types: `/spec` → AI responds: `spec`
+
+## Agent System Alias
+
+The agent activation command uses parameter substitution to load agent definitions dynamically:
+
+<alias>
+  <trigger>/agents {agent_name}</trigger>
+  <definition>
+## Agent Activation: {agent_name}
+
+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
+4. Use `{agent_name}` as the agent identifier throughout the protocol
+  </definition>
+</alias>
+
+This alias enables users to activate any agent with `/agents {name}` syntax.
+
+
+## Mode System Alias
+
+The mode switching command uses parameter substitution to load mode definitions dynamically:
+
+<alias>
+  <trigger>/modes {mode_name}</trigger>
+  <definition>
+## Mode Switch: {mode_name}
+
+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
+4. Use `{mode_name}` as the mode identifier throughout the protocol
+  </definition>
+</alias>
+
+This alias enables users to switch modes with `/modes {name}` syntax.

package/build/npm/dist/modes.md

@@ -8,93 +8,142 @@ keywords: ["modes", "vibe", "spec", "workflow", "interactive"]
 
 You are now in **mode management** using chit-chat interaction protocol.
 
-## Step 1: Load Chit-Chat Mode
+## Mode Management Steps
+
+When entering mode management:
+
+### Step 1: Load Chit-Chat Mode
+
+Apply protocols from `chit-chat.md` steering document:
+- Use diff blocks to show progress
+- Provide numbered choice lists (4-6 options)
+- Maintain single focus per message
+- Use visual formatting (bold, code blocks, lists)
+
+Begin with a diff block showing:
+```diff
+  👉 Mode management
+  ⏳ Mode selection
+```
+
+### Step 2: Detect Available Modes
+
+Scan agent-system directory for `kiro-*-mode.md` files:
+- Extract mode names from filenames (remove `kiro-` prefix and `-mode.md` suffix)
+- Read frontmatter for descriptions
+- Identify current mode from context (if any)
+
+**Available Kiro modes:**
+- **vibe** - Flexible, conversational development assistance
+- **spec** - Structured feature development with requirements, design, and tasks
+
+### Step 3: Present Mode Selection
+
+Use this response structure:
+
+```diff
+  👉 Mode management
+  ⏳ Mode selection
+```
+
+**Current mode:** [current_mode or "none"]
+
+**Available Kiro modes:**
+
+- **vibe** - Flexible, conversational development assistance
+- **spec** - Structured feature development with requirements, design, and tasks
+
+**What would you like to do?**
+
+1. **Switch to vibe mode** - Flexible development and quick iterations
+2. **Switch to spec mode** - Structured feature planning and implementation
+3. **View mode details** - See full mode capabilities and protocols
+4. **Mode comparison** - Understand differences between modes
+5. **Stay in current mode** - Continue with current mode
+6. **Help** - Learn about mode system
+
+### Step 4: Handle User Choice
+
+Based on user selection:
+
+#### Option 1 - Switch to vibe
+
+- Execute `/modes vibe` command
+- Load vibe mode protocols
+- Begin flexible interaction
+
+#### Option 2 - Switch to spec
+
+- Execute `/modes spec` command
+- Load spec mode protocols
+- Begin structured workflow
+
+#### Option 3 - View mode details
+
+- Show numbered list of modes
+- User selects mode to view
+- Display full mode definition
+- Explain capabilities and use cases
+- Offer to switch to that mode
+
+#### Option 4 - Mode comparison
+
+- Show side-by-side comparison:
+  - **Vibe Mode**: Flexible, conversational, quick iterations, no formal workflow
+  - **Spec Mode**: Structured workflow with requirements → design → tasks, approval gates
+- Explain when to use each mode:
+  - Use vibe for: Quick fixes, exploration, prototyping, iterative development
+  - Use spec for: Complex features, team collaboration, formal planning, documentation
+- Highlight key differences:
+  - Workflow: None vs. Structured phases
+  - Approval: Direct changes vs. Approval gates
+  - Documentation: Minimal vs. Comprehensive
+- Help user choose appropriate mode
+
+#### Option 5 - Stay in current mode
+
+- Confirm staying in current mode
+- Return to normal interaction
+- Preserve current state
+
+#### Option 6 - Help
+
+Explain mode system:
+- **What are modes?** - Different interaction styles for different workflows
+- **How to switch?** - Use `/modes {name}` or `/modes` for interactive menu
+- **Mode benefits:**
+  - Vibe: Fast iteration, flexible approach
+  - Spec: Structured planning, comprehensive documentation
+- **Mode coordination:**
+  - Modes can be combined with agents
+  - File changes preserved when switching
+  - Workflow state resets when switching
+- **Usage examples:**
+  - Quick bug fix → Use vibe mode
+  - New feature with requirements → Use spec mode
+  - Refactoring existing code → Use vibe mode
+  - Team feature with documentation → Use spec mode
+
+### Step 5: Maintain Chit-Chat Mode
+
+Continue using diff blocks and numbered choices throughout mode 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
+
+---
+
+**Mode management 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)
-- Maintain single focus per message
-- Use visual formatting (bold, code blocks, lists)
-
-## Step 2: Detect Available Modes
-
-Scan agent-system directory for `kiro-*-mode.md` files:
-- Extract mode names from filenames
-- Read frontmatter for descriptions
-- Identify current mode from context
-
-## Step 3: Present Mode Selection
-
-Use this response structure:
-
-```diff
-  👉 Mode management
-  ⏳ Mode selection
-```
-
-**Current mode:** [current_mode]
-
-**Available Kiro modes:**
-
-- **vibe** - Flexible, conversational development assistance
-- **spec** - Structured feature development with requirements, design, and tasks
-
-**What would you like to do?**
-
-1. **Switch to vibe mode** - Flexible development and quick iterations
-2. **Switch to spec mode** - Structured feature planning and implementation
-3. **View mode details** - See full mode capabilities and protocols
-4. **Mode comparison** - Understand differences between modes
-5. **Stay in current mode** - Continue with current mode
-6. **Help** - Learn about mode system
-
-## Step 4: Handle User Choice
-
-Based on user selection:
-
-**Option 1 - Switch to vibe:**
-- Execute `/modes vibe` command
-- Load vibe mode protocols
-- Begin flexible interaction
-
-**Option 2 - Switch to spec:**
-- Execute `/modes spec` command
-- Load spec mode protocols
-- Begin structured workflow
-
-**Option 3 - View mode details:**
-- Show numbered list of modes
-- User selects mode to view
-- Display full mode definition
-- Explain capabilities and use cases
-- Offer to switch to that mode
-
-**Option 4 - Mode comparison:**
-- Show side-by-side comparison
-- Explain when to use each mode
-- Highlight key differences
-- Help user choose appropriate mode
-
-**Option 5 - Stay in current mode:**
-- Confirm staying in current mode
-- Return to normal interaction
-- Preserve current state
-
-**Option 6 - Help:**
-- Explain mode system
-- Show switching commands
-- Describe mode benefits
-- Provide usage examples
-
-## Step 5: Maintain Chit-Chat Mode
-
-Continue using diff blocks and numbered choices throughout mode management.
-
-After each action:
-- Update diff block with progress
-- Show current focus
-- Provide next action choices
-- Allow going back or canceling
 
 ---
 

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

@@ -1,6 +1,6 @@
 # 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`.
+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
 

package/build/npm/dist/protocols/mode-management.mdx

@@ -0,0 +1,139 @@
+# Mode Management Protocol
+
+This file contains the detailed instructions for interactive mode management. It is referenced when `/modes` is executed without parameters.
+
+## Mode Management Steps
+
+When entering mode management:
+
+### Step 1: Load Chit-Chat Mode
+
+Apply protocols from `chit-chat.md` steering document:
+- Use diff blocks to show progress
+- Provide numbered choice lists (4-6 options)
+- Maintain single focus per message
+- Use visual formatting (bold, code blocks, lists)
+
+Begin with a diff block showing:
+```diff
+  👉 Mode management
+  ⏳ Mode selection
+```
+
+### Step 2: Detect Available Modes
+
+Scan agent-system directory for `kiro-*-mode.md` files:
+- Extract mode names from filenames (remove `kiro-` prefix and `-mode.md` suffix)
+- Read frontmatter for descriptions
+- Identify current mode from context (if any)
+
+**Available Kiro modes:**
+- **vibe** - Flexible, conversational development assistance
+- **spec** - Structured feature development with requirements, design, and tasks
+
+### Step 3: Present Mode Selection
+
+Use this response structure:
+
+```diff
+  👉 Mode management
+  ⏳ Mode selection
+```
+
+**Current mode:** [current_mode or "none"]
+
+**Available Kiro modes:**
+
+- **vibe** - Flexible, conversational development assistance
+- **spec** - Structured feature development with requirements, design, and tasks
+
+**What would you like to do?**
+
+1. **Switch to vibe mode** - Flexible development and quick iterations
+2. **Switch to spec mode** - Structured feature planning and implementation
+3. **View mode details** - See full mode capabilities and protocols
+4. **Mode comparison** - Understand differences between modes
+5. **Stay in current mode** - Continue with current mode
+6. **Help** - Learn about mode system
+
+### Step 4: Handle User Choice
+
+Based on user selection:
+
+#### Option 1 - Switch to vibe
+
+- Execute `/modes vibe` command
+- Load vibe mode protocols
+- Begin flexible interaction
+
+#### Option 2 - Switch to spec
+
+- Execute `/modes spec` command
+- Load spec mode protocols
+- Begin structured workflow
+
+#### Option 3 - View mode details
+
+- Show numbered list of modes
+- User selects mode to view
+- Display full mode definition
+- Explain capabilities and use cases
+- Offer to switch to that mode
+
+#### Option 4 - Mode comparison
+
+- Show side-by-side comparison:
+  - **Vibe Mode**: Flexible, conversational, quick iterations, no formal workflow
+  - **Spec Mode**: Structured workflow with requirements → design → tasks, approval gates
+- Explain when to use each mode:
+  - Use vibe for: Quick fixes, exploration, prototyping, iterative development
+  - Use spec for: Complex features, team collaboration, formal planning, documentation
+- Highlight key differences:
+  - Workflow: None vs. Structured phases
+  - Approval: Direct changes vs. Approval gates
+  - Documentation: Minimal vs. Comprehensive
+- Help user choose appropriate mode
+
+#### Option 5 - Stay in current mode
+
+- Confirm staying in current mode
+- Return to normal interaction
+- Preserve current state
+
+#### Option 6 - Help
+
+Explain mode system:
+- **What are modes?** - Different interaction styles for different workflows
+- **How to switch?** - Use `/modes {name}` or `/modes` for interactive menu
+- **Mode benefits:**
+  - Vibe: Fast iteration, flexible approach
+  - Spec: Structured planning, comprehensive documentation
+- **Mode coordination:**
+  - Modes can be combined with agents
+  - File changes preserved when switching
+  - Workflow state resets when switching
+- **Usage examples:**
+  - Quick bug fix → Use vibe mode
+  - New feature with requirements → Use spec mode
+  - Refactoring existing code → Use vibe mode
+  - Team feature with documentation → Use spec mode
+
+### Step 5: Maintain Chit-Chat Mode
+
+Continue using diff blocks and numbered choices throughout mode 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
+
+---
+
+**Mode management active. Present choices to user.**

package/build/npm/dist/protocols/mode-switching.mdx

@@ -1,84 +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.**
+# 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/package.json

@@ -1,7 +1,15 @@
 {
   "name": "kiro-agents",
-  "version": "1.3.0",
-  "description": "AI agent system for Kiro IDE",
+  "version": "1.5.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": {
+    "type": "git",
+    "url": "https://github.com/Theadd/kiro-agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Theadd/kiro-agents/issues"
+  },
   "type": "module",
   "bin": {
     "kiro-agents": "build/npm/bin/cli.js"
@@ -24,7 +32,22 @@
   },
   "keywords": [
     "kiro",
-    "ai-agents"
+    "kiro-ide",
+    "ai-agents",
+    "ai-assistant",
+    "agent-system",
+    "development-tools",
+    "ide-extension",
+    "ai-workflow",
+    "code-assistant",
+    "developer-productivity",
+    "steering-documents",
+    "ai-modes",
+    "strict-mode",
+    "vibe-mode",
+    "spec-mode",
+    "typescript",
+    "bun"
   ],
   "author": "R. Beltran",
   "license": "MIT",