Migration update

qmims has been migrated from Amazon Q CLI to Kiro CLI. These docs reflect the current install, authentication, and command workflows.

Embedded Instructions

Use embedded qmims comments to guide Kiro-backed README generation and editing

Embedded instructions let you control what qmims asks Kiro CLI to generate inside a Markdown file. They are written as HTML comments and placed directly where you want new or updated content to appear.

Kiro-backed workflow

qmims now runs on Kiro CLI rather than Amazon Q. The instruction syntax stays simple, but the underlying execution, authentication, and troubleshooting flow now use Kiro commands.

Instruction Syntax

Embedded instructions use an HTML comment beginning with the qmims prefix:

<!-- qmims: Your instruction here -->

qmims passes these instructions to Kiro, which reads the surrounding Markdown context and updates the file accordingly.

Where to Place Instructions

Place each instruction exactly where you want the generated content to appear. That makes the intent clear and helps qmims preserve the structure of your document.

# Project Title

<!-- qmims: Generate a concise overview of the repository's purpose and primary use case. -->

## Features

<!-- qmims: List the main user-facing features based on the current codebase. -->

## Installation

<!-- qmims: Add installation steps using the detected package manager and runtime requirements. -->

After processing, the surrounding Markdown should contain the generated content in those sections rather than empty placeholders.

Multiple Instructions

qmims supports multiple embedded instructions in the same file. This is especially useful when you want different sections of a README to be guided independently.

# My Library

<!-- qmims: Write a short project summary focused on what problem this library solves. -->

## Installation

<!-- qmims: Provide install instructions for npm and pnpm if applicable. -->

## Usage

<!-- qmims: Add two practical usage examples for the library's main entry points. -->

## API Notes

<!-- qmims: Summarize the most important exported functions or classes. -->

Important behavior

qmims now uses all discovered embedded instructions when building the Kiro prompt flow, not just the first instruction in the file.

Typical Instruction Types

You can use embedded comments for many kinds of documentation work:

1. Generate new content

<!-- qmims: Generate a list of API endpoints based on the server routes in this repository. -->

2. Refresh outdated sections

<!-- qmims: Update this installation section to match the current package manager, runtime, and CLI requirements. -->

3. Add a section with a specific purpose

<!-- qmims: Add a Contributing section with practical setup and pull request guidance for this repository. -->

4. Request a specific format

<!-- qmims: Document these commands as a table with columns for command, purpose, and example usage. -->

How to Process Instructions

There are two main ways to work with embedded instructions, depending on whether you are creating a new file or updating an existing one.

# Process instructions from an existing Markdown file
qmims edit

# Process instructions from a specific file
qmims edit path/to/README.md

# Generate using embedded instructions
qmims generate --mode instruct

# Generate using embedded instructions from a specific file
qmims generate --mode instruct:path/to/README.md

Use edit when you already have a Markdown file in place. Use generate --mode instruct when you want the instruction file itself to drive README creation.

Writing Effective Instructions

Kiro generally produces better results when your instructions are explicit, contextual, and format-aware.

Be Specific

Less effective

<!-- qmims: Write about installation. -->

More effective

<!-- qmims: Provide step-by-step installation instructions using the detected package manager, including prerequisites and a quick verification command. -->

Provide Context

Less effective

<!-- qmims: List the features. -->

More effective

<!-- qmims: List the main features of this authentication service based on the API routes, middleware, and token-handling modules. -->

Ask for a Format

Less effective

<!-- qmims: Document the commands. -->

More effective

<!-- qmims: Document the CLI commands as a Markdown table with columns for command, description, and example usage. -->

Control Length and Tone

Less effective

<!-- qmims: Describe the project. -->

More effective

<!-- qmims: Write a concise two-paragraph project overview in a practical, developer-focused tone. -->

Best practice

Treat each embedded instruction like a small prompt. The clearer you are about scope, source context, desired tone, and output format, the better the generated Markdown usually becomes.

Kiro Setup and Troubleshooting

Embedded instructions rely on the same Kiro-backed runtime as the rest of qmims. If processing fails, verify your environment first:

kiro-cli whoami
kiro-cli login
kiro-cli doctor

For headless or CI use, Kiro can authenticate with KIRO_API_KEY.

# Linux / macOS
export KIRO_API_KEY=your_api_key_here

# Windows PowerShell
$env:KIRO_API_KEY = "your_api_key_here"

Preview Before You Apply Changes

If you want to inspect the workflow before making updates, use dry-run mode:

qmims edit --dry-run
qmims generate --mode instruct --dry-run

Tip

Dry-run mode is especially useful when you are editing an important README, testing a new instruction style, or confirming which file qmims will target before invoking Kiro.

Example Use Cases

Updating installation steps

## Installation

<!-- qmims: Update the installation instructions to reflect the current runtime requirements, package manager commands, and setup verification steps. -->

Generating API documentation

## API Reference

<!-- qmims: Generate API documentation for the main exported functions and classes, including parameters, return values, and short usage notes. -->

Creating usage examples

## Usage Examples

<!-- qmims: Add 3 practical usage examples that reflect the most common developer workflows supported by this project. -->

Refreshing a migration note

## Migration Notes

<!-- qmims: Update this section to explain the migration from Amazon Q CLI to Kiro CLI, including new install, login, and troubleshooting commands. -->