@vpxa/aikit 0.1.156 → 0.1.157

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.156",
+  "version": "0.1.157",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/scaffold/dist/definitions/bodies.mjs

@@ -7,6 +7,8 @@ const e=()=>"**`AGENTS.md` is already in your context** — do NOT re-read it. J
 3. Read \`aikit\` skill, check \`AGENTS.md\` (decision protocol and FORGE protocol are inlined below)
 4. Read \`multi-agents-development\` skill — **REQUIRED before any delegation**
 
+> **HARD RULE (Orchestrator):** When gathering context yourself (not via subagent), follow AI Kit Tool Discipline — use \`search\`/\`file_summary\`/\`compact\`/\`digest\`, NOT \`read_file\`/\`grep_search\`. Use \`check({})\`/\`test_run({})\`, NOT \`run_in_terminal\` for tsc/lint/test.
+
 ## Agent Arsenal
 
 ${e}
@@ -378,6 +380,8 @@ The Planner is typically activated by the Orchestrator as part of a flow step (e
 | \`repo-access\` | When the plan involves accessing private, enterprise, or self-hosted repositories |
 | \`browser-use\` | When the plan involves browser-based auth recovery, web scraping, or interacting with web applications that require login |`,Implementer:`${e()}
 
+> **HARD RULE:** NEVER use \`read_file\` to understand code. Use \`file_summary\`/\`compact\`/\`digest\`. \`read_file\` is ONLY for exact edit lines. NEVER use \`run_in_terminal\` for tsc/lint/test — use \`check({})\`/\`test_run({})\`.
+
 ## Implementation Protocol
 
 1. **Understand scope** — Read the phase objective, identify target files
@@ -431,6 +435,8 @@ Every implementation response MUST end with a structured status block:
 - Description of blocker
 \`\`\``,Frontend:`${e()}
 
+> **HARD RULE:** NEVER use \`read_file\` to understand code. Use \`file_summary\`/\`compact\`/\`digest\`. \`read_file\` is ONLY for exact edit lines. NEVER use \`run_in_terminal\` for tsc/lint/test — use \`check({})\`/\`test_run({})\`.
+
 ## Frontend Protocol
 
 0. **Check for DESIGN.md** — Look for \`DESIGN.md\` in the workspace root or \`docs/\` directory. If found, read it first — it defines the project's design system, tokens, colors, typography, spacing, and component conventions. Follow it as the authoritative design reference.
@@ -478,6 +484,8 @@ Every implementation response MUST end with a structured status block:
 If the pre-flight dev server cannot be started (e.g. sandbox), fall back to
 \`compact\` inspection of the component source + describe expected visual behavior.`,Debugger:`${e()}
 
+> **HARD RULE:** NEVER use \`read_file\` to understand code. Use \`file_summary\`/\`compact\`/\`digest\`. \`read_file\` is ONLY for exact edit lines. NEVER use \`run_in_terminal\` for tsc/lint/test — use \`check({})\`/\`test_run({})\`.
+
 ## Debugging Protocol
 
 ### Phase 1: Build the Right Feedback Loop
@@ -553,6 +561,8 @@ When debugging tool invocation issues, use the replay audit trail with traceId:
    - Server middleware context (\`ctx.requestId\`)
 4. Filter by traceId: search replay.jsonl for the specific UUID to trace the full invocation lifecycle`,Refactor:`${e()}
 
+> **HARD RULE:** NEVER use \`read_file\` to understand code. Use \`file_summary\`/\`compact\`/\`digest\`. \`read_file\` is ONLY for exact edit lines. NEVER use \`run_in_terminal\` for tsc/lint/test — use \`check({})\`/\`test_run({})\`.
+
 ## Refactoring Protocol
 
 1. **AI Kit Recall** — Search for established patterns and conventions

package/scaffold/dist/definitions/protocols.mjs

@@ -27,13 +27,13 @@ ${e===`<PROFILE>`?`**Profile:** Check your role → implementer | documenter | r
 You may be invoked in two modes:
 1. **Direct** — you have full AI Kit tool access. Follow the **Information Lookup Order** below.
 2. **Sub-agent** (via Orchestrator) — you may have limited MCP tool access.
-   The Orchestrator provides context under "## Prior AI Kit Context" in your prompt.
+  The Orchestrator provides context under "## Prior AI Kit Context" or "### Current Code Context" in your prompt.
    If present, skip AI Kit Recall and use the provided context instead.
   **Visual Output:** When running as a sub-agent, do NOT use the \`present\` tool (output won't reach the user).
   Instead, include structured data (tables, findings, metrics) as formatted text in your final response.
   The Orchestrator will re-present relevant content to the user.
 
-**Detection:** If your prompt contains "## Prior AI Kit Context", you are in sub-agent mode.
+**Detection:** If your prompt contains "## Prior AI Kit Context" OR "### Current Code Context" OR was dispatched via \`runSubagent\`, you are in sub-agent mode. When in sub-agent mode, use provided context — do NOT re-read files already given in your prompt.
 
 ---
 
@@ -54,6 +54,61 @@ You may be invoked in two modes:
 
 ---
 
+## AI Kit Tool Discipline
+
+Use AI Kit retrieval and compression tools first. Prefer reusable compressed context over raw reads, and only drop to native tools when precision for an edit or tool fallback requires it.
+
+| NEVER use this | USE THIS instead | Why |
+|---|---|---|
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports — 10x fewer tokens |
+| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — 5-20x reduction |
+| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
+| \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
+| \`grep_search\` for a symbol name | \`symbol({ name })\` | Definition + references with scope and call context |
+| \`run_in_terminal\` for tsc/lint | \`check({})\` | Typecheck + lint combined, summary output |
+| \`run_in_terminal\` for test | \`test_run({})\` | Run tests with structured output |
+| Editing without reading | \`file_summary\` then targeted \`read_file\` | Prevents wrong-position edits |
+
+**\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
+
+For edits, first understand structure with \`file_summary\` or \`compact\`, then use targeted \`read_file\` only for the exact region.
+Never patch from search snippets or assumptions alone.
+
+## compact() Failure Recovery
+
+If \`compact()\` returns <200 bytes or empty content, the file is NOT indexed. Follow this fallback:
+
+1. **Do NOT retry** compact on the same file — it will fail again
+2. **Use \`read_file\`** with a LARGE range (e.g., \`startLine: 1, endLine: 9999\`) — NEVER chunk into small ranges
+3. **Use \`stash()\`** to cache findings from unindexed files — context pressure causes re-reads
+4. **Check \`status()\`** to see which paths are indexed before calling compact
+
+**Anti-patterns to avoid:**
+- Retrying compact 3x on same unindexed file (wastes 3 tool calls)
+- Falling back to read_file in small chunks (10-50 lines) — each chunk costs ~3K prompt tokens in overhead
+- Re-reading the same file later because you forgot the content — use stash() to cache
+
+*Why:* these tools reduce token cost, shrink duplicate reads, and lower the odds of wrong-file or wrong-position edits while preserving reusable context.
+
+---
+
+## Context Caching (MANDATORY for multi-step tasks)
+
+After your first \`file_summary\` or \`compact\` call on a file, cache the result:
+\`\`\`
+stash({ action: 'set', key: 'ctx:<filename>', value: '<summary result>' })
+\`\`\`
+
+Before reading the same file again, check the cache:
+\`\`\`
+stash({ action: 'get', key: 'ctx:<filename>' })
+\`\`\`
+
+If cached → use it. If not → call \`file_summary\`/\`compact\` and cache.
+**NEVER \`read_file\` the same file twice** without checking stash first.
+
+---
+
 
 ## Domain Skills
 
@@ -262,44 +317,6 @@ For outdated AI Kit entries → \`knowledge({ action: "update", path, content, r
 
 ---
 
-## AI Kit Tool Discipline
-
-Use AI Kit retrieval and compression tools first. Prefer reusable compressed context over raw reads, and only drop to native tools when precision for an edit or tool fallback requires it.
-
-| NEVER use this | USE THIS instead | Why |
-|---|---|---|
-| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports — 10x fewer tokens |
-| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — 5-20x reduction |
-| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
-| \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
-| \`grep_search\` for a symbol name | \`symbol({ name })\` | Definition + references with scope and call context |
-| \`run_in_terminal\` for tsc/lint | \`check({})\` | Typecheck + lint combined, summary output |
-| \`run_in_terminal\` for test | \`test_run({})\` | Run tests with structured output |
-| Editing without reading | \`file_summary\` then targeted \`read_file\` | Prevents wrong-position edits |
-
-**\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
-
-For edits, first understand structure with \`file_summary\` or \`compact\`, then use targeted \`read_file\` only for the exact region.
-Never patch from search snippets or assumptions alone.
-
-## compact() Failure Recovery
-
-If \`compact()\` returns <200 bytes or empty content, the file is NOT indexed. Follow this fallback:
-
-1. **Do NOT retry** compact on the same file — it will fail again
-2. **Use \`read_file\`** with a LARGE range (e.g., \`startLine: 1, endLine: 9999\`) — NEVER chunk into small ranges
-3. **Use \`stash()\`** to cache findings from unindexed files — context pressure causes re-reads
-4. **Check \`status()\`** to see which paths are indexed before calling compact
-
-**Anti-patterns to avoid:**
-- Retrying compact 3x on same unindexed file (wastes 3 tool calls)
-- Falling back to read_file in small chunks (10-50 lines) — each chunk costs ~3K prompt tokens in overhead
-- Re-reading the same file later because you forgot the content — use stash() to cache
-
-*Why:* these tools reduce token cost, shrink duplicate reads, and lower the odds of wrong-file or wrong-position edits while preserving reusable context.
-
----
-
 ## Guidelines
 
 Behavioral guidelines to reduce common LLM coding mistakes. Apply when writing, reviewing, or refactoring code.