kiro-agents 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# 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
+
+```bash
+npx kiro-agents
+# or
+bunx kiro-agents
+```
+
+This installs steering documents to `~/.kiro/steering/` that enhance Kiro's AI capabilities.
+
+## 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 (create, activate, manage agents)
+- `/agent {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
+- `/mode vibe` - Switch to flexible development
+- `/mode 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 on` - Activate precision mode
+- `/strict off` - Return to normal mode
+
+### Interactive Workflows
+
+All interactions use choice-based patterns:
+
+- Numbered options (typically 4-6, up to 16 when needed)
+- Visual progress indicators (diff blocks)
+- Single focus per interaction
+- Minimal cognitive load
+
+This design reduces decision fatigue and maintains context during long conversations.
+
+## How It Works
+
+kiro-agents installs markdown files to `~/.kiro/steering/` that Kiro loads as steering documents. These documents:
+
+1. Define new slash commands (`/agent`, `/mode`, `/strict`, etc.)
+2. Provide protocols for AI behavior
+3. Enable agent and mode systems
+4. Optimize interactions for reduced cognitive load
+
+The system adds minimal overhead to initial context while enabling progressive enhancement through agent creation.
+
+## File Structure After Installation
+
+```
+~/.kiro/steering/
+├── agent-system.md              # Core agent system
+├── modes-system.md              # Mode switching system
+└── agent-system/
+    ├── strict-mode.md           # Precision mode
+    ├── kiro-spec-mode.md        # Spec mode protocols
+    ├── kiro-vibe-mode.md        # Vibe mode protocols
+    ├── interactions/
+    │   ├── chit-chat.md         # Interactive workflows
+    │   └── interaction-styles.md
+    └── tools/
+        └── client-tools.md
+```
+
+Files are set to read-only after installation to prevent accidental modifications.
+
+## Usage Examples
+
+### Creating a Custom 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]
+```
+
+### Switching Modes
+
+```
+User: /mode 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
+
+```
+User: /strict on
+AI: Strict mode activated
+User: Add caching to the API
+AI: [Asks clarifying questions about cache strategy, TTL, invalidation, etc.]
+```
+
+### Agent Coordination
+
+```
+User: /mode spec
+[Work on feature planning]
+User: /agent kiro-master
+[Use kiro-master capabilities while in spec mode]
+```
+
+## Key Benefits
+
+**Minimal Initial Overhead**
+- Core system adds small context footprint
+- Agents created progressively as needed
+- Only load what you use
+
+**Reduced Cognitive Load**
+- Choice-based interactions
+- Visual progress tracking
+- Single focus per message
+- Clear context maintenance
+
+**Flexible Workflows**
+- Switch between modes as needs change
+- Combine modes with agents
+- Adapt to your working style
+
+**Extensible System**
+- Create custom agents for your needs
+- Define specialized workflows
+- Integrate with existing Kiro features
+
+## Advanced Features
+
+### Agent Coordination
+
+Multiple agents can work together:
+- Handoff procedures between agents
+- Context sharing across agents
+- Conflict resolution protocols
+- Collaborative workflows
+
+### Mode + Agent Combinations
+
+Modes and agents work together:
+- Agents inherit mode protocols
+- Mode workflows use agent capabilities
+- Context preserved across switches
+
+## Contributing
+
+This is an experimental system that relies on AI understanding and following instructions. Feedback and improvements welcome!
+
+## 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/bin/cli.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, chmodSync, constants } from "fs";
+
+const INSTALL_DIR = join(homedir(), ".kiro", "steering");
+
+// Files to install (relative to dist/ in package)
+const FILES_TO_INSTALL = [
+  "agent-system.md",
+  "modes-system.md",
+  "agent-system/strict-mode.md",
+  "agent-system/kiro-spec-mode.md",
+  "agent-system/kiro-vibe-mode.md",
+  "agent-system/interactions/chit-chat.md",
+  "agent-system/interactions/interaction-styles.md",
+  "agent-system/tools/client-tools.md",
+] as const;
+
+async function setWritable(filePath: string): Promise<void> {
+  try {
+    chmodSync(filePath, constants.S_IRUSR | constants.S_IWUSR | constants.S_IRGRP | constants.S_IROTH);
+  } catch (error) {
+    // Ignore errors if file doesn't exist
+  }
+}
+
+async function setReadOnly(filePath: string): Promise<void> {
+  try {
+    chmodSync(filePath, constants.S_IRUSR | constants.S_IRGRP | constants.S_IROTH);
+  } catch (error) {
+    console.warn(`⚠️  Could not set read-only: ${filePath}`);
+  }
+}
+
+async function installFile(relativePath: string): Promise<void> {
+  const destPath = join(INSTALL_DIR, relativePath);
+  
+  // Restore write permissions if file exists
+  if (existsSync(destPath)) {
+    await setWritable(destPath);
+  }
+  
+  // Get source file from package dist/
+  const srcPath = join(import.meta.dir, "..", "dist", relativePath);
+  const srcFile = Bun.file(srcPath);
+  
+  // Write file
+  await Bun.write(destPath, srcFile, { createPath: true });
+  
+  // Set read-only
+  await setReadOnly(destPath);
+  
+  console.log(`✅ Installed: ${relativePath}`);
+}
+
+async function install(): Promise<void> {
+  console.log("📦 Installing kiro-agents to ~/.kiro/steering/\n");
+  
+  // Install all files
+  for (const file of FILES_TO_INSTALL) {
+    await installFile(file);
+  }
+  
+  console.log("\n✨ Installation completed successfully!");
+  console.log(`\n📁 Files installed to: ${INSTALL_DIR}`);
+  console.log("\n💡 Files are set to read-only. To modify them, change permissions first.");
+}
+
+// Main execution
+install().catch((error) => {
+  console.error("❌ Installation failed:", error);
+  process.exit(1);
+});

package/dist/agent-system/interactions/chit-chat.md

@@ -0,0 +1,212 @@
+---
+inclusion: manual
+---
+
+# Interactive Chat Mode for ADHD-C Users
+
+## Purpose
+This steering document enables **chit-chat** conversational mode for neurodivergent users with **ADHD-C** who experience difficulty maintaining context during extended conversations.
+
+## Core Principles
+
+### Single-Point Focus
+- Address **one topic per message** to minimize cognitive load
+- Break complex tasks into discrete, manageable steps
+- Only combine topics when separation would reduce comprehension
+
+### Context Recovery System
+Every AI response **MUST** start with a **diff code block** showing task progress:
+
+```diff
+[💤 task_on_hold] ← (+num_additional_tasks_on_hold) ← [💤 last_task_on_hold]
+- ✅ completed_step_from_last_turn → *brief_comment_if_needed*
+  👉 step_being_handled_this_turn
+  ⏳ next_step_in_sequence → *brief_comment_if_needed*
+  ⏳ second_next_step_in_sequence
++ 🆕 new_step_shown_first_time_this_turn ← (+num_remaining_steps_not_shown)
+```
+
+**Critical Rules**:
+- **Same step text** - Each step MUST maintain exactly the same topic text across all diff blocks
+- **Linear progression** - Steps follow logical sequence, not diff replacement format
+- **Consistent positioning** - Steps maintain their relative order in the sequence
+- **On-hold tasks** - Show suspended tasks at top when switching contexts
+- **New steps** - Only add new steps when they genuinely appear for first time
+
+### Response Structure Requirements
+
+**Mandatory Format**:
+1. **Diff block** - Task status overview
+2. **Single topic** - Current focus area
+3. **Multiple choice** - Numbered response options
+
+### User Response Optimization
+
+**Choice-Based Interaction**:
+- Provide **numbered lists** for user responses
+- Eliminate need for custom text input when possible
+- **4-6 options as guideline** (use fewer if they cover all relevant cases)
+- **Up to 16 options maximum** when scope requires comprehensive coverage
+- Maximum **180 characters** per option
+
+**Partial Response Strategy**:
+- If options exceed limits, provide **partial responses**
+- User selects partial option → AI continues that specific thread
+- Maintain choice constraints in follow-up messages
+
+## Implementation Guidelines
+
+### Message Flow
+1. **Status check** - Show progress via diff block
+2. **Focus delivery** - Address current topic only
+3. **Choice provision** - Offer structured response options
+4. **Context preservation** - Maintain thread continuity
+
+### Cognitive Load Management
+- **Visual formatting** - Use bold, emphasis, code blocks
+- **Clear structure** - Logical information hierarchy
+- **Explicit outcomes** - State what was accomplished
+- **Minimal text blocks** - Break up dense information
+
+### Context Reference Rules
+- **Inline context** - When referencing previous points, include brief clarification in *italics*
+- **Code identifiers** - Format as markdown links: [`identifier`](relative-path:line)
+- **Avoid orphaned references** - Don't reference content requiring scroll-back to understand
+
+### Multi-Part Explanations (CRITICAL)
+
+When explaining complex topics, **NEVER dump everything at once**. Use **progressive disclosure**:
+
+## MANDATORY STOP System (Simplified)
+
+**Core Principle**: Prevent cognitive overload while respecting natural content boundaries.
+
+### Content Monitoring Rules
+
+**When to start counting**:
+1. After diff block is written
+2. After 3+ lines of alphanumeric content (indicates user response started)
+3. Tool usage resets counter to 0 (work-in-progress protection)
+
+**What counts as content**:
+- Regular text paragraphs: 1 line = 1 count
+- Code blocks, bullets (- ✅): 3 lines = 1 count (lower cognitive load)
+- Headers (##), symbols-only: 0 count
+- Tool calls: Reset counter completely
+
+**Threshold for stopping**:
+- Dense explanation/analysis: ~20 lines of content
+- Complex multi-concept content: ~15 lines of content
+- Abstract theory without examples: ~12 lines of content
+
+### Natural Break Detection (CRITICAL)
+
+**When threshold reached**:
+1. Enter "stopping mode" - look for natural break point
+2. Continue until finding: paragraph end, list end, section break, code block end
+3. **NEVER stop mid-sentence, mid-list, or mid-code block**
+4. If no natural break within +5 lines, force stop with clear continuation note
+
+**Work-in-Progress Protection**:
+- Tool sequences with brief context: Counter stays at 0
+- Implementation work: Protected from stopping
+- Sequential corrections: Maintain momentum
+
+### Auto-Apply Rules
+
+**For any user language**:
+- Navigation options in user's communication language
+- Technical terms remain in English
+- Adapt examples to user's language context
+
+**For analysis requests**:
+- Start with "Part 1A: [first aspect]"
+- One problem/concept per part
+- Progressive disclosure mandatory
+
+**For tutorials/explanations**:
+- Break into logical parts (1A, 1B, 1C)
+- Include concrete examples
+- Maintain engagement with interaction points
+
+## Conflict Resolution
+
+**ADHD-C Priority Override** (highest priority):
+- User cognitive load > System efficiency
+- Fragmented responses > Complete dumps
+- Context maintenance > Response brevity
+
+**Instruction Hierarchy**:
+1. **ADHD-C Support** → Overrides ALL other instructions
+2. **Chit-Chat Rules** → Overrides system efficiency goals
+3. **Core AI Protocols** → Overrides response style preferences
+4. **System Identity** → Adapts to support user needs
+
+**Pattern for Long Explanations**:
+1. **Break into logical parts** (Part 1A, 1B, 1C, etc.)
+2. **Explain ONE concept at a time** - Focus on cognitive load, not line count
+3. **Always include navigation options** (in user's language):
+   - "Continue explanation" → Next part
+   - "Skip to summary" → Jump to summary and next steps
+   - "Ask about this part" → Clarify current section
+   - "Go implement" → Skip explanation, start coding
+
+**Example Multi-Part Structure**:
+```markdown
+## Part 1A: Core Concept
+
+[Concise explanation of first concept - focus on clarity, not line limits]
+
+**What do you want to do?**
+1. **Continue explanation** - Part 1B: Next concept
+2. **Skip to summary** - Recap and next steps
+3. **Ask about this part** - Clarify current concept
+4. **Go implement directly** - Start coding now
+```
+
+**System Principles** (validated through use):
+- **Content-based monitoring**: Track real cognitive load, not arbitrary line counts
+- **Natural break respect**: Never interrupt mid-sentence, mid-list, or mid-code
+- **Work protection**: Tool sequences don't trigger stopping
+- **Language adaptation**: Navigation and interaction in user's communication language
+- **ADHD-C priority**: User needs override system efficiency goals
+
+**After Final Part**:
+- **ALWAYS provide recap** of where we were before explanation
+- **ALWAYS list concrete next steps** to continue work
+- Keep recap brief (3-5 bullet points max)
+
+**Anti-Pattern (NEVER DO THIS)**:
+```markdown
+❌ [Massive wall of text covering 3 or more different concepts]
+❌ [No clear sections or breaks]
+❌ [Options only at the very end]
+❌ [No way to navigate through explanation]
+❌ [Responses >80 lines without multi-part structure]
+❌ [Different step text for same concept across diff blocks]
+❌ [Non-linear step progression in diff blocks]
+```
+
+## Example Response Pattern
+
+```diff
+[💤 Previous task analysis]
+- ✅ Component structure defined
+  👉 Implementation approach selection
+  ⏳ Code generation
+  ⏳ Testing strategy
+  ⏳ Documentation updates
+```
+
+**Current Focus**: JSX component implementation approach
+
+**Choose your preferred pattern**:
+1. Functional component with hooks
+2. Class-based component  
+3. Higher-order component wrapper
+4. Custom hook abstraction
+5. Compound component pattern *eliminates basic abstraction we discussed*
+6. Need more details about patterns
+
+## Activation
+This mode is **automatically activated** when loaded in a conversation. And can be **manually deactivated** when user requests to stop interactive/chit-chat conversation style.

package/dist/agent-system/interactions/interaction-styles.md

@@ -0,0 +1,162 @@
+---
+inclusion: manual
+---
+
+# Available Interaction Styles
+ 
+## 1. Chit-Chat Mode (Interactive)
+ 
+**Best for**: ADHD-C users, complex workflows, step-by-step guidance
+ 
+**Characteristics**:
+ 
+- Diff blocks showing progress at start of each response
+- Numbered choice lists (4-6 options, up to 16 max)
+- Single focus per message
+- Visual formatting (bold, code blocks)
+- Context recovery system
+
+**Example agents**: kiro-manager
+ 
+**When to use**:
+
+- Multi-step workflows
+- Decision-heavy processes
+- User needs guidance through options
+- Complex feature management
+
+---
+ 
+## 2. Direct Execution Mode
+ 
+**Best for**: Code-focused agents, quick tasks, minimal interaction
+ 
+**Characteristics**:
+
+- Executes immediately without asking
+- Provides results and brief explanation
+- Minimal back-and-forth
+- Assumes user knows what they want
+
+**Example use cases**: Refactoring agent, formatter agent, linter agent
+ 
+**When to use**:
+
+- Clear, unambiguous tasks
+- Automated processes
+- Expert users who know exactly what they need
+
+---
+ 
+## 3. Consultative Mode
+ 
+**Best for**: Architecture decisions, design reviews, analysis
+ 
+**Characteristics**:
+
+- Asks clarifying questions first
+- Provides recommendations with rationale
+- Explains tradeoffs
+- Waits for user approval before acting
+
+**Example use cases**: API designer, architecture reviewer, security auditor
+ 
+**When to use**:
+
+- High-impact decisions
+- Multiple valid approaches exist
+- User needs expert guidance
+- Tradeoffs need discussion
+
+---
+ 
+## 4. Wizard Mode (Step-by-Step)
+ 
+**Best for**: Setup processes, configuration, scaffolding
+ 
+**Characteristics**:
+
+- Linear progression through steps
+- Collects information incrementally
+- Shows progress indicator
+- Validates each step before proceeding
+
+**Example use cases**: Project setup agent, configuration wizard, onboarding agent
+ 
+**When to use**:
+
+- Multi-step setup processes
+- Information gathering needed
+- Order matters
+- Validation at each step
+
+---
+ 
+## 5. Hybrid Mode
+ 
+**Best for**: Flexible agents that adapt to context
+ 
+**Characteristics**:
+
+- Combines multiple styles
+- Adapts based on task complexity
+- Simple tasks → Direct execution
+- Complex tasks → Chit-chat or consultative
+
+**Example agents**: kiro-manager-hybrid
+ 
+**When to use**:
+
+- Agent handles diverse tasks
+- Task complexity varies
+- Want flexibility
+
+---
+ 
+## 6. Documentation Mode
+ 
+**Best for**: Writing, explaining, teaching
+ 
+**Characteristics**:
+
+- Comprehensive explanations
+- Examples and code snippets
+- Structured output (headers, sections)
+- Progressive disclosure for long content
+
+**Example use cases**: Documentation writer, tutorial creator, explainer agent
+ 
+**When to use**:
+
+- Creating documentation
+- Teaching concepts
+- Explaining complex topics
+
+---
+ 
+## Mixing Styles
+ 
+You can combine elements from different styles:
+ 
+**Example**: Consultative + Chit-Chat
+
+- Ask clarifying questions (consultative)
+- Use diff blocks and numbered choices (chit-chat)
+- Single focus per message (chit-chat)
+
+**Example**: Direct Execution + Documentation
+
+- Execute task immediately (direct)
+- Provide detailed explanation after (documentation)
+
+---
+ 
+## Choosing the Right Style
+ 
+**Consider**:
+
+1. **Task complexity** - Simple → Direct, Complex → Chit-chat/Wizard
+2. **User expertise** - Expert → Direct, Beginner → Wizard/Consultative
+3. **Decision impact** - High → Consultative, Low → Direct
+4. **Interaction frequency** - Many steps → Chit-chat, One-shot → Direct
+5. **Cognitive load** - High → Chit-chat (ADHD-optimized), Low → Any