Kiro Rails - Lightweight Development Guardrails

Simple, effective constraints that help AWS Kiro deliver production-ready software. Now enhanced with Kiro's Specification-Driven Development for maximum precision.

What is Kiro Rails?

Kiro Rails is a minimal framework that prevents common AI assistant pitfalls through:

• Time-based gates that ensure real progress
• Scope limits that prevent overwhelming changes
• DRS scoring that measures actual deployability (now includes integration testing)
• Evidence requirements that prove functionality
• Architecture preservation that prevents breaking existing interfaces
• Contract validation that detects risky changes to APIs and schemas
• Specification compliance that ensures alignment with requirements, design, and tasks (Kiro-specific)

Quick Start (2 Minutes)

1. Install Kiro Rails

# Clone or download Kiro Rails to your project
cp -r /path/to/kiro-rails ./kiro-rails

# Make scripts executable
chmod +x kiro-rails/scripts/*.sh

# Initialize your project
bash kiro-rails/scripts/init.sh

2. Tell AWS Kiro About It

When starting a session with AWS Kiro, simply say:

I'm using Kiro Rails. Please read KIRO.md first.
Also review the specifications in .kiro/specs/PROJECT_NAME/

That's it! Kiro will now follow the framework automatically.

3. Use the Commands

# Check your deployment readiness (DRS score)
bash kiro-rails/scripts/check-drs.sh

# Verify specification compliance (Kiro-specific)
bash kiro-rails/scripts/check-specification.sh

# Verify you're following the rules
bash kiro-rails/scripts/verify.sh

# Capture proof of functionality
bash kiro-rails/scripts/capture-evidence.sh api "Login endpoint working"

Core Principles

1. Real Services After 30 Minutes

• First 30 minutes: Setup and exploration allowed
• After 30 minutes: MUST use real APIs/databases
• No permanent mocks in production code

2. Scope Control

• Maximum 5 files changed per session
• Maximum 200 lines of code added
• One feature at a time

3. Time Gates

Time	Requirement
30min	Real services connected
60min	One feature working
90min	Error handling complete
120min	DRS ≥ 85 (deployable)

4. Evidence-Based Progress

• Capture API responses
• Save test results
• Document what's working

How It Helps AWS Kiro

Without Kiro Rails:

• Kiro might create elaborate mocks that never get replaced
• Changes might span 20+ files making review impossible
• "Looks good" code that doesn't actually work
• No clear definition of "done"
• Accidentally breaks working interfaces and contracts
• Changes APIs without considering downstream impacts
• Deviates from the original requirements and design
• Adds unnecessary features not in the specification

With Kiro Rails:

• Real integrations from the start
• Manageable, reviewable changes
• Proven functionality with evidence
• Clear deployment criteria (DRS ≥ 85)
• Protects existing architecture from unintended changes
• Requires confidence declarations for risky modifications
• Enforces integration testing for interface changes
• Specification-driven: Stays aligned with .kiro/specs/PROJECT/requirements.md, design.md, tasks.md
• Contract preservation: Validates changes against documented interfaces

File Structure

your-project/
├── KIRO.md                  # Rules for Kiro (auto-created)
├── .kiro/                   # Kiro native directory
│   └── specs/              # Project specifications
│       └── PROJECT_NAME/   # Your project specs
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
├── .kiro-active             # Active project marker (optional)
├── kiro-rails/
│   ├── README.md            # This file
│   ├── KIRO.md              # Template rules
│   └── scripts/
│       ├── init.sh          # Project setup
│       ├── check-drs.sh     # Deployment readiness score
│       ├── verify.sh        # Compliance check
│       ├── capture-evidence.sh  # Proof capture
│       ├── ready-to-deploy.sh   # Final deployment check
│       └── diagnose.sh      # Problem diagnosis
├── evidence/                # Captured proofs (auto-created)
└── .kiro-rails/             # Session tracking (auto-created)

Commands Reference

init.sh

Initializes a project with Kiro Rails. Creates necessary directories and files.

check-drs.sh

Calculates your Deployment Readiness Score (0-100):

• 85+ = Ready to deploy
• 70-84 = Close, fix remaining issues
• <70 = Significant work needed

Now includes:

• Actual test execution verification (not just existence)
• Integration test requirements for interface changes
• Stricter scoring for production readiness

verify.sh

Quick compliance check:

• Mock timeout enforcement
• Scope limits
• Evidence freshness
• Time gate status
• Confidence declaration tracking
• Contract integrity validation

capture-evidence.sh <type> <description>

Captures proof of functionality:

• api - API responses
• db - Database connections
• test - Test results
• integration - Integration test results
• perf - Performance metrics
• error - Error handling
• feature - Feature completion

ready-to-deploy.sh

Comprehensive deployment check:

• Runs all validations
• Ensures DRS ≥ 85
• Verifies no critical issues

check-contracts.sh

Detects risky interface changes:

• Identifies modified API/schema files
• Tracks function signature changes
• Validates database schema modifications
• Ensures contract changes are documented
• Checks for integration test coverage

check-specification.sh (Kiro-Enhanced)

Validates alignment with Kiro's specification files:

• Ensures changes match .kiro/specs/PROJECT/requirements.md
• Validates architecture against .kiro/specs/PROJECT/design.md
• Tracks progress in .kiro/specs/PROJECT/tasks.md
• Prevents scope creep and contract violations
• Calculates specification compliance score

diagnose.sh

Identifies what's blocking progress:

• Finds mocks in code
• Checks test status
• Reviews scope compliance
• Suggests quick fixes

Integration with AWS Kiro

Kiro Rails enhances AWS Kiro by:

1. Providing Clear Constraints - Kiro knows exactly what's allowed
2. Enforcing Quality Gates - Can't proceed without meeting standards
3. Tracking Real Progress - DRS score shows actual deployability
4. Preventing Scope Creep - Hard limits on changes
5. Requiring Proof - Evidence captures prevent "theoretical" code
6. Specification Alignment - Ensures Kiro follows .kiro/specs/PROJECT/ specifications
7. Contract Preservation - Prevents breaking changes to interfaces

The Power of Specification + Rails

When Kiro's specification-driven development meets Kiro Rails:

• Specifications define WHAT and HOW
• Rails ensure it's built CORRECTLY and DEPLOYABLY
• Together they prevent ALL major AI coding pitfalls

Examples

Starting a New Feature

# 1. Initialize session
bash kiro-rails/scripts/init.sh

# 2. Tell Kiro
"I need to add user authentication. Using Kiro Rails."

# 3. Kiro reads KIRO.md and follows rules automatically

# 4. Check progress periodically
bash kiro-rails/scripts/verify.sh

Fixing Bugs

# 1. Check current state
bash kiro-rails/scripts/check-drs.sh

# 2. Tell Kiro
"Fix the login bug. Remember Kiro Rails rules - max 5 files."

# 3. Capture evidence when fixed
bash kiro-rails/scripts/capture-evidence.sh feature "Login bug fixed"

Preparing for Deployment

# 1. Full check
bash kiro-rails/scripts/ready-to-deploy.sh

# 2. If not ready, diagnose
bash kiro-rails/scripts/diagnose.sh

# 3. Fix issues, then recheck

FAQ

Q: Do I need to modify my project? A: No, Kiro Rails only adds a KIRO.md file and creates evidence/ and .kiro-rails/ directories.

Q: What if I'm not using git? A: Some features (scope tracking) work best with git, but the framework still functions without it.

Q: Can I customize the rules? A: Yes, edit KIRO.md after initialization to adjust limits and requirements.

Q: What if scripts don't work on my system? A: The scripts are bash-based. On Windows, use Git Bash or WSL. Alternatively, follow the rules manually.

Q: Does this slow down development? A: No, it prevents the rework that comes from shipping broken code. The constraints actually speed up delivery of working software.

Troubleshooting

"Scripts not executable"

chmod +x kiro-rails/scripts/*.sh

"Command not found"

Make sure to include the path:

bash kiro-rails/scripts/check-drs.sh
# not just: check-drs.sh

"No evidence directory"

Run init first:

bash kiro-rails/scripts/init.sh

Support

For issues or suggestions, please open an issue on the GitHub repository.

License

MIT - Use freely in your projects.

---

Remember: Kiro Rails helps you ship working code, not perfect code. Focus on getting to DRS ≥ 85 and deploy with confidence!