@vyuhlabs/dxkit 0.1.0

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

@@ -0,0 +1,55 @@
+---
+name: learned
+description: Project-specific learnings, gotchas, and conventions discovered during development. Check this before starting any task for accumulated team knowledge.
+---
+
+# Learned Patterns & Gotchas
+
+This skill accumulates project-specific knowledge over time.
+It is updated during session-end checkpoints.
+
+## How This Works
+
+1. During `make session-end`, the checkpoint process reviews the session
+2. Any new gotchas, patterns, or conventions are appended to the reference files
+3. Over time, this becomes the most valuable skill — real failure points and patterns
+
+## Files
+
+- [references/gotchas.md](references/gotchas.md) - Accumulated gotchas and edge cases (append-only)
+- [references/conventions.md](references/conventions.md) - Team conventions discovered during development
+- [references/deny-recommendations.md](references/deny-recommendations.md) - Commands that should be added to `.claude/settings.json` deny list (requires human review)
+
+## When to Update
+
+Update these files when you encounter:
+- Unexpected behaviors or edge cases
+- Workarounds for tool/framework bugs
+- Team conventions or patterns that aren't obvious from the code
+- Configuration pitfalls
+- Deployment or environment-specific issues
+
+## When to Create a New Skill
+
+If a learning is significant enough to warrant its own skill (e.g., a specific API integration, a migration workflow, a caching pattern), create a new directory under `.claude/skills/<name>/` with a `SKILL.md` instead of appending here. This skill (`learned`) is for general cross-cutting knowledge; domain-specific knowledge deserves its own skill.
+
+## Format
+
+### Gotchas
+```markdown
+## YYYY-MM-DD - Category / Short Title
+Description of the issue.
+**Resolution:** How it was resolved.
+```
+
+### Conventions
+```markdown
+## Category - Convention Name
+Description of the convention.
+**Rationale:** Why this convention was adopted.
+```
+
+## Security
+
+**NEVER include secret values, tokens, passwords, or API keys in any file under this skill.**
+If a gotcha involves credentials, describe the issue generically without exposing actual values.

package/templates/.claude/skills/learned/references/conventions.md

@@ -0,0 +1,11 @@
+# Team Conventions
+
+<!-- Discovered conventions are added here during session-end. -->
+<!-- Format: category, convention, rationale -->
+<!-- NEVER include secret values, tokens, or credentials here -->
+
+<!-- Example:
+## Python - Use App Factory Pattern
+All FastAPI applications should use the app factory pattern (create_app function) rather than module-level app instantiation.
+**Rationale:** Enables test isolation and configuration flexibility. Adopted after test pollution issues in the auth service.
+-->

package/templates/.claude/skills/learned/references/deny-recommendations.md

@@ -0,0 +1,18 @@
+# Deny Rule Recommendations
+
+<!--
+  This file tracks commands/actions that SHOULD be added to .claude/settings.json deny list.
+  Claude cannot modify settings.json directly (security boundary).
+  A developer should periodically review this file and promote entries to settings.json.
+
+  Format:
+  ## YYYY-MM-DD - Rule
+  `DenyPattern` — reason this should be blocked
+  **Context:** what happened that surfaced this need
+-->
+
+<!-- Example:
+## 2025-12-15 - Block database drop
+`Bash(dropdb:*)` — accidentally dropped staging database during cleanup
+**Context:** Claude ran dropdb instead of truncating tables during test cleanup
+-->

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

@@ -0,0 +1,11 @@
+# Project 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 -->
+
+<!-- Example:
+## 2025-12-15 - Python / Import Order
+ruff's isort rules conflict with local imports when using relative paths in the src/ directory.
+**Resolution:** Use absolute imports from package root (e.g., `from mypackage.module import X`).
+-->

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

@@ -0,0 +1,67 @@
+---
+name: pulumi
+description: Pulumi infrastructure as code — stacks, previews, deployments, config. Use when asked about IaC, Pulumi, cloud resources, infrastructure provisioning, or stack management.
+---
+
+# Pulumi (Infrastructure as Code)
+
+## Setup
+- **Auth:** `pulumi login` (configured during `make setup`)
+- **SDK:** Installed via devcontainer post-create script
+- **Path:** `~/.pulumi/bin/pulumi`
+
+## Core Workflow
+
+**ALWAYS preview before applying changes:**
+
+```bash
+# 1. Preview changes (safe, read-only)
+pulumi preview
+
+# 2. Review the diff carefully
+
+# 3. Apply changes (REQUIRES explicit user confirmation)
+pulumi up
+
+# 4. Check outputs
+pulumi stack output
+```
+
+## Common Commands
+
+### Stack Management
+```bash
+pulumi stack ls                    # list stacks
+pulumi stack select <name>         # switch stack
+pulumi stack output                # view outputs
+pulumi stack export                # export state
+```
+
+### Configuration
+```bash
+pulumi config                     # view config
+pulumi config set key value       # set plain config
+pulumi config set --secret key value  # set encrypted secret
+pulumi config get key             # get value
+```
+
+### State & History
+```bash
+pulumi stack history              # deployment history
+pulumi state                      # inspect state
+pulumi refresh                    # sync state with cloud
+```
+
+## Security — CRITICAL
+
+1. **ALWAYS `pulumi preview` before `pulumi up`** — review the diff
+2. **NEVER run `pulumi destroy` without explicit user confirmation** — it deletes all resources
+3. **Use `pulumi config set --secret`** for sensitive values — never plain-text
+4. **NEVER output `pulumi config get --secret`** values in responses
+5. **State files may contain secrets** — ensure backend is secure (encrypted)
+6. Pulumi passphrase (if using local backend) should be in `.env`, never hardcoded
+
+## Integration
+
+- Secrets from Infisical can be used as Pulumi config values
+- GCP project from `.env` (`GOOGLE_CLOUD_PROJECT`) can configure Pulumi GCP provider

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

@@ -0,0 +1,108 @@
+---
+name: quality
+description: Run code quality checks, linting, formatting, and auto-fixing. Use when asked to check code quality, fix lint errors, format code, or run pre-commit checks.
+---
+
+# Code Quality
+
+## Commands
+- `make quality` - Run all quality checks (report: `tmp/reports/quality-report.md`)
+- `make quality-fix` - Auto-fix all fixable issues
+- `make lint` - Lint only
+- `make format` - Format all code
+- `make fix` - Fix + format (shorthand)
+- `make check` - Full pre-commit check (validate + quality + test)
+- `make format-check` - Check formatting without modifying
+
+## Quality Presets
+- `make quality-strict` - 90% coverage, all checks
+- `make quality-standard` - 80% coverage (default)
+- `make quality-relaxed` - 50% coverage
+- `make quality-off` - Disable checks
+- `make quality-config` - Show current settings
+
+{{#IF_PYTHON}}
+## Python
+
+**Tools:** ruff (lint + format), mypy (types)
+**Config:** `ruff.toml`, `pyproject.toml`
+**Script:** `.project/scripts/quality/lint-python.sh`
+
+Common fixes:
+```bash
+ruff check --fix .
+ruff format .
+mypy src/
+```
+
+Key ruff rules: pycodestyle (E), pyflakes (F), isort (I), mccabe (C90), bugbear (B).
+Per-file ignores configured in `ruff.toml` for tests (assertions, fixtures).
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+## Go
+
+**Tools:** golangci-lint (27 linters), gofmt, goimports
+**Config:** `.golangci.yml`
+**Script:** `.project/scripts/quality/lint-go.sh`
+
+Common fixes:
+```bash
+gofmt -w .
+goimports -w .
+golangci-lint run --fix
+```
+{{/IF_GO}}
+
+{{#IF_NODE}}
+## Node.js
+
+**Tools:** ESLint, Prettier
+Common fixes:
+```bash
+npx prettier --write .
+npx eslint --fix .
+```
+{{/IF_NODE}}
+
+{{#IF_NEXTJS}}
+## Next.js
+
+**Directory:** `frontend/`
+```bash
+cd frontend && npm run lint
+cd frontend && npx prettier --write .
+cd frontend && npx tsc --noEmit  # type check
+```
+{{/IF_NEXTJS}}
+
+{{#IF_RUST}}
+## Rust
+
+**Tools:** clippy, rustfmt
+```bash
+cargo fmt
+cargo clippy --fix --allow-dirty
+```
+{{/IF_RUST}}
+
+{{#IF_CSHARP}}
+## C#
+
+**Tools:** dotnet format, Roslyn Analyzers, StyleCop Analyzers
+**Config:** `.editorconfig`, `Directory.Build.props`
+
+Common fixes:
+```bash
+dotnet format                          # auto-fix formatting
+dotnet format --verify-no-changes      # CI check (no modifications)
+```
+{{/IF_CSHARP}}
+
+## Gotchas
+
+See [references/gotchas.md](references/gotchas.md) for known quality issues.
+
+## Security
+
+Never disable security-related lint rules. If a rule seems wrong, investigate before suppressing.

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

@@ -0,0 +1,5 @@
+# Quality 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/review/SKILL.md.template

@@ -0,0 +1,73 @@
+---
+name: review
+description: Review code for quality, security, and patterns. Use when asked to review code, a PR, check for problems, or audit for security issues.
+---
+
+# Code Review
+
+## Quick Check
+Run `make check` first — it validates, lints, tests, and checks docs in one command.
+
+## Review Checklist
+
+### 1. Quality
+- [ ] `make quality` passes
+- [ ] Coverage meets threshold ({{COVERAGE_THRESHOLD}}%)
+- [ ] No suppressed lint rules without justification
+
+### 2. Security
+- [ ] No hardcoded secrets, API keys, tokens, or passwords
+- [ ] No secrets in commit messages, comments, or logs
+- [ ] User input is validated/sanitized at system boundaries
+- [ ] No SQL injection, XSS, or command injection vectors
+- [ ] Sensitive files are gitignored (`.env`, credentials)
+
+### 3. Testing
+- [ ] New features have tests
+- [ ] Edge cases and error paths tested
+- [ ] Tests are deterministic (no timing/order dependencies)
+
+### 4. Architecture
+- [ ] Follows existing patterns in the codebase
+- [ ] Dependencies injected (not imported directly in business logic)
+- [ ] Error handling is consistent
+
+{{#IF_PYTHON}}
+### Python-Specific
+- [ ] Type hints on public functions
+- [ ] Pydantic models for data validation
+- [ ] No bare `except:` — catch specific exceptions
+- [ ] Async/await used correctly (no blocking in async context)
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+### Go-Specific
+- [ ] Errors checked and handled (no `_` for errors)
+- [ ] Context propagated through call chains
+- [ ] Proper resource cleanup (defer for Close/Unlock)
+- [ ] Table-driven tests used where appropriate
+{{/IF_GO}}
+
+{{#IF_NEXTJS}}
+### Next.js-Specific
+- [ ] Server vs client components used correctly
+- [ ] No sensitive data in client components
+- [ ] TypeScript strict mode compliance
+{{/IF_NEXTJS}}
+
+{{#IF_CSHARP}}
+### C#-Specific
+- [ ] Nullable reference types enabled (`#nullable enable`)
+- [ ] Async/await used correctly (no blocking on async with `.Result` or `.Wait()`)
+- [ ] IDisposable resources properly disposed (`using` statements)
+- [ ] LINQ used appropriately (not in hot paths without reason)
+- [ ] Dependency injection used (no `new` for services)
+- [ ] No hardcoded connection strings
+{{/IF_CSHARP}}
+
+## Common Issues
+- Missing error handling
+- Hardcoded configuration (should use `.env` or config)
+- Missing tests for edge cases
+- Inconsistent naming conventions
+- Overly broad error catching

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

@@ -0,0 +1,123 @@
+---
+name: scaffold
+description: Scaffold new code — services, packages, modules, components. Use when asked to create new files, modules, project structure, or boilerplate.
+---
+
+# Code Scaffolding
+
+## Project Structure
+- `.project.yaml` - Central config (edit via `make config`, view via `make info`)
+- `.project/` - Framework tooling and scripts
+- `.ai/` - AI session management and checkpoints
+
+## Language Management
+- `make lang-list` - Show enabled languages
+- `make lang-add LANG=<name>` - Enable a language
+- `make lang-remove LANG=<name>` - Disable a language
+- `make sync` - Sync `.project.yaml` to language config files
+- `make sync-preview` - Preview sync changes (dry run)
+
+{{#IF_PYTHON}}
+## Python Structure
+```
+services/python/<service-name>/
+├── pyproject.toml
+├── src/
+│   ├── __init__.py
+│   ├── app.py          # Entry point / app factory
+│   ├── models.py       # Data models (Pydantic)
+│   └── routes.py       # API endpoints (if web)
+└── tests/
+    ├── __init__.py
+    └── test_app.py
+```
+
+**Patterns:**
+- FastAPI for web APIs (app factory pattern)
+- Pydantic for data validation
+- pytest for testing
+- See `.template/examples/python-api/` and `.template/examples/python-cli/` for reference
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+## Go Structure
+```
+services/go/<service-name>/
+├── go.mod
+├── main.go             # Entry point
+├── handlers.go         # HTTP handlers
+├── handlers_test.go    # Handler tests
+└── internal/           # Private packages
+```
+
+**Patterns:**
+- Standard library `net/http` for HTTP
+- `httptest` for handler testing
+- See `.template/examples/go-service/` for reference
+{{/IF_GO}}
+
+{{#IF_NEXTJS}}
+## Next.js Structure
+```
+frontend/
+├── src/
+│   ├── app/            # App Router pages
+│   ├── components/     # React components
+│   └── lib/            # Utilities
+├── public/             # Static assets
+├── package.json
+└── tsconfig.json
+```
+{{/IF_NEXTJS}}
+
+{{#IF_NODE}}
+## Node.js Structure
+```
+services/node/<service-name>/
+├── package.json
+├── tsconfig.json
+├── src/
+│   └── index.ts
+└── tests/
+    └── index.test.ts
+```
+{{/IF_NODE}}
+
+{{#IF_RUST}}
+## Rust Structure
+```
+services/rust/<service-name>/
+├── Cargo.toml
+├── src/
+│   ├── main.rs         # Binary entry
+│   └── lib.rs          # Library code
+└── tests/
+    └── integration.rs
+```
+{{/IF_RUST}}
+
+{{#IF_CSHARP}}
+## C# Structure
+```
+src/<ProjectName>/
+├── <ProjectName>.csproj
+├── Program.cs
+├── Controllers/      # API controllers
+├── Models/           # Data models
+├── Services/         # Business logic
+└── appsettings.json  # Configuration
+tests/<ProjectName>.Tests/
+├── <ProjectName>.Tests.csproj
+└── UnitTests/
+```
+
+**Patterns:**
+- ASP.NET Core for web APIs (minimal APIs or controllers)
+- Entity Framework Core for data access
+- xUnit + Moq for testing
+{{/IF_CSHARP}}
+
+## After Scaffolding
+1. Run `make sync` to update config files
+2. Run `make doctor` to verify setup
+3. Run `make test` to confirm everything works

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

@@ -0,0 +1,45 @@
+---
+name: secrets
+description: Manage secrets via Infisical. Use when asked about secrets, environment variables, API keys, .env configuration, or credential management.
+---
+
+# Secrets Management (Infisical)
+
+## Commands
+- `make secrets-pull` - Pull secrets from Infisical to `.env`
+- `make secrets-show` - Show Infisical configuration (**no secrets displayed**)
+- `make setup` - Configure Infisical during initial setup
+
+## How It Works
+1. Infisical stores secrets centrally (encrypted, access-controlled)
+2. `make secrets-pull` fetches secrets and merges into `.env`
+3. `.env` is gitignored — **never commit secrets**
+
+## Configuration
+Required in `.env` (set during `make setup`):
+- `INFISICAL_TOKEN` - Authentication token
+- `INFISICAL_PROJECT_ID` - Project identifier
+- `INFISICAL_ENV` - Environment (default: `dev`)
+
+## Checking Configuration
+Always use `make secrets-show` — it displays config keys without values:
+```
+INFISICAL_PROJECT_ID=abc123
+INFISICAL_ENV=dev
+INFISICAL_TOKEN=***configured***
+```
+
+## Security — CRITICAL
+
+1. **NEVER read `.env` directly** — it contains plain-text secrets
+2. **NEVER output secret values** in responses, logs, or commit messages
+3. **NEVER include secrets** in session checkpoints or skill files
+4. **NEVER pass secrets as CLI arguments** — they appear in process lists
+5. **NEVER commit** `.env`, `.env.*`, or `.env.secrets`
+6. Use `make secrets-show` to verify configuration without exposing values
+7. If a secret is accidentally exposed, rotate it immediately
+
+## Troubleshooting
+- Token expired → re-authenticate via `make setup`
+- Pull fails → check `make secrets-show` for config, verify token permissions
+- Missing env var → check if it exists in Infisical project, correct environment

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

@@ -0,0 +1,43 @@
+---
+name: session
+description: Manage AI development sessions — start, checkpoint, commit, push, create PRs. Use when asked about session workflow, checkpoints, or development workflow.
+---
+
+# Session Management
+
+## Workflow
+1. `make session-start` - Start session (finds last checkpoint, generates prompts)
+2. Work on your task using step-by-step development
+3. `make session-end` - Create checkpoint document
+4. `make session-commit` - Commit with quality checks
+5. `make session-push` - Push to remote
+6. `make session-pr` - Create PR with auto-generated content
+
+## Key Files
+- `.ai/prompts/session-start.md` - Planning prompt template
+- `.ai/prompts/session-end.md` - Checkpoint creation guide
+- `.ai/prompts/step-by-step.md` - Step-by-step development guide
+- `.ai/templates/session-checkpoint-template.md` - Checkpoint structure
+
+## Checkpoints
+- Stored in: `.ai/sessions/<developer>/<date>/session-<N>.md`
+- Auto-numbered per day
+- Include: accomplishments, files, decisions, next steps, AI context
+
+## Checkpoint Quality
+A good checkpoint is specific, not vague:
+- **Bad:** "worked on the client"
+- **Good:** "Implemented PolygonClient with 3 endpoints, added 15 unit tests, all passing"
+
+## Skill Evolution (during session-end)
+After creating the checkpoint, review the session for learnings:
+- Append gotchas to `.claude/skills/learned/references/gotchas.md`
+- Append conventions to `.claude/skills/learned/references/conventions.md`
+- Update area-specific gotchas in `.claude/skills/<area>/references/gotchas.md`
+- **Create new skills** if a distinct domain/workflow emerged (new `.claude/skills/<name>/SKILL.md`)
+
+**NEVER include secret values in checkpoints or skill files.**
+
+## Tips
+- `SKIP_VERIFY=1` on session-commit/push to bypass quality checks for WIP
+- `BASE=main` on session-pr to override base branch

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

@@ -0,0 +1,109 @@
+---
+name: test
+description: Run tests, check coverage, debug test failures. Use when asked to run tests, write tests, investigate test failures, or check coverage.
+---
+
+# Testing
+
+## Commands
+- `make test` - Run all tests (report: `tmp/reports/test-report.md`)
+- `make test-unit` - Fast unit tests only (no coverage)
+- `make test-quick` - Alias for test-unit
+- `make test-integration` - Integration tests only
+- `make test-coverage` - Detailed coverage report
+- Coverage threshold: **{{COVERAGE_THRESHOLD}}%**
+
+{{#IF_PYTHON}}
+## Python
+
+**Framework:** pytest (config: `pytest.ini`, `pyproject.toml`)
+**Coverage:** pytest-cov
+**Pattern:** `tests/` directories alongside source
+
+```bash
+pytest tests/ -v                    # run all
+pytest tests/test_foo.py -v         # run specific
+pytest tests/ -k "test_name" -v    # run by name
+pytest tests/ --cov=src --cov-report=term-missing  # with coverage
+```
+
+Writing tests:
+- Use fixtures for setup/teardown
+- Use `@pytest.mark.parametrize` for data-driven tests
+- Mock external dependencies with `unittest.mock` or `pytest-mock`
+- Use dependency injection for testability
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+## Go
+
+**Framework:** `go test`
+**Coverage:** `go test -coverprofile`
+**Pattern:** `_test.go` files alongside source
+
+```bash
+go test ./... -v                          # run all
+go test ./pkg/mypackage/ -v               # run specific
+go test ./... -run TestName -v            # run by name
+go test ./... -coverprofile=coverage.out  # with coverage
+go tool cover -html=coverage.out          # view coverage
+```
+
+Writing tests:
+- Use table-driven tests for multiple cases
+- Use `httptest` for HTTP handler tests
+- Use `testify/assert` if available, otherwise standard `testing`
+{{/IF_GO}}
+
+{{#IF_NEXTJS}}
+## Next.js
+
+**Framework:** Jest (if configured)
+**Directory:** `frontend/`
+
+```bash
+cd frontend && npm test
+cd frontend && npm test -- --coverage
+```
+{{/IF_NEXTJS}}
+
+{{#IF_RUST}}
+## Rust
+
+```bash
+cargo test                    # run all
+cargo test test_name          # run specific
+cargo test -- --nocapture     # show output
+```
+{{/IF_RUST}}
+
+{{#IF_CSHARP}}
+## C#
+
+**Framework:** xUnit (preferred), NUnit, MSTest
+**Coverage:** coverlet
+**Pattern:** `*.Tests` projects alongside source
+
+```bash
+dotnet test                                              # run all
+dotnet test --filter "FullyQualifiedName~TestName"       # run specific
+dotnet test --collect:"XPlat Code Coverage"              # with coverage
+```
+
+Writing tests:
+- Use `[Fact]` for single assertions, `[Theory]` with `[InlineData]` for data-driven
+- Use dependency injection + mocking (Moq, NSubstitute)
+- Follow Arrange-Act-Assert pattern
+{{/IF_CSHARP}}
+
+## Writing Tests
+
+- Every new feature should include tests
+- Aim for coverage threshold ({{COVERAGE_THRESHOLD}}%)
+- Use dependency injection for mockability
+- Test edge cases and error paths, not just happy paths
+- Integration tests go in separate directories/files from unit tests
+
+## Gotchas
+
+See [references/gotchas.md](references/gotchas.md) for known test issues.

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

@@ -0,0 +1,5 @@
+# Test 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 -->