@eltonssouza/development-utility-kit 0.10.0

package/README.md

@@ -0,0 +1,412 @@
+# development-utility-kit
+
+> Meta-skill harness for Claude Code. Generic agents by domain, knowledge packs by stack, single-`npx` injection into any project.
+
+[![npm](https://img.shields.io/npm/v/@eltonssouza/development-utility-kit)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit)
+[![beta](https://img.shields.io/npm/v/@eltonssouza/development-utility-kit/beta?label=beta)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit?activeTab=versions)
+[![downloads](https://img.shields.io/npm/dt/@eltonssouza/development-utility-kit)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit)
+[![license](https://img.shields.io/npm/l/@eltonssouza/development-utility-kit)](LICENSE)
+[![stars](https://img.shields.io/github/stars/eltonssouza/development-utility-kit?style=social)](https://github.com/eltonssouza/development-utility-kit/stargazers)
+[![issues](https://img.shields.io/github/issues/eltonssouza/development-utility-kit)](https://github.com/eltonssouza/development-utility-kit/issues)
+[![roadmap](https://img.shields.io/badge/roadmap-public-blue)](ROADMAP.md)
+[![comparisons](https://img.shields.io/badge/comparisons-honest-orange)](docs/COMPARISONS.md)
+
+CLI binary: `duk` · Node `>=18` · License: MIT
+
+---
+
+## What it is
+
+Not an agent. Not a skill. The **bundle** that turns any repo into a Claude-Code-driven project — with:
+
+- **20 keyword-triggered skills** (front-controller `project-manager`, `run-sprint`, `auto-test-guard`, `pair-debug`, `grill-me`, `to-prd`, `to-issues`, `quick-feature`, `brain-keeper`, `stack-discovery`, `create-stack-pack`, `quality-standards`, `caveman`, etc.)
+- **21 specialized sub-agents** (1 Opus for `tech-lead`, 3 Haiku for mechanical work, 17 Sonnet for everything else)
+- **5 stack knowledge packs** (Java + Spring Boot 3/4, Angular 18/19/21) — extend with `create-stack-pack` skill
+- **Full discovery → delivery pipeline** (`grill-me → to-prd → to-issues → analyst → run-sprint`) with mandatory TDD
+- **Local sub-agent telemetry** (`SubagentStop` hook → SQLite) + **web dashboard** (Express + Vanilla JS + Chart.js CDN)
+- **Non-negotiable Senior+ quality gate** (coverage ≥85%, mutation ≥70%, Lighthouse ≥0.80, a11y 0 critical)
+- **Autonomy Matrix**: agents decide on their own; human is interrupted only in 4 PO cases or 3 TL cases
+- **Drift detection** via `.claude/.MANIFEST` (sha256 per file) — `duk install` refuses to overwrite local modifications without `--force`
+
+> v2.0.0+ introduces **stack-agnostic agents** consuming knowledge packs at `.claude/stacks/<lang>/<framework>-<major>.md`. The pre-1.0 era of hardcoded Java/Angular agents is gone — agents now adapt to the declared stack via `STACK CONTEXT` injection (ADR-026).
+
+---
+
+## Why use it
+
+| Strength | Detail |
+|---|---|
+| **Zero-friction injection** | `duk install` in the project directory. No clone, no git, no boilerplate. |
+| **Stack-agnostic agents** | `backend-developer`, `frontend-developer`, `mobile-developer`, etc. read `## Project Identity` and consume the matching stack pack. Works on Java, TypeScript, Python, Go, etc. |
+| **Knowledge packs by version** | Java SB3 vs SB4 vs SB5 each get their own `## Code patterns`, `## Security`, `## Anti-patterns` section. No pack? `create-stack-pack` skill generates one conversationally. |
+| **Auto stack detection** | `detect-stack.js` parses `pom.xml`, `package.json`, `pyproject.toml`, `go.mod`, `docker-compose.yml`. |
+| **Idempotent install + drift detection** | Previous `.claude/` becomes `.claude.bak-<timestamp>/`. `.MANIFEST` (sha256) detects local modifications and refuses unsafe overwrites. `## Project Identity` preserved verbatim. |
+| **Local overrides via `.claude/local/`** | Project-specific tweaks live there. Never touched by `duk install`. Loader priority: `local/` wins over harness. |
+| **Aggressive autonomy by design** | Agents never ask permission for routine. PO/TL hold decision power; specialists never escalate directly to human. |
+| **Universal TDD** | `sprint-runner` enforces `qa-engineer (failing test) → developer → gate-keeper` on every task. ADR-020. |
+| **Obsidian-ready brain** | `brain-keeper` provisions `docs/brain/` with vault, color snippets, MOC, ADRs, daily, features, bugs, tech-debt, migrations. |
+| **Caveman mode by default** | ~65–75% cheaper output in tokens, no technical loss. ULTRA in code, FULL in `.md`. Credit: [@JuliusBrussee](https://github.com/JuliusBrussee). |
+| **No build for dashboard** | Vanilla JS + Chart.js via CDN. Tiny tarball. ADR-014. |
+
+---
+
+## How it works
+
+### 3-layer architecture
+
+```
+User prompt
+    │
+    ▼
+┌─────────────────────────────┐
+│  SKILLS (entry point)       │  keyword match
+│  .claude/skills/<X>/SKILL.md│  → specific skill OR
+└─────────────┬───────────────┘    project-manager (front-controller)
+              │
+              ▼  Step 0 (orchestrating skills)
+┌─────────────────────────────┐
+│  stack-resolver (Haiku)     │  reads ## Project Identity
+│  reads .claude/stacks/<pack>│  returns STACK CONTEXT block
+└─────────────┬───────────────┘
+              │
+              ▼  Task tool dispatch (with STACK CONTEXT inlined)
+┌─────────────────────────────┐
+│  AGENTS (executors)         │  21 specialized agents
+│  .claude/agents/<X>.md      │  Opus | Sonnet | Haiku per matrix
+└─────────────┬───────────────┘
+              │
+              ▼
+   Artifact (code, ADR, PRD, plan, test, deploy)
+```
+
+Skill = entry point + multi-step protocol. Agent = executor with tools. Pack = stack-specific knowledge consumed by agents. No loose commands.
+
+### Discovery → delivery flow
+
+```
+grill-me          → docs/discovery/DISCOVERY_<NAME>.md
+   ↓
+to-prd            → docs/prd/PRD_<NAME>.md
+   ↓
+to-issues         → docs/issues/ISSUES_<NAME>.md   (gh issue create-ready)
+   ↓
+analyst           → docs/plans/PLAN_<NAME>.md       (goal-ready DoD)
+   ↓
+run-sprint        → sprint-runner (mandatory TDD, Stage 0 stack-resolver)
+   ↓
+gate-keeper       → Senior+ gate (coverage, mutation, a11y, lighthouse, pyramid)
+   ↓
+brain-keeper      → docs/brain/ (daily, feature, ADR, bug, tech-debt, migration, MOC)
+```
+
+For small features that don't justify the full pipeline (adding a field, fixing a search, exporting CSV): use `quick-feature` skill — bypasses discovery/PRD/issues, generates minimal PLAN, dispatches `run-sprint` directly. TDD + Senior+ gate still mandatory.
+
+### Flow governance
+
+Every prompt passes through `flow-guard.js` (UserPromptSubmit hook) before reaching the model. It injects `[FLOW STATE]`, classifies the lane (greenfield / brownfield / sprint / small-task), and hard-blocks qualified implementation work that is missing its prerequisite artifact (DISCOVERY_*.md or PLAN_*.md). Bypass is audited in `.flow-state.json`.
+
+`project-manager` is the universal front-controller: classifies the lane, enforces the stage order, then dispatches (ROUTE → 1 specialist | ORCHESTRATE → ≤5 parallel with a shared `run_group_id` | ESCALATE → `sprint-runner`).
+
+### Telemetry + Dashboard
+
+```
+Claude Code ─► UserPromptSubmit ─► flow-guard.js   (lane classify + block)
+            │
+            └► SubagentStop hook ─► subagent-telemetry.sh ─► telemetry-writer.js
+                                                                  │
+                                                                  ▼
+                                                    ~/.claude/telemetry.db (SQLite)
+                                                         events + orchestration_runs
+                                                                  │
+                        ┌─────────────────────────────────────────┘
+                        ▼
+              duk dashboard  →  Express @ :4242+  →  Vanilla JS UI
+                               /api/stats
+                               /api/projects
+                               /api/projects/processes   (run-groups + agent children)
+                               /api/rtk                  (rtk gain --format json)
+```
+
+Polling every 5s. Click a project → **Processes panel** shows recent orchestration run-groups, each expandable into its parallel agent fan (agent type, model, status). Phase A: completed runs. Phase B (live in-flight): deferred — no `SubagentStart` hook available in Claude Code today.
+
+---
+
+## Quickstart
+
+### Brand-new project
+
+```bash
+duk new my-app
+cd my-app
+# Open Cowork or Claude Code in this folder, then in chat:
+# > "sabatina pra projeto novo"
+# stack-discovery skill walks you through 8 questions to declare type, language,
+# framework, version, database, UI lib, domain.
+```
+
+### Existing project
+
+```bash
+cd <your-project>
+npx @eltonssouza/development-utility-kit install
+```
+
+Injects `.claude/`, `CLAUDE.md`, `.claude/HARNESS_VERSION`, `.claude/.MANIFEST`, `.claude/local/` placeholder. Detects stack automatically.
+
+**Preview before applying** (no writes):
+```bash
+duk install --check-only
+```
+
+Reports detected stack + local vs latest harness version + pack availability.
+
+**Override local modifications** (skip drift detection):
+```bash
+duk install --force
+```
+
+`.claude.backup-<timestamp>/` is always created.
+
+### Edit `## Project Identity` in `CLAUDE.md`
+
+The only section the project owns. All others are harness base and receive updates via `duk install` (with drift detection).
+
+```markdown
+## Project Identity
+
+- **Project name**: my-store
+- **Project type**: fullstack
+- **Primary stack**: Java 21 + Spring Boot 3.2
+- **Database**: PostgreSQL 17 + Redis 7
+- **Domain**: e-commerce
+- **Team size**: 3 fullstack
+```
+
+`stack-resolver` reads this and loads `.claude/stacks/java/spring-boot-3.md`. If pack absent for declared stack: dispatches `create-stack-pack` skill to author it conversationally.
+
+### Run the dashboard
+
+```bash
+duk dashboard            # auto-detects free port from 4242
+duk dashboard --port 5000
+duk dashboard --no-open  # skip browser launch
+```
+
+Before starting Express, prints `rtk gain` (token savings analytics). If `rtk` not in PATH: non-fatal warning, proceeds.
+
+### Update many projects at once
+
+```bash
+# Preview which projects would be updated:
+duk sync-all C:\development\source\projects
+
+# Apply with filters (AND logic between multiple --filter):
+duk sync-all C:\development\source\projects --filter stack:java --apply
+duk sync-all C:\development\source\projects --filter age:30d --apply
+duk sync-all C:\development\source\projects --filter harness-version:<2 --apply
+
+# Exclude specific projects:
+duk sync-all C:\development\source\projects --exclude prod-critical --apply
+```
+
+---
+
+## `duk` commands
+
+```
+duk new <name>                                       # scaffold new project + open conversational discovery
+duk install [--sub <dir>] [--dry-run] [--check-only] [--force]
+                                                     # inject harness into CWD (idempotent)
+duk update                                           # alias of install
+duk sync-all <dir> [--filter <expr>]* [--exclude <name>]* [--apply]
+                                                     # update harness in many projects
+duk dashboard [--port <n>] [--no-open]               # launch local dashboard
+duk doctor [--strict] [--json]                       # validate environment (Node, git, hooks, packs)
+duk lint [--category <name>] [--json]                # validate harness .claude/ structure
+duk help [command]                                   # general help or command-specific
+duk --version                                        # print version
+```
+
+See `duk help <command>` for detailed per-command flags. The `doctor` and
+`lint` commands are deterministic and run without any LLM/API calls — safe
+to use in CI. See **ADR-034** for the design principle behind them.
+
+---
+
+## Prompts that trigger skills
+
+| You say | Skill fires |
+|---|---|
+| "sabatina pra projeto novo", "stack discovery" | `stack-discovery` → fills `## Project Identity` |
+| "cria pack para Django", "gera pack" | `create-stack-pack` → new `.claude/stacks/<lang>/<framework>-<major>.md` |
+| "grill me", "interview me about X" | `grill-me` → discovery interview |
+| "to-prd", "generate PRD" | `to-prd` (after `grill-me`) |
+| "to-issues", "break into issues" | `to-issues` (after `to-prd`) |
+| "run sprint 2", "execute the sprint" | `run-sprint` (Stage 0 stack-resolver) |
+| "quick-feature: add field X" | `quick-feature` → bypass discovery, minimal PLAN, run-sprint |
+| "pair debug", "investigate this bug" | `pair-debug` (Stage 0 stack-resolver) |
+| "audit coverage" | `test-coverage-auditor` |
+| "PRD-ready?", "ready for prod?" | `prd-ready-check` |
+| "create endpoint", "build the screen", anything else | `project-manager` (front-controller — classifies lane, enforces flow) |
+| "stop caveman", "normal mode" | disables caveman |
+
+---
+
+## Senior+ Quality Gate
+
+Non-negotiable. `gate-keeper` blocks merge if any item fails. **Thresholds are universal across stacks**; tooling specifics (JaCoCo vs coverage.py, JUnit vs pytest, etc.) come from the active stack pack:
+
+| Metric | Threshold |
+|---|---|
+| Backend coverage (lines / branches) | ≥85% / ≥80% |
+| Backend mutation score | ≥70% in domain + application layers |
+| Frontend coverage | ≥85% statements, ≥80% branches |
+| Static analysis (SpotBugs / mypy / golangci-lint / ESLint strict / ...) | 0 CRITICAL, 0 HIGH |
+| Dependency vuln scan (OWASP DC / npm audit / safety / govulncheck) | 0 CVE CVSS ≥7.0 |
+| Playwright E2E | 100% green, console 0 errors |
+| a11y (jest-axe + axe-playwright) | 0 serious, 0 critical |
+| Lighthouse | score ≥0.80, LCP ≤2500ms, CLS ≤0.1, TBT ≤300ms |
+| Testing pyramid | E2E ≤30% of total (ideal ≤15%) |
+
+Reference: ADR-007 (a11y + Lighthouse + pyramid), ADR-027 (pack `## Security` mandatory).
+
+---
+
+## Structure
+
+```
+development-utility-kit/
+├── .claude/
+│   ├── skills/      # 20 skills (catch-all, run-sprint, stack-discovery, create-stack-pack, ...)
+│   ├── agents/      # 21 agents (Opus/Sonnet/Haiku per matrix)
+│   ├── stacks/      # 5 stack packs (java/spring-boot-3, spring-boot-4; typescript/angular-18,19,21)
+│   │   ├── _template.md
+│   │   ├── README.md
+│   │   ├── CODEOWNERS
+│   │   ├── java/
+│   │   └── typescript/
+│   └── settings.json
+├── bin/
+│   ├── cli.js       # zero-deps `duk` CLI router (Node 18+)
+│   └── lib/         # 8 helper modules (detect-stack, version-check, sync-all, manifest, ...)
+├── dashboard/
+│   ├── server.js    # Express + 3 endpoints
+│   ├── db.js        # better-sqlite3 / sql.js wrapper
+│   ├── rtk.js       # spawns rtk gain --format json
+│   └── public/      # Vanilla JS + Chart.js CDN
+├── scripts/
+│   ├── hooks/
+│   │   ├── subagent-telemetry.sh    # SubagentStop hook
+│   │   └── telemetry-writer.js      # triple-fallback writer
+│   ├── lint-harness.mjs             # validates Pattern 1/2, packs, agent hardcode, drift
+│   └── latest-versions.json         # offline fallback for version detection
+├── docs/
+│   ├── brain/       # Obsidian vault (features, decisions, daily, bugs, migrations)
+│   ├── discovery/   # DISCOVERY_*.md
+│   ├── prd/         # PRD_*.md
+│   ├── issues/      # ISSUES_*.md
+│   └── plans/       # PLAN_*.md
+├── tests/smoke/     # smoke tests (install, dashboard, telemetry)
+├── .github/workflows/
+│   ├── publish.yml             # auto-publish on GitHub Release published
+│   └── promote-dist-tag.yml    # manual: promote beta → latest via Actions UI
+├── CLAUDE.md        # base template (Project Identity + plugin base)
+├── CHANGELOG.md     # release-please-managed
+└── package.json
+```
+
+---
+
+## Key ADRs
+
+| ADR | Decision |
+|---|---|
+| **ADR-007** | Senior+ gate (a11y + Lighthouse + pyramid thresholds) |
+| **ADR-008** | Standard pipeline (PO → analyst → tech-lead → sprint-runner → gate-keeper → reviewer → TL) |
+| **ADR-011** | `grill-me` as opt-in discovery skill |
+| **ADR-014** | Vanilla JS + Chart.js CDN dashboard |
+| **ADR-015** | Triple-fallback telemetry writer |
+| **ADR-017** | `DISCOVERY_*.md` in `docs/discovery/` (not `docs/plans/`) |
+| **ADR-018** | `duk` CLI redesign — `install → adoptProject` |
+| **ADR-020** | Mandatory TDD in `sprint-runner` |
+| **ADR-026** | Generic agents + stack packs (architecture foundation) |
+| **ADR-027** | Pack governance (frontmatter + `## Security` mandatory + CODEOWNERS + annual review) |
+| **ADR-028** | `duk` workflow (new, install --check-only, sync-all with filters, help) |
+| **ADR-029** | Canonical pack format (10 sections, 300-450L target) |
+| **ADR-030** | Migrator consumes 2 packs (FROM + TO), multi-major incremental, fullstack sequential |
+| **ADR-032** | Drift detection (`.MANIFEST`) + `.claude/local/` overrides + opt-in propagation |
+| **ADR-033** | `project-manager` orchestrate mode (ROUTE / ORCHESTRATE ≤5 / ESCALATE) — fast-lane for ad-hoc multi-domain tasks without a formal `PLAN_*.md` |
+| **ADR-034** | CLI vs Skill design principle — mechanical/deterministic → `duk` CLI; contextual/judgment → chat (skills + agents); hybrid → CLI executes + skill orchestrates |
+
+Full vault under [`docs/brain/`](docs/brain/) — browse via Obsidian. Live ADR index also rendered at `duk dashboard` → Tech Docs tab.
+
+---
+
+## Commit restrictions (NON-NEGOTIABLE)
+
+- Conventional Commits (`feat(scope): ...`, `fix(scope): ...`, `feat!: ...` for breaking)
+- **Never** reference Anthropic, Claude, AI, LLM, or assistant in subject/body/trailers
+- **Never** add `Co-Authored-By: Claude`
+- Commits must look 100% authored by the human developer
+- `tech-lead` rejects merge on violation
+
+---
+
+## Acknowledgements
+
+`development-utility-kit` is a **meta-skill harness** — it ships its own skills and agents, but it also stands on the shoulders of skills built by other people in the Claude Code community. The bundle would not work the way it does without them, and the credit belongs to their authors.
+
+Honest thanks to:
+
+- **[`grill-me`](https://github.com/mattpocock/skills)** — by **[Matt Pocock](https://github.com/mattpocock)** ([aihero.dev](https://www.aihero.dev/my-grill-me-skill-has-gone-viral)). The relentless discovery interview that opens our `grill-me → to-prd → to-issues → analyst → run-sprint` pipeline is Matt's design. We adapted the skill to persist its output to `docs/discovery/DISCOVERY_*.md` and hand off to `analyst`, but the interview mechanic — one decision branch at a time, with a recommended answer the user just confirms — is his.
+- **[`caveman`](https://github.com/JuliusBrussee/caveman)** — by **[Julius Brussee](https://github.com/JuliusBrussee)**. The telegraphic communication mode that saves us 65–75% of output tokens with zero technical loss. We use it as the default style in this harness; the compression rules, the levels (lite/full/ultra), and the auto-clarity carve-outs are Julius's work.
+- **[`impeccable`](https://github.com/pbakaus/impeccable)** — by **[Paul Bakaus](https://github.com/pbakaus)**. The design-refinement skill (`polish | harden | audit`) that drives our visual-quality gate. Paul's `npx skills add pbakaus/impeccable` distribution pattern also directly inspired our own `npx @eltonssouza/development-utility-kit install` installer (ADR-018).
+- **[`rtk`](https://github.com/rtk-ai/rtk)** — by the **[rtk-ai](https://github.com/rtk-ai) team**. The Rust Token Killer CLI proxy that powers the live "RTK savings" widget on the `duk dashboard` (`rtk gain --format json` → `/api/rtk`). The 60–90% savings on dev operations we surface in the dashboard are RTK's, not ours.
+
+If you build on top of this harness, please give these projects a star — they are the load-bearing dependencies our pipeline assumes, and their authors made them available freely to the community. Any mistake in the way we integrate or describe their work is ours, not theirs.
+
+> For the full rationale on **why each plugin was selected**, **how it integrates inside the harness**, **what breaks if you disable it**, and **alternatives considered**, see the dedicated [External plugins reference](dashboard/public/content/docs/plugins.en.md) — also rendered live at `duk dashboard` → Tech Docs → "External plugins".
+
+---
+
+## Release Process
+
+Releases ship through GitHub Actions, not manual `npm publish`.
+
+### Publishing a new version
+
+1. Bump `package.json` version (e.g., `2.0.0-beta.1 → 2.0.0`) and update `CHANGELOG.md`.
+2. Commit + push + tag:
+   ```bash
+   git commit -m "feat!: <summary>"
+   git tag v2.0.0
+   git push origin <branch> --tags
+   ```
+3. Create a GitHub Release pointing at the tag (UI or `gh release create`).
+4. `publish.yml` workflow fires on `release: published`, runs `npm publish --access public`.
+5. `publishConfig.tag` in `package.json` controls dist-tag target (`beta` or `latest`).
+
+### Pre-release vs stable
+
+- Pre-releases use `--tag beta` (default in `publishConfig`). `npx @eltonssouza/development-utility-kit@beta install` pulls them.
+- After validating against real projects: **manually promote** to `latest` via the **Promote npm dist-tag** workflow (GitHub Actions → Run workflow → enter version + target tag).
+
+### Rollback
+
+If a release breaks something, rollback by re-pointing `latest` to the prior stable:
+
+```
+GitHub Actions → Promote npm dist-tag → version=1.0.1, tag=latest
+```
+
+Bad version stays published (npm doesn't allow real deletion past 72h), but no one downloads it via `npx` anymore.
+
+### Required secret
+
+The promote workflow needs a `NPM_TOKEN` repository secret — a **Granular Access Token** with read+write on `@eltonssouza/development-utility-kit`. Generated at https://www.npmjs.com/settings/eltonssouza/tokens.
+
+---
+
+## License
+
+MIT