@vpxa/aikit 0.1.384 → 0.1.385

package/scaffold/dist/definitions/bodies.mjs

@@ -169,7 +169,8 @@ Use web_fetch/http first. On auth failure, load repo-access; if exhausted, use A
 - After read-only/epilogue-only flows: no reindex (0 token cost). remember decisions as normal.
 - If re-onboard/reindex fails: log warning, surface in flow status, do not block.
 - Flow-derived promotion: evidence-backed promotion candidates from final consolidation; confidence alone never promotes.
-- session_digest({ persist: true }).`,Planner:`${r()}
+- session_digest({ persist: true }).
+- **Contribute durable knowledge**: After meaningful work, persist user preferences, repo conventions, architecture invariants, pitfalls, and lessons via \`knowledge({ action: "remember|lesson", ... })\` with appropriate categories and tags. Without curation the workspace skill stays at structural-only — curated facts make it self-improving.`,Planner:`${r()}
 
 > **Reminder:** Follow ## MANDATORY FIRST ACTION from your shared base protocol.
 

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

@@ -1,4 +1,124 @@
-var e=[{file:`SKILL.md`,content:"---\nname: aikit\ndescription: \"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.\"\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [codebase]\n  outputs: [search-results, analysis, knowledge]\n  relatedSkills: [session-handoff, present]\n---\n\n# @vpxa/aikit - AI Kit\n\nUse AI Kit as compression, memory, validation, and coordination layer. Each call should reduce uncertainty or token load.\n\n## Communicating With the User\n\n**Use `present({ schemaVersion: 1, title, blocks })` for ALL non-trivial output.** This is the preferred way to show summaries, results, evidence maps, task plans, reviews, comparisons, dashboards, charts, timelines, and batch results to the user. Plain text is only for 1-2 sentence status updates or simple questions. The `present` tool renders rich, structured output that the user can interact with.\n\n## Session Loop\n\nStart:\n1. status({ includePrelude: true }).\n2. If `onboarded` is false or `prelude.onboardContext` / `structuredContent.onboard_context` is null → run `onboard({ path, mode: 'generate' })`, then `status({ includePrelude: true })` again.\n3. If `onboard_context.freshness.status` is `stale` or `unknown`, or `nextAction.kind === \"update_onboard\"` → run `onboard({ path, update: true })`, then `status({ includePrelude: true })` again.\n4. **Workspace context start**: Extract workspace skill + fresh onboard context from status: `workspace_skill.uri`, `prelude.workspaceSkillResource`, `onboard_context.freshness`, `onboard_context.packageMap`, `onboard_context.architecture`, and `onboard_context.recommendedReadOrder`. Read `aikit://skill/SKILL.md` when full repo-specific guidance is needed. Use fresh onboard context before broad retrieval. ≤ 2,100 tokens.\n5. search({ query: \"SESSION CHECKPOINT\", origin: \"curated\" }).\n6. flow({ action: 'status' }) when active flow may exist — use L1 snapshot before broad retrieval.\n7. scope_map({ task }) only when workspace context + checkpoint do not identify a narrow workset.\n\nDuring:\n- Prefer search/file_summary/digest/symbol/trace/graph over raw reads.\n- Use stash for temporary findings; knowledge for durable decisions.\n- Run blast_radius before shared/public edits.\n- Validate with check + relevant test_run.\n\nEnd:\n- reindex after structural changes.\n- produce_knowledge for durable project updates.\n- session_digest({ persist: true }).\n- knowledge remember session checkpoint with done/decisions/next/blockers.\n\n## Retrieval Ladder — Layered (Workspace Context + L1-L3)\n\n> This table maps knowledge layers to tool needs. For the canonical quick-reference tool decision table, see `aiKitToolPreference()` in protocols.mjs.\n\n| Layer | Need | Tool |\n|-------|------|------|\n| **Workspace Context** | Workspace skill + fresh onboard context | `status({ includePrelude: true })`; read `aikit://skill/SKILL.md` only when full guidance is needed. Run `onboard({ path, mode: 'generate' })` if `onboard_context` is missing; run `onboard({ path, update: true })` if `onboard_context.freshness.status` is `stale` or `unknown`. Consume fresh context before broad scans. |\n| **Workspace Context** | Architecture overview | `status({ includePrelude: true }).onboard_context.architecture`, then onboard `diagram.md` / `domains.md` when deeper detail is needed |\n| **Workspace Context** | Package map / repo shape | `status({ includePrelude: true }).onboard_context.packageMap`, then onboard `structure.md` / `dependencies.md` |\n| **Flow Context** | Flow-specific context | L1 flow snapshot via `knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })` |\n| **L1** | Active flow state | `knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })` |\n| **L2** | Prior decisions/conventions | `search` / `knowledge` |\n| **L2** | File structure | `file_summary({ files, tier: 'T1' })` |\n| **L2** | Exact relevant section | `file_summary({ files, tier: 'T2' })` |\n| **L2** | Many files | `digest` |\n| **L2** | Symbol defs/refs | `symbol` |\n| **L2** | Call/data flow | `trace` |\n| **L2** | Module/import relationships | `graph` |\n| **L2** | Impact | `blast_radius` |\n| **L2** | Type/lint/test | `check` / `test_run` |\n| **L3** | Evidence, provenance, conflict review | `search` with `knowledge({ action: 'lesson' })` — focused only |\n| **General** | Tool choice unknown | `list_tools({ intent: \"<task>\" })` (use intent param for planner-ranked results) or `search({ query: \"tool to <do X>\" })` |\n\nRaw read_file only for exact edit lines after compressed tools identify target.\n\n## Context Reuse\n\nBefore rereading path/topic, search exact path/topic first. If response gives ctxc_..., reuse with file_summary({ ref }) or file_summary({ ref, query }). Use enrich: true on tools that support it after first pass.\n\n## Patterns\n\n- New area: search -> scope_map -> file_summary -> graph/trace -> stash.\n- Bug: search -> symbol -> trace -> file_summary -> test/check -> remember.\n- Refactor shared code: blast_radius -> checkpoint -> file_summary -> rename/codemod -> check -> test_run.\n- Web/API: web_search/web_fetch/http; browser only when JS/auth interaction needed. Browser snapshots now use ~200-400 tokens, making them practical for quick page state checks.\n\n## Memory Discipline\n\nStore only high-signal facts:\n- Decisions and rationale.\n- Conventions that constrain future work.\n- Non-obvious root causes and fixes.\n- Checkpoints and blockers.\n\nReview decayed/stale entries periodically with knowledge({ action: 'flagged' }). Use lesson actions for reusable engineering lessons; load lesson-learned after implementation/review work.\n\n## Flow + FORGE\n\nFlows guide multi-step work. Read active step before acting. FORGE handles tiering/evidence/gates; load references only when main skill is too thin.\n\n### Layered Knowledge Protocol\n- **Workspace Context** → Workspace skill + fresh onboard context: load via `status({ includePrelude: true })`. Requires `onboard()` first — if `onboard_context` is null, run `onboard`; if `onboard_context.freshness.status` is `stale` or `unknown`, run `onboard({ path, update: true })`. Consume the workspace skill preview/resource pointer and fresh onboard package map/architecture/read-order before `search`, `scope_map`, `digest`, or repeated `file_summary`. Use `file_summary({ tier: 'T1' })` for structure, or `file_summary({ tier: 'T2', query })` for content only after status/onboard context narrows the workset. Token-bounded.\n- **L1** → Flow working context. Withdraw before dispatch; reuse before broad retrieval.\n- **L2** → Canonical curated knowledge. Retrieve on demand; never preload broadly.\n- **L3** → Evidence/auto-knowledge. Inspect only for provenance, conflict, or promotion assessment.\n\nReference docs:\n- references/coordination.md - queue, lanes, stash, checkpoints, signaling.\n- references/forge-protocol.md - tiering, evidence, gates.\n- references/search-patterns.md - search, trace, graph, compression recipes.\n- references/layered-knowledge-protocol.md - workspace context + L1-L3 operating policy and hot path.\n\n## Self-Dogfooding\n\nWhen developing AI Kit itself: regenerate scaffold output, run focused checks, rebuild, then reindex so future searches see new shape.\n"},{file:`references/coordination.md`,content:`# Coordination
+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
+
+Use AI Kit as compression, memory, validation, and coordination layer. Each call should reduce uncertainty or token load.
+
+## Communicating With the User
+
+**Use \`present({ schemaVersion: 1, title, blocks })\` for ALL non-trivial output.** This is the preferred way to show summaries, results, evidence maps, task plans, reviews, comparisons, dashboards, charts, timelines, and batch results to the user. Plain text is only for 1-2 sentence status updates or simple questions. The \`present\` tool renders rich, structured output that the user can interact with.
+
+## Session Loop
+
+Start:
+1. status({ includePrelude: true }).
+2. If \`onboarded\` is false or \`prelude.onboardContext\` / \`structuredContent.onboard_context\` is null → run \`onboard({ path, mode: 'generate' })\`, then \`status({ includePrelude: true })\` again.
+3. If \`onboard_context.freshness.status\` is \`stale\` or \`unknown\`, or \`nextAction.kind === "update_onboard"\` → run \`onboard({ path, update: true })\`, then \`status({ includePrelude: true })\` again.
+4. **Workspace context start**: Extract workspace skill + fresh onboard context from status: \`workspace_skill.uri\`, \`prelude.workspaceSkillResource\`, \`onboard_context.freshness\`, \`onboard_context.packageMap\`, \`onboard_context.architecture\`, and \`onboard_context.recommendedReadOrder\`. Read \`aikit://skill/SKILL.md\` when full repo-specific guidance is needed. Use fresh onboard context before broad retrieval. ≤ 2,100 tokens.
+5. search({ query: "SESSION CHECKPOINT", origin: "curated" }).
+6. flow({ action: 'status' }) when active flow may exist — use L1 snapshot before broad retrieval.
+7. scope_map({ task }) only when workspace context + checkpoint do not identify a narrow workset.
+
+During:
+- Prefer search/file_summary/digest/symbol/trace/graph over raw reads.
+- Use stash for temporary findings; knowledge for durable decisions.
+- Run blast_radius before shared/public edits.
+- Validate with check + relevant test_run.
+
+End:
+- reindex after structural changes.
+- produce_knowledge for durable project updates.
+- session_digest({ persist: true }).
+- knowledge remember session checkpoint with done/decisions/next/blockers.
+
+## Retrieval Ladder — Layered (Workspace Context + L1-L3)
+
+> This table maps knowledge layers to tool needs. For the canonical quick-reference tool decision table, see \`aiKitToolPreference()\` in protocols.mjs.
+
+| Layer | Need | Tool |
+|-------|------|------|
+| **Workspace Context** | Workspace skill + fresh onboard context | \`status({ includePrelude: true })\`; read \`aikit://skill/SKILL.md\` only when full guidance is needed. Run \`onboard({ path, mode: 'generate' })\` if \`onboard_context\` is missing; run \`onboard({ path, update: true })\` if \`onboard_context.freshness.status\` is \`stale\` or \`unknown\`. Consume fresh context before broad scans. |
+| **Workspace Context** | Architecture overview | \`status({ includePrelude: true }).onboard_context.architecture\`, then onboard \`diagram.md\` / \`domains.md\` when deeper detail is needed |
+| **Workspace Context** | Package map / repo shape | \`status({ includePrelude: true }).onboard_context.packageMap\`, then onboard \`structure.md\` / \`dependencies.md\` |
+| **Flow Context** | Flow-specific context | L1 flow snapshot via \`knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })\` |
+| **L1** | Active flow state | \`knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })\` |
+| **L2** | Prior decisions/conventions | \`search\` / \`knowledge\` |
+| **L2** | File structure | \`file_summary({ files, tier: 'T1' })\` |
+| **L2** | Exact relevant section | \`file_summary({ files, tier: 'T2' })\` |
+| **L2** | Many files | \`digest\` |
+| **L2** | Symbol defs/refs | \`symbol\` |
+| **L2** | Call/data flow | \`trace\` |
+| **L2** | Module/import relationships | \`graph\` |
+| **L2** | Impact | \`blast_radius\` |
+| **L2** | Type/lint/test | \`check\` / \`test_run\` |
+| **L3** | Evidence, provenance, conflict review | \`search\` with \`knowledge({ action: 'lesson' })\` — focused only |
+| **General** | Tool choice unknown | \`list_tools({ intent: "<task>" })\` (use intent param for planner-ranked results) or \`search({ query: "tool to <do X>" })\` |
+
+Raw read_file only for exact edit lines after compressed tools identify target.
+
+## Context Reuse
+
+Before rereading path/topic, search exact path/topic first. If response gives ctxc_..., reuse with file_summary({ ref }) or file_summary({ ref, query }). Use enrich: true on tools that support it after first pass.
+
+## Patterns
+
+- New area: search -> scope_map -> file_summary -> graph/trace -> stash.
+- Bug: search -> symbol -> trace -> file_summary -> test/check -> remember.
+- Refactor shared code: blast_radius -> checkpoint -> file_summary -> rename/codemod -> check -> test_run.
+- Web/API: web_search/web_fetch/http; browser only when JS/auth interaction needed. Browser snapshots now use ~200-400 tokens, making them practical for quick page state checks.
+
+## Memory Discipline
+
+Store only high-signal facts:
+- Decisions and rationale.
+- Conventions that constrain future work.
+- Non-obvious root causes and fixes.
+- Checkpoints and blockers.
+
+Review decayed/stale entries periodically with knowledge({ action: 'flagged' }). Use lesson actions for reusable engineering lessons; load lesson-learned after implementation/review work.
+
+### Contribute Durable Knowledge
+
+The workspace skill auto-improves from curated knowledge. After meaningful work, persist durable facts:
+- User preferences or collaboration style → \`knowledge({ action: "remember", category: "context", tags: ["user-preference", "collaboration"] })\`
+- Repo conventions or constraints → \`knowledge({ action: "remember", category: "conventions", tags: ["repo-rule", "constraint"] })\`
+- Architecture invariants → \`knowledge({ action: "remember", category: "context", tags: ["architecture-memory", "invariant"] })\`
+- Recurring pitfalls or prevention rules → \`knowledge({ action: "lesson", subAction: "create", context: "...", insight: "...", evidence: "..." })\` with tag \`pitfall\` or \`prevention\`
+- Tool-use or retrieval patterns → \`knowledge({ action: "remember", category: "patterns", tags: ["tool-use", "retrieval"] })\`
+- Stable engineering lessons → \`knowledge({ action: "lesson", ... })\` with confidence >= 60
+
+The skill regenerates when promoted knowledge changes. Without curation, the skill stays at structural-only.
+
+## Flow + FORGE
+
+Flows guide multi-step work. Read active step before acting. FORGE handles tiering/evidence/gates; load references only when main skill is too thin.
+
+### Layered Knowledge Protocol
+- **Workspace Context** → Workspace skill + fresh onboard context: load via \`status({ includePrelude: true })\`. Requires \`onboard()\` first — if \`onboard_context\` is null, run \`onboard\`; if \`onboard_context.freshness.status\` is \`stale\` or \`unknown\`, run \`onboard({ path, update: true })\`. Consume the workspace skill preview/resource pointer and fresh onboard package map/architecture/read-order before \`search\`, \`scope_map\`, \`digest\`, or repeated \`file_summary\`. Use \`file_summary({ tier: 'T1' })\` for structure, or \`file_summary({ tier: 'T2', query })\` for content only after status/onboard context narrows the workset. Token-bounded.
+- **L1** → Flow working context. Withdraw before dispatch; reuse before broad retrieval.
+- **L2** → Canonical curated knowledge. Retrieve on demand; never preload broadly.
+- **L3** → Evidence/auto-knowledge. Inspect only for provenance, conflict, or promotion assessment.
+
+Reference docs:
+- references/coordination.md - queue, lanes, stash, checkpoints, signaling.
+- references/forge-protocol.md - tiering, evidence, gates.
+- references/search-patterns.md - search, trace, graph, compression recipes.
+- references/layered-knowledge-protocol.md - workspace context + L1-L3 operating policy and hot path.
+
+## Self-Dogfooding
+
+When developing AI Kit itself: regenerate scaffold output, run focused checks, rebuild, then reindex so future searches see new shape.
+`},{file:`references/coordination.md`,content:`# Coordination
 
 Use coordination tools when work is parallel, long-running, or easy to repeat incorrectly.
 

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

@@ -77,4 +77,15 @@ Every subagent dispatch MUST include:
 
 STOP → ASSESS (\`git diff --stat\` + \`check({})\`) → CONTAIN (1-3 files: fix, widespread: stash) → RECOVER (stash first) → DOCUMENT (remember what went wrong).
 
-Max 2 retries per task. Same failure twice → stop loop, change plan.`}];export{e as default};
+Max 2 retries per task. Same failure twice → stop loop, change plan.
+
+## Contribute Durable Knowledge
+
+After meaningful work, persist facts that make the workspace skill self-improving:
+- **User preferences** → \`knowledge({ action: "remember", category: "context", tags: ["user-preference"] })\`
+- **Repo conventions** → \`knowledge({ action: "remember", category: "conventions", tags: ["repo-rule"] })\`
+- **Architecture invariants** → \`knowledge({ action: "remember", category: "context", tags: ["architecture-memory"] })\`
+- **Pitfalls/prevention** → \`knowledge({ action: "lesson", ..., tags: ["pitfall"] })\`
+- **Tool-use/retrieval patterns** → \`knowledge({ action: "remember", category: "patterns", tags: ["tool-use"] })\`
+
+The workspace skill regenerates from curated knowledge. Without deliberate curation, the skill stays at structural-only (package name + build commands). The promotion engine observes tool use and can auto-promote conventions, but manual curation produces the highest-quality skill sections.`}];export{e as default};