Kirogen

Bootstrap empty git repositories for Kiro development.

Overview

Kirogen is a lightweight CLI tool that initializes the necessary directory structure for Kiro-based development workflows. Run it once in your git repository to set up the .kiro/steering and .kiro/hooks directories.

Installation

No installation required! Use npx to run it directly:

npx kirogen

Usage

Navigate to your git repository and run:

npx kirogen

This will create:

• .kiro/steering/ - Directory for workflow guidance files
• .kiro/hooks/ - Directory for agent hook configurations
• .kirogenrc.mjs - Configuration file for your Kiro environment

Basic Example

$ cd my-project
$ npx kirogen
Initializing Kiro development environment...
✓ Created .kiro/steering directory
✓ Created .kiro/hooks directory
✓ Created .kirogenrc.mjs configuration file
✓ Kiro development environment initialized successfully!

Download Steering Files from GitHub

You can automatically download steering files from a GitHub repository:

npx kirogen --steering-from=DeepSRT/kiro-assets/dotkiro/steering

This will:

1. Create the .kiro directory structure
2. Download all *.global.md files from the specified GitHub path
3. Save them to your local .kiro/steering/ directory

URL Formats:

• Shorthand (defaults to main branch): owner/repo/path
• Full format with branch: owner/repo/tree/branch/path

Equivalent URLs:

• DeepSRT/kiro-assets/dotkiro/steering (shorthand)
• DeepSRT/kiro-assets/tree/main/dotkiro/steering (full)
• Both point to: https://github.com/DeepSRT/kiro-assets/tree/main/dotkiro/steering

Example with Steering Files

$ npx kirogen --steering-from=DeepSRT/kiro-assets/dotkiro/steering
Initializing Kiro development environment...
✓ Created .kiro/steering directory
✓ Created .kiro/hooks directory
Downloading steering files from DeepSRT/kiro-assets/dotkiro/steering...
✓ Downloaded 3 steering files
✓ Created .kirogenrc.mjs configuration file
✓ Kiro development environment initialized successfully!

Configuration File

Kirogen creates a .kirogenrc.mjs configuration file in your project root. This file stores your Kiro environment settings:

/**
 * Kirogen Configuration
 * 
 * This file defines the configuration for your Kiro development environment.
 */

export default {
  "steeringFrom": "DeepSRT/kiro-assets/dotkiro/steering",
  "directories": {
    "steering": ".kiro/steering",
    "hooks": ".kiro/hooks"
  }
};

You can manually edit this file to customize your Kiro environment settings.

Syncing Steering Files

If you've initialized your project with --steering-from, you can re-download the latest steering files at any time:

npx kirogen sync

This command:

1. Reads the steeringFrom URL from your .kirogenrc.mjs
2. Downloads the latest *.global.md files from that GitHub location
3. Overwrites your local .kiro/steering/ files with the latest versions

Example:

$ npx kirogen sync
Syncing steering files from DeepSRT/kiro-assets/dotkiro/steering...
✓ Downloaded 3 steering files
✓ Steering files synced successfully!

This is useful when:

• The remote steering files have been updated
• You want to refresh your local steering files
• You've accidentally modified or deleted steering files

Commands

Initialize

npx kirogen [--steering-from=<github-url>]

Initializes the Kiro development environment.

Sync

npx kirogen sync

Re-downloads steering files from the configured remote source.

Requirements

• Node.js >= 14.0.0

Features

• Zero installation - Run directly with npx
• Idempotent - Safe to run multiple times
• Fast - Completes in milliseconds
• Clear feedback - Visual indicators for success and errors

Error Handling

Kirogen validates your environment before making changes:

• Not a git repository: Exits with code 1 if .git directory is not found
• Permission errors: Exits with code 2 if unable to create directories
• Unexpected errors: Exits with code 3 for other failures

Development

Running Tests

npm test

Project Structure

kirogen/
├── bin/
│   └── kirogen.js       # CLI entry point
├── lib/
│   ├── bootstrap.js     # Directory creation logic
│   ├── logger.js        # Console output utilities
│   └── validator.js     # Git repository validation
└── test/
    └── unit/            # Unit tests

License

MIT