@vpxa/aikit 0.1.185 → 0.1.187

package/scaffold/dist/definitions/skills/session-handoff.mjs

@@ -1298,7 +1298,7 @@ if (args.includes('--json')) {
 }
 `},{file:`SKILL.md`,content:`---
 name: session-handoff
-description: "Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity, (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity."
+description: "Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity (>70% pressure), (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity."
 metadata:
   category: cross-cutting
   domain: general
@@ -1309,247 +1309,197 @@ metadata:
   relatedSkills: [lesson-learned]
 ---
 
-# Handoff
+# Session Handoff
 
-Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.
+Creates compact, high-signal handoffs so a fresh agent can resume work without rereading the full conversation.
 
-## Quick Reference
-
-**Purpose:** Create handoff documents for seamless AI session transfers. Solves context exhaustion — fresh agents continue with zero ambiguity.
-
-**Two modes:**
-- **CREATE** — Save current state when: user requests, context filling up, milestone completed, session ending
-- **RESUME** — Load prior state when: user says "continue", "resume", or references existing handoff
-
-**Dual storage** (every handoff creates both):
-1. **Full file** → \`.aikit-state/handoffs/{flow-slug}/<timestamp>-<slug>.md\` (browsable, gitignored)
-2. **Compact entry** → \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>" })\` (~1-2K chars, for \`withdraw\`)
-
-**CREATE workflow:** Gather state → Fill template (metadata, state summary, codebase understanding, work completed, pending work, resume context) → Save dual format → Present summary
+## Mindset
 
-**RESUME workflow:** \`withdraw({ scope: "flow", profile: "implementer" })\` → Read compact entry → If need full context, read file from \`.aikit-state/handoffs/\` → Verify state → Continue work
+Session handoffs solve the "context amnesia" problem — you have 200K tokens of accumulated understanding that will vanish. Your job is compression with zero information loss on the critical path.
 
-**Template sections:** Session Metadata | Current State | Codebase Understanding | Work Completed | Pending Work | Resume Context | Environment State | Related Resources
+Think of it as writing a briefing for a colleague who will take over your shift:
+- What's the current state? (not how we got here)
+- What decisions were made and WHY? (not what was considered)
+- What's blocked and needs action? (not what's going fine)
+- What will surprise them? (gotchas, non-obvious constraints)
 
-**Proactive trigger:** After 5+ file edits, complex debugging, or major decisions → suggest handoff.
+The 80/20 rule applies brutally: 80% of context is irrelevant to the next step. Identify the 20% that matters and make it crystal clear.
 
-## Mode Selection
-
-Determine which mode applies:
+## Quick Reference
 
-**Creating a handoff?** User wants to save current state, pause work, or context is getting full.
-- Follow: CREATE Workflow below
+Use this skill in two modes:
+- **CREATE** — when user asks to save context, context pressure exceeds ~70%, a milestone lands, or the session is ending
+- **RESUME** — when user asks to continue prior work, load saved context, or pick up from an existing handoff
 
-**Resuming from a handoff?** User wants to continue previous work, load context, or mentions an existing handoff.
-- Follow: RESUME Workflow below
+Every good handoff stores context in two forms:
+1. **Full markdown file** at \`.aikit-state/handoffs/{flow-slug}/YYYY-MM-DD-HHMMSS-[slug].md\`
+2. **Compact flow knowledge entry** via \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>", content })\`
 
-**Proactive suggestion?** After substantial work (5+ file edits, complex debugging, major decisions), suggest:
-> "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
+On resume, start with \`knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })\`. Only open the full handoff file if the compact entry is insufficient.
 
-> **aikit Integration:** Handoffs use dual storage — file in \`.aikit-state/handoffs/{flow-slug}/\` (gitignored, browsable) + compact knowledge entry (\`knowledge({ scope: "flow" })\`). On resume, \`withdraw\` retrieves the compact version automatically. For full context, read the file from \`.aikit-state/\`.
+## NEVER
 
-## Dual Format Storage
+- **NEVER include full file contents in handoffs** — reference file paths + what changed, not entire files. Handoffs that paste 1000 lines of code are useless because the next agent will need to re-read them anyway.
+- **NEVER omit the "why" behind decisions** — "chose JWT" is worthless without "chose JWT because: stateless, API consumers, no session store." The next agent WILL re-examine your decisions without the rationale.
+- **NEVER create a handoff without blockers/next-steps** — these are the single most important sections. Everything else provides context; these drive action.
+- **NEVER hand off mid-failure** without capturing: error message, what was tried, what was NOT tried yet. Incomplete failure context causes the next agent to repeat failed approaches.
+- **NEVER include conversation history** — handoffs summarize OUTCOMES not PROCESS. "We discussed 3 options and chose X" not "I said... user said... I said..."
+- **NEVER create handoffs larger than 500 words** — if it's longer, you're pasting instead of summarizing. Compress ruthlessly.
+- **NEVER skip the architecture context** — the next agent doesn't know the codebase. Include: key files, patterns used, critical constraints.
 
-Each handoff creates TWO artifacts:
+## Handoff Quality Gate
 
-1. **Full document** → \`.aikit-state/handoffs/{flow-slug}/<timestamp>-<slug>.md\`
-  - Complete template with all sections
-  - Browsable on disk but NOT committed to git
-  - Auto-cleaned when \`.aikit-state/\` is cleared
+A good handoff passes the "cold start" test: could a brand-new agent, with NO prior context, pick up where you left off and produce correct output on the FIRST attempt?
 
-2. **Compact knowledge entry** → \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>", content: "<compact format>" })\`
-  - ~1-2K chars, optimized for \`withdraw\` retrieval
-  - Contains: State, Decisions, Next Steps, Blockers, Assumptions
-  - Auto-retrieved by resuming agents via \`withdraw({ scope: "flow", profile: "implementer", budget: 6000 })\`
+Score your handoff (must be 4/4):
+- [ ] **Actionable** — next steps are specific enough to execute without interpretation
+- [ ] **Self-contained** — doesn't require reading the conversation to understand
+- [ ] **Minimal** — no content that doesn't directly serve the next agent's work
+- [ ] **Verified** — decisions cite evidence (file:line, test output, tool result)
 
-The compact format ensures continuity even if the next session doesn't explicitly load the full handoff file.
+If any criterion fails, compress further or add the missing context.
 
 ## CREATE Workflow
 
-### Step 1: Generate Scaffold
-
-Run the smart scaffold script to create a pre-filled handoff document:
-
-\`\`\`bash
-node scripts/create_handoff.js [task-slug]
-node scripts/create_handoff.js [task-slug] --flow <flow-slug>
-\`\`\`
-
-Example: \`node scripts/create_handoff.js implementing-user-auth\`
+### 1. Choose storage target
 
-**For continuation handoffs** (linking to previous work):
-\`\`\`bash
-node scripts/create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md
-\`\`\`
+Save the full handoff at one of these locations:
+- Flow-scoped: \`.aikit-state/handoffs/{flow-slug}/YYYY-MM-DD-HHMMSS-[slug].md\`
+- Standalone: \`.aikit-state/handoffs/_standalone/YYYY-MM-DD-HHMMSS-[slug].md\`
 
-The script generates:
-- Full handoff file in \`.aikit-state/handoffs/{active-flow}/\`
-- Compact format string (printed to stdout for pasting into \`knowledge({ action: "remember", ... })\`)
+Use a slug that describes the active task, not the conversation.
 
-It also:
-- Uses \`--flow\` to override the active flow slug
-- Falls back to \`.aikit-state/handoffs/_standalone/\` when no flow is active
-- Pre-fills: timestamp, project path, git branch, recent commits, modified files
-- Adds handoff chain links if continuing from previous
-- Outputs file path for editing
+### 2. Gather only critical-path facts
 
-### Step 2: Complete the Handoff Document
+Before writing, capture the minimum context needed for a cold start:
+- Current state: what is done, in progress, failing, or pending
+- Key files: exact paths and why they matter
+- Decisions: what was chosen and why
+- Verification: tests, checks, tool results, or specific evidence
+- Blockers: error text, attempted fixes, untried options
+- Next steps: ordered, concrete actions
 
-Open the generated file and fill in all \`[TODO: ...]\` sections. Prioritize these sections:
+Use AI Kit tools inline instead of external scripts:
+- \`stash({ action: "set", key: "handoff:<slug>:notes", value })\` for temporary compression while drafting
+- \`checkpoint({ action: "save", label: "handoff-<slug>", notes })\` when session state itself matters
+- \`knowledge({ action: "list", category: "decisions" })\` and \`search({ query })\` to pull prior decisions into the handoff when relevant
 
-1. **Current State Summary** - What's happening right now
-2. **Important Context** - Critical info the next agent MUST know
-3. **Immediate Next Steps** - Clear, actionable first steps
-4. **Decisions Made** - Choices with rationale (not just outcomes)
+### 3. Write the full handoff
 
-Use the template structure in [references/handoff-template.md](references/handoff-template.md) for guidance.
+Use this structure:
 
-### Step 3: Validate the Handoff
+\`\`\`md
+# Handoff: <task>
 
-Run the validation script to check completeness and security:
+## Current State
+- Status:
+- Last completed step:
+- Current failure or pending task:
 
-\`\`\`bash
-node scripts/validate_handoff.js <handoff-file>
-\`\`\`
+## Critical Files
+- path/to/file - purpose + why it matters now
 
-The validator checks:
-- [ ] No \`[TODO: ...]\` placeholders remaining
-- [ ] Required sections present and populated
-- [ ] No potential secrets detected (API keys, passwords, tokens)
-- [ ] Referenced files exist
-- [ ] Quality score (0-100)
+## Decisions
+- Decision: why
+- Evidence: file:line | test output | tool result
 
-**Do not finalize a handoff with secrets detected or score below 70.**
+## Next Steps
+1. First action
+2. Second action
+3. Third action
 
-### Step 4: Confirm Handoff
+## Blockers
+- Blocker:
+- Tried:
+- Not tried yet:
 
-Report to user:
-- Handoff file location
-- Validation score and any warnings
-- Summary of captured context
-- First action item for next session
+## Gotchas
+- Non-obvious constraint or pattern
+\`\`\`
 
-## RESUME Workflow
+Use [references/handoff-template.md](references/handoff-template.md) when you need a fuller structure, but delete sections that add no value.
 
-### Step 1: Find Available Handoffs
+### 4. Save compact flow knowledge
 
-List handoffs in the current project:
+Store a compressed version for automatic resume:
 
-\`\`\`bash
-node scripts/list_handoffs.js
+\`\`\`
+knowledge({
+  action: "remember",
+  scope: "flow",
+  category: "session",
+  title: "Session Handoff: <slug>",
+  content: "State: ...
+Decisions: ...
+Next: ...
+Blockers: ...
+Evidence: ..."
+})
 \`\`\`
 
-This shows all handoffs with dates, titles, and completion status.
-
-### Step 2: Check Staleness
+Target 1-2K characters. This is the resume fast-path.
 
-Before loading, check how current the handoff is:
+### 5. Self-review before finalizing
 
-\`\`\`bash
-node scripts/check_staleness.js <handoff-file>
-\`\`\`
+Confirm all of the following:
+- No secrets, tokens, or raw credentials
+- No pasted file dumps
+- Every decision includes rationale
+- Every blocker includes attempted and untried paths
+- Next step #1 is immediately executable
+- Quality Gate score is 4/4
 
-Staleness levels:
-- **FRESH**: Safe to resume - minimal changes since handoff
-- **SLIGHTLY_STALE**: Review changes, then resume
-- **STALE**: Verify context carefully before resuming
-- **VERY_STALE**: Consider creating a fresh handoff
+## RESUME Workflow
 
-The script checks:
-- Time since handoff was created
-- Git commits since handoff
-- Files changed since handoff
-- Branch divergence
-- Missing referenced files
+### 1. Pull compact context first
 
-### Step 2b: Check Flow Knowledge
+Start with:
 
-If a flow is active, check for compact handoffs in flow knowledge:
 \`\`\`
 knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })
 \`\`\`
 
-If a "Session Handoff:" entry appears but is truncated:
+If the entry is truncated or multiple handoffs exist, use:
+
 \`\`\`
 knowledge({ action: "list", category: "session", scope: "flow" })
 knowledge({ action: "read", path: "<handoff-entry>" })
 \`\`\`
 
-### Step 3: Load the Handoff
+### 2. Load the full handoff only when needed
 
-Read the relevant handoff document completely before taking any action.
+Open the markdown file in \`.aikit-state/handoffs/\` if the compact entry lacks enough detail to act safely.
 
-If handoff is part of a chain (has "Continues from" link), also read the linked previous handoff for full context.
+### 3. Verify live state before coding
 
-### Step 4: Verify Context
+Do a fast reality check:
+- Does current branch still match the handoff assumptions?
+- Do referenced files still exist?
+- Have blockers already been resolved?
+- Do stated next steps still make sense against current diff and tests?
 
-Follow the checklist in [references/resume-checklist.md](references/resume-checklist.md):
+Use the checklist in [references/resume-checklist.md](references/resume-checklist.md) for the verification pass.
 
-1. Verify project directory and git branch match
-2. Check if blockers have been resolved
-3. Validate assumptions still hold
-4. Review modified files for conflicts
-5. Check environment state
+### 4. Resume from the first actionable step
 
-### Step 5: Begin Work
+Begin with Next Step #1. If reality differs from the handoff, update the handoff or create a successor handoff instead of silently continuing on stale assumptions.
 
-Start with "Immediate Next Steps" item #1 from the handoff document.
+## Chaining Rule
 
-Reference these sections as you work:
-- "Critical Files" for important locations
-- "Key Patterns Discovered" for conventions to follow
-- "Potential Gotchas" to avoid known issues
+For long-running work, create a successor handoff instead of overwriting history. Each new handoff should state what it supersedes and what changed since the previous handoff.
 
-### Step 6: Update or Chain Handoffs
+## Output Expectations
 
-As you work:
-- Mark completed items in "Pending Work"
-- Add new discoveries to relevant sections
-- For long sessions: create a new handoff with \`--continues-from\` to chain them
-
-## Handoff Chaining
-
-For long-running projects, chain handoffs together to maintain context lineage:
-
-\`\`\`
-handoff-1.md (initial work)
-    ↓
-handoff-2.md --continues-from handoff-1.md
-    ↓
-handoff-3.md --continues-from handoff-2.md
-\`\`\`
+When asked to create a handoff, return:
+- Handoff status
+- File path written
+- Key decisions captured
+- Top blocker or next step
 
-Each handoff in the chain:
-- Links to its predecessor
-- Can mark older handoffs as superseded
-- Provides context breadcrumbs for new agents
-
-When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.
-
-## Storage Location
-
-**Primary (flow-scoped):** \`.aikit-state/handoffs/{flow-slug}/\`
-**Standalone fallback:** \`.aikit-state/handoffs/_standalone/\` (when no flow is active)
-
-All handoffs live in \`.aikit-state/\` which is gitignored — handoffs are ephemeral context, not project history.
-
-Naming convention: \`YYYY-MM-DD-HHMMSS-[slug].md\`
-
-Example: \`2024-01-15-143022-implementing-auth.md\`
+Do not return conversation transcripts or visual dashboards.
 
 ## Resources
 
-### scripts/
-
-| Script | Purpose |
-|--------|---------|
-| \`create_handoff.js [slug] [--continues-from <file>] [--flow <flow-slug>]\` | Generate new handoff with smart scaffolding |
-| \`list_handoffs.js [path]\` | List available handoffs in a project |
-| \`validate_handoff.js <file>\` | Check completeness, quality, and security |
-| \`check_staleness.js <file>\` | Assess if handoff context is still current |
-
-### references/
-
-- [handoff-template.md](references/handoff-template.md) - Complete template structure with guidance
-- [resume-checklist.md](references/resume-checklist.md) - Verification checklist for resuming agents
+- [references/handoff-template.md](references/handoff-template.md) - full markdown template when a simple structure is insufficient
+- [references/resume-checklist.md](references/resume-checklist.md) - verification checklist before resuming from saved context
 `}];export{e as default};

package/scaffold/dist/definitions/skills/typescript.mjs

@@ -14,6 +14,12 @@ metadata:
 
 > Comprehensive TypeScript development patterns — type system performance, compiler configuration, advanced types, type safety, async patterns, module organization, and runtime optimization. Synthesized from pproenca TypeScript rules, TypeScript 6.0 features, wshobson advanced types and modern JS patterns, and Jeffallan typescript-pro patterns.
 
+## Mindset
+
+Type errors are specifications, not obstacles. Every red squiggle is the compiler telling you about a contract violation BEFORE runtime. Your job is to make impossible states unrepresentable — if the type system allows an invalid value, the design is wrong.
+
+Think in terms of: narrowing (make types more specific at each step), branding (distinguish structurally identical types by meaning), and exhaustiveness (force the compiler to verify all cases are handled).
+
 ## When to Use
 
 **MANDATORY** for the Implementer agent on every TypeScript task. Also use when:
@@ -22,6 +28,16 @@ metadata:
 - Designing type-safe APIs, libraries, or utilities
 - Optimizing type-check performance or build times
 
+## NEVER
+
+- **NEVER use \`as\` to silence type errors** — it hides bugs. Use type guards, assertion functions, or fix the upstream type instead. \`as\` is only acceptable for test mocks with \`as unknown as T\` pattern.
+- **NEVER use \`any\` in exported signatures** — it infects every consumer. Use \`unknown\` + narrowing, generics, or explicit union types. \`any\` in implementation internals is tolerable if contained.
+- **NEVER use \`!\` (non-null assertion) without a runtime guard** — it's a lie to the compiler. If you're sure it's not null, prove it with an \`if\` check or \`?? throw\`.
+- **NEVER mix null and undefined semantics** — pick one convention per codebase. Prefer \`undefined\` for "not set" (matches optional properties), \`null\` for "explicitly empty" (matches DOM/JSON).
+- **NEVER export mutable state as a shared type** — use \`readonly\` modifier, \`Readonly<T>\`, or \`ReadonlyArray<T>\`. Mutable shared state causes action-at-a-distance bugs that types cannot catch.
+- **NEVER use \`enum\` in new code** — use \`as const\` objects or string literal unions. Enums have runtime cost, tree-shaking issues, and numeric enums allow unsafe access.
+- **NEVER ignore generic constraints** — if a function works on "any array", type it as \`T extends readonly unknown[]\`, not \`T[]\`. Constraints document intent and catch misuse at call sites.
+
 ## Type System Performance
 
 These rules prevent slow type-checking and IDE lag: