@zweer/dev 1.2.0 → 2.0.0

package/README.md

@@ -1,508 +1,109 @@
-# @zweer/dev - Shared Configurations & AI Agents
+# @zweer/dev
 
-Central repository of reusable configurations and specialized AI agents for software projects.
+Shared configurations, golden configs & Kiro AI templates for software projects.
 
-## Table of Contents
+## What's Inside
 
-- [Project Purpose](#project-purpose)
-- [Structure](#structure)
-- [How It Works](#how-it-works)
-  - [1. Orchestrator Agent (in your project)](#1-orchestrator-agent-in-your-project)
-  - [2. Specialized Agents (in this repo)](#2-specialized-agents-in-this-repo)
-  - [3. Agent Handoff](#3-agent-handoff)
-- [Available Agents](#available-agents)
-  - [Web Development](#web-development-agentsdev)
-- [How to Use Agents](#how-to-use-agents)
-  - [Setup in Your Project](#setup-in-your-project)
-  - [Delegation Example in Orchestrator](#delegation-example-in-orchestrator)
-  - [Providing Context to Agents](#providing-context-to-agents)
-- [Benefits of This Approach](#benefits-of-this-approach)
-- [Contributing](#contributing)
-- [Roadmap](#roadmap)
-- [License](#license)
+| Directory | Purpose |
+|-----------|---------|
+| `cli/` | CLI tool (`dev bootstrap`, `dev setup`, `dev init-kiro`) |
+| `configs/` | Golden config files copied to target projects |
+| `kiro/` | Kiro agent, prompt, steering & skill templates |
+| `workflows/` | GitHub Actions workflow templates |
 
-## Project Purpose
+## Quick Start
 
-This repository contains:
-
-1. **Specialized AI agents** - Agent configurations for different domains (web development, writing, etc.)
-2. **Common configurations** - Shared setups for linting, formatting, TypeScript, etc.
-3. **Templates** - Reusable project structures
-
-The idea is to have an **orchestrator + specialized agents pattern**:
-- Each project has an **orchestrator agent** with project-specific context
-- The orchestrator delegates tasks to **specialized agents** via handoff
-- Specialized agents are generic and reusable across projects
-
-## Structure
-
-```
-dev/
-├── agents/                              # Specialized AI agents (30 total)
-│   ├── data/                           # Data engineering (1)
-│   │   └── zweer_data_engineer.md
-│   ├── design/                         # UI/UX (2)
-│   │   ├── zweer_ui_designer.md
-│   │   └── zweer_ui_ux.md
-│   ├── infrastructure/                 # Platform & IaC (4)
-│   │   ├── zweer_infra_cdk.md
-│   │   ├── zweer_infra_devops.md
-│   │   ├── zweer_infra_observability.md
-│   │   └── zweer_infra_terraform.md
-│   ├── mobile/                         # Mobile development (5)
-│   │   ├── zweer_mobile_android.md
-│   │   ├── zweer_mobile_flutter.md
-│   │   ├── zweer_mobile_ionic.md
-│   │   ├── zweer_mobile_ios.md
-│   │   └── zweer_mobile_react_native.md
-│   ├── quality/                        # Quality & best practices (4)
-│   │   ├── zweer_qa_documentation.md
-│   │   ├── zweer_qa_performance.md
-│   │   ├── zweer_qa_security.md
-│   │   └── zweer_qa_testing.md
-│   ├── services/                       # Backend services (5)
-│   │   ├── zweer_svc_api_gateway.md
-│   │   ├── zweer_svc_containers.md
-│   │   ├── zweer_svc_lambda.md
-│   │   ├── zweer_svc_messaging.md
-│   │   └── zweer_svc_microservices.md
-│   ├── web/                            # Web full-stack (5)
-│   │   ├── zweer_web_api_integration.md
-│   │   ├── zweer_web_backend.md
-│   │   ├── zweer_web_database.md
-│   │   ├── zweer_web_frontend.md
-│   │   └── zweer_web_reader.md
-│   └── write/                          # Content & creative writing (4)
-│       ├── zweer_write_content.md
-│       ├── zweer_write_narrative.md
-│       ├── zweer_write_style.md
-│       └── zweer_write_warmth.md
-├── cli/                                # CLI tool implementation
-├── templates/                          # Project templates
-└── README.md                          # This file
-```
-
-All agents follow the naming convention: `zweer_<category>_<name>` for global uniqueness.
-
-## How It Works
-
-### 1. Orchestrator Agent (in your project)
-
-The orchestrator is project-specific and contains:
-- **Project context**: name, purpose, tech stack, architecture
-- **Documentation**: references to README, ARCHITECTURE, DATABASE_SCHEMA, etc.
-- **Delegation logic**: which agent to call for which task
-- **Project standards**: code conventions, design system, best practices
-
-Example orchestrator structure:
-
-```yaml
----
-name: my_project_orchestrator
-description: Project orchestrator for My Project
-model: claude-sonnet-4.5
-mcpServers:
-  cao-mcp-server:
-    type: stdio
-    command: uvx
-    args:
-      - "--from"
-      - "git+https://github.com/awslabs/cli-agent-orchestrator.git@main"
-      - "cao-mcp-server"
-tools: ["*"]
-allowedTools: ["fs_read", "fs_write", "execute_bash", "@cao-mcp-server"]
----
-
-# My Project - Orchestrator
-
-## Project Context
-- Name: My Project
-- Tech Stack: Next.js, TypeScript, PostgreSQL
-- [Project-specific details]
-
-## Instructions
-[Orchestration and delegation logic]
-```
-
-### 2. Specialized Agents (in this repo)
-
-Specialized agents are **generic** and **reusable**. They don't know about your specific project, but are experts in a domain.
-
-Each agent has:
-- **Specific expertise**: e.g. React, database design, security
-- **Best practices**: guidelines for the domain
-- **Examples**: common patterns and solutions
-
-### 3. Agent Handoff
-
-The orchestrator delegates tasks to agents via the `@cao-mcp-server` tool:
-
-```
-Orchestrator receives: "Create login page"
-  ↓
-Orchestrator analyzes and plans:
-  1. UX design → delegate to dev_ux
-  2. UI components → delegate to dev_frontend
-  3. Authentication → delegate to dev_backend
-  4. DB schema → delegate to dev_database
-  ↓
-Orchestrator coordinates execution and validates results
-```
-
-## Available Agents
-
-All agents use the `zweer_<category>_<name>` naming convention for global uniqueness.
-
-### Web Development (`agents/web/`)
-
-- **zweer_web_frontend** - React, Next.js, components, client-side logic
-- **zweer_web_backend** - API routes, Server Actions, business logic
-- **zweer_web_database** - Schema design, queries, migrations
-- **zweer_web_api_integration** - External API integrations, scrapers
-- **zweer_web_reader** - Image viewer, document reader, gestures
-
-### Services (`agents/services/`)
-
-- **zweer_svc_lambda** - AWS Lambda, serverless functions, event handlers
-- **zweer_svc_microservices** - Service design, communication patterns, distributed systems
-- **zweer_svc_api_gateway** - REST, GraphQL, API Gateway, rate limiting
-- **zweer_svc_messaging** - SQS, SNS, EventBridge, event-driven architecture
-- **zweer_svc_containers** - Docker, ECS, EKS, container orchestration
-
-### Infrastructure (`agents/infrastructure/`)
-
-- **zweer_infra_cdk** - AWS CDK with TypeScript, stacks, constructs
-- **zweer_infra_terraform** - Terraform HCL, modules, state management
-- **zweer_infra_devops** - Deploy, CI/CD, infrastructure
-- **zweer_infra_observability** - Monitoring, logging, tracing, alerting
-
-### Design (`agents/design/`)
-
-- **zweer_ui_designer** - UI components, design system, styling
-- **zweer_ui_ux** - User flows, accessibility, mobile experience
-
-### Mobile (`agents/mobile/`)
-
-- **zweer_mobile_react_native** - Cross-platform mobile with React Native
-- **zweer_mobile_ionic** - Hybrid mobile apps with Capacitor
-- **zweer_mobile_flutter** - Cross-platform mobile with Dart
-- **zweer_mobile_ios** - Native iOS with Swift, SwiftUI, UIKit
-- **zweer_mobile_android** - Native Android with Kotlin, Jetpack Compose
-
-### Quality (`agents/quality/`)
-
-- **zweer_qa_testing** - Unit, integration, E2E tests
-- **zweer_qa_security** - Auth, security, vulnerabilities
-- **zweer_qa_performance** - Optimization, caching, monitoring
-- **zweer_qa_documentation** - Technical writing, API docs
-
-### Data Engineering (`agents/data/`)
-
-- **zweer_data_engineer** - ETL pipelines, data warehousing, analytics
-
-### Writing (`agents/write/`)
-
-- **zweer_write_content** - Blog posts, articles, marketing copy
-- **zweer_write_narrative** - Creative fiction, storytelling, character development
-- **zweer_write_style** - Refine writing quality, remove AI patterns, improve flow
-- **zweer_write_warmth** - Add human warmth, empathy, and emotional connection
-
-## CLI Tool
-
-Command-line tool for managing AI agents, orchestrators, and project configurations.
-
-### Installation
-
-```bash
-npm install -g @zweer/dev
-```
-
-Or use with npx:
-
-```bash
-npx @zweer/dev <command>
-```
-
-### Commands
-
-#### Project Setup
-
-##### `dev bootstrap`
-
-Bootstrap a new npm package with standard configuration.
-
-```bash
-# Interactive mode
-dev bootstrap
-
-# Skip prompts (use defaults)
-dev bootstrap --yes
-```
-
-Creates a complete project structure with:
-- `package.json` with all dependencies and scripts
-- TypeScript configuration (`tsconfig.json`)
-- Biome linter/formatter (`biome.json`)
-- Vitest testing setup (`vitest.config.ts`)
-- Git hooks with Husky and lint-staged
-- EditorConfig (`.editorconfig`)
-- Sample source and test files
-- README template
-
-**Options:**
-- `-y, --yes` - Skip prompts and use defaults
-
-##### `dev setup`
-
-Add standard configuration to an existing project.
+### New project
 
 ```bash
-# Interactive mode - choose what to add
-dev setup
-
-# Add everything
-dev setup --yes
+npx @zweer/dev bootstrap my-project
+cd my-project
+npx @zweer/dev init-kiro
 ```
 
-Adds configurations to existing project:
-- Merges dependencies into existing `package.json` (doesn't overwrite)
-- Merges scripts into existing `package.json`
-- Creates missing config files (tsconfig, biome, vitest, etc.)
-- Skips files that already exist
-- Preserves existing values
-
-**Options:**
-- `-y, --yes` - Skip prompts and add all configurations
-
-#### AI Agents (CAO)
-
-All CAO-related commands are under the `cao` subcommand:
-
-##### `dev cao init [name]`
-
-Create an orchestrator in your current project.
+### Existing project
 
 ```bash
-# Interactive mode
-dev cao init
-
-# With custom name
-dev cao init my_orchestrator
-
-# Skip prompts (use defaults)
-dev cao init --yes
+npx @zweer/dev setup
+npx @zweer/dev init-kiro
 ```
 
-Creates `.cao/agents/<name>.md` with a template orchestrator configured for your project.
+## CLI Commands
 
-**Options:**
-- `-y, --yes` - Skip prompts and use defaults
+### `dev bootstrap [name]`
 
-##### `dev cao install`
+Scaffolds a new project with all golden configs, scripts, and dependencies.
 
-Install CAO (CLI Agent Orchestrator) and all common agents.
+### `dev setup`
 
-```bash
-# Install everything
-dev cao install
+Adds golden configs to an existing project. Merges deps and scripts into `package.json`, copies config files (won't overwrite existing), installs base GitHub Actions workflows.
 
-# Install only CAO
-dev cao install --cao-only
+### `dev init-kiro`
 
-# Install only agents
-dev cao install --agents-only
-```
+Installs the `zweer-setup` agent globally for Kiro-powered project configuration. After running, launch `kiro-cli chat` and use `/agent swap zweer-setup` to configure the project.
 
-This command:
-1. Installs tmux configuration
-2. Installs `uv` package manager
-3. Installs CAO via `uv tool install`
-4. Installs all 30+ common agents from this repository
+## Golden Configs
 
-**Options:**
-- `--cao-only` - Install only CAO prerequisites
-- `--agents-only` - Install only agents (skip CAO)
+All projects get these configs (via `dev bootstrap` or `dev setup`):
 
-##### `dev cao server`
+| Config | Tool |
+|--------|------|
+| `biome.json` | Biome (linter + formatter) |
+| `tsconfig.json` | TypeScript (`@tsconfig/node22`) |
+| `tsdown.config.ts` | tsdown (build) |
+| `vitest.config.ts` | Vitest (testing + v8 coverage) |
+| `lefthook.yml` | Lefthook (git hooks) |
+| `commitlint.config.ts` | Commitlint (conventional commits) |
+| `.editorconfig` | EditorConfig |
+| `.lockfile-lintrc.json` | Lockfile-lint (security) |
+| `.npmpackagejsonlintrc.json` | npm-package-json-lint |
 
-Launch the CAO server.
+## Project Templates
 
-```bash
-dev cao server
-```
+`dev bootstrap` uses these templates:
 
-Starts `cao-server` which enables agent communication and handoff.
+| Template | Use case | Example repos |
+|----------|----------|---------------|
+| `single` (default) | Single npm package | utils (if single-pkg) |
+| `monorepo` | npm workspaces with `packages/*` | bonvoy, FlowRAG, utils |
 
-##### `dev cao launch <agent>`
+For web apps (Next.js, SvelteKit, etc.), use the framework's own scaffolding tool first, then run `dev setup` to add golden configs.
 
-Launch a specific agent.
+## Kiro Templates
 
-```bash
-# Launch your orchestrator
-dev cao launch my_project_orchestrator
+The `zweer-setup` agent generates `.kiro/` config for any project:
 
-# Launch a specialized agent
-dev cao launch zweer_web_frontend
-```
+- **5 steering files**: code-style, build-tooling, testing, interaction, commit-conventions
+- **Agent config**: Tailored `dev.json` with project-specific write paths
+- **Prompt**: Project-specific system prompt
+- **Skills**: Monorepo scaffolding, etc.
 
-##### `dev cao list`
+## Workflow Templates
 
-List all available agents with descriptions.
+| Tier | Workflows | When |
+|------|-----------|------|
+| Base | ci, pr, security, dependabot-auto-merge | Always |
+| Library | npm release | npm packages |
+| Docs | VitePress deploy | Projects with docs/ |
 
-```bash
-dev cao list
-```
-
-Shows all 30+ agents organized by category.
+## Stack Decisions
 
-## How to Use Agents
+- **Biome** today, Oxc when stable
+- **Lefthook** (not husky + lint-staged)
+- **tsdown** (not tsc for build)
+- **bonvoy** (not semantic-release)
+- **@tsconfig/node22** (LTS)
+- **Copy** config distribution (not extends)
 
-### Setup in Your Project
+## Development
 
 ```bash
-# In your project directory
-cd my-project
-
-# Create orchestrator
-dev cao init
-
-# Install CAO and agents
-dev cao install
+npm install
+npm run build
+npm test
+npm run lint
 ```
 
-### Customize Orchestrator
-
-Edit `.cao/agents/my-project_orchestrator.md` to add:
-- Project-specific context
-- Tech stack details
-- Architecture notes
-- Custom agent selection logic
-
-### Launch and Work
-
-```bash
-# Start CAO server (in one terminal)
-dev cao server
-
-# Launch your orchestrator (in another terminal)
-dev cao launch my-project_orchestrator
-```
-
-### Use Agent Handoff
-
-In your orchestrator, delegate to specialized agents:
-
-```typescript
-handoff({
-  agent: "zweer_web_frontend",
-  context: {
-    task: "Create login page component",
-    requirements: {
-      framework: "Next.js 15",
-      styling: "Tailwind CSS",
-      validation: "Zod"
-    }
-  }
-})
-```
-
-### Delegation Example in Orchestrator
-
-```markdown
-### Agent Selection Guide
-
-**For UI/UX Tasks**:
-- `zweer_ui_ux` → User flows, accessibility, mobile experience
-- `zweer_ui_designer` → Components, styling, design system
-- `zweer_web_frontend` → React components, pages, client logic
-
-**For Backend Tasks**:
-- `zweer_web_backend` → API routes, Server Actions, business logic
-- `zweer_web_database` → Schema design, queries, migrations
-- `zweer_web_api_integration` → External integrations
-
-**For Quality Tasks**:
-- `zweer_qa_testing` → Automated tests
-- `zweer_qa_security` → Security and auth
-- `zweer_qa_performance` → Optimizations
-
-### Task Breakdown Example
-
-**User**: "Create login page"
-
-**Orchestrator**:
-1. `zweer_ui_ux` → Design authentication flow
-2. `zweer_ui_designer` → Form components and UI
-3. `zweer_web_backend` → Setup Auth.js and session management
-4. `zweer_web_database` → Users table and queries
-5. `zweer_qa_security` → CSRF protection and validation
-6. `zweer_qa_testing` → Test complete flow
-```
-
-### Providing Context to Agents
-
-When the orchestrator delegates to an agent, it must provide:
-
-```markdown
-**Project Context**:
-- Name: My Project
-- Tech Stack: Next.js 15, TypeScript, Drizzle ORM, Neon Postgres
-- Design: Dark mode, blue theme, mobile-first
-- Architecture: App Router, Server Components, Server Actions
-
-**Specific Task**:
-[Detailed task description]
-
-**Constraints**:
-- Use TypeScript strict mode
-- Follow project conventions (see ARCHITECTURE.md)
-- Minimal code, only what's needed
-```
-
-## Benefits of This Approach
-
-1. **Reusability**: Specialized agents work for any project
-2. **Separation**: Project context (orchestrator) vs generic expertise (agents)
-3. **Maintainability**: Agent updates propagate to all projects
-4. **Modularity**: Each agent is expert in a specific domain
-5. **Scalability**: Easy to add new agents or domains
-
-## Contributing
-
-To add new agents:
-
-1. Identify the domain (e.g. `agents/data/`, `agents/mobile/`)
-2. Create appropriate folder structure
-3. Write the agent in `.md` format with:
-   - YAML frontmatter (name, description, model, tools)
-   - Expertise description
-   - Best practices
-   - Code examples
-
-## Roadmap
-
-- [x] Services agents (`agents/services/`)
-  - [x] Lambda development
-  - [x] Microservices architecture
-  - [x] API Gateway & REST/GraphQL
-  - [x] Messaging (SQS, SNS, EventBridge)
-  - [x] Container orchestration (ECS, EKS)
-- [x] Infrastructure agents (`agents/infrastructure/`)
-  - [x] AWS CDK
-  - [x] Terraform
-  - [x] Observability (monitoring, logging)
-- [x] Mobile agents (`agents/mobile/`)
-  - [x] React Native
-  - [x] Ionic
-  - [x] Flutter
-  - [x] iOS native
-  - [x] Android native
-- [x] Data engineering agents (`agents/data/`)
-- [x] Writing agents (`agents/writing/`)
-- [ ] Common configurations (`configs/`)
-- [ ] Project templates (`templates/`)
-- [ ] Orchestrator examples
-
 ## License
 
 MIT

package/configs/_biome.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.8/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "files": { "ignoreUnknown": false },
+  "formatter": { "enabled": true, "useEditorconfig": true, "lineWidth": 100 },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": { "noUnknownAtRules": "off" }
+    },
+    "domains": { "test": "recommended" }
+  },
+  "javascript": { "formatter": { "quoteStyle": "single" } },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": {
+          "level": "on",
+          "options": {
+            "groups": [
+              ":URL:",
+              ":BLANK_LINE:",
+              [":BUN:", ":NODE:"],
+              ":BLANK_LINE:",
+              [":PACKAGE_WITH_PROTOCOL:", ":PACKAGE:"],
+              ":BLANK_LINE:",
+              ":ALIAS:",
+              ":BLANK_LINE:",
+              ":PATH:"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/configs/commitlint.config.ts

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/configs/editorconfig

@@ -0,0 +1,16 @@
+# http://editorconfig.org/
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

package/configs/lefthook.yml

@@ -0,0 +1,38 @@
+pre-commit:
+  piped: true
+  commands:
+    biome:
+      glob: "*.{ts,json,yaml,md,css,html}"
+      run: npx biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
+      stage_fixed: true
+      priority: 1
+    lockfile:
+      glob: "package-lock.json"
+      run: npx lockfile-lint
+      priority: 1
+    package-lint:
+      glob: "package.json"
+      run: npx npmPkgJsonLint .
+      priority: 1
+    package-sort:
+      glob: "package.json"
+      run: npx sort-package-json "package.json"
+      stage_fixed: true
+      priority: 1
+    build:
+      glob: "*.ts"
+      run: npm run build
+      priority: 2
+    typecheck:
+      glob: "*.ts"
+      run: tsc --noEmit
+      priority: 3
+    test:
+      glob: "*.ts"
+      run: npx vitest run --reporter=dot
+      priority: 3
+
+commit-msg:
+  commands:
+    commitlint:
+      run: npx --no -- commitlint --edit {1}

package/configs/lockfile-lintrc.json

@@ -0,0 +1,6 @@
+{
+  "path": "package-lock.json",
+  "type": "npm",
+  "validate-https": true,
+  "allowed-hosts": ["npm"]
+}