var e=[{file:`SKILL.md`,content:`---
name: aikit
description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, context compression, validation, and persistent memory. Load at session start or before using aikit_* tools. This skill teaches tool judgment: minimize raw reads, choose the smallest useful retrieval path, and persist decisions that matter."
metadata:
  category: cross-cutting
  domain: general
  applicability: always
  inputs: [codebase]
  outputs: [search-results, analysis, knowledge]
  relatedSkills: [session-handoff, present]
---

# @vpxa/aikit — AI Kit

> This skill provides DEEP GUIDANCE beyond base instructions. For tool routing rules, see your base instructions.

Local-first AI developer toolkit with 60+ tools for search, analysis, compression, validation, memory, flows, and coordination.

## When to Use

- You need to understand unfamiliar code without raw-reading large files.
- You need structured search across code, docs, and prior decisions.
- You need typecheck, test, or audit results in structured form.
- You need memory across sessions, not just within one conversation.
- You need to estimate blast radius before changing shared code.
- You need guided flows, FORGE gates, or coordination primitives.

## Mindset

AI Kit tools are a compression layer. Their job is to prevent agents from wasting tokens on raw file reads and flat text search.

Every call should reduce context, not add to it.

Think: what's the minimum I need to read to act? Then choose the tool that gives exactly that.

Common mistake: using \`read_file\` out of habit. That is the last resort, not the first.

Default progression: \`file_summary\` → \`compact\` → \`digest\` → \`read_file\` only for exact edit lines.

If you are unsure which tool fits, ask AI Kit for the live catalog with \`list_tools\`, then narrow with \`search_tools\` or \`describe_tool\`.

## Operating Model

1. Orient with compressed retrieval, not raw reads.
2. Validate with structured tools, not noisy terminal output.
3. Persist decisions that future sessions must reuse.
4. Reuse previous context before searching again.
5. Use reference docs only when the main routing logic is not enough.

**When tools return empty:**
- \`search\` → 0 results? Broaden query terms OR fall back to \`find({ pattern })\` with regex
- \`symbol\` → not found? Check spelling, try \`search\` with partial name
- \`compact\` → irrelevant content? Refine \`query\` parameter or try different \`segmentation\`

## Session Protocol

### Why This Matters

Without session discipline, agents repeat work, miss context, and make decisions that contradict earlier choices. These steps exist to keep work cumulative.

### Start (do first, every session)

1. \`status({})\` — Why: confirms index is built, tools are ready, and onboard state is known. Skipping this causes tool-avoidance and blind exploration.
2. \`search({ query: "SESSION CHECKPOINT", origin: "curated" })\` — Why: pulls prior session context so you do not re-solve finished work.
3. \`scope_map({ task })\` — Why: creates a reading plan before exploration, which prevents broad wandering.
4. If a flow may already exist, run \`flow({ action: 'status' })\` — Why: flow state is part of task state. Resuming the wrong way duplicates work.
5. If onboard is missing, run \`onboard({ path: "." })\` — Why: AI Kit is strongest after structure, patterns, and symbols are pre-analyzed.

### During (do continuously)

- \`stash({ action: "set", key, value })\` for intermediate results — Why: chat context compresses; stash survives it.
- \`knowledge({ action: "remember" })\` for decisions and conventions — Why: decisions must outlive the current conversation.
- \`checkpoint({ action: "save" })\` before risky multi-step changes — Why: it gives you a known milestone for recovery.
- \`blast_radius\` before shared-symbol edits — Why: public changes are rarely local.
- \`check\` and \`test_run\` after changes — Why: verification is cheaper than debugging assumptions later.

### End (do always)

- \`session_digest({ persist: true })\` — Why: captures tool trajectory and supports crash recovery.
- \`knowledge({ action: "remember", title: "Session checkpoint: <topic>" })\` — Why: the next session's first search is looking for exactly this.
- \`reindex\` after structural code changes — Why: stale index data makes every later search worse.
- \`knowledge({ action: "flagged" })\` periodically (not every session, but every few) — Why: decayed entries accumulate; reviewing them prevents stale advice from persisting.

## Anti-Patterns (NEVER)

- NEVER \`search\` then immediately \`read_file\` the result — search already returns content snippets
- NEVER call \`compact\` on a file you just \`file_summary\`'d — pick one retrieval depth
- NEVER stash >10 items without \`checkpoint\` — stash has no TTL, checkpoints do
- NEVER run \`reindex\` mid-implementation — wait until all edits are done
- NEVER skip \`search\` before implementing — past decisions may exist that constrain your approach
- NEVER echo full subagent output to user — compress with \`stash\` + brief summary

## Search Strategy

1. Start with \`search\` in hybrid mode unless you know you need exact identifiers.
2. Switch to \`symbol\` when the question is about one named thing.
3. Switch to \`trace\` when the question is flow, not location.
4. Switch to \`graph\` when the question is relationships between modules or importers.
5. Use \`compact\`, not raw file reads, once you know the file and the question.

## Judgment Patterns

### Understanding a New Area

~~~text
search → scope_map → file_summary/compact → graph or trace → stash
~~~

Use this when you need a fast mental model. Do not start with \`read_file\`.

### Investigating a Bug

~~~text
search → symbol → trace → compact → check/test_run → knowledge remember
~~~

Use this when the failure path matters more than file ownership.

### Refactoring Shared Code

~~~text
blast_radius → checkpoint → compact/file_summary → rename or codemod → check → test_run
~~~

Use this when contract breakage is more dangerous than local implementation detail.

### Picking the Right Tool

~~~text
list_tools → search_tools → describe_tool → execute
~~~

Use this instead of baking a static catalog into the skill. Tool metadata is live at runtime.

## Memory Discipline

- Use \`stash\` for temporary state you may need again in the same task.
- Use \`checkpoint\` for recoverable milestones in longer sessions.
- Use \`knowledge\` for decisions, conventions, non-obvious findings, and reusable lessons.
- Search curated memory before inventing a new pattern.
- Keep memory high-signal. Store what must survive, not everything you observed.

## Memory Lifecycle

AI Kit auto-captures knowledge from tool outputs. Know what it captures so you can leverage it.

### Auto-Knowledge Capture

Every tool call passes through extractors that capture reusable facts:

| Extractor | Tools Covered | What It Captures |
|-----------|--------------|-----------------|
| **Content reads** | \`compact\`, \`file_summary\`, \`digest\`, \`lookup\`, \`stratum_card\` | File structure, exports, compressed sections |
| **Symbol analysis** | \`symbol\`, \`trace\`, \`graph\` (read-only) | Definitions, references, call chains, module relationships |
| **Research results** | \`web_search\`, \`web_fetch\`, \`search\`, \`find\` | Search findings, web content, code discoveries |
| **Behavioral patterns** | ALL tools (ring buffer) | Tool preferences, search→edit sequences, error-fix cycles |

**Refresh model:** High-use extractors should converge on stable facts keyed by path, task, query, or analysis scope. Revisiting the same thing should refresh or no-op instead of multiplying near-duplicate memory.

**Retrieval:** Use \`enrich: true\` on any tool that supports it — the server automatically surfaces previously captured facts relevant to your query. Search/find/knowledge responses can also emit reusable \`ctxc_...\` refs; pass them as \`ref\` to \`compact({ ref })\` or \`compact({ ref, query? })\` instead of reopening the source. \`ctxc_...\` is a reversible ref, not an id or path.

**Best practice:** Before re-reading a file you've already explored, try \`search({ query: "exact-file-path-or-topic" })\` first. If you already have a \`ctxc_...\` ref, reuse it with \`compact({ ref })\` or \`compact({ ref, query? })\`. Reach for fresh \`file_summary\` / \`scope_map\` calls only when the topic materially changed or retrieval came back thin.

### Retention & Tier Promotion
- Memories start at **working** tier → promote on repeated access: episodic (2) → semantic (5) → procedural (10)
- Unused entries decay via Ebbinghaus curve. Re-accessing important memories strengthens them.
- Check decayed entries: \`knowledge({ action: "flagged" })\` — review, refresh important ones, forget stale ones.

### Lessons

Capture reusable engineering insights via \`knowledge({ action: "lesson", subAction: "create" })\`. Confirm with \`confirm\`, contradict with \`contradict\`, list with \`list-lessons\`. Confidence 60-70 for single-observation, 80+ when multiple diffs confirm. Auto-archived below 20 confidence after contradictions.

See the \`lesson-learned\` skill for the full extraction workflow.

### Lesson Lifecycle Management

| SubAction | Purpose | Default |
|-----------|---------|---------|
| \`prune\` | Archive stale lessons (confidence < 15, idle > 30d) | dryRun: true |
| \`group\` | Cluster similar lessons, add group tags | dryRun: true |
| \`promote\` | Cross-workspace promotion to global store | dryRun: true |
| \`demote\` | Remove from global store | -- |
| \`auto-observe\` | Pattern detection from tool outputs | automatic |

**Maintenance workflow** (periodic):
\`\`\`
knowledge({ action: "lesson", subAction: "prune" })   // review stale
knowledge({ action: "lesson", subAction: "group" })   // organize
knowledge({ action: "lesson", subAction: "promote" }) // share universal
\`\`\`

### Session Prelude
Request context-primed session start:
\`\`\`
status({ includePrelude: true })
\`\`\`
Returns: top 3 lessons (by decayed confidence), top 2 conventions (by recency), last session checkpoint.
Use at session start for immediate situational awareness.

### Confidence Decay
Lesson confidence decays over time via Ebbinghaus curve:
- Accessing lessons (via withdraw, list-lessons) implicitly reinforces them
- Unaccessed lessons gradually lose confidence
- Below threshold 15 + idle > 30 days -> eligible for pruning
- \`knowledge({ action: "flagged" })\` surfaces decayed entries for review

### Supersession (automatic dedup)
When you \`remember()\`, similar entries are detected automatically:
- Jaccard > 0.7 → flagged for review
- Jaccard > 0.95 → auto-superseded (replaced)
- Use \`force: true\` to explicitly supersede flagged entries

## Flows

Flows are the preferred path for guided multi-step work.

- Use \`flow({ action: 'status' })\` first to detect active work.
- Use \`flow({ action: 'list' })\` when the task looks repeatable or cross-cutting.
- Use \`flow({ action: 'read' })\` before acting inside a started flow.
- Use native agent workflow only when no flow matches the problem.

## Reference Docs

Load these only when the main skill is not enough:

- \`references/coordination.md\` — queue, lanes, stash, checkpoints, signaling
- \`references/forge-protocol.md\` — tiering, evidence, gates
- \`references/search-patterns.md\` — search, trace, graph, compression patterns

## Complementary Skills

- Load \`typescript\` before TypeScript-heavy implementation work.
- Load \`react\` before React component or hooks work.
- Load \`session-handoff\` when context is filling up or a pause is imminent.
- Load \`repo-access\` when repo auth fails.

## Self-Dogfooding

When developing AI Kit itself, rebuild generated output before trusting runtime behavior, and reindex after structural changes so the toolkit can see its own new shape.
`},{file:`references/coordination.md`,content:`# Coordination

Use coordination tools when work is parallel, long-running, or easy to repeat incorrectly.

## Pick the Right Primitive

- \`queue\` for ordered task execution or DAG-style dependencies.
- \`lane\` for isolated exploration of alternative approaches.
- \`workset\` for named file groups you will revisit.
- \`stash\` for temporary intermediate results between tool calls.
- \`checkpoint\` for recoverable milestones before risky changes.
- \`signal\` for cross-agent status or file-level leases.

## Minimal Patterns

~~~text
Multi-step task: queue → next → done/fail
Try two approaches: lane create A/B → diff → merge winner
Need same files repeatedly: workset save → get
Need temporary findings later: stash set → get
About to make risky change: checkpoint save → edit → load only if recovery needed
Parallel agents: signal post/get or lease/unlease
~~~

## Rule of Thumb

If the problem is about sequence, use \`queue\`. If it is about comparison, use \`lane\`. If it is about memory within one effort, use \`stash\` or \`checkpoint\`.
`},{file:`references/forge-protocol.md`,content:`# FORGE Protocol

Use FORGE when the task is large enough that being "probably right" is not enough.

## Tiering

- Floor: single-file, low-blast-radius, few unknowns.
- Standard: multi-file or non-trivial. Default when unsure.
- Critical: schema, security, cross-service, or high-blast-radius work.

Start with \`forge_classify\` if tier is unknown. Use \`forge_ground\` when you want one call to classify, scope, load constraints, and seed evidence.

## Flow

~~~text
Ground → Build → Break → Gate
~~~

- Ground: classify task, gather constraints, identify unknowns.
- Build: implement with evidence-backed claims.
- Break: challenge assumptions and edge cases.
- Gate: evaluate evidence quality before declaring completion.

## Core Tools

- \`forge_classify\` to size ceremony.
- \`forge_ground\` to bootstrap full context.
- \`evidence_map\` to track verified, assumed, and unresolved claims.
- \`blast_radius\`, \`check\`, and \`test_run\` to verify the implementation actually holds.

## Rule of Thumb

If the task crosses boundaries or would be expensive to get wrong, pay the FORGE cost up front.
`},{file:`references/search-patterns.md`,content:`# Search Patterns

Use the smallest search primitive that answers the real question.

## Routing

~~~text
Need rough discovery?        → search
Need one named thing?        → symbol
Need real usage examples?    → find({ mode: 'examples' })
Need call/data flow?         → trace
Need import/module graph?    → graph
Need file reading plan?      → scope_map
Need one file section?       → compact
Need many files compressed?  → digest
~~~

## Heuristics

- Use \`search\` first when you know the topic but not the owner.
- Use \`symbol\` when the question is definition, imports, or refs.
- Use \`trace\` when you care about execution path.
- Use \`graph\` when you care about who depends on what.
- Use \`compact\` after you already know the file and the question.
- Use \`file_summary\` before \`compact\` if you still need structure.

## Compression Ladder

~~~text
file_summary → compact → digest → read_file only for edit lines
~~~

## Rule of Thumb

If you are about to read raw code, ask whether the answer is really about structure, relevance, flow, or relationships. AI Kit has a smaller tool for each of those.
`}];export{e as default};