kenmark-skills 1.0.3 → 1.0.6

package/README.md

@@ -6,18 +6,47 @@ Created by **Tanooj Mehra** and **Adwait Date**.
 
 ## What's included
 
+Skills are grouped by **use case**. Within each group, rows are in the order most teams run them.
+
+### Onboard a project (start here)
+
 | Skill | Purpose |
 | --- | --- |
 | [`init-brain`](skills/user-skills/init-brain/SKILL.md) | Bootstrap `brain/` and sync project standards to `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.cursor/rules/` |
-| [`skill-router`](skills/user-skills/skill-router/SKILL.md) | Pick the best installed user skill from intent and keywords |
+| [`skills-init`](skills/user-skills/skills-init/SKILL.md) | First-time CLI wizard: Kenmark skills + optional curated packs (interactive; use `npx kenmark-skills init`) |
+| [`skills-router`](skills/user-skills/skills-router/SKILL.md) | Pick the best installed user skill from intent and keywords |
+
+### Ship changes
+
+| Skill | Purpose |
+| --- | --- |
 | [`commit-push`](skills/user-skills/commit-push/SKILL.md) | Group changes by feature, write conventional commits, push (no co-author trailers) |
+
+### Issue tracking (`issues-*`)
+
+Requires **`init-brain`** (or at least `brain/issues/` from **`issues-setup`**).
+
+| Skill | Purpose |
+| --- | --- |
 | [`issues-setup`](skills/user-skills/issues-setup/SKILL.md) | Create `brain/issues/` layout and `INDEX.md` |
 | [`issues-list`](skills/user-skills/issues-list/SKILL.md) | Dashboard of open issues by area and priority |
 | [`issues-check`](skills/user-skills/issues-check/SKILL.md) | Move resolved issues to `completed/` and refresh the index |
 | [`issues-scan`](skills/user-skills/issues-scan/SKILL.md) | Discover new issues in the codebase and file them under `brain/issues/` |
 | [`issues-maintenance`](skills/user-skills/issues-maintenance/SKILL.md) | Audit issue tracker health (duplicates, stale index, missing files) |
 
-These skills assume a **`brain/`** knowledge base (standards, changelog, optional issue tracker). Use **`init-brain`** first on a new repo, then the issues and git workflow skills as needed.
+### Skills library (`skills-*`)
+
+For installing, updating, and cleaning up skills on your machine (pairs with **`npx kenmark-skills`** commands).
+
+| Skill | Purpose |
+| --- | --- |
+| [`skills-install-recommended`](skills/user-skills/skills-install-recommended/SKILL.md) | Install curated third-party packs (Impeccable, ECC, …) with scope and pack selection |
+| [`skills-update`](skills/user-skills/skills-update/SKILL.md) | Refresh Kenmark skills and optionally reinstall recommended packs |
+| [`skills-maintain`](skills/user-skills/skills-maintain/SKILL.md) | Inventory installed skills, group duplicates, recommend keep vs remove (no auto-delete) |
+
+**Typical path:** `skills-init` or `npx kenmark-skills setup` → **`skills-install-recommended`** for curated packs → day-to-day **`skills-router`** → periodic **`skills-update`** / **`skills-maintain`**.
+
+These skills assume a **`brain/`** knowledge base (standards, changelog, optional issue tracker). On a new repo: **`init-brain`** → **`issues-setup`** if you track work in `brain/issues/` → **`commit-push`** when shipping.
 
 ## Requirements
 
@@ -26,14 +55,26 @@ These skills assume a **`brain/`** knowledge base (standards, changelog, optiona
 
 ## Install
 
+### Interactive-first CLI
+
+All `kenmark-skills` commands **prompt in the terminal by default** (TTY). For agents and scripts, pass explicit flags plus **`-y`** to skip prompts.
+
+| Command | Humans | Agents (example) |
+| --- | --- | --- |
+| `init` | `npx kenmark-skills init` | `npx kenmark-skills init --global --ide all -y` |
+| `setup` | `npx kenmark-skills setup` | `npx kenmark-skills setup --global --ide cursor -y` |
+| `install-recommended` | `npx kenmark-skills install-recommended` | `npx kenmark-skills install-recommended --ids impeccable,ecc --global -y` |
+| `update` | `npx kenmark-skills update` | `npx kenmark-skills update --both --global -y` |
+| `inventory` | `npx kenmark-skills inventory` | `npx kenmark-skills inventory --markdown ./report.md -y` |
+
 ### Option A — Global npm install (recommended)
 
 ```bash
 npm install -g kenmark-skills
-npx kenmark-skills setup
+npx kenmark-skills init
 ```
 
-`npx kenmark-skills setup` (or `kenmark-skills-setup`) auto-detects your platform and copies skills to detected global IDE paths:
+**`init`** walks through Kenmark skills + optional curated packs. For Kenmark-only copy, use **`setup`** (or `kenmark-skills-setup`), which auto-detects your platform and copies skills to detected global IDE paths:
 
 - Cursor: `~/.cursor/skills`
 - Codex/shared agents: `~/.agents/skills`
@@ -82,6 +123,47 @@ npx kenmark-skills setup --global --ide all
 
 If new Claude slash commands do not appear immediately, restart Claude Code.
 
+### Skills inventory and recommended installs
+
+Scan installed skills across common IDE paths and get a keep / dedupe / remove report:
+
+```bash
+npx kenmark-skills inventory
+npx kenmark-skills inventory --markdown ~/Desktop/skills-report.md --json ~/Desktop/skills-inventory.json
+npx kenmark-skills inventory --include-plugins
+```
+
+Install curated packs from [`recommended-catalog.json`](skills/user-skills/recommended-catalog.json) via **npx** (no git clone). Default is **global** install; use **project** for the current repo only.
+
+```bash
+npx kenmark-skills install-recommended --list
+
+# Interactive: scope → packs → ECC profile
+npx kenmark-skills install-recommended
+
+# Non-interactive
+npx kenmark-skills install-recommended --all --global -y
+npx kenmark-skills install-recommended --all --project -y
+npx kenmark-skills install-recommended --ids impeccable,ecc --global --ecc-profile core -y
+npx kenmark-skills install-recommended --dry-run --all --project
+```
+
+Use **`skills-maintain`** in chat for a guided cleanup workflow (no auto-delete). Use **`skills-install-recommended`** for first-time curated installs. Use **`skills-update`** to refresh after a package upgrade or repo pull.
+
+### Update installed skills
+
+Re-sync Kenmark skills (and optionally refresh recommended packs) without a full uninstall:
+
+```bash
+npx kenmark-skills update
+
+# Non-interactive
+npx kenmark-skills update --both --global -y
+npx kenmark-skills update --kenmark-only --global --ide all -y
+npx kenmark-skills update --recommended-only --global --ids impeccable,ecc -y
+npx kenmark-skills update --npm-only -y
+```
+
 ## Uninstall
 
 `npm uninstall -g kenmark-skills` removes only the CLI package; it does **not** remove skills already copied into your IDE folders.
@@ -136,8 +218,12 @@ Manual fallback (Claude global):
 
 ```bash
 rm -rf ~/.claude/skills/init-brain \
-       ~/.claude/skills/skill-router \
        ~/.claude/skills/commit-push \
+       ~/.claude/skills/skills-router \
+       ~/.claude/skills/skills-init \
+       ~/.claude/skills/skills-install-recommended \
+       ~/.claude/skills/skills-update \
+       ~/.claude/skills/skills-maintain \
        ~/.claude/skills/issues-setup \
        ~/.claude/skills/issues-list \
        ~/.claude/skills/issues-check \
@@ -167,9 +253,9 @@ npm run publish:public
    - "**issues-list**" or "list open issues"
 3. The agent should **read and follow** the full `SKILL.md` for that skill — not improvise from the description alone.
 
-### skill-router note
+### skills-router note
 
-`skill-router` builds a local registry at `skills/user-skills/skill-router/registry.json` when run from a checkout of this repo. That file is **gitignored** and **not** published to npm; it is per-machine generated state.
+`skills-router` builds a local registry at `skills/user-skills/skills-router/registry.json` when run from a checkout of this repo. That file is **gitignored** and **not** published to npm; it is per-machine generated state.
 
 ## Repository layout
 
@@ -182,9 +268,12 @@ kenmark-skills/
 └── skills/
     └── user-skills/          # Skills shipped in the npm package
         ├── init-brain/
-        ├── skill-router/
+        ├── skills-router/
         ├── commit-push/
-        └── issues-*/
+        ├── issues-*/
+        ├── skills-maintain/
+        ├── skills-install-recommended/
+        └── recommended-catalog.json
 ```
 
 ## Contributing

package/brain/CHANGELOG.md

@@ -1,5 +1,52 @@
 # CHANGELOG
 
+## v2026.06.02-2330-readme-skills-grouped
+
+- **README:** Reorganized "What's included" by use case — onboard, ship, `issues-*`, `skills-*` — with workflow order within each group.
+- **README:** Extended manual Claude uninstall `rm` list to include all `skills-*` skill folders.
+
+## v2026.06.02-2320-skills-maintain-interactive-docs
+
+- **skills-maintain:** document `skills-init`, interactive-first CLI, inventory TTY prompts, and `-y` for agents.
+- Synced `.cursor/` and `.claude/` copies for `skills-init`, `skills-install-recommended`, `skills-update`, `skills-maintain`.
+
+## v2026.06.02-2315-interactive-cli-init
+- **Interactive-first CLI:** all setup/install/init flows prompt in a TTY by default; agents use explicit flags + `-y` (or `KENMARK_SKILLS_NONINTERACTIVE=1`).
+- Added **`scripts/interactive.js`** shared prompts (scope, IDE, action, confirm).
+- **`setup-skills.js`:** interactive install/uninstall wizard; `-y`, `--dry-run`, comma-separated `--ide`.
+- **`skills-init.js`** + **`npx kenmark-skills init`:** first-time onboarding (Kenmark + optional recommended defaults).
+- **`skills-install-recommended.js`:** shared prompts, numbered pack selection, Enter = default packs.
+- **`skills-update.js`:** shared `promptScope` / `confirmPlan`.
+- **`skills-inventory.js`:** interactive output path choice; `-y` for agents.
+- New skill **`skills-init`**, README table, `package.json` `files` + `init` script.
+
+## v2026.06.02-2230-skills-update
+- Added **`skills-update`** skill and **`scripts/skills-update.js`**: interactive refresh for Kenmark skills, optional `npm update -g kenmark-skills`, and optional recommended-pack reinstall via npx.
+- CLI: `npx kenmark-skills update` with flags `--kenmark-only`, `--recommended-only`, `--both`, `--global`, `--project`, `--ide`, `--npm-only`, `--dry-run`, `-y`.
+- Wired `skills-update` into inventory `KEEP_ALWAYS`, README, and cross-links from **skills-maintain** / **skills-install-recommended**.
+
+## v2026.06.02-2200-recommended-catalog-npx-interactive
+- **recommended-catalog.json v2:** removed git-clone install paths; each pack defines `install.global` and `install.project` npx commands.
+- **Impeccable:** global `npx skills add pbakaus/impeccable -g -y`; project `npx impeccable skills install`.
+- **ECC:** `npx -p ecc-universal ecc-install` with profile `core` (default), targets `claude` (global) or `cursor` (project); documented single-path warning vs marketplace plugin.
+- **skills-install-recommended.js:** interactive scope (global/project), pack selection, ECC profile prompt; flags `--global`, `--project`, `--scope`, `--ecc-profile`.
+- Updated **skills-install-recommended** skill docs, README, and synced `.cursor`/`.claude` catalog copies.
+
+## v2026.06.02-2115-rename-skills-router
+- Renamed **`skill-router`** → **`skills-router`** for consistent `skills-*` Kenmark naming.
+- Registry path is now `skills/user-skills/skills-router/registry.json`; Claude slash command is `/kenmark-skills-router`.
+- After upgrading, remove old installs (`skill-router` folders and `kenmark-skill-router.md`) or re-run `npx kenmark-skills setup`.
+
+## v2026.06.02-2100-skills-maintain-and-recommended-install
+- Added **`skills-maintain`** skill: inventory installed `SKILL.md` trees, group by name, flag vendored mirrors (e.g. gstack), recommend keep vs remove — never auto-deletes.
+- Added **`skills-install-recommended`** skill and **`recommended-catalog.json`** with curated packs: [Impeccable](https://github.com/pbakaus/impeccable), [Everything Claude Code](https://github.com/affaan-m/everything-claude-code).
+- Added CLI commands: `npx kenmark-skills inventory` and `npx kenmark-skills install-recommended` (`--list`, `--all`, `--ids`, `--dry-run`, `-y`).
+- Published scripts: `scripts/skills-inventory.js`, `scripts/skills-install-recommended.js`.
+
+## v2026.06.02-2000-skill-description-normalization
+- Normalized skill frontmatter descriptions from YAML block style (`description: |`) to single-line `description: "..."` format.
+- Applied across all local `SKILL.md` files so skill descriptions render consistently in clients that expect inline description values.
+
 ## v2026.06.02-1955-uninstall-version-lag-troubleshooting
 - Added uninstall troubleshooting to README for `Unknown command: uninstall` caused by older `npx` package versions.
 - Documented explicit `npx kenmark-skills@latest` usage, npm cache clean fallback, and manual Claude cleanup commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kenmark-skills",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "Skills by Kenmark ITan Solutions — Cursor/Codex agent skills from our development workflows. Created by Tanooj Mehra & Adwait Date.",
   "license": "MIT",
   "private": false,
@@ -11,11 +11,21 @@
     "skills/COPIED_SKILLS.md",
     "brain/CHANGELOG.md",
     "scripts/setup-skills.js",
-    "scripts/cli.js"
+    "scripts/cli.js",
+    "scripts/interactive.js",
+    "scripts/skills-init.js",
+    "scripts/skills-inventory.js",
+    "scripts/skills-install-recommended.js",
+    "scripts/skills-update.js",
+    "skills/user-skills/recommended-catalog.json"
   ],
   "scripts": {
+    "init": "node scripts/cli.js init",
     "setup": "node scripts/cli.js setup",
     "uninstall:skills": "node scripts/cli.js uninstall",
+    "inventory": "node scripts/cli.js inventory",
+    "install-recommended": "node scripts/cli.js install-recommended",
+    "update": "node scripts/cli.js update",
     "setup:skills": "node scripts/setup-skills.js",
     "pack:check": "npm pack --dry-run",
     "publish:public": "npm publish --access public"

package/scripts/cli.js

@@ -9,16 +9,22 @@ const command = args[0];
 function printUsage() {
   console.log("kenmark-skills CLI");
   console.log("");
+  console.log("Interactive by default in a terminal (humans). Pass flags + -y for agents.");
+  console.log("");
   console.log("Usage:");
-  console.log("  kenmark-skills setup [--global|--project] [--ide <target>]");
-  console.log("  kenmark-skills uninstall [--global|--project] [--ide <target>]");
+  console.log("  kenmark-skills init [--global|--project] [--ide <target>] [--skip-recommended] [-y]");
+  console.log("  kenmark-skills setup [--global|--project] [--ide <target>] [-y]");
+  console.log("  kenmark-skills uninstall [--global|--project] [--ide <target>] [-y]");
+  console.log("  kenmark-skills inventory [--json path] [--markdown path] [--include-plugins]");
+  console.log("  kenmark-skills install-recommended [--list] [--all] [--ids a,b] [--global|--project] [-y]");
+  console.log("  kenmark-skills update [--kenmark-only|--recommended-only|--both] [--global|--project] [-y]");
   console.log("  kenmark-skills help");
   console.log("");
   console.log("Examples:");
+  console.log("  npx kenmark-skills init");
   console.log("  npx kenmark-skills setup");
-  console.log("  npx kenmark-skills setup --project --ide cursor");
-  console.log("  npx kenmark-skills setup --global --ide all");
-  console.log("  npx kenmark-skills uninstall --global --ide claude");
+  console.log("  npx kenmark-skills setup --project --ide cursor -y");
+  console.log("  npx kenmark-skills uninstall --global --ide claude -y");
 }
 
 if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -26,6 +32,14 @@ if (!command || command === "help" || command === "--help" || command === "-h")
   process.exit(0);
 }
 
+if (command === "init") {
+  const scriptPath = path.join(__dirname, "skills-init.js");
+  const result = spawnSync(process.execPath, [scriptPath, ...args.slice(1)], {
+    stdio: "inherit"
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
 if (command === "setup") {
   const scriptPath = path.join(__dirname, "setup-skills.js");
   const forwardedArgs = args.slice(1);
@@ -44,6 +58,30 @@ if (command === "uninstall") {
   process.exit(result.status === null ? 1 : result.status);
 }
 
+if (command === "inventory") {
+  const scriptPath = path.join(__dirname, "skills-inventory.js");
+  const result = spawnSync(process.execPath, [scriptPath, ...args.slice(1)], {
+    stdio: "inherit"
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+if (command === "install-recommended") {
+  const scriptPath = path.join(__dirname, "skills-install-recommended.js");
+  const result = spawnSync(process.execPath, [scriptPath, ...args.slice(1)], {
+    stdio: "inherit"
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+if (command === "update") {
+  const scriptPath = path.join(__dirname, "skills-update.js");
+  const result = spawnSync(process.execPath, [scriptPath, ...args.slice(1)], {
+    stdio: "inherit"
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
 console.error(`Unknown command: ${command}`);
 printUsage();
 process.exit(1);

package/scripts/interactive.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Shared interactive prompts for kenmark-skills CLI.
+ * Priority: interactive when stdin is a TTY and -y is not set.
+ * Agents should pass explicit flags plus -y to skip prompts.
+ */
+
+const readline = require("readline");
+
+const IDE_LABELS = {
+  cursor: "Cursor (.cursor/skills)",
+  claude: "Claude Code (.claude/skills)",
+  codex: "Codex (.agents/skills)",
+  gemini: "Gemini (.gemini/skills)",
+  opencode: "OpenCode (.opencode/skills)",
+  kiro: "Kiro (.kiro/skills)",
+  trae: "Trae (.trae/skills)",
+  "trae-cn": "Trae CN (.trae-cn/skills)",
+  rovo: "Rovo Dev (.rovodev/skills)",
+  qoder: "Qoder (.qoder/skills)"
+};
+
+function createRl() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (ans) => resolve(ans.trim())));
+}
+
+function wantsInteractive(parsed) {
+  if (parsed.yes) return false;
+  if (process.env.KENMARK_SKILLS_NONINTERACTIVE === "1") return false;
+  return Boolean(process.stdin.isTTY);
+}
+
+async function promptYesNo(message, defaultYes = true) {
+  const rl = createRl();
+  const hint = defaultYes ? "[Y/n]" : "[y/N]";
+  const answer = await ask(rl, `${message} ${hint} `);
+  rl.close();
+  if (!answer) return defaultYes;
+  const lower = answer.toLowerCase();
+  if (lower === "y" || lower === "yes") return true;
+  if (lower === "n" || lower === "no") return false;
+  return defaultYes;
+}
+
+async function promptScope(defaultScope = "global") {
+  const rl = createRl();
+  console.log("\nWhere should skills be installed?");
+  console.log("  1) global  — all projects on this machine (~/.cursor, ~/.claude, …) [default]");
+  console.log("  2) project — only this repo (.cursor/, .claude/, … in cwd)\n");
+  const answer = await ask(
+    rl,
+    `Choose scope [1/2 or global/project] (default ${defaultScope}): `
+  );
+  rl.close();
+  const lower = answer.toLowerCase();
+  if (!lower || lower === "1" || lower === "global" || lower === "g") return "global";
+  if (lower === "2" || lower === "project" || lower === "p") return "project";
+  console.log(`Using default scope: ${defaultScope}`);
+  return defaultScope;
+}
+
+async function promptAction(defaultAction = "install") {
+  const rl = createRl();
+  console.log("\nWhat do you want to do?");
+  console.log("  1) install   — copy Kenmark skills into IDE folders [default]");
+  console.log("  2) uninstall — remove Kenmark skills from IDE folders\n");
+  const answer = await ask(rl, "Choose [1/2 or install/uninstall] (default install): ");
+  rl.close();
+  const lower = answer.toLowerCase();
+  if (!lower || lower === "1" || lower === "install" || lower === "i") return "install";
+  if (lower === "2" || lower === "uninstall" || lower === "u") return "uninstall";
+  return defaultAction;
+}
+
+/**
+ * @param {string[]} availableIdes - keys from targetMap
+ * @param {string[]} detectedIdes - subset that exist on disk
+ */
+async function promptIde(availableIdes, detectedIdes) {
+  const rl = createRl();
+  console.log("\nWhich IDE / agent should receive skills?");
+  console.log("  0) auto — use detected installs only [default]");
+  console.log("  a) all  — every supported IDE path\n");
+  const sorted = [...availableIdes].sort();
+  sorted.forEach((ide, i) => {
+    const label = IDE_LABELS[ide] || ide;
+    const mark = detectedIdes.includes(ide) ? " ✓ detected" : "";
+    console.log(`  ${i + 1}) ${ide} — ${label}${mark}`);
+  });
+  console.log("");
+  const answer = await ask(
+    rl,
+    "Choose [0/auto, a/all, numbers like 1,2, or id names]: "
+  );
+  rl.close();
+
+  const lower = answer.toLowerCase();
+  if (!lower || lower === "0" || lower === "auto") {
+    return detectedIdes.length > 0 ? detectedIdes : ["cursor"];
+  }
+  if (lower === "a" || lower === "all") {
+    return sorted;
+  }
+
+  const picked = new Set();
+  const parts = lower.split(/[\s,]+/).filter(Boolean);
+  for (const part of parts) {
+    const num = parseInt(part, 10);
+    if (!Number.isNaN(num) && num >= 1 && num <= sorted.length) {
+      picked.add(sorted[num - 1]);
+      continue;
+    }
+    if (sorted.includes(part)) {
+      picked.add(part);
+    }
+  }
+  if (picked.size > 0) {
+    return [...picked];
+  }
+  console.log("No valid IDE choice; using auto-detect.");
+  return detectedIdes.length > 0 ? detectedIdes : ["cursor"];
+}
+
+async function confirmPlan(lines, dryRun = false) {
+  if (dryRun) return true;
+  const rl = createRl();
+  console.log("\nPlanned steps:");
+  for (const line of lines) {
+    console.log(`  • ${line}`);
+  }
+  const answer = await ask(rl, "\nProceed? [Y/n] ");
+  rl.close();
+  const lower = answer.toLowerCase();
+  if (!lower || lower === "y" || lower === "yes") return true;
+  return false;
+}
+
+function banner(title, subtitle) {
+  console.log(`\n${"═".repeat(60)}`);
+  console.log(`  ${title}`);
+  if (subtitle) console.log(`  ${subtitle}`);
+  console.log(`${"═".repeat(60)}\n`);
+}
+
+module.exports = {
+  IDE_LABELS,
+  createRl,
+  ask,
+  wantsInteractive,
+  promptYesNo,
+  promptScope,
+  promptAction,
+  promptIde,
+  confirmPlan,
+  banner
+};