kiro-agents 1.11.0 → 1.13.0

package/README.md

@@ -1,229 +1,103 @@
 # 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
+- 🧠 **Reflection System** - Agents learn from experience with persistent memory across sessions
 
 ## 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
+- **[Reflection System](docs/user-guide/reflection-system.md)** - Persistent memory for agents
+- **[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/bin/cli.js

@@ -33,7 +33,8 @@ var STEERING_FILES = [
   "aliases.md",
   "agents.md",
   "modes.md",
-  "strict.md"
+  "strict.md",
+  "reflect.md"
 ];
 var POWER_FILES = [
   "POWER.md",
@@ -46,6 +47,7 @@ var POWER_FILES = [
   "steering/kiro-spec-mode.md",
   "steering/kiro-as-vibe-mode.md",
   "steering/kiro-as-spec-mode.md",
+  "steering/explainability-protocol.md",
   "steering/chit-chat.md",
   "steering/agent-management.md",
   "steering/agent-creation.md",

package/build/npm/dist/agents.md

@@ -13,11 +13,10 @@ keywords: ["agents", "management", "create", "activate", "interactive"]
 If the user's message contains `/agents {agent_name}` with a specific agent name (e.g., `/agents kiro-master`):
 
 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
-   - /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
+2. **INSTEAD, execute the instruction alias:**
+   ```
+   /agents {agent_name}
+   ```
 3. **Stop processing this document** - The agent activation protocol takes over
 
 **Only continue with interactive management flow below if user typed `/agents` without parameters.**
@@ -34,11 +33,23 @@ You are now in **agent management mode** using chit-chat interaction protocol.
 
 ## Initial Agent
 
-When auto-setup detects no agents exist, create the initial agent:
+When auto-setup detects no agents exist:
 
-**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
+1. **Load agent definition structure:**
+   ```
+   /only-read-protocols agent-creation.md
+   ```
 
-This description is used when creating `.kiro/agents/kiro-master.md` during auto-setup.
+2. **Create `.kiro/agents/kiro-master.md`** using the agent definition structure from agent-creation.md Step 3, with:
+   
+   **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
+
+3. **Validate** the created agent file has:
+   - Valid YAML frontmatter
+   - All required sections from agent-creation.md Step 3
+   - Proper markdown formatting
+
+This ensures the initial agent follows the standard agent definition structure.
 
 ---
 

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/build/npm/dist/reflect.md

@@ -0,0 +1,158 @@
+---
+inclusion: manual
+description: "Reflection system commands for capturing and managing agent insights"
+keywords: ["reflect", "insights", "learning", "reflection"]
+---
+
+# Reflection System
+
+Commands for managing the AI reflection system that captures insights, patterns, decisions, and learnings.
+
+## Commands
+
+### /reflect - Enable Reflection (Session-Temporary)
+
+**Usage:** `/reflect`
+
+**Behavior:**
+
+Enables reflection system for the currently active agent (session-temporary).
+
+**If agent already has Reflections section:**
+- Confirm it's already enabled
+- Show reflection status
+- Continue
+
+**If agent lacks Reflections section:**
+- Add Reflections section temporarily for this session
+- Include all 4 tiers (Universal, Category, Agent-Specific, Project)
+- Reflection active while using this agent
+- Removed when session ends or agent changes
+- Next session: agent returns to original state
+
+**Reflections section added (temporary):**
+
+````markdown
+## Reflections
+
+This agent records insights, patterns, and learnings in its dedicated reflection files.
+
+### Universal Insights
+
+#[[file:.ai-storage/reflections/approved/universal.md:insights]]
+
+### Category Insights ({agent-category})
+
+#[[file:.ai-storage/reflections/approved/categories/{agent-category}.md:insights]]
+
+### Agent-Specific Insights
+
+#[[file:.ai-storage/reflections/approved/agents/{agent-name}.md:insights]]
+
+### Project Insights
+
+#[[file:.ai-storage/reflections/approved/project.md:insights]]
+````
+
+**Note:** Replace `{agent-category}` and `{agent-name}` with actual values from agent definition.
+
+**After enabling:**
+
+```diff
+✅ REFLECTION ENABLED (Session-Temporary)
+
+Agent: {agent-name}
+Category: {agent-category}
+
+Reflection files:
+- Universal: .ai-storage/reflections/approved/universal.md
+- Category: .ai-storage/reflections/approved/categories/{agent-category}.md
+- Agent: .ai-storage/reflections/approved/agents/{agent-name}.md
+- Project: .ai-storage/reflections/approved/project.md
+
+Draft file:
+- .ai-storage/reflections/drafts/agents/{agent-name}.md
+
+You can now capture insights during work. Use /agents reflection-curator to review drafts.
+```
+
+**Use case:** Quick testing, one-off reflection capture, temporary enablement.
+
+---
+
+### /reflect review - Review Draft Insights
+
+**Usage:** `/reflect review`
+
+**Behavior:**
+
+Activates reflection-curator agent and starts draft review workflow.
+
+**Equivalent to:**
+```
+/agents reflection-curator
+```
+
+Then curator agent automatically starts review workflow.
+
+**Use case:** Review pending draft insights and approve them to appropriate tiers.
+
+---
+
+## Reflection System Overview
+
+### Purpose
+
+Enable agents to capture and reuse knowledge across sessions:
+- **Insights** - General knowledge, preferences, standards
+- **Patterns** - Reusable approaches, workflows, solutions
+- **Decisions** - Important choices and their rationale
+- **Learnings** - Lessons from successes or failures
+
+### Workflow
+
+1. **Agent captures insight** → Writes to draft file
+2. **User reviews drafts** → `/reflect review`
+3. **Curator validates** → Checks quality, assigns tier
+4. **Insight approved** → Moves to approved file
+5. **Agents use insights** → Load via file references
+
+### Insight Tiers
+
+**Universal** - Used by ALL agents  
+**Category** - Used by agent type (architects, developers, etc.)  
+**Agent-Specific** - Used by one agent only  
+**Project** - About this specific project
+
+### Storage Location
+
+```
+.ai-storage/reflections/
+├── drafts/        - Pending insights
+└── approved/      - Approved insights by tier
+```
+
+### On-Demand Creation
+
+No initialization required! Files created automatically when:
+- Agent records first insight
+- Curator approves insight
+- Agent loads reflections
+
+## Related Commands
+
+```
+/reflect              Enable reflection (session-temporary)
+/reflect review       Review draft insights
+/agents reflection-curator   Activate curator agent
+```
+
+## Learn More
+
+- **README:** `.ai-storage/README.md` - Complete system documentation
+- **Curator Agent:** `.kiro/agents/reflection-curator.md`
+- **Proposal:** `proposals/ai-managed-storage-and-reflection-system-v2.md`
+
+---
+
+**Start capturing insights with `/reflect` and review them with `/reflect review`.**