@vpxa/aikit 0.1.1

package/scaffold/general/skills/session-handoff/references/resume-checklist.md

@@ -0,0 +1,80 @@
+# Resume Checklist
+
+Follow this checklist when resuming work from a handoff document to ensure zero-ambiguity continuation.
+
+## Pre-Resume Verification
+
+- [ ] Read the entire handoff document before taking any action
+- [ ] Verify you are in the correct project directory
+- [ ] Confirm the git branch matches (or understand why it might differ)
+- [ ] Check the handoff timestamp - how stale is this context?
+
+## Context Validation
+
+- [ ] Review "Important Context" section thoroughly
+- [ ] Understand all assumptions listed - are they still valid?
+- [ ] Check if any blockers have been resolved since handoff
+- [ ] Review "Potential Gotchas" to avoid known pitfalls
+
+## State Verification
+
+- [ ] Run `git status` to see current file state
+- [ ] Compare modified files list in handoff vs current state
+- [ ] Check if any environment variables need to be set
+- [ ] Verify any required services/processes are running
+
+## Resume Execution
+
+- [ ] Start with "Immediate Next Steps" item #1
+- [ ] Reference "Files Modified" table for context on recent changes
+- [ ] Apply patterns documented in "Key Patterns Discovered"
+- [ ] Follow architectural insights from "Architecture Overview"
+
+## During Work
+
+- [ ] Update handoff document if major new context is discovered
+- [ ] Mark completed items in "Pending Work" as you finish them
+- [ ] Add new blockers/questions as they arise
+- [ ] Consider creating a new handoff if session becomes long
+
+## Red Flags - Stop and Verify
+
+If you encounter any of these, pause and verify context before proceeding:
+
+1. **Files mentioned in handoff don't exist** - codebase may have changed significantly
+2. **Branch has diverged substantially** - check git log for recent commits
+3. **Assumptions are clearly invalid** - reassess the approach
+4. **Blockers marked as unresolved are now blocking you** - escalate to user
+5. **Architecture has changed** - re-explore before continuing
+
+## Quick Start Commands
+
+After reading the handoff, these commands help verify state:
+
+```bash
+# Check current branch and status
+git branch --show-current
+git status
+
+# See recent commits (compare with handoff)
+git log --oneline -10
+
+# Check for any running processes mentioned
+ps aux | grep [process-name]
+
+# Verify environment
+env | grep [relevant-var]
+```
+
+## Handoff Quality Assessment
+
+Rate the handoff quality to identify if more exploration is needed:
+
+| Aspect | Good | Needs Exploration |
+|--------|------|-------------------|
+| Next steps | Clear, actionable | Vague or missing |
+| File references | Specific paths/lines | General descriptions |
+| Decisions | Rationale included | Just outcomes |
+| Context | Complete picture | Gaps or assumptions |
+
+If multiple aspects "Need Exploration", spend time re-exploring the codebase before continuing implementation.

package/scaffold/general/skills/session-handoff/scripts/check_staleness.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * Check staleness of a handoff document compared to current project state.
+ *
+ * Analyzes:
+ * - Time since handoff was created
+ * - Git commits since handoff
+ * - Files that changed since handoff
+ * - Branch divergence
+ * - Modified files status
+ *
+ * Usage:
+ *   node check_staleness.js <handoff-file>
+ *   node check_staleness.js .handoffs/2024-01-15-143022-auth.md
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+function _die(msg) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+}
+
+function runCmd(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, timeout: 10_000, encoding: 'utf-8' }).trim() };
+  } catch {
+    return { ok: false, out: '' };
+  }
+}
+
+function parseHandoffMetadata(filepath) {
+  const content = fs.readFileSync(filepath, 'utf-8');
+  const meta = { created: null, branch: null, projectPath: null, modifiedFiles: [] };
+
+  const createdMatch = content.match(/Created:\s*(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})/);
+  if (createdMatch) meta.created = new Date(createdMatch[1].replace(' ', 'T'));
+
+  const branchMatch = content.match(/Branch:\s*(\S+)/);
+  if (branchMatch && !branchMatch[1].startsWith('[')) meta.branch = branchMatch[1];
+
+  const projMatch = content.match(/Project:\s*(.+?)(?:\n|$)/);
+  if (projMatch) meta.projectPath = projMatch[1].trim();
+
+  const fileMatches = content.matchAll(/\|\s*([a-zA-Z0-9_\-./]+\.[a-zA-Z]+)\s*\|/g);
+  for (const m of fileMatches) {
+    if (m[1].includes('/') && !m[1].startsWith('[')) meta.modifiedFiles.push(m[1]);
+  }
+
+  return meta;
+}
+
+function getCommitsSince(timestamp, cwd) {
+  if (!timestamp) return [];
+  const iso = timestamp.toISOString();
+  const { ok, out } = runCmd(`git log --since="${iso}" --oneline --no-decorate`, cwd);
+  return ok && out ? out.split('\n') : [];
+}
+
+function getChangedFilesSince(timestamp, cwd) {
+  if (!timestamp) return [];
+  const iso = timestamp.toISOString();
+  const { ok, out } = runCmd(`git log --since="${iso}" --name-only --pretty=format:`, cwd);
+  if (ok && out) {
+    return [
+      ...new Set(
+        out
+          .split('\n')
+          .map((f) => f.trim())
+          .filter(Boolean),
+      ),
+    ];
+  }
+  return [];
+}
+
+function checkFilesExist(files, cwd) {
+  const existing = [];
+  const missing = [];
+  for (const f of files) {
+    if (fs.existsSync(path.join(cwd, f))) existing.push(f);
+    else missing.push(f);
+  }
+  return { existing, missing };
+}
+
+function calculateStaleness(daysOld, commitsSince, filesChanged, branchMatches, filesMissing) {
+  const issues = [];
+  let score = 0;
+
+  if (daysOld > 30) {
+    score += 3;
+    issues.push(`Handoff is ${Math.floor(daysOld)} days old`);
+  } else if (daysOld > 7) {
+    score += 2;
+    issues.push(`Handoff is ${Math.floor(daysOld)} days old`);
+  } else if (daysOld > 1) {
+    score += 1;
+  }
+
+  if (commitsSince > 50) {
+    score += 3;
+    issues.push(`${commitsSince} commits since handoff - significant changes`);
+  } else if (commitsSince > 20) {
+    score += 2;
+    issues.push(`${commitsSince} commits since handoff`);
+  } else if (commitsSince > 5) {
+    score += 1;
+  }
+
+  if (!branchMatches) {
+    score += 2;
+    issues.push('Current branch differs from handoff branch');
+  }
+
+  if (filesMissing > 5) {
+    score += 2;
+    issues.push(`${filesMissing} referenced files no longer exist`);
+  } else if (filesMissing > 0) {
+    score += 1;
+    issues.push(`${filesMissing} referenced file(s) missing`);
+  }
+
+  if (filesChanged > 20) {
+    score += 2;
+    issues.push(`${filesChanged} files changed since handoff`);
+  } else if (filesChanged > 5) {
+    score += 1;
+  }
+
+  let level, recommendation;
+  if (score === 0) {
+    level = 'FRESH';
+    recommendation = 'Safe to resume - minimal changes since handoff';
+  } else if (score <= 2) {
+    level = 'SLIGHTLY_STALE';
+    recommendation = 'Generally safe to resume - review changes before continuing';
+  } else if (score <= 4) {
+    level = 'STALE';
+    recommendation = 'Proceed with caution - significant changes may affect context';
+  } else {
+    level = 'VERY_STALE';
+    recommendation = 'Consider creating new handoff - too many changes since original';
+  }
+
+  return { level, recommendation, issues };
+}
+
+function checkStaleness(handoffPath) {
+  if (!fs.existsSync(handoffPath)) return { error: `Handoff file not found: ${handoffPath}` };
+
+  const meta = parseHandoffMetadata(handoffPath);
+  const projectPath =
+    meta.projectPath && fs.existsSync(meta.projectPath)
+      ? meta.projectPath
+      : path.resolve(path.dirname(handoffPath), '..'); // Up from .handoffs/
+
+  const isGitRepo = runCmd('git rev-parse --git-dir', projectPath).ok;
+
+  const result = {
+    handoffFile: handoffPath,
+    projectPath,
+    isGitRepo,
+    created: meta.created,
+    handoffBranch: meta.branch,
+  };
+
+  if (meta.created) {
+    const age = Date.now() - meta.created.getTime();
+    result.daysOld = age / 86_400_000;
+    result.hoursOld = age / 3_600_000;
+  }
+
+  if (isGitRepo) {
+    const { out: currentBranch } = runCmd('git branch --show-current', projectPath);
+    result.currentBranch = currentBranch;
+    result.branchMatches = meta.branch ? currentBranch === meta.branch : true;
+
+    const commits = getCommitsSince(meta.created, projectPath);
+    result.commitsSince = commits.length;
+    result.recentCommits = commits.slice(0, 5);
+
+    const changedFiles = getChangedFilesSince(meta.created, projectPath);
+    result.filesChangedCount = changedFiles.length;
+    result.filesChanged = changedFiles.slice(0, 10);
+
+    const { existing, missing } = checkFilesExist(meta.modifiedFiles, projectPath);
+    result.referencedFilesExist = existing.length;
+    result.referencedFilesMissing = missing;
+
+    const { level, recommendation, issues } = calculateStaleness(
+      result.daysOld || 0,
+      result.commitsSince,
+      result.filesChangedCount,
+      result.branchMatches,
+      missing.length,
+    );
+    result.stalenessLevel = level;
+    result.recommendation = recommendation;
+    result.issues = issues;
+  } else {
+    result.stalenessLevel = 'UNKNOWN';
+    result.recommendation = 'Not a git repo - unable to detect changes';
+    result.issues = ['Project is not a git repository'];
+  }
+
+  return result;
+}
+
+function printReport(result) {
+  if (result.error) {
+    console.log(`Error: ${result.error}`);
+    return;
+  }
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('Handoff Staleness Report');
+  console.log('='.repeat(60));
+  console.log(`File: ${result.handoffFile}`);
+  console.log(`Project: ${result.projectPath}`);
+
+  if (result.created) {
+    console.log(`Created: ${result.created.toISOString().replace('T', ' ').slice(0, 19)}`);
+    if (result.daysOld != null) {
+      console.log(
+        result.daysOld < 1
+          ? `Age: ${result.hoursOld.toFixed(1)} hours`
+          : `Age: ${result.daysOld.toFixed(1)} days`,
+      );
+    }
+  }
+
+  console.log(`\nStaleness: ${result.stalenessLevel}`);
+  console.log(`Recommendation: ${result.recommendation}`);
+
+  if (result.issues && result.issues.length > 0) {
+    console.log('\nIssues:');
+    for (const issue of result.issues) console.log(`  - ${issue}`);
+  }
+
+  if (result.isGitRepo) {
+    console.log(
+      `\nBranch: ${result.currentBranch || 'detached'}${result.branchMatches ? ' (matches handoff)' : ` (handoff: ${result.handoffBranch})`}`,
+    );
+    console.log(`Commits since handoff: ${result.commitsSince}`);
+    console.log(`Files changed since handoff: ${result.filesChangedCount}`);
+    if (result.referencedFilesMissing.length > 0) {
+      console.log(`Missing referenced files: ${result.referencedFilesMissing.join(', ')}`);
+    }
+  }
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  console.log('Usage: node check_staleness.js <handoff-file>');
+  console.log('       node check_staleness.js .handoffs/2024-01-15-143022-auth.md');
+  process.exit(args.length === 0 ? 1 : 0);
+}
+
+if (args.includes('--json')) {
+  const result = checkStaleness(args.find((a) => !a.startsWith('-')));
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  const result = checkStaleness(args[0]);
+  printReport(result);
+}

package/scaffold/general/skills/session-handoff/scripts/create_handoff.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Smart scaffold generator for handoff documents.
+ *
+ * Creates a new handoff document with auto-detected metadata:
+ * - Current timestamp
+ * - Project path
+ * - Git branch (if available)
+ * - Recent git log
+ * - Modified/staged files
+ * - Handoff chain linking
+ *
+ * Usage:
+ *   node create_handoff.js [task-slug]
+ *   node create_handoff.js "implementing-auth"
+ *   node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md
+ *   node create_handoff.js  # auto-generates slug from timestamp
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+function _die(msg) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+}
+
+function runCmd(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, timeout: 10_000, encoding: 'utf-8' }).trim() };
+  } catch {
+    return { ok: false, out: '' };
+  }
+}
+
+function getGitInfo(projectPath) {
+  const info = {
+    isGitRepo: false,
+    branch: null,
+    recentCommits: [],
+    modifiedFiles: [],
+    stagedFiles: [],
+  };
+
+  if (!runCmd('git rev-parse --git-dir', projectPath).ok) return info;
+  info.isGitRepo = true;
+
+  const { ok: bOk, out: branch } = runCmd('git branch --show-current', projectPath);
+  if (bOk && branch) info.branch = branch;
+
+  const { ok: lOk, out: log } = runCmd('git log --oneline -5 --no-decorate', projectPath);
+  if (lOk && log) info.recentCommits = log.split('\n');
+
+  const { ok: mOk, out: modified } = runCmd('git diff --name-only', projectPath);
+  if (mOk && modified) info.modifiedFiles = modified.split('\n');
+
+  const { ok: sOk, out: staged } = runCmd('git diff --name-only --cached', projectPath);
+  if (sOk && staged) info.stagedFiles = staged.split('\n');
+
+  return info;
+}
+
+function findPreviousHandoffs(projectPath) {
+  const dir = path.join(projectPath, '.handoffs');
+  if (!fs.existsSync(dir)) return [];
+
+  const handoffs = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.md')) continue;
+    const fp = path.join(dir, name);
+
+    let title = name;
+    try {
+      const content = fs.readFileSync(fp, 'utf-8');
+      const m = content.match(/^#\s+(?:Handoff:\s*)?(.+)$/m);
+      if (m) title = m[1].trim();
+    } catch {
+      /* ignore */
+    }
+
+    let date = null;
+    const dm = name.match(/^(\d{4}-\d{2}-\d{2})-(\d{6})/);
+    if (dm) {
+      try {
+        date = new Date(`${dm[1]}T${dm[2].slice(0, 2)}:${dm[2].slice(2, 4)}:${dm[2].slice(4, 6)}`);
+      } catch {
+        /* ignore */
+      }
+    }
+
+    handoffs.push({ filename: name, path: fp, title, date });
+  }
+
+  handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
+  return handoffs;
+}
+
+function getPreviousHandoffInfo(projectPath, continuesFrom) {
+  const handoffs = findPreviousHandoffs(projectPath);
+
+  if (continuesFrom) {
+    const found = handoffs.find((h) => h.filename.includes(continuesFrom));
+    return found
+      ? { exists: true, filename: found.filename, title: found.title }
+      : { exists: false, filename: continuesFrom, title: 'Not found' };
+  }
+
+  if (handoffs.length > 0) {
+    return {
+      exists: true,
+      filename: handoffs[0].filename,
+      title: handoffs[0].title,
+      suggested: true,
+    };
+  }
+
+  return { exists: false };
+}
+
+function sanitizeSlug(slug) {
+  return slug
+    .toLowerCase()
+    .replace(/[\s_]/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+}
+
+function generateHandoff(projectPath, slug, continuesFrom) {
+  const now = new Date();
+  const timestamp = now.toISOString().replace('T', ' ').slice(0, 19);
+  const fileTs = `${now.toISOString().slice(0, 10)}-${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`;
+
+  if (!slug) slug = 'handoff';
+  slug = sanitizeSlug(slug);
+  const filename = `${fileTs}-${slug}.md`;
+
+  const handoffsDir = path.join(projectPath, '.handoffs');
+  fs.mkdirSync(handoffsDir, { recursive: true });
+  const filepath = path.join(handoffsDir, filename);
+
+  const git = getGitInfo(projectPath);
+  const prev = getPreviousHandoffInfo(projectPath, continuesFrom);
+
+  const branchLine = git.branch || '[not a git repo or detached HEAD]';
+
+  const commitsSection =
+    git.recentCommits.length > 0
+      ? git.recentCommits.map((c) => `  - ${c}`).join('\n')
+      : '  - [no recent commits or not a git repo]';
+
+  const allModified = [...new Set([...git.modifiedFiles, ...git.stagedFiles])];
+  let modifiedSection;
+  if (allModified.length > 0) {
+    modifiedSection = allModified
+      .slice(0, 10)
+      .map((f) => `| ${f} | [describe changes] | [why changed] |`)
+      .join('\n');
+    if (allModified.length > 10)
+      modifiedSection += `\n| ... and ${allModified.length - 10} more files | | |`;
+  } else {
+    modifiedSection = '| [no modified files detected] | | |';
+  }
+
+  let chainSection;
+  if (prev.exists) {
+    chainSection = `## Handoff Chain
+
+- **Continues from**: [${prev.filename}](./${prev.filename})
+  - Previous title: ${prev.title || 'Unknown'}
+- **Supersedes**: [list any older handoffs this replaces, or "None"]
+
+> Review the previous handoff for full context before filling this one.`;
+  } else {
+    chainSection = `## Handoff Chain
+
+- **Continues from**: None (fresh start)
+- **Supersedes**: None
+
+> This is the first handoff for this task.`;
+  }
+
+  const content = `# Handoff: [TASK_TITLE - replace this]
+
+## Session Metadata
+- Created: ${timestamp}
+- Project: ${projectPath}
+- Branch: ${branchLine}
+- Session duration: [estimate how long you worked]
+
+### Recent Commits (for context)
+${commitsSection}
+
+${chainSection}
+
+## Current State Summary
+
+[TODO: Write one paragraph describing what was being worked on, current status, and where things left off]
+
+## Codebase Understanding
+
+### Architecture Overview
+
+[TODO: Document key architectural insights discovered during this session]
+
+### Critical Files
+
+| File | Purpose | Relevance |
+|------|---------|-----------|
+| [TODO: Add critical files] | | |
+
+### Key Patterns Discovered
+
+[TODO: Document important patterns, conventions, or idioms found in this codebase]
+
+## Work Completed
+
+### Tasks Finished
+
+- [ ] [TODO: List completed tasks]
+
+### Files Modified
+
+| File | Changes | Rationale |
+|------|---------|-----------|
+${modifiedSection}
+
+### Decisions Made
+
+| Decision | Options Considered | Rationale |
+|----------|-------------------|-----------|
+| [TODO: Document key decisions] | | |
+
+## Pending Work
+
+### Immediate Next Steps
+
+1. [TODO: Most critical next action]
+2. [TODO: Second priority]
+3. [TODO: Third priority]
+
+### Blockers/Open Questions
+
+- [ ] [TODO: List blockers or open questions]
+
+### Deferred Items
+
+- [TODO: Items deferred and why]
+
+## Context for Resuming Agent
+
+### Important Context
+
+[TODO: Critical information the next agent MUST know]
+
+### Assumptions Made
+
+[TODO: List assumptions that might not be obvious]
+
+### Potential Gotchas
+
+[TODO: Things that could trip up the next agent]
+
+## Environment State
+
+[TODO: Required env vars, running processes, DB state]
+
+## Related Resources
+
+[TODO: Links to docs, PRs, issues, Slack threads]
+`;
+
+  fs.writeFileSync(filepath, content, 'utf-8');
+  return { filepath, filename };
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: node create_handoff.js [task-slug] [--continues-from <previous>]');
+  console.log('       node create_handoff.js "implementing-auth"');
+  console.log('       node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md');
+  process.exit(0);
+}
+
+let slug = null;
+let continuesFrom = null;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--continues-from' && i + 1 < args.length) {
+    continuesFrom = args[++i];
+  } else if (!args[i].startsWith('-')) {
+    slug = args[i];
+  }
+}
+
+const cwd = process.cwd();
+const { filepath } = generateHandoff(cwd, slug, continuesFrom);
+console.log(`Created handoff: ${filepath}`);
+console.log(`\nNext: Open the file and fill in all [TODO: ...] sections.`);
+console.log(`Then validate: node scripts/validate_handoff.js ${filepath}`);