@vpxa/kb 0.1.12 → 0.1.15

package/packages/cli/dist/commands/init/templates.js

@@ -0,0 +1,302 @@
+function e(e,t){let n=e=>e;return`# ${e} — Copilot Instructions
+
+This project uses **@vpxa/kb** as an MCP knowledge base server. The KB provides search, context compression, persistent memory, and validation tools that **MUST** be used to maintain quality and performance.
+
+## Mandatory Rules
+
+### 1. ALWAYS search before acting
+Before writing or modifying code, you MUST recall prior decisions and understand the affected area:
+\`\`\`
+${n(`search`)}({ query: "<task keywords>" })
+${n(`scope_map`)}({ task: "<what you are doing>" })
+\`\`\`
+
+### 2. ALWAYS compress context before reading large files
+Do NOT read entire files into context. Use these tools to reduce tokens and focus on what matters:
+
+| Situation | Tool | Why |
+|-----------|------|-----|
+| Need relevant sections of a large file | \`${n(`compact`)}\` | Extracts only semantically relevant chunks — 5-20x reduction |
+| Need to summarize multiple sources | \`${n(`digest`)}\` | Compresses multiple text blocks into a token-budgeted summary |
+| Need a quick structural overview of a file | \`${n(`file_summary`)}\` | Returns exports, imports, functions without reading the full file |
+| Need a reusable context card | \`${n(`stratum_card`)}\` | Generates T1/T2 cards — 10-100x token reduction |
+
+**Example — reading a 400-line file:**
+\`\`\`
+# BAD: read_file entire file (wastes ~3000 tokens)
+# GOOD: get structure first, then compact only what you need
+${n(`file_summary`)}({ path: "src/http-client.ts" })
+${n(`compact`)}({ path: "src/http-client.ts", query: "retry logic" })
+\`\`\`
+
+### 3. ALWAYS use persistent memory
+- **Start of session**: Read prior knowledge with \`${n(`list`)}()\` and \`${n(`search`)}({ query: "SESSION CHECKPOINT", origin: "curated" })\`
+- **During session**: Use \`${n(`stash`)}\` for temporary working data, \`${n(`checkpoint`)}\` to save progress
+- **End of session**: MUST call \`${n(`remember`)}\` to persist decisions, patterns, and lessons learned
+- **Before proposing a new approach**: MUST \`${n(`search`)}\` to check if a decision already exists
+
+| Tool | When | Persistence |
+|------|------|-------------|
+| \`${n(`stash`)}\` | Temporary data within a session (intermediate results, scratch notes) | Session only |
+| \`${n(`checkpoint`)}\` | Save/restore session progress (resumable work) | Session only |
+| \`${n(`remember`)}\` | Architecture decisions, conventions, patterns, troubleshooting | Permanent (survives reindex) |
+
+### 4. ALWAYS validate before committing
+\`\`\`
+${n(`check`)}({})                    # Typecheck + lint (returns summary by default)
+${n(`test_run`)}({})                 # Run tests
+${n(`blast_radius`)}({ changed_files: ["..."] })  # Impact analysis
+${n(`audit`)}({})                    # Unified project audit with score and recommendations
+\`\`\`
+
+### 5. Use FORGE for complex tasks
+For tasks involving multiple files or architectural decisions:
+\`\`\`
+${n(`forge_classify`)}({ task: "<description>" })   # Classify complexity tier
+${n(`forge_ground`)}({ task: "<description>" })     # Full analysis: scope + constraints + evidence
+${n(`evidence_map`)}({ claims: [...] })             # Track verified vs assumed claims
+\`\`\`
+
+## Quick Workflow
+
+\`\`\`
+# 1. Orient
+${n(`search`)}({ query: "task keywords" })
+${n(`scope_map`)}({ task: "what you are doing" })
+
+# 2. Read efficiently (NEVER raw-read large files)
+${n(`file_summary`)}({ path: "relevant-file.ts" })
+${n(`compact`)}({ path: "relevant-file.ts", query: "specific concern" })
+
+# 3. Do the work
+
+# 4. Validate
+${n(`check`)}({})
+${n(`test_run`)}({})
+
+# 5. Persist
+${n(`remember`)}({ title: "What I learned", content: "...", category: "decisions" })
+\`\`\`
+
+## Context Budget Rules
+
+- **Prefer \`${n(`file_summary`)}\` over \`read_file\`** for understanding file structure
+- **Prefer \`${n(`compact`)}\` over full file reads** when you need specific sections (use \`path\` param to avoid read_file round-trip)
+- **Prefer \`${n(`search`)}\` over \`grep_search\`** for semantic/conceptual queries
+- **Prefer \`${n(`symbol`)}\` over manual grep** for finding definitions and references
+- **Use \`${n(`digest`)}\`** when combining information from 3+ sources
+- **Use \`${n(`stratum_card`)}\`** to create reusable compressed context for repeated reference
+`}function t(e,t){let n=e=>e;return`# ${e} — Agent Instructions
+
+## KB Knowledge Base
+
+This project has a **@vpxa/kb** MCP server providing search, analysis, memory, and developer tools.
+
+### Skills Reference
+
+| Context | Skill | Details |
+|---------|-------|--------|
+| KB search, analysis, memory | \`kb\` | See [.github/skills/knowledge-base/SKILL.md](.github/skills/knowledge-base/SKILL.md) or run \`${n(`status`)}({})\` |
+| Brainstorming & design | \`brainstorming\` | See [.github/skills/brainstorming/SKILL.md](.github/skills/brainstorming/SKILL.md) |
+
+### Available Tool Categories
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| Search & Discovery | \`${n(`search`)}\`, \`${n(`find`)}\`, \`${n(`symbol`)}\`, \`${n(`trace`)}\`, \`${n(`scope_map`)}\`, \`${n(`lookup`)}\`, \`${n(`dead_symbols`)}\`, \`${n(`file_summary`)}\` | Find code, symbols, data flow, reading plans |
+| Code Analysis | \`${n(`analyze_structure`)}\`, \`${n(`analyze_dependencies`)}\`, \`${n(`analyze_symbols`)}\`, \`${n(`analyze_patterns`)}\`, \`${n(`analyze_entry_points`)}\`, \`${n(`analyze_diagram`)}\`, \`${n(`blast_radius`)}\` | Structure, deps, patterns, impact, diagrams |
+| Knowledge | \`${n(`remember`)}\`, \`${n(`read`)}\`, \`${n(`update`)}\`, \`${n(`forget`)}\`, \`${n(`list`)}\`, \`${n(`produce_knowledge`)}\` | Persistent cross-session memory |
+| Execution | \`${n(`check`)}\`, \`${n(`test_run`)}\`, \`${n(`eval`)}\`, \`${n(`batch`)}\`, \`${n(`audit`)}\` | Typecheck, lint, test, run code, unified audit. \`check\` defaults to summary output (~300 tokens) |
+| Code Manipulation | \`${n(`rename`)}\`, \`${n(`codemod`)}\`, \`${n(`diff_parse`)}\`, \`${n(`data_transform`)}\` | Safe renames, transforms, diff parsing |
+| Context | \`${n(`compact`)}\`, \`${n(`workset`)}\`, \`${n(`stash`)}\`, \`${n(`checkpoint`)}\`, \`${n(`parse_output`)}\` | Manage working sets, save progress. \`compact\` accepts \`path\` for server-side file read |
+| FORGE | \`${n(`forge_ground`)}\`, \`${n(`forge_classify`)}\`, \`${n(`evidence_map`)}\`, \`${n(`digest`)}\`, \`${n(`stratum_card`)}\` | Quality gates, context compression |
+| Web & API | \`${n(`web_fetch`)}\`, \`${n(`web_search`)}\`, \`${n(`http`)}\` | Fetch pages, search web, test APIs |
+| Lanes | \`${n(`lane`)}\` | Isolated file copies for parallel exploration (create/list/status/diff/merge/discard) |
+| Git & Environment | \`${n(`git_context`)}\`, \`${n(`process`)}\`, \`${n(`watch`)}\`, \`${n(`delegate`)}\` | Git info, process management |
+| Utilities | \`${n(`regex_test`)}\`, \`${n(`encode`)}\`, \`${n(`measure`)}\`, \`${n(`changelog`)}\`, \`${n(`schema_validate`)}\`, \`${n(`snippet`)}\`, \`${n(`env`)}\`, \`${n(`time`)}\` | Regex, encoding, metrics, validation |
+| System | \`${n(`status`)}\`, \`${n(`reindex`)}\`, \`${n(`health`)}\`, \`${n(`guide`)}\`, \`${n(`onboard`)}\`, \`${n(`graph`)}\`, \`${n(`queue`)}\`, \`${n(`replay`)}\` | Index management, health checks, tool discovery, knowledge graph |
+
+---
+
+## MANDATORY: Context Reduction Protocol
+
+**Every agent interaction MUST minimize context window usage.** Raw file reads waste tokens and degrade LLM output quality. Use these tools instead:
+
+### Decision Tree — How to Read Code
+
+\`\`\`
+Need to understand a file?
+├─ Just structure? → ${n(`file_summary`)} (exports, imports, functions — ~50 tokens)
+├─ Specific section? → ${n(`compact`)}({ path: "file.ts", query: "topic" }) — 5-20x reduction
+├─ Multiple files? → ${n(`digest`)} (multi-source compression — token-budgeted)
+├─ Repeated reference? → ${n(`stratum_card`)} (T1/T2 card — 10-100x reduction)
+└─ Full file needed? → ONLY as last resort, and compact it after reading
+\`\`\`
+
+### Rules
+1. **NEVER read a file >100 lines without compressing it first**
+2. **ALWAYS use \`${n(`file_summary`)}\` before \`read_file\`** — often the summary is sufficient
+3. **ALWAYS use \`${n(`compact`)}\` when you only need specific sections** of a file (use \`path\` param to read server-side)
+4. **Use \`${n(`digest`)}\` when synthesizing from 3+ sources** — don't accumulate raw text
+5. **Use \`${n(`stratum_card`)}\` for files you'll reference repeatedly** in a session
+
+---
+
+## MANDATORY: Memory Protocol
+
+**Every session MUST read and write persistent memory.** Without this, every conversation starts from zero.
+
+### Session Start (MUST do ALL of these)
+\`\`\`
+${n(`status`)}({})                                              # Verify KB is ready
+${n(`list`)}()                                                  # See what knowledge exists
+${n(`search`)}({ query: "SESSION CHECKPOINT", origin: "curated" })  # Resume prior work
+\`\`\`
+
+### During Session
+| Situation | Action |
+|-----------|--------|
+| Found a useful intermediate result | \`${n(`stash`)}({ key: "name", value: "data" })\` |
+| Completed a milestone | \`${n(`checkpoint`)}({ action: "save", name: "milestone" })\` |
+| Made an architecture decision | \`${n(`remember`)}({ title: "...", category: "decisions" })\` |
+| Discovered a pattern or convention | \`${n(`remember`)}({ title: "...", category: "patterns" })\` |
+| Found a non-obvious solution | \`${n(`remember`)}({ title: "...", category: "troubleshooting" })\` |
+| About to propose a new approach | \`${n(`search`)}({ query: "..." })\` — check if decided before |
+
+### Session End (MUST do this)
+\`\`\`
+${n(`remember`)}({
+  title: "Session checkpoint: <topic>",
+  content: "<what was done, decisions made, blockers, next steps>",
+  category: "conventions"
+})
+\`\`\`
+
+### Memory Decision Tree
+\`\`\`
+Is this data temporary (scratch, intermediate)?
+├─ Yes → ${n(`stash`)} (session-scoped key-value)
+└─ No → Is it resumable progress?
+   ├─ Yes → ${n(`checkpoint`)} (session-scoped snapshot)
+   └─ No → ${n(`remember`)} (permanent, survives reindex)
+       Categories: decisions | patterns | conventions | troubleshooting
+\`\`\`
+
+---
+
+## MANDATORY: Search-Before-Act Protocol
+
+**NEVER write or modify code without first searching for context.**
+
+\`\`\`
+# Before ANY code change:
+${n(`search`)}({ query: "<what you're about to change>" })     # Prior decisions?
+${n(`scope_map`)}({ task: "<description>" })                    # What files to read?
+${n(`symbol`)}({ name: "<key symbol>" })                        # Where is it defined/used?
+\`\`\`
+
+If \`${n(`search`)}\` returns a prior decision about the topic, you MUST follow it or explicitly explain why you're deviating.
+
+---
+
+## MANDATORY: Validation Protocol
+
+**NEVER commit or present code without validation.**
+
+\`\`\`
+${n(`check`)}({})                                    # Typecheck + lint (tsc + biome)
+${n(`test_run`)}({})                                 # Run tests
+${n(`blast_radius`)}({ changed_files: ["..."] })     # Impact analysis
+${n(`audit`)}({})                                    # Unified project audit (structure, deps, patterns, health, dead symbols, entry points)
+\`\`\`
+
+---
+
+## FORGE Protocol (for complex tasks)
+
+For tasks touching 3+ files or involving architectural decisions:
+
+\`\`\`
+${n(`forge_classify`)}({ task: "<description>" })        # Quick: Floor/Standard/Critical tier
+${n(`forge_ground`)}({ task: "<description>" })           # Full: scope + constraints + evidence
+${n(`evidence_map`)}({ claims: ["claim1", "claim2"] })   # Track verified vs assumed
+\`\`\`
+
+---
+
+## Search Modes
+
+| Mode | When | Example |
+|------|------|---------|
+| \`hybrid\` (default) | General queries | \`${n(`search`)}({ query: "error handling" })\` |
+| \`semantic\` | Conceptual/meaning-based | \`${n(`search`)}({ query: "retry with backoff", search_mode: "semantic" })\` |
+| \`keyword\` | Exact identifiers | \`${n(`search`)}({ query: "CircuitBreaker", search_mode: "keyword" })\` |
+
+Filters: \`origin\` (\`indexed\`/\`curated\`/\`produced\`), \`category\`, \`content_type\`, \`tags\`, \`min_score\`.
+
+---
+
+## Workflow Chains
+
+**Codebase onboarding:**
+\`\`\`
+${n(`onboard`)}({ path: "." }) → ${n(`produce_knowledge`)}({ path: "src/" }) → ${n(`remember`)}(...)
+\`\`\`
+
+**Planning a task:**
+\`\`\`
+${n(`search`)}({ query: "task keywords" })
+→ ${n(`scope_map`)}({ task: "description" })
+→ ${n(`file_summary`)} for each file in scope
+→ ${n(`compact`)}({ path: "relevant-file.ts", query: "detail needed" }) for files needing detail
+→ ${n(`workset`)}({ action: "save", name: "task", files: [...] })
+\`\`\`
+
+**Bug investigation:**
+\`\`\`
+${n(`parse_output`)}({ output: "<error>" })
+→ ${n(`symbol`)}({ name: "failingFn" })
+→ ${n(`trace`)}({ symbol: "failingFn", direction: "backward" })
+→ ${n(`blast_radius`)}({ changed_files: ["suspect.ts"] })
+\`\`\`
+
+**Safe refactor with lanes:**
+\`\`\`
+${n(`lane`)}({ action: "create", name: "refactor", files: [...] })
+→ [make changes]
+→ ${n(`lane`)}({ action: "diff", name: "refactor" })
+→ ${n(`check`)}({}) → ${n(`test_run`)}({})
+→ ${n(`lane`)}({ action: "merge", name: "refactor" })
+\`\`\`
+
+**After making changes:**
+\`\`\`
+${n(`blast_radius`)}({ changed_files: ["src/file.ts"] })
+→ ${n(`check`)}({}) → ${n(`test_run`)}({})
+→ ${n(`reindex`)}({})
+→ ${n(`remember`)}(...)
+\`\`\`
+
+---
+
+## Knowledge Categories
+
+| Category | What to store |
+|----------|---------------|
+| \`decisions\` | Architecture choices, trade-offs, rejected alternatives |
+| \`patterns\` | Code patterns, naming conventions, structural patterns |
+| \`conventions\` | Session checkpoints, workflow conventions, team agreements |
+| \`troubleshooting\` | Non-obvious fixes, debugging strategies, workarounds |
+
+---
+
+## Core Rules Summary
+
+1. **Search KB before proposing anything new** — prior decisions exist
+2. **Compress context aggressively** — \`file_summary\` → \`compact\` → \`digest\`
+3. **Use persistent memory** — \`remember\` decisions, \`stash\` temporary data
+4. **Validate before committing** — \`check\` + \`test_run\` + \`blast_radius\`
+5. **Follow \`_Next:\` hints** in tool responses for guided workflow
+6. **Use FORGE for complex tasks** — \`forge_classify\` → \`forge_ground\` → \`evidence_map\`
+`}export{t as buildAgentsMd,e as buildCopilotInstructions};
+//# sourceMappingURL=templates.js.map

package/packages/cli/dist/commands/init.d.ts

@@ -1,9 +1,15 @@
+//#region packages/cli/src/commands/init.d.ts
 /**
  * `kb init` — scaffold a knowledge base in the current directory.
  * Creates kb.config.json, .gitignore entry, optional IDE config,
- * and agent instruction files (.github/copilot-instructions.md, AGENTS.md).
+ * agent instruction files (.github/copilot-instructions.md, AGENTS.md),
+ * and .github/skills/ (knowledge-base, brainstorming).
  */
-export declare function initProject(options: {
-    force: boolean;
+declare function initProject(options: {
+  force: boolean;
 }): Promise<void>;
+/** Generate a JSON guide report comparing installed vs source files. */
+declare function guideProject(): Promise<void>;
+//#endregion
+export { guideProject, initProject };
 //# sourceMappingURL=init.d.ts.map