knowzcode 0.3.3 → 0.3.7

package/knowzcode/knowzcode_loop.md

@@ -327,6 +327,8 @@ All phases work without MCP. MCP enhances analysis depth and organizational lear
 
 ## 7. Learning Capture (Optional)
 
+> **Vault content must be detailed and self-contained.** Vault entries are retrieved via semantic search — not read directly like local files. Include full reasoning, specific technology names, code examples, and file paths. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 During finalization, scan the WorkGroup for insight-worthy patterns:
 
 | Signal Type | Examples |
@@ -336,6 +338,9 @@ During finalization, scan the WorkGroup for insight-worthy patterns:
 | Workaround | "workaround", "limitation", "can't do X so" |
 | Performance | "optimized", "reduced from X to Y", "cache" |
 | Security | "vulnerability", "sanitize", "authentication fix" |
+| Convention | "established convention", "team standard", "naming pattern", "agreed to always" |
+| Integration | "API integration", "upstream API changed", "service dependency", "webhook" |
+| Scope | "included because", "excluded because", "out of scope", "deferred to" |
 
 ### Auto-Capture Triggers
 
@@ -351,13 +356,21 @@ At each quality gate, send a message to the knowz-scribe with the phase identifi
 
 The knowz-scribe reads the WorkGroup file, extracts relevant data, checks for duplicates, and writes to the appropriate vault. No other agent should call `create_knowledge` when the scribe is active.
 
+**Ad-hoc captures (any agent, any time):**
+
+Any agent can send knowledge to the knowz-scribe outside phase boundaries:
+- `"Log: {description}"` — explicit capture, scribe must write it (decides vault routing)
+- `"Consider: {description}"` — soft capture, scribe evaluates whether to log and where
+
+The scribe handles routing, dedup, and formatting for both modes. If MCP is unavailable, captures are queued to `knowzcode/pending_captures.md` for later sync.
+
 **Single-agent / no scribe (direct MCP writes):**
 
 If MCP is available but no knowz-scribe, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
 
-- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {goal}", content="[NodeIDs] {list}\n[Risk] {assessment}", tags=["scope"])`
-- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles
-- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}%", content="[Findings] {gaps}\n[Security] {issues}", tags=["audit"])`
+- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {descriptive goal summary}", content="[CONTEXT] {problem description, what prompted this work, constraints}\n[INSIGHT] {scope decisions — what's included/excluded and why}\n[RATIONALE] {risk assessment with full reasoning, affected files, mitigation}\n[TAGS] scope, {domain}", tags=["scope", "{domain}"])`
+- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles — include specific file paths, code examples, and the problem each pattern solves
+- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}% — {key finding summary}", content="[CONTEXT] {what was audited, scope of the review}\n[INSIGHT] {specific gaps with file paths and line references, security findings with severity reasoning}\n[RATIONALE] {gap resolution decisions — what was deferred vs fixed and why}\n[TAGS] audit, {domain}", tags=["audit", "{domain}"])`
 - After Phase 2B (enterprise): If enterprise vault configured and compliance enabled, push audit results to enterprise vault
 - After Phase 3: Capture architectural learnings and consolidation decisions (handled by closer agent)
 

package/knowzcode/knowzcode_vaults.md

@@ -124,16 +124,39 @@ On confirmation, each vault is created via the MCP `create_vault(name, descripti
 
 Each vault type defines when it accepts writes (Write Conditions) and how content should be formatted (Content Filter).
 
+### Content Detail Principle
+
+Vault entries live in a vector search index — they are chunked and retrieved via semantic search. Unlike local files (specs, workgroups, logs) which are read directly and benefit from being scannable, vault entries must be **self-contained, detailed, and keyword-rich** because they are discovered by meaning, not by file path.
+
+**Include in every vault entry:**
+- Full reasoning and context — why, not just what
+- Specific technology names, library versions, framework details
+- Code examples, file paths, error messages where relevant
+- Consequences and alternatives considered
+
+**Anti-pattern** (poor search recall, useless when retrieved):
+
+> `"[NodeIDs] AuthMiddleware\n[Risk] Medium"`
+
+**Good pattern** (rich search matches, self-contained on retrieval):
+
+> `[CONTEXT] During JWT authentication implementation for the Express API, the jsonwebtoken library's verify() method silently accepts expired tokens when clockTolerance is set above 0.`
+> `[INSIGHT] Always set clockTolerance to 0 (default) and handle TokenExpiredError explicitly. Some tutorials suggest 30s tolerance which creates a security window where revoked tokens remain valid.`
+> `[RATIONALE] A 30-second tolerance means stolen tokens stay usable after revocation. Our auth middleware in src/middleware/auth.ts now checks expiry with zero tolerance.`
+> `[TAGS] security, jwt, express, authentication`
+
+Write vault content as if the reader has no project context — they will find this entry via a search query months from now.
+
 ### code
 
 **Write Conditions**: Learning category is Pattern, Workaround, or Performance.
 
 **Content Filter**:
 ```
-[CONTEXT] {where the pattern/workaround was encountered}
-[PATTERN] {what was built or discovered}
-[EXAMPLE] {code snippet or usage example}
-[TAGS] {learning category, domain, language}
+[CONTEXT] {Where and why the pattern was encountered — include the component, framework, and problem being solved. Provide enough background for someone with no project familiarity.}
+[PATTERN] {What was built or discovered — describe the approach, the key insight, and how it differs from the obvious/naive solution.}
+[EXAMPLE] {Code snippet, usage example, or file path reference — concrete enough to be directly useful when retrieved.}
+[TAGS] {learning category, domain, language, framework — include specific technology names for search discoverability}
 ```
 
 ### ecosystem
@@ -142,10 +165,10 @@ Each vault type defines when it accepts writes (Write Conditions) and how conten
 
 **Content Filter**:
 ```
-[CONTEXT] {what prompted the decision or convention}
-[INSIGHT] {the decision, convention, security finding, or integration detail}
-[RATIONALE] {why this approach was chosen}
-[TAGS] {learning category, domain}
+[CONTEXT] {What prompted the decision — the problem, the alternatives considered, and the constraints. Include component names and file paths where relevant.}
+[INSIGHT] {The decision, convention, security finding, or integration detail — state it clearly and completely so it stands alone without context.}
+[RATIONALE] {Why this approach was chosen over alternatives — include trade-offs, risks of the rejected options, and any conditions that might change this decision.}
+[TAGS] {learning category, domain, specific technology names — be generous with tags for search discoverability}
 ```
 
 ### finalizations
@@ -154,11 +177,12 @@ Each vault type defines when it accepts writes (Write Conditions) and how conten
 
 **Content Filter**:
 ```
-[GOAL] {original goal from WorkGroup}
-[OUTCOME] {success | partial | abandoned}
-[NODES] {NodeIDs changed}
-[DURATION] {phases completed, e.g. "1A-3"}
-[TAGS] {finalization, domain, outcome}
+[GOAL] {Original goal from WorkGroup — restate fully, not just the WorkGroup slug}
+[OUTCOME] {success | partial | abandoned — include what was delivered and what was deferred}
+[NODES] {NodeIDs changed — list each with a one-line summary of what it covers}
+[DURATION] {Phases completed (e.g. "1A-3"), total iterations, any notable delays or blockers}
+[SUMMARY] {Key learnings from this WorkGroup — architectural discoveries, patterns established, gotchas encountered. This is the most valuable field for future search queries.}
+[TAGS] {finalization, domain, outcome, key technology names}
 ```
 
 ---

package/knowzcode/platform_adapters.md

@@ -58,17 +58,28 @@ Specialized agents handle each phase when using Agent Teams or subagent executio
 If configured, agents use `search_knowledge`, `ask_question`, and `create_knowledge` for enhanced context.
 All commands work without MCP — it enhances but never blocks.
 
-### Vault Targeting (MANDATORY when MCP is connected)
-**When calling `create_knowledge` or `update_knowledge`, ALWAYS pass `vaultId`.**
-Omitting `vaultId` saves to the tenant default vault (often Personal) — NOT the project vault.
+### 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:
 
-Before any MCP write:
-1. Check if vault IDs are already in context from a previous read or CLAUDE.md
-2. If not, read `knowzcode/knowzcode_vaults.md` for vault IDs and routing rules
-3. Match your content type to the correct vault using the routing table
-4. Pass `vaultId` explicitly in every call
+- **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).
 
-For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
+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)
@@ -142,9 +153,12 @@ 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
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## 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:
@@ -258,9 +272,12 @@ 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%
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## 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:
@@ -330,9 +347,12 @@ Before any feature work, read:
 - Read `knowzcode/knowzcode_tracker.md` for active work
 - Log completions in `knowzcode/knowzcode_log.md`
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## 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.
 ```
 
 ---
@@ -426,9 +446,12 @@ Follow Red-Green-Refactor for every feature/criterion in the spec.
 If configured in `.vscode/mcp.json`, use `search_knowledge` and `ask_question` tools
 for enhanced context from knowledge vaults. All prompts work without MCP.
 
-### Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## 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
 
@@ -900,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
@@ -1001,9 +1024,12 @@ Follow `knowzcode/knowzcode_loop.md` for all feature development.
 - Target <20 specs per project
 - Every WorkGroup todo starts with `KnowzCode:` prefix
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## 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:

package/package.json

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

package/skills/alias-resolver.json

@@ -1,15 +1,15 @@
-{
-  "name": "alias-resolver",
-  "version": "0.3.3",
-  "description": "Resolves friendly natural-language aliases to KnowzCode canonical values (phase, audit, plan, workgroup_type).",
-  "parameters": [
-    {"name": "domain", "type": "string", "required": true},
-    {"name": "text", "type": "string", "required": false}
-  ],
-  "actions": [
-    {
-      "type": "python",
-      "code": "domain = (inputs.get('domain') or '').strip().lower()\ntext = (inputs.get('text') or '').strip().lower()\nresult = {'value': None}\nphase_map = {\n    '1a': {'agent': 'analyst', 'prompt': 'knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md'},\n    '1b': {'agent': 'architect', 'prompt': 'knowzcode/prompts/[LOOP_1B]__Draft_Specs.md'},\n    '2a': {'agent': 'builder', 'prompt': 'knowzcode/prompts/[LOOP_2A]__Implement_Change_Set.md'},\n    '2b': {'agent': 'reviewer', 'prompt': 'knowzcode/prompts/[LOOP_2B]__Verify_Implementation.md'},\n    '3': {'agent': 'closer', 'prompt': 'knowzcode/prompts/[LOOP_3]__Finalize_And_Commit.md'}\n}\nphase_synonyms = {\n    '1a': ['1a','loop 1a','analyze','analysis','impact','scope','change set','proposal'],\n    '1b': ['1b','loop 1b','spec','specs','draft','design','blueprint'],\n    '2a': ['2a','loop 2a','implement','implementation','build','code','develop'],\n    '2b': ['2b','loop 2b','verify','verification','audit','test','qa','review'],\n    '3': ['3','loop 3','final','finalize','finalization','commit','wrap up','close']\n}\naudit_map = {\n    'spec': 'knowzcode/prompts/Spec_Verification_Checkpoint.md',\n    'implementation': 'knowzcode/prompts/[LOOP_2B]__Verify_Implementation.md',\n    'architecture': None,\n    'security': None,\n    'integration': None\n}\naudit_synonyms = {\n    'spec': ['spec','specs','specification','checkpoint'],\n    'implementation': ['implementation','code','verify implementation','loop 2b'],\n    'architecture': ['architecture','arch','diagram','flowchart','structure'],\n    'security': ['security','sec','owasp','vulnerability'],\n    'integration': ['integration','holistic','system','end to end','e2e']\n}\nworkgroup_map = {'feat': 'feat','feature': 'feat','fix': 'fix','bug': 'fix','bugfix': 'fix','refactor': 'refactor','cleanup': 'refactor','issue': 'issue','incident': 'issue'}\nif domain == 'phase':\n    if not text:\n        key = '1a'\n    else:\n        key = None\n        for canonical, synonyms in phase_synonyms.items():\n            if text == canonical or text in synonyms or any(s in text for s in synonyms):\n                key = canonical\n                break\n        if key is None:\n            for canonical in phase_map.keys():\n                if text.replace(' ','') == canonical:\n                    key = canonical\n                    break\n        if key is None:\n            key = '1a'\n    data = phase_map[key]\n    result['value'] = key.upper()\n    result['prompt'] = data['prompt']\n    result['agent'] = data['agent']\n    result['requires_workgroup'] = data['agent'] != 'analyst'\nelif domain == 'audit':\n    if not text:\n        key = 'spec'\n    else:\n        key = None\n        for canonical, synonyms in audit_synonyms.items():\n            if text == canonical or text in synonyms or any(s in text for s in synonyms):\n                key = canonical\n                break\n        if key is None:\n            key = 'spec'\n    result['value'] = key\n    result['prompt'] = audit_map.get(key)\n    result['agent'] = 'reviewer'\nelif domain == 'plan':\n    result['value'] = text or ''\n    result['prompt'] = None\nelif domain == 'workgroup_type':\n    if not text:\n        value = 'feat'\n    else:\n        value = None\n        for key, mapped in workgroup_map.items():\n            if text == key or key in text:\n                value = mapped\n                break\n        if value is None:\n            value = workgroup_map.get(text, 'feat')\n    result['value'] = value\nelse:\n    result['value'] = text or ''\noutputs.update(result)\n"
-    }
-  ]
-}
+{
+  "name": "alias-resolver",
+  "version": "0.3.7",
+  "description": "Resolves friendly natural-language aliases to KnowzCode canonical values (phase, audit, plan, workgroup_type).",
+  "parameters": [
+    {"name": "domain", "type": "string", "required": true},
+    {"name": "text", "type": "string", "required": false}
+  ],
+  "actions": [
+    {
+      "type": "python",
+      "code": "domain = (inputs.get('domain') or '').strip().lower()\ntext = (inputs.get('text') or '').strip().lower()\nresult = {'value': None}\nphase_map = {\n    '1a': {'agent': 'analyst', 'prompt': 'knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md'},\n    '1b': {'agent': 'architect', 'prompt': 'knowzcode/prompts/[LOOP_1B]__Draft_Specs.md'},\n    '2a': {'agent': 'builder', 'prompt': 'knowzcode/prompts/[LOOP_2A]__Implement_Change_Set.md'},\n    '2b': {'agent': 'reviewer', 'prompt': 'knowzcode/prompts/[LOOP_2B]__Verify_Implementation.md'},\n    '3': {'agent': 'closer', 'prompt': 'knowzcode/prompts/[LOOP_3]__Finalize_And_Commit.md'}\n}\nphase_synonyms = {\n    '1a': ['1a','loop 1a','analyze','analysis','impact','scope','change set','proposal'],\n    '1b': ['1b','loop 1b','spec','specs','draft','design','blueprint'],\n    '2a': ['2a','loop 2a','implement','implementation','build','code','develop'],\n    '2b': ['2b','loop 2b','verify','verification','audit','test','qa','review'],\n    '3': ['3','loop 3','final','finalize','finalization','commit','wrap up','close']\n}\naudit_map = {\n    'spec': 'knowzcode/prompts/Spec_Verification_Checkpoint.md',\n    'implementation': 'knowzcode/prompts/[LOOP_2B]__Verify_Implementation.md',\n    'architecture': None,\n    'security': None,\n    'integration': None\n}\naudit_synonyms = {\n    'spec': ['spec','specs','specification','checkpoint'],\n    'implementation': ['implementation','code','verify implementation','loop 2b'],\n    'architecture': ['architecture','arch','diagram','flowchart','structure'],\n    'security': ['security','sec','owasp','vulnerability'],\n    'integration': ['integration','holistic','system','end to end','e2e']\n}\nworkgroup_map = {'feat': 'feat','feature': 'feat','fix': 'fix','bug': 'fix','bugfix': 'fix','refactor': 'refactor','cleanup': 'refactor','issue': 'issue','incident': 'issue'}\nif domain == 'phase':\n    if not text:\n        key = '1a'\n    else:\n        key = None\n        for canonical, synonyms in phase_synonyms.items():\n            if text == canonical or text in synonyms or any(s in text for s in synonyms):\n                key = canonical\n                break\n        if key is None:\n            for canonical in phase_map.keys():\n                if text.replace(' ','') == canonical:\n                    key = canonical\n                    break\n        if key is None:\n            key = '1a'\n    data = phase_map[key]\n    result['value'] = key.upper()\n    result['prompt'] = data['prompt']\n    result['agent'] = data['agent']\n    result['requires_workgroup'] = data['agent'] != 'analyst'\nelif domain == 'audit':\n    if not text:\n        key = 'spec'\n    else:\n        key = None\n        for canonical, synonyms in audit_synonyms.items():\n            if text == canonical or text in synonyms or any(s in text for s in synonyms):\n                key = canonical\n                break\n        if key is None:\n            key = 'spec'\n    result['value'] = key\n    result['prompt'] = audit_map.get(key)\n    result['agent'] = 'reviewer'\nelif domain == 'plan':\n    result['value'] = text or ''\n    result['prompt'] = None\nelif domain == 'workgroup_type':\n    if not text:\n        value = 'feat'\n    else:\n        value = None\n        for key, mapped in workgroup_map.items():\n            if text == key or key in text:\n                value = mapped\n                break\n        if value is None:\n            value = workgroup_map.get(text, 'feat')\n    result['value'] = value\nelse:\n    result['value'] = text or ''\noutputs.update(result)\n"
+    }
+  ]
+}

package/skills/architecture-diff.json

@@ -1,12 +1,12 @@
-{
-  "name": "architecture-diff",
-  "version": "0.3.3",
-  "description": "Highlights differences between specs and the Mermaid flowchart in knowzcode_architecture.md.",
-  "parameters": [],
-  "actions": [
-    {
-      "type": "python",
-      "code": "from pathlib import Path\nimport re\narch = Path('knowzcode/knowzcode_architecture.md').read_text()\nspec_paths = list(Path('knowzcode/specs').glob('*.md'))\nnode_ids = {p.stem for p in spec_paths}\nmermaid_nodes = set(re.findall(r'([A-Z]{2,}_[A-Za-z0-9]+)', arch))\nmissing_in_arch = sorted(node_ids - mermaid_nodes)\nmissing_in_specs = sorted(mermaid_nodes - node_ids)\noutputs['missing_in_architecture'] = missing_in_arch\noutputs['missing_specs'] = missing_in_specs\n"
-    }
-  ]
-}
+{
+  "name": "architecture-diff",
+  "version": "0.3.7",
+  "description": "Highlights differences between specs and the Mermaid flowchart in knowzcode_architecture.md.",
+  "parameters": [],
+  "actions": [
+    {
+      "type": "python",
+      "code": "from pathlib import Path\nimport re\narch = Path('knowzcode/knowzcode_architecture.md').read_text()\nspec_paths = list(Path('knowzcode/specs').glob('*.md'))\nnode_ids = {p.stem for p in spec_paths}\nmermaid_nodes = set(re.findall(r'([A-Z]{2,}_[A-Za-z0-9]+)', arch))\nmissing_in_arch = sorted(node_ids - mermaid_nodes)\nmissing_in_specs = sorted(mermaid_nodes - node_ids)\noutputs['missing_in_architecture'] = missing_in_arch\noutputs['missing_specs'] = missing_in_specs\n"
+    }
+  ]
+}

package/skills/check-installation-status.json

@@ -1,14 +1,14 @@
-{
-  "name": "check-installation-status",
-  "version": "0.3.3",
-  "description": "Checks if KnowzCode is initialized in the current project and reports current status",
-
-  "parameters": [],
-
-  "actions": [
-    {
-      "type": "python",
-      "code": "from pathlib import Path\n\nknowzcode_dir = Path('knowzcode')\n\nif not knowzcode_dir.exists():\n    outputs['initialized'] = False\n    outputs['commands_count'] = 0\n    outputs['skills_count'] = 0\n    outputs['agents_count'] = 0\n    outputs['has_required_files'] = False\n    exit()\n\n# Check required files exist\nrequired_files = [\n    'knowzcode_loop.md',\n    'knowzcode_tracker.md',\n    'knowzcode_project.md',\n    'knowzcode_architecture.md'\n]\n\nmissing_files = [f for f in required_files if not (knowzcode_dir / f).exists()]\nhas_required_files = len(missing_files) == 0\n\n# Count components from various possible locations\n\n# Check .claude directory\nclaude_dir = Path('.claude')\ncommands_count = 0\nskills_count = 0\nagents_count = 0\n\nif claude_dir.exists():\n    if (claude_dir / 'commands').exists():\n        commands_count = len(list((claude_dir / 'commands').glob('*.md')))\n    if (claude_dir / 'skills').exists():\n        skills_count = len(list((claude_dir / 'skills').glob('*.json')))\n    if (claude_dir / 'agents').exists():\n        agents_count = len(list((claude_dir / 'agents').glob('*.md')))\n    if (claude_dir / 'subagents').exists():\n        agents_count += len(list((claude_dir / 'subagents').glob('*.yaml')))\n\n# Also check top-level directories (plugin installation)\nif Path('commands').exists():\n    commands_count = max(commands_count, len(list(Path('commands').glob('*.md'))))\nif Path('skills').exists():\n    skills_count = max(skills_count, len(list(Path('skills').glob('*.json'))))\nif Path('agents').exists():\n    agents_count = max(agents_count, len(list(Path('agents').glob('*.md'))))\n\noutputs['initialized'] = has_required_files\noutputs['commands_count'] = commands_count\noutputs['skills_count'] = skills_count\noutputs['agents_count'] = agents_count\noutputs['has_required_files'] = has_required_files\noutputs['missing_files'] = missing_files if missing_files else None"
-    }
-  ]
-}
+{
+  "name": "check-installation-status",
+  "version": "0.3.7",
+  "description": "Checks if KnowzCode is initialized in the current project and reports current status",
+
+  "parameters": [],
+
+  "actions": [
+    {
+      "type": "python",
+      "code": "from pathlib import Path\n\nknowzcode_dir = Path('knowzcode')\n\nif not knowzcode_dir.exists():\n    outputs['initialized'] = False\n    outputs['commands_count'] = 0\n    outputs['skills_count'] = 0\n    outputs['agents_count'] = 0\n    outputs['has_required_files'] = False\n    exit()\n\n# Check required files exist\nrequired_files = [\n    'knowzcode_loop.md',\n    'knowzcode_tracker.md',\n    'knowzcode_project.md',\n    'knowzcode_architecture.md'\n]\n\nmissing_files = [f for f in required_files if not (knowzcode_dir / f).exists()]\nhas_required_files = len(missing_files) == 0\n\n# Count components from various possible locations\n\n# Check .claude directory\nclaude_dir = Path('.claude')\ncommands_count = 0\nskills_count = 0\nagents_count = 0\n\nif claude_dir.exists():\n    if (claude_dir / 'commands').exists():\n        commands_count = len(list((claude_dir / 'commands').glob('*.md')))\n    if (claude_dir / 'skills').exists():\n        skills_count = len(list((claude_dir / 'skills').glob('*.json')))\n    if (claude_dir / 'agents').exists():\n        agents_count = len(list((claude_dir / 'agents').glob('*.md')))\n    if (claude_dir / 'subagents').exists():\n        agents_count += len(list((claude_dir / 'subagents').glob('*.yaml')))\n\n# Also check top-level directories (plugin installation)\nif Path('commands').exists():\n    commands_count = max(commands_count, len(list(Path('commands').glob('*.md'))))\nif Path('skills').exists():\n    skills_count = max(skills_count, len(list(Path('skills').glob('*.json'))))\nif Path('agents').exists():\n    agents_count = max(agents_count, len(list(Path('agents').glob('*.md'))))\n\noutputs['initialized'] = has_required_files\noutputs['commands_count'] = commands_count\noutputs['skills_count'] = skills_count\noutputs['agents_count'] = agents_count\noutputs['has_required_files'] = has_required_files\noutputs['missing_files'] = missing_files if missing_files else None"
+    }
+  ]
+}

package/skills/environment-guard.json

@@ -1,12 +1,12 @@
-{
-  "name": "environment-guard",
-  "version": "0.3.3",
-  "description": "Verifies that knowzcode/environment_context.md no longer contains placeholder brackets.",
-  "parameters": [],
-  "actions": [
-    {
-      "type": "python",
-      "code": "from pathlib import Path\ntext = Path('knowzcode/environment_context.md').read_text()\nplaceholders = [line.strip() for line in text.splitlines() if '[' in line and ']' in line]\nif placeholders:\n    raise ValueError('environment_context.md still contains placeholders: ' + ', '.join(placeholders[:5]))\n"
-    }
-  ]
-}
+{
+  "name": "environment-guard",
+  "version": "0.3.7",
+  "description": "Verifies that knowzcode/environment_context.md no longer contains placeholder brackets.",
+  "parameters": [],
+  "actions": [
+    {
+      "type": "python",
+      "code": "from pathlib import Path\ntext = Path('knowzcode/environment_context.md').read_text()\nplaceholders = [line.strip() for line in text.splitlines() if '[' in line and ']' in line]\nif placeholders:\n    raise ValueError('environment_context.md still contains placeholders: ' + ', '.join(placeholders[:5]))\n"
+    }
+  ]
+}

package/skills/generate-workgroup-id.json

@@ -1,25 +1,25 @@
-{
-  "name": "generate-workgroup-id",
-  "version": "0.3.3",
-  "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": [
-    {
-      "name": "type",
-      "type": "string",
-      "required": true,
-      "description": "One of feat, fix, refactor, issue"
-    },
-    {
-      "name": "slug",
-      "type": "string",
-      "required": false,
-      "description": "A 2-4 word kebab-case descriptor (e.g., 'auth-jwt', 'dark-mode'). If not provided, generates ID without slug."
-    }
-  ],
-  "actions": [
-    {
-      "type": "python",
-      "code": "import datetime\nimport re\nallowed = {'feat', 'fix', 'refactor', 'issue'}\nwg_type = inputs['type']\nif wg_type not in allowed:\n    raise ValueError(f'Invalid type {wg_type!r}, expected one of {sorted(allowed)}')\ntimestamp = datetime.datetime.utcnow().strftime('%Y%m%d-%H%M%S')\nslug = inputs.get('slug', '')\nif slug:\n    # Sanitize slug: lowercase, replace spaces with hyphens, remove non-alphanumeric\n    slug = re.sub(r'[^a-z0-9-]', '', slug.lower().replace(' ', '-'))\n    slug = re.sub(r'-+', '-', slug).strip('-')[:25]  # Max 25 chars\n    outputs['workgroup_id'] = f'{wg_type}-{slug}-{timestamp}'\nelse:\n    outputs['workgroup_id'] = f'{wg_type}-{timestamp}'"
-    }
-  ]
-}
+{
+  "name": "generate-workgroup-id",
+  "version": "0.3.7",
+  "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": [
+    {
+      "name": "type",
+      "type": "string",
+      "required": true,
+      "description": "One of feat, fix, refactor, issue"
+    },
+    {
+      "name": "slug",
+      "type": "string",
+      "required": false,
+      "description": "A 2-4 word kebab-case descriptor (e.g., 'auth-jwt', 'dark-mode'). If not provided, generates ID without slug."
+    }
+  ],
+  "actions": [
+    {
+      "type": "python",
+      "code": "import datetime\nimport re\nallowed = {'feat', 'fix', 'refactor', 'issue'}\nwg_type = inputs['type']\nif wg_type not in allowed:\n    raise ValueError(f'Invalid type {wg_type!r}, expected one of {sorted(allowed)}')\ntimestamp = datetime.datetime.utcnow().strftime('%Y%m%d-%H%M%S')\nslug = inputs.get('slug', '')\nif slug:\n    # Sanitize slug: lowercase, replace spaces with hyphens, remove non-alphanumeric\n    slug = re.sub(r'[^a-z0-9-]', '', slug.lower().replace(' ', '-'))\n    slug = re.sub(r'-+', '-', slug).strip('-')[:25]  # Max 25 chars\n    outputs['workgroup_id'] = f'{wg_type}-{slug}-{timestamp}'\nelse:\n    outputs['workgroup_id'] = f'{wg_type}-{timestamp}'"
+    }
+  ]
+}

package/skills/install-knowzcode.json

@@ -1,21 +1,21 @@
-{
-  "name": "install-knowzcode",
-  "version": "0.3.3",
-  "description": "Initializes KnowzCode directory structure and required files in the current project",
-
-  "parameters": [
-    {
-      "name": "force",
-      "type": "boolean",
-      "required": false,
-      "description": "Force reinstall even if knowzcode/ exists"
-    }
-  ],
-
-  "actions": [
-    {
-      "type": "python",
-      "code": "import os\nimport json\nfrom pathlib import Path\nfrom datetime import datetime\n\n# Configuration\ntarget_dir = Path('knowzcode')\nforce = inputs.get('force', False)\n\n# Check if target exists\nif target_dir.exists() and not force:\n    outputs['success'] = False\n    outputs['error'] = 'knowzcode/ already exists. Use force=true to reinitialize'\n    outputs['already_installed'] = True\n    exit()\n\n# Create directory structure\ntarget_dir.mkdir(exist_ok=True)\n(target_dir / 'specs').mkdir(exist_ok=True)\n(target_dir / 'workgroups').mkdir(exist_ok=True)\n(target_dir / 'prompts').mkdir(exist_ok=True)\n(target_dir / 'planning').mkdir(exist_ok=True)\n\n# Create .gitignore if it doesn't exist\ngitignore_path = target_dir / '.gitignore'\nif not gitignore_path.exists():\n    gitignore_content = '''# KnowzCode gitignore - protects environment-specific files\n\n# Environment-specific (contains local paths, commands)\nenvironment_context.md\n\n# Session-specific work (can be regenerated)\nworkgroups/\n\n# Personal notes and scratch files\n*.local.md\n.scratch/\n'''\n    with open(gitignore_path, 'w') as f:\n        f.write(gitignore_content)\n\n# Note: The actual template files (knowzcode_loop.md, etc.) should be copied\n# from the plugin template directory or created by the /kc:init command.\n# This skill creates the structure; the command copies the content.\n\noutputs['success'] = True\noutputs['target_dir'] = str(target_dir)\noutputs['directories_created'] = ['specs', 'workgroups', 'prompts', 'planning']\noutputs['gitignore_created'] = not gitignore_path.exists()\noutputs['message'] = f'KnowzCode directory structure created at {target_dir}/'"
-    }
-  ]
-}
+{
+  "name": "install-knowzcode",
+  "version": "0.3.7",
+  "description": "Initializes KnowzCode directory structure and required files in the current project",
+
+  "parameters": [
+    {
+      "name": "force",
+      "type": "boolean",
+      "required": false,
+      "description": "Force reinstall even if knowzcode/ exists"
+    }
+  ],
+
+  "actions": [
+    {
+      "type": "python",
+      "code": "import os\nimport json\nfrom pathlib import Path\nfrom datetime import datetime\n\n# Configuration\ntarget_dir = Path('knowzcode')\nforce = inputs.get('force', False)\n\n# Check if target exists\nif target_dir.exists() and not force:\n    outputs['success'] = False\n    outputs['error'] = 'knowzcode/ already exists. Use force=true to reinitialize'\n    outputs['already_installed'] = True\n    exit()\n\n# Create directory structure\ntarget_dir.mkdir(exist_ok=True)\n(target_dir / 'specs').mkdir(exist_ok=True)\n(target_dir / 'workgroups').mkdir(exist_ok=True)\n(target_dir / 'prompts').mkdir(exist_ok=True)\n(target_dir / 'planning').mkdir(exist_ok=True)\n\n# Create .gitignore if it doesn't exist\ngitignore_path = target_dir / '.gitignore'\nif not gitignore_path.exists():\n    gitignore_content = '''# KnowzCode gitignore - protects environment-specific files\n\n# Environment-specific (contains local paths, commands)\nenvironment_context.md\n\n# Session-specific work (can be regenerated)\nworkgroups/\n\n# Personal notes and scratch files\n*.local.md\n.scratch/\n'''\n    with open(gitignore_path, 'w') as f:\n        f.write(gitignore_content)\n\n# Note: The actual template files (knowzcode_loop.md, etc.) should be copied\n# from the plugin template directory or created by the /kc:init command.\n# This skill creates the structure; the command copies the content.\n\noutputs['success'] = True\noutputs['target_dir'] = str(target_dir)\noutputs['directories_created'] = ['specs', 'workgroups', 'prompts', 'planning']\noutputs['gitignore_created'] = not gitignore_path.exists()\noutputs['message'] = f'KnowzCode directory structure created at {target_dir}/'"
+    }
+  ]
+}

package/skills/load-core-context.json

@@ -1,18 +1,18 @@
-{
-  "name": "load-core-context",
-  "version": "0.3.3",
-  "description": "Loads the KnowzCode project overview, architecture, tracker, log header, and automation manifest for downstream steps.",
-  "parameters": [],
-  "actions": [
-    {
-      "type": "read_file",
-      "paths": [
-        "knowzcode/knowzcode_project.md",
-        "knowzcode/knowzcode_architecture.md",
-        "knowzcode/knowzcode_tracker.md",
-        "knowzcode/knowzcode_log.md",
-        "knowzcode/automation_manifest.md"
-      ]
-    }
-  ]
-}
+{
+  "name": "load-core-context",
+  "version": "0.3.7",
+  "description": "Loads the KnowzCode project overview, architecture, tracker, log header, and automation manifest for downstream steps.",
+  "parameters": [],
+  "actions": [
+    {
+      "type": "read_file",
+      "paths": [
+        "knowzcode/knowzcode_project.md",
+        "knowzcode/knowzcode_architecture.md",
+        "knowzcode/knowzcode_tracker.md",
+        "knowzcode/knowzcode_log.md",
+        "knowzcode/automation_manifest.md"
+      ]
+    }
+  ]
+}

package/skills/log-entry-builder.json

@@ -1,15 +1,15 @@
-{
-  "name": "log-entry-builder",
-  "version": "0.3.3",
-  "description": "Appends structured entries to knowzcode/knowzcode_log.md with KnowzCode formatting.",
-  "parameters": [
-    {"name": "entry_type", "type": "string", "required": true},
-    {"name": "content", "type": "string", "required": true}
-  ],
-  "actions": [
-    {
-      "type": "python",
-      "code": "from pathlib import Path\nentry_type = inputs['entry_type']\ncontent = inputs['content'].strip()\npath = Path('knowzcode/knowzcode_log.md')\ntext = path.read_text()\nmarker = '---\n**[NEWEST ENTRIES APPEAR HERE - DO NOT REMOVE THIS MARKER]**'\nidx = text.index(marker) + len(marker)\nnew_entry = f"\n---\n**Type:** {entry_type}\n{content}\n"\nupdated = text[:idx] + new_entry + text[idx:]\npath.write_text(updated)"
-    }
-  ]
-}
+{
+  "name": "log-entry-builder",
+  "version": "0.3.7",
+  "description": "Appends structured entries to knowzcode/knowzcode_log.md with KnowzCode formatting.",
+  "parameters": [
+    {"name": "entry_type", "type": "string", "required": true},
+    {"name": "content", "type": "string", "required": true}
+  ],
+  "actions": [
+    {
+      "type": "python",
+      "code": "from pathlib import Path\nentry_type = inputs['entry_type']\ncontent = inputs['content'].strip()\npath = Path('knowzcode/knowzcode_log.md')\ntext = path.read_text()\nmarker = '---\n**[NEWEST ENTRIES APPEAR HERE - DO NOT REMOVE THIS MARKER]**'\nidx = text.index(marker) + len(marker)\nnew_entry = f"\n---\n**Type:** {entry_type}\n{content}\n"\nupdated = text[:idx] + new_entry + text[idx:]\npath.write_text(updated)"
+    }
+  ]
+}