@vpxa/aikit 0.1.73 → 0.1.75

package/scaffold/general/skills/session-handoff/references/handoff-template.md

@@ -1,139 +0,0 @@
-# Handoff Template
-
-Use this template structure when creating handoff documents. The smart scaffold script will pre-fill metadata sections; complete the remaining sections based on session context.
-
-## Table of Contents
-
-- [Session Metadata](#session-metadata)
-- [Current State Summary](#current-state-summary)
-- [Codebase Understanding](#codebase-understanding)
-  - [Architecture Overview](#architecture-overview)
-  - [Critical Files](#critical-files)
-  - [Key Patterns Discovered](#key-patterns-discovered)
-- [Work Completed](#work-completed)
-  - [Tasks Finished](#tasks-finished)
-  - [Files Modified](#files-modified)
-  - [Decisions Made](#decisions-made)
-- [Pending Work](#pending-work)
-  - [Immediate Next Steps](#immediate-next-steps)
-  - [Blockers/Open Questions](#blockersopen-questions)
-  - [Deferred Items](#deferred-items)
-- [Context for Resuming Agent](#context-for-resuming-agent)
-  - [Important Context](#important-context)
-  - [Assumptions Made](#assumptions-made)
-  - [Potential Gotchas](#potential-gotchas)
-- [Environment State](#environment-state)
-- [Related Resources](#related-resources)
-- [Template Usage Notes](#template-usage-notes)
-
----
-
-# Handoff: [TASK_TITLE]
-
-## Session Metadata
-- Created: [TIMESTAMP]
-- Project: [PROJECT_PATH]
-- Branch: [GIT_BRANCH]
-- Session duration: [APPROX_DURATION]
-
-## Current State Summary
-
-[One paragraph: What was being worked on, current status, and where things left off]
-
-## Codebase Understanding
-
-### Architecture Overview
-
-[Key architectural insights discovered during this session - how the system is structured, main components, data flow]
-
-### Critical Files
-
-| File | Purpose | Relevance |
-|------|---------|-----------|
-| path/to/file | What this file does | Why it matters for this task |
-
-### Key Patterns Discovered
-
-[Important patterns, conventions, or idioms found in this codebase that the next agent should follow]
-
-## Work Completed
-
-### Tasks Finished
-
-- [x] Task 1 - brief description of what was done
-- [x] Task 2 - brief description
-
-### Files Modified
-
-| File | Changes | Rationale |
-|------|---------|-----------|
-| path/to/file | Description of changes | Why this change was made |
-
-### Decisions Made
-
-| Decision | Options Considered | Rationale |
-|----------|-------------------|-----------|
-| Chose X over Y | X, Y, Z | Why X was chosen |
-
-## Pending Work
-
-### Immediate Next Steps
-
-1. [Most critical next action - what to do first]
-2. [Second priority]
-3. [Third priority]
-
-### Blockers/Open Questions
-
-- [ ] Blocker: [description] - Needs: [what's required to unblock]
-- [ ] Question: [unclear aspect] - Suggested: [potential resolution]
-
-### Deferred Items
-
-- Item 1 (deferred because: [reason, e.g., out of scope, needs user input])
-
-## Context for Resuming Agent
-
-### Important Context
-
-[Critical information the next agent MUST know to continue effectively - this is the most important section for handoff]
-
-### Assumptions Made
-
-- Assumption 1: [what was assumed to be true]
-- Assumption 2: [another assumption]
-
-### Potential Gotchas
-
-- [Things that might trip up a new agent - edge cases, quirks, non-obvious behavior]
-
-## Environment State
-
-### Tools/Services Used
-
-- [Tool/Service]: [relevant configuration or state]
-
-### Active Processes
-
-- [Any background processes, dev servers, watchers that may be running]
-
-### Environment Variables
-
-- [Key env vars that matter for this work - DO NOT include secrets/values, just names]
-
-## Related Resources
-
-- [Link to relevant documentation]
-- [Related file paths]
-- [External resources consulted]
-
----
-
-## Template Usage Notes
-
-When filling this template:
-1. Be specific and concrete - vague descriptions don't help the next agent
-2. Include file paths with line numbers where relevant (e.g., `src/auth.ts:142`)
-3. Prioritize the "Important Context" and "Immediate Next Steps" sections
-4. Don't include sensitive data (API keys, passwords, tokens)
-5. Focus on WHAT and WHY, not just WHAT - rationale is crucial for handoffs

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

@@ -1,80 +0,0 @@
-# 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

@@ -1,269 +0,0 @@
-#!/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);
-}