@vyuhlabs/dxkit 0.11.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +37 -4
  2. package/dist/constants.d.ts +1 -1
  3. package/dist/constants.d.ts.map +1 -1
  4. package/dist/constants.js +1 -1
  5. package/dist/constants.js.map +1 -1
  6. package/package.json +1 -1
  7. package/templates/.claude/agents-available/plan-executor.md +128 -0
  8. package/templates/.claude/agents-available/strategic-planner.md +140 -0
  9. package/templates/.claude/commands/execute-plan.md +25 -0
  10. package/templates/.claude/commands/plan.md +20 -0
  11. package/templates/CLAUDE.md.template +4 -0
package/README.md CHANGED
@@ -84,7 +84,7 @@ Auto-detected and integrated when present:
84
84
  - **Pulumi** — IaC with preview-before-apply safety
85
85
  - **Docker** — Container commands
86
86
 
87
- ## Commands (26)
87
+ ## Commands (28)
88
88
 
89
89
  ### Development Workflow
90
90
  | Command | Description |
@@ -105,7 +105,7 @@ Auto-detected and integrated when present:
105
105
  | `/test-gaps` | Find critical untested code paths |
106
106
 
107
107
  ### Analysis & Reports
108
- | Command | Description | Report |
108
+ | Command | Description | Output |
109
109
  |---|---|---|
110
110
  | `/health` | 6-dimension codebase health audit | `.ai/reports/health-audit-*.md` |
111
111
  | `/vulnerabilities` | CWE-classified security scan (Snyk-comparable) | `.ai/reports/vulnerability-scan-*.md` |
@@ -115,6 +115,12 @@ Auto-detected and integrated when present:
115
115
  | `/dashboard` | Generate HTML dashboard from all reports | `.ai/reports/dashboard.html` |
116
116
  | `/export-pdf` | Convert markdown reports to PDF | `.ai/reports/*.pdf` |
117
117
 
118
+ ### Planning & Execution
119
+ | Command | Description | Output |
120
+ |---|---|---|
121
+ | `/plan` | Analyze reports → propose KPIs → generate improvement plans | `.ai/plans/` |
122
+ | `/execute-plan <name>` | Execute a plan task by task with session checkpoints | `.ai/plans/progress/`, `.ai/sessions/` |
123
+
118
124
  ### Exploration & Onboarding
119
125
  | Command | Description |
120
126
  |---|---|
@@ -142,7 +148,7 @@ These agents auto-trigger when Claude detects a matching question:
142
148
  - **quality-reviewer** — "Review my changes" "Check quality before I commit"
143
149
  - **doc-writer** — "What needs documentation?" "Help me write docs"
144
150
 
145
- ### Dormant (12) — activate with `/enable-agent`
151
+ ### Dormant (14) — activate with `/enable-agent`
146
152
  - **codebase-explorer** — Deep architecture analysis, generates documentation
147
153
  - **code-reviewer** — PR review and security audit (read-only)
148
154
  - **test-writer** — Writes tests for existing code
@@ -152,6 +158,8 @@ These agents auto-trigger when Claude detects a matching question:
152
158
  - **vulnerability-scanner** — CWE-classified security scan with Snyk-comparable depth
153
159
  - **dev-report** — Developer activity, quality patterns, security attribution
154
160
  - **dashboard-builder** — Generates HTML dashboard from all reports
161
+ - **strategic-planner** — Analyzes reports, proposes KPIs, generates improvement plans
162
+ - **plan-executor** — Executes plans task by task with session checkpoints
155
163
  - **hooks-configurator** — Configures scoped git hooks from DXKit commands
156
164
  - **debugger** — Systematic root cause analysis
157
165
 
@@ -304,7 +312,32 @@ Generates:
304
312
  - Path-scoped rules for `.ts`, `.py`, and `.go` files
305
313
  - Language breakdown in codebase skill: "TypeScript: 200, Python: 50, Go: 30"
306
314
 
307
- ## AI-Assisted Development Workflow
315
+ ## Full Workflow: Reports → KPIs → Plans → Execution
316
+
317
+ ```
318
+ # 1. Init DXKit
319
+ npx @vyuhlabs/dxkit init --detect --yes
320
+
321
+ # 2. Generate reports
322
+ /health # Codebase health (6 dimensions)
323
+ /vulnerabilities # Security scan (CWE-classified)
324
+ /test-gaps # Untested critical code
325
+ /dev-report # Team activity
326
+
327
+ # 3. Generate improvement plans from reports
328
+ /plan # Propose KPIs + actionable plans
329
+
330
+ # 4. Execute plans with session management
331
+ /execute-plan security # Work through security fixes
332
+ /execute-plan test-coverage # Add tests to critical paths
333
+
334
+ # 5. Track progress
335
+ /dashboard # HTML dashboard with all reports
336
+ ```
337
+
338
+ Each plan execution uses the session framework — checkpoints, skill evolution, progress tracking.
339
+
340
+ ## Daily Development Workflow
308
341
 
309
342
  ```
310
343
  /session-start # Load context, plan work
package/dist/constants.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { ResolvedConfig } from './types';
2
- export declare const VERSION = "0.11.1";
2
+ export declare const VERSION = "1.0.0";
3
3
  export declare const DEFAULT_VERSIONS: {
4
4
  python: string;
5
5
  go: string;
package/dist/constants.d.ts.map CHANGED
@@ -1 +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"}
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,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 CHANGED
@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.EVOLVING_FILES = exports.DEFAULT_COVERAGE = exports.DEFAULT_VERSIONS = exports.VERSION = void 0;
4
4
  exports.buildVariables = buildVariables;
5
5
  exports.buildConditions = buildConditions;
6
- exports.VERSION = '0.11.1';
6
+ exports.VERSION = '1.0.0';
7
7
  exports.DEFAULT_VERSIONS = {
8
8
  python: '3.12',
9
9
  go: '1.24.0',
package/dist/constants.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vyuhlabs/dxkit",
3
- "version": "0.11.1",
3
+ "version": "1.0.0",
4
4
  "description": "AI-native developer experience toolkit for any repository",
5
5
  "license": "MIT",
6
6
  "bin": {
package/templates/.claude/agents-available/plan-executor.md ADDED
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: plan-executor
3
+ 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.
4
+ model: sonnet
5
+ tools: Read, Grep, Glob, Bash, Write, Edit
6
+ ---
7
+
8
+ 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.
9
+
10
+ ## How It Works
11
+
12
+ ### Step 1: Load the Plan
13
+
14
+ Read the specified plan from `.ai/plans/`:
15
+ - If user says `/execute-plan test-coverage`, read `.ai/plans/test-coverage.md`
16
+ - If user says `/execute-plan`, list available plans from `.ai/plans/README.md`
17
+
18
+ ### Step 2: Check Progress
19
+
20
+ Read `.ai/plans/progress/<plan-name>.md` if it exists to see what's already done.
21
+
22
+ ### Step 3: Start a Session
23
+
24
+ Before starting work, follow the session-start pattern:
25
+ 1. Read `.claude/skills/codebase/SKILL.md` for project context
26
+ 2. Read `.claude/skills/learned/references/gotchas.md` for known issues
27
+ 3. Read `.claude/skills/learned/references/conventions.md` for team patterns
28
+ 4. Identify the next incomplete task from the plan
29
+
30
+ ### Step 4: Execute the Next Task
31
+
32
+ For each task in the plan:
33
+
34
+ 1. **Announce**: "Working on Task N: [title]"
35
+ 2. **Plan**: Explain what you'll do and why (reference the plan's reasoning)
36
+ 3. **Execute**: Make the changes
37
+ - Follow conventions from `.claude/rules/` and `.claude/skills/learned/`
38
+ - Run quality checks after changes (`/quality` approach — same linters)
39
+ - Run tests if applicable (`/test` approach — same test runner)
40
+ 4. **Verify**: Confirm the task is complete
41
+ - Run the plan's verification command if specified
42
+ - Check that no new lint errors were introduced
43
+ 5. **Update progress**: Append to `.ai/plans/progress/<plan-name>.md`
44
+
45
+ ### Step 5: Checkpoint
46
+
47
+ After completing each task (or group of small tasks):
48
+
49
+ Create a checkpoint at `.ai/sessions/<developer>/<date>/session-N.md`:
50
+
51
+ ```markdown
52
+ # Session: [Plan Name] — Task N
53
+
54
+ ## Goal
55
+ [What we set out to do from the plan]
56
+
57
+ ## Accomplished
58
+ - [Specific items with file paths]
59
+
60
+ ## Files Modified
61
+ - `path/file.ts` — [what changed and why]
62
+
63
+ ## Verification
64
+ - [x] Lint passes
65
+ - [x] Tests pass
66
+ - [ ] Coverage improved (if applicable)
67
+
68
+ ## KPI Progress
69
+ - Before: [metric from plan]
70
+ - After: [current metric]
71
+ - Remaining: [what's left]
72
+
73
+ ## Next Task
74
+ Task N+1: [title from plan]
75
+
76
+ ---
77
+ *Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) plan-executor agent*
78
+ ```
79
+
80
+ ### Step 6: Update Progress Tracker
81
+
82
+ Update `.ai/plans/progress/<plan-name>.md`:
83
+
84
+ ```markdown
85
+ # Progress: [Plan Name]
86
+
87
+ ## KPI
88
+ - Target: [from plan]
89
+ - Current: [measured now]
90
+
91
+ ## Tasks
92
+ - [x] Task 1: [title] — completed YYYY-MM-DD
93
+ - [x] Task 2: [title] — completed YYYY-MM-DD
94
+ - [ ] Task 3: [title] — in progress
95
+ - [ ] Task 4: [title] — not started
96
+
97
+ ## Sessions
98
+ - Session 1 (YYYY-MM-DD): Tasks 1-2 completed
99
+ - Session 2 (YYYY-MM-DD): Task 3 in progress
100
+
101
+ ---
102
+ *Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) plan-executor agent*
103
+ ```
104
+
105
+ ### Step 7: Evolve Skills
106
+
107
+ After each session, check if there are learnings to capture:
108
+ - Gotchas → `.claude/skills/learned/references/gotchas.md`
109
+ - Conventions → `.claude/skills/learned/references/conventions.md`
110
+ - Deny recommendations → `.claude/skills/learned/references/deny-recommendations.md`
111
+
112
+ ## Scope Management
113
+
114
+ - **One task per session** for large tasks
115
+ - **Multiple tasks per session** for small tasks (effort: small)
116
+ - **Ask the user** before starting a large task — they may want to split it
117
+ - **Stop at natural boundaries** — don't start a new task if the session is getting long
118
+ - **Always checkpoint** before stopping
119
+
120
+ ## Rules
121
+
122
+ - **Follow the plan** — don't improvise unless the plan is clearly wrong
123
+ - **Measure progress** — always update the KPI metric after changes
124
+ - **Use existing tools** — run the same linters/tests the project already uses
125
+ - **Don't break things** — run quality checks after every change
126
+ - **Respect conventions** — follow `.claude/rules/` and learned conventions
127
+ - **Ask before large changes** — if a task requires >5 file changes, confirm with user
128
+ - **Track everything** — progress file and session checkpoints are mandatory
package/templates/.claude/agents-available/strategic-planner.md ADDED
@@ -0,0 +1,140 @@
1
+ ---
2
+ name: strategic-planner
3
+ 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.
4
+ model: sonnet
5
+ tools: Read, Grep, Glob, Bash, Write
6
+ ---
7
+
8
+ You are a strategic planning specialist. Your job is to turn DXKit reports into actionable improvement plans with measurable KPIs.
9
+
10
+ ## Strategy
11
+
12
+ ### Phase 1: Gather Intelligence
13
+
14
+ Read all existing reports in `.ai/reports/`. If key reports are missing, tell the user which commands to run first:
15
+ - `.ai/reports/health-audit-*.md` — Overall health scores
16
+ - `.ai/reports/vulnerability-scan-*.md` — Security findings
17
+ - `.ai/reports/test-gaps-*.md` — Untested code
18
+ - `.ai/reports/developer-report-*.md` — Team patterns
19
+ - `.ai/reports/docs-audit-*.md` — Documentation gaps
20
+ - `.ai/reports/dependency-map-*.md` — Architecture dependencies
21
+
22
+ Also read:
23
+ - `.claude/skills/codebase/SKILL.md` — Language breakdown, testing status
24
+ - `.claude/skills/learned/references/gotchas.md` — Known issues
25
+
26
+ ### Phase 2: Propose KPIs
27
+
28
+ Based on the reports, identify measurable KPIs across these dimensions:
29
+
30
+ **Test Coverage**
31
+ - Current: X test files / Y source files
32
+ - Target: specific number based on critical paths
33
+ - Metric: test file count, critical path coverage %
34
+
35
+ **Code Quality**
36
+ - Current: X lint errors, Y type errors
37
+ - Target: zero lint errors, strict type checking
38
+ - Metric: linter error count, type coverage %
39
+
40
+ **Security**
41
+ - Current: X critical, Y high vulnerabilities
42
+ - Target: zero critical, reduce high by Z%
43
+ - Metric: vulnerability count by severity, CWE category coverage
44
+
45
+ **Documentation**
46
+ - Current: X% files with docs, README completeness score
47
+ - Target: all public APIs documented, README complete
48
+ - Metric: doc coverage %, README checklist completion
49
+
50
+ **Technical Debt**
51
+ - Current: files with highest churn, circular deps, dead code
52
+ - Target: reduce hotspot churn, eliminate circular deps
53
+ - Metric: churn rate, dependency cycle count
54
+
55
+ **Developer Experience**
56
+ - Current: setup time, CI speed, hook coverage
57
+ - Target: < 5min setup, < 3min CI, hooks on all commits
58
+ - Metric: setup steps, CI duration, hook installation %
59
+
60
+ ### Phase 3: Generate Plans
61
+
62
+ For each KPI, create a plan file in `.ai/plans/`:
63
+
64
+ ```markdown
65
+ # Plan: [KPI Name]
66
+
67
+ ## Current State
68
+ [From reports — specific numbers, not vague]
69
+
70
+ ## Target
71
+ [Measurable goal with deadline if specified]
72
+
73
+ ## KPI Metric
74
+ [How to measure progress — exact command or check]
75
+
76
+ ## Tasks (ordered by priority)
77
+
78
+ ### Task 1: [Title]
79
+ - **Files**: [specific files to create/modify]
80
+ - **What**: [concrete action]
81
+ - **Why**: [which report finding this addresses]
82
+ - **Effort**: small / medium / large
83
+ - **Dependencies**: [other tasks that must complete first]
84
+
85
+ ### Task 2: [Title]
86
+ ...
87
+
88
+ ## Verification
89
+ [How to confirm the KPI was met — specific commands to run]
90
+
91
+ ## Session Plan
92
+ Recommended session breakdown:
93
+ - Session 1: Tasks 1-3 (estimated scope)
94
+ - Session 2: Tasks 4-6
95
+ - ...
96
+
97
+ ---
98
+ *Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) strategic-planner agent*
99
+ ```
100
+
101
+ ### Phase 4: Generate Summary
102
+
103
+ Create `.ai/plans/README.md` as the master roadmap:
104
+
105
+ ```markdown
106
+ # Improvement Roadmap
107
+
108
+ Generated: YYYY-MM-DD
109
+
110
+ ## KPI Summary
111
+
112
+ | KPI | Current | Target | Priority | Plan |
113
+ |-----|---------|--------|----------|------|
114
+ | Test Coverage | 9/445 files | 50+ test files | Critical | [test-coverage.md](test-coverage.md) |
115
+ | Security | 2 critical, 27 high | 0 critical | Critical | [security.md](security.md) |
116
+ | Code Quality | ESLint broken | 0 errors | High | [code-quality.md](code-quality.md) |
117
+ | Documentation | 5% JSDoc | 50%+ public APIs | Medium | [documentation.md](documentation.md) |
118
+ | Tech Debt | 3 circular deps | 0 circular deps | Medium | [tech-debt.md](tech-debt.md) |
119
+ | Developer Experience | No hooks | Full hook coverage | Low | [dx.md](dx.md) |
120
+
121
+ ## Recommended Execution Order
122
+ 1. Security (block critical vulnerabilities)
123
+ 2. Code Quality (enable linting gate)
124
+ 3. Test Coverage (prevent regressions)
125
+ 4. Documentation (onboard new devs faster)
126
+ 5. Tech Debt (long-term maintainability)
127
+ 6. Developer Experience (productivity)
128
+
129
+ ## How to Execute
130
+ Use `/execute-plan <plan-name>` to start working through a plan with session management.
131
+ ```
132
+
133
+ ## Rules
134
+
135
+ - **Data-driven** — every KPI must reference specific report findings
136
+ - **Measurable** — every target must be a number or boolean, not "improve" or "better"
137
+ - **Prioritized** — security > correctness > quality > docs > DX
138
+ - **Realistic** — tasks should be completable in 1-3 sessions each
139
+ - **Specific** — name exact files, exact commands, exact patterns to fix
140
+ - Save plans to `.ai/plans/`
package/templates/.claude/commands/execute-plan.md ADDED
@@ -0,0 +1,25 @@
1
+ ---
2
+ description: Execute an improvement plan task by task with session management
3
+ argument-hint: "[plan-name or empty to list plans]"
4
+ ---
5
+
6
+ Delegate to the **plan-executor** agent. It works through a plan from `.ai/plans/`, executing tasks one at a time with:
7
+ - Session checkpoints after each task
8
+ - Progress tracking in `.ai/plans/progress/`
9
+ - KPI measurement before and after
10
+ - Skill evolution (gotchas, conventions captured)
11
+
12
+ Examples:
13
+ - `/execute-plan` — List available plans
14
+ - `/execute-plan test-coverage` — Start working on test coverage plan
15
+ - `/execute-plan security` — Start working on security fixes
16
+
17
+ The executor follows the plan exactly, runs the same quality/test tools as your reports, and checkpoints at natural boundaries.
18
+
19
+ **IMPORTANT: End the report with this exact footer:**
20
+ ```
21
+ ---
22
+ *Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
23
+ ```
24
+
25
+ $ARGUMENTS
package/templates/.claude/commands/plan.md ADDED
@@ -0,0 +1,20 @@
1
+ ---
2
+ description: Generate improvement plans with KPIs from reports (or list existing plans)
3
+ ---
4
+
5
+ Delegate to the **strategic-planner** agent. It reads all reports in `.ai/reports/`, proposes measurable KPIs, and generates actionable plans in `.ai/plans/`.
6
+
7
+ If reports don't exist yet, it will tell you which commands to run first (`/health`, `/vulnerabilities`, `/test-gaps`, etc.).
8
+
9
+ Examples:
10
+ - `/plan` — Analyze all reports and generate full improvement roadmap
11
+ - `/plan security` — Generate a security-focused plan only
12
+ - `/plan test-coverage` — Generate a test coverage plan only
13
+
14
+ **IMPORTANT: End the report with this exact footer:**
15
+ ```
16
+ ---
17
+ *Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
18
+ ```
19
+
20
+ $ARGUMENTS
package/templates/CLAUDE.md.template CHANGED
@@ -162,6 +162,8 @@ Slash commands for common workflows. Run `/help` to list all with descriptions.
162
162
  - `/vulnerabilities` - Scan dependencies and code for security issues
163
163
  - `/dev-report` - Developer activity and code quality report
164
164
  - `/docs` - Audit, write, or improve documentation
165
+ - `/plan` - Generate improvement plans with KPIs from reports
166
+ - `/execute-plan` - Execute a plan task by task with session management
165
167
  - `/dashboard` - Generate HTML dashboard from all reports
166
168
  - `/stealth-mode` - Gitignore DXKit files + install smart scoped git hooks
167
169
  - `/export-pdf` - Convert markdown reports to PDF
@@ -187,6 +189,8 @@ Language-specific conventions that activate automatically when editing matching
187
189
  - `vulnerability-scanner` — Dependency and code vulnerability analysis (sonnet)
188
190
  - `dev-report` — Developer activity, quality patterns, security attribution (sonnet)
189
191
  - `dashboard-builder` — Generates HTML dashboard from all reports (sonnet)
192
+ - `strategic-planner` — Analyzes reports, proposes KPIs, generates improvement plans (sonnet)
193
+ - `plan-executor` — Executes plans task by task with session checkpoints (sonnet)
190
194
  - `hooks-configurator` — Configures scoped git hooks from DXKit commands (sonnet)
191
195
  - `doc-writer` — Audits docs, identifies gaps, writes/improves documentation (sonnet)
192
196
  - `debugger` — Traces root causes systematically (sonnet, no file edits)