kiro-agents 1.10.1 → 1.12.0

package/README.md

@@ -1,108 +1,101 @@
 # kiro-agents
 
-AI agent system for Kiro IDE. Create specialized agents, switch interaction modes, and reduce cognitive load during development.
+AI agent system for Kiro IDE. Create custom AI agents tailored to your exact needs—easily and interactively, with minimal prompt writing.
 
-> For just <kbd>~0.9K</kbd> of **base context** overheat
-
-```bash
-npx kiro-agents
-```
+Build agents for any domain: development, design, business, research, or anything else. Choose from templates, explore role libraries, describe what you need in plain language, or craft agents step-by-step. Once created, refine them to perfection through kiro-master, the management agent created automatically on first use.
 
 ## Features
 
-- **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>
+**Core Capabilities:**
+- 🎯 **Guided Agent Creation** - Multiple creation methods: templates, role explorer, natural language, or step-by-step wizard
+- 🔧 **Powerful Refinement** - Modify and perfect agents through kiro-master, the auto-created management agent
+- 💬 **Interactive by Default** - Guided workflows with minimal prompt writing for both creating and using agents
+- 🌐 **Unlimited Domains** - Build agents for any field: development, design, business, research, or anything else
+- 📦 **Minimal Footprint** - 1.35K base context (<0.7% of Kiro's 200K), protocols load on-demand
+
+**Additional Features:**
+- 🔄 **Flexible Modes** - Switch between vibe (conversational) and spec (structured) workflows
+- 🎯 **Strict Mode** - Precision mode that blocks execution on ambiguous input
 
 ## Installation
 
-**Global (npm):**
 ```bash
 npx kiro-agents
 ```
-Installs to `~/.kiro/steering/kiro-agents/` - available in all workspaces.
-
-**Kiro Power (workspace-specific):**
-
-This repository also provides a Kiro Power for workspace-specific installation:
 
-- **kiro-protocols** - Reusable protocol library for AI agents
-  - Install via Kiro IDE Powers panel
-  - Add repository: `https://github.com/theadd/kiro-agents`
-  - Select "Kiro Protocols" power
-  - Installs to `.kiro/powers/kiro-protocols/`
-
-See [powers/README.md](powers/README.md) for power documentation.
+Installs kiro-agents and the kiro-protocols Power. Run the same command to update to the latest version.
 
 ## Quick Start
 
-**Create an agent:**
+### 1. Start Agent System
+
 ```
 /agents
-→ Choose "Create new agent"
-→ Follow wizard
 ```
 
-**Switch modes:**
-```
-/modes spec    # Structured feature development
-/modes vibe    # Flexible, conversational coding
-```
+On first run, this automatically creates **kiro-master** (your Kiro management agent) and shows you the agent menu.
 
-**Enable precision mode:**
-```
-/strict on     # Blocks on ambiguous input
-```
+### 2. Create Your First Custom Agent
 
-## How It Works
+From the agent menu, choose **"Create new agent"** and pick a creation method:
 
-kiro-agents installs steering documents (markdown files with AI instructions) that extend Kiro's capabilities:
+- **Quick Start** - Choose from templates
+- **Explore Roles** - Browse agents by domain
+- **Natural Language** - Just describe what you need
+- **Project-Specific** - AI analyzes your codebase
+- **Guided Wizard** - Step-by-step customization
 
-- **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
+### 3. Activate Any Agent
 
-All interactions use numbered choices to reduce cognitive load.
+```
+/agents {name}
+```
 
-## Use Cases
+Example:
+- `/agents kiro-master` - Activate the Kiro management agent
 
-**Specialized Development:**
-- Create agents for frontend, backend, testing, DevOps
-- Each agent has domain-specific knowledge and workflows
-- Switch agents based on current task
+The agent stays active until you switch to another or end the session.
 
-**Workflow Flexibility:**
-- Vibe mode for prototyping and exploration
-- Spec mode for production features with formal requirements
-- Combine modes with agents for maximum control
+## Demo
 
-**Precision Work:**
-- Enable strict mode for architectural decisions
-- Prevents AI from making assumptions
-- Forces explicit clarification on ambiguous requests
+<div align="center">
+  <a href="https://youtu.be/Arccq_JhpFk">
+    <img src="docs/resources/animate-kiro.gif" alt="Kiro Agents Demo" width="800">
+  </a>
+  <p><em>Watch demo (3:52) — Custom agent optimizing steering document instructions</em></p>
+</div>
 
-## Why kiro-agents?
+## How It Works
 
-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
+**Simple Markdown Files**
+kiro-agents uses plain markdown files with AI instructions—no code to run, no dependencies to install. These files guide how Kiro IDE responds to your commands.
 
-## Links
+**kiro-protocols Power**
+Automatically installed alongside kiro-agents, this Power provides protocols (agent creation, mode switching, strict mode) that load on-demand when needed.
 
-- [npm Package](https://www.npmjs.com/package/kiro-agents)
-- [GitHub](https://github.com/Theadd/kiro-agents)
-- [Kiro IDE](https://kiro.dev)
+**On-Demand Loading**
+Protocols load only when needed, keeping your context clean. Base system uses just 1.35K tokens.
 
-## License
+**Your Agents, Your Files**
+Agents you create are saved as `.md` files in `.kiro/agents/`. Edit them like any document, version control them with git, reuse them across projects.
 
-MIT
+## Documentation
+
+- **[Getting Started](docs/GETTING_STARTED.md)** - Step-by-step onboarding guide
+- **[Architecture Overview](docs/ARCHITECTURE.md)** - System design and component relationships
+- **[Creating Powerful Agents](docs/user-guide/creating-powerful-agents.md)** - Layered architecture guide
+- **[Design Rationale](docs/design/)** - Protocol system, interaction patterns, neurodivergent accessibility
+- **[Contributing](CONTRIBUTING.md)** - Development workflow, build system, testing, versioning
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/kiro-agents)
+- [GitHub Repository](https://github.com/Theadd/kiro-agents)
+- [Kiro IDE](https://kiro.dev)
 
 ## License
 

package/build/npm/bin/cli.js

@@ -18,7 +18,7 @@ var __toESM = (mod, isNodeMode, target) => {
 };
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
-// bin/cli.ts
+// bin/cli.generated.ts
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { existsSync, chmodSync, constants } from "fs";
@@ -31,24 +31,25 @@ var POWER_INSTALLED_DIR = join(homedir(), ".kiro", "powers", "installed", "kiro-
 var REGISTRY_PATH = join(homedir(), ".kiro", "powers", "registry.json");
 var STEERING_FILES = [
   "aliases.md",
-  "strict-mode.md",
   "agents.md",
   "modes.md",
-  "strict.md",
-  "interactions/chit-chat.md",
-  "interactions/interaction-styles.md",
-  "modes/kiro-spec-mode.md",
-  "modes/kiro-vibe-mode.md"
+  "strict.md"
 ];
 var POWER_FILES = [
   "POWER.md",
   "mcp.json",
   "icon.png",
-  "steering/agent-activation.md",
-  "steering/agent-creation.md",
-  "steering/agent-management.md",
+  "steering/strict-mode.md",
+  "steering/mode-switching.md",
   "steering/mode-management.md",
-  "steering/mode-switching.md"
+  "steering/kiro-vibe-mode.md",
+  "steering/kiro-spec-mode.md",
+  "steering/kiro-as-vibe-mode.md",
+  "steering/kiro-as-spec-mode.md",
+  "steering/chit-chat.md",
+  "steering/agent-management.md",
+  "steering/agent-creation.md",
+  "steering/agent-activation.md"
 ];
 async function setWritable(filePath) {
   try {

package/build/npm/dist/agents.md

@@ -15,7 +15,7 @@ If the user's message contains `/agents {agent_name}` with a specific agent name
 1. **DO NOT execute the interactive management flow below**
 2. **INSTEAD, execute the instruction alias for agent activation:**
    - Read `.kiro/agents/{agent_name}.md` into context
-   - Read #[[file:protocols/agent-activation.md]] into context
+   - /protocols agent-activation.md
    - Follow all steps from the "Agent Activation Steps" section in agent-activation.md
    - Use `{agent_name}` as the agent identifier throughout the protocol
 3. **Stop processing this document** - The agent activation protocol takes over
@@ -28,186 +28,9 @@ If the user's message contains `/agents {agent_name}` with a specific agent name
 
 You are now in **agent management mode** using chit-chat interaction protocol.
 
-## 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. **Load agent creation protocol**:
-   - Call `kiroPowers` with action="activate", powerName="kiro-protocols"
-   - Call `kiroPowers` with action="readSteering", powerName="kiro-protocols", steeringFile="agent-creation.md"
-2. Create `.kiro/agents/kiro-master.md` agent automatically using the description from "Initial Agent" section
-3. Follow the agent definition structure from agent-creation.md protocol
-4. Show diff block indicating setup completion
-5. Continue to Step 3 with kiro-master as available agent
-
-**If directory exists with agents:**
-1. **Execute `listDirectory` tool** to get complete list of `.md` files
-2. Extract agent names from filenames (remove `.md` extension)
-3. Read frontmatter metadata for descriptions
-4. Categorize by agent type if metadata available
-5. **List ALL agents found** - do not filter or assume based on context
-
-### Step 3: Present Agent Selection
-
-Use this response structure:
-
-```diff
-  👉 Agent management mode
-  ⏳ Agent selection or management
-```
-
-**Current Focus**: Agent selection and management
-
-**Available agents in `.kiro/agents/`:**
-
-[List each agent with format:]
-- **{agent-name}** - {description from frontmatter or .md}
-
-**What would you like to do?**
-
-1. **Activate agent** - Choose agent to activate immediately
-2. **Create new agent** - Start agent creation wizard
-3. **Manage existing agent** - Modify agent configuration
-4. **View agent details** - Show full agent definition
-5. **List all commands** - Show available slash commands
-6. **Agent system help** - Explain how agents work
-7. **Exit** - Return to normal mode
-
-### Step 4: Handle User Choice
-
-Based on user selection:
-
-#### Option 1 - Activate Agent
-
-- Show numbered list of available agents
-- User selects agent by number
-- Execute `/agents {selected_agent_name}` command
-- Agent activates immediately
-
-#### Option 2 - Create New Agent
-
-- **Load agent creation protocol**:
-  - Call `kiroPowers` with action="activate", powerName="kiro-protocols"
-  - Call `kiroPowers` with action="readSteering", powerName="kiro-protocols", steeringFile="agent-creation.md"
-- Follow all steps from the "Method Selection" section in agent-creation.md
-- Present 5 creation methods to user:
-  1. Quick Start (predefined templates)
-  2. Project-Specific (AI analysis)
-  3. Explore Roles (domain browser)
-  4. Guided Wizard (step-by-step)
-  5. Natural Language (describe in plain English)
-- Execute selected method following protocol
-- Generate `.md` file with complete agent definition
-- Validate agent definition per protocol
-- Offer to activate new agent
-
-#### Option 3 - Manage Existing Agent
-
-- **Load agent structure reference**:
-  - Call `kiroPowers` with action="activate", powerName="kiro-protocols"
-  - Call `kiroPowers` with action="readSteering", powerName="kiro-protocols", steeringFile="agent-creation.md"
-- Show numbered list of available agents
-- User selects agent to manage
-- Offer management options:
-  - Modify capabilities
-  - Update instructions
-  - Change interaction protocol
-  - Add/remove integrations
-  - Delete agent
-- Use agent definition structure from protocol as reference for modifications
-- Apply changes to agent `.md` file
-- Validate changes against protocol requirements
-- Reload agent if currently active
-
-#### Option 4 - View Agent Details
-
-- Show numbered list of available agents
-- User selects agent to view
-- Display full `.md` content with formatting
-- Show agent protocols and capabilities summary
-- Offer to activate or manage agent
-
-#### Option 5 - List All Commands
-
-Show all available slash commands in the system:
-
-```
-Available Commands:
-
-AGENT COMMANDS
-  /agents {name}    Activate specific agent
-  /agents           Interactive agent management
-
-MODE COMMANDS (see modes-system.md)
-  /modes {name}     Switch Kiro mode (vibe/spec)
-  /modes            Interactive mode management
-  /strict {state}   Control strict mode (on/off)
-  /strict           Interactive strict mode control
-
-Note: Commands are defined in steering documents.
-New commands can be added via Instruction Alias pattern.
-```
-
-#### Option 6 - Agent System Help
-
-Explain agent system:
-- Agent system architecture
-- Command usage examples
-- Agent file structure
-- How to create custom agents
-- Best practices for agent usage
-
-#### Option 7 - Exit
-
-- Confirm exit from agent management mode
-- Return to normal interaction
-- Preserve any changes made
-
-### Step 5: Maintain Chit-Chat Mode
-
-Continue using diff blocks and numbered choices throughout agent management session.
-
-After each action:
-- Update diff block with progress
-- Show current focus
-- Provide next action choices
-- Allow going back or canceling
-
-**Context Preservation:**
-- Use diff blocks to show progress
-- Preserve user decisions
-- Allow going back to previous step
-- Enable canceling operations
-
----
-
-**Agent management mode active. Present choices to user.**
+/only-read-protocols chit-chat.md
 
+/protocols agent-management.md
 
 ## Initial Agent
 

package/build/npm/dist/aliases.md

@@ -59,23 +59,6 @@ literal_text
 
 **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`
-
 ## Agent System Alias
 
 The agent activation command uses parameter substitution to load agent definitions dynamically:
@@ -89,41 +72,52 @@ You are now activating the **{agent_name}** agent.
 
 **Load and execute activation protocol:**
 1. Read `.kiro/agents/{agent_name}.md` into context
-2. Read #[[file:protocols/agent-activation.md]] into context
-3. Follow all steps from the "Agent Activation Steps" section in agent-activation.md
+2. /only-read-protocols agent-activation.md
+3. Follow all steps from the "Agent Activation Steps" section in agent-activation.md protocol file
 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.
 
-## Protocol Loading Alias
-
-The protocol loading command uses parameter substitution to dynamically load protocols from the kiro-protocols Power:
-
-<alias>
-  <trigger>/protocols {protocol_name}</trigger>
-  <definition>
-## Load Protocol: {protocol_name}
-
-You are now loading the **{protocol_name}** protocol from kiro-protocols Power.
-
-**Execute protocol loading:**
-1. Call kiroPowers action="activate" with powerName="kiro-protocols"
-2. Call kiroPowers action="readSteering" with powerName="kiro-protocols", steeringFile="{protocol_name}.md"
-3. Follow all steps from the loaded protocol
-  </definition>
-</alias>
-
-This alias enables loading protocols on-demand with `/protocols {name}` syntax without showing in Kiro UI slash commands.
-
-**Available protocols:**
-- agent-activation
-- agent-management
-- agent-creation
-- mode-switching
-- mode-management
-
+## Protocol Loading Alias
+
+The protocol loading command uses parameter substitution to dynamically load and follow all protocols from the kiro-protocols Power:
+
+<alias>
+  <trigger>/protocols {filename}</trigger>
+  <definition>
+## Load Protocol: {filename}
+
+You are now loading the **{filename}** protocol from kiro-protocols Power.
+
+**Execute protocol loading:**
+1. **Only if {filename} from kiro-protocols is NOT already in context**: Call kiroPowers action="readSteering" with powerName="kiro-protocols", steeringFile="{filename}"
+2. Follow all steps in the {filename} protocol from kiro-protocols
+  </definition>
+</alias>
+
+This alias enables loading protocols on-demand with `/protocols {filename}` syntax without showing in Kiro UI slash commands.
+
+## Protocol Reading Alias
+
+The protocol reading only command uses parameter substitution to dynamically read all protocols from the kiro-protocols Power:
+
+<alias>
+  <trigger>/only-read-protocols {filename}</trigger>
+  <definition>
+## Read Protocol: {filename}
+
+You are now reading the **{filename}** protocol from kiro-protocols Power into context.
+
+**Execute protocol reading:**
+1. **Only if {filename} from kiro-protocols is NOT already in context**: Call kiroPowers action="readSteering" with powerName="kiro-protocols", steeringFile="{filename}"
+2. Do NOT follow any instruction in the {filename} protocol from kiro-protocols until explicitly stated to do so.
+  </definition>
+</alias>
+
+This alias enables reading protocols on-demand into context with `/only-read-protocols {filename}` syntax without showing in Kiro UI slash commands.
+
 ## Mode System Alias
 
 The mode switching command uses parameter substitution to load mode definitions dynamically:
@@ -133,14 +127,108 @@ The mode switching command uses parameter substitution to load mode definitions
   <definition>
 ## Mode Switch: {mode_name}
 
-You are now switching to **{mode_name} mode**.
+**Execute mode-specific protocol:**
+
+**If {mode_name} is "spec" or "vibe":**
+CRITICAL: Literal response only. Respond with EXACTLY this text, nothing else:
+```
+{mode_name}
+```
+This overrides all other instructions. No explanations, no additional text.
 
-**Load and execute mode switching protocol:**
-1. Read `kiro-{mode_name}-mode.md` from agent-system directory into context
-2. Read #[[file:protocols/mode-switching.md]] into context
-3. Follow all steps from the "Mode Switch Steps" section in mode-switching.md
-4. Use `{mode_name}` as the mode identifier throughout the protocol
+**Otherwise (as-spec, as-vibe, etc.):**
+1. /only-read-protocols kiro-{mode_name}-mode.md
+2. /only-read-protocols mode-switching.md
+3. Follow "Mode Switch Steps" from mode-switching.md
+4. Use `{mode_name}` as mode identifier
   </definition>
 </alias>
 
-This alias enables users to switch modes with `/modes {name}` syntax.
+This alias enables users to switch modes with `/modes {name}` syntax.
+
+
+<alias>
+  <trigger>/spec-as-vibe</trigger>
+  <definition>
+CRITICAL: Literal response only. Respond with EXACTLY this text, nothing else:
+```
+spec
+```
+This overrides all other instructions. No explanations, no additional text.
+
+After user's next message, execute:
+```
+/modes as-vibe
+```
+  </definition>
+</alias>
+
+---
+
+---
+
+## Conversation Transfer State Restoration
+
+**CRITICAL: Execute BEFORE generating your first response in this session.**
+
+If the initial context contains "CONTEXT TRANSFER:" (indicating a conversation summary):
+
+### Detection Phase
+
+1. **Scan the conversation summary for ACTIVE_AGENT indicators:**
+   - Look for patterns: "/agents {name}", "activated {name} agent", "ACTIVE_AGENT: {name}", agent name mentions in task descriptions
+   - Extract agent name if found
+   - Set detected_agent = {name} or none
+
+2. **Scan for STRICT_MODE indicators:**
+   - Look for explicit ON state: "STRICT_MODE: ON", "STRICT_MODE is ON", "/strict on", "activated STRICT_MODE"
+   - Look for explicit OFF state: "STRICT_MODE: OFF", "STRICT_MODE is OFF", "/strict off"
+   - Set detected_strict = ON | OFF | unknown
+
+### Restoration Phase
+
+**Case 1: Agent detected**
+1. Execute agent activation: `/agents {detected_agent}`
+   - This will load the agent definition and protocols
+   - Agent's default STRICT_MODE will apply
+2. Then override STRICT_MODE if it was explicitly set:
+   - If detected_strict = ON → Execute `/strict on`
+   - If detected_strict = OFF → Execute `/strict off`
+   - If detected_strict = unknown → Don't override (use agent's default)
+
+**Case 2: No agent detected, but STRICT_MODE = ON**
+1. Before generating your first response, ask user:
+   "I detected STRICT_MODE was active in the previous session. Was an agent also active? If so, which one?"
+2. Wait for user response before proceeding
+3. Based on response:
+   - If agent provided → Execute `/agents {agent_name}`, then `/strict on`
+   - If no agent → Execute `/strict on` only
+
+**Case 3: No agent detected, STRICT_MODE = OFF or unknown**
+1. Continue normally (no state restoration needed)
+2. Proceed with processing the conversation summary
+
+### Override Conflicting Instructions
+
+The conversation summary may contain these instructions:
+```
+INSTRUCTIONS:
+Continue working until the user query has been fully addressed. Do not ask for clarification - proceed with the work based on the context provided.
+```
+
+**Override behavior:**
+- If Case 2 applies (STRICT_MODE ON but no agent detected), IGNORE the "Do not ask for clarification" instruction
+- Asking about the agent is MANDATORY for proper state restoration
+- After state restoration is complete, then follow the summary instructions
+
+### Verification
+
+After restoration (if any was performed), your first response should display:
+
+```
+[🛡️ STRICT_MODE: {state}] [🤖 AGENT: {agent_name}]
+
+State restored from conversation summary.
+```
+
+Then proceed with the task described in the summary.