@vyuhlabs/dxkit 0.6.0 → 0.8.0

package/README.md

@@ -21,61 +21,51 @@ Running `init` auto-detects your tech stack and generates a complete `.claude/`
 
 ```
 .claude/
-  settings.json          # Permissions, deny list, hooks
-  agents/                # Active agents (auto-trigger)
+  settings.json          # Permissions, deny list, learning hooks
+  agents/                # Active agents (auto-trigger on matching questions)
     knowledge-bot.md     # Answers codebase questions
     onboarding.md        # Interactive onboarding buddy
     quality-reviewer.md  # Reviews code before committing
-  agents-available/      # Dormant agents (activate on demand)
+    doc-writer.md        # Audits and writes documentation
+  agents-available/      # Dormant agents (activate with /enable-agent)
     codebase-explorer.md # Deep architecture analysis
     code-reviewer.md     # PR review and security audit
     test-writer.md       # Writes tests for existing code
+    test-gap-finder.md   # Identifies untested critical code
+    dependency-mapper.md # Maps import chains and blast radius
+    health-auditor.md    # 6-dimension codebase health audit
+    vulnerability-scanner.md # Dependency + code security scan
+    dev-report.md        # Developer activity + quality attribution
     debugger.md          # Root cause analysis
-  commands/              # Slash commands
-    ask.md               # /ask — Query the codebase
-    quality.md           # /quality — Run linters
-    test.md              # /test — Run tests with coverage
-    check.md             # /check — Full pre-commit validation
-    fix.md               # /fix — Auto-fix issues
-    learn.md             # /learn — Capture gotchas/conventions
-    onboarding.md        # /onboarding — Start onboarding
-    help.md              # /help — List everything
-    session-start.md     # /session-start — Begin dev session
-    session-end.md       # /session-end — Checkpoint + evolve skills
-    ...
+  commands/              # 24 slash commands (see below)
   skills/                # Domain knowledge
     codebase/            # Auto-generated architecture overview
     learned/             # Evolving gotchas, conventions, deny list
-    quality/             # Quality check patterns
-    ...
-  rules/                 # Path-scoped rules (per language)
+  rules/                 # Path-scoped rules (per language + framework)
 CLAUDE.md                # Main context file for Claude Code
 .ai/
   sessions/              # Session checkpoints
+  reports/               # Generated reports (health, vulnerabilities, etc.)
+.github/
+  workflows/
+    pr-review.yml        # Automated PR review (opt-in)
 ```
 
 ## Supported Languages
 
-| Language | Detection | Linters | Tests | Coverage |
-|---|---|---|---|---|
-| Node.js / TypeScript | `package.json` | ESLint, Prettier, tsc | Auto-detected (Jest, Mocha, Vitest, Ava) | framework-specific |
-| Python | `pyproject.toml`, `setup.py`, `*.py` | ruff, mypy | pytest | pytest-cov |
-| Go | `go.mod` | golangci-lint, go vet | go test | go cover |
-| C# | `*.csproj`, `*.sln` | dotnet format, Roslyn | dotnet test | coverlet |
-| Rust | `Cargo.toml` | clippy, rustfmt | cargo test | tarpaulin |
+| Language | Detection | Linters | Test Runner |
+|---|---|---|---|
+| Node.js / TypeScript | `package.json` | ESLint, Prettier, tsc | Auto-detected (Jest, Mocha, Vitest, Ava, Tap) |
+| Python | `pyproject.toml`, `setup.py`, `*.py` | ruff, mypy | pytest |
+| Go | `go.mod` | golangci-lint, go vet | go test |
+| C# | `*.csproj`, `*.sln` | dotnet format, Roslyn | dotnet test |
+| Rust | `Cargo.toml` | clippy, rustfmt | cargo test |
 
-## Supported Tools
-
-Auto-detected and integrated when present:
-
-- **Google Cloud** (gcloud) — SDK commands, security rules
-- **Infisical** — Secrets management, never-leak rules
-- **Pulumi** — IaC with preview-before-apply safety
-- **Docker** — Container commands
+Multi-language repos fully supported — detects and generates rules/commands for all languages present.
 
 ## Supported Frameworks
 
-Auto-detected with framework-specific rules:
+Auto-detected with framework-specific path-scoped rules:
 
 - **LoopBack** — Controller/model/repository patterns, decorator conventions
 - **Express** — Middleware/routing conventions, error handling patterns
@@ -83,9 +73,16 @@ Auto-detected with framework-specific rules:
 - **FastAPI**, **Django**, **Flask** — Detected (rules coming soon)
 - **Gin**, **Echo**, **Fiber** — Detected (rules coming soon)
 
-## Commands
+## Supported Tools
+
+Auto-detected and integrated when present:
+
+- **Google Cloud** (gcloud) — SDK commands, security rules
+- **Infisical** — Secrets management, never-leak rules
+- **Pulumi** — IaC with preview-before-apply safety
+- **Docker** — Container commands
 
-After init, these slash commands are available in Claude Code:
+## Commands (24)
 
 ### Development Workflow
 | Command | Description |
@@ -99,19 +96,28 @@ After init, these slash commands are available in Claude Code:
 | Command | Description |
 |---|---|
 | `/quality` | Run language-specific linters + AI review |
-| `/test` | Run tests (auto-detected runner: Jest, Mocha, Vitest, etc.) |
+| `/test` | Run tests (auto-detected runner) |
 | `/check` | Full pre-commit validation (quality + tests + AI review) |
 | `/fix` | Auto-fix formatting and lint issues |
 | `/build` | Build the project |
 | `/setup-hooks` | Install git pre-commit/pre-push hooks |
 | `/test-gaps` | Find critical untested code paths |
 
+### Analysis & Reports
+| Command | Description | Report |
+|---|---|---|
+| `/health` | 6-dimension codebase health audit | `.ai/reports/health-audit-*.md` |
+| `/vulnerabilities` | Dependency + code vulnerability scan | `.ai/reports/vulnerability-scan-*.md` |
+| `/dev-report` | Developer activity + security attribution | `.ai/reports/developer-report-*.md` |
+| `/docs audit` | Documentation gap analysis | `.ai/reports/docs-audit-*.md` |
+| `/deps` | Dependency map + blast radius | `.ai/reports/dependency-map-*.md` |
+| `/export-pdf` | Convert markdown reports to PDF | `.ai/reports/*.pdf` |
+
 ### Exploration & Onboarding
 | Command | Description |
 |---|---|
-| `/onboarding` | Interactive onboarding for new developers |
+| `/onboarding` | Interactive onboarding buddy for new developers |
 | `/explore-codebase` | Deep architecture exploration |
-| `/deps` | Map dependencies ("what breaks if I change X?") |
 | `/help` | List all commands and agents |
 
 ### Operations
@@ -124,21 +130,41 @@ After init, these slash commands are available in Claude Code:
 
 ## Agents
 
-### Active by Default
+### Active by Default (4)
 These agents auto-trigger when Claude detects a matching question:
 
 - **knowledge-bot** — "How does auth work?" "Where are payments handled?"
 - **onboarding** — "I'm new, help me get started" "What does this project do?"
 - **quality-reviewer** — "Review my changes" "Check quality before I commit"
+- **doc-writer** — "What needs documentation?" "Help me write docs"
 
-### Dormant (activate with `/enable-agent`)
+### Dormant (9) — activate with `/enable-agent`
 - **codebase-explorer** — Deep architecture analysis, generates documentation
 - **code-reviewer** — PR review and security audit (read-only)
 - **test-writer** — Writes tests for existing code
 - **test-gap-finder** — Identifies critical untested code paths, prioritized by risk
 - **dependency-mapper** — Maps import chains and blast radius of changes
+- **health-auditor** — Comprehensive codebase health audit (scores 6 dimensions)
+- **vulnerability-scanner** — Dependency + code vulnerability analysis
+- **dev-report** — Developer activity, quality patterns, security attribution
 - **debugger** — Systematic root cause analysis
 
+## Reports
+
+All analysis commands save timestamped reports to `.ai/reports/`:
+
+```bash
+.ai/reports/
+  health-audit-2026-03-30.md          # Scores: tests, quality, docs, security, DX
+  vulnerability-scan-2026-03-30.md     # CVEs, hardcoded secrets, dependency risks
+  developer-report-2026-03-30.md       # Team activity, ownership, security attribution
+  test-gaps-2026-03-30.md              # Critical untested code, prioritized by risk
+  docs-audit-2026-03-30.md             # Documentation gaps and recommendations
+  dependency-map-2026-03-30.md         # Import chains, most-depended-on files
+```
+
+Convert to PDF: `/export-pdf all` or `/export-pdf .ai/reports/health-audit-2026-03-30.md`
+
 ## Learning System
 
 DXKit includes a continuous learning system that improves over time:
@@ -146,14 +172,14 @@ DXKit includes a continuous learning system that improves over time:
 1. **Stop Hook** — After each conversation, Claude is reminded to capture learnings
 2. **`/learn` command** — Explicitly save gotchas, conventions, or things to avoid
 3. **`/session-end`** — Creates checkpoint and evolves skill files
-4. **Evolving files** — These files are append-only and never overwritten:
+4. **Evolving files** — Append-only, never overwritten even with `--force`:
    - `.claude/skills/learned/references/gotchas.md`
    - `.claude/skills/learned/references/conventions.md`
    - `.claude/skills/learned/references/deny-recommendations.md`
 
 ## PR Review Automation
 
-DXKit generates a GitHub Action (`.github/workflows/pr-review.yml`) that automatically reviews PRs using Claude Code. Enable it by:
+DXKit generates a GitHub Action that automatically reviews PRs using Claude Code:
 
 1. Set `ENABLE_AI_REVIEW=true` as a GitHub Actions variable
 2. Add `ANTHROPIC_API_KEY` to repo secrets
@@ -162,33 +188,21 @@ Reviews appear as PR comments with issues rated as critical/warning/suggestion.
 
 ## Smart Detection
 
-DXKit goes beyond language detection:
-
-- **Test runner** — Detects Jest, Mocha, Vitest, Ava, Tap, pytest, go test from package.json scripts and dependencies
-- **Framework** — Detects LoopBack, Express, NestJS, FastAPI, Gin, etc. and generates framework-specific rules
-- **Test presence** — Counts test files vs source files and warns about minimal test coverage
-- **Multi-language** — Detects Python from `.py` files even without `pyproject.toml` (common in mixed repos)
+- **Test runner** — Detects Jest, Mocha, Vitest, Ava, Tap, pytest, go test from scripts and dependencies
+- **Framework** — Detects LoopBack, Express, NestJS, FastAPI, Gin, etc. with framework-specific rules
+- **Test presence** — Counts test files vs source files, warns about minimal coverage
+- **Multi-language** — Detects all languages including Python from `.py` files (no config file required)
+- **Language breakdown** — Shows file count per language in codebase skill for accurate analysis
 
 ## CLI Reference
 
 ```bash
-# Initialize (auto-detect stack)
-npx @vyuhlabs/dxkit init --detect
-
-# Initialize (interactive)
-npx @vyuhlabs/dxkit init
-
-# Initialize (everything, no prompts)
-npx @vyuhlabs/dxkit init --full --yes
-
-# Re-generate after config changes (preserves evolved files)
-npx @vyuhlabs/dxkit update
-
-# Re-generate with codebase rescan
-npx @vyuhlabs/dxkit update --rescan
-
-# Verify setup
-npx @vyuhlabs/dxkit doctor
+npx @vyuhlabs/dxkit init --detect        # Auto-detect, minimal prompts
+npx @vyuhlabs/dxkit init                  # Interactive
+npx @vyuhlabs/dxkit init --full --yes     # Everything, no prompts
+npx @vyuhlabs/dxkit update               # Re-generate (preserves evolved files)
+npx @vyuhlabs/dxkit update --rescan      # Re-run codebase analysis
+npx @vyuhlabs/dxkit doctor               # Verify setup
 ```
 
 ### Init Options
@@ -203,56 +217,44 @@ npx @vyuhlabs/dxkit doctor
 | `--name <n>` | Override project name |
 | `--no-scan` | Skip codebase analysis |
 
-## Example: Adding to an Existing Node.js Project
+## Example: Node.js/TypeScript Project
 
 ```bash
-cd my-express-app
+cd my-loopback-app
 npx @vyuhlabs/dxkit init --detect --yes
 ```
 
-This generates:
-- `CLAUDE.md` with Node.js-specific context
-- `.claude/commands/quality.md` with `npx eslint .` and `npx tsc --noEmit`
-- `.claude/commands/test.md` with auto-detected test runner and framework
-- `.claude/rules/` with Node.js + framework-specific conventions
-- `.claude/skills/codebase/SKILL.md` with auto-scanned architecture overview
-- `.github/workflows/pr-review.yml` for automated PR review
-- 3 active agents + 7 dormant agents
+Output:
+```
+✓ Languages: node
+✓ Framework: loopback
+✓ Tests: mocha (npm test)
+✓ Created: 61 files
+```
 
 Then in Claude Code:
 ```
-/help                              # See everything available
-/ask How does the auth middleware work?  # Ask about the codebase
-/quality                           # Run ESLint + TypeScript checks
-/onboarding                        # Get oriented as a new developer
+/help                                    # See everything
+/ask How does the auth middleware work?   # Codebase Q&A
+/health                                  # Full health audit
+/vulnerabilities                         # Security scan
+/dev-report                              # Team activity report
+/quality                                 # ESLint + AI review
+/onboarding                              # New developer guide
 ```
 
-## Example: Adding to a Python + Go Monorepo
+## Example: Multi-Language Repo (Python + Go + TypeScript)
 
 ```bash
 cd my-monorepo
 npx @vyuhlabs/dxkit init --detect --yes
 ```
 
-Detects both languages and generates:
-- Quality commands with ruff + mypy (Python) and golangci-lint (Go)
-- Test commands with pytest + go test
-- Path-scoped rules for both `.py` and `.go` files
-- Language-specific coverage enforcement
-
-## How It Works
-
-1. **Detection** — Scans for config files (`package.json`, `go.mod`, `pyproject.toml`, etc.) to determine languages and tools
-2. **Template Processing** — Processes `.md.template` files through a conditional template engine, stripping irrelevant language sections
-3. **Codebase Scanning** — Analyzes source files to find entry points, API routes, test patterns, and conventions
-4. **Generation** — Writes files non-destructively (never overwrites without `--force`, evolving files always preserved)
-5. **Manifest** — Saves state to `.vyuh-dxkit.json` for `update` and `doctor` commands
-
-## Non-Destructive by Design
-
-- Files that already exist are **skipped** (use `--force` to overwrite)
-- Evolving files (`gotchas.md`, `conventions.md`, `deny-recommendations.md`) are **never overwritten**, even with `--force`
-- The manifest (`.vyuh-dxkit.json`) tracks what was generated for safe updates
+Generates:
+- Quality commands with `npx eslint .` + `ruff check .` + `golangci-lint run`
+- Test commands with `npm test` + `pytest` + `go test`
+- Path-scoped rules for `.ts`, `.py`, and `.go` files
+- Language breakdown in codebase skill: "TypeScript: 200, Python: 50, Go: 30"
 
 ## AI-Assisted Development Workflow
 
@@ -262,11 +264,20 @@ git checkout -b feature/my-feature      # Create branch
 /ask How does the payment flow work?    # Understand the code
 # ... develop with full context ...
 /quality                                # Lint + AI review
-/test                                   # Tests with coverage
+/test                                   # Tests
+/learn auth tokens expire after 24h     # Capture gotcha
 git add -A && git commit                # Commit
 /session-end                            # Checkpoint + evolve skills
 ```
 
+## How It Works
+
+1. **Detection** — Scans for config files, source files, and tools to determine languages, frameworks, and test runners
+2. **Template Processing** — Processes `.md.template` files through a conditional engine, generating language-specific commands
+3. **Codebase Scanning** — Analyzes source files to find entry points, API routes (including LoopBack/Express/FastAPI decorators), test patterns, and language breakdown
+4. **Generation** — Writes 60+ files non-destructively (never overwrites without `--force`, evolving files always preserved)
+5. **Manifest** — Saves state to `.vyuh-dxkit.json` for `update` and `doctor` commands
+
 ## License
 
 MIT

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 import { ResolvedConfig } from './types';
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.8.0";
 export declare const DEFAULT_VERSIONS: {
     python: string;
     go: string;

package/dist/constants.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EVOLVING_FILES = exports.DEFAULT_COVERAGE = exports.DEFAULT_VERSIONS = exports.VERSION = void 0;
 exports.buildVariables = buildVariables;
 exports.buildConditions = buildConditions;
-exports.VERSION = '0.6.0';
+exports.VERSION = '0.8.0';
 exports.DEFAULT_VERSIONS = {
     python: '3.12',
     go: '1.24.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "AI-native developer experience toolkit for any repository",
   "license": "MIT",
   "bin": {

package/templates/.claude/agents-available/dev-report.md

@@ -0,0 +1,104 @@
+---
+name: dev-report
+description: Generates developer activity and code quality reports from git history. Use when asked about "developer report", "who introduced this bug?", "contribution analysis", or "team activity". Saves report to .ai/reports/.
+model: sonnet
+tools: Read, Grep, Glob, Bash, Write
+---
+
+You are a developer activity analyst. Your job is to generate insightful reports about developer contributions, code quality patterns, and areas of ownership.
+
+## Report Types
+
+### 1. Team Overview (default)
+When asked for a general report or "developer report":
+
+Run these commands to gather data:
+- `git shortlog -sn --no-merges --since="3 months ago"` — commit counts per developer
+- `git log --since="3 months ago" --pretty=format:"%an|%s" --no-merges` — recent commits
+- `git log --since="3 months ago" --pretty=format:"%an" --no-merges | sort | uniq -c | sort -rn` — activity ranking
+
+For each active developer, analyze:
+- **Areas of ownership**: `git log --author="Name" --since="3 months ago" --name-only --pretty=format:"" | sort | uniq -c | sort -rn | head -20`
+- **Commit patterns**: feature vs fix vs refactor ratio
+- **Files most touched**: potential hotspots
+
+### 2. Individual Developer Report
+When asked about a specific developer:
+
+- `git log --author="Name" --since="6 months ago" --stat --no-merges` — their commits with stats
+- `git log --author="Name" --since="6 months ago" --pretty=format:"%H" --no-merges` — commit hashes
+- For each recent commit, check the diff for:
+  - Quality issues introduced (hardcoded values, missing error handling, TODOs)
+  - Security concerns (secrets, eval, exec, SQL concatenation)
+  - Test coverage (did they add tests with features?)
+
+### 3. Code Quality by Developer
+Cross-reference git blame with known issues:
+
+- For files with known vulnerabilities (from `/vulnerabilities` report if available in `.ai/reports/`):
+  - `git blame <file>` on the problematic lines
+  - Identify who introduced the issue and when
+- For files with no tests:
+  - Who last modified them? They should write the tests.
+
+## Output Format
+
+Save to `.ai/reports/developer-report-YYYY-MM-DD.md`:
+
+```markdown
+## Developer Activity Report
+Generated: YYYY-MM-DD | Period: last 3 months
+
+### Team Summary
+| Developer | Commits | Files Changed | Primary Areas |
+|-----------|---------|--------------|---------------|
+| Alice | 45 | 120 | controllers, services |
+| Bob | 30 | 80 | models, migrations |
+
+### Activity by Developer
+
+#### Alice (45 commits)
+**Areas of ownership:**
+- src/controllers/ (25 commits)
+- src/services/ (12 commits)
+
+**Commit breakdown:**
+- Features: 20 | Fixes: 15 | Refactors: 8 | Docs: 2
+
+**Quality observations:**
+- Added tests in 8/20 feature commits (40%)
+- 2 commits introduced TODOs without linked issues
+- No security concerns in recent changes
+
+**Notable contributions:**
+- Implemented auth middleware (commit abc123)
+- Fixed payment race condition (commit def456)
+
+---
+
+### Code Quality Hotspots
+Files with most churn (frequent changes = potential instability):
+| File | Changes (3mo) | Last Author | Concern |
+|------|--------------|-------------|---------|
+| src/server.ts | 12 changes | Multiple | High churn, complex file |
+
+### Security Attribution
+Issues from vulnerability scan attributed to authors:
+| Issue | File:Line | Introduced by | When |
+|-------|-----------|--------------|------|
+| Hardcoded secret | keys.ts:18 | Bob | 2025-06-15 |
+
+### Recommendations
+1. [Team-level recommendations]
+2. [Per-developer suggestions]
+```
+
+## Important Guidelines
+
+- **Be constructive, not punitive** — the goal is to improve, not blame
+- **Context matters** — a developer may have inherited bad code
+- **Use git blame carefully** — the last modifier isn't always the author of the problem
+- **Focus on patterns** — one missed test is noise; consistently missing tests is a pattern
+- **Respect privacy** — this report may be sensitive; don't include in public repos
+- **Never output secrets** found in git history
+- Save report to `.ai/reports/developer-report-YYYY-MM-DD.md`

package/templates/.claude/commands/dev-report.md

@@ -0,0 +1,14 @@
+---
+description: Generate developer activity and code quality report from git history
+---
+
+Delegate to the **dev-report** agent. It analyzes git history to generate reports on developer contributions, code quality patterns, and security attribution.
+
+**Saves report to `.ai/reports/developer-report-YYYY-MM-DD.md`**
+
+Examples:
+- `/dev-report` — Team overview (last 3 months)
+- `/dev-report Alice` — Individual developer report
+- `/dev-report security` — Who introduced known security issues
+
+$ARGUMENTS

package/templates/.claude/commands/export-pdf.md

@@ -0,0 +1,30 @@
+---
+description: Convert a markdown report to PDF
+argument-hint: "[file-path or 'all' for all reports]"
+---
+
+Convert markdown report(s) to PDF.
+
+## Arguments
+- `$ARGUMENTS`
+- If empty or "all", convert all reports in `.ai/reports/`
+- If a file path, convert that specific file
+
+## How to Convert
+
+Try these tools in order (use whichever is available):
+
+1. **md-to-pdf** (Node.js): `npx md-to-pdf <file.md>` — creates `<file.pdf>` alongside it
+2. **pandoc**: `pandoc <file.md> -o <file.pdf> --pdf-engine=wkhtmltopdf`
+3. **If neither is available**, install md-to-pdf: `npx md-to-pdf <file.md>`
+
+## For "all" reports
+```
+for f in .ai/reports/*.md; do
+  npx md-to-pdf "$f"
+done
+```
+
+## Output
+- PDFs are saved alongside the markdown files in `.ai/reports/`
+- Report which files were converted and their paths

package/templates/CLAUDE.md.template

@@ -160,7 +160,9 @@ Slash commands for common workflows. Run `/help` to list all with descriptions.
 - `/deps` - Map dependencies ("what breaks if I change X?")
 - `/health` - Comprehensive codebase health audit
 - `/vulnerabilities` - Scan dependencies and code for security issues
+- `/dev-report` - Developer activity and code quality report
 - `/docs` - Audit, write, or improve documentation
+- `/export-pdf` - Convert markdown reports to PDF
 - `/fix-issue <number>` - Investigate and fix a GitHub issue
 
 ### Rules (`.claude/rules/`)
@@ -181,6 +183,7 @@ Language-specific conventions that activate automatically when editing matching
 - `dependency-mapper` — Maps import chains and blast radius (sonnet, read-only)
 - `health-auditor` — Comprehensive codebase health audit (sonnet, read-only)
 - `vulnerability-scanner` — Dependency and code vulnerability analysis (sonnet)
+- `dev-report` — Developer activity, quality patterns, security attribution (sonnet)
 - `doc-writer` — Audits docs, identifies gaps, writes/improves documentation (sonnet)
 - `debugger` — Traces root causes systematically (sonnet, no file edits)