knowzcode 0.3.1 → 0.3.6

package/knowzcode/platform_adapters.md

@@ -54,10 +54,33 @@ Specialized agents handle each phase when using Agent Teams or subagent executio
 - `/kc:learn "insight"` — Capture learning to vault
 - `/kc:status` — Check MCP connection and vault status
 
-## MCP Integration (Optional)
+## MCP Integration
 If configured, agents use `search_knowledge`, `ask_question`, and `create_knowledge` for enhanced context.
 All commands work without MCP — it enhances but never blocks.
 
+### Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds, convention changes —
+**must** be captured. Knowledge lives in two places:
+
+- **MCP vaults** (when connected): `knowzcode/knowzcode_vaults.md` defines vault IDs, routing rules,
+  and write conditions. Always pass `vaultId` when calling `create_knowledge` — omitting it saves
+  to the tenant default vault, NOT the project vault.
+- **Local files** (always available): specs, workgroup files, log entries, architecture docs, and
+  `knowzcode/pending_captures.md` (scribe fallback queue when MCP is unavailable).
+
+If MCP is not connected, knowledge still gets captured locally. Never let insights die in the conversation.
+
+**Vault content detail**: Vault entries are retrieved via semantic search, not read directly like local files. Write detailed, self-contained entries with full reasoning, specific technology names, code examples, and file paths. Terse entries produce poor search results. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+### Knowz-Scribe Delegation
+When knowz-scribe is active (Agent Teams mode), it owns all vault writes — do NOT call `create_knowledge` directly. Send knowledge to the scribe instead:
+
+- **Phase captures**: Handled automatically at quality gates via task-tracked DMs
+- **Explicit**: `"Log: {description}"` — scribe MUST write it; it decides routing (which vault or local file)
+- **Soft**: `"Consider: {description}"` — scribe evaluates whether to capture and where; may skip if not insight-worthy or duplicative
+
+Any agent can send ad-hoc knowledge to the scribe at any time. The scribe handles routing, dedup, and formatting. If MCP is unavailable, the scribe queues captures to `knowzcode/pending_captures.md` for later sync. When no scribe is active, use `/kc:learn "insight"` for automatic routing.
+
 ## WorkGroup Files
 - Created in `knowzcode/workgroups/` (gitignored)
 - Every todo must start with `KnowzCode:` prefix
@@ -130,6 +153,13 @@ Read `knowzcode/knowzcode_loop.md` before starting any feature work.
 - Every WorkGroup todo must start with `KnowzCode:` prefix
 - Target <20 specs per project — consolidate when domains overlap
 
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 ## Quick Fix (Micro-Fix)
 For single-file, <50 line, no-ripple-effect changes:
 1. Implement the fix
@@ -242,6 +272,13 @@ Read these files before starting any feature work (use @import syntax for direct
 - Log completions in `knowzcode/knowzcode_log.md`
 - Target <20 specs — consolidate when domains overlap >50%
 
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 ## Micro-Fix (for small changes)
 Single file, <50 lines, no ripple effects:
 1. Implement fix → 2. Run tests → 3. Log MicroFix → 4. Commit with `fix:`
@@ -309,6 +346,13 @@ Before any feature work, read:
 - Target <20 specs per project
 - Read `knowzcode/knowzcode_tracker.md` for active work
 - Log completions in `knowzcode/knowzcode_log.md`
+
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 ```
 
 ---
@@ -397,11 +441,18 @@ Follow Red-Green-Refactor for every feature/criterion in the spec.
 - `knowzcode/specs/` — Component specifications
 - `knowzcode/workgroups/` — Active session data (gitignored)
 
-## MCP Integration (Optional)
+## MCP Integration
 
 If configured in `.vscode/mcp.json`, use `search_knowledge` and `ask_question` tools
 for enhanced context from knowledge vaults. All prompts work without MCP.
 
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 ## Copilot Coding Agent
 
 When the Copilot Coding Agent works on GitHub issues for this repository:
@@ -872,22 +923,22 @@ Optionally generated by `/kc:init` when Copilot is detected and MCP is configure
 ```json
 {
   "servers": {
-    "knowzcode": {
+    "knowz": {
       "type": "http",
-      "url": "${input:knowzcode_mcp_url}",
+      "url": "${input:knowz_mcp_url}",
       "headers": {
-        "x-api-key": "${input:knowzcode_api_key}"
+        "x-api-key": "${input:knowz_api_key}"
       }
     }
   },
   "inputs": [
     {
-      "id": "knowzcode_mcp_url",
+      "id": "knowz_mcp_url",
       "description": "KnowzCode MCP server URL",
       "type": "promptString"
     },
     {
-      "id": "knowzcode_api_key",
+      "id": "knowz_api_key",
       "description": "KnowzCode API key",
       "type": "promptString",
       "password": true
@@ -973,6 +1024,13 @@ Follow `knowzcode/knowzcode_loop.md` for all feature development.
 - Target <20 specs per project
 - Every WorkGroup todo starts with `KnowzCode:` prefix
 
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 ## Micro-Fix (for small changes)
 Single file, <50 lines, no ripple effects:
 Implement → Test → Log MicroFix → Commit with `fix:` prefix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowzcode",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
   "type": "module",
   "bin": {

package/skills/alias-resolver.json

@@ -1,6 +1,6 @@
 {
   "name": "alias-resolver",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Resolves friendly natural-language aliases to KnowzCode canonical values (phase, audit, plan, workgroup_type).",
   "parameters": [
     {"name": "domain", "type": "string", "required": true},

package/skills/architecture-diff.json

@@ -1,6 +1,6 @@
 {
   "name": "architecture-diff",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Highlights differences between specs and the Mermaid flowchart in knowzcode_architecture.md.",
   "parameters": [],
   "actions": [

package/skills/check-installation-status.json

@@ -1,6 +1,6 @@
 {
   "name": "check-installation-status",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Checks if KnowzCode is initialized in the current project and reports current status",
 
   "parameters": [],

package/skills/environment-guard.json

@@ -1,6 +1,6 @@
 {
   "name": "environment-guard",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Verifies that knowzcode/environment_context.md no longer contains placeholder brackets.",
   "parameters": [],
   "actions": [

package/skills/generate-workgroup-id.json

@@ -1,6 +1,6 @@
 {
   "name": "generate-workgroup-id",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Generates a WorkGroupID following the KnowzCode convention [type]-[slug]-YYYYMMDD-HHMMSS. The slug is a 2-4 word descriptor extracted from the goal.",
   "parameters": [
     {

package/skills/install-knowzcode.json

@@ -1,6 +1,6 @@
 {
   "name": "install-knowzcode",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Initializes KnowzCode directory structure and required files in the current project",
 
   "parameters": [

package/skills/load-core-context.json

@@ -1,6 +1,6 @@
 {
   "name": "load-core-context",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Loads the KnowzCode project overview, architecture, tracker, log header, and automation manifest for downstream steps.",
   "parameters": [],
   "actions": [

package/skills/log-entry-builder.json

@@ -1,6 +1,6 @@
 {
   "name": "log-entry-builder",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Appends structured entries to knowzcode/knowzcode_log.md with KnowzCode formatting.",
   "parameters": [
     {"name": "entry_type", "type": "string", "required": true},

package/skills/spec-quality-check.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-quality-check",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Validates KnowzCode spec files for mandatory sections. Supports new 4-section format and legacy numbered format.",
   "parameters": [
     {"name": "node_id", "type": "string", "required": true}

package/skills/spec-template.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-template",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Seeds or repairs KnowzCode spec files with the lean 4-section template.",
   "parameters": [
     {"name": "node_id", "type": "string", "required": true},

package/skills/spec-validator.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-validator",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Validates NodeID specification completeness and quality. Supports new 4-section format (preferred) and legacy numbered sections (deprecated).",
   "parameters": [
     {

package/skills/tracker-scan.json

@@ -1,6 +1,6 @@
 {
   "name": "tracker-scan",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Extracts NodeID statuses and WorkGroup assignments from the KnowzCode tracker.",
   "parameters": [],
   "actions": [

package/skills/tracker-update.json

@@ -1,6 +1,6 @@
 {
   "name": "tracker-update",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Applies validated updates to knowzcode/knowzcode_tracker.md while preserving table structure.",
   "parameters": [
     {

package/skills/validate-installation.json

@@ -1,6 +1,6 @@
 {
   "name": "validate-installation",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "description": "Validates that KnowzCode installation completed successfully with required directories and files",
 
   "parameters": [],