@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/ck/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: ck
+description: Persistent per-project memory for Claude Code. Auto-loads project context on session start, tracks sessions with git activity, and writes to native memory. Commands run deterministic Node.js scripts — behavior is consistent across model versions.
+origin: community
+version: 2.0.0
+author: sreedhargs89
+repo: https://github.com/sreedhargs89/context-keeper
+---
+
+# ck — Context Keeper
+
+You are the **Context Keeper** assistant. When the user invokes any `/ck:*` command,
+run the corresponding Node.js script and present its stdout to the user verbatim.
+Scripts live at: `~/.claude/skills/ck/commands/` (expand `~` with `$HOME`).
+
+---
+
+## Data Layout
+
+```
+~/.claude/ck/
+├── projects.json              ← path → {name, contextDir, lastUpdated}
+└── contexts/<name>/
+    ├── context.json           ← SOURCE OF TRUTH (structured JSON, v2)
+    └── CONTEXT.md             ← generated view — do not hand-edit
+```
+
+---
+
+## Commands
+
+### `/ck:init` — Register a Project
+```bash
+node "$HOME/.claude/skills/ck/commands/init.mjs"
+```
+The script outputs JSON with auto-detected info. Present it as a confirmation draft:
+```
+Here's what I found — confirm or edit anything:
+Project:     <name>
+Description: <description>
+Stack:       <stack>
+Goal:        <goal>
+Do-nots:     <constraints or "None">
+Repo:        <repo or "none">
+```
+Wait for user approval. Apply any edits. Then pipe confirmed JSON to save.mjs --init:
+```bash
+echo '<confirmed-json>' | node "$HOME/.claude/skills/ck/commands/save.mjs" --init
+```
+Confirmed JSON schema: `{"name":"...","path":"...","description":"...","stack":["..."],"goal":"...","constraints":["..."],"repo":"..." }`
+
+---
+
+### `/ck:save` — Save Session State
+**This is the only command requiring LLM analysis.** Analyze the current conversation:
+- `summary`: one sentence, max 10 words, what was accomplished
+- `leftOff`: what was actively being worked on (specific file/feature/bug)
+- `nextSteps`: ordered array of concrete next steps
+- `decisions`: array of `{what, why}` for decisions made this session
+- `blockers`: array of current blockers (empty array if none)
+- `goal`: updated goal string **only if it changed this session**, else omit
+
+Show a draft summary to the user: `"Session: '<summary>' — save this? (yes / edit)"`
+Wait for confirmation. Then pipe to save.mjs:
+```bash
+echo '<json>' | node "$HOME/.claude/skills/ck/commands/save.mjs"
+```
+JSON schema (exact): `{"summary":"...","leftOff":"...","nextSteps":["..."],"decisions":[{"what":"...","why":"..."}],"blockers":["..."]}`
+Display the script's stdout confirmation verbatim.
+
+---
+
+### `/ck:resume [name|number]` — Full Briefing
+```bash
+node "$HOME/.claude/skills/ck/commands/resume.mjs" [arg]
+```
+Display output verbatim. Then ask: "Continue from here? Or has anything changed?"
+If user reports changes → run `/ck:save` immediately.
+
+---
+
+### `/ck:info [name|number]` — Quick Snapshot
+```bash
+node "$HOME/.claude/skills/ck/commands/info.mjs" [arg]
+```
+Display output verbatim. No follow-up question.
+
+---
+
+### `/ck:list` — Portfolio View
+```bash
+node "$HOME/.claude/skills/ck/commands/list.mjs"
+```
+Display output verbatim. If user replies with a number or name → run `/ck:resume`.
+
+---
+
+### `/ck:forget [name|number]` — Remove a Project
+First resolve the project name (run `/ck:list` if needed).
+Ask: `"This will permanently delete context for '<name>'. Are you sure? (yes/no)"`
+If yes:
+```bash
+node "$HOME/.claude/skills/ck/commands/forget.mjs" [name]
+```
+Display confirmation verbatim.
+
+---
+
+### `/ck:migrate` — Convert v1 Data to v2
+```bash
+node "$HOME/.claude/skills/ck/commands/migrate.mjs"
+```
+For a dry run first:
+```bash
+node "$HOME/.claude/skills/ck/commands/migrate.mjs" --dry-run
+```
+Display output verbatim. Migrates all v1 CONTEXT.md + meta.json files to v2 context.json.
+Originals are backed up as `meta.json.v1-backup` — nothing is deleted.
+
+---
+
+## SessionStart Hook
+
+The hook at `~/.claude/skills/ck/hooks/session-start.mjs` must be registered in
+`~/.claude/settings.json` to auto-load project context on session start:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "node \"~/.claude/skills/ck/hooks/session-start.mjs\"" }] }
+    ]
+  }
+}
+```
+
+The hook injects ~100 tokens per session (compact 5-line summary). It also detects
+unsaved sessions, git activity since last save, and goal mismatches vs CLAUDE.md.
+
+---
+
+## Rules
+- Always expand `~` as `$HOME` in Bash calls.
+- Commands are case-insensitive: `/CK:SAVE`, `/ck:save`, `/Ck:Save` all work.
+- If a script exits with code 1, display its stdout as an error message.
+- Never edit `context.json` or `CONTEXT.md` directly — always use the scripts.
+- If `projects.json` is malformed, tell the user and offer to reset it to `{}`.

package/.agent/skills/ck/commands/forget.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * ck — Context Keeper v2
+ * forget.mjs — remove a project's context and registry entry
+ *
+ * Usage: node forget.mjs [name|number]
+ * stdout: confirmation or error
+ * exit 0: success  exit 1: not found
+ *
+ * Note: SKILL.md instructs Claude to ask "Are you sure?" before calling this script.
+ * This script is the "do it" step — no confirmation prompt here.
+ */
+
+import { rmSync } from 'fs';
+import { resolve } from 'path';
+import { resolveContext, readProjects, writeProjects, CONTEXTS_DIR } from './shared.mjs';
+
+const arg = process.argv[2];
+const cwd = process.env.PWD || process.cwd();
+
+const resolved = resolveContext(arg, cwd);
+if (!resolved) {
+  const hint = arg ? `No project matching "${arg}".` : 'This directory is not registered.';
+  console.log(`${hint}`);
+  process.exit(1);
+}
+
+const { name, contextDir, projectPath } = resolved;
+
+// Remove context directory
+const contextDirPath = resolve(CONTEXTS_DIR, contextDir);
+try {
+  rmSync(contextDirPath, { recursive: true, force: true });
+} catch (e) {
+  console.log(`ck: could not remove context directory — ${e.message}`);
+  process.exit(1);
+}
+
+// Remove from projects.json
+const projects = readProjects();
+delete projects[projectPath];
+writeProjects(projects);
+
+console.log(`✓ Context for '${name}' removed.`);

package/.agent/skills/ck/commands/info.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * ck — Context Keeper v2
+ * info.mjs — quick read-only context snapshot
+ *
+ * Usage: node info.mjs [name|number]
+ * stdout: compact info block
+ * exit 0: success  exit 1: not found
+ */
+
+import { resolveContext, renderInfoBlock } from './shared.mjs';
+
+const arg = process.argv[2];
+const cwd = process.env.PWD || process.cwd();
+
+const resolved = resolveContext(arg, cwd);
+if (!resolved) {
+  const hint = arg ? `No project matching "${arg}".` : 'This directory is not registered.';
+  console.log(`${hint} Run /ck:init to register it.`);
+  process.exit(1);
+}
+
+console.log('');
+console.log(renderInfoBlock(resolved.context));

package/.agent/skills/ck/commands/init.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * ck — Context Keeper v2
+ * init.mjs — auto-detect project info and output JSON for Claude to confirm
+ *
+ * Usage: node init.mjs
+ * stdout: JSON with auto-detected project info
+ * exit 0: success  exit 1: error
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, basename } from 'path';
+import { readProjects } from './shared.mjs';
+
+const cwd = process.env.PWD || process.cwd();
+const projects = readProjects();
+
+const output = {
+  path: cwd,
+  name: null,
+  description: null,
+  stack: [],
+  goal: null,
+  constraints: [],
+  repo: null,
+  alreadyRegistered: !!projects[cwd],
+};
+
+function readFile(filename) {
+  const p = resolve(cwd, filename);
+  if (!existsSync(p)) return null;
+  try { return readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function extractSection(md, heading) {
+  const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = md.match(re);
+  return m ? m[1].trim() : null;
+}
+
+// ── package.json ──────────────────────────────────────────────────────────────
+const pkg = readFile('package.json');
+if (pkg) {
+  try {
+    const parsed = JSON.parse(pkg);
+    if (parsed.name && !output.name) output.name = parsed.name;
+    if (parsed.description && !output.description) output.description = parsed.description;
+
+    // Detect stack from dependencies
+    const deps = Object.keys({ ...(parsed.dependencies || {}), ...(parsed.devDependencies || {}) });
+    const stackMap = {
+      next: 'Next.js', react: 'React', vue: 'Vue', svelte: 'Svelte', astro: 'Astro',
+      express: 'Express', fastify: 'Fastify', hono: 'Hono', nestjs: 'NestJS',
+      typescript: 'TypeScript', prisma: 'Prisma', drizzle: 'Drizzle',
+      '@neondatabase/serverless': 'Neon', '@upstash/redis': 'Upstash Redis',
+      '@clerk/nextjs': 'Clerk', stripe: 'Stripe', tailwindcss: 'Tailwind CSS',
+    };
+    for (const [dep, label] of Object.entries(stackMap)) {
+      if (deps.includes(dep) && !output.stack.includes(label)) {
+        output.stack.push(label);
+      }
+    }
+    if (deps.includes('typescript') || existsSync(resolve(cwd, 'tsconfig.json'))) {
+      if (!output.stack.includes('TypeScript')) output.stack.push('TypeScript');
+    }
+  } catch { /* malformed package.json */ }
+}
+
+// ── go.mod ────────────────────────────────────────────────────────────────────
+const goMod = readFile('go.mod');
+if (goMod) {
+  if (!output.stack.includes('Go')) output.stack.push('Go');
+  const modName = goMod.match(/^module\s+(\S+)/m)?.[1];
+  if (modName && !output.name) output.name = modName.split('/').pop();
+}
+
+// ── Cargo.toml ────────────────────────────────────────────────────────────────
+const cargo = readFile('Cargo.toml');
+if (cargo) {
+  if (!output.stack.includes('Rust')) output.stack.push('Rust');
+  const crateName = cargo.match(/^name\s*=\s*"(.+?)"/m)?.[1];
+  if (crateName && !output.name) output.name = crateName;
+}
+
+// ── pyproject.toml ────────────────────────────────────────────────────────────
+const pyproject = readFile('pyproject.toml');
+if (pyproject) {
+  if (!output.stack.includes('Python')) output.stack.push('Python');
+  const pyName = pyproject.match(/^name\s*=\s*"(.+?)"/m)?.[1];
+  if (pyName && !output.name) output.name = pyName;
+}
+
+// ── .git/config (repo URL) ────────────────────────────────────────────────────
+const gitConfig = readFile('.git/config');
+if (gitConfig) {
+  const repoMatch = gitConfig.match(/url\s*=\s*(.+)/);
+  if (repoMatch) output.repo = repoMatch[1].trim();
+}
+
+// ── CLAUDE.md ─────────────────────────────────────────────────────────────────
+const claudeMd = readFile('CLAUDE.md');
+if (claudeMd) {
+  const goal = extractSection(claudeMd, 'Current Goal');
+  if (goal && !output.goal) output.goal = goal.split('\n')[0].trim();
+
+  const doNot = extractSection(claudeMd, 'Do Not Do');
+  if (doNot) {
+    const bullets = doNot.split('\n')
+      .filter(l => /^[-*]\s+/.test(l))
+      .map(l => l.replace(/^[-*]\s+/, '').trim());
+    output.constraints = bullets;
+  }
+
+  const stack = extractSection(claudeMd, 'Tech Stack');
+  if (stack && output.stack.length === 0) {
+    output.stack = stack.split(/[,\n]/).map(s => s.replace(/^[-*]\s+/, '').trim()).filter(Boolean);
+  }
+
+  // Description from first section or "What This Is"
+  const whatItIs = extractSection(claudeMd, 'What This Is') || extractSection(claudeMd, 'About');
+  if (whatItIs && !output.description) output.description = whatItIs.split('\n')[0].trim();
+}
+
+// ── README.md (description fallback) ─────────────────────────────────────────
+const readme = readFile('README.md');
+if (readme && !output.description) {
+  // First non-header, non-badge, non-empty paragraph
+  const lines = readme.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!') && !trimmed.startsWith('>') && !trimmed.startsWith('[') && trimmed !== '---' && trimmed !== '___') {
+      output.description = trimmed.slice(0, 120);
+      break;
+    }
+  }
+}
+
+// ── Name fallback: directory name ─────────────────────────────────────────────
+if (!output.name) {
+  output.name = basename(cwd).toLowerCase().replace(/\s+/g, '-');
+}
+
+console.log(JSON.stringify(output, null, 2));

package/.agent/skills/ck/commands/list.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * ck — Context Keeper v2
+ * list.mjs — portfolio view of all registered projects
+ *
+ * Usage: node list.mjs
+ * stdout: ASCII table of all projects + prompt to resume
+ * exit 0: success  exit 1: no projects
+ */
+
+import { readProjects, loadContext, today, renderListTable } from './shared.mjs';
+
+const cwd = process.env.PWD || process.cwd();
+const projects = readProjects();
+const entries = Object.entries(projects);
+
+if (entries.length === 0) {
+  console.log('No projects registered. Run /ck:init to get started.');
+  process.exit(1);
+}
+
+// Build enriched list sorted alphabetically by contextDir
+const enriched = entries
+  .map(([path, info]) => {
+    const context = loadContext(info.contextDir);
+    return {
+      name: info.name,
+      contextDir: info.contextDir,
+      path,
+      context,
+      lastUpdated: info.lastUpdated,
+    };
+  })
+  .sort((a, b) => a.contextDir.localeCompare(b.contextDir));
+
+const table = renderListTable(enriched, cwd, today());
+console.log('');
+console.log(table);
+console.log('');
+console.log('Resume which? (number or name)');

package/.agent/skills/ck/commands/migrate.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * ck — Context Keeper v2
+ * migrate.mjs — convert v1 (CONTEXT.md + meta.json) to v2 (context.json)
+ *
+ * Usage:
+ *   node migrate.mjs           — migrate all v1 projects
+ *   node migrate.mjs --dry-run — preview without writing
+ *
+ * Safe: backs up meta.json to meta.json.v1-backup, never deletes data.
+ * exit 0: success  exit 1: error
+ */
+
+import { readFileSync, existsSync, renameSync } from 'fs';
+import { resolve } from 'path';
+import { readProjects, writeProjects, saveContext, today, shortId, CONTEXTS_DIR } from './shared.mjs';
+
+const isDryRun = process.argv.includes('--dry-run');
+
+if (isDryRun) {
+  console.log('ck migrate — DRY RUN (no files will be written)\n');
+}
+
+// ── v1 markdown parsers ───────────────────────────────────────────────────────
+
+function extractSection(md, heading) {
+  const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = md.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function parseBullets(text) {
+  if (!text) return [];
+  return text.split('\n')
+    .filter(l => /^[-*\d]\s/.test(l.trim()))
+    .map(l => l.replace(/^[-*\d]+\.?\s+/, '').trim())
+    .filter(Boolean);
+}
+
+function parseDecisionsTable(text) {
+  if (!text) return [];
+  const rows = [];
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('|') || line.match(/^[|\s-]+$/)) continue;
+    const cols = line.split('|').map(c => c.trim()).filter((c, i) => i > 0 && i < 4);
+    if (cols.length >= 1 && !cols[0].startsWith('Decision') && !cols[0].startsWith('_')) {
+      rows.push({ what: cols[0] || '', why: cols[1] || '', date: cols[2] || '' });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Parse "Where I Left Off" which in v1 can be:
+ * - Simple bullet list
+ * - Multi-session blocks: "Session N (date):\n- bullet\n"
+ * Returns array of session-like objects {date?, leftOff}
+ */
+function parseLeftOff(text) {
+  if (!text) return [{ leftOff: null }];
+
+  // Detect multi-session format: "Session N ..."
+  const sessionBlocks = text.split(/(?=Session \d+)/);
+  if (sessionBlocks.length > 1) {
+    return sessionBlocks
+      .filter(b => b.trim())
+      .map(block => {
+        const dateMatch = block.match(/\((\d{4}-\d{2}-\d{2})\)/);
+        const bullets = parseBullets(block);
+        return {
+          date: dateMatch?.[1] || null,
+          leftOff: bullets.length ? bullets.join('\n') : block.replace(/^Session \d+.*\n/, '').trim(),
+        };
+      });
+  }
+
+  // Simple format
+  const bullets = parseBullets(text);
+  return [{ leftOff: bullets.length ? bullets.join('\n') : text.trim() }];
+}
+
+// ── Main migration ─────────────────────────────────────────────────────────────
+
+const projects = readProjects();
+let migrated = 0;
+let skipped = 0;
+let errors = 0;
+
+for (const [projectPath, info] of Object.entries(projects)) {
+  const contextDir = info.contextDir;
+  const contextDirPath = resolve(CONTEXTS_DIR, contextDir);
+  const contextJsonPath = resolve(contextDirPath, 'context.json');
+  const contextMdPath   = resolve(contextDirPath, 'CONTEXT.md');
+  const metaPath        = resolve(contextDirPath, 'meta.json');
+
+  // Already v2
+  if (existsSync(contextJsonPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(contextJsonPath, 'utf8'));
+      if (existing.version === 2) {
+        console.log(`  ✓ ${contextDir} — already v2, skipping`);
+        skipped++;
+        continue;
+      }
+    } catch { /* fall through to migrate */ }
+  }
+
+  console.log(`\n  → Migrating: ${contextDir}`);
+
+  try {
+    // Read v1 files
+    const contextMd = existsSync(contextMdPath) ? readFileSync(contextMdPath, 'utf8') : '';
+    let meta = {};
+    if (existsSync(metaPath)) {
+      try {
+        meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+      } catch (e) {
+        console.warn(`  ! ${contextDir}: invalid meta.json, continuing with defaults (${e.message})`);
+      }
+    }
+
+    // Extract fields from CONTEXT.md
+    const description   = extractSection(contextMd, 'What This Is') || extractSection(contextMd, 'About') || null;
+    const stackRaw      = extractSection(contextMd, 'Tech Stack') || '';
+    const stack         = stackRaw.split(/[,\n]/).map(s => s.replace(/^[-*]\s+/, '').trim()).filter(Boolean);
+    const goal          = (extractSection(contextMd, 'Current Goal') || '').split('\n')[0].trim() || null;
+    const constraintRaw = extractSection(contextMd, 'Do Not Do') || '';
+    const constraints   = parseBullets(constraintRaw);
+    const decisionsRaw  = extractSection(contextMd, 'Decisions Made') || '';
+    const decisions     = parseDecisionsTable(decisionsRaw);
+    const nextStepsRaw  = extractSection(contextMd, 'Next Steps') || '';
+    const nextSteps     = parseBullets(nextStepsRaw);
+    const blockersRaw   = extractSection(contextMd, 'Blockers') || '';
+    const blockers      = parseBullets(blockersRaw).filter(b => b.toLowerCase() !== 'none');
+    const leftOffRaw    = extractSection(contextMd, 'Where I Left Off') || '';
+    const leftOffParsed = parseLeftOff(leftOffRaw);
+
+    // Build sessions from parsed left-off blocks (may be multiple)
+    const sessions = leftOffParsed.map((lo, idx) => ({
+      id: idx === leftOffParsed.length - 1 && meta.lastSessionId
+        ? meta.lastSessionId.slice(0, 8)
+        : shortId(),
+      date: lo.date || meta.lastUpdated || today(),
+      summary: idx === leftOffParsed.length - 1
+        ? (meta.lastSessionSummary || 'Migrated from v1')
+        : `Session ${idx + 1} (migrated)`,
+      leftOff: lo.leftOff,
+      nextSteps: idx === leftOffParsed.length - 1 ? nextSteps : [],
+      decisions: idx === leftOffParsed.length - 1 ? decisions : [],
+      blockers: idx === leftOffParsed.length - 1 ? blockers : [],
+    }));
+
+    const context = {
+      version: 2,
+      name: contextDir,
+      path: meta.path || projectPath,
+      description,
+      stack,
+      goal,
+      constraints,
+      repo: meta.repo || null,
+      createdAt: meta.lastUpdated || today(),
+      sessions,
+    };
+
+    if (isDryRun) {
+      console.log(`    description: ${description?.slice(0, 60) || '(none)'}`);
+      console.log(`    stack:       ${stack.join(', ') || '(none)'}`);
+      console.log(`    goal:        ${goal?.slice(0, 60) || '(none)'}`);
+      console.log(`    sessions:    ${sessions.length}`);
+      console.log(`    decisions:   ${decisions.length}`);
+      console.log(`    nextSteps:   ${nextSteps.length}`);
+      migrated++;
+      continue;
+    }
+
+    // Backup meta.json
+    if (existsSync(metaPath)) {
+      renameSync(metaPath, resolve(contextDirPath, 'meta.json.v1-backup'));
+    }
+
+    // Write context.json + regenerated CONTEXT.md
+    saveContext(contextDir, context);
+
+    // Update projects.json entry
+    projects[projectPath].lastUpdated = today();
+
+    console.log(`    ✓ Migrated — ${sessions.length} session(s), ${decisions.length} decision(s)`);
+    migrated++;
+  } catch (e) {
+    console.log(`    ✗ Error: ${e.message}`);
+    errors++;
+  }
+}
+
+if (!isDryRun && migrated > 0) {
+  writeProjects(projects);
+}
+
+console.log(`\nck migrate: ${migrated} migrated, ${skipped} already v2, ${errors} errors`);
+if (isDryRun) console.log('Run without --dry-run to apply.');
+if (errors > 0) process.exit(1);

package/.agent/skills/ck/commands/resume.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * ck — Context Keeper v2
+ * resume.mjs — full project briefing
+ *
+ * Usage: node resume.mjs [name|number]
+ * stdout: bordered briefing box
+ * exit 0: success  exit 1: not found
+ */
+
+import { existsSync } from 'fs';
+import { resolveContext, renderBriefingBox } from './shared.mjs';
+
+const arg = process.argv[2];
+const cwd = process.env.PWD || process.cwd();
+
+const resolved = resolveContext(arg, cwd);
+if (!resolved) {
+  const hint = arg ? `No project matching "${arg}".` : 'This directory is not registered.';
+  console.log(`${hint} Run /ck:init to register it.`);
+  process.exit(1);
+}
+
+const { context, projectPath } = resolved;
+
+// Attempt to cd to the project path
+if (projectPath && projectPath !== cwd) {
+  if (existsSync(projectPath)) {
+    console.log(`→ cd ${projectPath}`);
+  } else {
+    console.log(`WARNING Path not found: ${projectPath}`);
+  }
+}
+
+console.log('');
+console.log(renderBriefingBox(context));