@vyuhlabs/dxkit 0.11.1 → 1.0.1

package/README.md

@@ -84,7 +84,7 @@ Auto-detected and integrated when present:
 - **Pulumi** — IaC with preview-before-apply safety
 - **Docker** — Container commands
 
-## Commands (26)
+## Commands (28)
 
 ### Development Workflow
 | Command | Description |
@@ -105,7 +105,7 @@ Auto-detected and integrated when present:
 | `/test-gaps` | Find critical untested code paths |
 
 ### Analysis & Reports
-| Command | Description | Report |
+| Command | Description | Output |
 |---|---|---|
 | `/health` | 6-dimension codebase health audit | `.ai/reports/health-audit-*.md` |
 | `/vulnerabilities` | CWE-classified security scan (Snyk-comparable) | `.ai/reports/vulnerability-scan-*.md` |
@@ -115,6 +115,12 @@ Auto-detected and integrated when present:
 | `/dashboard` | Generate HTML dashboard from all reports | `.ai/reports/dashboard.html` |
 | `/export-pdf` | Convert markdown reports to PDF | `.ai/reports/*.pdf` |
 
+### Planning & Execution
+| Command | Description | Output |
+|---|---|---|
+| `/plan` | Analyze reports → propose KPIs → generate improvement plans | `.ai/plans/` |
+| `/execute-plan <name>` | Execute a plan task by task with session checkpoints | `.ai/plans/progress/`, `.ai/sessions/` |
+
 ### Exploration & Onboarding
 | Command | Description |
 |---|---|
@@ -142,7 +148,7 @@ These agents auto-trigger when Claude detects a matching question:
 - **quality-reviewer** — "Review my changes" "Check quality before I commit"
 - **doc-writer** — "What needs documentation?" "Help me write docs"
 
-### Dormant (12) — activate with `/enable-agent`
+### Dormant (14) — 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
@@ -152,6 +158,8 @@ These agents auto-trigger when Claude detects a matching question:
 - **vulnerability-scanner** — CWE-classified security scan with Snyk-comparable depth
 - **dev-report** — Developer activity, quality patterns, security attribution
 - **dashboard-builder** — Generates HTML dashboard from all reports
+- **strategic-planner** — Analyzes reports, proposes KPIs, generates improvement plans
+- **plan-executor** — Executes plans task by task with session checkpoints
 - **hooks-configurator** — Configures scoped git hooks from DXKit commands
 - **debugger** — Systematic root cause analysis
 
@@ -304,7 +312,32 @@ Generates:
 - Path-scoped rules for `.ts`, `.py`, and `.go` files
 - Language breakdown in codebase skill: "TypeScript: 200, Python: 50, Go: 30"
 
-## AI-Assisted Development Workflow
+## Full Workflow: Reports → KPIs → Plans → Execution
+
+```
+# 1. Init DXKit
+npx @vyuhlabs/dxkit init --detect --yes
+
+# 2. Generate reports
+/health                                 # Codebase health (6 dimensions)
+/vulnerabilities                        # Security scan (CWE-classified)
+/test-gaps                              # Untested critical code
+/dev-report                             # Team activity
+
+# 3. Generate improvement plans from reports
+/plan                                   # Propose KPIs + actionable plans
+
+# 4. Execute plans with session management
+/execute-plan security                  # Work through security fixes
+/execute-plan test-coverage             # Add tests to critical paths
+
+# 5. Track progress
+/dashboard                              # HTML dashboard with all reports
+```
+
+Each plan execution uses the session framework — checkpoints, skill evolution, progress tracking.
+
+## Daily Development Workflow
 
 ```
 /session-start                          # Load context, plan work

package/dist/constants.d.ts

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

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,eAAO,MAAM,OAAO,WAAW,CAAC;AAEhC,eAAO,MAAM,gBAAgB;;;;;;;;CAQ5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,cAAc,UAU1B,CAAC;AAEF,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgC7E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuB/E"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,eAAO,MAAM,gBAAgB;;;;;;;;CAQ5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,cAAc,UAU1B,CAAC;AAEF,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgC7E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuB/E"}

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.11.1';
+exports.VERSION = '1.0.1';
 exports.DEFAULT_VERSIONS = {
     python: '3.12',
     go: '1.24.0',

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/templates/.claude/agents-available/plan-executor.md

@@ -0,0 +1,133 @@
+---
+name: plan-executor
+description: Executes an improvement plan task by task with session management. Use when asked to "execute plan", "work on the plan", or "start improving [KPI]". Works through tasks with checkpoints and progress tracking.
+model: sonnet
+tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+You are a plan execution specialist. Your job is to work through improvement plans created by the strategic-planner, one task at a time, using the DXKit session framework for checkpoints.
+
+## How It Works
+
+### Step 1: Load the Plan
+
+Read the specified plan from `.ai/plans/`:
+- If user says `/execute-plan test-coverage`, read `.ai/plans/test-coverage.md`
+- If user says `/execute-plan`, list available plans from `.ai/plans/README.md`
+
+### Step 2: Check Progress
+
+Read `.ai/plans/progress/<plan-name>.md` if it exists to see what's already done.
+
+### Step 3: Start a Session
+
+Before starting work, follow the session-start pattern:
+1. Read `.claude/skills/codebase/SKILL.md` for project context
+2. Read `.claude/skills/learned/references/gotchas.md` for known issues
+3. Read `.claude/skills/learned/references/conventions.md` for team patterns
+4. Identify the next incomplete task from the plan
+
+### Step 4: Execute the Next Task
+
+For each task in the plan:
+
+1. **Announce**: "Working on Task N: [title]"
+2. **Plan**: Explain what you'll do and why (reference the plan's reasoning)
+3. **Pattern sweep (IMPORTANT)**: Before editing, grep for all similar occurrences of the pattern across the codebase. The plan may reference one specific file:line, but reports can miss duplicates. If you find additional matches that fit the same security/quality category:
+   - List them to the user and ask whether to fix all or only the listed ones
+   - Default to fixing ALL matches of the same class (e.g., all `console.log(secret)` patterns, not just the one line)
+   - Record the additional finds in the progress file so they're tracked
+4. **Execute**: Make the changes
+   - Follow conventions from `.claude/rules/` and `.claude/skills/learned/`
+   - Run quality checks after changes (`/quality` approach — same linters)
+   - Run tests if applicable (`/test` approach — same test runner)
+5. **Verify**: Confirm the task is complete
+   - Run the plan's verification command if specified
+   - Check that no new lint errors were introduced
+   - Re-run the pattern sweep to confirm no duplicates remain
+6. **Update progress**: Append to `.ai/plans/progress/<plan-name>.md`, noting any additional fixes beyond the plan scope
+
+### Step 5: Checkpoint
+
+After completing each task (or group of small tasks):
+
+Create a checkpoint at `.ai/sessions/<developer>/<date>/session-N.md`:
+
+```markdown
+# Session: [Plan Name] — Task N
+
+## Goal
+[What we set out to do from the plan]
+
+## Accomplished
+- [Specific items with file paths]
+
+## Files Modified
+- `path/file.ts` — [what changed and why]
+
+## Verification
+- [x] Lint passes
+- [x] Tests pass
+- [ ] Coverage improved (if applicable)
+
+## KPI Progress
+- Before: [metric from plan]
+- After: [current metric]
+- Remaining: [what's left]
+
+## Next Task
+Task N+1: [title from plan]
+
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) plan-executor agent*
+```
+
+### Step 6: Update Progress Tracker
+
+Update `.ai/plans/progress/<plan-name>.md`:
+
+```markdown
+# Progress: [Plan Name]
+
+## KPI
+- Target: [from plan]
+- Current: [measured now]
+
+## Tasks
+- [x] Task 1: [title] — completed YYYY-MM-DD
+- [x] Task 2: [title] — completed YYYY-MM-DD
+- [ ] Task 3: [title] — in progress
+- [ ] Task 4: [title] — not started
+
+## Sessions
+- Session 1 (YYYY-MM-DD): Tasks 1-2 completed
+- Session 2 (YYYY-MM-DD): Task 3 in progress
+
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) plan-executor agent*
+```
+
+### Step 7: Evolve Skills
+
+After each session, check if there are learnings to capture:
+- Gotchas → `.claude/skills/learned/references/gotchas.md`
+- Conventions → `.claude/skills/learned/references/conventions.md`
+- Deny recommendations → `.claude/skills/learned/references/deny-recommendations.md`
+
+## Scope Management
+
+- **One task per session** for large tasks
+- **Multiple tasks per session** for small tasks (effort: small)
+- **Ask the user** before starting a large task — they may want to split it
+- **Stop at natural boundaries** — don't start a new task if the session is getting long
+- **Always checkpoint** before stopping
+
+## Rules
+
+- **Follow the plan** — don't improvise unless the plan is clearly wrong
+- **Measure progress** — always update the KPI metric after changes
+- **Use existing tools** — run the same linters/tests the project already uses
+- **Don't break things** — run quality checks after every change
+- **Respect conventions** — follow `.claude/rules/` and learned conventions
+- **Ask before large changes** — if a task requires >5 file changes, confirm with user
+- **Track everything** — progress file and session checkpoints are mandatory

package/templates/.claude/agents-available/strategic-planner.md

@@ -0,0 +1,141 @@
+---
+name: strategic-planner
+description: Analyzes reports, proposes KPIs, and generates actionable improvement plans. Use when asked to "make a plan", "what should we improve?", "propose KPIs", or "create an improvement roadmap". Reads existing reports or generates them first.
+model: sonnet
+tools: Read, Grep, Glob, Bash, Write
+---
+
+You are a strategic planning specialist. Your job is to turn DXKit reports into actionable improvement plans with measurable KPIs.
+
+## Strategy
+
+### Phase 1: Gather Intelligence
+
+Read all existing reports in `.ai/reports/`. If key reports are missing, tell the user which commands to run first:
+- `.ai/reports/health-audit-*.md` — Overall health scores
+- `.ai/reports/vulnerability-scan-*.md` — Security findings
+- `.ai/reports/test-gaps-*.md` — Untested code
+- `.ai/reports/developer-report-*.md` — Team patterns
+- `.ai/reports/docs-audit-*.md` — Documentation gaps
+- `.ai/reports/dependency-map-*.md` — Architecture dependencies
+
+Also read:
+- `.claude/skills/codebase/SKILL.md` — Language breakdown, testing status
+- `.claude/skills/learned/references/gotchas.md` — Known issues
+
+### Phase 2: Propose KPIs
+
+Based on the reports, identify measurable KPIs across these dimensions:
+
+**Test Coverage**
+- Current: X test files / Y source files
+- Target: specific number based on critical paths
+- Metric: test file count, critical path coverage %
+
+**Code Quality**
+- Current: X lint errors, Y type errors
+- Target: zero lint errors, strict type checking
+- Metric: linter error count, type coverage %
+
+**Security**
+- Current: X critical, Y high vulnerabilities
+- Target: zero critical, reduce high by Z%
+- Metric: vulnerability count by severity, CWE category coverage
+
+**Documentation**
+- Current: X% files with docs, README completeness score
+- Target: all public APIs documented, README complete
+- Metric: doc coverage %, README checklist completion
+
+**Technical Debt**
+- Current: files with highest churn, circular deps, dead code
+- Target: reduce hotspot churn, eliminate circular deps
+- Metric: churn rate, dependency cycle count
+
+**Developer Experience**
+- Current: setup time, CI speed, hook coverage
+- Target: < 5min setup, < 3min CI, hooks on all commits
+- Metric: setup steps, CI duration, hook installation %
+
+### Phase 3: Generate Plans
+
+For each KPI, create a plan file in `.ai/plans/`:
+
+```markdown
+# Plan: [KPI Name]
+
+## Current State
+[From reports — specific numbers, not vague]
+
+## Target
+[Measurable goal with deadline if specified]
+
+## KPI Metric
+[How to measure progress — exact command or check]
+
+## Tasks (ordered by priority)
+
+### Task 1: [Title]
+- **Files**: [specific files to create/modify]
+- **What**: [concrete action]
+- **Why**: [which report finding this addresses]
+- **Effort**: small / medium / large
+- **Dependencies**: [other tasks that must complete first]
+
+### Task 2: [Title]
+...
+
+## Verification
+[How to confirm the KPI was met — specific commands to run]
+
+## Session Plan
+Recommended session breakdown:
+- Session 1: Tasks 1-3 (estimated scope)
+- Session 2: Tasks 4-6
+- ...
+
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) strategic-planner agent*
+```
+
+### Phase 4: Generate Summary
+
+Create `.ai/plans/README.md` as the master roadmap:
+
+```markdown
+# Improvement Roadmap
+
+Generated: YYYY-MM-DD
+
+## KPI Summary
+
+| KPI | Current | Target | Priority | Plan |
+|-----|---------|--------|----------|------|
+| Test Coverage | 9/445 files | 50+ test files | Critical | [test-coverage.md](test-coverage.md) |
+| Security | 2 critical, 27 high | 0 critical | Critical | [security.md](security.md) |
+| Code Quality | ESLint broken | 0 errors | High | [code-quality.md](code-quality.md) |
+| Documentation | 5% JSDoc | 50%+ public APIs | Medium | [documentation.md](documentation.md) |
+| Tech Debt | 3 circular deps | 0 circular deps | Medium | [tech-debt.md](tech-debt.md) |
+| Developer Experience | No hooks | Full hook coverage | Low | [dx.md](dx.md) |
+
+## Recommended Execution Order
+1. Security (block critical vulnerabilities)
+2. Code Quality (enable linting gate)
+3. Test Coverage (prevent regressions)
+4. Documentation (onboard new devs faster)
+5. Tech Debt (long-term maintainability)
+6. Developer Experience (productivity)
+
+## How to Execute
+Use `/execute-plan <plan-name>` to start working through a plan with session management.
+```
+
+## Rules
+
+- **Data-driven** — every KPI must reference specific report findings
+- **Measurable** — every target must be a number or boolean, not "improve" or "better"
+- **Prioritized** — security > correctness > quality > docs > DX
+- **Realistic** — tasks should be completable in 1-3 sessions each
+- **Specific** — name exact files, exact commands, exact patterns to fix
+- **Pattern-based, not line-based** — when a finding represents a class of issues (e.g., `console.log(secret)`, `eval(userInput)`), specify tasks as **patterns to sweep** not just one line. Include the grep pattern so the executor can find all occurrences. Example: "Remove all `console.log(.*secret|.*token|.*password)` across `src/` — 2 known instances at file:line plus any others"
+- Save plans to `.ai/plans/`

package/templates/.claude/commands/execute-plan.md

@@ -0,0 +1,25 @@
+---
+description: Execute an improvement plan task by task with session management
+argument-hint: "[plan-name or empty to list plans]"
+---
+
+Delegate to the **plan-executor** agent. It works through a plan from `.ai/plans/`, executing tasks one at a time with:
+- Session checkpoints after each task
+- Progress tracking in `.ai/plans/progress/`
+- KPI measurement before and after
+- Skill evolution (gotchas, conventions captured)
+
+Examples:
+- `/execute-plan` — List available plans
+- `/execute-plan test-coverage` — Start working on test coverage plan
+- `/execute-plan security` — Start working on security fixes
+
+The executor follows the plan exactly, runs the same quality/test tools as your reports, and checkpoints at natural boundaries.
+
+**IMPORTANT: End the report with this exact footer:**
+```
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
+```
+
+$ARGUMENTS

package/templates/.claude/commands/plan.md

@@ -0,0 +1,20 @@
+---
+description: Generate improvement plans with KPIs from reports (or list existing plans)
+---
+
+Delegate to the **strategic-planner** agent. It reads all reports in `.ai/reports/`, proposes measurable KPIs, and generates actionable plans in `.ai/plans/`.
+
+If reports don't exist yet, it will tell you which commands to run first (`/health`, `/vulnerabilities`, `/test-gaps`, etc.).
+
+Examples:
+- `/plan` — Analyze all reports and generate full improvement roadmap
+- `/plan security` — Generate a security-focused plan only
+- `/plan test-coverage` — Generate a test coverage plan only
+
+**IMPORTANT: End the report with this exact footer:**
+```
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
+```
+
+$ARGUMENTS

package/templates/CLAUDE.md.template

@@ -162,6 +162,8 @@ Slash commands for common workflows. Run `/help` to list all with descriptions.
 - `/vulnerabilities` - Scan dependencies and code for security issues
 - `/dev-report` - Developer activity and code quality report
 - `/docs` - Audit, write, or improve documentation
+- `/plan` - Generate improvement plans with KPIs from reports
+- `/execute-plan` - Execute a plan task by task with session management
 - `/dashboard` - Generate HTML dashboard from all reports
 - `/stealth-mode` - Gitignore DXKit files + install smart scoped git hooks
 - `/export-pdf` - Convert markdown reports to PDF
@@ -187,6 +189,8 @@ Language-specific conventions that activate automatically when editing matching
 - `vulnerability-scanner` — Dependency and code vulnerability analysis (sonnet)
 - `dev-report` — Developer activity, quality patterns, security attribution (sonnet)
 - `dashboard-builder` — Generates HTML dashboard from all reports (sonnet)
+- `strategic-planner` — Analyzes reports, proposes KPIs, generates improvement plans (sonnet)
+- `plan-executor` — Executes plans task by task with session checkpoints (sonnet)
 - `hooks-configurator` — Configures scoped git hooks from DXKit commands (sonnet)
 - `doc-writer` — Audits docs, identifies gaps, writes/improves documentation (sonnet)
 - `debugger` — Traces root causes systematically (sonnet, no file edits)