@khanhcan148/mk 0.1.10 → 0.1.12

package/README.md

@@ -6,15 +6,8 @@
 
 Modular packages that extend Claude Code with specialized knowledge, workflows, and tool integrations.
 
-**Quick Navigation:** [Quick Reference](docs/QUICK-REFERENCE.md) | [Common Workflows](docs/COMMON-WORKFLOWS.md) | [Skill Index](docs/SKILL-INDEX.md)
+**Quick Navigation:** [Quick Reference](docs/quick-reference.md) | [Common Workflows](docs/common-workflows.md) | [Skill Index](docs/skill-index.md)
 
-## 🔒 Access Notice
-
-**This package has limited access.** To get access to the npm package and repository:
-
-📧 **Email:** khanhcan148@gmail.com
-
-Include your use case and I'll send you an invitation.
 
 ## Quick Start
 
@@ -74,7 +67,7 @@ cp -r .claude ~/.claude/
 ```bash
 # Use a workflow command
 /mk-init           # Bootstrap new project
-/mk-brainstorm     # Explore options, debate trade-offs
+/mk-brainstorm     # Explore options, debate trade-offs; pass Jira/AzDO URL to fetch ticket context first
 /mk-plan           # Create implementation plan
 /mk-implement      # End-to-end feature delivery
 /mk-test           # Run tests and validate
@@ -83,20 +76,21 @@ cp -r .claude ~/.claude/
 /mk-security       # Security scan and audit
 /mk-db             # Database operations
 /mk-docs           # Generate documentation
+/mk-overview       # Multi-tier stakeholder overview (Executive, Product, Technical)
 /mk-git            # Git operations
 /mk-audit          # Code archaeology chain: orientation, testing, heatmap, breaking-change analysis, technical debt, domain extraction
-/mk-skill-creator  # Create and scaffold new Claude Code skills with automated validation
 /mk-selftest       # Self-validation checks on kit agents, skills, docs, workflows
+/mk-log-analysis   # Datadog + Azure App Insights log analysis with severity triage and Mermaid visual reports
 ```
 
 ## Structure
 
 ```
 ├── .claude/
-│   ├── agents/      # 29 agents (5 primary + 24 utility: implementers, quality, docs, specialized, concerns)
-│   ├── skills/      # 58 skill packages (SKILL.md + scripts/references/assets)
-│   │   ├── mk-*/    # 16 workflow commands (/mk-audit, /mk-brainstorm, /mk-skill-creator, /mk-selftest, etc.)
-│   │   └── ...      # Domain skills (frontend, backend, testing, etc.)
+│   ├── agents/      # 31 agents (5 primary + 26 utility: implementers, quality, docs, specialized, concerns)
+│   ├── skills/      # 65 skill packages (SKILL.md + scripts/references/assets)
+│   │   ├── mk-*/    # 19 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-selftest, etc.)
+│   │   └── ...      # Domain skills (frontend, backend, testing, browser automation, etc.)
 │   └── workflows/   # Development protocols
 ├── bin/             # CLI entry point (mk command)
 ├── src/             # CLI source code
@@ -109,7 +103,7 @@ cp -r .claude ~/.claude/
 
 ## Primary Workflow
 
-Orchestration is handled by `/mk-*` skills which spawn utility agents as needed. See [Common Workflows](docs/COMMON-WORKFLOWS.md) for practical examples.
+Orchestration is handled by `/mk-*` skills which spawn utility agents as needed. See [Common Workflows](docs/common-workflows.md) for practical examples.
 
 **Architecture:**
 
@@ -126,21 +120,24 @@ User → /mk-* command (skill) → spawns utility agents → agents use knowledg
 
 | Command | Purpose |
 |---------|---------|
-| `/mk-init` | Full project bootstrap from conception to deployment; includes brownfield detection (Phase 0 gate) and adoption workflow (B1-B4.5 stages) |
-| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent) |
-| `/mk-audit` | Code archaeology chain: orientation report, characterization testing, topology heatmap, breaking-change analysis, technical debt dashboard, domain extraction |
+| `/mk-init` | Full project bootstrap from conception to deployment; includes brownfield detection (Phase 0 gate) and adoption workflow (B1-B4.5 stages); generates AGENTS.md template (or migrates existing tool configs); suggests /mk-audit as next step for brownfield projects |
+| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent); pass a Jira or AzDO URL to fetch ticket hierarchy first (Phase 0.5) |
+| `/mk-audit` | Code archaeology chain: orientation report, characterization testing, topology heatmap, breaking-change analysis, technical debt dashboard, domain extraction; enriches CLAUDE.md and AGENTS.md with auto-generated architecture and debt sections |
 | `/mk-plan` | Create implementation plans with phases and tasks (opus) |
 | `/mk-design` | UI/UX wireframes, design systems, mockups |
 | `/mk-implement` | End-to-end feature delivery (sonnet) |
 | `/mk-test` | Run tests, analyze coverage, validate builds |
 | `/mk-review` | Code review for quality, security, performance |
-| `/mk-debug` | Debugging workflow: investigate, diagnose, fix, verify |
+| `/mk-debug` | Debugging workflow: investigate, diagnose, fix, verify; always offers incident journal documentation with severity hints |
 | `/mk-security` | Security-first workflow: dependency scan, secrets detection |
 | `/mk-db` | Database operations: diagnose, optimize, design, migrate |
-| `/mk-docs` | Generate and update project documentation |
+| `/mk-docs` | Generate and update project documentation; maintains AGENTS.md; Impact Areas analysis produces human-readable "What changed / Who is affected / What could go wrong" narrative |
 | `/mk-git` | Git operations: branch, commit, push, PR, merge |
 | `/mk-research` | Deep multi-source research on technical topics |
-| `/mk-skill-creator` | Create and scaffold new Claude Code skills with automated SKILL.md, scripts, references, and agent |
+| `/mk-spike` | Investigate external service integrations: fetch API docs, evaluate options, produce spike.md with Go/No-Go |
+| `/mk-overview` | Synthesize project artifacts into multi-tier stakeholder overview: Executive Brief, Product Report, Technical Report |
+| `/mk-workflow` | Trace REST endpoint call chains with upstream caller detection, variant branching, side effects/feature flags, Mermaid diagrams |
+| `/mk-log-analysis` | Analyze production logs from Datadog or Azure Application Insights via MCP; progressive severity triage, pattern detection, mandatory stack trace investigation, mk-debug integration |
 | `/mk-selftest` | Run self-validation checks on kit agents, skills, docs, and workflows |
 
 ## Primary Agents
@@ -153,17 +150,18 @@ Invoked directly via `/mk-*` skills:
 | **planner** | Implementation planning with phases, tasks, dependencies | opus |
 | **implementer** | End-to-end feature implementation | sonnet |
 | **database-admin** | Database operations: diagnose, optimize, design, migrate | sonnet |
-| **git-manager** | Git operations: commit, push, PR, merge | haiku |
+| **git-manager** | Git operations: commit, push, PR, merge | sonnet |
 
 ## Utility Agents
 
 Spawned by primary agents for domain-specific work:
 
-**Implementation & Quality (8)**
+**Implementation & Quality (9)**
 | Agent | Purpose |
 |-------|---------|
 | **backend-implementer** | API and domain logic implementation |
 | **frontend-implementer** | UI components, consuming API contract |
+| **mobile-implementer** | Mobile app implementation (Flutter, React Native, Swift, Kotlin) with TFD |
 | **tester** | Test execution and validation |
 | **debugger** | Issue investigation and diagnosis |
 | **refactorer** | Refactoring with TFD-first safety workflow |
@@ -189,7 +187,7 @@ Spawned by primary agents for domain-specific work:
 | **scout-external** | Codebase search via external tools |
 | **mcp-manager** | MCP server integrations |
 
-**Parallel Concern Review Agents (10)**
+**Parallel Concern Review Agents (11)**
 | Agent | Purpose |
 |-------|---------|
 | **quality-reviewer** | Code quality, readability, maintainability (mk-review concern) |
@@ -202,33 +200,30 @@ Spawned by primary agents for domain-specific work:
 | **infra-reviewer** | Infrastructure security review (mk-security concern) |
 | **log-analyzer** | Log analysis and diagnostics (mk-debug concern) |
 | **hypothesis-generator** | Root cause hypothesis generation (mk-debug concern) |
+| **log-collector** | External observability platform queries — Datadog and Azure App Insights MCP (mk-log-analysis concern) |
 
 [Full agent details →](.claude/agents/README.md)
 
 ## Skills
 
-See [Skill Index](docs/SKILL-INDEX.md) for a complete categorized list of all skills.
+See [Skill Index](docs/skill-index.md) for a complete categorized list of all skills.
 
 Each skill contains:
-- `SKILL.md` (required) - Instructions (<100 lines)
+- `SKILL.md` (required) - Instructions (≤250 lines)
 - `scripts/` (optional) - Executable code with tests
 - `references/` (optional) - Documentation chunks
 - `assets/` (optional) - Templates, images
 
 ```bash
-# Create new skill (recommended)
-/mk-skill-creator
-
-# Or use scripts directly
-.claude/skills/mk-skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
-.claude/skills/mk-skill-creator/scripts/package_skill.py <path/to/skill-folder>
+# Create new skill
+python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>
 ```
 
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
-| [Skill Index](docs/SKILL-INDEX.md) | Categorized list of all skills and workflows |
+| [Skill Index](docs/skill-index.md) | Categorized list of all skills and workflows |
 | [mk-* Workflows & Agents](docs/mk-workflow-agents.md) | How each /mk-* command works and which agents it uses |
 | [Project Overview & PDR](docs/project-overview-pdr.md) | Requirements, constraints, success metrics |
 | [Project Roadmap](docs/project-roadmap.md) | Phases, milestones, and risk register |
@@ -236,8 +231,8 @@ Each skill contains:
 | [Code Standards](docs/code-standards.md) | Conventions, naming, quality gates |
 | [System Architecture](docs/system-architecture.md) | Component diagrams, data flow |
 | [Product Domain Glossary](docs/product-domain-glossary.md) | Core domain concepts, terminology, and ecosystem definitions |
-| [Quick Reference](docs/QUICK-REFERENCE.md) | Common commands and quick lookup |
-| [Common Workflows](docs/COMMON-WORKFLOWS.md) | Practical workflow examples |
+| [Quick Reference](docs/quick-reference.md) | Common commands and quick lookup |
+| [Common Workflows](docs/common-workflows.md) | Practical workflow examples |
 
 ## Core Principles
 
@@ -248,16 +243,12 @@ Each skill contains:
 
 ## Key Constraints
 
-- SKILL.md must be under 100 lines
-- Referenced markdown files also under 100 lines
+- SKILL.md must be ≤250 lines
+- Reference files in `references/` have no line limit; loaded on-demand
 - Scripts must include tests
 - **Cross-platform compatibility (Windows + macOS/Linux) is mandatory**: Scripts use Python or Node.js only — no bash/shell scripts
 - Token efficiency - minimize context usage
 
-## Compatibility
-
-This skill kit works in both Claude Code CLI and VSCode GitHub Copilot (1.108+).
-
 ## Cross-Platform Compatibility
 
 This kit is designed to work on Windows, macOS, and Linux:
@@ -265,19 +256,4 @@ This kit is designed to work on Windows, macOS, and Linux:
 - **Scripts**: All executable scripts use Python or Node.js (no bash/shell scripts)
 - **Claude Code Bash tool**: Provides a Unix-like shell on all platforms, including Windows — git commands and other Bash tool invocations work everywhere
 - **External tool installs**: Reference files include install instructions for macOS (`brew`), Ubuntu/Debian (`apt-get`), and Windows (`winget`/`choco`) where applicable
-- **Agent fallbacks**: Agents using CLI-only tools (TodoWrite, BashOutput, MultiEdit) document VSCode Copilot fallback behavior inline
-
-| Feature | Claude Code CLI | VSCode Copilot (1.108+) |
-|---------|----------------|------------------------|
-| Skills (SKILL.md) | Full support | Full support |
-| Agents (.md) | Full support | Full support |
-| CLAUDE.md | Full support | Full support |
-| Model field | Shorthand (opus/sonnet/haiku) | Shorthand (recommended) |
-| Task tool | Native Task() syntax | Natural language delegation* |
-| color | Supported | Ignored (harmless) |
-| MCP tools | Full support | Limited |
-| AskUserQuestion | Native UI | Natural language fallback |
-
-*VSCode Copilot users: Use natural language to invoke agents (e.g., "Use the planner agent to create a plan"). The explicit Task() syntax is Claude Code CLI-specific.
-
-**CLI-only tools**: TodoWrite, BashOutput, KillShell, MultiEdit are Claude Code-specific. Agents gracefully fall back to standard tools (Write, Bash, sequential Edit) when these are unavailable.
+**Supported runtime**: Claude Code CLI. All skills, agents, and workflows are designed for the Claude Code runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -14,8 +14,8 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js",
-    "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null || true",
+    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js test/hooks/*.test.cjs",
+    "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null",
     "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py"
   },
   "dependencies": {

package/src/commands/init.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { copyKitFiles } from '../lib/copy.js';
+import { copyKitFiles, mergeSettingsJson } from '../lib/copy.js';
 import { writeManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
 import { resolveTargetDir, resolveManifestPath } from '../lib/paths.js';
@@ -45,6 +45,9 @@ export async function runInit(params = {}) {
   // Copy files (dry-run or real)
   const fileList = copyKitFiles(sourceDir, targetDir, { dryRun });
 
+  // Merge settings.json (hooks configuration) — safe merge, never overwrites user keys
+  mergeSettingsJson(sourceDir, targetDir, { dryRun });
+
   if (dryRun) {
     return { files: fileList, totalSize: fileList.reduce((s, f) => s + f.size, 0), dryRun: true };
   }

package/src/commands/remove.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
-import { existsSync, unlinkSync, rmdirSync, readdirSync } from 'node:fs';
+import { existsSync, unlinkSync, rmdirSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import { readManifest } from '../lib/manifest.js';
 import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
+import { isEmptyDir } from '../lib/fs-utils.js';
 
 /**
  * Run the remove command.
@@ -110,19 +111,6 @@ export async function runRemove(params = {}) {
   return { removed, skipped, dirsCleaned };
 }
 
-/**
- * Check if a directory is empty.
- * @param {string} dir
- * @returns {boolean}
- */
-function isEmptyDir(dir) {
-  try {
-    return readdirSync(dir).length === 0;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * CLI action handler for 'mk remove'.
  * @param {{ global: boolean }} options

package/src/commands/update.js

@@ -1,16 +1,17 @@
 import chalk from 'chalk';
 import { createInterface } from 'node:readline';
-import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync, readdirSync } from 'node:fs';
+import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
-import { copyKitFiles, collectDiskFiles } from '../lib/copy.js';
+import { copyKitFiles, collectDiskFiles, mergeSettingsJson } from '../lib/copy.js';
 import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';
 import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
 import { fetchLatestRelease, compareVersions } from '../lib/releases.js';
+import { isEmptyDir } from '../lib/fs-utils.js';
 
 // ---------------------------------------------------------------------------
 // Prompt helper
@@ -219,6 +220,9 @@ export async function runUpdate(params = {}) {
     }
   }
 
+  // Merge settings.json hooks — additive merge, never overwrites user keys
+  mergeSettingsJson(sourceDir, targetDir);
+
   // Update manifest with new file map.
   // Use explicitVersion when provided (e.g. release.version from updateAction);
   // fall back to pkg.version for direct runUpdate calls or main-branch fallback downloads.
@@ -235,19 +239,6 @@ export async function runUpdate(params = {}) {
   };
 }
 
-/**
- * Check if a directory is empty.
- * @param {string} dir
- * @returns {boolean}
- */
-function isEmptyDir(dir) {
-  try {
-    return readdirSync(dir).length === 0;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * CLI action handler for 'mk update'.
  * Checks GitHub Releases for a newer version, prompts the user, then downloads

package/src/lib/constants.js

@@ -1,7 +1,7 @@
 /**
  * Kit subdirectories to copy/manage (relative to .claude/)
  */
-export const KIT_SUBDIRS = ['agents', 'skills', 'workflows'];
+export const KIT_SUBDIRS = ['agents', 'skills', 'workflows', 'hooks'];
 
 /**
  * Manifest file name
@@ -19,7 +19,8 @@ export const COPY_FILTER_PATTERNS = [
   'node_modules',
   '.DS_Store',
   'package-lock.json',
-  '.env'
+  '.env',
+  '.logs'
 ];
 
 /**

package/src/lib/copy.js

@@ -1,5 +1,5 @@
 import { join, relative } from 'node:path';
-import { statSync, lstatSync, existsSync } from 'node:fs';
+import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import fsExtra from 'fs-extra';
 import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
 
@@ -153,3 +153,96 @@ export function copyKitFiles(sourceDir, targetDir, options = {}) {
 
   return fileList;
 }
+
+/**
+ * Merge kit's settings.json into user's existing settings.json.
+ * Strategy: deep-merge "hooks" key from kit source; preserve all other user keys.
+ * If user has no settings.json, copy kit source as-is.
+ * If kit source has no settings.json, do nothing.
+ *
+ * @param {string} sourceDir - Absolute path to source .claude/
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @param {{ dryRun: boolean }} options
+ * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[] }}
+ */
+export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
+  const { dryRun = false } = options;
+  const srcPath = join(sourceDir, 'settings.json');
+  const destPath = join(targetDir, 'settings.json');
+
+  if (!existsSync(srcPath)) return { action: 'skipped' };
+
+  let kitSettings;
+  try {
+    kitSettings = JSON.parse(readFileSync(srcPath, 'utf-8'));
+  } catch {
+    return { action: 'skipped' };
+  }
+
+  // No existing user settings — copy kit source as-is
+  if (!existsSync(destPath)) {
+    if (!dryRun) {
+      mkdirSync(targetDir, { recursive: true });
+      writeFileSync(destPath, JSON.stringify(kitSettings, null, 2) + '\n', 'utf-8');
+    }
+    return { action: 'created' };
+  }
+
+  // Existing user settings — merge hooks only, preserve everything else
+  let userSettings;
+  try {
+    userSettings = JSON.parse(readFileSync(destPath, 'utf-8'));
+  } catch {
+    // Malformed user settings — skip to avoid data loss
+    return { action: 'skipped' };
+  }
+
+  const merged = [];
+
+  // Merge hooks: kit entries are added/updated, user entries not in kit are preserved
+  if (kitSettings.hooks) {
+    if (!userSettings.hooks) userSettings.hooks = {};
+    for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
+      if (!userSettings.hooks[event]) {
+        userSettings.hooks[event] = kitEntries;
+        merged.push(event);
+      } else {
+        // Merge by matcher: add kit entries whose matcher doesn't already exist
+        for (const kitEntry of kitEntries) {
+          const kitMatcher = kitEntry.matcher || '*';
+          const exists = userSettings.hooks[event].some(
+            e => (e.matcher || '*') === kitMatcher
+          );
+          if (!exists) {
+            userSettings.hooks[event].push(kitEntry);
+            merged.push(`${event}[${kitMatcher}]`);
+          }
+          // If matcher exists, check if kit hooks are present
+          if (exists) {
+            const userEntry = userSettings.hooks[event].find(
+              e => (e.matcher || '*') === kitMatcher
+            );
+            if (userEntry && userEntry.hooks && kitEntry.hooks) {
+              for (const kh of kitEntry.hooks) {
+                const hookExists = userEntry.hooks.some(
+                  uh => uh.command === kh.command
+                );
+                if (!hookExists) {
+                  userEntry.hooks.push(kh);
+                  merged.push(`${event}[${kitMatcher}]:${kh.command}`);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (merged.length === 0) return { action: 'skipped' };
+
+  if (!dryRun) {
+    writeFileSync(destPath, JSON.stringify(userSettings, null, 2) + '\n', 'utf-8');
+  }
+  return { action: 'merged', merged };
+}

package/src/lib/fs-utils.js

@@ -0,0 +1,18 @@
+import { readdirSync } from 'node:fs';
+
+/**
+ * Check if a directory is empty.
+ *
+ * Returns false (rather than throwing) if the directory does not exist
+ * or is inaccessible — callers treat non-empty as a safe default.
+ *
+ * @param {string} dir - Absolute path to directory
+ * @returns {boolean} true if directory exists and contains no entries
+ */
+export function isEmptyDir(dir) {
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}