Kiro Agent Documentation

Kiro uses a hierarchical prompt structure to ensure high-quality AI responses across different models and tasks:

1. Base System Prompt: Establishes Kiro's identity, capabilities (file system, code assistance), and security rules via getBasePrompt().
2. Model-Specific Formatting: An optimization layer that uses specialized templates (e.g., GPT Edit Prompt, Claude Edit Prompt) to match the instruction-following patterns of specific providers.
3. Context Injection: Dynamically injects environment data like OS, platform, shell, workspace state, and open files.
4. Task-Specific Prompts: Workflow-oriented instructions (e.g., Specification Generation).
5. Tool Integration: Action-specific prompting for built-in tools.

Template System

Kiro uses a Template Factory pattern with Handlebars support. It automatically detects models via autodetectPromptTemplates() and compiles templates with support for variable interpolation ({{variable}}), conditionals ({{#if condition}}), and loops ({{#each items}}).

Once a design has been approved, the Kiro Agent enters the Implementation Planning workflow stage to create an actionable checklist of coding tasks. This plan is stored in a specific file within the project structure to guide subsequent code generation.

Task List Requirements

• File Location: The implementation plan must be created at .kiro/specs/{feature_name}/tasks.md.
• Format: A numbered checkbox list with a maximum of two levels of hierarchy:
  • Top-level items (e.g., epics) used only when necessary.
  • Sub-tasks using decimal notation (e.g., 1.1, 1.2).
• Task Content: Each task must include:
  • A clear objective involving writing, modifying, or testing code.
  • Sub-bullets providing additional context.
  • Specific references to granular sub-requirements from the requirements document.

Constraints and Scope

• Coding Focus Only: Tasks must be actionable by a coding agent (e.g., "Implement X function", "Create Y component").
• Excluded Tasks: Do NOT include tasks for user testing, deployment, performance metrics, user training, or documentation creation. Automated end-to-end tests are allowed, but manual application running is not.
• Incremental Progress: Tasks must be sequenced to build incrementally, prioritizing test-driven development (TDD) and validating core functionality early.

Approval Workflow

1. After generating or updating the tasks.md file, the agent must ask: "Do the tasks look good?".
2. The agent must use the userInput tool with the exact reason string: spec-tasks-review.
3. If the user requests changes, the agent must iterate on the document and ask for approval again.
4. The workflow is only complete once the user provides explicit approval (e.g., "yes", "approved", "looks good").

Note: This workflow is strictly for creating planning artifacts. It does not perform the actual feature implementation. Once approved, users can begin execution by opening the tasks.md file and clicking "Start task" next to individual items.

The extension uses ESBuild to bundle dependencies into dist/extension.js. However, certain packages must remain external (unbundled) due to native binaries, dynamic requires, or platform-specific constraints.

To add a new package that cannot be bundled, follow these steps:

1. Update the curated list: Open scripts/analyze-externals.mjs and add the package name to the UNBUNDLEABLE_PACKAGES array.
2. Categorize the package: Place the package in the appropriate section within the array:
   • // VSCode runtime provided: For vscode modules.
   • // Native binaries that can't be bundled: For packages containing .node files.
   • // ESBuild and platform-specific binaries: For @esbuild/* packages.
   • // Runtime dependencies with native binaries or dynamic requires.
   • // Relative imports that can't be bundled.
3. Apply changes: Run npm run analyze-externals to update both scripts/esbuild.mjs and .vscodeignore automatically.

// Example: Adding a package to scripts/analyze-externals.mjs
const UNBUNDLEABLE_PACKAGES = [
  // ... existing packages
  'your-new-package',
];