knowzcode 0.3.1 → 0.3.6

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official KnowzCode plugin marketplace - Platform-agnostic AI development methodology",
-    "version": "0.3.1"
+    "version": "0.3.6"
   },
   "plugins": [
     {
       "name": "kc",
       "source": "./",
       "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-      "version": "0.3.1",
+      "version": "0.3.6",
       "author": {
         "name": "Alex Headscarf"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kc",
   "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "author": {
     "name": "Alex Headscarf"
   }

package/README.md

@@ -6,7 +6,7 @@
 
 [![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT_+_Commons_Clause-yellow.svg)](LICENSE)
 [![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowzcode)
-[![Version](https://img.shields.io/badge/version-0.3.1-blue)](https://github.com/knowz-io/knowzcode/releases)
+[![Version](https://img.shields.io/badge/version-0.3.6-blue)](https://github.com/knowz-io/knowzcode/releases)
 
 [Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)
 

package/agents/analyst.md

@@ -59,6 +59,37 @@ If MCP is configured:
 
 If MCP is not available, use standard grep/glob. All analysis works without MCP.
 
+## Preliminary Findings Protocol (Parallel Teams Only)
+
+When running in Parallel Teams mode and the architect is alive during Stage 0, stream preliminary NodeID findings as you discover them. This lets the architect start speculative research while you complete your full analysis.
+
+### Rules
+- Max **3** `[PRELIMINARY]` DMs to the architect
+- Send each DM as soon as you have high-confidence evidence for a NodeID — don't batch
+- Do NOT wait for scouts to finish; send findings from your own scanning
+- If the change is clearly a 1-NodeID micro-change, skip this protocol (no DMs needed)
+- Sequential mode: skip this protocol entirely (no architect to DM)
+
+### Message Format
+```
+[PRELIMINARY] NodeID: {PascalCaseName} | Affected: {comma-separated file paths} | Risk: {low/medium/high} | Spec: {new/update-existing}
+```
+
+### Example
+```
+[PRELIMINARY] NodeID: UserAuth | Affected: src/auth/login.ts, src/auth/middleware.ts | Risk: medium | Spec: new
+```
+
+### When to Send
+- After your first targeted grep confirms a distinct domain area is affected
+- After reading a key file reveals cross-cutting impact worth a separate NodeID
+- After scanner broadcasts confirm a new area you hadn't yet identified
+
+### What NOT to Send
+- Speculative NodeIDs you haven't confirmed with at least one file read
+- Duplicate findings (same NodeID already sent)
+- Consolidation updates (save those for the final Change Set)
+
 ## Exit Expectations
 
 - Produce a complete Change Set (format defined in `knowzcode_loop.md` section 3.1)

package/agents/architect.md

@@ -84,6 +84,73 @@ Provide a structured Architecture Health Report at each quality gate. This is a
 - Recommendation: {proceed / fix drift}
 ```
 
+## Speculative Research Protocol (Parallel Teams Only)
+
+During Stage 0, after completing your standard pre-load (architecture docs, existing specs, project config), use remaining idle time to conduct speculative research based on `[PRELIMINARY]` NodeID messages from the analyst.
+
+### Rules
+- **READ-ONLY** — do NOT write any files, create tasks, or modify specs
+- Research only — gather context for faster spec drafting after Gate #1
+- Graceful degradation: if no `[PRELIMINARY]` DMs arrive, just finish standard pre-load and wait
+- Max research scope: files mentioned in `[PRELIMINARY]` messages + their immediate imports/dependencies
+
+### What To Research
+For each `[PRELIMINARY]` NodeID received:
+1. Read the affected files listed in the message
+2. Check `knowzcode/specs/*.md` for existing specs in the same domain (consolidation check)
+3. Analyze interface patterns — what public APIs exist, what contracts would a spec need to define
+4. Note cross-NodeID dependencies if multiple `[PRELIMINARY]` messages share files or interfaces
+
+### What NOT To Do
+- Draft specs or write any content to disk
+- Create tasks or assign work
+- Send DMs to the analyst (don't interrupt their scanning)
+- Research areas NOT mentioned in `[PRELIMINARY]` messages (stick to what the analyst flagged)
+
+### Outcome
+By Gate #1, you should have ~80% of the research done for flagged NodeIDs. When the lead sends the approved Change Set and creates spec-drafting tasks, you can begin drafting immediately with deep context already loaded.
+
+## Parallel Spec Coordination (Parallel Teams — 3+ NodeIDs)
+
+When the approved Change Set contains **3 or more NodeIDs**, the lead spawns temporary spec-drafter agents to parallelize spec drafting. You coordinate this process.
+
+### Threshold
+- **1-2 NodeIDs**: You draft all specs alone (current behavior, zero overhead)
+- **3+ NodeIDs**: Lead spawns spec-drafters, you coordinate and review
+
+### Your Coordination Role
+
+#### 1. Partition NodeIDs
+When the lead DMs you the approved Change Set with 3+ NodeIDs:
+- Group NodeIDs into partitions of 1-2 each
+- Constraints:
+  - NodeIDs targeting the **same existing spec** MUST be in the same partition
+  - NodeIDs with **interface dependencies** (one consumes the other's output) SHOULD be together
+  - Max 3 spec-drafter partitions (`ceil(NodeID_count / 2)`, capped at 3)
+- Reply to the lead with your proposed partition plan
+
+#### 2. Brief Each Drafter
+For each spec-drafter partition, prepare a briefing (the lead includes this in the spawn prompt):
+- Research findings from Speculative Research (file contents, interface analysis, consolidation notes)
+- Cross-NodeID interface constraints (e.g., "NodeID-A's UserService is consumed by NodeID-B")
+- Consolidation instructions (update existing spec vs. create new)
+- VERIFY criteria guidance based on your architecture review
+
+#### 3. Consistency Review
+After all spec-drafters complete their specs:
+- Read all drafted specs
+- Check cross-spec alignment: naming consistency, interface compatibility, no conflicting decisions
+- Verify VERIFY criteria coverage: every NodeID has 2+ VERIFY statements, no gaps
+- Check consolidation: specs that should share a file do share a file
+- Fix any inconsistencies directly (you have Write/Edit tools)
+- Report consistency review results to the lead
+
+### What Spec-Drafters Do
+Spec-drafters use your same agent definition (`architect`) with a scoped spawn prompt. They:
+- Draft specs for their assigned NodeIDs using the 4-section format
+- Follow the same Consolidation Mandate and Spec Philosophy as you
+- Shut down after their specs are drafted (before your consistency review)
+
 ## During Implementation (Parallel Teams — Consultative Role)
 
 When builders are implementing, you persist as a read-only consultative resource:

package/agents/closer.md

@@ -61,12 +61,17 @@ Scan the WorkGroup for insight-worthy patterns using the signal types from `know
 ### Knowz-Scribe Delegation (Parallel Teams)
 
 If knowz-scribe is active (Parallel Teams mode with MCP connected):
-- Send message to **knowz-scribe**: `"Capture Phase 3: {wgid}"` — the scribe handles all vault writes (appropriate vaults by type)
+- Create capture task: `TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send DM to **knowz-scribe** with task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`
 - Do NOT call `create_knowledge` directly — the scribe owns all vault writes
+- Note: The lead waits for the scribe's capture task to complete before shutdown. The closer does NOT wait — create the task, send the DM, and continue finalization.
 
 ### Direct Write Fallback (Sequential/Subagent)
 
 If knowz-scribe is NOT active but MCP is configured:
+
+> **Content Detail Principle**: Vault entries are retrieved via semantic search — write detailed, self-contained content with full reasoning, technology names, and code examples. See `knowzcode/knowzcode_vaults.md`.
+
 1. Read `knowzcode/knowzcode_vaults.md` to discover configured vaults
 2. For each learning type, find the appropriate vault by type:
    - Pattern/Workaround/Performance → vault with type `code`

package/agents/knowz-scribe.md

@@ -40,22 +40,32 @@ This catches MCP issues at Stage 0 instead of 10+ minutes later at first capture
 
 ## Capture Request Format
 
-You receive messages from the lead or other agents in this format:
+You receive capture requests from the lead or other agents in three forms:
 
-```
-Capture Phase {phase}: {wgid}
-```
+### Phase Captures (task-tracked)
+Format: `"Capture Phase {phase}: {wgid}. Your task: #{task-id}"`
 
-Examples:
-- `Capture Phase 1A: WG-feat-auth-20260212` — scope decision approved
-- `Capture Phase 2A: WG-feat-auth-20260212` — implementation patterns discovered
-- `Capture Phase 2B: WG-feat-auth-20260212` — audit results
-- `Capture Phase 3: WG-feat-auth-20260212` — finalization learnings
+Triggered at quality gates. Read the WorkGroup file, extract phase-specific content, write to appropriate vaults.
+
+### Explicit Ad-Hoc: `"Log: {description}"`
+A teammate has identified knowledge worth capturing and is telling you to write it.
+You MUST write it — decide which vault based on content type using the Learning Category Routing table.
+Apply standard dedup checking. If a task ID is included, track it.
+
+### Soft Ad-Hoc: `"Consider: {description}"`
+A teammate is forwarding something that MIGHT be worth capturing — a catch-all.
+Evaluate the content against the Learning Category signal types (Pattern, Decision, Workaround, Performance, Security, Convention).
+If it's insight-worthy and not duplicative, write it. If not, skip silently.
+The sender is not asking you to log it — they're asking you to use your judgement.
 
 ## Write Process
 
 For each capture request:
 
+### Step 0: Claim Task
+
+If a pre-created task exists for this capture (task ID provided in the capture message), claim it immediately (`TaskUpdate(taskId, status: "in_progress")`). After completing all vault writes for this capture, mark the task complete with a summary (count of items written + vault names). If no task ID was provided (ad-hoc messages), proceed without task tracking.
+
 ### Step 1: Read Context
 
 1. Read the WorkGroup file (`knowzcode/workgroups/{wgid}.md`) to extract relevant content for the phase
@@ -90,9 +100,11 @@ If multiple vaults match the target type, use the first one listed in `knowzcode
 
 For each target vault, apply its **Content Filter** to format the `create_knowledge` payload:
 
-- **Title**: Use the appropriate prefix (`Pattern:`, `Decision:`, `Workaround:`, `Performance:`, `Security:`, `Convention:`, `Scope:`, `Audit:`, `Integration:`, `Completion:`)
-- **Content**: Follow the content filter structure defined for the vault type
-- **Tags**: Include learning category, phase, and domain-relevant tags
+> **Content Detail Principle**: Vault entries are retrieved via semantic search, not read directly like local files. Every entry must be self-contained and detailed — include full reasoning, specific technology names, code examples, file paths, and error messages. A terse entry like `"[Risk] Medium"` is useless when retrieved months later. See `knowzcode/knowzcode_vaults.md` for the full principle and examples.
+
+- **Title**: Use the appropriate prefix (`Pattern:`, `Decision:`, `Workaround:`, `Performance:`, `Security:`, `Convention:`, `Scope:`, `Audit:`, `Integration:`, `Completion:`) followed by a descriptive summary including key technology names for search discoverability
+- **Content**: Follow the content filter structure defined for the vault type — fill every field with enough detail that the entry is useful without any other context
+- **Tags**: Include learning category, phase, domain-relevant tags, and specific technology names
 - **Source**: `KnowzCode WorkGroup {wgid}`
 
 ### Step 4: Dedup Check
@@ -107,49 +119,62 @@ Call `create_knowledge` with the formatted payload for each target vault.
 
 ### Phase 1A (Scope Approved)
 Extract from WorkGroup:
-- NodeIDs in the change set
-- Risk assessment
-- User approval decision
+- **NodeIDs**: List each with its description, affected files, and domain area
+- **Risk assessment**: Include the full reasoning — what could break, which files are high-risk, what mitigation is planned. Never write just "Medium"
+- **Scope decisions**: What was included/excluded and why — alternatives the user considered
 - Write to: `ecosystem` vault (or single vault)
 
 ### Phase 2A (Implementation Complete)
 Extract from WorkGroup:
-- Implementation patterns and workarounds discovered during build
-- New utilities or abstractions created
-- Performance optimizations applied
+- **Patterns discovered**: Describe the pattern, why it was needed, how it works, and include file paths or code snippets. E.g., "Created retry wrapper in src/utils/retry.ts using exponential backoff with jitter for all external API calls"
+- **Workarounds**: What limitation was hit, what the workaround does, and any upstream fix to watch for
+- **New utilities or abstractions**: What was created, its API surface, and where it's used
+- **Performance optimizations**: Before/after metrics, the technique used, and any trade-offs
 - Write to: `code` vault for patterns/workarounds/performance, `ecosystem` vault for decisions
 
 ### Phase 2B (Audit Complete)
 Extract from WorkGroup:
-- Audit score and findings
-- Security issues found
-- Gap resolution decisions
+- **Audit findings**: Completion percentage, specific gaps with file paths and line references
+- **Security issues**: Describe the vulnerability, affected code paths, severity reasoning, and how it was (or should be) fixed
+- **Gap resolution decisions**: What was deferred vs fixed, and the rationale for each decision
 - Write to: `ecosystem` vault for audit learnings, user's enterprise vault for audit trail (if configured + compliance enabled)
 
 ### Phase 3 (Finalization)
 Extract from WorkGroup:
-- Architectural learnings and consolidation decisions
-- Convention patterns established
-- Any remaining insight-worthy content
+- **Architectural learnings**: Structural discoveries, component relationships that weren't obvious, integration patterns that emerged
+- **Convention patterns established**: New team conventions with full rationale and examples
+- **Consolidation decisions**: What was merged or refactored during finalization and why
 - Write to: appropriate vault per learning category routing
 
 ## Communication
 
-- **Report to lead only on**: errors (MCP failures, vault not found) or dedup catches
-- **Silent on success** — do not broadcast write confirmations to the team
+- **Report to lead on**: errors (MCP failures, vault not found) or dedup catches
+- **Task-based confirmation**: Mark pre-created capture tasks complete with summary (count + vault names) — this is the primary confirmation mechanism
+- **Phase 3 DM confirmation REQUIRED**: After processing Phase 3, send confirmation DM to lead: `"Phase 3 capture complete: {N} items written to {vault names}"`
+- **Silent on success for other phases** — task completion is sufficient, do not broadcast
 - Respond to direct queries from teammates about what has been captured
 
 ## MCP Graceful Degradation
 
-If MCP calls fail:
-1. Log the failure
-2. Report the error to the lead via direct message
-3. Do not retry immediately — wait for the next capture request or lead instruction
-4. The workflow continues without vault writes
+If MCP calls fail or MCP is unavailable:
+1. **Queue locally**: Append the capture to `knowzcode/pending_captures.md` using this format:
+   ```markdown
+   ### {timestamp} — {title}
+   - **Intent**: {Phase capture | Log | Consider}
+   - **Category**: {Pattern|Decision|Workaround|Performance|Security|Convention}
+   - **Target Vault Type**: {code|ecosystem|enterprise|finalizations}
+   - **Source**: {agent name} / WorkGroup {wgid}
+   - **Content**: {description or extracted learning}
+   ```
+2. Report the MCP failure to the lead via DM: `"MCP unavailable — queued {N} capture(s) to pending_captures.md"`
+3. If MCP recovers mid-session, flush pending captures to vaults on the next capture request
+4. Mark the capture task complete (if task-tracked) with note: `"Queued locally — MCP unavailable"`
+
+Never drop knowledge. If MCP is down, queue it. The pending file can be flushed later via `/kc:learn --flush` or by a future scribe instance.
 
 ## Exit Expectations
 
-- All capture requests processed
-- Dedup catches reported to lead
-- Errors reported to lead
-- Ready for shutdown after closer completes
+- All capture tasks marked complete
+- Phase 3 confirmation DM sent to lead
+- Dedup catches and errors reported to lead
+- Ready for shutdown only after all capture tasks are complete

package/agents/project-advisor.md

@@ -69,10 +69,11 @@ Near the end of Stage 2 (before the gap loop), DM lead with structured proposals
 
 ## Knowz-Scribe Integration
 
-If knowz-scribe is active, DM it with idea captures:
-> "Capture idea: {description}. Category: {Pattern|Decision|Convention}. Source: WorkGroup {wgid}."
+If knowz-scribe is active, DM it with idea captures. Include enough detail for the scribe to write a rich vault entry — terse one-liners produce poor search results when stored in the vault.
 
-The scribe routes to the correct vault based on category.
+> "Log: {Detailed description including the specific technology, component, and rationale — e.g. 'Discovered that the Express auth middleware should validate JWT clockTolerance=0 to prevent revoked tokens being accepted during the tolerance window. Affects src/middleware/auth.ts and all protected routes.'}. Category: {Pattern|Decision|Convention}. Source: WorkGroup {wgid}."
+
+The scribe routes to the correct vault based on category. The more context you provide in the DM, the more useful the vault entry will be when retrieved via search months later.
 
 ## Enterprise Compliance (Optional)
 

package/commands/connect-mcp.md

@@ -88,9 +88,9 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
    - Store parsed values for use in configuration
 
 2. **Check for existing configuration**
-   - Check if MCP server already configured: `claude mcp get knowzcode`
+   - Check if MCP server already configured: `CLAUDECODE= claude mcp get knowz`
    - If already configured, ask if user wants to reconfigure
-   - If yes, run `claude mcp remove knowzcode` first
+   - If yes, run `CLAUDECODE= claude mcp remove knowz` first
 
 3. **Prompt for API key (if not provided)**
    - If no API key in arguments, prompt user interactively:
@@ -280,18 +280,42 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
    You can edit knowzcode/knowzcode_vaults.md to update descriptions or routing rules.
    ```
 
+   **Step 6f: Update CLAUDE.md with vault targeting guidance**
+
+   Ensure agents always know to pass `vaultId` by adding a reference section to the project's CLAUDE.md:
+
+   1. Read the project's `CLAUDE.md`
+   2. Search for an existing `### Vault Targeting` or `### Knowz MCP` section
+   3. **If found:** Replace the existing section with the updated content below
+   4. **If NOT found:** Append the section after the `# KnowzCode Integration` block (or at the end if not found)
+   5. Insert a vault targeting reference section that points to the central config:
+
+   ```markdown
+   ### Vault Targeting (MCP Writes)
+   **Always pass `vaultId`** when calling `create_knowledge` or `update_knowledge`.
+   Omitting it saves to the tenant default vault — NOT the project vault.
+
+   Vault IDs and routing rules: `knowzcode/knowzcode_vaults.md`
+   If vault IDs are already in context from a previous read, do not re-read the file.
+   For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
+   ```
+
+   6. Confirm: `"Updated CLAUDE.md with vault targeting guidance (vault IDs managed in knowzcode/knowzcode_vaults.md)."`
+
+   **Idempotent:** Replaces existing `### Vault Targeting` section rather than duplicating.
+
 7. **Add MCP server using CLI**
    ```bash
    claude mcp add --transport http \
      --scope <chosen-scope> \
-     knowzcode \
+     knowz \
      <endpoint-url> \
      --header "Authorization: Bearer <api-key>" \
      --header "X-Project-Path: $(pwd)"
    ```
 
 8. **Verify configuration**
-   - Run: `claude mcp get knowzcode`
+   - Run: `CLAUDECODE= claude mcp get knowz`
    - Confirm server appears in the list
    - Check for any error messages
 
@@ -437,7 +461,7 @@ If using --dev environment, verify the dev server is running.
 To change from local to project scope:
 ```bash
 # Remove existing (or the command will prompt to reconfigure)
-claude mcp remove knowzcode
+CLAUDECODE= claude mcp remove knowz
 
 # Re-add with new scope
 /kc:connect-mcp <api-key> --scope project

package/commands/learn.md

@@ -182,6 +182,9 @@ Capture the provided insight to the appropriate vault using the MCP `create_know
      ```
 
 7. **Build learning content**
+
+   > Vault entries are retrieved via semantic search — content must be detailed and self-contained. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
    ```markdown
    [CONTEXT]
    Project: {project-name}
@@ -189,9 +192,11 @@ Capture the provided insight to the appropriate vault using the MCP `create_know
    Vault: {selected_vault_name}
    Source: {--source value or "KnowzCode /kc:learn command"}
    Date: {ISO timestamp}
+   Situation: {Expand on what prompted this learning — the problem being solved, the component involved, relevant technology stack. Provide enough background that someone unfamiliar with the project can understand.}
 
    [INSIGHT]
    {User's insight text}
+   Detail: {Expand the user's insight with technical specifics — include file paths, library names, version numbers, code patterns, or error messages that make this actionable when retrieved via search.}
 
    [SOURCE]
    Captured via /kc:learn command
@@ -202,7 +207,7 @@ Capture the provided insight to the appropriate vault using the MCP `create_know
    ```json
    create_knowledge({
      "content": "{formatted content}",
-     "title": "{Category}: {Brief summary from insight}",
+     "title": "{Category}: {Descriptive summary — include key technology names for search discoverability}",
      "knowledgeType": "Note",
      "vaultId": "{selected_vault_id}",
      "tags": ["{category}", "{extracted-tags}", "{project-name}"],

package/commands/register.md

@@ -111,7 +111,7 @@ YOU                              USER
 
 1. Check if MCP server already configured:
    ```bash
-   claude mcp get knowzcode
+   CLAUDECODE= claude mcp get knowz
    ```
 
 2. If already configured, display:
@@ -127,7 +127,7 @@ YOU                              USER
    ```
 
    Use AskUserQuestion to get user choice. If they choose to keep existing, STOP.
-   If they choose to continue, run `claude mcp remove knowzcode` first.
+   If they choose to continue, run `CLAUDECODE= claude mcp remove knowz` first.
 
 3. If not configured: Continue to Step 2.
 
@@ -330,7 +330,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
    # Production (default)
    claude mcp add --transport http \
      --scope <chosen-scope> \
-     knowzcode \
+     knowz \
      https://mcp.knowz.io/mcp \
      --header "Authorization: Bearer <api_key>" \
      --header "X-Project-Path: $(pwd)"
@@ -338,7 +338,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
    # Development (with --dev flag)
    claude mcp add --transport http \
      --scope <chosen-scope> \
-     knowzcode \
+     knowz \
      https://mcp.dev.knowz.io/mcp \
      --header "Authorization: Bearer <api_key>" \
      --header "X-Project-Path: $(pwd)"
@@ -346,7 +346,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
 
 5. **Verify MCP configuration**:
    ```bash
-   claude mcp get knowzcode
+   CLAUDECODE= claude mcp get knowz
    ```
 
 6. **Configure vault in mcp_config.md**:

package/commands/status.md

@@ -41,7 +41,7 @@ Check Agent Teams status, then check the KnowzCode MCP server status, and report
 
 2. **Check MCP server configuration**
    ```bash
-   claude mcp get knowzcode
+   CLAUDECODE= claude mcp get knowz
    ```
 
    - If configured: Extract scope, endpoint, headers