kiro-agents 1.2.0 → 1.4.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/dist/agent-system.md

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