knowzcode 0.3.1 → 0.3.3

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.3"
   },
   "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.3",
       "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.3",
   "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.3-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/commands/connect-mcp.md

@@ -280,6 +280,30 @@ 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 \

package/commands/work.md

@@ -66,11 +66,15 @@ If `knowzcode/knowzcode_orchestration.md` exists, parse its YAML blocks:
 2. `SCOUT_MODE` = `scout_mode` value (default: "full")
 3. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
 4. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
+5. `CODEBASE_SCANNER_ENABLED` = `codebase_scanner_enabled` value (default: true)
+6. `PARALLEL_SPEC_THRESHOLD` = `parallel_spec_threshold` value (default: 3, clamp to 2-10)
 
 Apply flag overrides (flags win over config):
 - `--max-builders=N` in `$ARGUMENTS` → override `MAX_BUILDERS`
 - `--no-scouts` in `$ARGUMENTS` → override `SCOUT_MODE = "none"`
 - `--no-mcp` in `$ARGUMENTS` → override `MCP_AGENTS_ENABLED = false`
+- `--no-scanners` in `$ARGUMENTS` → override `CODEBASE_SCANNER_ENABLED = false`
+- `--no-parallel-specs` in `$ARGUMENTS` → override `PARALLEL_SPEC_THRESHOLD = 999` (effectively disabled)
 
 If the file doesn't exist, use hardcoded defaults (current behavior).
 
@@ -354,7 +358,13 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - If `SCOUT_MODE = "none"`: spawn analyst + architect only (2 agents). Analyst and architect scan the codebase independently without pre-loaded scout context.
    - Always:
      - `TaskCreate("Phase 1A: Impact analysis for {goal}")` → `TaskUpdate(owner: "analyst")`
-     - `TaskCreate("Pre-load architecture context")` → `TaskUpdate(owner: "architect")`
+     - `TaskCreate("Pre-load architecture context and speculative research")` → `TaskUpdate(owner: "architect")`
+   - If `CODEBASE_SCANNER_ENABLED = true` (default):
+     - Derive two search focuses from the goal:
+       - **Scanner-Direct**: source code search — grep for goal keywords, read affected code paths
+       - **Scanner-Tests**: test discovery — search test directories for tests covering the goal area
+     - `TaskCreate("Scanner: direct codebase scan for {goal}")` → `TaskUpdate(owner: "scanner-direct")`
+     - `TaskCreate("Scanner: test coverage scan for {goal}")` → `TaskUpdate(owner: "scanner-tests")`
    Spawn all Group A agents with their `{task-id}` in the spawn prompt (use spawn prompts from Phase Prompt Reference below).
 5. **Spawn Group B** (MCP agents — same turn as Group A): If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`:
    Create tasks first, pre-assign, then spawn with task IDs:
@@ -369,16 +379,17 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - If `project-advisor` in list: `TaskCreate("Project advisor: backlog context")` → `TaskUpdate(owner: "project-advisor")`
    Spawn each enabled specialist with its `{task-id}` in the spawn prompt (use spawn prompts from Specialist Spawn Prompts section below).
    If `SPECIALISTS_ENABLED` is empty, skip Group C.
-7. **Roster confirmation** — lead lists every spawned agent by name to the user. Include Group C specialists if active. If `VAULTS_CONFIGURED` was true but knowz-scout or knowz-scribe is missing from the roster, STOP and re-spawn the missing agent(s) before continuing.
-8. All spawned agents work immediately in parallel (context scouts are cheap Sonnet read-only agents; knowz-scribe is a cheap Haiku agent; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-10 agents at Stage 0.
+7. **Roster confirmation** — lead lists every spawned agent by name to the user. Include scanners and Group C specialists if active. If `VAULTS_CONFIGURED` was true but knowz-scout or knowz-scribe is missing from the roster, STOP and re-spawn the missing agent(s) before continuing.
+8. All spawned agents work immediately in parallel (context scouts are cheap Sonnet read-only agents; scanners are lightweight general-purpose agents; knowz-scribe is a cheap Haiku agent; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-12 agents at Stage 0.
 9. Scouts broadcast findings → analyst and architect consume as messages. Specialists work independently on their Stage 0 tasks.
 
-**Key**: The analyst does NOT wait for scouts or specialists to finish. It starts scanning the codebase immediately. Scout findings arrive as messages and enrich the analyst's work as they arrive. Specialist findings are consumed by the lead at gates.
+**Key**: The analyst does NOT wait for scouts, scanners, or specialists to finish. It starts scanning the codebase immediately. Scout and scanner findings arrive as messages and enrich the analyst's work as they arrive. The analyst also streams `[PRELIMINARY]` NodeID findings to the architect as it discovers them (see Preliminary Findings Protocol). Specialist findings are consumed by the lead at gates.
 
 ### Stage 1: Analysis + Specification
 
 1. Analyst completes Change Set (includes dependency map — see `agents/analyst.md`)
 2. Lead reads analyst's task summary
+3. Shut down scanners (scanner-direct, scanner-tests) if they were spawned — no longer needed after analysis
 3. **Specialist Change Set reviews** (if `SPECIALISTS_ENABLED` non-empty): Create review tasks blocked on analysis:
    - If `security-officer` active: `TaskCreate("Security officer: Change Set review", addBlockedBy: [analysis-task-id])` → `TaskUpdate(owner: "security-officer")`. DM security-officer: `"**New Task**: #{task-id} — Review Change Set for security risk. Rate each NodeID."`
    - If `test-advisor` active: `TaskCreate("Test advisor: Change Set test strategy", addBlockedBy: [analysis-task-id])` → `TaskUpdate(owner: "test-advisor")`. DM test-advisor: `"**New Task**: #{task-id} — Recommend test types per NodeID."`
@@ -389,12 +400,29 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - Specialist Reports (if active — see gate template below)
 5. User approves (or rejects → re-run analyst with feedback)
 6. Lead sends DM to architect with the approved Change Set
-7. Lead creates spec-drafting tasks for architect (1 task per NodeID, `addBlockedBy: [analysis-task-id]`):
-   - `TaskCreate("Spec: NodeID-X")` → `TaskUpdate(taskId, owner: "architect")`
-   - DM architect with task IDs: `"**New Tasks**: #{id-1} Spec: NodeID-A, #{id-2} Spec: NodeID-B. Approved Change Set: {summary}"`
-   - Architect is already warm (pre-loaded during Stage 0) → specs drafted FAST
+7. **Spec Drafting** — choose path based on NodeID count and `PARALLEL_SPEC_THRESHOLD`:
+
+   **Path A: Standard (fewer than PARALLEL_SPEC_THRESHOLD NodeIDs)**
+   - Lead creates spec-drafting tasks for architect (1 task per NodeID, `addBlockedBy: [analysis-task-id]`):
+     - `TaskCreate("Spec: NodeID-X")` → `TaskUpdate(taskId, owner: "architect")`
+     - DM architect with task IDs: `"**New Tasks**: #{id-1} Spec: NodeID-A, #{id-2} Spec: NodeID-B. Approved Change Set: {summary}"`
+   - Architect is already warm (pre-loaded + speculative research during Stage 0) → specs drafted FAST
    - If Gate #1 rejected: shut down architect, re-run analyst with feedback, re-spawn architect after
-8. Architect completes specs
+
+   **Path B: Parallel Spec Drafting (PARALLEL_SPEC_THRESHOLD or more NodeIDs)**
+   - Lead DMs architect the full approved Change Set and asks for a partition plan (see `agents/architect.md` — Parallel Spec Coordination)
+   - Architect proposes NodeID partitions (1-2 NodeIDs each, max 3 partitions, respecting same-spec and interface constraints)
+   - Lead spawns spec-drafter agents — one per partition:
+     - Spec-drafters use the `architect` agent definition with a scoped spawn prompt
+     - Each drafter gets: its NodeID partition, architect's research findings, cross-NodeID interface constraints, consolidation instructions
+     - `TaskCreate("Spec draft: NodeID-A, NodeID-B")` → `TaskUpdate(owner: "spec-drafter-1")`
+     - Max 3 spec-drafters: `ceil(NodeID_count / 2)`, capped at 3
+   - Spec-drafters draft specs in parallel
+   - After all spec-drafters complete: architect runs consistency review (cross-spec alignment, naming, VERIFY coverage)
+   - Shut down spec-drafters after consistency review
+   - If Gate #1 rejected: shut down architect and any spec-drafters, re-run analyst with feedback, re-spawn architect after
+
+8. Architect completes specs (Path A) or architect completes consistency review (Path B)
 9. **Test-advisor spec review** (if `test-advisor` in `SPECIALISTS_ENABLED`): After specs drafted, create spec testability review task:
    - `TaskCreate("Test advisor: spec testability review", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "test-advisor")`
    - DM test-advisor: `"**New Task**: #{task-id} — Review specs for testability. Check VERIFY criteria are automatable."`
@@ -544,14 +572,17 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 | Scout: backlog context | (none) | context-scout-backlog |
 | Knowz-scout: vault queries | (none — persistent) | knowz-scout |
 | Knowz-scribe: listen | (none — persistent) | knowz-scribe |
-| Phase 1A analysis | (none — scouts enrich via broadcast) | analyst |
-| Architect pre-load | (none) | architect |
+| Scanner: direct codebase scan | (none) | scanner-direct |
+| Scanner: test coverage scan | (none) | scanner-tests |
+| Phase 1A analysis | (none — scouts + scanners enrich via broadcast) | analyst |
+| Architect pre-load + speculative research | (none — receives [PRELIMINARY] DMs from analyst) | architect |
 | Security officer: initial threat scan | (none — Group C) | security-officer |
 | Test advisor: coverage baseline | (none — Group C) | test-advisor |
 | Project advisor: backlog context | (none — Group C) | project-advisor |
 | Security officer: Change Set review | Phase 1A analysis | security-officer |
 | Test advisor: Change Set test strategy | Phase 1A analysis | test-advisor |
-| Spec: NodeID-X | Phase 1A (gate approval) | architect |
+| Spec: NodeID-X | Phase 1A (gate approval) | architect (Path A) or spec-drafter-N (Path B) |
+| Spec consistency review | All spec drafts complete (Path B only) | architect |
 | Test advisor: spec testability review | Spec: NodeID-X | test-advisor |
 | Implement: NodeID-X | Spec: NodeID-X | builder-N |
 | Audit: NodeID-X | Implement: NodeID-X | reviewer-N |
@@ -631,6 +662,51 @@ Three instances of the same agent, each focused on a different local folder grou
 
 ---
 
+## Stage 0: Codebase Scanners (2 instances — conditional)
+
+**Agent**: `general-purpose` (x2) | Lightweight codebase searchers (no agent definition file)
+
+Two temporary agents that scan the codebase in parallel with the analyst, broadcasting findings to accelerate impact analysis. Only spawned when `CODEBASE_SCANNER_ENABLED = true` (default).
+
+**scanner-direct spawn prompt**:
+> You are `scanner-direct` for WorkGroup `{wgid}`.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Focus**: Search source code for goal-related keywords and patterns.
+>
+> **Steps**:
+> 1. Grep for goal keywords across source files (exclude node_modules, dist, build, .git)
+> 2. Read the top 5-8 matching files to understand affected code paths
+> 3. Identify module boundaries and cross-module dependencies
+> 4. Note public APIs and interfaces that may need changes
+>
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast findings to all teammates — affected files, code paths, module boundaries, and interface patterns.
+> **Budget**: Complete within ~12 turns. Focus on breadth over depth.
+
+**scanner-tests spawn prompt**:
+> You are `scanner-tests` for WorkGroup `{wgid}`.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Focus**: Discover tests covering the goal area to understand test patterns and coverage shape.
+>
+> **Steps**:
+> 1. Glob for test files: `**/*.test.*`, `**/*.spec.*`, `**/test_*`, `**/tests/**`
+> 2. Grep test files for goal-related keywords
+> 3. Read 3-5 matching test files to understand testing patterns (test framework, mocking strategy, fixture patterns)
+> 4. Check for integration/e2e tests related to the goal area
+>
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast findings to all teammates — test file locations, testing patterns, coverage gaps, and fixture/mock patterns.
+> **Budget**: Complete within ~12 turns. Focus on breadth over depth.
+
+**Dispatch**:
+- *Parallel Teams*: Spawned at Stage 0 if `CODEBASE_SCANNER_ENABLED = true`. Use `subagent_type: "general-purpose"`, `maxTurns: 12`. Shut down after Stage 1 (analyst completes Change Set).
+- *Sequential Teams*: Not applicable (scanners are Parallel Teams only).
+- *Subagent*: `Task(subagent_type="general-purpose", description="Scan codebase for {focus}", maxTurns=12, prompt=<above>)` if `CODEBASE_SCANNER_ENABLED = true`.
+
+---
+
 ## Stage 0: Knowz Scout
 
 **Agent**: `knowz-scout` | MCP vault researcher and knowledge agent
@@ -740,10 +816,12 @@ The spawn prompts below are used when `SPECIALISTS_ENABLED` is non-empty. Specia
 >
 > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
+> **Codebase scanners**: Scanner agents are running in parallel — their findings will arrive as broadcast messages. Incorporate them into your analysis but do NOT wait for them.
+> **Preliminary Findings Protocol**: As you discover high-confidence NodeIDs, DM the architect with `[PRELIMINARY]` messages (max 3 — see `agents/analyst.md` for format). This lets the architect start speculative research early.
 > **Deliverable**: Change Set proposal written to the WorkGroup file. Include NodeIDs, descriptions, affected files, risk assessment, and dependency map (for Parallel Teams mode).
 
 **Dispatch**:
-- *Parallel Teams*: Spawned at Stage 0 alongside scouts and architect. Starts immediately (no blockedBy).
+- *Parallel Teams*: Spawned at Stage 0 alongside scouts, scanners, and architect. Starts immediately (no blockedBy).
 - *Sequential Teams*: Spawn teammate `analyst`, create task `Phase 1A: Impact analysis for "{goal}"`, wait for completion.
 - *Subagent*: `Task(subagent_type="analyst", description="Phase 1A impact analysis", prompt=<above>)`
 
@@ -783,11 +861,34 @@ If MCP is configured and knowz-scribe is active, after Change Set approval:
 
 ---
 
+## Stage 0: Architect Pre-load (Parallel Teams)
+
+**Agent**: `architect` | Spawned at Stage 0 for context pre-loading and speculative research
+
+In Parallel Teams mode, the architect is spawned at Stage 0 (not at Phase 1B). It pre-loads architecture context and performs speculative research on `[PRELIMINARY]` NodeIDs from the analyst.
+
+**Stage 0 spawn prompt** (Parallel Teams only):
+> You are the **architect** for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition.
+>
+> **Goal**: {goal}
+> **Context files**: Read sections 1-2 and 3.2 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Stage 0 Role**: Pre-load architecture context, then perform speculative research on any `[PRELIMINARY]` NodeID messages from the analyst (see Speculative Research Protocol in `agents/architect.md`). READ-ONLY research — do NOT write specs yet.
+> **Lifecycle**: You persist through the entire workflow. After Gate #1, you will receive spec-drafting tasks via DM. After Gate #2, you shift to consultative role for builders.
+
+After Gate #1, the lead sends the approved Change Set via DM and creates spec-drafting tasks. For spec-drafting prompts, see Phase 1B below.
+
+---
+
 ## Phase 1B: Specification
 
 **Agent**: `architect` | **Loop.md**: Section 3.2
 
-**Spawn prompt**:
+**Spec-drafting prompt** (sent via DM to already-warm architect in Parallel Teams, or as spawn prompt in Sequential/Subagent):
 > You are the **architect** for WorkGroup `{wgid}`.
 > Read `agents/architect.md` for your full role definition.
 >
@@ -801,12 +902,29 @@ If MCP is configured and knowz-scribe is active, after Change Set approval:
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
 > **Deliverable**: Finalized specs for all NodeIDs written to `knowzcode/specs/`.
 
+**Spec-drafter spawn prompt** (Path B — 3+ NodeIDs, Parallel Teams only):
+> You are `spec-drafter-{N}` for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition — you follow the same Spec Philosophy, Spec Format, and Consolidation Mandate.
+>
+> **Goal**: {goal}
+> **Your NodeIDs**: {partition — 1-2 NodeIDs assigned to this drafter}
+> **Architect Research**: {research findings from architect's speculative research for these NodeIDs}
+> **Cross-NodeID Constraints**: {interface dependencies, shared specs, naming conventions from architect}
+> **Context files**: Read sections 1-2 and 3.2 of `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Deliverable**: Draft specs for your assigned NodeIDs written to `knowzcode/specs/`. The architect will review for consistency after all drafters finish.
+
 **Dispatch**:
-- *Parallel Teams*: Architect is already warm from Stage 0 pre-load. Lead sends DM with approved Change Set, then creates spec-drafting tasks. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Architect plan`.
+- *Parallel Teams*:
+  - **Path A** (< PARALLEL_SPEC_THRESHOLD NodeIDs): Architect is already warm from Stage 0 pre-load + speculative research. Lead sends DM with approved Change Set, then creates spec-drafting tasks. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Architect plan`.
+  - **Path B** (>= PARALLEL_SPEC_THRESHOLD NodeIDs): Lead asks architect for partition plan. Architect proposes partitions. Lead spawns spec-drafters (`subagent_type: "architect"`, `permissionMode: "acceptEdits"`, `maxTurns: 15`) with partition-scoped prompts. After all drafters complete, architect runs consistency review and reports to lead.
 - *Sequential Teams*: Spawn teammate `architect`, create task `Phase 1B: Draft specifications for {N} NodeIDs`. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` Wait for `plan_approval_request`, review, respond with `plan_approval_response`. If `AUTONOMOUS_MODE = true`: auto-approve immediately. Log `[AUTO-APPROVED] Architect plan`.
 - *Subagent*: `Task(subagent_type="architect", description="Phase 1B specification drafting", prompt=<above> + "Present your spec design in your output for lead review.")`
 
-> **Note:** Plan approval (agent pauses for lead review) only works in Agent Teams mode via `permissionMode: plan`. In subagent mode, the architect presents its design in the output for post-hoc review.
+> **Note:** Plan approval (agent pauses for lead review) only works in Agent Teams mode via `permissionMode: plan`. In subagent mode, the architect presents its design in the output for post-hoc review. Spec-drafters (Path B) do NOT use plan approval — they follow the architect's partition briefing directly.
 
 ### Quality Gate #2
 

package/knowzcode/claude_code_execution.md

@@ -146,7 +146,8 @@ Use mailbox messaging for coordination between teammates:
 | From | To | When |
 |------|-----|------|
 | scout | all | Initial context/vault findings (broadcast) |
-| analyst | architect | Scope clarifications, NodeID overlap with existing specs |
+| scanner | all | Codebase scan findings — affected files, test patterns (broadcast) |
+| analyst | architect | `[PRELIMINARY]` NodeID findings during Stage 0 (max 3 DMs), scope clarifications, NodeID overlap with existing specs |
 | architect | analyst | Scope adjustments needed |
 | architect | builder | Design guidance and spec intent responses |
 | builder | analyst | Affected files and dependency questions |
@@ -217,10 +218,13 @@ Agents must NOT create new tasks for work already assigned to them via task ID.
 | context-scout-specs | Stage 0 | After Gate #2 | Spec context lookups |
 | context-scout-workgroups | Stage 0 | After Gate #2 | WorkGroup history lookups |
 | context-scout-backlog | Stage 0 | After Gate #2 | Tracker/log/architecture lookups |
+| scanner-direct | Stage 0 (conditional) | After Stage 1 (analyst done) | Source code scanning — broadcasts affected files and code paths |
+| scanner-tests | Stage 0 (conditional) | After Stage 1 (analyst done) | Test discovery — broadcasts test patterns and coverage shape |
 | knowz-scout | Stage 0 | After Phase 3 capture | Vault queries (read-only) throughout workflow |
 | knowz-scribe | Stage 0 | After Phase 3 capture | Vault writes — receives capture messages, handles all `create_knowledge` calls |
 | analyst | Stage 0 | Early Stage 2 | Scope questions from builders |
-| architect | Stage 0 (pre-load) | After Gate #3 | Spec clarifications + design guidance for builders throughout Stage 2 |
+| architect | Stage 0 (pre-load + speculative research) | After Gate #3 | Pre-load → speculative research on `[PRELIMINARY]` NodeIDs → spec drafting (+ parallel coordination for 3+ NodeIDs) → design guidance for builders |
+| spec-drafter(s) | Stage 1 (Path B, 3+ NodeIDs) | After architect consistency review | Draft specs for assigned NodeID partition |
 | builder(s) | Stage 2 | After Gate #3 | Implementation + gap fixes (persistent through gap loop) |
 | reviewer(s) | Stage 2 (1 per builder partition) | After Gate #3 | Incremental audit per partition (persistent through gap loop) |
 | security-officer | Stage 0 (Group C) | After Gate #3 | Threat modeling + vulnerability scanning (officer — can block gates) |
@@ -237,8 +241,8 @@ All tasks in a workflow use `addBlockedBy` to express the dependency chain:
 
 ### Task Graph Patterns
 
-- Stage 0 tasks: scout + knowz-scribe + analysis tasks (no deps)
-- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate)
+- Stage 0 tasks: scout + scanner + knowz-scribe + analysis tasks (no deps)
+- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate). Path B (3+ NodeIDs): spec-drafter tasks + architect consistency review task
 - Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
 - Stage 3 tasks: finalization (blocked by audit approval)
 
@@ -252,6 +256,8 @@ Team sizing defaults are configurable via `knowzcode/knowzcode_orchestration.md`
 | `scout_mode` | full | `--no-scouts` | full (3 scouts), minimal (1 scout), none (lead reads context) |
 | `default_specialists` | [] | `--specialists`, `--no-specialists` | Project-level specialist defaults |
 | `mcp_agents_enabled` | true | `--no-mcp` | Toggle vault agents (knowz-scout, knowz-scribe) |
+| `codebase_scanner_enabled` | true | `--no-scanners` | Toggle codebase scanner agents (scanner-direct, scanner-tests) |
+| `parallel_spec_threshold` | 3 | `--no-parallel-specs` | NodeID count threshold for parallel spec drafting (Path B) |
 
 Precedence: hardcoded defaults → orchestration config → per-invocation flags.
 
@@ -284,11 +290,22 @@ During Stage 2, the architect persists as a read-only consultative resource:
 - Lead notifies architect when builders are spawned — architect sends intro message to each builder
 - Shut down with builders and reviewers after Gate #3
 
-#### Discovery Pre-loading
-During Stage 0, the architect pre-loads context in parallel with analysis:
-- Architect reads architecture docs, existing specs, project config
-- When Gate #1 is approved, architect already has context → specs drafted faster
-- If Gate #1 rejected, architect context is still useful for the revised analysis cycle
+#### Discovery Pre-loading + Speculative Research
+During Stage 0, the architect pre-loads context and conducts speculative research in parallel with analysis:
+- **Pre-load phase**: Architect reads architecture docs, existing specs, project config (3-5 turns)
+- **Speculative research phase**: After pre-load, architect receives `[PRELIMINARY]` NodeID messages from the analyst (max 3). For each, it reads affected files, checks spec consolidation, and analyzes interface patterns — all read-only, no spec writing
+- When Gate #1 is approved, architect already has context + deep research on flagged NodeIDs → specs drafted ~80% faster
+- If Gate #1 rejected, architect context and research are still useful for the revised analysis cycle
+- If no `[PRELIMINARY]` messages arrive (simple 1-NodeID change), architect finishes standard pre-load and waits
+
+#### Parallel Spec Drafting (Path B — 3+ NodeIDs)
+When the approved Change Set contains 3+ NodeIDs (configurable via `PARALLEL_SPEC_THRESHOLD`), spec drafting is parallelized:
+- Architect proposes NodeID partitions (1-2 per partition, max 3 partitions)
+- Lead spawns spec-drafter agents (using `architect` agent definition) for each partition
+- Each drafter receives: its NodeIDs, architect's speculative research findings, cross-NodeID constraints
+- After all drafters complete, architect runs a consistency review: cross-spec alignment, naming, VERIFY coverage
+- Spec-drafters shut down after consistency review, before Gate #2
+- For 1-2 NodeIDs (Path A), architect drafts all specs alone (current behavior, zero overhead)
 
 #### Specialist Agents (Group C — opt-in via `--specialists`)
 
@@ -296,11 +313,12 @@ When specialists are enabled, three additional agents spawn at Stage 0 alongside
 
 ```
 Group A (always):           3 context-scouts + analyst + architect       (5 agents)
+Group A (if scanners):      + scanner-direct + scanner-tests            (+2 agents)
 Group B (if MCP):           knowz-scout + knowz-scribe                  (2 agents)
 Group C (if --specialists): security-officer + test-advisor + project-advisor  (3 agents)
 ```
 
-Max Stage 0 concurrent: 5-10 agents depending on orchestration config (scouts, MCP agents, specialists). Scouts shut down after Gate #2, so Stage 2 peak is manageable.
+Max Stage 0 concurrent: 5-12 agents depending on orchestration config (scouts, scanners, MCP agents, specialists). Scouts shut down after Gate #2, scanners shut down after Stage 1, so Stage 2 peak is manageable.
 
 ##### Officer vs Advisor Authority
 

package/knowzcode/platform_adapters.md

@@ -54,10 +54,22 @@ 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.
 
+### 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.
+
+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
+
+For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
+
 ## WorkGroup Files
 - Created in `knowzcode/workgroups/` (gitignored)
 - Every todo must start with `KnowzCode:` prefix
@@ -130,6 +142,10 @@ 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.
+
 ## Quick Fix (Micro-Fix)
 For single-file, <50 line, no-ripple-effect changes:
 1. Implement the fix
@@ -242,6 +258,10 @@ 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.
+
 ## 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 +329,10 @@ 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`
+
+## 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.
 ```
 
 ---
@@ -397,11 +421,15 @@ 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.
 
+### 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.
+
 ## Copilot Coding Agent
 
 When the Copilot Coding Agent works on GitHub issues for this repository:
@@ -973,6 +1001,10 @@ 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.
+
 ## 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.3",
   "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.3",
   "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.3",
   "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.3",
   "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.3",
   "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.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": [
     {

package/skills/install-knowzcode.json

@@ -1,6 +1,6 @@
 {
   "name": "install-knowzcode",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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.3",
   "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.3",
   "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.3",
   "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.3",
   "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.3",
   "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.3",
   "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.3",
   "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.3",
   "description": "Validates that KnowzCode installation completed successfully with required directories and files",
 
   "parameters": [],