kiro-agents 1.11.0 → 1.12.0

package/README.md

@@ -1,229 +1,101 @@
 # kiro-agents
 
-AI agent system for Kiro IDE with specialized agents, interaction modes, and protocol-driven workflows.
+AI agent system for Kiro IDE. Create custom AI agents tailored to your exact needs—easily and interactively, with minimal prompt writing.
 
-> **Zero-prompt interaction (default)** — Chit-chat protocol provides numbered choices for all interactions. Agents can be created with or without this interaction style.
->
-> **Minimal footprint** — ~0.9K base context, protocols load on-demand.
-
-```bash
-npx kiro-agents
-```
-
-<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) — Protocol-driven agent creation with zero-prompt interaction</em></p>
-</div>
+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
 
-### Agent System
-Create specialized agents with defined capabilities and workflows. Agents are stored as markdown files in `.kiro/agents/` and activated via `/agents {name}`.
-
-**Layered protocol architecture** makes agents all-powerful: structured boundaries at top levels provide clear responsibilities, while open-ended inner levels leverage SOTA model creativity to generate optimal implementations. You specify WHAT (roles, capabilities), the AI determines HOW (architecture, workflows). See [Creating All-Powerful Agents](docs/user-guide/creating-powerful-agents.md) for details.
-
-- **Interactive creation** - Guided wizard with 5 creation methods
-- **Domain specialization** - Frontend, backend, testing, DevOps, documentation
-- **AI-generated architecture** - Model creates optimal agent structure from your specifications
-- **Persistent definitions** - Reusable across sessions and projects
-
-### Mode System
-Switch between workflow structures based on development needs:
-
-- **`vibe`** - Flexible, fast-paced development with Kiro tools
-- **`spec`** - Structured feature development (requirements → design → tasks) with Kiro tools
-- **`as-vibe`** - Vibe workflow, keeps current tools (agent superpowers)
-- **`as-spec`** - Spec workflow, keeps current tools (agent superpowers)
-
-Modes preserve file changes but reset workflow state. Combine with agents for specialized tools + preferred workflow structure.
-
-### Strict Mode
-Precision mode that blocks execution on ambiguous input. Prevents assumption propagation in experimental or architectural work.
-
-- **Explicit clarification** - Forces questions instead of guesses
-- **Assumption prevention** - Stops errors before they spread
-- **Optional activation** - Defaults to OFF, enable with `/strict on`
+**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
 
-### Chit-Chat Interaction Protocol
-Structured interaction optimized for reduced cognitive load (default for all agents):
-
-- **Numbered choices** - Pre-structured options eliminate prompt writing
-- **Diff blocks** - Visual progress tracking and context preservation
-- **Single focus** - One concept per message prevents overwhelm
-- **Full control + simplicity** - Navigate complex workflows without writing prompts
-- **ADHD-optimized** - Designed for neurodivergent users, benefits everyone
-- **Optional** - Agents can be created with custom interaction styles if needed
+**Additional Features:**
+- 🔄 **Flexible Modes** - Switch between vibe (conversational) and spec (structured) workflows
+- 🎯 **Strict Mode** - Precision mode that blocks execution on ambiguous input
 
 ## Installation
 
-**Global installation (recommended):**
 ```bash
 npx kiro-agents
 ```
 
-Installs to `~/.kiro/steering/kiro-agents/` and `~/.kiro/powers/kiro-protocols/` — available in all workspaces.
-
-**What gets installed:**
-- Core system files (aliases, protocols, interaction patterns)
-- kiro-protocols Power (reusable protocol library)
-- Automatic power registration in Kiro IDE
+Installs kiro-agents and the kiro-protocols Power. Run the same command to update to the latest version.
 
 ## Quick Start
 
-### 1. Create Your First Agent
+### 1. Start Agent System
 
 ```
 /agents
 ```
 
-Interactive wizard with 5 creation methods:
-1. **Quick Start** - Predefined templates (frontend, backend, testing, etc.)
-2. **Project-Specific** - AI analyzes your codebase
-3. **Explore Roles** - Browse domain categories
-4. **Guided Wizard** - Step-by-step customization
-5. **Natural Language** - Describe in plain English
+On first run, this automatically creates **kiro-master** (your Kiro management agent) and shows you the agent menu.
+
+### 2. Create Your First Custom Agent
+
+From the agent menu, choose **"Create new agent"** and pick a creation method:
+
+- **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
 
-### 2. Switch Modes
+### 3. Activate Any Agent
 
 ```
-/modes vibe      # Flexible, conversational
-/modes spec      # Structured workflow
-/modes as-vibe   # Vibe style, keep agent tools
-/modes as-spec   # Spec style, keep agent tools
+/agents {name}
 ```
 
-**Mode comparison:**
+Example:
+- `/agents kiro-master` - Activate the Kiro management agent
 
-| Mode | Tools | Interaction | Workflow | Use Case |
-|------|-------|-------------|----------|----------|
-| `vibe` | Kiro tools | Conversational | Flexible | Prototyping, debugging, exploration |
-| `spec` | Kiro tools | Structured | Requirements → Design → Tasks | Production features, formal development |
-| `as-vibe` | Current tools | Conversational | Flexible | Agent tools + vibe flexibility |
-| `as-spec` | Current tools | Structured | Requirements → Design → Tasks | Agent tools + spec structure |
+The agent stays active until you switch to another or end the session.
 
-### 3. Enable Strict Mode (Optional)
+## Demo
 
-```
-/strict on       # Blocks on ambiguity
-/strict off      # Allows assumptions
-```
+<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>
+
+## How It Works
 
-Use for architectural decisions, experimental projects, or when precision is critical.
-
-## Commands Reference
-
-### Agent Commands
-- `/agents` - Interactive agent management (create, activate, manage)
-- `/agents {name}` - Activate specific agent (e.g., `/agents kiro-master`)
-
-### Mode Commands
-- `/modes` - Interactive mode management (view, compare, switch)
-- `/modes {name}` - Switch to mode (e.g., `/modes vibe`, `/modes as-spec`)
-
-### Strict Mode Commands
-- `/strict` - Interactive strict mode control
-- `/strict {state}` - Set strict mode (e.g., `/strict on`, `/strict off`)
-
-### Protocol Commands (Advanced)
-- `/protocols {filename}` - Load and execute protocol from kiro-protocols Power
-- `/only-read-protocols {filename}` - Read protocol into context without executing
-
-## Architecture
-
-### Technical Implementation
-
-**Pure markdown steering documents:**
-- No runtime code, only AI instructions
-- Stored in `~/.kiro/steering/kiro-agents/`
-- Processed at build time with dynamic substitutions
-
-**Protocol-driven interaction:**
-- Protocols structure presentation format, not AI capability
-- Lazy loading keeps base context minimal (~0.9K tokens)
-- Structured via diff blocks and numbered choices
-- Optimized for SOTA model generation
-
-**Agent storage:**
-- Agents stored as `.md` files in `.kiro/agents/`
-- Contain capabilities, workflows, protocols, examples
-- Activated via instruction alias system
-- Inherit chit-chat interaction protocol
-
-**Mode system:**
-- Mode definitions in kiro-protocols Power
-- Loaded on-demand via protocol system
-- Define interaction style and available tools
-- Preserve file changes, reset workflow state
-
-### Build System
-
-**Centralized manifest:**
-- Single source of truth in `src/manifest.ts`
-- Glob pattern support for automatic file discovery
-- Guaranteed consistency between dev mode and CLI installation
-- Type-safe with compile-time validation
-
-**Dual distribution:**
-- npm package with CLI installer
-- kiro-protocols Power for protocol library
-- Both installed automatically via `npx kiro-agents`
-
-## Use Cases
-
-### Specialized Development
-Create domain-specific agents with specialized knowledge:
-- Frontend agent with React/Vue/Angular expertise
-- Backend agent with API design and database patterns
-- Testing agent with TDD workflows and coverage strategies
-- DevOps agent with CI/CD and infrastructure knowledge
-
-### Workflow Flexibility
-Adapt interaction style to task requirements:
-- Vibe mode for rapid prototyping and exploration
-- Spec mode for production features with formal requirements
-- Role modes (`as-vibe`, `as-spec`) for agent superpowers
-
-### Agent Superpowers (Experimental)
-Combine specialized agent tools with preferred interaction style using role modes:
-- `/agents frontend-specialist` then `/modes as-vibe` = React expertise + conversational flow
-- `/agents api-architect` then `/modes as-spec` = API design tools + structured workflow
-- **Spec + Vibe combo**: `/modes spec` then `/modes as-vibe` = Spec tools + vibe interaction (recently added, testing in progress)
-
-### Precision Work
-Enable strict mode for critical development:
-- Architectural decisions that propagate throughout codebase
-- Experimental projects with cutting-edge technologies
-- Breaking changes affecting multiple systems
-- Debugging propagated errors from incorrect assumptions
+**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.
+
+**kiro-protocols Power**
+Automatically installed alongside kiro-agents, this Power provides protocols (agent creation, mode switching, strict mode) that load on-demand when needed.
+
+**On-Demand Loading**
+Protocols load only when needed, keeping your context clean. Base system uses just 1.35K tokens.
+
+**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.
 
 ## Documentation
 
-- **[Getting Started](docs/GETTING-STARTED.md)** - Step-by-step onboarding guide
-- **[User Guide](docs/user-guide/)** - Agents, modes, commands, workflows, examples
-- **[Developer Guide](docs/developer-guide/)** - Contributing, versioning, build system, testing
-- **[Design Rationale](docs/design/)** - Neurodivergent accessibility, protocol system, interaction patterns
+- **[Getting Started](docs/GETTING_STARTED.md)** - Step-by-step onboarding guide
 - **[Architecture Overview](docs/ARCHITECTURE.md)** - System design and component relationships
-- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[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
 
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
-- Development workflow
-- Build commands
-- Testing guidelines
-- Versioning system (AI-powered with Changesets)
-- Cross-IDE compatibility rules
-
-**Important:** Do not modify `powers/*/steering/` directories directly. These are auto-generated from `src/` during build. PRs modifying these files will fail CI.
+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)
-- [Demo Video](https://youtu.be/Arccq_JhpFk) (3:52)
 
 ## License
 

package/build/npm/dist/aliases.md

@@ -80,44 +80,44 @@ You are now activating the **{agent_name}** agent.
 
 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 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.
-
+## 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:
@@ -161,4 +161,74 @@ After user's next message, execute:
 /modes as-vibe
 ```
   </definition>
-</alias>
+</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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-agents",
-  "version": "1.11.0",
+  "version": "1.12.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": {