Creating Kiro Packages

Creating Kiro Packages

Overview

Kiro uses two package types:

1. Steering files (.kiro/steering/*.md) - Markdown with optional YAML frontmatter
2. Hooks (.kiro/hooks/*.json) - JSON configuration for event-driven automation

Package Types

Steering Files

Inclusion Modes

Quick Reference

---
inclusion: always  # always, fileMatch, or manual
fileMatchPattern: "components/**/*.tsx"  # Required for fileMatch
domain: testing  # Optional: for organization
---

Creating Always-Included Steering Files

Used for workspace-wide standards that influence all code generation:

---
inclusion: always
---

# Core Technology Stack

Our workspace uses the following technologies and standards.

## Stack

- **Frontend**: React 18 + TypeScript + Vite
- **Backend**: Node.js + Express + Prisma
- **Database**: PostgreSQL
- **Testing**: Vitest + Testing Library

## Universal Principles

- Write self-documenting code
- Keep functions under 50 lines
- Use meaningful variable names
- Add comments only for complex logic

Creating FileMatch Steering Files

Applied automatically when working with files matching the pattern:

---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"
domain: frontend
---

# React Component Guidelines

Applied automatically when working with React components.

## Component Standards

- Use functional components with hooks
- Keep components under 200 lines
- Extract logic into custom hooks
- Co-locate styles with components

## Example

\`\`\`tsx
// Good: Focused component
function UserProfile({ userId }: Props) {
  const user = useUser(userId);
  return <div>{user.name}</div>;
}
\`\`\`

Common FileMatch Patterns

# React components
fileMatchPattern: "*.tsx"

# API routes
fileMatchPattern: "app/api/**/*"

# Test files
fileMatchPattern: "**/*.test.*"

# Components in specific directory
fileMatchPattern: "src/components/**/*"

# Documentation
fileMatchPattern: "*.md"

Creating Manual Steering Files

User explicitly activates when needed:

---
inclusion: manual
domain: performance
---

# Performance Optimization Guide

Manually activate when optimizing performance-critical code.

## Profiling First

- Always measure before optimizing
- Use Chrome DevTools or similar
- Identify actual bottlenecks

## Common Optimizations

- Memoization for expensive calculations
- Lazy loading for large components
- Debouncing for frequent events
- Virtual scrolling for long lists

Foundational Files

Kiro recognizes special steering files with reserved names:

product.md

---
inclusion: always
foundationalType: product
---

# Product Context

## Mission

Build the best task management app for remote teams.

## Key Features

1. Real-time collaboration
2. Offline-first architecture
3. Natural language task input
4. Smart scheduling

## User Personas

- **Project Manager**: Needs overview and reporting
- **Team Member**: Needs task details and updates
- **Stakeholder**: Needs high-level progress tracking

tech.md

---
inclusion: always
foundationalType: tech
---

# Technical Architecture

## Stack

- **Frontend**: React 18 + TypeScript + Vite
- **Backend**: Node.js + Express + Prisma
- **Database**: PostgreSQL
- **Cache**: Redis
- **Deploy**: Docker + AWS ECS

## Architecture Patterns

- Clean architecture (domain/application/infrastructure)
- CQRS for complex operations
- Event sourcing for audit trail
- Repository pattern for data access

structure.md

---
inclusion: always
foundationalType: structure
---

# Project Structure

## Directory Layout

\`\`\`
src/
  api/              # API routes and controllers
  domain/           # Business logic and entities
  services/         # Application services
  repositories/     # Data access layer
  middleware/       # Express middleware
  utils/            # Helper functions
\`\`\`

## File Naming Conventions

- **Components**: PascalCase (e.g., `UserProfile.tsx`)
- **Services**: camelCase with Service suffix (e.g., `userService.ts`)
- **Types**: PascalCase (e.g., `User.ts`)
- **Tests**: `*.test.ts` or `*.spec.ts`

Kiro Hooks

Hooks are JSON configuration files for event-driven automation:

Hook Structure

{
  "name": "Hook Name",
  "description": "What this hook does",
  "version": "1",
  "when": {
    "type": "eventType",
    "patterns": ["glob", "patterns"]
  },
  "then": {
    "type": "actionType",
    "prompt": "Instructions for agent"
  }
}

Event Types

File Events (require patterns):

Lifecycle Events (no patterns needed):

Action Types

Creating Hooks

Automatic Test File Creation

.kiro/hooks/auto-test-files.json:

{
  "name": "Auto Test Files",
  "description": "Creates test files for new components",
  "version": "1",
  "when": {
    "type": "fileCreated",
    "patterns": ["src/components/**/*.tsx"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "A new component was created. Create a corresponding test file following our testing patterns. Use React Testing Library and include tests for rendering and key interactions."
  }
}

Image Asset Indexer

.kiro/hooks/image-indexer.json:

{
  "name": "Image Asset Indexer",
  "description": "Adds references to new images in index.ts",
  "version": "1",
  "when": {
    "type": "fileCreated",
    "patterns": [
      "client/src/assets/*.png",
      "client/src/assets/*.jpg",
      "client/src/assets/*.svg"
    ]
  },
  "then": {
    "type": "askAgent",
    "prompt": "A new image file has been added to the assets folder. Please update the index.ts file in the assets folder to include a reference to this new image. First, check the current structure of the index.ts file to understand how images are referenced. Then add an appropriate export statement for the new image file following the existing pattern."
  }
}

Dependency Update Checker

.kiro/hooks/dependency-checker.json:

{
  "name": "Dependency Update Checker",
  "description": "Checks for breaking changes in package.json",
  "version": "1",
  "when": {
    "type": "fileModified",
    "patterns": ["package.json"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "package.json was modified. Check if any dependencies were updated and review the changelog for breaking changes. Suggest any code updates needed."
  }
}

Session Context Loader (Lifecycle Hook)

.kiro/hooks/session-setup.json:

{
  "name": "Session Setup",
  "description": "Loads project context when agent starts",
  "version": "1",
  "when": {
    "type": "agentSpawn"
  },
  "then": {
    "type": "askAgent",
    "prompt": "Read the README.md and CONTRIBUTING.md to understand the project structure and coding conventions before starting work."
  }
}

Security Gate (Lifecycle Hook)

.kiro/hooks/security-check.json:

{
  "name": "Security Check",
  "description": "Reviews tool calls for security concerns",
  "version": "1",
  "when": {
    "type": "preToolUse"
  },
  "then": {
    "type": "askAgent",
    "prompt": "Review this tool call for potential security issues. Block if it accesses sensitive files (.env, credentials) or runs dangerous commands."
  }
}

Common Mistakes

Validation

Schemas location:

• Steering: /Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/kiro-steering.schema.json
• Hooks: /Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/kiro-hooks.schema.json

Documentation:

• Steering: /Users/khaliqgant/Projects/prpm/app/packages/converters/docs/kiro.md
• Hooks: /Users/khaliqgant/Projects/prpm/app/packages/converters/docs/kiro-hooks.md

Best Practices

Steering Files

1. Start with foundational files: product.md, tech.md, structure.md
2. Use always for core patterns: Code style, architecture principles
3. Use fileMatch for specific contexts: Component rules, API patterns
4. Group by domain: Consistent naming helps discovery
5. Manual for workflows: Special procedures, optimization guides

Hooks

1. Specific patterns: Use precise globs to avoid unnecessary triggers
2. Clear prompts: Write detailed agent prompts with context
3. Idempotent actions: Ensure hooks can run multiple times safely
4. Performance: Avoid hooks on frequently modified files
5. Testing: Test hooks in isolation before deploying

Remember: Steering files use inclusion modes (always/fileMatch/manual). Hooks use JSON with event triggers (fileCreated/fileModified/fileDeleted).