@jhm1909/ag-kit 0.1.0

package/.agent/skills/designer/scripts/ui-search/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, google-fonts
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/.agent/skills/designer/templates/design-motion-spec.md

@@ -0,0 +1,30 @@
+---
+id: MOTION-SPEC-{ID}
+type: specification
+status: draft
+owner: @designer
+linked-to: [[User-Story-ID]]
+---
+
+# Motion Specification: {Title}
+
+**Purpose**: {Why are we animating this? Orientation / Feedback / Focus / Delight}
+**Trigger**: {Load / Hover / Click / Scroll / State Change}
+**Element**: {Component or Element Name, e.g., Primary Button, Hero Image}
+
+## Animation Timeline
+
+| Time | Element   | Property | Start Value | End Value | Duration | Easing   | Delay |
+| :--- | :-------- | :------- | :---------- | :-------- | :------- | :------- | :---- |
+| 0ms  | Container | Scale    | 0.9         | 1.0       | 300ms    | ease-out | 0ms   |
+| 50ms | Icon      | Opacity  | 0           | 1         | 200ms    | linear   | 50ms  |
+| ...  | ...       | ...      | ...         | ...       | ...      | ...      | ...   |
+
+## Behavior Description
+
+{Describe the behavior in plain English. Example: "The container should spring open, and then the icon fades in slightly later to lead the eye."}
+
+## Development Reference
+
+- **Standard Curve**: `cubic-bezier(0, 0, 0.2, 1)` (Decelerate)
+- **Reduced Motion**: {Fade in only / None}

package/.agent/skills/devops-engineer/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: devops-engineer
+description: >
+  CI/CD, multi-cloud infrastructure, and observability. Use for AWS/GCP/Azure, Docker, Kubernetes, and SRE practices.
+license: MIT
+compatibility: Claude Code, Cursor, Gemini CLI, GitHub Copilot
+metadata:
+  author: jhm1909
+  version: "2.0.0"
+  domain: infra
+  estimated_tokens: 6000
+---
+
+# DevOps Engineer
+
+Infrastructure automation, deployment pipelines, and observability systems.
+
+## Knowledge Graph
+
+- **extends**: []
+- **requires**: []
+- **suggests**: []
+- **conflicts**: []
+- **enhances**: [[backend-developer]], [[mobile-developer]] (EAS CI/CD)
+- **moc**: [[infrastructure-moc]]
+
+## Capability Add-ons
+
+| Sub-capability | Location | Use For |
+|:---------------|:---------|:--------|
+| Docker Compose | `docker-compose/` | Local development environments |
+| Kubernetes | Load `kubernetes/` reference | Container orchestration |
+| Observability | Load `observability/` reference | Monitoring & logging |
+
+## Using Sub-capabilities
+
+When a task requires Docker Compose expertise:
+
+1. Load `docker-compose/README.md` from this skill directory
+2. Apply patterns for multi-container local development
+3. Reference docker-compose.yml examples provided
+
+Example workflow:
+```
+User: "Set up local dev environment with Postgres and Redis"
+→ Load devops-engineer/docker-compose/README.md
+→ Define services, volumes, networks
+→ Provide docker-compose.yml configuration
+```
+
+## Core Philosophy
+
+1. **Automate Everything** — If done twice, script it
+2. **Infrastructure as Code** — No click-ops (Terraform, Pulumi)
+3. **Security First** — Secrets via Vault/KMS, not env vars
+4. **Observability** — Logs, Metrics, Traces are mandatory
+
+## Stack Selection
+
+| Component | Options | Best For |
+|:----------|:--------|:---------|
+| **Cloud** | AWS / GCP / Azure | AWS=Enterprise, GCP=Data/AI, Azure=Windows |
+| **IaC** | Terraform / Pulumi / CDK | TF=Standard, Pulumi=Dev-friendly |
+| **CI/CD** | GitHub Actions / GitLab CI / Jenkins | GHA=Open Source, GitLab=DevSecOps |
+| **Containers** | Docker / Kubernetes | Docker=Simple, K8s=Orchestration |
+| **Observability** | Datadog / Grafana / CloudWatch | Full stack monitoring |
+
+## Security Standards
+
+- **Least Privilege** — IAM strictly scoped
+- **Encryption** — At rest (KMS) and in transit (TLS 1.2+)
+- **Scanning** — SAST, DAST, Container scanning (Trivy)
+
+## References
+
+- `cloud-providers.md` — AWS/GCP/Azure specifics
+- `iac-tools.md` — Terraform/Pulumi patterns
+- `ci-cd-pipelines.md` — Pipeline design
+- `container-orchestration.md` — Docker/Kubernetes
+- `observability-security.md` — Monitoring, logging
+
+## Related Skills
+
+- [[backend-developer]] — Application deployment
+- [[mobile-developer]] — EAS CI/CD for mobile
+- [[lead-architect]] — High-level infrastructure decisions
+
+---
+
+*Part of [[infrastructure-moc]] | Foundation for all deployments*

package/.agent/skills/devops-engineer/docker-compose/README.md

@@ -0,0 +1,47 @@
+---
+name: docker-compose
+type: capability
+domain: infra
+status: draft
+version: "1.0.0"
+estimated_tokens: 5000
+description: Docker Compose for local development and multi-container apps.
+---
+
+# Docker Compose
+
+Container orchestration for local development.
+
+## Knowledge Graph
+
+- **extends**: []
+- **requires**: [[devops-engineer]]
+- **suggests**: []
+- **conflicts": []
+- **enhances": [[devops-engineer]], [[backend-developer]]
+- **moc**: [[infrastructure-moc]]
+
+## Overview
+
+This skill covers:
+- docker-compose.yml structure
+- Multi-service applications
+- Environment configuration
+- Volume management
+- Local development workflows
+
+## Use Cases
+
+- Local development environment
+- Integration testing
+- CI/CD pipelines
+- Quick prototyping
+
+## Related
+
+- [[devops-engineer]] — Container fundamentals
+- [[kubernetes]] — Production orchestration
+
+---
+
+*Part of [[infrastructure-moc]]*

package/.agent/skills/devops-engineer/references/ci-cd-pipelines.md

@@ -0,0 +1,76 @@
+# CI/CD Pipelines
+
+## GitHub Actions
+
+### Workflow Structure (`.github/workflows/main.yml`)
+
+```yaml
+name: Production Build
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+      - run: npm ci
+      - run: npm test
+
+  deploy:
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy
+        env:
+          API_KEY: ${{ secrets.PROD_API_KEY }}
+        run: ./deploy.sh
+```
+
+### Best Practices
+
+- **Secrets**: NEVER hardcode. Use `${{ secrets.NAME }}`.
+- **Caching**: Use `setup-node` (or equivalent) built-in caching or `actions/cache`.
+- **Reusable Workflows**: Use `workflow_call` for shared logic.
+
+## GitLab CI
+
+### Workflow Structure (`.gitlab-ci.yml`)
+
+```yaml
+stages:
+  - test
+  - build
+  - deploy
+
+test_job:
+  stage: test
+  image: node:20
+  script:
+    - npm ci
+    - npm test
+
+deploy_prod:
+  stage: deploy
+  script:
+    - ./deploy.sh
+  only:
+    - main
+  environment: production
+```
+
+### Best Practices
+
+- **Templates**: Use `include:` to share config across projects.
+- **Runners**: Tag jobs to run on specific runners (`tags: [docker]`).
+- **Artifacts**: Use `artifacts` to pass binaries/files between stages.

package/.agent/skills/devops-engineer/references/cloud-providers.md

@@ -0,0 +1,57 @@
+# Cloud Providers Reference
+
+## Service Mapping Cheat Sheet
+
+| Service Category          | Amazon Web Services (AWS) | Google Cloud Platform (GCP) | Microsoft Azure                     |
+| :------------------------ | :------------------------ | :-------------------------- | :---------------------------------- |
+| **Compute - VM**          | EC2                       | Compute Engine              | Virtual Machines                    |
+| **Compute - Serverless**  | Lambda                    | Cloud Functions             | Azure Functions                     |
+| **Compute - Managed K8s** | EKS                       | GKE                         | AKS                                 |
+| **Compute - Containers**  | ECS / Fargate             | Cloud Run                   | Container Instances / Apps          |
+| **Storage - Object**      | S3                        | Cloud Storage (GCS)         | Blob Storage                        |
+| **Storage - Block**       | EBS                       | Persistent Disk             | Disk Storage                        |
+| **Storage - File**        | EFS                       | Filestore                   | Azure Files                         |
+| **Database - RDBMS**      | RDS / Aurora              | Cloud SQL / Spanner         | Azure SQL / Database for PostgreSQL |
+| **Database - NoSQL**      | DynamoDB                  | Firestore / BigTable        | Cosmos DB                           |
+| **Caching**               | ElastiCache               | Memorystore                 | Azure Cache for Redis               |
+| **Networking - CDN**      | CloudFront                | Cloud CDN                   | Azure Front Door / CDN              |
+| **Networking - DNS**      | Route 53                  | Cloud DNS                   | Azure DNS                           |
+| **IaC**                   | CloudFormation / CDK      | Deployment Manager          | ARM Templates / Bicep               |
+
+## AWS (Amazon Web Services)
+
+### Quick Start
+
+- **CLI**: `aws`
+- **Auth**: `aws configure` (requires `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+
+### Best Practices
+
+- **Roles**: Use IAM Roles for EC2/Lambda, never baked-in credentials.
+- **Regions**: Always specify regions in code (e.g., `us-east-1`).
+- **Cost**: Use Budgets and Cost Explorer alarms.
+
+## GCP (Google Cloud Platform)
+
+### Quick Start
+
+- **CLI**: `gcloud`
+- **Auth**: `gcloud auth login` or service account JSON (`GOOGLE_APPLICATION_CREDENTIALS`).
+
+### Best Practices
+
+- **Projects**: Use hierarchal project structure (Folder -> Project).
+- **APIs**: Explicitly enable required APIs in Terraform (`google_project_service`).
+- **Network**: Use VPC-native clusters for GKE.
+
+## Azure
+
+### Quick Start
+
+- **CLI**: `az`
+- **Auth**: `az login` or Service Principal (`ARM_CLIENT_ID`, `ARM_CLIENT_SECRET`).
+
+### Best Practices
+
+- **Resource Groups**: Logical container for lifecycle management.
+- **Policies**: Use Azure Policy for governance (e.g., allow regions).

package/.agent/skills/devops-engineer/references/codebase-normalization.md

@@ -0,0 +1,104 @@
+# Codebase Normalization & Quality Gates
+
+This guide outlines standards and instructions for implementing codebase normalization tools to ensure code quality, consistency, and stability.
+
+## 🧰 Toolchain Selection
+
+| Feature            | Husky + Lint-staged            | Lefthook                             | Biome                           | ESLint + Prettier              |
+| :----------------- | :----------------------------- | :----------------------------------- | :------------------------------ | :----------------------------- |
+| **Role**           | Git Hooks Manager              | Git Hooks Manager                    | Formatter + Linter              | Linter + Formatter             |
+| **Speed**          | Standard                       | Fast (Go-based)                      | Extremely Fast (Rust)           | Standard                       |
+| **Usage**          | Industry Standard for Node.js  | Growing popularity, multi-language   | Modern, zero-config replacement | Mature, vast ecosystem         |
+| **Recommendation** | **Default** for JS/TS projects | Projects with heavy pre-commit tasks | Greenfields needing speed       | Legacy or complex custom rules |
+
+## 🚀 Implementation Guides
+
+### 1. Husky & Lint-staged (Standard)
+
+Use this setup to enforce checks before every commit.
+
+```bash
+# 1. Install dependencies
+npm install --save-dev husky lint-staged
+
+# 2. Initialize Husky
+npx husky init
+
+# 3. Configure lint-staged in package.json
+# Add this to your package.json
+"lint-staged": {
+  "*.{js,ts,jsx,tsx}": [
+    "eslint --fix",
+    "prettier --write"
+  ],
+  "*.{json,md}": [
+    "prettier --write"
+  ]
+}
+
+# 4. Create pre-commit hook
+# In .husky/pre-commit
+echo "npx lint-staged" > .husky/pre-commit
+```
+
+### 2. Commitlint (Conventional Commits)
+
+Enforce meaningful commit messages.
+
+```bash
+# 1. Install dependencies
+npm install --save-dev @commitlint/{cli,config-conventional}
+
+# 2. Configure Commitlint
+echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
+
+# 3. Add commit-msg hook
+echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
+```
+
+### 3. Biome (All-in-one Alternative)
+
+Replace ESLint & Prettier for performance.
+
+```bash
+# 1. Install Biome
+npm install --save-dev --save-exact @biomejs/biome
+
+# 2. Initialize
+npx @biomejs/biome init
+
+# 3. Use in lint-staged
+"lint-staged": {
+  "*.{js,ts,jsx,tsx,json}": [
+    "npx @biomejs/biome check --apply"
+  ]
+}
+```
+
+## 🏗️ Workflow Integration
+
+### Pre-commit Strategy
+
+- **Goal**: Prevent bad code from entering the repo.
+- **Scope**: Run ONLY on staged files (don't lint the whole repo).
+- **Checks**:
+  - Linting (ESLint/Biome)
+  - Formatting (Prettier/Biome)
+  - Type Checking (tsc --noEmit) -> _Note: tsc often needs the whole project, consider running in CI instead or using `tsc-files` for partial checks._
+  - Unit Tests (related files only)
+
+### CI Strategy
+
+- **Goal**: Verify state of the branch.
+- **Scope**: Run on all files.
+- **Checks**:
+  - Full Lint
+  - Full Type Check
+  - Full Audit (`npm audit`)
+  - Integration/E2E tests
+
+## 🛡️ Best Practices
+
+1.  **Keep Hooks Fast**: Developers hate waiting. If pre-commit takes >5s, move heavy tasks to CI.
+2.  **Escape Hatches**: Allow `--no-verify` for emergencies, but log it.
+3.  **Consistency**: Ensure local checks match CI checks exactly.

package/.agent/skills/devops-engineer/references/container-orchestration.md

@@ -0,0 +1,69 @@
+# Container Orchestration
+
+## Docker
+
+### Dockerfile Best Practices
+
+1.  **Multi-Stage Builds**: Keep final images small.
+
+    ```dockerfile
+    # Build Stage
+    FROM node:20-alpine AS builder
+    WORKDIR /app
+    COPY . .
+    RUN npm ci && npm run build
+
+    # Run Stage
+    FROM node:20-alpine
+    WORKDIR /app
+    COPY --from=builder /app/dist ./dist
+    COPY --from=builder /app/node_modules ./node_modules
+    CMD ["node", "dist/index.js"]
+    ```
+
+2.  **.dockerignore**: Always include one to avoid context bloat.
+3.  **User**: Run as non-root user (`USER node`).
+
+## Kubernetes (K8s)
+
+### Core Resources
+
+- **Pod**: Smallest deployable unit (containers).
+- **Deployment**: Manages Pod replicas and rollouts.
+- **Service**: Exposes network access (ClusterIP, LoadBalancer).
+- **Ingress**: HTTP/HTTPS routing.
+- **ConfigMap/Secret**: Configuration separation.
+
+### Manifest Example (`deployment.yaml`)
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+        - name: my-app
+          image: my-registry/my-app:v1
+          ports:
+            - containerPort: 8080
+          resources:
+            limits:
+              memory: "128Mi"
+              cpu: "500m"
+```
+
+### Best Practices
+
+- **Liveness/Readiness Probes**: Mandatory for self-healing and zero-downtime.
+- **Resources**: ALWAYS set requests and limits.
+- **Namespaces**: Use namespaces to isolate environments.

package/.agent/skills/devops-engineer/references/iac-tools.md

@@ -0,0 +1,63 @@
+# Infrastructure as Code (IaC) Tools
+
+## Terraform (The Standard)
+
+### Structure
+
+- `main.tf`: Resources
+- `variables.tf`: Input schemas
+- `outputs.tf`: Return values
+- `provider.tf`: Provider config
+
+### Essential Commands
+
+```bash
+terraform init          # Initialize backend
+terraform plan -out=tfplan # Preview changes
+terraform apply tfplan  # Execute changes
+terraform fmt -recursive # Format code
+terraform validate      # Check syntax
+```
+
+### Best Practices
+
+- **Remote Backend**: Store state in S3/GCS with locking (DynamoDB).
+- **Modules**: Use standard directory structure for reusability.
+- **Versions**: Pin provider versions in `required_providers`.
+
+## Pulumi (The Modern)
+
+### Philosophy
+
+Write infrastructure in real programming languages (TS, Python, Go).
+
+### Essential Commands
+
+```bash
+pulumi new aws-typescript # Start project
+pulumi up                 # Plan & Apply
+pulumi stack ls           # List stacks (dev/prod)
+```
+
+### Best Practices
+
+- **ComponentResources**: Group multiple resources into logical components (e.g., `VpcComponent`).
+- **Secrets**: Use `pulumi config set --secret` to encrypt values.
+
+## Ansible (The Configurator)
+
+### Philosophy
+
+Agentless configuration management using YAML playbooks and SSH.
+
+### Essential Commands
+
+```bash
+ansible-playbook -i inventory site.yml
+```
+
+### Best Practices
+
+- **Idempotency**: Ensure tasks can run multiple times without side effects.
+- **Roles**: Organize tasks into reusable Roles (Galaxy).
+- **Vault**: Encrypt sensitive variables with `ansible-vault`.