// .kiro/steering/architecture.md
# Service Architecture Guidelines
- All API endpoints must implement request validation using Zod schemas
- Database queries require explicit transaction boundaries
- Error responses follow RFC 7807 Problem Details format
- Logging must include correlation_id and request_id headers
- AWS SDK v3 is mandatory; v2 is deprecated for new services

# .kiro/specs/user-preferences/requirements.md
## User Stories
- As a registered user, I want to customize notification channels so I can control communication frequency
- As an admin, I want to enforce default notification policies so compliance requirements are met

## Acceptance Criteria
- [ ] Email, SMS, and push channels are independently toggleable
- [ ] Changes persist across sessions and devices
- [ ] Admin overrides require audit trail logging
- [ ] Rate limiting prevents notification spam (>10/hour)

# .kiro/specs/user-preferences/design.md
## Component Breakdown
- `PreferenceService`: Handles CRUD operations and validation
- `NotificationRouter`: Dispatches events based on channel configuration
- `AuditLogger`: Records policy changes and admin overrides

## Data Flow
1. Client submits PATCH request to `/api/v1/preferences`
2. PreferenceService validates against Zod schema
3. NotificationRouter evaluates channel rules
4. Changes persisted to DynamoDB with conditional writes
5. AuditLogger writes immutable record to CloudWatch Logs

# .kiro/specs/user-preferences/tasks.md
## Implementation Checklist
1. [ ] Create Zod validation schemas for preference payloads
2. [ ] Implement PreferenceService with 

DynamoDB integration 3. [ ] Build NotificationRouter with channel filtering logic 4. [ ] Add audit logging middleware for policy changes 5. [ ] Write integration tests for concurrent preference updates 6. [ ] Configure rate limiting at API Gateway level

The specification becomes the single source of truth. Code is generated to satisfy these constraints, not the other way around. This reverses the traditional documentation debt cycle.

### Step 3: Configure Event-Driven Hooks

Hooks transform passive specifications into active quality gates. They trigger on workspace events and execute automated workflows without developer intervention.

```typescript
// .kiro/hooks/quality-gates.ts
export const workspaceHooks = {
  onFileSave: [
    {
      trigger: 'src/**/*.ts',
      action: 'runLinter',
      config: { fixOnSave: true, strictMode: true }
    },
    {
      trigger: 'src/services/**/*.ts',
      action: 'regenerateTests',
      config: { coverageThreshold: 0.85, framework: 'vitest' }
    }
  ],
  onCommit: [
    {
      trigger: '*',
      action: 'securityScan',
      config: { tool: 'trivy', failOnCritical: true }
    },
    {
      trigger: 'src/**',
      action: 'syncSpecDesign',
      config: { diffThreshold: 0.15, autoUpdate: true }
    }
  ],
  onPRCreate: [
    {
      trigger: '*',
      action: 'generateDescription',
      config: { source: 'requirements.md', template: 'standard' }
    }
  ]
};

Step 4: Execute and Verify

The autonomous agent processes the task list sequentially, referencing steering files for conventions and specifications for requirements. Hooks run continuously in the background. When implementation completes, the system auto-generates commit messages from spec diffs and populates PR descriptions from acceptance criteria. The loop closes without manual documentation updates.

Architecture Rationale:

• Separation of Concerns: Specs define intent, hooks enforce quality, steering files maintain context. This prevents coupling between generation logic and governance rules.
• Deterministic Output: By treating code as a build artifact of specifications, you eliminate ambiguity. Two developers implementing the same spec will produce structurally consistent results.
• Background Automation: Hooks remove friction from quality enforcement. Junior developers receive the same automated guardrails as senior engineers, standardizing output without micromanagement.

Pitfall Guide

1. Treating Specifications as Static Documentation

Explanation: Teams generate specs once and ignore them during implementation. This recreates the exact documentation debt problem spec-first workflows aim to solve. Fix: Configure hooks to sync spec changes with code modifications. Treat design.md as a living contract that updates when architectural decisions shift.

2. Overloading Hooks with Synchronous Tasks

Explanation: Running heavy operations (full test suites, security scans) synchronously on every file save blocks the developer workflow and causes context switching fatigue. Fix: Use asynchronous execution for non-critical checks. Reserve synchronous hooks for fast linters and type checks. Queue heavier operations for pre-commit or pre-merge gates.

3. Ignoring Steering File Hierarchy

Explanation: Placing project-specific rules in global steering files causes cross-project contamination. Conversely, duplicating global standards in every repository creates maintenance overhead. Fix: Enforce a strict hierarchy. Global files handle language versions, security baselines, and logging standards. Project files handle domain-specific patterns, API contracts, and service boundaries.

4. Assuming Cloud-Agnostic Parity

Explanation: Kiro's native integrations with CodeCatalyst, Bedrock, and IAM Identity Center provide significant advantages for AWS-first teams. Attempting to replicate this depth in multi-cloud environments requires custom MCP server development. Fix: Use Kiro for AWS-native services and maintain your existing editor for non-AWS components. Leverage the tool's strengths rather than forcing uniformity across heterogeneous infrastructure.

5. Neglecting Task Granularity in Implementation Plans

Explanation: Vague task descriptions lead to inconsistent agent output. Tasks like "implement authentication" produce unpredictable results compared to "create JWT validation middleware with refresh token rotation." Fix: Decompose tasks into atomic, verifiable units. Each task should map to a single function, module, or configuration change with clear success criteria.

6. Bypassing the Specification Review Gate

Explanation: Skipping the human review of generated specs assumes the agent understands business constraints and edge cases. This is a dangerous assumption for production systems. Fix: Mandate a review step before implementation begins. Add edge cases, adjust data flow diagrams, and validate acceptance criteria against product requirements. The agent executes; humans validate intent.

7. Mixing Model Routing Without Cost Controls

Explanation: Routing all operations through Claude Sonnet for reasoning increases latency and cost. Conversely, using Amazon Nova exclusively for complex architectural decisions reduces output quality. Fix: Configure explicit routing rules. Use Sonnet for spec generation, design validation, and complex refactors. Route Nova for boilerplate generation, test scaffolding, and high-volume code synthesis. Monitor Bedrock usage metrics to optimize token allocation.

Production Bundle

Action Checklist

• Initialize steering files: Create global and project-specific context documents before starting any feature
• Define hook triggers: Map workspace events to automated quality gates (lint, test, security, spec sync)
• Establish spec review protocol: Require human validation of requirements and design before implementation begins
• Configure model routing: Assign reasoning tasks to Claude Sonnet and generation tasks to Amazon Nova via Bedrock
• Set task granularity standards: Decompose implementation plans into atomic, verifiable units
• Enable autonomous PR generation: Configure hooks to auto-populate commit messages and PR descriptions from spec diffs
• Audit steering file hierarchy: Verify global rules don't leak into project contexts and vice versa
• Monitor hook performance: Track execution times and adjust synchronous vs asynchronous thresholds

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Multi-developer production feature	Spec-first with hooks	Enforces consistency, maintains living documentation, reduces review overhead	Medium (initial setup), Low (long-term maintenance)
Solo prototyping / exploration	Chat-driven or CLI agent	Spec overhead slows iteration; rapid feedback loop prioritized	Low (token usage only)
AWS-native service development	Kiro with native integrations	Direct Bedrock routing, CodeCatalyst CI/CD, IAM auth, domain-specific MCP servers	Medium (AWS service costs), High (productivity gain)
Multi-cloud / hybrid infrastructure	Kiro for AWS components + existing editor for others	Leverages native integrations where available, avoids forced uniformity	Low (tool fragmentation), Medium (context switching)
Compliance-heavy domain (healthcare, finance)	Spec-first with security hooks	Automated guardrails, audit trail generation, consistent policy enforcement	High (initial configuration), Low (compliance risk reduction)

Configuration Template

# .kiro/config/project.yaml
workspace:
  spec_directory: ".kiro/specs"
  steering_paths:
    global: "~/.kiro/steering"
    project: ".kiro/steering"
  
model_routing:
  reasoning:
    provider: "bedrock"
    model: "anthropic.claude-sonnet-4-20250514-v1:0"
    use_cases: ["spec_generation", "design_validation", "complex_refactor"]
  generation:
    provider: "bedrock"
    model: "amazon.nova-pro-v1:0"
    use_cases: ["boilerplate", "test_scaffolding", "high_volume_synthesis"]

hooks:
  on_save:
    - pattern: "src/**/*.ts"
      action: "lint_and_fix"
      timeout_ms: 2000
    - pattern: "src/services/**/*.ts"
      action: "regenerate_unit_tests"
      timeout_ms: 5000
  on_commit:
    - pattern: "*"
      action: "security_scan"
      fail_on: "critical"
    - pattern: "src/**"
      action: "sync_spec_design"
      diff_threshold: 0.15
  on_pr:
    - pattern: "*"
      action: "generate_description"
      source: "requirements.md"

quality_gates:
  test_coverage: 0.85
  lint_strict_mode: true
  security_scan_tool: "trivy"
  spec_sync_frequency: "on_change"

Quick Start Guide

1. Initialize the workspace: Download the IDE from the official distribution channel. Sign in using GitHub or Google credentials. Point the workspace to an existing repository and import your VS Code settings during onboarding.
2. Create baseline steering files: Add language standards, framework preferences, and security requirements to ~/.kiro/steering/. Create project-specific overrides in .kiro/steering/ for domain conventions.
3. Generate your first specification: Describe a planned feature. Review the generated requirements.md, design.md, and tasks.md. Add edge cases, adjust data flow, and validate acceptance criteria against product goals.
4. Configure essential hooks: Set up a linter hook for file saves and a test regeneration hook for service files. Verify execution times and adjust synchronous thresholds to maintain workflow fluidity.
5. Execute and iterate: Allow the agent to process the task list. Monitor hook outputs for quality enforcement. Review the auto-generated PR description and commit message. Refine steering files and hook configurations based on initial results.

The transition from prompt-driven to spec-driven development requires upfront discipline but yields compounding returns in team alignment, documentation accuracy, and production stability. When specifications become the unit of work, AI agents shift from code generators to engineering orchestrators.