@vpxa/kb 0.1.26 → 0.1.28

package/scaffold/general/agents/_shared/architect-reviewer-base.md

@@ -3,13 +3,22 @@
 > Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
 
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` — especially `structure.md`, `dependencies.md`, and `diagram.md` for architecture context
+
+---
+
 ## Review Workflow
 
-1. **KB Recall** — Search for architecture decisions, boundary conventions
+1. **KB Recall** — `search("architecture decisions boundaries")` + `list()` for past ADRs, patterns
 2. **Analyze** — `analyze_structure`, `analyze_dependencies`, `blast_radius`
 3. **Evaluate** — Check all dimensions below
 4. **Report** — Structured findings with verdict
-5. **Persist** — `remember` findings
+5. **Persist** — `remember({ title: "Architecture: <finding>", content: "<details>", category: "decisions" })` for any structural findings, boundary violations, or design insights
 
 ## Review Dimensions
 

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -6,7 +6,7 @@
 ## Invocation Mode Detection
 
 You may be invoked in two modes:
-1. **Direct** — you have full KB tool access. Execute KB Recall normally.
+1. **Direct** — you have full KB 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 KB Context" in your prompt.
    If present, skip KB Recall and use the provided context instead.
@@ -15,6 +15,67 @@ You may be invoked in two modes:
 
 ---
 
+## MANDATORY FIRST ACTION — Knowledge Base Initialization
+
+**Before ANY other work**, check the knowledge base:
+
+1. Run `status({})` — check **Onboard Status** and note the **Onboard Directory** path
+2. If onboard shows ❌:
+   - Run `onboard({ path: "." })` — `path` is the codebase root to analyze
+   - Artifacts are written to the **Onboard Directory** automatically (the server resolves the correct location for workspace or user-level mode — you don't need to specify `out_dir`)
+   - Wait for completion (~30s) — the result shows the output directory path
+   - Do NOT proceed with any other work until onboard finishes
+3. If onboard shows ✅:
+   - Proceed to **Information Lookup Order** below
+
+**This is non-negotiable.** Without onboarding, you waste 10-50x tokens on blind exploration.
+
+---
+
+## Information Lookup Order (MANDATORY)
+
+Always follow this order when you need to understand something. **Never skip to step 3 without checking steps 1-2 first.**
+
+> **How to read artifacts:** Use `compact({ path: "<dir>/<file>" })` where `<dir>` is the **Onboard Directory** from `status({})`.
+> `compact()` reads a file and extracts relevant content — **5-20x fewer tokens** than `read_file`.
+
+### Step 1: Onboard Artifacts (pre-analyzed, fastest)
+
+| Need to understand... | Read this artifact |
+|---|---|
+| Project overview, tech stack | `synthesis-guide.md` |
+| File tree, module purposes | `structure.md` |
+| Import graph, dependencies | `dependencies.md` |
+| Exported functions, classes | `symbols.md` |
+| Function signatures, JSDoc, decorators | `api-surface.md` |
+| Interface/type/enum definitions | `type-inventory.md` |
+| Architecture patterns, conventions | `patterns.md` |
+| CLI bins, route handlers, main exports | `entry-points.md` |
+| C4 architecture diagram | `diagram.md` |
+| Module graph with key symbols | `code-map.md` |
+
+### Step 2: Curated Knowledge (past decisions, remembered patterns)
+
+```
+search("your keywords")    // searches curated + indexed content
+scope_map("what you need") // generates a reading plan
+list()                     // see all stored knowledge entries
+```
+
+### Step 3: Real-time Exploration (only if steps 1-2 don't cover it)
+
+| Tool | Use for |
+|---|---|
+| `find({ pattern })` | Locate files by name/glob |
+| `symbol({ name })` | Find symbol definition + references |
+| `trace({ symbol, direction })` | Follow call graph forward/backward |
+| `compact({ path, query })` | Read specific section of a file |
+| `read_file` | **Only** when you need exact lines for editing |
+
+### Step 4: Tool Discovery
+
+If unsure which KB tool to use → run `guide({ topic: "what you need" })` for recommendations.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -26,28 +87,88 @@ You may be invoked in two modes:
 
 ---
 
-## KB Recall (BLOCKING — Before ANY Code Change)
+## Loop Detection & Breaking
+
+Track repeated failures. If the same approach fails, **stop and change strategy**.
+
+| Signal | Action |
+|--------|--------|
+| Same error appears **3 times** after attempted fixes | **STOP** — do not attempt a 4th fix with the same approach |
+| Same test fails with identical output after code change | Step back — re-read the error, check assumptions, try a fundamentally different approach |
+| Fix→test→same error cycle | The fix is wrong. Re-diagnose from scratch — `trace` the actual execution path |
+| `read_file`→edit→same state | File may not be saved, wrong file, or edit didn't match. Verify with `check` |
+
+**Escalation ladder:**
+1. **Strike 1-2** — Retry with adjustments, verify assumptions
+2. **Strike 3** — Stop current approach entirely. Re-read error output. Try alternative strategy
+3. **Still stuck** — Return `ESCALATE` status in handoff. Include: what was tried, what failed, your hypothesis for why
+
+**Never brute-force.** If you catch yourself making the same type of edit repeatedly, you are in a loop.
+
+---
+
+## Hallucination Self-Check
 
-1. **Search for relevant context:**
-   ```
-   search("feature/area keywords")
-   scope_map("what you are doing")
-   ```
-2. **Check for existing patterns** — reuse established conventions
-3. **Read design decisions** that constrain your implementation
-4. **If KB has no hits**, proceed but **remember your findings at the end**
+**Verify before asserting.** Never claim something exists or works without evidence.
 
-**Proceed only after KB search is complete.**
+| Before you... | First verify with... |
+|---------------|---------------------|
+| Reference a file path | `find({ pattern })` or `file_summary({ path })` — confirm it exists |
+| Call a function/method | `symbol({ name })` — confirm its signature and location |
+| Claim a dependency is available | `search({ query: "package-name" })` or check `package.json` / imports |
+| Assert a fix works | `check({})` + `test_run({})` — run actual validation |
+| Describe existing behavior | `compact({ path, query })` — read the actual code, don't assume |
+
+**Red flags you may be hallucinating:**
+- You "remember" a file path but haven't verified it this session
+- You assume an API signature without checking the source
+- You claim tests pass without running them
+- You reference a config option that "should exist"
+
+**Rule: If you haven't verified it with a tool in this session, treat it as unverified.**
+
+---
+
+## Scope Guard
+
+Before making changes, establish expected scope. Flag deviations early.
+
+- **Before starting**: Note how many files you expect to modify (from the task/plan)
+- **During work**: If you're about to modify **2x more files** than expected, **STOP and reassess**
+  - Is the scope creeping? Should this be split into separate tasks?
+  - Is the approach wrong? A simpler approach might touch fewer files
+- **Before large refactors**: Confirm scope with user or Orchestrator before proceeding
+- **Git safety**: For risky multi-file changes, recommend `git stash` or working branch first
 
 ---
 
-## KB Learn (After Completing Work)
+## MANDATORY: Memory Persistence Before Completing
+
+**Before finishing ANY task**, you MUST call `remember()` if ANY of these apply:
+
+- ✅ You discovered how something works that wasn't in onboard artifacts
+- ✅ You made an architecture or design decision
+- ✅ You found a non-obvious solution, workaround, or debugging technique
+- ✅ You identified a pattern, convention, or project-specific gotcha
+- ✅ You encountered and resolved an error that others might hit
+
+**How to remember:**
+```
+remember({
+  title: "Short descriptive title",
+  content: "Detailed finding with context",
+  category: "patterns" | "conventions" | "decisions" | "troubleshooting"
+})
+```
+
+**Examples:**
+- `remember({ title: "Auth uses JWT refresh tokens with 15min expiry", content: "Access tokens expire in 15 min, refresh in 7 days. Middleware at src/auth/guard.ts validates.", category: "patterns" })`
+- `remember({ title: "Build requires Node 20+", content: "Uses Web Crypto API — Node 18 fails silently on crypto.subtle calls.", category: "conventions" })`
+- `remember({ title: "Decision: LanceDB over Chroma for vector store", content: "LanceDB is embedded (no Docker), supports WASM, better for user-level MCP.", category: "decisions" })`
 
-Before returning your handoff, persist discoveries to KB:
-- Architecture insights → `remember({ title, content, category: "patterns" })`
-- Non-obvious solutions → `remember({ title, content, category: "troubleshooting" })`
-- Key decisions made → `remember({ title, content, category: "decisions" })`
-- Outdated KB entries → `update(path, content, reason)`
+**If you complete a task without remembering anything, you likely missed something.** Review what you learned.
+
+For outdated KB entries → `update(path, content, reason)`
 
 ---
 
@@ -58,6 +179,49 @@ Minimize token usage by choosing the right compression tool:
 - **`digest({ sources })`** — Compress 3+ files into a single token-budgeted summary
 - **`stratum_card({ path })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
+**Session phases** — structure your work to minimize context bloat:
+
+| Phase | What to do | Compress after? |
+|-------|-----------|----------------|
+| **Understand** | Search KB, read summaries, trace symbols | Yes — `digest` findings before planning |
+| **Plan** | Design approach, identify files to change | Yes — `stash` the plan, compact analysis |
+| **Execute** | Make changes, one sub-task at a time | Yes — compact between independent sub-tasks |
+| **Verify** | `check` + `test_run` + `blast_radius` | — |
+
+**Rules:**
+- **Never compact mid-operation** — finish the current sub-task first
+- **Recycle context to files** — save analysis results via `stash` or `remember`, not just in conversation
+- **Decompose monolithic work** — break into independent chunks, pass results via artifact files between sub-tasks
+- **One-shot sub-tasks** — for self-contained changes, provide all context upfront to avoid back-and-forth
+
+---
+
+## Quality Verification
+
+For non-trivial tasks, **think before you implement**.
+
+**Think-first protocol:**
+1. Read existing code patterns in the area you're changing
+2. Design your approach (outline, pseudo-code, or mental model) before writing code
+3. Check: does your design match existing conventions? Use `search` for patterns
+4. Implement
+5. Verify: `check` + `test_run`
+
+**Quality dimensions** — verify each before returning handoff:
+
+| Dimension | Check |
+|-----------|-------|
+| **Correctness** | Does it do what was asked? Tests pass? |
+| **Standards** | Follows project conventions? Lint-clean? |
+| **Architecture** | Fits existing patterns? No unnecessary coupling? |
+| **Robustness** | Handles edge cases? No obvious failure modes? |
+| **Maintainability** | Clear naming? Minimal complexity? Would another developer understand it? |
+
+**Explicit DON'Ts:**
+- Don't implement the first idea without considering alternatives for complex tasks
+- Don't skip verification — "it should work" is not evidence
+- Don't add features, refactor, or "improve" code beyond what was asked
+
 ---
 
 ## User Interaction Rules

package/scaffold/general/agents/_shared/code-reviewer-base.md

@@ -3,15 +3,24 @@
 > Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
 
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` — especially `patterns.md` and `api-surface.md` for review context
+
+---
+
 ## Review Workflow
 
-1. **KB Recall** — Search for relevant conventions, past review findings
+1. **KB Recall** — `search("conventions relevant-area")` + `list()` for past review findings, patterns
 2. **Blast Radius** — `blast_radius` on changed files to understand impact
 3. **FORGE Classify** — `forge_classify` to determine review depth
 4. **Review** — Evaluate against all dimensions below
 5. **Validate** — Run `check` (typecheck + lint) and `test_run`
 6. **Report** — Structured findings with verdict
-7. **Persist** — `remember` any new patterns or issues
+7. **Persist** — `remember({ title: "Review: <finding>", content: "<details>", category: "patterns" })` for any new patterns, anti-patterns, or recurring issues found
 
 ## Review Dimensions
 

package/scaffold/general/agents/_shared/researcher-base.md

@@ -3,6 +3,17 @@
 > Shared methodology for all Researcher variants. Each variant's definition contains only its unique identity and model assignment. **Do not duplicate.**
 
 
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` before exploring
+
+**Start with pre-analyzed artifacts.** They cover 80%+ of common research needs.
+
+---
+
 ## Research Methodology
 
 ### Phase 1: KB Recall (BLOCKING)
@@ -31,8 +42,23 @@ Return structured findings. Always include:
 5. **Trade-offs** — Pros and cons of alternatives
 6. **Risks** — What could go wrong
 
-### Phase 5: Persist
-`remember` key findings for future recall.
+### Phase 5: MANDATORY — Persist Discoveries
+
+**Before returning your report**, you MUST call `remember()` for:
+- ✅ Architecture insights not already in onboard artifacts
+- ✅ Non-obvious findings, gotchas, or edge cases
+- ✅ Trade-off analysis and recommendations made
+- ✅ External knowledge gathered from web_search/web_fetch
+
+```
+remember({
+  title: "Short descriptive title",
+  content: "Detailed finding with context",
+  category: "patterns" | "conventions" | "decisions" | "troubleshooting"
+})
+```
+
+**If you complete research without remembering anything, you wasted tokens.** Your research should enrich the knowledge base for future sessions.
 
 ---
 
@@ -61,7 +87,7 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Invocation Mode Detection
 
-- **Direct** (has KB tools) → Execute KB Recall normally
+- **Direct** (has KB tools) → Follow the **Information Lookup Order** from code-agent-base
 - **Sub-agent** (prompt has "## Prior KB Context") → Skip KB Recall, use provided context
 
 ---