kiro-kit 0.1.0

package/dist/presets/frontend/skills/web-frameworks/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: web-frameworks
+description: Build modern full-stack web applications with Next.js App Router, Server Components, and React patterns. Use when working with Next.js routing, rendering, or data fetching.
+---
+
+# Web Frameworks
+
+Activate this skill when working with Next.js App Router, routing, rendering strategies, or full-stack React patterns.
+
+## When to Use
+
+- Setting up Next.js App Router routes and layouts
+- Implementing Server Components and Server Actions
+- Configuring rendering strategies (SSR, SSG, ISR, PPR)
+- Working with middleware and route handlers
+- Implementing authentication flows
+- Optimizing with streaming and Suspense
+
+## Next.js App Router
+
+- File-based routing in `app/` directory
+- `page.tsx` defines route segments
+- `layout.tsx` wraps child routes (persists across navigation)
+- `loading.tsx` provides Suspense fallback
+- `error.tsx` handles errors at segment level
+- `not-found.tsx` for 404 handling
+- Route groups `(name)` for organization without URL impact
+
+## Server Components (default)
+
+- No `use client` directive needed
+- Can fetch data directly (async components)
+- Cannot use hooks, event handlers, or browser APIs
+- Reduce client bundle size significantly
+- Use for data display, layouts, and static content
+
+## Client Components
+
+- Add `use client` at top of file
+- Required for: hooks, event handlers, browser APIs, state
+- Keep as small as possible (leaf components)
+- Pass Server Component children as props when possible
+
+## Server Actions
+
+- Define with `use server` directive
+- Use for form submissions and mutations
+- Integrate with `useActionState` for pending/error states
+- Revalidate cache with `revalidatePath` or `revalidateTag`
+
+## Rendering Strategies
+
+- Static (default): pre-rendered at build time
+- Dynamic: rendered per-request (use `cookies()`, `headers()`, or `searchParams`)
+- ISR: static with timed revalidation (`revalidate` option)
+- Streaming: progressive rendering with Suspense boundaries

package/dist/presets/frontend/specs/_templates/frontend/design.md

@@ -0,0 +1,66 @@
+# Design: [Feature Name]
+
+## Architecture
+
+### Component Hierarchy
+
+```
+[ParentComponent]
+  [ChildComponent]
+    [GrandchildComponent]
+```
+
+### Data Flow
+
+Describe how data flows through the component tree:
+- Props passed down
+- State lifted up
+- Context providers
+- Server vs client boundaries
+
+## Component Design
+
+### [ComponentName]
+
+**Type**: Server Component / Client Component
+**Props**:
+```typescript
+interface ComponentNameProps {
+  // Define props
+}
+```
+
+**State**: Describe internal state if Client Component
+**Side Effects**: Describe effects and cleanup
+
+## Rendering Strategy
+
+- [ ] Static (build-time)
+- [ ] Dynamic (per-request)
+- [ ] ISR (revalidate interval: ___s)
+- [ ] Streaming (with Suspense boundaries)
+
+## API Integration
+
+### Endpoints Used
+- `GET /api/[resource]` - [description]
+- `POST /api/[resource]` - [description]
+
+### Caching Strategy
+- Cache duration: ___
+- Revalidation trigger: ___
+- Optimistic updates: yes/no
+
+## Testing Strategy
+
+- Unit tests: component rendering, hook behavior
+- Integration tests: user interactions, data flow
+- E2E tests: critical user paths
+- Visual regression: screenshot comparison
+
+## Performance Considerations
+
+- Code splitting boundaries
+- Image optimization approach
+- Font loading strategy
+- Third-party script handling

package/dist/presets/frontend/specs/_templates/frontend/requirements.md

@@ -0,0 +1,41 @@
+# Requirements: [Feature Name]
+
+## Overview
+
+Brief description of the feature and its purpose.
+
+## User Stories
+
+- As a [user type], I want to [action] so that [benefit]
+
+## Functional Requirements
+
+### UI/UX
+- [ ] Component renders correctly across breakpoints (mobile, tablet, desktop)
+- [ ] Loading states display skeleton UI during data fetch
+- [ ] Error states show actionable error messages with retry option
+- [ ] Empty states provide guidance on next steps
+
+### Behavior
+- [ ] [Describe interactive behavior]
+- [ ] [Describe data flow]
+- [ ] [Describe state management needs]
+
+### Accessibility
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Screen reader announces dynamic content changes
+- [ ] Color contrast meets WCAG 2.1 AA standards
+- [ ] Focus management is correct for modals/dialogs
+
+## Non-Functional Requirements
+
+- [ ] First Contentful Paint under 1.5s
+- [ ] No layout shift (CLS < 0.1)
+- [ ] Bundle size increase under 50KB (gzipped)
+- [ ] Works without JavaScript for critical content (progressive enhancement)
+
+## Acceptance Criteria
+
+1. [Specific, testable criterion]
+2. [Specific, testable criterion]
+3. [Specific, testable criterion]

package/dist/presets/frontend/specs/_templates/frontend/tasks.md

@@ -0,0 +1,44 @@
+# Tasks: [Feature Name]
+
+## Phase 1: Setup and Structure
+
+- [ ] 1.1 Create component directory structure
+- [ ] 1.2 Define TypeScript interfaces and types
+- [ ] 1.3 Set up route files (page, layout, loading, error)
+
+## Phase 2: Core Implementation
+
+- [ ] 2.1 Implement Server Component data fetching
+- [ ] 2.2 Build UI components with Tailwind CSS
+- [ ] 2.3 Add Client Component interactivity
+- [ ] 2.4 Implement form handling and validation
+- [ ] 2.5 Connect to API endpoints
+
+## Phase 3: States and Error Handling
+
+- [ ] 3.1 Implement loading skeleton UI
+- [ ] 3.2 Add error boundary with retry
+- [ ] 3.3 Handle empty states
+- [ ] 3.4 Add optimistic updates for mutations
+
+## Phase 4: Accessibility and Polish
+
+- [ ] 4.1 Add ARIA attributes and roles
+- [ ] 4.2 Implement keyboard navigation
+- [ ] 4.3 Add focus management for dynamic content
+- [ ] 4.4 Verify color contrast compliance
+- [ ] 4.5 Add micro-interactions and transitions
+
+## Phase 5: Testing
+
+- [ ] 5.1 Write unit tests for components
+- [ ] 5.2 Write integration tests for user flows
+- [ ] 5.3 Add E2E tests for critical paths
+- [ ] 5.4 Verify responsive behavior across breakpoints
+
+## Phase 6: Performance
+
+- [ ] 6.1 Implement code splitting
+- [ ] 6.2 Optimize images and assets
+- [ ] 6.3 Verify Core Web Vitals metrics
+- [ ] 6.4 Run Lighthouse audit and fix issues

package/dist/presets/frontend/statusline.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Statusline: outputs git branch + project name + time on one line.
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+let branch = '';
+try {
+  branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+} catch (e) {
+  // Not a git repo
+}
+
+const projectName = path.basename(process.cwd());
+const time = new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+
+const parts = [];
+if (branch) parts.push(branch);
+parts.push(projectName);
+parts.push(time);
+
+process.stdout.write(parts.join(' | ') + '\n');

package/dist/presets/frontend/statusline.ps1

@@ -0,0 +1,16 @@
+# Statusline: outputs git branch + project name + time on one line.
+# Gracefully omits git branch if not a git repository.
+
+$Branch = ''
+try {
+    $Branch = (git rev-parse --abbrev-ref HEAD 2>$null)
+} catch {}
+
+$Project = Split-Path -Leaf (Get-Location)
+$Time = Get-Date -Format 'HH:mm'
+
+if ($Branch) {
+    Write-Output "$Branch | $Project | $Time"
+} else {
+    Write-Output "$Project | $Time"
+}

package/dist/presets/frontend/statusline.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Statusline: outputs git branch + project name + time on one line.
+# Gracefully omits git branch if not a git repository.
+
+BRANCH=""
+if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+  BRANCH=$(git rev-parse --abbrev-ref HEAD)
+fi
+
+PROJECT=$(basename "$PWD")
+TIME=$(date +"%H:%M")
+
+if [ -n "$BRANCH" ]; then
+  echo "$BRANCH | $PROJECT | $TIME"
+else
+  echo "$PROJECT | $TIME"
+fi

package/dist/presets/frontend/steering/nextjs-patterns.md

@@ -0,0 +1,77 @@
+---
+inclusion: always
+description: Next.js App Router patterns including routing, data fetching, caching, and deployment conventions.
+---
+
+# Next.js Patterns
+
+## App Router Structure
+
+```
+app/
+  layout.tsx           Root layout (html, body, providers)
+  page.tsx             Home page
+  loading.tsx          Root loading state
+  error.tsx            Root error boundary
+  not-found.tsx        404 page
+  (auth)/              Route group for auth pages
+    login/page.tsx
+    register/page.tsx
+  dashboard/
+    layout.tsx         Dashboard layout (sidebar, nav)
+    page.tsx           Dashboard home
+    settings/page.tsx  Nested route
+  api/                 Route handlers
+    [resource]/route.ts
+```
+
+## Data Fetching
+
+- Server Components: fetch directly with caching options
+- Use `cache: 'force-cache'` for static data (default)
+- Use `cache: 'no-store'` for dynamic data
+- Use `next: { revalidate: 60 }` for ISR
+- Parallel fetching: use `Promise.all` for independent requests
+- Sequential fetching: only when data depends on previous result
+
+## Route Handlers (API Routes)
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const data = await fetchData();
+  return NextResponse.json(data);
+}
+```
+
+## Metadata and SEO
+
+- Use `generateMetadata` for dynamic metadata
+- Export static `metadata` object for fixed pages
+- Include Open Graph and Twitter card metadata
+- Use `robots.ts` and `sitemap.ts` for SEO
+
+## Performance Patterns
+
+- Use `next/image` for all images (automatic optimization)
+- Use `next/font` for font loading (no layout shift)
+- Dynamic imports for heavy components: `dynamic(() => import(...))`
+- Use `loading.tsx` for instant loading states
+- Implement streaming with nested Suspense boundaries
+
+## Environment Variables
+
+- `NEXT_PUBLIC_*` for client-side variables
+- Server-only variables: no prefix (never exposed to client)
+- Use `.env.local` for local development
+- Validate env vars at build time with `@t3-oss/env-nextjs`
+
+## Error Handling
+
+- `error.tsx` at each route segment for granular error boundaries
+- `error.tsx` must be a Client Component (`'use client'`)
+- Include reset button to retry the failed operation
+- Log errors to monitoring service in production
+- Use `notFound()` function for 404 responses

package/dist/presets/frontend/steering/react-conventions.md

@@ -0,0 +1,59 @@
+---
+inclusion: always
+description: React and TypeScript conventions for component development, hook patterns, and state management.
+---
+
+# React/TypeScript Conventions
+
+## Component Structure
+
+- Use functional components exclusively (no class components)
+- Export component as default, types as named exports
+- Props interface named `[Component]Props`
+- Colocate tests with components (`Component.test.tsx`)
+
+## File Organization
+
+```
+src/
+  app/                 Next.js App Router pages
+  components/
+    ui/                shadcn/ui primitives
+    [feature]/         Feature-specific components
+  hooks/               Custom hooks (useX naming)
+  lib/                 Utilities and helpers
+  types/               Shared TypeScript types
+```
+
+## TypeScript Rules
+
+- Strict mode enabled, no `any` types
+- Use `interface` for component props, `type` for unions/intersections
+- Prefer `unknown` over `any` for untyped data
+- Use discriminated unions for complex state
+- Generic components for reusable patterns
+
+## Component Patterns
+
+- Server Components by default (no directive needed)
+- Add `'use client'` only when using hooks, events, or browser APIs
+- Keep Client Components as leaf nodes
+- Pass Server Component children to Client wrappers
+- Use Suspense boundaries for async data
+
+## State Management
+
+- Local state: `useState` for simple, `useReducer` for complex
+- Server state: TanStack Query or SWR
+- Global state: Zustand (small stores, no single god store)
+- URL state: `useSearchParams` for shareable state
+- Form state: React Hook Form + Zod validation
+
+## Naming Conventions
+
+- Components: PascalCase (`UserProfile.tsx`)
+- Hooks: camelCase with `use` prefix (`useAuth.ts`)
+- Utilities: camelCase (`formatDate.ts`)
+- Types: PascalCase (`UserProfile`, `ApiResponse`)
+- Constants: UPPER_SNAKE_CASE (`MAX_RETRIES`)
+- Files: kebab-case for non-component files (`api-client.ts`)

package/dist/presets/frontend/workflows/development-rules.md

@@ -0,0 +1,34 @@
+# Development Rules
+
+Follow these principles: YAGNI (You Aren't Gonna Need It), KISS (Keep It Simple, Stupid), DRY (Don't Repeat Yourself).
+
+## General
+
+- Use kebab-case for file names with meaningful descriptive names
+- Keep individual code files under 200 lines
+- Split large files into smaller, focused components/modules
+- Use composition over inheritance for complex components
+- Extract utility functions into separate modules
+- Create dedicated service classes for business logic
+
+## Code Quality
+
+- Prioritize functionality and readability over strict style enforcement
+- Use try-catch error handling and cover security standards
+- No syntax errors -- code must be compilable at all times
+- Follow the codebase structure and code standards in `docs/`
+
+## Pre-commit Rules
+
+- Run linting before commit
+- Run tests before push
+- Keep commits focused on actual code changes
+- Do NOT commit confidential information (dotenv files, API keys, credentials)
+- Use conventional commit format
+
+## Implementation
+
+- Write clean, readable, maintainable code
+- Follow established architectural patterns
+- Handle edge cases and error scenarios
+- Do NOT create new enhanced files -- update existing files directly

package/dist/presets/frontend/workflows/documentation-management.md

@@ -0,0 +1,24 @@
+# Documentation Management
+
+## Automatic Updates Required
+
+- After feature implementation: update roadmap progress and changelog
+- After major milestones: review and adjust roadmap phases
+- After bug fixes: document fixes in changelog with severity and impact
+- After security updates: record security improvements and version updates
+
+## Documentation Triggers
+
+Update documentation when:
+- A development phase status changes
+- Major features are implemented or released
+- Significant bugs are resolved or security patches applied
+- Project timeline or scope adjustments are made
+- External dependencies or breaking changes occur
+
+## Update Protocol
+
+1. Before updates: read current roadmap and changelog status
+2. During updates: maintain version consistency and proper formatting
+3. After updates: verify links, dates, and cross-references
+4. Quality check: ensure updates align with actual implementation progress

package/dist/presets/frontend/workflows/orchestration-protocol.md

@@ -0,0 +1,18 @@
+# Orchestration Protocol
+
+## Sequential Chaining
+
+Chain agents when tasks have dependencies:
+- Planning then Implementation then Testing then Review: for feature development
+- Research then Design then Code then Documentation: for new components
+- Each agent completes fully before the next begins
+- Pass context and outputs between agents in the chain
+
+## Parallel Execution
+
+Spawn multiple agents simultaneously for independent tasks:
+- Code + Tests + Docs: when implementing separate, non-conflicting components
+- Multiple Feature Branches: different agents working on isolated features
+- Component + Styles + Tests: parallel work on different aspects of same feature
+- Ensure no file conflicts or shared resource contention
+- Plan integration points before parallel execution begins

package/dist/presets/frontend/workflows/primary-workflow.md

@@ -0,0 +1,33 @@
+# Primary Workflow
+
+Follow this cycle for all implementation work: Plan, Implement, Test, Review.
+
+## 1. Planning
+
+- Analyze requirements and break into concrete tasks
+- Research relevant technical topics before implementation
+- Create implementation plan with TODO items
+
+## 2. Implementation
+
+- Write clean, readable, maintainable code
+- Follow established architectural patterns
+- Implement features according to specifications
+- Handle edge cases and error scenarios
+- After modifying code, run compile/build to check for errors
+
+## 3. Testing
+
+- Write comprehensive unit tests for new functionality
+- Ensure high code coverage on critical paths
+- Test error scenarios and edge cases
+- Validate performance requirements
+- Do not use mocks or fake data just to pass tests
+
+## 4. Review
+
+- Review code for standards compliance
+- Check for security concerns
+- Verify documentation is updated
+- Ensure backward compatibility
+- Confirm no regressions introduced

package/dist/presets/fullstack/.env.example

@@ -0,0 +1,37 @@
+# Project-level environment variables
+# Copy this file to .env and fill in your values.
+
+# Workspace root path (auto-detected by CLI)
+# WORKSPACE_ROOT=/path/to/project
+
+# API keys for external services
+# OPENAI_API_KEY=<your-openai-api-key>
+# ANTHROPIC_API_KEY=<your-anthropic-api-key>
+
+# Next.js / T3 Stack
+# NEXT_PUBLIC_API_URL=http://localhost:3000/api
+# NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# Database
+# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# Authentication
+# NEXTAUTH_SECRET=<your-nextauth-secret>
+# NEXTAUTH_URL=http://localhost:3000
+
+# OAuth Providers
+# GOOGLE_CLIENT_ID=<your-google-client-id>
+# GOOGLE_CLIENT_SECRET=<your-google-client-secret>
+# GITHUB_CLIENT_ID=<your-github-client-id>
+# GITHUB_CLIENT_SECRET=<your-github-client-secret>
+
+# Payment (Stripe / Polar / SePay)
+# STRIPE_SECRET_KEY=<your-stripe-secret-key>
+# STRIPE_WEBHOOK_SECRET=<your-stripe-webhook-secret>
+# POLAR_ACCESS_TOKEN=<your-polar-access-token>
+
+# Redis (optional)
+# REDIS_URL=redis://localhost:6379
+
+# Application environment
+# NODE_ENV=development

package/dist/presets/fullstack/.mcp.json.example

@@ -0,0 +1,37 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORKSPACE_ROOT}"]
+    },
+    "git": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "${WORKSPACE_ROOT}"]
+    },
+    "docs-seeker": {
+      "command": "npx",
+      "args": ["-y", "@mcp/docs-seeker"],
+      "env": {
+        "DOCS_PATH": "${WORKSPACE_ROOT}/docs"
+      }
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp-server"],
+      "env": {
+        "BROWSER": "chromium"
+      }
+    },
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}

package/dist/presets/fullstack/README.md

@@ -0,0 +1,40 @@
+# Fullstack Preset
+
+Comprehensive kit for Next.js/T3 stack development combining frontend and backend capabilities with payment integration and e-commerce support.
+
+## Target Stack
+
+- Next.js App Router (React Server Components, Server Actions)
+- TypeScript strict mode
+- tRPC or REST API routes
+- Prisma/Drizzle ORM with PostgreSQL
+- Authentication (NextAuth.js / Better Auth)
+- Tailwind CSS + shadcn/ui
+- Stripe / Polar / SePay payment integration
+- Shopify integration (optional)
+
+## Included Artifacts
+
+- 20 agents (fullstack-developer, api-developer, database-architect, performance-optimizer, + 16 baseline)
+- 22 skills (frontend + backend + shopify + payment-integration)
+- 29 commands (baseline + fullstack category)
+- 8 hooks (cross-platform with .js/.sh/.ps1 variants)
+- 4 workflows (always-on development guides)
+- 2 steering files (fullstack conventions, Next.js App Router)
+- Spec templates for fullstack features
+- Docs templates (code standards, architecture, roadmap)
+- MCP server configurations (filesystem, git, playwright, fetch, docs-seeker, postgres)
+
+## Usage
+
+```bash
+npx kiro-kit init --preset fullstack
+```
+
+## Recommended For
+
+- SaaS applications with Next.js
+- E-commerce platforms (Shopify storefront + custom backend)
+- Full-stack TypeScript monorepos
+- T3 stack projects (Next.js + tRPC + Prisma + Tailwind)
+- Applications requiring payment processing

package/dist/presets/fullstack/agents/api-developer.md

@@ -0,0 +1,45 @@
+---
+name: api-developer
+description: Use when implementing API endpoints, route handlers, tRPC procedures, Server Actions, middleware, or integrating with external services in a Next.js backend.
+---
+
+You are a senior backend developer specializing in API design and implementation within Next.js applications. You build production-grade APIs that are secure, performant, and type-safe.
+
+## Responsibilities
+
+- Implement Next.js Route Handlers (REST API endpoints)
+- Design tRPC routers and procedures with input/output validation
+- Build Server Actions for form mutations
+- Create middleware for auth, logging, rate limiting, and error handling
+- Integrate with databases, caches, and external services
+- Write API documentation (OpenAPI/Swagger or tRPC panel)
+
+## Process
+
+1. Review API design conventions and existing route patterns
+2. Define request/response schemas with Zod validation
+3. Implement route handler or tRPC procedure with error handling
+4. Add middleware (auth, validation, rate limiting) as needed
+5. Write integration tests for the endpoint
+6. Update API documentation
+7. Run build and tests to verify no regressions
+
+## Coding Standards
+
+- Use layered architecture: handler -> service -> repository
+- Validate all input at the handler layer (Zod schemas)
+- Return consistent error response format across all endpoints
+- Use parameterized queries for all database operations
+- Implement proper HTTP status codes (not just 200 and 500)
+- Add request logging with correlation IDs
+- Handle async errors with proper try-catch
+- Keep route handlers thin -- delegate logic to service layer
+
+## Quality Standards
+
+- All endpoints must have input validation
+- Error responses must be structured and actionable
+- Authentication/authorization checked on every protected route
+- Database queries must use parameterized statements
+- Response times under 200ms for simple CRUD operations
+- Tests cover happy path, validation errors, and auth failures