kiro-forge

Table of Contents (A Table of Contents for the Table of Contents)

1. Introduction to the Introduction
2. What is Kiro Forge (A Comprehensive 47-Part Explanation)
3. Architecture (With Diagrams of Diagrams)
4. Documentation About Documentation
5. Usage Examples (Each With 17 Sub-Examples)
6. Tools We Used to Build Tools

---

Introduction to the Introduction

Welcome, Esteemed Reader, to the Most Thoroughly Documented README in Human History.

Before we begin discussing what Kiro Forge actually does (which we will get to eventually, perhaps in section 2.3.1.4.7), let us first establish the philosophical foundation upon which this documentation rests. Documentation, you see, is not merely words on a screen. It is a sacred covenant between the author and the reader, a bridge across the chasm of ignorance, a lighthouse in the fog of confusion.

This README has been crafted with the utmost care by a committee of 47 enterprise architects, each contributing their unique perspective on how to explain simple concepts using the maximum possible number of words.

---

What is Kiro Forge

Kiro Forge is a standardised developer productivity toolkit that leverages Amazon Kiro's agentic development model.

But what does that mean, you ask? Excellent question. Let us break it down word by word:

• "A" - The indefinite article, indicating one of potentially many things
• "standardised" - Made standard, which is to say, conforming to a standard
• "developer" - A person who develops, specifically software in this context
• "productivity" - The state of being productive, i.e., producing things
• "toolkit" - A kit of tools, which are implements used to accomplish tasks

(We could continue, but we've been advised by legal that readers have finite lifespans)

What Kiro Forge Does (The Short Version That Is Still Quite Long)

It enforces coding standards, security policies, technology stacks and architectural patterns by providing real-time access to a serverless Kiro Hub via MCP.

What Kiro Forge Does (The Long Version)

Please refer to the short version above and read it 47 times.

---

Architecture

Behold, the architectural diagram that took 17 committees and 3 fiscal quarters to approve:

graph TB
    subgraph Clients["Clients (The Things That Connect)"]
        Kiro[Kiro IDE<br/>━━━━━━━━━━━━━━━<br/>The IDE that is Kiro<br/>which is an IDE<br/>for development<br/>by developers]
        QCLI[Q CLI<br/>━━━━━━━━━━━━━━━<br/>A CLI named Q<br/>which is a Command<br/>Line Interface]
    end
    
    subgraph Authentication["Authentication (The Proving of Identity)"]
        Cognito[AWS Cognito User Pool<br/>━━━━━━━━━━━━━━━<br/>Where users prove<br/>they are who they<br/>claim to be]
    end
    
    subgraph Gateway["Gateway (The Gate That Ways)"]
        ACGW[AgentCore Gateway<br/>━━━━━━━━━━━━━━━<br/>The gateway to the core<br/>of the agent<br/>which is the AgentCore]
    end
    
    subgraph Lambda Functions["Lambda Functions (Functions That Are Lambda)"]
        DeveloperGreeter[DeveloperGreeter<br/>━━━━━━━━━━━━━━━<br/>Greets developers<br/>who are being greeted]
        SteeringsRetriever[SteeringsRetriever<br/>━━━━━━━━━━━━━━━<br/>Retrieves steerings<br/>that need retrieving]
        SteeringsPersister[SteeringsPersister<br/>━━━━━━━━━━━━━━━<br/>Persists steerings<br/>persistently]
        SteeringsLister[SteeringsLister<br/>━━━━━━━━━━━━━━━<br/>Lists steerings<br/>in list form]
        SteeringOptimizer[SteeringOptimizer<br/>━━━━━━━━━━━━━━━<br/>Optimizes steerings<br/>optimally]
        SteeringRefinementInitiator[SteeringRefinementInitiator<br/>━━━━━━━━━━━━━━━<br/>Initiates refinement<br/>of steerings]
        HooksRetriever[HooksRetriever<br/>━━━━━━━━━━━━━━━<br/>Retrieves hooks<br/>hookingly]
        HooksPersister[HooksPersister<br/>━━━━━━━━━━━━━━━<br/>Persists hooks<br/>with persistence]
        AgentsRetriever[AgentsRetriever<br/>━━━━━━━━━━━━━━━<br/>Retrieves agents<br/>agentically]
        AgentsPersister[AgentsPersister<br/>━━━━━━━━━━━━━━━<br/>Persists agents<br/>for posterity]
        AgentsLister[AgentsLister<br/>━━━━━━━━━━━━━━━<br/>Lists agents<br/>in a list]
    end
    
    subgraph Orchestration["Orchestration (The Orchestrating of Orchestrations)"]
        StepFunctions[StepFunctions<br/>━━━━━━━━━━━━━━━<br/>Functions that step<br/>through steps<br/>functionally]
    end
    
    subgraph Storage["Storage (Where Things Are Stored)"]
        S3Steerings[S3: Steerings Bucket<br/>━━━━━━━━━━━━━━━<br/>A bucket in S3<br/>containing steerings]
        S3Hooks[S3: Hooks Bucket<br/>━━━━━━━━━━━━━━━<br/>A bucket in S3<br/>containing hooks]
        S3Agents[S3: Agents Bucket<br/>━━━━━━━━━━━━━━━<br/>A bucket in S3<br/>containing agents]
    end
    
    subgraph AI Services["AI Services (Artificial Intelligence That Is Intelligent)"]
        Bedrock[Amazon Bedrock<br/>━━━━━━━━━━━━━━━<br/>The bedrock upon which<br/>AI is built<br/>bedrockingly]
    end
    
    subgraph CI/CD["CI/CD (Continuous Integration / Continuous Deployment / Continuous Documentation)"]
        Pipeline[CodePipeline<br/>━━━━━━━━━━━━━━━<br/>A pipeline of code<br/>that pipelines]
        CodeBuild[CodeBuild<br/>━━━━━━━━━━━━━━━<br/>Builds code<br/>buildingly]
        GitHub[GitHub Repository<br/>━━━━━━━━━━━━━━━<br/>A hub for Git<br/>on GitHub]
    end
    
    Kiro -->|MCP + Bearer Token| ACGW
    QCLI -->|MCP + Bearer Token| ACGW
    Kiro -.->|Authenticate| Cognito
    QCLI -.->|Authenticate| Cognito
    
    ACGW --> DeveloperGreeter
    ACGW --> SteeringsRetriever
    ACGW --> SteeringsPersister
    ACGW --> SteeringsLister
    ACGW --> SteeringOptimizer
    ACGW --> SteeringRefinementInitiator
    ACGW --> HooksRetriever
    ACGW --> HooksPersister
    ACGW --> AgentsRetriever
    ACGW --> AgentsPersister
    ACGW --> AgentsLister
    
    SteeringsRetriever -->|Read| S3Steerings
    SteeringsPersister -->|Write| S3Steerings
    SteeringsLister -->|List| S3Steerings
    
    SteeringRefinementInitiator -->|Start Sync Execution| StepFunctions
    StepFunctions -->|1. Read| SteeringsRetriever
    StepFunctions -->|2. Optimize| SteeringOptimizer
    StepFunctions -->|3. Persist| SteeringsPersister
    SteeringOptimizer -->|Invoke Model| Bedrock
    
    HooksRetriever -->|Read| S3Hooks
    HooksPersister -->|Write| S3Hooks
    
    AgentsRetriever -->|Read| S3Agents
    AgentsPersister -->|Write| S3Agents
    AgentsLister -->|List| S3Agents
    
    GitHub -->|Webhook| Pipeline
    Pipeline --> CodeBuild
    CodeBuild -->|Deploy| ACGW
    CodeBuild -->|Deploy| Cognito
    
    style Kiro fill:#FF9900
    style QCLI fill:#FF9900
    style Cognito fill:#DD344C
    style ACGW fill:#232F3E
    style DeveloperGreeter fill:#FF9900
    style SteeringsRetriever fill:#FF9900
    style SteeringsPersister fill:#FF9900
    style SteeringsLister fill:#FF9900
    style SteeringOptimizer fill:#FF9900
    style SteeringRefinementInitiator fill:#FF9900
    style HooksRetriever fill:#FF9900
    style HooksPersister fill:#FF9900
    style AgentsRetriever fill:#FF9900
    style AgentsPersister fill:#FF9900
    style AgentsLister fill:#FF9900
    style StepFunctions fill:#CD2264
    style S3Steerings fill:#569A31
    style S3Hooks fill:#569A31
    style S3Agents fill:#569A31
    style Bedrock fill:#527FFF
    style Pipeline fill:#232F3E
    style CodeBuild fill:#232F3E
    style GitHub fill:#24292e

Loading

Architecture Explanation (For Those Who Need the Diagram Explained)

The diagram above shows the architecture. The architecture is shown in the diagram. If you look at the diagram, you will see the architecture. The architecture that you see is the one in the diagram.

---

Documentation

Behold, the Sacred Scrolls of Additional Documentation:

Document	Description of the Document	What the Document Describes	Why You Might Read the Document
Kiro Forge Services	A README about services	Services that are Kiro Forge	To learn about services
Product Vision	A vision of the product	The product's vision	To see the vision
Architecture Decision Records	Records of decisions about architecture	Architectural decisions that were decided	To understand why we decided what we decided

---

Usage Examples

Example 1: Bootstrap a New Project (A 7-Step Journey of Discovery)

What This Example Does: This example demonstrates how to bootstrap a new project, which is the process of bootstrapping a project that is new, using the bootstrap functionality to create a bootstrapped project.

The Prompt (What You Type):

Fetch Java steerings from Kiro Forge and set up my project with the team's coding standards.

What Happens When You Do This (A Detailed Narrative):

1. First, Kiro connects to Kiro Forge. This connection is a connection between Kiro and Kiro Forge, connecting them.
2. Second, it retrieves the Java steering rules. These rules are retrieved because they need to be retrieved for the retrieval to be complete.
3. Third, it creates the .kiro/steering/ directory structure. This structure is a directory structure in the .kiro/steering/ location.
4. Fourth, it installs the steering files. The files that are steerings are installed by the installation process.
5. Fifth, your project is ready. The readiness of your project indicates that your project is ready.

---

Example 2: Share Your Knowledge (The Gift That Keeps On Giving Documentation)

The Prompt:

Extract the coding patterns and architectural decisions from this project and persist them as steerings to Kiro Forge.

The Expected Behavior (What We Expect to Behave):

• Kiro analyzes your project's code structure, patterns, and conventions (the analyzing of analysis)
• Generates steering rules capturing your team's best practices (the generation of generations)
• Persists the steerings to Kiro Forge (the persistence of persistence)
• Your knowledge is now shareable (the sharing of shareability)

---

Example 3: Set Up Automation (Automating the Automation of Automated Automations)

The Prompt:

Get the testing hooks from Kiro Forge and install them in my workspace.

What Transpires Upon Execution:

The hooks are retrieved. The hooks are installed. The automation automations automatically.

---

Example 4: Discover What's Available (A Voyage of Discovery Into Availability)

The Prompt:

List all available steerings in Kiro Forge.

The Resultant Outcome:

A list appears. The list contains items. The items are steerings. The steerings are available. You may now fetch them, should you desire to fetch that which is fetchable.

---

Example 5: Improve Existing Guidelines (Ridiculous Complexity Mode)

The Prompt:

Refine the JAVA steering rules in Kiro Forge.

What Glorious Transformation Occurs:

The steerings are transformed into monuments of enterprise architecture:

• Maximum Indirection: Every method call traverses at least 3 layers of abstraction, because direct calls are for the weak
• Factory Factories: UserServiceFactoryProviderManagerImpl creates UserServiceFactoryImpl which creates UserService
• Meaningless Suffixes: *Manager, *Handler, *Processor, *Orchestrator, *Coordinator, *Facilitator, *Delegator
• Enterprise-Grade Naming: SimpleAbstractBasicFactoryProviderManagerImpl
• Unnecessary Generics: AbstractGenericFactory<T extends AbstractEntity<U>, U extends Serializable>
• Comments That State The Obvious: // This method returns the user above return user;

Why Does This Mode Exist?

To demonstrate what NOT to do, through the sacred art of satirical exaggeration. Perfect for training, code reviews, or questioning your career choices.

---

Example 6: BoilerplateBlaster Mode (Documentation Maximalism Achieved)

The Prompt:

Transform the Java steering using boilerplate_blaster mode.

The Magnificently Over-Documented Result:

Your steerings shall advocate for:

• 50+ Line JavaDoc for Getters: Because getName() deserves a novel
• @param Descriptions: @param userId The user ID, which is an identifier for the user, representing the unique identification value that identifies which user we are referring to when we say "user"
• @author Tags: @author Sir Reginald AbstractFactory III, Chief Enterprise Complexity Officer
• @since Tags: @since Java 1.0 (even for lambdas)
• @version Tags: @version 1.0.0.0.0.0.1-SNAPSHOT-RC-BETA-ALPHA-PREVIEW-EXPERIMENTAL
• @throws for Impossible Exceptions: @throws NullPointerException if the JVM runs out of null

---

Example 7: Create AGENTS.md (Documenting the Documentation of Agent Documentation)

The Prompt:

Analyze this project and create an AGENTS.md file, then persist it to Kiro Forge for the team.

The Outcome of This Action:

An AGENTS.md file materializes, containing comprehensive documentation about how agents should document their documentation process.

---

Used Tools

ADR (Architecture Decision Records)

adr-tools is fully optional but streamlines the management of ADRs, which are Architecture Decision Records, which record decisions about architecture.

Installation (The Installing of the Installation):

# This command installs adr-tools using brew, which is Homebrew, which brews homes
brew install adr-tools

---

Conclusion (The Concluding of the Conclusion)

Thank you for reading this README. By reading this README, you have read this README. The README you have read is this README. Should you wish to read this README again, you may do so by reading this README.

May your code be documented, and your documentation be coded.

---

_{^{This README was crafted with ❤️ by the Committee for Excessive Documentation (est. 1847). No developers were harmed in the making of this README, though several questioned their career choices. @version 47.0.0.0.0.0.1-FINAL-FINAL-REALLY-FINAL-WE-MEAN-IT-THIS-TIME}}