ai-engineering-kit 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { basename as basename2 } from "path";
-import { intro, outro, confirm, select, isCancel as isCancel2, cancel as cancel2, log } from "@clack/prompts";
+import { basename as basename3 } from "path";
+import { intro, outro, confirm, select as select2, isCancel as isCancel2, cancel as cancel2, note } from "@clack/prompts";
 
 // src/catalog/load.ts
 import { readdirSync, readFileSync } from "fs";
@@ -22,29 +22,77 @@ function parseManifest(json) {
 
 // src/catalog/definition.ts
 var CATEGORIES = [
-  { id: "core-workflow", label: "Core workflow", from: "skills/core-workflow", to: "ai/skills" },
-  { id: "engineering", label: "Engineering", from: "skills/engineering", to: "ai/skills" },
-  { id: "productivity", label: "Productivity", from: "skills/productivity", to: "ai/skills" },
-  { id: "misc", label: "Misc", from: "skills/misc", to: "ai/skills" }
+  {
+    id: "core-workflow",
+    label: "Core workflow",
+    hint: "End-to-end loop: kickoff \u2192 PRD \u2192 plan \u2192 implement \u2192 review \u2192 verify",
+    from: "skills/core-workflow",
+    to: "ai/skills"
+  },
+  {
+    id: "engineering",
+    label: "Engineering",
+    hint: "Daily coding skills \u2014 TDD, debugging, triage, architecture (from mattpocock/skills)",
+    from: "skills/engineering",
+    to: "ai/skills"
+  },
+  {
+    id: "productivity",
+    label: "Productivity",
+    hint: "Workflow helpers \u2014 grilling, handoff, teaching, concise mode (from mattpocock/skills)",
+    from: "skills/productivity",
+    to: "ai/skills"
+  },
+  {
+    id: "misc",
+    label: "Misc",
+    hint: "Occasional utilities \u2014 git guardrails, pre-commit, scaffolding (from mattpocock/skills)",
+    from: "skills/misc",
+    to: "ai/skills"
+  }
 ];
 var TREE_COMPONENTS = [
-  { id: "docs-foundations", label: "docs/foundations scaffold", from: "docs/foundations", to: "docs/foundations" },
-  { id: "ai-workspace", label: "ai/ workspace dirs", from: "ai-workspace", to: "ai" }
+  {
+    id: "docs-foundations",
+    label: "Foundation docs",
+    hint: "Starter docs for product vision, guidelines, and technical decisions (docs/foundations/)",
+    from: "docs/foundations",
+    to: "docs/foundations"
+  },
+  {
+    id: "ai-workspace",
+    label: "Workspace folders",
+    hint: "Folders the skills write to: brainstorms, PRDs, plans, reviews (ai/)",
+    from: "ai-workspace",
+    to: "ai"
+  }
 ];
 var COMPONENTS = [
-  { id: "skills", label: "Skills", unlocks: "categories" },
-  ...TREE_COMPONENTS.map((t) => ({ id: t.id, label: t.label })),
-  { id: "entry-files", label: "Agent entry files", unlocks: "agents" }
+  {
+    id: "skills",
+    label: "Skills",
+    hint: "Reusable AI playbooks the agent runs on demand (plan, implement, review, debug\u2026)",
+    unlocks: "categories"
+  },
+  ...TREE_COMPONENTS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+  {
+    id: "entry-files",
+    label: "Agent entry files",
+    hint: "Instruction files that wire your coding agent to the skills (CLAUDE.md / AGENTS.md)",
+    unlocks: "agents"
+  }
 ];
 var AGENTS = [
   {
     id: "claude-code",
     label: "Claude Code",
+    hint: "Adds CLAUDE.md + a .claude/skills/ symlink for native skill discovery",
     files: [{ from: "agents/claude-code.CLAUDE.md", to: "CLAUDE.md", substitute: true }]
   },
   {
     id: "codex",
     label: "Codex",
+    hint: "Adds AGENTS.md referencing ai/skills/",
     files: [{ from: "agents/codex.AGENTS.md", to: "AGENTS.md", substitute: true }]
   }
 ];
@@ -114,6 +162,31 @@ function resolveSelection(catalog, selection) {
   });
 }
 
+// src/menu/summary.ts
+import { basename } from "path";
+var labelOf = (id) => COMPONENTS.find((c) => c.id === id)?.label ?? id;
+function summarize(files, plan) {
+  const byPath = new Map(files.map((f) => [f.targetPath, f]));
+  const groups = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  let written = 0;
+  for (const action of plan.actions) {
+    if (action.type === "conflict") {
+      conflicts.push(action.path);
+      continue;
+    }
+    if (action.type !== "add" && action.type !== "refresh") continue;
+    const file = byPath.get(action.path);
+    if (!file) continue;
+    written++;
+    const group = groups.get(file.component) ?? groups.set(file.component, { component: file.component, label: labelOf(file.component), count: 0, names: [] }).get(file.component);
+    group.count++;
+    if (file.component === "entry-files") group.names.push(basename(file.targetPath));
+  }
+  const ordered = COMPONENTS.map((c) => groups.get(c.id)).filter((g) => g !== void 0);
+  return { groups: ordered, conflicts, written };
+}
+
 // src/planner/planner.ts
 function planInstall(input) {
   const files = resolveSelection(input.catalog, input.selection);
@@ -290,18 +363,25 @@ On Windows, enable Developer Mode (or run as admin) and re-run, or point Claude
 }
 
 // src/menu/prompt.ts
-import { basename } from "path";
-import { multiselect, text, isCancel, cancel } from "@clack/prompts";
+import { basename as basename2 } from "path";
+import { select, multiselect, text, isCancel, cancel } from "@clack/prompts";
 
 // src/menu/menu.ts
 function componentOptions() {
-  return COMPONENTS.map((c) => ({ value: c.id, label: c.label }));
+  return COMPONENTS.map((c) => ({ value: c.id, label: c.label, hint: c.hint }));
 }
 function categoryOptions() {
-  return CATEGORIES.map((c) => ({ value: c.id, label: c.label }));
+  return CATEGORIES.map((c) => ({ value: c.id, label: c.label, hint: c.hint }));
 }
 function agentOptions() {
-  return AGENTS.map((a) => ({ value: a.id, label: a.label }));
+  return AGENTS.map((a) => ({ value: a.id, label: a.label, hint: a.hint }));
+}
+function presetSelection(preset) {
+  return {
+    components: COMPONENTS.map((c) => c.id),
+    categories: preset === "everything" ? CATEGORIES.map((c) => c.id) : ["core-workflow"],
+    agents: AGENTS.map((a) => a.id)
+  };
 }
 function buildSelection(answers) {
   return {
@@ -319,42 +399,31 @@ function required(value) {
   }
   return value;
 }
+async function pick(message, options) {
+  return required(await multiselect({ message, options, required: true }));
+}
+async function chooseSelection() {
+  const components = await pick("Select parts to install", componentOptions());
+  const categories = components.includes("skills") ? await pick("Select skill categories", categoryOptions()) : [];
+  const agents = components.includes("entry-files") ? await pick("Select coding agents", agentOptions()) : [];
+  return buildSelection({ components, categories, agents });
+}
 async function promptForSelection(projectDir) {
-  const components = required(
-    await multiselect({
-      message: "Which parts do you want to install?",
-      options: componentOptions(),
-      required: true
-    })
-  );
-  let categories = [];
-  if (components.includes("skills")) {
-    categories = required(
-      await multiselect({
-        message: "Which skill categories?",
-        options: categoryOptions(),
-        required: true
-      })
-    );
-  }
-  let agents = [];
-  if (components.includes("entry-files")) {
-    agents = required(
-      await multiselect({
-        message: "Which coding agents?",
-        options: agentOptions(),
-        required: true
-      })
-    );
-  }
-  const projectName = required(
-    await text({
-      message: "Project name",
-      defaultValue: basename(projectDir),
-      placeholder: basename(projectDir)
+  const mode = required(
+    await select({
+      message: `How do you want to set up ${basename2(projectDir)}?`,
+      options: [
+        { value: "everything", label: "Everything", hint: "all skills, docs, and workspace \u2014 Claude Code + Codex" },
+        { value: "core", label: "Core skills only", hint: "core-workflow skills, docs, and workspace \u2014 both agents" },
+        { value: "choose", label: "Choose what to install\u2026", hint: "pick components, skill categories, and agents" }
+      ]
     })
   );
-  return { selection: buildSelection({ components, categories, agents }), projectName };
+  const selection = mode === "choose" ? await chooseSelection() : presetSelection(mode);
+  const projectName = selection.components.includes("entry-files") ? required(
+    await text({ message: "Project name", defaultValue: basename2(projectDir), placeholder: basename2(projectDir) })
+  ) : basename2(projectDir);
+  return { selection, projectName };
 }
 
 // src/applier/update.ts
@@ -506,7 +575,29 @@ function planFor(projectDir, selection) {
     onDisk: readOnDiskHashes(projectDir, files),
     manifest: readManifest(projectDir)
   });
-  return { catalog, plan };
+  return { catalog, files, plan };
+}
+function formatSummary(summary) {
+  if (summary.written === 0 && summary.conflicts.length === 0) return "Everything is already up to date.";
+  const width = Math.max(0, ...summary.groups.map((g) => g.label.length));
+  const lines = summary.groups.map((g) => {
+    const detail = g.names.length > 0 ? g.names.join(", ") : String(g.count);
+    return `  ${g.label.padEnd(width)}  ${detail}`;
+  });
+  if (summary.conflicts.length > 0) {
+    lines.push("", `Conflicts \u2014 you edited these (you'll choose per file):`);
+    for (const path of summary.conflicts) lines.push(`  ${path}`);
+  }
+  return lines.join("\n");
+}
+function successOutro(verb, written, selection) {
+  if (selection.components.includes("skills")) {
+    note(
+      "Open your coding agent in this project and run a skill:\n  setup-foundations   fill in docs/foundations\n  kickoff             brainstorm an MVP",
+      "Next steps"
+    );
+  }
+  outro(`${verb} ${written} file${written === 1 ? "" : "s"}.`);
 }
 function reportConflict(error) {
   if (!(error instanceof ApplyConflictError)) return false;
@@ -526,7 +617,7 @@ function dryRun(args) {
 function init(args) {
   const projectDir = process.cwd();
   const selection = selectionFromArgs(args);
-  const projectName = parseValue(args, "--name") ?? basename2(projectDir);
+  const projectName = parseValue(args, "--name") ?? basename3(projectDir);
   try {
     const result = runInit({ projectDir, selection, projectName });
     console.log(`ai-engineering-kit ${kitVersion()} installed into ${projectDir}`);
@@ -546,7 +637,7 @@ async function runReRun(projectDir) {
   const manifest = readManifest(projectDir);
   intro(`ai-engineering-kit ${kitVersion()} \u2014 already installed`);
   const mode = bail(
-    await select({
+    await select2({
       message: "What would you like to do?",
       options: [
         { value: "update", label: "Update installed parts to latest" },
@@ -556,7 +647,7 @@ async function runReRun(projectDir) {
     })
   );
   let addParts = EMPTY_SELECTION;
-  let projectName = basename2(projectDir);
+  let projectName = basename3(projectDir);
   if (mode === "add" || mode === "both") {
     const picked = await promptForSelection(projectDir);
     addParts = picked.selection;
@@ -566,24 +657,27 @@ async function runReRun(projectDir) {
   const applicable = {
     actions: prepared.plan.actions.filter((a) => prepared.applyTypes.has(a.type))
   };
-  log.message(formatPlan(applicable));
+  const pending = applicable.actions.filter((a) => a.type !== "skip").length;
+  if (pending === 0) {
+    outro("Already up to date \u2014 nothing to do.");
+    return;
+  }
+  note(formatSummary(summarize(prepared.files, applicable)), mode === "add" ? "This will add" : "This will update");
   const resolutions = /* @__PURE__ */ new Map();
-  if (prepared.applyTypes.has("conflict")) {
-    for (const action of applicable.actions.filter((a) => a.type === "conflict")) {
-      const choice = bail(
-        await select({
-          message: `You edited ${action.path}. A newer version exists.`,
-          options: [
-            { value: "keep-mine", label: "Keep mine" },
-            { value: "overwrite", label: "Overwrite with the new version" },
-            { value: "keep-theirs", label: "Keep mine, save theirs as .new" }
-          ]
-        })
-      );
-      resolutions.set(action.path, choice);
-    }
+  const conflicts = applicable.actions.filter((a) => a.type === "conflict");
+  for (const [index, action] of conflicts.entries()) {
+    const choice = bail(
+      await select2({
+        message: `Conflict ${index + 1}/${conflicts.length}: you edited ${action.path}, and a newer version exists.`,
+        options: [
+          { value: "keep-mine", label: "Keep mine", hint: "discard the update for this file" },
+          { value: "overwrite", label: "Use the new version", hint: "replace your file" },
+          { value: "keep-theirs", label: "Keep mine + save theirs", hint: `writes ${basename3(action.path)}.new` }
+        ]
+      })
+    );
+    resolutions.set(action.path, choice);
   }
-  const pending = applicable.actions.filter((a) => a.type !== "skip").length;
   const proceed = await confirm({ message: `Apply ${pending} changes in ${projectDir}?` });
   if (isCancel2(proceed) || !proceed) {
     outro("Nothing written.");
@@ -601,24 +695,24 @@ async function runReRun(projectDir) {
     projectName,
     applyTypes: prepared.applyTypes
   });
-  outro(`Done. ${result.written.length} files written.`);
+  successOutro(mode === "add" ? "Added" : "Updated", result.written.length, prepared.selection);
 }
 async function runInteractive() {
   const projectDir = process.cwd();
   if (readManifest(projectDir)) return runReRun(projectDir);
   intro(`ai-engineering-kit ${kitVersion()}`);
   const { selection, projectName } = await promptForSelection(projectDir);
-  const { plan } = planFor(projectDir, selection);
-  log.message(formatPlan(plan));
+  const { files, plan } = planFor(projectDir, selection);
+  note(formatSummary(summarize(files, plan)), "This will add");
   const pending = plan.actions.filter((a) => a.type !== "skip").length;
-  const proceed = await confirm({ message: `Scaffold ${pending} files into ${projectDir}?` });
+  const proceed = await confirm({ message: `Install ${pending} files into ${projectDir}?` });
   if (isCancel2(proceed) || !proceed) {
     outro("Nothing written.");
     return;
   }
   try {
     const result = runInit({ projectDir, selection, projectName });
-    outro(`Installed ${result.written.length} files into ${projectDir}.`);
+    successOutro("Installed", result.written.length, selection);
   } catch (error) {
     if (!reportConflict(error)) throw error;
   }
@@ -641,7 +735,7 @@ function performReRun(projectDir, mode, addParts) {
     priorManifest: manifest,
     selection: prepared.selection,
     version: prepared.version,
-    projectName: basename2(projectDir),
+    projectName: basename3(projectDir),
     applyTypes: prepared.applyTypes
   });
   console.log(`${result.written.length} files written. Edited files were kept (use the interactive flow to resolve).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-kit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "An opinionated, agent-agnostic AI-development kit — disciplined skills plus a structured workspace — installed and updated through one npx command.",
   "type": "module",
   "license": "MIT",

package/template/skills/core-workflow/commit-organizer/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: commit-organizer
+description: Analyze all code changes across one or more repos and organize them into logical, separate conventional commits. Use when you have many unstaged/staged changes and want clean, atomic commits instead of one big commit.
+argument-hint: "[repo-path]"
+allowed-tools: Read, Bash(git *), Glob, Grep
+---
+
+# Commit Organizer
+
+Analyze all code changes (staged and unstaged) in the current directory. If the directory contains multiple git repos (a workspace root), analyze each repo independently. Organize changes into logical, atomic conventional commits.
+
+## How It Works
+
+1. Detect whether the current directory is a git repo or a workspace containing multiple repos
+2. For each repo, collect all modified, added, and untracked files
+3. Read the diffs and new file contents to understand what each change does
+4. Group related changes into logical commit units (e.g., a permission change + its test = one commit)
+5. Order commits so dependencies come first
+6. Present the commit plan to the user for approval
+7. Execute the commits one by one
+
+## Commit Message Rules
+
+- Use conventional commits: `type(scope): description`
+- Types: `feat`, `fix`, `refactor`, `style`, `docs`, `test`, `chore`
+- One line only, max 72 characters
+- Describe WHAT the change does from the user's perspective, not HOW
+- Use imperative mood: "add", "fix", "ensure", "change", not "added", "fixes"
+- Be specific — name the feature, the bug, the thing that changed
+
+### Good Examples
+
+```
+feat: add per-card CSV export to Insights dashboard cards
+feat: ensure bulk data export is only available to superAdmin users
+fix: use YYYY/MM/DD date format in all CSV exports
+refactor: extract shared RQS value mapping to exportUtils
+feat: add export audit log with search and pagination
+chore: add i18n keys for export and audit log UI
+```
+
+### Bad Examples
+
+```
+update code                          # too vague
+feat: changes to export              # what changes?
+fix: fix bug                         # what bug?
+feat: add new feature                # what feature?
+refactor: refactor stuff             # what stuff?
+feat: implement export refactoring   # describes the task, not the change
+```
+
+## Grouping Strategy
+
+Group changes into commits by **logical intent**, not by file type:
+
+- A backend permission change + frontend visibility change for the same feature = ONE commit
+- A new utility file + the component that uses it = ONE commit (if tightly coupled)
+- i18n keys can be grouped with the feature that uses them, or in a separate commit if they span multiple features
+- Unrelated changes to different features = SEPARATE commits
+- A new GraphQL schema + resolver + frontend query/mutation for one feature = ONE commit
+
+When in doubt, prefer fewer, more meaningful commits over many tiny ones.
+
+## Execution
+
+### Step 1: Detect Repos
+
+If `$ARGUMENTS` is provided, use it as the path. Otherwise use the current working directory.
+
+```bash
+# Check if current dir is a git repo
+git rev-parse --git-dir 2>/dev/null
+
+# If not, find git repos one level deep (workspace mode)
+for dir in */; do
+  if [ -d "$dir/.git" ]; then
+    echo "$dir"
+  fi
+done
+```
+
+### Step 2: Collect Changes Per Repo
+
+For each repo, run:
+
+```bash
+git status -u          # all changes including untracked (never use -uall)
+git diff               # unstaged changes
+git diff --cached      # staged changes
+```
+
+For untracked files, read their contents to understand what they add.
+
+### Step 3: Analyze and Group
+
+Read all diffs and new files. For each change, determine:
+- What feature or concern does this belong to?
+- Is it a feat, fix, refactor, style, docs, test, or chore?
+- What other changes is it related to?
+
+Group into commit units. Each unit has:
+- A list of files to stage
+- A commit message
+- A brief rationale (for the user to review)
+
+### Step 4: Present Plan
+
+Show the user a numbered list of proposed commits in order:
+
+```
+Repository: cliezen-graph
+
+  1. feat: restrict bulk CSV export to superAdmin users
+     Files: routes/exportCsv.js
+     
+  2. fix: use YYYY/MM/DD date format in bulk CSV exports
+     Files: routes/exports/csv.js
+
+Repository: cliezen-dashboard
+
+  3. feat: add shared export utilities and CSV formatters
+     Files: src/utils/exportUtils.js, src/utils/cardExportFormatters.js
+
+  4. feat: add per-card CSV export to Insights dashboard cards
+     Files: src/composables/useCardExport.js, src/components/Insights/DashCard.vue, src/graphql/mutations.js
+```
+
+Ask the user: "Does this commit plan look good? You can adjust, reorder, merge, or split any commits."
+
+Wait for approval before proceeding. If the user says "go" or "yes" or "looks good", execute. If they request changes, adjust and re-present.
+
+### Step 5: Execute Commits
+
+For each commit unit, in order:
+
+```bash
+cd <repo-path>
+git add <file1> <file2> ...    # stage only files for this commit
+git commit -m "<message>"       # commit with the planned message
+```
+
+After each commit, confirm success before moving to the next.
+
+If a commit fails (e.g., pre-commit hook), stop and report the error. Do not skip or force.
+
+### Step 6: Summary
+
+After all commits are done, show a summary:
+
+```
+Done! Created N commits across M repos:
+
+cliezen-graph (2 commits):
+  abc1234 feat: restrict bulk CSV export to superAdmin users
+  def5678 fix: use YYYY/MM/DD date format in bulk CSV exports
+
+cliezen-dashboard (4 commits):
+  111aaaa feat: add shared export utilities and CSV formatters
+  222bbbb feat: add per-card CSV export to Insights dashboard cards
+  ...
+```
+
+## Edge Cases
+
+- If there are no changes in a repo, skip it silently
+- If all changes belong to one logical unit, make one commit (don't force artificial splits)
+- If a file has changes belonging to two different features, note this and ask the user how to handle it (commit the whole file with the more significant change, or suggest the user manually split it with `git add -p`)
+- Never run `git add .` or `git add -A` — always stage specific files
+- Never amend existing commits
+- Never force push
+- Never use `--no-verify`
+- Never add Co-Authored-By, Signed-off-by, or any AI attribution trailers to commit messages
+- Commit messages are the developer's own — no mention of Claude, AI, or any tool