Kiro Project Init

[PROJECT_NAME]/
├── .kiro/
│   ├── steering/          # 6 files: product, tech, structure, api-standards, testing-standards, security-policies
│   ├── hooks/             # 4 files: test-sync, documentation-update, security-scan, cost-check
│   └── specs/.gitkeep
├── .vscode/mcp.json
├── .cursor/mcp.json
├── .gitignore
├── .env.example
└── README.md

---
inclusion: always
---

# Product Overview: [PROJECT_NAME]

## Purpose

[2-3 paragraphs: what it does, why it exists]

## Target Users

[Who uses this]

## Key Features

[3-7 core features]

## Business Objectives

[Business goals]

## Success Metrics

[3-5 key metrics]

---
inclusion: always
---

# Technology Stack: [PROJECT_NAME]

## Primary Technologies

- **Frontend**: [e.g., React 18, TypeScript, Vite]
- **Backend**: [e.g., Python 3.12, FastAPI]
- **Database**: [e.g., DynamoDB, Aurora PostgreSQL]
- **Infrastructure**: [e.g., AWS CDK, Lambda, API Gateway]
- **Testing**: [e.g., Jest, Pytest, Playwright]

## AWS Services

- **Compute**: [Lambda, ECS, EC2]
- **Storage**: [S3, DynamoDB, Aurora]
- **Networking**: [API Gateway, CloudFront, VPC]
- **AI/ML**: [Bedrock, SageMaker]
- **Monitoring**: [CloudWatch, X-Ray, CloudTrail]

## MCP Servers Configured

- **aws-mcp** (unified AWS MCP Server): AWS service management, AWS documentation search and reads, regional availability, and AWS skills — one server covering all AWS access for this project

## Development Tools

- **IDE**: [VS Code, Cursor]
- **Version Control**: [Git, GitHub]
- **CI/CD**: [GitHub Actions, CodePipeline]
- **Package Management**: [npm, pip, poetry]

## Technical Constraints

[Limitations, requirements]

## Architecture Decisions

[Key choices and rationale]

---
inclusion: always
---

# Project Structure: [PROJECT_NAME]

## Directory Organization

## Naming Conventions
- **Components**: PascalCase (`UserProfile.tsx`)
- **Utilities**: camelCase (`formatDate.ts`)
- **Tests**: `.test.ts` suffix (`UserProfile.test.tsx`)
- **Types**: `.types.ts` suffix (`User.types.ts`)
## Import Patterns
- Absolute imports: `@/components/Button`
- Group: external, internal, types, styles
- Prefer named exports
## Infrastructure Location
[e.g., `infrastructure/`, `cdk/`]

---
inclusion: fileMatch
fileMatchPattern: "**/{api,routes,endpoints,controllers}/**/*.{ts,js,py}"
---

# API Standards: [PROJECT_NAME]

## REST Conventions

- Plural nouns: `/users`, `/products`
- Methods: GET (read), POST (create), PUT (update), DELETE (delete)
- Status: 200 (success), 201 (created), 400 (client error), 500 (server error)

## Response Format

```typescript
// Success
{ "data": {}, "meta": { "timestamp": "ISO 8601", "requestId": "uuid" }}
// Error
{ "error": { "code": "ERROR_CODE", "message": "...", "details": {} }, "meta": {...}}
```

### .kiro/steering/testing-standards.md
```markdown
---
inclusion: fileMatch
fileMatchPattern: "**/*.{test,spec}.{ts,js,tsx,jsx,py}"
---
# Testing Standards: [PROJECT_NAME]
## Organization
- Co-locate: `Component.tsx` → `Component.test.tsx`
- Or mirror in `__tests__/`
## Structure
```typescript
describe('[ComponentName]', () => {
  describe('[method]', () => {
    it('should [behavior] when [condition]', () => {
      // Arrange, Act, Assert
    });
  });
});

### .kiro/steering/security-policies.md
```markdown
---
inclusion: always
---
# Security Policies: [PROJECT_NAME]
## Credential Management
- NEVER commit secrets
- Use environment variables
- Store in Secrets Manager/Parameter Store
- Document in `.env.example`
## Input Validation
- Validate ALL inputs
- Parameterized queries
- CSRF protection
- Length limits
## Authentication & Authorization
[Auth flows, authorization rules]
## Data Protection
[Encryption at rest/transit, PII handling]
## Compliance
[HIPAA, GDPR, SOC 2, PCI DSS]
## Security Scanning
- cdk-nag for CDK stacks
- Checkov for Terraform
- Well-Architected Framework review guidance via `aws___search_documentation` / `aws___read_documentation`
## Incident Response
[Procedures]

{
  "name": "Test File Synchronization",
  "description": "Auto-creates/updates test files on save",
  "version": "1",
  "when": {
    "type": "fileSaved",
    "patterns": ["src/**/*.{ts,tsx,js,jsx}"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Source file saved:\n1. Check for test file (.test.ts/.test.tsx)\n2. If missing: Create with tests for all exports per testing-standards.md\n3. If exists: Add tests for untested functionality\n4. Follow structure.md conventions\n5. Don't modify source\n\nRef: #[[file:.kiro/steering/testing-standards.md]] #[[file:.kiro/steering/structure.md]]"
  }
}

{
  "name": "API Documentation Updater",
  "description": "Updates API docs on API file changes",
  "version": "1",
  "when": {
    "type": "fileSaved",
    "patterns": ["src/{api,routes,endpoints,controllers}/**/*.{ts,py}"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "API file modified:\n1. Analyze endpoint/parameter/response changes\n2. Update OpenAPI spec in api-specs/\n3. Use aws___search_documentation / aws___read_documentation for AWS patterns\n4. Update README API section\n5. Update JSDoc/docstrings\n6. Verify api-standards.md compliance\n\nRef: #[[file:.kiro/steering/api-standards.md]]"
  }
}

{
  "name": "Security Validation Scanner",
  "description": "Pre-commit security scan",
  "version": "1",
  "when": { "type": "manual" },
  "then": {
    "type": "askAgent",
    "prompt": "Security scan:\n1. Scan for: credentials, API keys, console.log with sensitive data, SQL injection, unsafe eval()\n2. Infrastructure: run cdk-nag against CDK stacks and Checkov against Terraform\n3. Verify security-policies.md: input validation, auth checks, encryption\n4. Report: issues by severity (CRITICAL/HIGH/MEDIUM/LOW), locations, fixes, pass/fail\n\nRef: #[[file:.kiro/steering/security-policies.md]]"
  }
}

{
  "name": "Infrastructure Cost Estimator",
  "description": "Estimates cost impact",
  "version": "1",
  "when": {
    "type": "fileSaved",
    "patterns": ["{infrastructure,cdk,terraform}/**/*", "**/*.template.{json,yaml,yml}"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Infrastructure modified:\n1. Identify added/modified/removed resources\n2. Price each resource with the AWS Price List Query API (`aws pricing get-products`, via aws___call_aws) or the AWS Pricing Calculator: costs per resource, region pricing, data transfer, compare previous\n3. Report: monthly estimate, delta, optimizations, unexpected costs\n4. Append to infrastructure/cost-estimates.md\n5. Flag if increase > $[THRESHOLD, e.g., 500]\n\nNote: cost figures are estimates — state assumptions explicitly"
  }
}

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws-cli@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--skip-auth"
      ],
      "env": {
        "AWS_REGION": "[us-east-1]",
        "AWS_PROFILE": "[profile-name]"
      }
    }
  }
}

mcp.json.local
.env
*.log
mcp-*.log
.mcp-cache/
.aws/
.vscode/
.cursor/
.idea/
node_modules/
__pycache__/
.venv/
venv/
dist/
build/
*.js.map
.DS_Store
Thumbs.db

AWS_REGION=us-east-1
AWS_PROFILE=your-profile
DATABASE_CLUSTER_ARN=arn:aws:rds:...
DATABASE_SECRET_ARN=arn:aws:secretsmanager:...
# API_KEY=your-key
COST_ALERT_THRESHOLD=500

# [PROJECT_NAME]

[Brief description]

## Structure

- `.kiro/steering/` - AI context, standards
- `.kiro/hooks/` - Automated workflows
- `.kiro/specs/` - Feature specs (requirements, design, tasks)
- `.vscode/mcp.json`, `.cursor/mcp.json` - MCP configs

## Prerequisites

1. **uv**: install per the official guide (https://docs.astral.sh/uv/getting-started/installation/), e.g. `brew install uv` or `pipx install uv`
2. **Python 3.10+**: `uv python install 3.10`
3. **AWS CLI**: Configured
4. **Node.js**: [version]

### AWS Setup

```bash
aws configure --profile [PROFILE]
export AWS_PROFILE=[PROFILE]
export AWS_REGION=[REGION]
```

## Install
[npm install / pip install]
## Configure
cp .env.example .env
## Edit .env
## Verify MCP
timeout 15s uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp --skip-auth 2>&1 || echo "OK"

"Use aws-mcp to read CloudWatch error logs from the last hour"
"Use aws-mcp to query the AWS Price List API and estimate costs for 3 Lambda functions"

## Logs
tail -f ~/Library/Logs/Claude/mcp*.log  # Mac
tail -f %APPDATA%/Claude/mcp*.log       # Windows
## Clear cache
uv cache clean mcp-proxy-for-aws-cli
## Test
timeout 15s uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp --skip-auth 2>&1

aws sts get-caller-identity --profile [PROFILE]

## TASK 6: INITIAL FEATURE SPEC
Create `.kiro/specs/[app-name]-core/` with three files:
### requirements.md
```markdown
# Requirements: [FEATURE_NAME]
## Overview
[2-3 paragraphs from PROJECT CONTEXT]
## User Personas
[From PROJECT CONTEXT]
## User Story 1: [From Core Features]
As a [persona]
I want to [action]
So that [benefit]
### Acceptance Criteria
WHEN [action/event]
THE SYSTEM SHALL [behavior]
AND THE SYSTEM SHALL [behavior]
WHEN [error condition]
THE SYSTEM SHALL [error handling]
[Repeat for each core feature]
## Non-Functional Requirements
### Performance
- Response time: [define]
- Throughput: [define]
- Scalability: [define]
### Security
- Authentication: [from PROJECT CONTEXT]
- Authorization: [define]
- Data protection: [encryption, PII]
### Reliability
- Availability: [define]
- Error handling: [define]
- Monitoring: [define]
## External Dependencies
[List with integration requirements]
## Data Requirements
[Schema, access patterns, retention]
## Out of Scope
[What's NOT included]

# Design: [FEATURE_NAME]

## Architecture

[High-level using tech stack from PROJECT CONTEXT]

```text
[ASCII component diagram]
```

{
  id: string;
  [field]: type;
  createdAt: timestamp;
  updatedAt: timestamp;
}

{ [param]: type; }

{ data: {...}, meta: {...} }

infrastructure/
├── lib/[feature]-stack.ts
└── bin/app.ts

### tasks.md
```markdown
# Tasks: [FEATURE_NAME]
## Task 1: Setup Infrastructure
**Status**: pending | **Depends**: none | **Effort**: 2-4h
### Description
Create base infrastructure: VPC, security groups, foundational resources
### Acceptance Criteria
- [ ] CDK initialized
- [ ] VPC with subnets
- [ ] Security groups
- [ ] IAM roles (least-privilege)
- [ ] CDK Nag passes
- [ ] Deploys to dev
### Files
- `infrastructure/lib/foundation-stack.ts`
- `infrastructure/bin/app.ts`
### Testing
- Deploy to dev
- Verify in Console
- Run CDK Nag
---
## Task 2: Data Layer
**Status**: pending | **Depends**: Task 1 | **Effort**: 3-5h
### Description
Database tables/resources, data access layer
### Acceptance Criteria
- [ ] Database with schema
- [ ] Indexes for access patterns
- [ ] CRUD operations
- [ ] Connection pooling
- [ ] Error handling
- [ ] Unit tests (>80%)
### Files
- `infrastructure/lib/database-stack.ts`
- `src/data/[entity]-repository.ts`