Kiro Steering Documents Browser

A Kiro IDE extension for browsing, previewing, and installing steering documents from a GitHub repository. Discover and adopt community-created steering rules and conventions to guide Kiro's code generation.

Features

• AI-Powered Recommendations: Get smart document suggestions based on your workspace analysis
• Simple Toggle Control: One-click toggle to activate or deactivate steering documents
• Bulk Activation: Multi-select documents from recommendations for instant activation
• Smart Defaults: Automatic inclusion mode selection based on document metadata
• Kiro Sidebar Integration: Access documents directly from the Kiro sidebar alongside other Kiro tools
• Browse Documents: Explore available steering documents organized by category and folder hierarchy
• Hierarchical Organization: Navigate nested folder structures within categories for better document organization
• Preview Content: View document content before installation with markdown preview
• Quick Load: Install and activate documents in one action
• Manage Inclusion Modes: Control when Kiro loads specific guidance into the agent context
• Update Management: Check for and install updates to installed documents
• Offline Support: Continue browsing with cached data when offline

Requirements

• Kiro IDE: This extension requires Kiro IDE (not compatible with VS Code or other editors)

Getting Started

Installation

1. Install the extension from the Kiro extension marketplace
2. Open a workspace in Kiro
3. Find the "Steering Documents" view in the Kiro sidebar (left panel)

Basic Usage

Get Recommendations (Fastest Way)

1. Click the sparkle ✨ icon at the top of the Steering Documents view
2. Select documents from the Quick Pick (use Tab to multi-select)
3. Press Enter - documents activate instantly with smart defaults
4. Done! Documents are now active in your workspace

When to Use Recommendations

Recommendations analyze your package.json and project structure to suggest relevant documents. For best results, use them after your project dependencies are set up.

With Kiro Specs (Requirements → Design → Tasks):

1. Complete your Requirements document
2. Complete your Design document (defines your tech stack)
3. Set up your project: npm init and install main dependencies
4. Click recommendations ← sweet spot
5. Install the suggested steering docs
6. Execute your Tasks with guidance in place

For existing projects: Just click recommendations - your dependencies are already there.

No package.json yet? You can still browse all documents in the tree view and install manually. Run recommendations again after setting up your project to get personalized suggestions.

What gets analyzed:

• package.json dependencies and devDependencies
• tsconfig.json presence (TypeScript detection)
• Folder structure (components/, routes/, api/)
• Test file patterns (*.test.ts, *.spec.js)

Note: In multi-root workspaces, only the first workspace folder is analyzed.

Manual Browse & Install

1. Browse Documents: Expand categories in the tree view to see available steering documents
2. Preview: Click the eye icon (👁️) to preview a document's content
3. Toggle On/Off: Click the toggle button next to any document to activate or deactivate it
   • Toggle ON: Installs the document and activates it (sets inclusion to "always")
   • Toggle OFF: Removes the document from your workspace
4. Quick Load: Right-click a document and select "Quick Load" to install and immediately activate it

Inclusion Modes

Steering documents support three inclusion modes that control when Kiro loads them into the agent context:

Always

Documents are automatically loaded into every Kiro conversation. Use this for core guidelines you want Kiro to follow consistently.

Example: Coding standards, project conventions, team best practices

Visual Indicator: 🟢 Green dot in tree view

Manual

Documents are only loaded when you explicitly reference them using # in chat. Use this for specialized guidance you need occasionally.

Example: Deployment procedures, specific framework documentation

Visual Indicator: 🔵 Blue dot in tree view

File Match

Documents are automatically loaded when files matching a specific pattern are in context. Use this for language or framework-specific guidance.

Example: TypeScript guidelines (pattern: *.ts), React conventions (pattern: *.tsx)

Visual Indicator: 🟡 Yellow dot in tree view

Changing Inclusion Modes

1. Right-click an installed document in the tree view
2. Select "Set Inclusion: Always", "Set Inclusion: Manual", or "Set Inclusion: File Match"
3. For File Match mode, enter a glob pattern when prompted (e.g., *.ts, src/**/*.py)

Commands

Access these commands from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Document Management

• Get Recommendations (✨): AI-powered document suggestions with bulk activation
• Toggle Document: Simple on/off control for activating or deactivating documents
• Refresh: Reload the document list from GitHub
• Check for Updates: Check all installed documents for available updates
• Show Active Documents Only: Filter the tree view to show only documents with "always" inclusion mode
• Preview Document: View document content in a read-only editor
• Install Document: Download and save a document to .kiro/steering/
• Quick Load (Install & Activate): Install a document with "always" inclusion mode
• Update Document: Update an installed document to the latest version
• Set Inclusion: Always/Manual/File Match: Change how a document is loaded

Token Management

• Steering Docs: Set GitHub Token: Securely store your GitHub Personal Access Token using the OS credential manager
• Steering Docs: Clear GitHub Token: Remove your stored token from secure storage
• Steering Docs: Check Token Status: Verify your token configuration and test validity against GitHub API

Configuration

Configure the extension through Kiro Code settings (File > Preferences > Settings > Extensions > Kiro Steering Documents):

{
  // GitHub repository containing steering documents
  "steeringDocs.repository": "mikeartee/kiro-steering-docs",
  
  // Branch to fetch documents from
  "steeringDocs.branch": "main",
  
  // Cache timeout in seconds (default: 1 hour)
  "steeringDocs.cacheTimeout": 3600,
  
  // Automatically check for updates on activation
  "steeringDocs.autoCheckUpdates": true
}

Token Management

GitHub API has rate limits that affect how many documents you can browse and install:

Authentication	Rate Limit	Use Case
Anonymous (no token)	60 requests/hour	Public repos, light usage
Personal Access Token	5,000 requests/hour	Private repos, heavy usage

Setting Up a Token

1. Generate a token at GitHub Settings → Developer settings → Personal access tokens
2. Select scopes:
   • For public repos: No scopes required (read-only access is default)
   • For private repos: Select the repo scope
3. Run the command: Steering Docs: Set GitHub Token from the Command Palette
4. Paste your token in the secure input box (input is masked)

Your token is stored securely using the operating system's credential manager (Windows Credential Manager, macOS Keychain, or Linux Secret Service).

Token Commands

Command	Description
Steering Docs: Set GitHub Token	Securely store your GitHub token
Steering Docs: Clear GitHub Token	Remove your stored token
Steering Docs: Check Token Status	Verify token configuration and validity

Security Features

• Encrypted Storage: Tokens are stored using the SecretStorage API, which uses your OS credential manager
• No Settings Sync: Tokens are never synced to the cloud
• Audit Logging: Token operations are logged to the "Steering Docs Security Audit" output channel
• Automatic Migration: If you previously stored a token in settings.json, it will be automatically migrated to secure storage

Note: The legacy steeringDocs.githubToken setting is deprecated. Please use the "Set GitHub Token" command instead for secure storage.

Tree View Icons

The tree view uses icons to indicate document status and organization:

• ⚪ Not Installed: Circle outline - document is available for installation
• 🟢 Always Active: Green filled circle - inclusion mode is "always"
• 🔵 Manual: Blue filled circle - inclusion mode is "manual"
• 🟡 File Match: Yellow filled circle - inclusion mode is "fileMatch"
• 🟠 Update Available: Orange filled circle - an update is available (takes priority over inclusion mode colors)
• 📁 Category: Folder icon - document category grouping
• 📂 Folder: Folder icon - nested folder within a category (collapsible)

When an update is available, the document description shows the version change (e.g., "1.0.0 -> 1.1.0").

Examples

Example 1: Installing TypeScript Standards

1. Expand the "Code Formatting" category, then the languages folder
2. Find typescript-formatting.md
3. Click the eye icon to preview the content
4. Right-click and select "Quick Load (Install & Activate)"
5. The document is now active in all Kiro conversations

Example 2: Setting Up Language-Specific Guidance

1. Install python-formatting.md from "Code Formatting" → languages
2. Right-click the installed document
3. Select "Set Inclusion: File Match"
4. Enter pattern: *.py
5. The guide now loads automatically when working with Python files

Example 3: Using Manual Reference Documents

1. Install semantic-contracts-for-kiro.md from the "Semantic Anchors" category
2. Right-click and select "Set Inclusion: Manual"
3. In Kiro chat, reference it with: #semantic-contracts-for-kiro.md
4. Kiro loads the document only for that conversation

Kiro Steering Document Usage

Once installed, steering documents guide Kiro's behavior. Here's how they work:

Document Structure

Steering documents are markdown files with YAML frontmatter:

---
version: "1.0.0"
category: "coding-standards"
description: "TypeScript coding standards"
inclusion: "always"
---

# TypeScript Guidelines

## Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for classes and interfaces
...

How Kiro Uses Steering Documents

• Always mode: Content is included in every Kiro conversation automatically
• Manual mode: Content is included only when you reference the file with #filename.md
• File Match mode: Content is included when relevant files are in the conversation context

Best Practices

1. Start with Quick Load: Use Quick Load for essential documents you want active immediately
2. Use File Match for Language Rules: Set language-specific guides to fileMatch mode
3. Keep Manual for Reference: Use manual mode for checklists and procedures
4. Review Before Installing: Always preview documents to understand their guidance
5. Update Regularly: Check for updates to get the latest best practices

Troubleshooting

Documents Not Loading

Problem: Tree view shows "Loading..." indefinitely

Solutions:

• Check your internet connection
• Verify the GitHub repository is accessible
• Try clicking the Refresh button
• Check the Output panel (View > Output) and select "Kiro Steering Documents" for error details

Installation Fails

Problem: Error when installing a document

Solutions:

• Ensure you have write permissions to the workspace
• Check that .kiro/steering/ directory is not read-only
• Verify disk space is available
• Try installing to a different workspace

Updates Not Detected

Problem: Update indicators don't appear for installed documents

Solutions:

• Click "Check for Updates" in the tree view toolbar
• Verify steeringDocs.autoCheckUpdates is enabled in settings
• Clear the cache by reloading Kiro
• Check that installed documents have valid version frontmatter

Inclusion Mode Not Working

Problem: Document with "always" mode doesn't appear in Kiro context

Solutions:

• Verify the frontmatter includes inclusion: "always"
• Reload Kiro to ensure changes are picked up
• Check the document is in .kiro/steering/ directory
• Ensure the document has valid YAML frontmatter

Offline Mode Issues

Problem: Cannot browse documents when offline

Solutions:

• The extension caches the last successful document list
• Connect to the internet and click Refresh to update the cache
• Cached data expires after the configured timeout (default: 1 hour)
• Installed documents remain accessible offline

GitHub Rate Limiting

Problem: "Rate limit exceeded" error

Solutions:

• GitHub API allows 60 requests/hour for unauthenticated users
• Wait for the rate limit to reset (check error message for reset time)
• Configure a GitHub Personal Access Token using Steering Docs: Set GitHub Token command
• Use Steering Docs: Check Token Status to verify your token is working
• Use cached data while waiting for rate limit reset

Token Issues

Problem: Token not working or missing after IDE update

Solutions:

• Run Steering Docs: Check Token Status to verify token configuration
• If token is missing, re-enter it using Steering Docs: Set GitHub Token
• Check the "Steering Docs Security Audit" output channel for error details
• Note: VS Code SecretStorage has a known issue (#193301) that can cause token loss after IDE updates - simply re-enter your token if this occurs

Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues: Found a bug? Open an issue on GitHub with details
2. Suggest Features: Have an idea? Create a feature request
3. Submit Pull Requests: Want to contribute code? Fork the repo and submit a PR
4. Share Steering Documents: Create and share your own steering documents

Development Setup

# Clone the repository
git clone https://github.com/mikeartee/kiro-steering-docs-extension.git

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run tests
npm test

# Launch extension in debug mode
# Press F5 in Kiro

Support

For issues, feature requests, or contributions:

• GitHub Repository: mikeartee/kiro-steering-docs-extension
• Report Issues: Check existing issues before creating new ones
• Include Details: Kiro version, extension version, and error messages help us help you

License

MIT License - see LICENSE file for details

Copyright (c) 2025-2026 Michael Rewiri-Thorsen

Changelog

See CHANGELOG.md for the full version history.

Acknowledgments

• Built for the Kiro IDE ecosystem
• Inspired by package managers and extension browsers
• Thanks to the Kiro community for feedback and testing