@vyuhlabs/dxkit 0.1.0

package/templates/.claude/commands/quality.md.template

@@ -0,0 +1,42 @@
+---
+description: Run quality checks (linting, formatting, type checking)
+---
+
+Two-step quality check:
+
+## Step 1: Run Linters
+
+Run these checks in order. Stop and report if any step fails.
+
+{{#IF_NODE}}
+### Node / TypeScript
+1. `npx eslint .` — Lint
+2. `npx tsc --noEmit` — Type check
+{{/IF_NODE}}
+{{#IF_PYTHON}}
+### Python
+1. `ruff check .` — Lint
+2. `ruff format --check .` — Format check
+3. `mypy .` — Type check
+{{/IF_PYTHON}}
+{{#IF_GO}}
+### Go
+1. `golangci-lint run ./...` — Lint
+2. `go vet ./...` — Vet
+{{/IF_GO}}
+{{#IF_CSHARP}}
+### C#
+1. `dotnet format --verify-no-changes` — Format check
+2. `dotnet build --no-restore -warnaserror` — Build with warnings as errors
+{{/IF_CSHARP}}
+{{#IF_RUST}}
+### Rust
+1. `cargo fmt --check` — Format check
+2. `cargo clippy -- -D warnings` — Lint
+{{/IF_RUST}}
+
+## Step 2: AI Review
+
+After linters pass, delegate to the **quality-reviewer** agent to review changed files for logic issues, security problems, and best practice violations that linters miss.
+
+Report combined results from both steps.

package/templates/.claude/commands/session-end.md

@@ -0,0 +1,40 @@
+---
+description: End session and create checkpoint with skill evolution
+---
+
+Ending the current development session.
+
+## Session Info
+
+Determine the developer name from `git config user.name` and today's date. Create the session directory at `.ai/sessions/<developer>/<date>/` if it doesn't exist. Find the next session number by checking existing `session-*.md` files. Also check recent git commits and uncommitted changes.
+
+## Create Checkpoint
+
+Create a comprehensive checkpoint at `.ai/sessions/<developer>/<date>/session-<N>.md`. Include:
+
+### Required Sections
+- **Session Goal** — What we set out to do
+- **Accomplished** — Specific items completed (not vague — include file paths, counts)
+- **Files Created/Modified** — Every file with description
+- **Key Decisions** — What we decided, why, alternatives considered
+- **Implementation Details** — How things work, patterns used
+- **Testing Status** — Tests added, coverage, passing status
+- **Next Session** — Clear, actionable steps for next session
+- **Context for AI** — Detailed context for the next session's agent
+- **Blockers / Considerations** — Issues, tech debt, dependencies
+
+## Skill Evolution
+
+After creating the checkpoint, review this session for learnings:
+
+1. **Gotchas** — Append to `.claude/skills/learned/references/gotchas.md`
+   Format: `## YYYY-MM-DD - Category / Title` + description + resolution
+
+2. **Conventions** — Append to `.claude/skills/learned/references/conventions.md`
+   Format: `## Category - Convention Name` + description + rationale
+
+3. **Deny recommendations** — If a dangerous command was nearly executed, append to `.claude/skills/learned/references/deny-recommendations.md`
+
+4. **New skills** — If a distinct new domain emerged, create `.claude/skills/<name>/SKILL.md`
+
+**NEVER include secret values, tokens, or credentials in checkpoints or skill files.**

package/templates/.claude/commands/session-start.md

@@ -0,0 +1,30 @@
+---
+description: Start an AI-assisted development session
+---
+
+Starting a new development session.
+
+## Session Info
+
+Determine the developer name from `git config user.name` and today's date. Check `.ai/sessions/` for previous checkpoints from this developer.
+
+## Before Planning
+
+Check Claude Code skills for relevant context:
+- Read `.claude/skills/codebase/SKILL.md` if it exists (run `/explore-codebase` if missing)
+- Read `.claude/skills/learned/references/gotchas.md` for known project gotchas
+- Read `.claude/skills/learned/references/conventions.md` for team conventions
+
+## Plan This Session
+
+Before coding, let's plan:
+
+1. What files will we need to create/modify?
+2. What are the key components/functions?
+3. What dependencies or external services do we need?
+4. What tests should we write?
+5. Can we complete this in one session?
+6. Does this align with our architecture?
+7. Are there relevant gotchas or conventions in `.claude/skills/` to be aware of?
+
+Once we have a solid plan, I'll proceed step by step — explaining WHAT, WHY, and HOW before each change.

package/templates/.claude/commands/setup-hooks.md

@@ -0,0 +1,60 @@
+---
+description: Install git pre-commit and pre-push hooks for quality checks
+---
+
+Set up git hooks for this project based on the detected tech stack.
+
+## Detect Stack
+
+Check which languages/tools are present by looking for:
+- `package.json` → Node/TypeScript (eslint, prettier, tsc)
+- `pyproject.toml` or `requirements.txt` → Python (ruff, mypy)
+- `go.mod` → Go (golangci-lint, gofmt)
+- `*.csproj` or `*.sln` → C# (dotnet format)
+- `Cargo.toml` → Rust (cargo clippy, cargo fmt)
+
+## Generate Hooks
+
+Create `.git/hooks/pre-commit` with the appropriate checks:
+
+**Structure:**
+```bash
+#!/bin/bash
+set -e
+echo "Running pre-commit checks..."
+
+# Only check staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+# [language-specific checks based on detected stack]
+
+echo "All checks passed!"
+```
+
+**Per language (only include detected ones):**
+
+- **Node/TS**: `npx eslint --no-warn-ignored $JS_FILES` and `npx prettier --check $JS_FILES`
+- **Python**: `ruff check $PY_FILES` and `ruff format --check $PY_FILES`
+- **Go**: `gofmt -l $GO_FILES` (fail if any output) and `golangci-lint run`
+- **C#**: `dotnet format --verify-no-changes`
+- **Rust**: `cargo fmt --check` and `cargo clippy -- -D warnings`
+
+Also create `.git/hooks/pre-push` with test runners:
+- **Node**: `npm test`
+- **Python**: `pytest`
+- **Go**: `go test ./...`
+- **C#**: `dotnet test`
+- **Rust**: `cargo test`
+
+Make both hooks executable with `chmod +x`.
+
+## If pre-commit framework exists
+
+If `.pre-commit-config.yaml` already exists or `pre-commit` is installed, suggest using that instead:
+```bash
+pre-commit install
+```
+
+## After Setup
+
+Confirm what hooks were installed and what they check. Mention that hooks can be bypassed with `git commit --no-verify` (but discourage it).

package/templates/.claude/commands/test.md.template

@@ -0,0 +1,49 @@
+---
+description: Run tests with coverage reporting
+---
+
+Run tests with coverage. Enforce minimum coverage threshold.
+
+{{#IF_NODE}}
+## Node / TypeScript
+Run: `npx jest --coverage` or `npm test -- --coverage`
+
+If jest is not configured, try: `npm test`
+
+**Coverage threshold: {{COVERAGE_THRESHOLD}}%** — fail if below this.
+Check `jest.config.*` or `package.json` for existing threshold config.
+{{/IF_NODE}}
+{{#IF_PYTHON}}
+## Python
+Run: `pytest --cov --cov-report=term-missing --cov-fail-under={{COVERAGE_THRESHOLD}}`
+
+If pytest-cov is not installed: `pytest`
+{{/IF_PYTHON}}
+{{#IF_GO}}
+## Go
+Run: `go test -coverprofile=coverage.out -covermode=atomic ./...`
+Then: `go tool cover -func=coverage.out`
+
+Check that total coverage is at least **{{COVERAGE_THRESHOLD}}%**.
+{{/IF_GO}}
+{{#IF_CSHARP}}
+## C#
+Run: `dotnet test --collect:"XPlat Code Coverage"`
+
+If coverlet is available, check that coverage meets **{{COVERAGE_THRESHOLD}}%**.
+{{/IF_CSHARP}}
+{{#IF_RUST}}
+## Rust
+Run: `cargo test`
+
+If cargo-tarpaulin is installed: `cargo tarpaulin --fail-under {{COVERAGE_THRESHOLD}}`
+{{/IF_RUST}}
+
+## Report
+
+Summarize:
+- Total tests: passed / failed / skipped
+- Coverage: X% (threshold: {{COVERAGE_THRESHOLD}}%)
+- Uncovered critical files (if any)
+
+If coverage is below threshold, list the files with lowest coverage that should be prioritized.

package/templates/.claude/rules/csharp.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.cs"
+  - "services/csharp/**/*"
+---
+
+# C# Rules
+
+- Enable nullable reference types (`#nullable enable`) in all files
+- Use async/await for all I/O — never block with `.Result` or `.Wait()`
+- Prefer pattern matching and switch expressions over if-else chains
+- Use record types for immutable data transfer objects
+- Use dependency injection via IServiceCollection — no service locators or manual `new` for services
+- Prefer xUnit for testing with `[Fact]` and `[Theory]` attributes
+- Use `dotnet format` for formatting — check with `dotnet format --verify-no-changes`
+- Write XML doc comments (`///`) on all public APIs
+- Use `using` declarations for IDisposable resources
+- Prefer `string.IsNullOrEmpty()` over null checks + length checks

package/templates/.claude/rules/go.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - "**/*.go"
+  - "services/go/**/*"
+---
+
+# Go Rules
+
+- Always handle errors — never assign to `_`
+- Propagate `context.Context` through call chains
+- Use `defer` for resource cleanup (Close, Unlock, etc.)
+- Table-driven tests with `t.Run()` subtests
+- Use `httptest` for HTTP handler testing
+- Errors should wrap with `fmt.Errorf("context: %w", err)`
+- Prefer standard library over third-party when reasonable
+- Use `golangci-lint` (not `go vet` alone) for comprehensive linting

package/templates/.claude/rules/nextjs.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "frontend/**/*.ts"
+  - "frontend/**/*.tsx"
+  - "frontend/**/*.js"
+  - "frontend/**/*.jsx"
+---
+
+# Next.js Rules
+
+- Use App Router (`app/` directory), not Pages Router
+- Prefer Server Components by default; add `"use client"` only when needed
+- Never expose secrets or sensitive data in client components
+- Use TypeScript strict mode — no `any` types
+- Validate API inputs with zod at route handlers
+- Use Tailwind CSS for styling (configured in project)
+- Run `npm run build` in `frontend/` to catch type errors before committing

package/templates/.claude/rules/python.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "src/**/*.py"
+  - "services/python/**/*.py"
+  - "tests/**/*.py"
+  - "**/*.py"
+---
+
+# Python Rules
+
+- Use ruff for linting and formatting (not black, not flake8)
+- Type hints required on all public functions
+- Use Pydantic models for data validation at system boundaries
+- Use `from __future__ import annotations` for forward references
+- Prefer `pathlib.Path` over `os.path`
+- No bare `except:` — catch specific exceptions
+- Use app factory pattern for FastAPI/Flask applications
+- Tests use pytest (not unittest) with fixtures for setup
+- Imports: stdlib → third-party → local (ruff isort handles this)

package/templates/.claude/rules/rust.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "**/*.rs"
+  - "services/rust/**/*"
+---
+
+# Rust Rules
+
+- Use `clippy` lints — fix all warnings before committing
+- Prefer `Result<T, E>` over panics for error handling
+- Use `thiserror` for library errors, `anyhow` for application errors
+- Write doc comments (`///`) on all public items
+- Use `cargo fmt` formatting (rustfmt.toml if configured)
+- Prefer `&str` over `String` in function signatures when possible

package/templates/.claude/skills/build/SKILL.md.template

@@ -0,0 +1,98 @@
+---
+name: build
+description: Build code, compile binaries, install dependencies, clean artifacts. Use when asked to build, compile, install, or clean the project.
+---
+
+# Build
+
+## Commands
+- `make build` - Build all services
+- `make clean` - Remove build artifacts (bin/, pyc, coverage, tmp/)
+- `make dev` - Start all services (docker-compose up)
+- `make stop` - Stop all services (docker-compose down)
+
+{{#IF_PYTHON}}
+## Python Build
+
+Python services use editable installs:
+```bash
+pip install -e services/python/<service-name>/
+```
+
+Build checks:
+- Syntax: `python3 -m py_compile <file>`
+- Types: `mypy src/`
+- Package: `python3 -m build` (if pyproject.toml has build-system)
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+## Go Build
+
+Go services compile to `bin/`:
+```bash
+go build -o bin/<service-name> ./services/go/<service-name>/
+```
+
+Build flags:
+- `CGO_ENABLED=0` for static binaries (container-friendly)
+- `-ldflags="-s -w"` to strip debug info (smaller binary)
+- `GOOS=linux GOARCH=amd64` for cross-compilation
+{{/IF_GO}}
+
+{{#IF_NODE}}
+## Node.js Build
+
+```bash
+npm install          # install dependencies
+npm run build        # compile TypeScript / bundle
+```
+{{/IF_NODE}}
+
+{{#IF_NEXTJS}}
+## Next.js Build
+
+```bash
+cd frontend
+npm install
+npm run build        # production build (checks for errors)
+npm run dev          # development server
+```
+
+The build step catches TypeScript errors and missing imports — run it before deploying.
+{{/IF_NEXTJS}}
+
+{{#IF_RUST}}
+## Rust Build
+
+```bash
+cargo build              # debug build
+cargo build --release    # optimized build
+```
+{{/IF_RUST}}
+
+{{#IF_CSHARP}}
+## C# Build
+
+```bash
+dotnet restore                       # restore NuGet packages
+dotnet build                         # debug build
+dotnet build --configuration Release # release build
+dotnet publish -c Release -o out/    # publish for deployment
+```
+{{/IF_CSHARP}}
+
+{{#IF_DOCKER}}
+## Docker Build
+
+```bash
+docker-compose build              # build all services
+docker-compose build <service>    # build specific service
+docker-compose up --build         # rebuild and start
+```
+{{/IF_DOCKER}}
+
+## Security
+
+- **Never include secrets in build args or Dockerfiles**
+- Use multi-stage builds to avoid leaking build-time dependencies
+- Don't copy `.env` files into Docker images

package/templates/.claude/skills/deploy/SKILL.md.template

@@ -0,0 +1,131 @@
+---
+name: deploy
+description: Deploy services, release to production, push to cloud. Use when asked about deployment, releases, shipping to production, or CI/CD.
+---
+
+# Deployment
+
+## Commands
+- `make deploy` - Deploy services (configure deployment target first)
+- `make build` - Build before deploying
+- `make check` - Run full validation before deploying
+
+## Pre-Deployment Checklist
+- [ ] `make check` passes (quality + tests + validation)
+- [ ] All changes committed and pushed
+- [ ] PR reviewed and approved
+{{#IF_INFISICAL}}
+- [ ] Secrets pulled: `make secrets-pull`
+{{/IF_INFISICAL}}
+- [ ] No hardcoded secrets in code or config
+
+## Deployment Safety
+
+**CRITICAL: Never auto-approve destructive deployment operations.**
+
+- Always preview/dry-run before applying changes
+- Require explicit user confirmation for production deployments
+- Never force-push or skip CI checks before deploying
+{{#IF_INFISICAL}}
+
+## Secrets for Deployment
+
+Pull secrets before deploying:
+```bash
+make secrets-pull     # fetch from Infisical to .env
+make secrets-show     # verify configuration (masked values)
+```
+
+**Never pass secrets as CLI arguments** — use environment variables or secret managers.
+{{/IF_INFISICAL}}
+
+{{#IF_GCLOUD}}
+## Google Cloud Deployment
+
+### Cloud Run
+```bash
+# Build and push container
+gcloud builds submit --tag gcr.io/$PROJECT_ID/<service-name>
+
+# Deploy (ALWAYS review before confirming)
+gcloud run deploy <service-name> \
+  --image gcr.io/$PROJECT_ID/<service-name> \
+  --region <region> \
+  --platform managed
+```
+
+### GKE
+```bash
+# Build image
+docker build -t gcr.io/$PROJECT_ID/<service-name> .
+docker push gcr.io/$PROJECT_ID/<service-name>
+
+# Apply manifests (review first)
+kubectl apply -f k8s/ --dry-run=client  # preview
+kubectl apply -f k8s/                    # apply
+```
+
+**Security:** Use Workload Identity for GCP auth in production — never embed service account keys.
+{{/IF_GCLOUD}}
+
+{{#IF_PULUMI}}
+## Pulumi Deployment
+
+```bash
+# ALWAYS preview first
+pulumi preview
+
+# Review the diff carefully, then apply
+pulumi up
+
+# Check outputs
+pulumi stack output
+```
+
+**Security:** Use `pulumi config set --secret` for sensitive config — never plain-text.
+
+**Never run `pulumi destroy` without explicit confirmation** — it deletes all resources.
+{{/IF_PULUMI}}
+
+{{#IF_DOCKER}}
+## Docker Deployment
+
+```bash
+# Build images
+docker-compose build
+
+# Push to registry
+docker-compose push
+
+# Deploy (depends on orchestration platform)
+docker-compose -f docker-compose.prod.yml up -d
+```
+
+**Security:** Never copy `.env` files into Docker images. Use runtime environment variables.
+{{/IF_DOCKER}}
+
+{{#IF_CSHARP}}
+## C# Deployment
+
+```bash
+# Framework-dependent (requires .NET runtime on target)
+dotnet publish -c Release -o out/ --self-contained false
+
+# Self-contained (no runtime needed on target)
+dotnet publish -c Release -r linux-x64 --self-contained true
+```
+
+For Docker, use multi-stage builds:
+- Build stage: `mcr.microsoft.com/dotnet/sdk:{{CSHARP_VERSION}}`
+- Runtime stage: `mcr.microsoft.com/dotnet/aspnet:{{CSHARP_VERSION}}`
+{{/IF_CSHARP}}
+
+## CI/CD
+
+CI pipeline (`.github/workflows/ci.yml`) runs automatically on PR:
+- Validation, quality checks, tests per enabled language
+- Coverage enforcement at {{COVERAGE_THRESHOLD}}%
+
+## Gotchas
+
+See [references/gotchas.md](references/gotchas.md) for known deployment issues.

package/templates/.claude/skills/deploy/references/gotchas.md

@@ -0,0 +1,5 @@
+# Deployment Gotchas
+
+<!-- This file grows over time. Each entry is added during session-end. -->
+<!-- Format: date, category, description, resolution -->
+<!-- NEVER include secret values, tokens, or credentials here -->

package/templates/.claude/skills/doctor/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: doctor
+description: Diagnose and fix development environment issues. Use when setup fails, tools are missing, the environment is broken, or something is misconfigured.
+---
+
+# Doctor & Setup
+
+## Commands
+- `make doctor` - Diagnose common setup issues (checks files, toolchains, config)
+- `make setup` - Interactive setup for new developers
+- `make info` - Show project configuration dashboard
+- `make config` - Interactive configuration editor
+
+## What Doctor Checks
+1. Core files (`.project.yaml`, `Makefile`, `.project/`)
+2. YAML syntax validation
+3. Language toolchain versions (Python, Go, Node, Rust)
+4. Quality tools installation (linters, formatters)
+5. Pre-commit hook configuration
+6. Git configuration
+7. Docker/Docker Compose availability
+8. Service health (if infrastructure enabled)
+
+## Common Issues & Fixes
+
+### Missing tools
+```bash
+make doctor    # identify what's missing
+make setup     # re-run interactive setup
+```
+
+### Config out of sync
+```bash
+make sync          # re-sync .project.yaml to language files
+make sync-preview  # preview changes first (dry run)
+```
+
+### Pre-commit failures
+```bash
+make fix       # auto-fix all issues
+make check     # verify everything passes
+```
+
+### Build failures after config change
+```bash
+make sync      # sync config
+make clean     # clean artifacts
+make build     # rebuild
+```
+
+## Environment
+- DevContainer-based (see `.devcontainer/`)
+- `post-create.sh` runs automatically on container creation
+- All tools installed via devcontainer features or post-create script

package/templates/.claude/skills/gcloud/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: gcloud
+description: Google Cloud Platform operations — gcloud CLI, Cloud Run, GKE, BigQuery, IAM, GCS. Use when asked about GCP, Google Cloud, gcloud commands, or cloud infrastructure.
+---
+
+# Google Cloud (gcloud)
+
+## Setup
+- **Auth:** `gcloud auth login` (configured during `make setup`)
+- **Project:** Set in `.env` as `GOOGLE_CLOUD_PROJECT`
+- **SDK:** Installed via devcontainer post-create script
+
+## Common Commands
+
+### Authentication & Project
+```bash
+gcloud auth list                              # check auth status
+gcloud config get-value project               # current project
+gcloud config set project <PROJECT_ID>        # switch project
+gcloud projects list                          # list accessible projects
+```
+
+### Services & Resources
+```bash
+gcloud services list --enabled                # enabled APIs
+gcloud run services list                      # Cloud Run services
+gcloud container clusters list                # GKE clusters
+gcloud sql instances list                     # Cloud SQL instances
+gcloud storage ls                             # GCS buckets
+```
+
+### Logs & Monitoring
+```bash
+gcloud logging read "resource.type=cloud_run_revision" --limit=50
+gcloud logging read "severity>=ERROR" --limit=20 --format=json
+```
+
+## Integration with Secrets
+
+GCP project ID is stored in `.env`:
+```
+GOOGLE_CLOUD_PROJECT=my-project-id
+```
+
+Use `make secrets-pull` to fetch GCP-related secrets from Infisical.
+
+## Security — CRITICAL
+
+1. **NEVER output `gcloud auth print-access-token`** — it exposes bearer tokens
+2. **NEVER output or log service account JSON keys**
+3. **NEVER embed credentials in code** — use Workload Identity or Application Default Credentials
+4. Use `gcloud auth application-default login` for local development
+5. In production, use Workload Identity Federation (not service account keys)
+
+## Deployment
+
+See the `deploy` skill for GCP deployment patterns (Cloud Run, GKE).
+
+## Gotchas
+
+See [references/gotchas.md](references/gotchas.md) for GCP-specific issues.

package/templates/.claude/skills/gcloud/references/gotchas.md

@@ -0,0 +1,5 @@
+# Google Cloud Gotchas
+
+<!-- This file grows over time. Each entry is added during session-end. -->
+<!-- Format: date, category, description, resolution -->
+<!-- NEVER include secret values, tokens, credentials, or project IDs here -->