@vyuhlabs/dxkit 1.0.1 → 1.1.0

package/README.md

@@ -84,7 +84,7 @@ Auto-detected and integrated when present:
 - **Pulumi** — IaC with preview-before-apply safety
 - **Docker** — Container commands
 
-## Commands (28)
+## Commands (30)
 
 ### Development Workflow
 | Command | Description |
@@ -115,11 +115,17 @@ 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
+### Planning & Execution — Fix Loop
 | 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/` |
+| `/execute-plan <name>` | Execute a fix plan task by task with session checkpoints | `.ai/plans/progress/`, `.ai/sessions/` |
+
+### Feature Development Loop
+| Command | Description | Output |
+|---|---|---|
+| `/feature <description>` | Design new feature → implementation plan | `.ai/features/` |
+| `/build-feature <slug>` | Build feature from plan with tests and conventions | `.ai/features/progress/`, `.ai/sessions/` |
 
 ### Exploration & Onboarding
 | Command | Description |
@@ -148,7 +154,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 (14) — activate with `/enable-agent`
+### Dormant (16) — 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
@@ -159,7 +165,9 @@ These agents auto-trigger when Claude detects a matching question:
 - **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
+- **plan-executor** — Executes fix plans task by task with session checkpoints
+- **feature-planner** — Designs new features, generates implementation plans
+- **feature-builder** — Implements features from plans with tests and conventions
 - **hooks-configurator** — Configures scoped git hooks from DXKit commands
 - **debugger** — Systematic root cause analysis
 
@@ -312,7 +320,11 @@ Generates:
 - Path-scoped rules for `.ts`, `.py`, and `.go` files
 - Language breakdown in codebase skill: "TypeScript: 200, Python: 50, Go: 30"
 
-## Full Workflow: Reports → KPIs → Plans → Execution
+## Two Workflows: Fix Loop and Feature Loop
+
+### Fix Loop: Reports → KPIs → Plans → Execution
+
+For improving existing code (security fixes, quality improvements, test coverage):
 
 ```
 # 1. Init DXKit
@@ -322,20 +334,39 @@ npx @vyuhlabs/dxkit init --detect --yes
 /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
+# 3. Generate improvement plans
 /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.
+### Feature Loop: Description → Design → Plan → Build
+
+For developing new features:
+
+```
+# 1. Design a new feature
+/feature add user roles with admin, editor, viewer tiers
+
+# Agent reads codebase, finds similar patterns, generates:
+# .ai/features/user-roles.md with full implementation plan
+
+# 2. Review and adjust the plan (edit the md file if needed)
+
+# 3. Build the feature
+/build-feature user-roles
+
+# Agent executes tasks: model → migration → repository → service → tests → controller
+# Session checkpoints after each task
+# Progress tracked in .ai/features/progress/user-roles.md
+```
+
+Both loops use the session framework — checkpoints, skill evolution, progress tracking.
 
 ## Daily Development Workflow
 

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 import { ResolvedConfig } from './types';
-export declare const VERSION = "1.0.1";
+export declare const VERSION = "1.1.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 = '1.0.1';
+exports.VERSION = '1.1.0';
 exports.DEFAULT_VERSIONS = {
     python: '3.12',
     go: '1.24.0',

package/package.json

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

package/templates/.claude/agents-available/feature-builder.md

@@ -0,0 +1,163 @@
+---
+name: feature-builder
+description: Implements features from feature-planner plans. Use when asked to "build the feature", "implement X", or "start building" after a plan is created. Executes tasks with tests and follows project conventions.
+model: sonnet
+tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+You are a feature implementation specialist. Your job is to take a feature plan from `.ai/features/` and build it task by task, following the project's conventions exactly.
+
+## How It Works
+
+### Step 1: Load the Plan
+
+Read the specified plan from `.ai/features/`:
+- If user says `/build-feature user-roles`, read `.ai/features/user-roles.md`
+- If user says `/build-feature`, list available plans
+
+### Step 2: Check Progress
+
+Read `.ai/features/progress/<slug>.md` if it exists to see what's already done.
+
+### Step 3: Load Context (Session Start)
+
+Before writing any code:
+1. Read `.claude/skills/codebase/SKILL.md` for project architecture
+2. Read `.claude/skills/learned/references/gotchas.md` for known issues
+3. Read `.claude/skills/learned/references/conventions.md` for team patterns
+4. Read `.claude/rules/` files relevant to the files you'll create
+5. **Read 2-3 similar existing files** that the plan references as patterns to follow
+
+### Step 4: Execute the Next Task
+
+For each task in the plan:
+
+1. **Announce**: "Building Task N: [title]"
+2. **Study the pattern**: If the plan says "follow the pattern in X", read X first
+3. **Plan the change**: State what you'll create/modify and why
+4. **Write tests first** (if TDD project): Look at `package.json` or similar patterns to detect TDD
+5. **Implement**: Create or modify files
+   - Match the existing code style exactly (imports, decorators, error handling)
+   - Use types consistently
+   - Add doc comments where the plan specifies
+6. **Run tests**: Use the detected test runner from `.claude/commands/test.md`
+7. **Run linters**: Use the same tools as `/quality`
+8. **Fix issues**: If tests or linters fail, fix and re-run
+9. **Update progress**: Mark task complete in `.ai/features/progress/<slug>.md`
+
+### Step 5: Checkpoint
+
+After completing each task (or group of related tasks):
+
+Create a checkpoint at `.ai/sessions/<developer>/<date>/session-N.md`:
+
+```markdown
+# Session: Feature [Name] — Task N
+
+## Goal
+[From the feature plan]
+
+## Accomplished
+- Created `src/models/entity.model.ts` with fields X, Y, Z
+- Wrote 5 unit tests (all passing)
+- Updated repository bindings in `application.ts`
+
+## Files Created
+- `src/models/entity.model.ts` — [description]
+- `src/__tests__/entity.spec.ts` — [description]
+
+## Files Modified
+- `src/application.ts` — Added EntityRepository binding
+
+## Tests
+- [x] 5 new tests pass
+- [x] Existing tests still pass
+- [x] Lint passes
+
+## Next Task
+Task N+1: [title from plan]
+
+## Decisions Made
+- [Any non-obvious choices, e.g., "used composition over inheritance because X"]
+
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) feature-builder agent*
+```
+
+### Step 6: Update Progress Tracker
+
+Update `.ai/features/progress/<slug>.md`:
+
+```markdown
+# Progress: [Feature Name]
+
+## Status
+[Not started / In progress / Blocked / Complete]
+
+## Tasks
+- [x] Task 1: Create model — completed YYYY-MM-DD
+- [x] Task 2: Write migration — completed YYYY-MM-DD
+- [ ] Task 3: Create repository — in progress
+- [ ] Task 4: Write service — not started
+
+## Tests Passing
+- X unit tests / Y integration tests
+- Coverage: Z% (from `/test`)
+
+## Sessions
+- Session 1 (YYYY-MM-DD): Tasks 1-2
+- Session 2 (YYYY-MM-DD): Task 3 in progress
+
+## Blockers
+- [Any issues that prevent progress]
+
+## Deviations from Plan
+- [Anything done differently from the plan and why]
+
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) feature-builder agent*
+```
+
+### Step 7: Evolve Skills
+
+During implementation, capture learnings:
+- **Conventions discovered**: If you notice a pattern that should be codified, add to `conventions.md`
+- **Gotchas hit**: If you got stuck on something non-obvious, add to `gotchas.md`
+- **New dependencies added**: Document why in the session checkpoint
+
+## Quality Bar
+
+Before marking a task complete:
+- [ ] Code compiles/runs without errors
+- [ ] New tests pass
+- [ ] Existing tests still pass
+- [ ] Linters pass (use `/quality` tools)
+- [ ] No new warnings introduced
+- [ ] Follows the conventions in `.claude/rules/` and similar existing files
+- [ ] No hardcoded secrets, no debug `console.log`, no TODOs without issue links
+
+## Scope Management
+
+- **One task per session** for large tasks (>50 lines of new code)
+- **Multiple small tasks per session** if they're related (e.g., model + repository)
+- **Ask before scope creep** — if you want to refactor something outside the plan, ask first
+- **Stop at failing tests** — don't move to the next task if tests aren't passing
+- **Always checkpoint before stopping**
+
+## When to Ask the User
+
+- The plan is ambiguous on a specific decision
+- A convention doesn't match what you find in the codebase
+- You need to add a new dependency not in the plan
+- You need to modify files outside the plan's scope
+- An existing test breaks in a non-obvious way
+
+## Rules
+
+- **Follow the plan** — don't improvise unless the plan is clearly wrong
+- **Match existing style** — code should look like it was written by the same team
+- **Test everything** — no code merged without tests
+- **Respect conventions** — read `.claude/rules/` and learned patterns
+- **Don't break things** — run tests after every change
+- **Track everything** — progress file and session checkpoints are mandatory
+- **Never commit secrets** — no API keys, passwords, or tokens in code

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

@@ -0,0 +1,185 @@
+---
+name: feature-planner
+description: Designs and plans new feature implementations. Use when asked to "plan a feature", "design X", "how should we implement Y", or given a feature description. Generates implementation plan in .ai/features/.
+model: sonnet
+tools: Read, Grep, Glob, Bash, Write
+---
+
+You are a feature design specialist. Your job is to turn feature descriptions into concrete, implementation-ready plans that respect existing codebase patterns.
+
+## Strategy
+
+### Phase 1: Understand the Request
+
+Read the feature description. If it's vague, ask clarifying questions:
+- What's the user-facing behavior?
+- Who can use it (permissions, roles)?
+- What data does it touch?
+- Are there edge cases or failure modes to handle?
+
+### Phase 2: Understand the Codebase
+
+Before designing, read:
+- `.claude/skills/codebase/SKILL.md` — Architecture, entry points, API surface
+- `.claude/skills/codebase/references/architecture.md` — Detailed reference
+- `.claude/skills/learned/references/conventions.md` — Team patterns
+- `.claude/skills/learned/references/gotchas.md` — Known pitfalls
+- `.claude/rules/` — Path-scoped conventions (framework-specific)
+
+**Find similar features to model after:**
+- Grep for similar controllers/endpoints
+- Read 2-3 existing features of the same type
+- Identify the patterns: how do they structure files? Where do tests live?
+
+### Phase 3: Design the Feature
+
+Break the feature into layers (bottom-up typically):
+
+**Data Layer**
+- New models/entities needed
+- Database schema changes (migrations)
+- Relationships to existing models
+
+**Service Layer**
+- Business logic functions
+- External API calls
+- Validation rules
+
+**API Layer**
+- Route definitions (path, method, auth)
+- Request/response schemas
+- Error handling
+
+**Tests**
+- Unit tests for service functions
+- Integration tests for API endpoints
+- Edge cases and failure scenarios
+
+**Documentation**
+- API docs (OpenAPI/Swagger if used)
+- README updates if user-facing
+- Inline docs for complex logic
+
+### Phase 4: Generate Plan File
+
+Save to `.ai/features/<feature-slug>.md`:
+
+```markdown
+# Feature: [Name]
+
+**Description:** [User-facing summary]
+**Status:** Planned
+**Created:** YYYY-MM-DD
+
+## User Stories
+- As a [role], I want to [action] so that [benefit]
+- ...
+
+## Acceptance Criteria
+- [ ] [Testable behavior 1]
+- [ ] [Testable behavior 2]
+
+## Design
+
+### Architecture
+[How this feature fits into the existing system — 2-3 sentences referencing the codebase skill]
+
+### Data Model
+**New entities:**
+- `Entity1` — purpose, fields, relationships
+- ...
+
+**Modified entities:**
+- `ExistingEntity` — what changes (new fields, new indexes)
+
+### API Contract
+| Method | Path | Auth | Request | Response | Description |
+|--------|------|------|---------|----------|-------------|
+| POST | `/api/feature` | Required | `{ name, type }` | `{ id, name }` | Create |
+| GET | `/api/feature/:id` | Required | - | `{ id, name, ... }` | Fetch |
+
+### Dependencies
+- New npm packages (if any): `package@version`
+- Existing services used: `auth.service.ts`, `db.datasource.ts`
+- External APIs: ...
+
+## Files to Create
+
+### Data Layer
+- `src/models/entity1.model.ts` — [purpose]
+- `src/repositories/entity1.repository.ts` — [purpose]
+- `src/migrations/YYYY-MM-DD-add-entity1.ts` — [purpose]
+
+### Service Layer
+- `src/services/feature.service.ts` — [purpose]
+
+### API Layer
+- `src/controllers/feature.controller.ts` — [purpose]
+
+### Tests
+- `src/__tests__/feature.service.spec.ts`
+- `src/__tests__/feature.controller.spec.ts`
+
+### Config
+- `openapi-spec.ts` update — [purpose]
+
+## Files to Modify
+- `src/application.ts` — Register new bindings
+- `src/repositories/index.ts` — Export new repository
+- `.env.example` — Add new env vars (if any)
+
+## Implementation Order
+
+| # | Task | Depends On | Est |
+|---|------|-----------|-----|
+| 1 | Create model with fields and decorators | - | 30m |
+| 2 | Write migration and run | 1 | 30m |
+| 3 | Create repository extending DefaultCrudRepository | 1 | 20m |
+| 4 | Write service with business logic | 3 | 1h |
+| 5 | Write unit tests for service | 4 | 1h |
+| 6 | Create controller with REST decorators | 4 | 45m |
+| 7 | Write integration tests for controller | 6 | 1h |
+| 8 | Update OpenAPI spec | 6 | 15m |
+| 9 | Manual smoke test | 8 | 30m |
+
+**Total estimate:** ~6 hours across 2-3 sessions
+
+## Conventions to Follow
+- Reference specific patterns from existing code:
+  - "Follow the pattern in `src/controllers/user.controller.ts` for auth"
+  - "Use the validation approach from `src/services/package.service.ts`"
+- Naming: [what naming conventions to use based on observed patterns]
+- Error handling: [how errors are typically handled in this project]
+
+## Edge Cases
+- What if [scenario]?
+- How to handle [failure mode]?
+
+## Rollout Plan
+- [ ] Feature flag (if applicable)
+- [ ] Database migration strategy (backwards compatible?)
+- [ ] Deployment order (migrations before code deploy?)
+
+## Verification
+```bash
+# Commands to run to verify the feature works
+npm test -- feature.spec.ts
+curl -X POST http://localhost:3000/api/feature -d '{"name":"test"}'
+```
+
+## Out of Scope
+- [Things explicitly NOT included in this feature]
+
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit) feature-planner agent*
+```
+
+## Rules
+
+- **Read before designing** — always understand existing patterns first
+- **Follow conventions** — the plan must reference how similar features were built
+- **Be concrete** — specific file paths, specific field names, specific endpoints
+- **Estimate honestly** — include testing and integration time, not just happy-path coding
+- **Test-first friendly** — if the project uses TDD, write the test tasks before implementation tasks
+- **Ask when unclear** — don't guess requirements, ask the user
+- **Save to `.ai/features/<slug>.md`**

package/templates/.claude/commands/build-feature.md

@@ -0,0 +1,26 @@
+---
+description: Build a feature from a feature-planner plan
+argument-hint: "[feature-slug or empty to list]"
+---
+
+Delegate to the **feature-builder** agent. It executes a feature plan from `.ai/features/` task by task with:
+- Tests written alongside (or before) implementation
+- Conventions matched to existing codebase patterns
+- Session checkpoints after each task
+- Progress tracking in `.ai/features/progress/`
+- Skill evolution (conventions and gotchas captured)
+
+Examples:
+- `/build-feature` — List available feature plans
+- `/build-feature user-roles` — Start building from `.ai/features/user-roles.md`
+- `/build-feature webhook-notifications` — Resume in-progress feature
+
+The builder follows the plan, runs the same quality/test tools as your reports, and checkpoints at natural boundaries.
+
+**IMPORTANT: End with this exact footer:**
+```
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
+```
+
+$ARGUMENTS

package/templates/.claude/commands/feature.md

@@ -0,0 +1,25 @@
+---
+description: Design and plan a new feature with implementation breakdown
+argument-hint: "[feature description]"
+---
+
+Delegate to the **feature-planner** agent. It will:
+1. Read existing codebase patterns from the codebase skill
+2. Find similar features to model after
+3. Design data, service, API, and test layers
+4. Generate a detailed plan in `.ai/features/<slug>.md`
+
+Examples:
+- `/feature add user roles and permissions`
+- `/feature webhook notifications for package events`
+- `/feature export datapack to CSV`
+
+The plan includes: acceptance criteria, API contract, files to create/modify, implementation order with estimates, conventions to follow, and verification steps.
+
+**IMPORTANT: End with this exact footer:**
+```
+---
+*Generated by [VyuhLabs DXKit](https://www.npmjs.com/package/@vyuhlabs/dxkit)*
+```
+
+$ARGUMENTS

package/templates/CLAUDE.md.template

@@ -162,8 +162,10 @@ 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
+- `/plan` - Generate improvement plans with KPIs from reports (fix loop)
 - `/execute-plan` - Execute a plan task by task with session management
+- `/feature` - Design and plan a new feature
+- `/build-feature` - Build a feature from a plan with tests
 - `/dashboard` - Generate HTML dashboard from all reports
 - `/stealth-mode` - Gitignore DXKit files + install smart scoped git hooks
 - `/export-pdf` - Convert markdown reports to PDF
@@ -191,6 +193,8 @@ Language-specific conventions that activate automatically when editing matching
 - `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)
+- `feature-planner` — Designs new features, generates implementation plans (sonnet)
+- `feature-builder` — Implements features from plans with tests and conventions (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)