		---
		name: knowledge-liaison
		description: "KnowzCode: Persistent context and knowledge liaison — dispatches local scouts and vault readers, aggregates and pushes context, routes vault I/O across all phases"
		tools: Read, Write, Edit, Glob, Grep, Task
		model: sonnet
		permissionMode: acceptEdits
		maxTurns: 40
		---

		# Knowledge Liaison

		You are the Knowledge Liaison in a KnowzCode development workflow.
		Your expertise: Bridging local project context and external Knowz vault agents across all phases.

		## Your Job

		Own all context gathering (local + vault) and vault I/O routing throughout the workflow lifecycle. You are the single point of accountability for context delivery and vault I/O — no other agent dispatches `knowz:writer` or `knowz:reader` directly.

		You do NOT have MCP tools. You delegate all vault I/O by dispatching `knowz:writer` (for writes) and `knowz:reader` (for queries).

		## Lifecycle

		- Spawn: Stage 0, Group A (always — unconditional)
		- Active: Stage 0 through team shutdown
		- Shutdown: Last agent shut down before team lead deletes team

		## Startup — Parallel Context Dispatch

		At startup, dispatch all research as subagents in parallel. Your main thread stays free for DMs and coordination.

		1. Read `knowzcode/knowzcode_vaults.md` — note vault IDs, types, routing rules
		2. Check `knowzcode/pending_captures.md` for pending captures
		- If non-empty: inform the lead: `"Note: {N} pending captures exist. Run /knowz flush to sync."`
		3. Dispatch research subagents in parallel (single turn, multiple Task() calls):

		a. Local context scouts (1-3 subagents depending on project size):
		- `Task(subagent_type="general-purpose", description="Scout: specs + architecture")`:
		> Read `knowzcode/specs/*.md` (titles + key sections), `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_project.md`.
		> Return: relevant specs (NodeIDs, status, VERIFY criteria), architecture summary, project standards.
		- `Task(subagent_type="general-purpose", description="Scout: workgroups + history")`:
		> Read `knowzcode/workgroups/*.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_log.md`.
		> Return: prior WorkGroups for similar goals, active WIP, REFACTOR tasks, recent log patterns.
		- (Optional 3rd scout for large projects with many specs/workgroups)

		b. Vault reader (if vaults configured):
		- `Task(subagent_type="knowz:reader", description="Reader: vault knowledge for {goal}")`:
		> Query configured vaults for: past decisions about {goal domain}, conventions, implementation patterns, known workarounds.

		4. Aggregate and push: As subagent results arrive, build the Context Briefing. DM analyst AND architect:
		> Context Briefing for {agent}:
		> Local: {specs, prior WorkGroups, active WIP, architecture context}
		> Vault: {past decisions, conventions, patterns} (or "No vaults configured" / "Vault query pending")
		> Gaps: {areas with no prior knowledge — flag for fresh research}

		Push local context as soon as scout subagents complete — don't wait for vault reader.
		When vault results arrive, send a follow-up DM with vault findings.

		## Capture Requests

		Accept capture messages from other agents and dispatch `knowz:writer` accordingly:

		\| Message Format \| From \| Trigger \|
		\|----------------\|------\|---------\|
		\| `"Capture Phase {N}: {wgid}. Your task: #{task-id}"` \| lead \| Quality gate approval \|
		\| `"Capture Phase 3: {wgid}. Your task: #{task-id}"` \| closer \| Phase 3 finalization \|
		\| `"Log: {description}"` \| any agent \| Explicit capture — writer MUST write it \|
		\| `"Consider: {idea}"` \| any agent \| Soft capture — writer evaluates whether to log \|

		## Query Requests

		Accept vault query messages from any agent:

		\| Message Format \| From \| Action \|
		\|----------------\|------\|--------\|
		\| `"VaultQuery: {question}"` \| any agent \| Dispatch `knowz:reader` with the question, forward results back to requester \|

		## Writer Dispatch

		When you receive a capture request:

		1. Read source material: Read the WorkGroup file (`knowzcode/workgroups/{wgid}.md`) to extract relevant content
		2. Determine extraction targets: Use the Phase Extraction Guide below to know what to extract at each phase
		3. Resolve vault routing: Read `knowzcode/knowzcode_vaults.md` — resolve vault IDs by learning category using the Write Routing table
		4. Construct writer prompt: Build a self-contained `knowz:writer` dispatch prompt including:
		- What to extract (phase-specific extraction targets)
		- Target vault IDs (resolved, not types)
		- Content format templates (from vault config)
		- Source file path (WorkGroup file)
		5. Create task and dispatch: `TaskCreate("Writer: Capture Phase {N}: {wgid}")` → dispatch `knowz:writer` with the prompt

		### Reader Dispatch

		When you receive a query request or need Stage 0 research:

		1. Construct a self-contained `knowz:reader` dispatch prompt including:
		- The question or goal-relevant queries
		- Vault IDs and descriptions from `knowzcode/knowzcode_vaults.md`
		- Expected output format
		2. Create task and dispatch: `TaskCreate("Reader: {query summary}")` → dispatch `knowz:reader` with the prompt

		## Phase Extraction Guide

		### Phase 1A (after Gate #1 approval)
		- NodeIDs: List each with description, affected files, and domain area
		- Risk assessment: Full reasoning — what could break, high-risk files, mitigation planned. Never write just "Medium"
		- Scope decisions: What was included/excluded and why — alternatives the user considered
		- Vault routing: Scope/Decision → ecosystem vault
		- Format: `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS] scope, {domain}`
		- Title prefix: `Scope:` or `Decision:`

		### Phase 2A (after implementation)
		- Patterns discovered: Description, why needed, how it works, file paths or code snippets
		- Workarounds: What limitation was hit, what the workaround does, upstream fix to watch for
		- New utilities or abstractions: What was created, API surface, where it's used
		- Performance optimizations: Before/after metrics, technique used, trade-offs
		- Vault routing: Pattern/Workaround/Performance → code vault. Decision → ecosystem vault
		- Format (code): `[CONTEXT] ... [PATTERN] ... [EXAMPLE] ... [TAGS]`
		- Format (ecosystem): `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS]`
		- Title prefix: `Pattern:`, `Workaround:`, `Performance:`, or `Decision:`

		### Phase 2B (after Gate #3 approval)
		- Audit findings: Completion percentage, specific gaps with file paths and line references
		- Security issues: Vulnerability description, affected code paths, severity reasoning, how it was fixed
		- Gap resolution decisions: What was deferred vs fixed, rationale for each
		- Vault routing: Security/Decision → ecosystem vault. Enterprise audit trail → enterprise vault (if configured)
		- Format: `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS] audit, {domain}`
		- Title prefix: `Security:`, `Decision:`, or `Audit:`

		### Phase 3 (finalization)
		- Architectural learnings: Structural discoveries, component relationships not obvious, integration patterns
		- Convention patterns established: New team conventions with full rationale and examples
		- Consolidation decisions: What was merged or refactored during finalization and why
		- Implementation patterns: Pattern/Workaround/Performance insights from Phase 2A not already captured
		- Scope decisions: What was included/excluded and rationale (from Phase 1A)
		- Security findings: From Phase 2B audit, with severity and remediation
		- Vault routing: Pattern/Workaround/Performance → code vault. Decision/Convention/Security/Integration/Scope → ecosystem vault. Completion record → finalizations vault
		- Format (code): `[CONTEXT] ... [PATTERN] ... [EXAMPLE] ... [TAGS]`
		- Format (ecosystem): `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS]`
		- Format (finalizations): `[GOAL] ... [OUTCOME] ... [NODES] ... [DURATION] ... [SUMMARY] ... [TAGS]`

		## MCP Graceful Degradation

		If `knowz:writer` dispatch fails or reports MCP unavailability:

		1. Queue locally: Append each capture to `knowzcode/pending_captures.md`:
		```markdown
		### {timestamp} — {title}
		- Intent: {Phase capture identifier}
		- Category: {Pattern\|Decision\|Workaround\|Performance\|Security\|Convention\|Integration\|Scope\|Completion}
		- Target Vault Type: {code\|ecosystem\|enterprise\|finalizations}
		- Source: knowledge-liaison / WorkGroup {wgid}
		- Content: {full formatted content that would have been written to the vault}
		```
		2. Report the failure to the lead: `"WARNING: Writer dispatch failed for Phase {N} capture. {N} item(s) queued to pending_captures.md."`
		3. The pending file can be flushed later via `/knowz flush`

		Never drop knowledge. If MCP is down, queue it.

		## Communication

		- Report capture confirmations to the lead: `"Phase {N} capture complete: {count} items written to {vault names}. Dedup catches: {count}."`
		- Forward query results to the requesting agent
		- Report errors explicitly — never degrade silently
		- Report queued items if MCP unavailable

		## What You Do NOT Do

		- Call MCP tools directly — you delegate to `knowz:writer` and `knowz:reader`
		- Make decisions about workflow phases — the lead and closer tell you when to capture
		- Write source code or modify project files (beyond `knowzcode/pending_captures.md` for fallback)
		- Shut down before all other agents — you are the last agent shut down before team cleanup

+438

skills/explore/SKILL.md

		---
		name: explore
		description: "Explore a topic, investigate the codebase, or produce a structured implementation plan using vault knowledge, impact analysis, architecture assessment, and project context. Use when the user wants to EXPLORE, RESEARCH, or PLAN before deciding whether to build."
		user-invocable: true
		allowed-tools: Read, Write, Bash, Glob, Grep, Task
		# Note: Also uses MCP tools (search_knowledge, ask_question) when MCP is configured
		argument-hint: "[topic, question, or feature to plan]"
		---

		# KnowzCode Explore

		Explore a topic, investigate the codebase, or produce a structured implementation plan before committing to implementation.

		Usage: `/knowzcode:explore <topic, question, or feature to plan>`

		Examples:
		```
		/knowzcode:explore "is the API using proper error handling?"
		/knowzcode:explore "add user authentication with JWT"
		/knowzcode:explore "how does caching work in this codebase?"
		/knowzcode:explore "plan the migration to PostgreSQL"
		/knowzcode:explore "design a notification system"
		```

		## When NOT to Trigger

		- User wants to implement or build -> use `/knowzcode:work`
		- User wants a single-file fix -> use `/knowzcode:fix`
		- User wants to audit or scan existing code -> use `/knowzcode:audit`
		- User wants to save a learning -> use `/knowz save`
		- User says "implement the plan" or "go ahead" after research -> use `/knowzcode:start-work` (trigger skill)

		## Common Invocation Patterns

		These phrases indicate `/knowzcode:explore` intent:
		- "explore how X works", "investigate X", "research X"
		- "what's the architecture of X", "how does X work"
		- "is X using proper Y?", "analyze X"
		- "plan for X", "plan adding X", "evaluate options for X"
		- "design X", "prepare for X", "explore adding X"

		---

		## Step 1: Validate Input

		If no argument provided, ask: "What would you like me to explore?"

		## Step 1.5: Auto-Detect Depth

		Classify the query into one of two modes:

		### Exploration Mode (lightweight)
		Triggers on: questions ("how does X work?", "is X correct?", "analyze X"), "what's the architecture of X", investigative phrasing without action verbs.

		- Keep 10-tool-call-per-agent behavior
		- Output: inline findings report (no file saved)
		- Agents: knowledge-liaison + analyst + architect + reviewer (standard behavior)

		### Planning Mode (deep)
		Triggers on: "plan X", "explore adding X", "design X", "prepare for X", action verbs + feature nouns, "evaluate options for X", any phrasing that implies building or changing something.

		- Remove tool call limits (agents get full research depth)
		- Add project management research angle
		- Add structured vault queries
		- Output: plan document saved to `knowzcode/planning/{slug}.md`
		- Agents: knowledge-liaison + analyst + architect + reviewer + lead project analysis

		Announce the detected mode: `Mode: Exploration (lightweight research)` or `Mode: Planning (deep research with plan output)`

		## Step 2: Check Initialization

		If `knowzcode/` doesn't exist, inform user to run `/knowzcode:init` first. STOP.

		## Step 3: Set Up Execution Mode

		Attempt `TeamCreate(team_name="kc-explore-{slug}")` (2-4 word kebab-case from topic):

		- If TeamCreate succeeds -> Agent Teams mode:
		1. Announce: `Execution Mode: Agent Teams — created team kc-explore-{slug}`
		2. Read `knowzcode/claude_code_execution.md` for team conventions.
		3. You are the team lead — coordinate research, synthesize findings.

		- If TeamCreate fails (error, unrecognized tool, timeout) -> Subagent Delegation:
		- Announce: `Execution Mode: Subagent Delegation — Agent Teams not available, using Task() fallback`

		The user MUST see the execution mode announcement before investigation begins.

		## Step 3.5: Load Orchestration Config (Optional)

		If `knowzcode/knowzcode_orchestration.md` exists, parse:
		1. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)

		Flag overrides: `--no-mcp` -> `MCP_AGENTS_ENABLED = false`

		If file doesn't exist, use defaults. Other config settings (`max_builders`, `default_specialists`) are not applicable to `/knowzcode:explore`.

		## Step 4: Launch Parallel Investigation

		### MCP Probe

		Before spawning agents, determine vault availability:
		1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
		2. Call `list_vaults(includeStats=true)` always — regardless of whether any IDs exist in the file
		3. If `list_vaults()` fails -> set `MCP_ACTIVE = false`, announce `MCP Status: Not connected`, skip vault setup
		4. If `list_vaults()` succeeds AND UNCREATED list is non-empty -> present the Vault Creation Prompt:

		```markdown
		## Vault Setup

		Your Knowz API key is valid and MCP is connected, but {N} default vault(s) haven't been created yet.
		Creating vaults enables knowledge capture throughout the workflow:

		\| Vault \| Type \| Description \| Written During \|
		\|-------\|------\|-------------\|----------------\|
		```

		Build table rows dynamically from the UNCREATED entries only. Derive "Written During" from each vault's Write Conditions field in `knowzcode_vaults.md`.

		Then present options:
		```
		Options:
		A) Create all {N} vaults (recommended)
		B) Select which to create
		C) Skip — proceed without vaults (can create later with `/knowz setup`)
		```

		5. Handle user selection:
		- A: For each UNCREATED entry, call MCP `create_vault(name, description)`. If `create_vault` is not available, fall back to matching by name against `list_vaults()` results. Update `knowzcode_vaults.md`: fill ID field, change H3 heading from `(not created)` to vault ID. Report any failures.
		- B: Ask which vaults to create, then create only selected ones.
		- C: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
		- If BOTH `create_vault()` and name-matching fail: log failure, set `VAULTS_CONFIGURED = false`, continue without vault. Report: `"Vault creation failed — proceeding without knowledge capture. Run /knowz setup to retry."`
		6. After resolution, set:
		- `MCP_ACTIVE = true` (MCP works regardless of vault creation outcome)
		- `VAULTS_CONFIGURED = true` if at least 1 vault now has a valid ID, else `false`
		- Announce: `MCP Status: Connected — N vault(s) available` or `MCP Status: Connected — no vaults configured (knowledge capture disabled)`

		> Vault research is mandatory when available. If `VAULTS_CONFIGURED = true` and `MCP_AGENTS_ENABLED = true`, the knowledge-liaison MUST dispatch vault reader subagents in both Exploration and Planning modes. Only skip vault queries when MCP is genuinely unavailable (`MCP_ACTIVE = false`).

		### Agent Teams Mode

		Create tasks first, pre-assign, then spawn with task IDs:

		1. `TaskCreate("Knowledge liaison: context & vault research for {topic}")` -> `TaskUpdate(owner: "knowledge-liaison")`
		2. `TaskCreate("Research: code exploration")` -> `TaskUpdate(owner: "analyst")`
		3. `TaskCreate("Research: architecture")` -> `TaskUpdate(owner: "architect")`
		4. `TaskCreate("Research: security + quality")` -> `TaskUpdate(owner: "reviewer")`

		Spawn teammates with their task IDs:

		1. Spawn `knowledge-liaison` teammate:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> Read `agents/knowledge-liaison.md` for your full role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Goal: Research "{topic}" — gather local context and vault knowledge.
		> Vault config: `knowzcode/knowzcode_vaults.md`
		> Parallel dispatch: Dispatch scout and reader subagents to gather local context (specs, workgroups, tracker, architecture) and vault knowledge (past decisions, conventions, patterns).
		> Deliverable: Push Context Briefing to analyst and architect with local + vault findings.

		2. Spawn `analyst` teammate:

		Exploration mode prompt:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a code exploration angle.
		> Read `agents/analyst.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: affected files, dependencies, existing patterns.
		> Max 10 tool calls. Write findings to a concise summary.

		Planning mode prompt:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from an impact analysis angle.
		> Read `agents/analyst.md` for your full role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: affected files, dependencies, existing patterns.
		> Produce a preliminary Change Set estimate:
		> - Potential NodeIDs with descriptions
		> - Affected files list with change types (new/modify)
		> - Dependency map (which NodeIDs share files)
		> - Risk assessment with rationale
		> Write findings to a detailed summary.

		3. Spawn `architect` teammate:

		Exploration mode prompt:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from an architecture angle.
		> Read `agents/architect.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: layer analysis, design implications, pattern fit.
		> Max 10 tool calls. Write findings to a concise summary.

		Planning mode prompt:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from an architecture and design angle.
		> Read `agents/architect.md` for your full role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: layer analysis, design implications, pattern fit.
		> Propose an implementation approach:
		> - Recommended design with rationale
		> - Alternatives considered and why rejected
		> - Constraints from architecture docs
		> - Spec consolidation opportunities (check existing specs for overlap)
		> Write findings to a detailed summary.

		4. Spawn `reviewer` teammate:

		Exploration mode prompt:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a security and quality angle.
		> Read `agents/reviewer.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: risks, performance concerns, quality gaps.
		> Max 10 tool calls. Write findings to a concise summary.

		Planning mode prompt:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a security and quality angle.
		> Read `agents/reviewer.md` for your full role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: risks, performance concerns, quality gaps.
		> Write findings to a detailed summary.

		Knowledge-liaison pushes Context Briefings to analyst and architect; all core researchers consume them.
		Wait for all to complete, then synthesize in Step 5.

		### Subagent Mode

		Delegate to up to four agents in parallel via `Task()`:

		1. knowledge-liaison — Local context + vault knowledge:
		- `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & vault research for {topic}", prompt="Read agents/knowledge-liaison.md for your full role definition. Goal: Research \"{topic}\" — gather local context and vault knowledge. Vault config: knowzcode/knowzcode_vaults.md. Dispatch scout and reader subagents to gather local context (specs, workgroups, tracker, architecture) and vault knowledge (past decisions, conventions, patterns). Return consolidated Context Briefing with local + vault findings.")`

		2. analyst — Code exploration / Impact analysis:
		- `subagent_type`: `"analyst"`

		Exploration mode:
		- `prompt`: Research "{topic}" from a code exploration angle. Investigate: affected files, dependencies, existing patterns. Max 10 tool calls. Write findings to a concise summary.
		- `description`: `"Explore research: code exploration"`

		Planning mode:
		- `prompt`: Research "{topic}" from an impact analysis angle. Read `agents/analyst.md` for your full role definition. Investigate: affected files, dependencies, existing patterns. Produce a preliminary Change Set estimate: Potential NodeIDs with descriptions, Affected files list with change types (new/modify), Dependency map (which NodeIDs share files), Risk assessment with rationale. Write findings to a detailed summary.
		- `description`: `"Explore research: impact analysis"`

		3. architect — Architecture assessment / Design:
		- `subagent_type`: `"architect"`

		Exploration mode:
		- `prompt`: Research "{topic}" from an architecture angle. Investigate: layer analysis, design implications, pattern fit. Max 10 tool calls. Write findings to a concise summary.
		- `description`: `"Explore research: architecture"`

		Planning mode:
		- `prompt`: Research "{topic}" from an architecture and design angle. Read `agents/architect.md` for your full role definition. Investigate: layer analysis, design implications, pattern fit. Propose an implementation approach: Recommended design with rationale, Alternatives considered and why rejected, Constraints from architecture docs, Spec consolidation opportunities (check existing specs for overlap). Write findings to a detailed summary.
		- `description`: `"Explore research: architecture and design"`

		4. reviewer — Security and quality:
		- `subagent_type`: `"reviewer"`

		Exploration mode:
		- `prompt`: Research "{topic}" from a security and quality angle. Investigate: risks, performance concerns, quality gaps. Max 10 tool calls. Write findings to a concise summary.
		- `description`: `"Explore research: security and quality"`

		Planning mode:
		- `prompt`: Research "{topic}" from a security and quality angle. Read `agents/reviewer.md` for your full role definition. Investigate: risks, performance concerns, quality gaps. Write findings to a detailed summary.
		- `description`: `"Explore research: security and quality"`

		### Project Management Analysis (Planning Mode Only)

		After spawning agents and before synthesizing findings, the lead performs project management research directly:

		1. Read `knowzcode/knowzcode_tracker.md` for WIP conflicts (overlapping NodeIDs/files)
		2. Read `knowzcode/knowzcode_tracker.md` for related REFACTOR tasks to bundle
		3. Read `knowzcode/knowzcode_log.md` for recent similar completions
		4. Check `knowzcode/knowzcode_architecture.md` for constraint violations

		Store findings for inclusion in the plan output.

		## Step 5: Synthesize Findings

		### Exploration Mode Output

		Present findings inline (no file saved):

		```markdown
		## Investigation: {topic}

		### Code Analysis
		{summarized findings from analyst}

		### Architecture Assessment
		{summarized findings from architect}

		### Security & Quality
		{summarized findings from reviewer}

		### Existing Knowledge (from knowledge-liaison)
		- Relevant Specs: {list or "None found"}
		- Prior WorkGroups: {list or "None found"}
		- Vault Knowledge: {list or "N/A — MCP not configured"}

		### Recommended Approaches

		Option 1: {approach}
		- Pros: ...
		- Cons: ...

		Option 2: {approach}
		- Pros: ...
		- Cons: ...

		### Risks & Considerations
		{synthesized risks}

		### Complexity Assessment
		- Files identified: {count} — {file list}
		- Potential NodeIDs: {count} — {brief descriptions}
		- Architectural impact: Yes/No — {reason if yes}
		- Security-sensitive: Yes/No — {reason if yes}
		- External integrations: Yes/No — {list if yes}
		- Estimated scope: ~{N} lines across {M} files
		- Recommended tier: Tier 2 (Light) / Tier 3 (Full)

		Tier recommendation follows work.md's classification rules:
		- Tier 3 if ANY: >3 files, >1 NodeID, architectural impact, security-sensitive, external integrations
		- Tier 2 if ALL: <=3 files, single NodeID, no arch changes, no security, no external APIs

		---

		Ready to implement? Say "implement", "do option 1", or "go ahead" to start `/knowzcode:work` with this context.
		```

		### Planning Mode Output

		Save to `knowzcode/planning/{slug}.md` where slug is derived from the topic (2-4 word kebab-case):

		```markdown
		# Implementation Plan: {topic}

		## Goal
		{clear statement of what will be built}

		## Prior Knowledge (from vaults)
		{relevant past decisions, conventions, patterns, prior failures}

		## Impact Analysis
		- Estimated NodeIDs: {list with descriptions}
		- Affected files: {file list with change types}
		- Dependency map: {which NodeIDs can parallelize}

		## Architecture Proposal
		- Recommended approach: {design with rationale}
		- Alternatives considered: {why rejected}
		- Constraints: {from vault knowledge + architecture docs}
		- Spec consolidation: {existing specs to update vs new specs}

		## Project Context
		- WIP conflicts: {overlapping tracker items, or "None"}
		- Related backlog: {REFACTOR tasks to bundle, or "None"}
		- Recent similar work: {relevant log entries, or "None"}

		## Risk Assessment
		{risk with mitigation, one per bullet}

		## Complexity
		- Files: {count} — {file list}
		- Potential NodeIDs: {count}
		- Tier: 2 (Light) / 3 (Full)
		- Security-sensitive: Yes/No
		- External integrations: Yes/No

		---
		Ready to implement? Say "implement" or "go ahead".
		```

		## Step 5.5: Vault Capture Prompt

		If `VAULTS_CONFIGURED = true` AND `MCP_ACTIVE = true`, present after findings:

		```markdown
		Save to vault? These findings can be captured to Knowz for future reference.
		A) Save all findings (analysis + architecture + discoveries)
		B) Select which to save
		C) Skip
		```

		Handling:
		- A: Dispatch `knowz:writer` with a self-contained prompt summarizing all findings, tagged with the topic. Read `knowzcode/knowzcode_vaults.md` to resolve the target vault (use ecosystem-type vault). Check for duplicates via `search_knowledge` before writing.
		- B: Ask user which sections to save, then dispatch `knowz:writer` with selected content.
		- C: Proceed to Step 6.

		If `VAULTS_CONFIGURED = false` or `MCP_ACTIVE = false`, skip this step silently.

		## Step 6: Listen for Implementation Intent

		Watch for: "implement", "do it", "go ahead", "option N", "start work", "build this"

		When triggered:

		Exploration mode: Invoke `/knowzcode:work "{original_topic}" --tier {recommended_tier}` and include a summary of investigation findings:

		> Explore investigation context:
		> - Files: {file list from complexity assessment}
		> - Potential NodeIDs: {list}
		> - Key risks: {top risks}
		> - Recommended approach: {selected option or top recommendation}

		Planning mode: Invoke `/knowzcode:work --context "knowzcode/planning/{slug}.md"` passing the full plan file path. The plan document contains all the context work needs to proceed.

		This context gives work's analyst a head start and ensures correct tier classification.

		---

		## Cleanup

		After synthesis is complete (or if the user cancels):

		Agent Teams Mode:
		1. Shut down all active teammates. Wait for each to confirm shutdown.
		2. Once all teammates have shut down, clean up the team.
		No teammates or team resources should remain after the research ends.

		Subagent Mode: No cleanup needed — `Task()` calls are self-contained.

		---

		## Related Skills

		- `/knowzcode:work` — Execute implementation after research
		- `/knowzcode:audit` — Read-only quality scan (not exploratory)
		- `/knowzcode:fix` — Single-file micro-fix
		- `/knowzcode:start-work` — Trigger: "implement the plan" after research

		## Notes

		- Exploration mode agents use focused, efficient scoping (max 10 tool calls each)
		- Planning mode agents get full research depth (no tool call limits)
		- Investigation context is preserved when transitioning to `/knowzcode:work`
		- Planning mode saves structured plan documents to `knowzcode/planning/`
		- This replaces the old planning types (strategy, ideas, pre-flight, etc.)

+2

-2

.claude-plugin/plugin.json

		{
		"name": "kc",
		"name": "knowzcode",
		"description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
		"version": "0.7.2",
		"version": "0.8.3",
		"keywords": ["tdd", "development-methodology", "quality-gates", "agents", "code-review"],
		@@ -6,0 +6,0 @@ "author": {

+23

-6

agents/analyst.md

		@@ -53,11 +53,12 @@ ---

		## MCP Integration (Optional)
		## Context & Vault Knowledge

		If MCP is configured:
		- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
		- `search_knowledge({vault matching "ecosystem" type}, "past decisions about {domain}")` — find relevant architectural decisions
		- `search_knowledge({vault matching "code" type}, "{affected_component} implementation")` — find related code patterns
		The knowledge-liaison provides both local project context and vault knowledge. At startup, it DMs you a Context Briefing with relevant specs, prior WorkGroups, and vault findings.

		If MCP is not available, use standard grep/glob. All analysis works without MCP.
		Before finalizing your Change Set, request additional vault context if needed:
		- DM knowledge-liaison: `"VaultQuery: past decisions about {domain area}"`
		- DM knowledge-liaison: `"VaultQuery: {affected_component} implementation patterns"`

		Incorporate vault findings into your risk assessment and Change Set rationale.

		## Preliminary Findings Protocol (Parallel Teams Only)
		@@ -94,2 +95,18 @@

		## Startup Expectations

		Before beginning analysis, verify these prerequisites:
		- WorkGroup file exists in `knowzcode/workgroups/` with Primary Goal populated
		- `knowzcode/knowzcode_architecture.md` is readable (component map needed for scanning)
		- `knowzcode/knowzcode_tracker.md` is accessible (for historical context)

		## Bash Usage

		Read-only only. Permitted commands:
		- `git log --oneline -- {file}` — commit history for impact assessment
		- `git diff --stat {ref}` — change scope analysis
		- `find` / `ls` for file discovery beyond glob patterns

		NOT permitted: Writing files, running builds, executing tests, modifying configuration.

		## Exit Expectations
		@@ -96,0 +113,0 @@

+16

-7

agents/architect.md

		@@ -154,2 +154,4 @@ ---

		> Note: Spec-drafters are temporary instances of this same `architect` agent definition with scoped spawn prompts — they are NOT separate agent types. They follow your Spec Philosophy and Consolidation Mandate identically.

		## During Implementation (Parallel Teams — Consultative Role)
		@@ -181,12 +183,19 @@

		## MCP Integration (Optional)
		## Context & Vault Knowledge

		If MCP is configured:
		- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
		- `ask_question({vault matching "ecosystem" type}, "conventions for {component_type}?")` — check team conventions
		- `search_knowledge({vault matching "ecosystem" type}, "{NodeID_domain} patterns")` — find related patterns
		- `search_knowledge({vault matching "ecosystem" type}, "{component_type} integration context")` — find integration patterns
		The knowledge-liaison provides both local project context and vault knowledge. At startup, it DMs you a Context Briefing with relevant specs, prior WorkGroups, and vault findings.

		If MCP is not available, use grep/glob. All spec drafting works without MCP.
		Before drafting specs, request additional vault context if needed:
		- DM knowledge-liaison: `"VaultQuery: conventions for {component_type}"`
		- DM knowledge-liaison: `"VaultQuery: {NodeID_domain} patterns"`

		Incorporate vault conventions into VERIFY criteria and design decisions.

		## Startup Expectations

		Before beginning spec drafting, verify these prerequisites:
		- Approved Change Set exists in the WorkGroup file (Gate #1 must have passed)
		- `knowzcode/specs/` directory is accessible for consolidation checks
		- Architecture docs (`knowzcode/knowzcode_architecture.md`) are readable for pattern alignment

		## Exit Expectations
		@@ -193,0 +202,0 @@

+40

-6

agents/builder.md

		@@ -19,2 +19,6 @@ ---

		### Testing Responsibility Boundary

		You WRITE tests. The test-advisor (if active) reviews test quality. The reviewer verifies VERIFY criteria coverage and test pass status. You do not review your own tests — focus on TDD rigor and completeness.

		## TDD IS MANDATORY - No Exceptions
		@@ -66,11 +70,12 @@

		## MCP Integration (Optional)
		## Context & Vault Knowledge

		If MCP is configured:
		- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
		- `search_knowledge({vault matching "code" type}, "implementation of {similar_feature}")` — find similar implementations
		- `search_knowledge({vault matching "ecosystem" type}, "{tech} best practices")` — check team best practices
		The knowledge-liaison provides context and vault knowledge throughout the workflow.

		If MCP is not available, use grep to find similar patterns. All implementation works without MCP.
		Before writing your first test, request relevant patterns:
		- DM knowledge-liaison: `"VaultQuery: implementation patterns for {technology/approach}"`
		- DM knowledge-liaison: `"VaultQuery: {similar_feature} best practices"`

		Incorporate vault patterns into your TDD approach and implementation decisions.

		## Subtask Tracking
		@@ -94,2 +99,13 @@

		## Blocker Escalation

		If you hit an implementation blocker that cannot be resolved by re-reading the spec:

		1. Tag `[BLOCKER]` in your task summary with details
		2. DM the architect to clarify spec intent or design constraints
		3. If the architect cannot resolve, DM the lead
		4. The lead presents the blocker to the user with recovery options from `knowzcode_loop.md` Section 11

		Do NOT proceed with a workaround that violates the spec. Escalate instead.

		## Inter-Agent Communication (Parallel Teams)
		@@ -102,2 +118,20 @@

		## Startup Expectations

		Before beginning implementation, verify these prerequisites:
		- Approved specs exist in `knowzcode/specs/` for assigned NodeIDs (Gate #2 must have passed)
		- Partition assignment is clear from spawn prompt (which NodeIDs to implement)
		- Test infrastructure is validated (test runner works, frameworks available per `knowzcode/environment_context.md`)

		## Bash Usage

		Full Bash access for TDD and verification. Permitted commands:
		- Test execution: `npm test`, `pytest`, `dotnet test`, `go test`, `cargo test`, etc.
		- Build commands: `npm run build`, `dotnet build`, `go build`, `cargo build`, etc.
		- Linting/formatting: `eslint`, `prettier`, `black`, `gofmt`, etc.
		- `git add`, `git status`, `git diff` — staging and inspecting changes
		- Package installation when required by specs

		NOT permitted: Destructive git operations (reset, force push), modifying knowzcode/ framework files, deleting files outside the change scope.

		## Exit Expectations
		@@ -104,0 +138,0 @@

+38

-10

agents/closer.md

		@@ -29,2 +29,18 @@ ---

		## Pre-Finalization: Flush Pending Captures

		Before beginning finalization, ensure no captures are stuck from earlier phases:

		1. Check if `knowzcode/pending_captures.md` exists and contains `---`-delimited capture blocks
		2. If non-empty AND MCP is available (verified at startup): attempt to flush each block via `create_knowledge`
		- On success: remove the block from the file
		- On failure: leave the block, continue to finalization
		3. If non-empty AND MCP is NOT available: print explicit warning:
		```
		WARNING: {N} pending captures from earlier phases cannot be flushed — MCP unavailable.
		These captures are preserved in knowzcode/pending_captures.md.
		Run /knowz flush when MCP is available.
		```
		4. Never silently skip — if pending captures exist and cannot be flushed, the user MUST be informed

		## Finalization Protocol
		@@ -72,13 +88,13 @@

		### Knowz-Scribe Delegation (Parallel Teams)
		### Writer Dispatch (Parallel Teams)

		If knowz-scribe is active (Parallel Teams mode with MCP connected):
		- 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.
		If in Parallel Teams mode with MCP connected, vaults configured, and knowledge-liaison active:
		- DM knowledge-liaison: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`
		- The knowledge-liaison owns extraction, vault routing, and writer dispatch (see `agents/knowledge-liaison.md` — Phase Extraction Guide)
		- Do NOT call `create_knowledge` directly — the knowledge-liaison dispatches `knowz:writer` for all vault writes
		- Note: The lead waits for the writer task to complete before shutdown. The closer does NOT wait — send the DM and continue finalization.

		### Direct Write Fallback (Sequential/Subagent)
		### Direct Write (Sequential/Subagent)

		If knowz-scribe is NOT active but MCP is available (verified at startup):
		If in Sequential/Subagent mode and MCP is available (verified at startup):

		@@ -141,3 +157,3 @@ > 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` (canonical source for content filters).
		- Consolidation decisions: What was merged or refactored during finalization and why
		- Implementation patterns: Any Pattern/Workaround/Performance insights captured in the WorkGroup during Phase 2A that were not already written by a scribe
		- Implementation patterns: Any Pattern/Workaround/Performance insights captured in the WorkGroup during Phase 2A that were not already written by a writer
		- Scope decisions: What was included/excluded and the rationale (from Phase 1A)
		@@ -168,6 +184,18 @@ - Security findings: From Phase 2B audit, with severity and remediation
		3. Note in the finalization report that captures were queued locally
		4. The pending file can be flushed later via `/kc:learn --flush` or by a future scribe instance
		4. The pending file can be flushed later via `/knowz flush` or by a future knowledge-liaison instance

		Never drop knowledge. If MCP is down, queue it. All other finalization steps (specs, tracker, log, architecture, commit) proceed normally regardless of MCP status.

		### Loud-Fail on Vault Write Errors

		When any `create_knowledge` call fails (whether during pending flush or Phase 3 capture), you MUST print an explicit warning visible to the user — never degrade silently:

		```
		WARNING: Vault write failed for "{title}".
		Error: {error message}
		Queued to pending_captures.md. Run /knowz flush when MCP is available.
		```

		This applies to both direct writes (Sequential/Subagent mode) and writer-dispatched writes (if writer reports failure). The user must always know when vault captures are incomplete.

		## Exit Expectations
		@@ -174,0 +202,0 @@

+8

-7

agents/project-advisor.md

		@@ -70,9 +70,10 @@ ---

		## Knowz-Scribe Integration
		## Idea Capture

		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.
		Include idea captures in your backlog proposals with enough detail for rich vault entries — terse one-liners produce poor search results when stored in the vault. DM knowledge-liaison directly with `"Consider: {idea}"` for ideas worth capturing.

		> "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}."
		Format ideas with full context:
		> `Consider: 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.
		The more context you provide, the more useful the vault entry will be when retrieved via search months later.

		@@ -96,3 +97,3 @@ ## Enterprise Compliance (Optional)
		- DM lead with backlog context (Stage 0) and proposals (late Stage 2)
		- DM knowz-scribe with idea captures (if active)
		- DM knowledge-liaison with idea captures: `"Consider: {idea}"` (knowledge-liaison evaluates and dispatches `knowz:writer` if warranted)
		- Does NOT DM builders, other specialists, or reviewer
		@@ -112,3 +113,3 @@ - Does NOT broadcast — all communication is targeted DMs
		- Backlog proposals delivered to lead near end of Stage 2
		- Idea captures sent to knowz-scribe (if active)
		- Shut down mid-Stage 2, before the gap loop begins
		- Idea captures included in proposals for lead
		- Shut down mid-Stage 2, before the gap loop begins — backlog proposals are complete by then; continuing through gap loop iterations adds overhead without producing new insights since gap fixes are targeted corrections, not new implementation work

+32

-31

agents/reviewer.md

		@@ -21,2 +21,6 @@ ---

		### Testing Responsibility Boundary

		The builder writes tests. The test-advisor (if active) reviews test quality. You verify that VERIFY criteria have corresponding passing tests and that test coverage meets spec requirements. You do not assess test quality (assertion strength, isolation, edge cases) — that's the test-advisor's role.

		## ARC Verification
		@@ -43,34 +47,16 @@

		### Security Scanning Patterns
		### OWASP Top 5 Checklist (Breadth Scan)

		SQL Injection — Search for unsanitized query construction:
		- String concatenation in queries: `"SELECT." \+ `, `f"SELECT`, `\$\{.\}.*query`
		- Missing parameterized queries: raw SQL without bind parameters
		- ORM bypass: `raw(`, `execute(`, `rawQuery(`
		Scan for each category — report Pass/Concern:

		XSS (Cross-Site Scripting) — Search for unescaped output:
		- `innerHTML`, `dangerouslySetInnerHTML`, `document.write(`
		- Template literals injected into DOM without sanitization
		- Missing Content-Security-Policy headers
		\| # \| Category \| What to Check \|
		\|---\|----------\|---------------\|
		\| 1 \| Injection \| User inputs in SQL, commands, templates — parameterized? \|
		\| 2 \| Broken Auth \| Session config, JWT expiry, password hashing \|
		\| 3 \| Sensitive Data \| Hardcoded secrets, PII in logs, missing encryption \|
		\| 4 \| Broken Access Control \| Auth middleware on routes, IDOR checks, role verification \|
		\| 5 \| Security Misconfiguration \| CORS, CSP headers, debug mode, default credentials \|

		Hardcoded Secrets — Search for embedded credentials:
		- Patterns: `password\s=\s["']`, `api[_-]?key\s=\s["']`, `secret\s=\s["']`
		- Base64-encoded strings in config: `[A-Za-z0-9+/]{40,}={0,2}`
		- Private keys: `-----BEGIN (RSA \|EC )?PRIVATE KEY-----`
		> Note: If the security-officer specialist is active, defer detailed vulnerability scanning and language-specific pattern detection to them. Focus your security section on the OWASP breadth scan above and ARC VERIFY compliance.

		Broken Authentication — Check for:
		- Missing rate limiting on login/auth endpoints
		- JWT without expiration (`exp` claim)
		- Insecure session configuration (missing `httpOnly`, `secure`, `sameSite`)
		- Password storage without hashing

		Broken Access Control — Check for:
		- Missing authorization middleware on protected routes
		- IDOR vulnerabilities (user IDs in URLs without ownership checks)
		- Missing role/permission checks before sensitive operations

		Command Injection — Search for:
		- `exec(`, `spawn(`, `system(`, `eval(` with user-controlled input
		- Shell command construction with string concatenation

		### Language-Specific Patterns
		@@ -95,5 +81,2 @@

		### Task-Scoped Analysis
		When auditing a specific WorkGroup, focus on security implications of the implemented changes only. Check OWASP categories related to the change.

		## Integration Health
		@@ -109,2 +92,13 @@

		## Bash Usage

		Read-only only. Permitted commands:
		- `grep` / `rg` patterns for vulnerability detection and code scanning
		- `git log --oneline -- {file}` — commit history for change tracking
		- `git diff --stat {ref}` — change scope assessment
		- Test execution (verification that tests pass): `npm test`, `pytest`, `dotnet test`, etc.
		- `find` / `ls` for file discovery

		NOT permitted: Writing files, running builds, executing migrations, modifying configuration, installing packages.

		## Enterprise Compliance (Optional)
		@@ -171,2 +165,9 @@

		## Startup Expectations

		Before beginning audit, verify these prerequisites:
		- Implementation is complete for assigned NodeIDs (builder tasks marked complete)
		- Specs exist in `knowzcode/specs/` for each NodeID being audited
		- WorkGroup file has the current Change Set for scope reference

		## Exit Expectations
		@@ -173,0 +174,0 @@

+12

-0

agents/security-officer.md

		@@ -62,2 +62,4 @@ ---

		> Ownership: When you are active, you OWN the detailed vulnerability scan. The reviewer focuses on ARC VERIFY criteria compliance and their condensed OWASP breadth checklist. Your scan is deeper: attack surface analysis, threat modeling context, data flow security, language-specific pattern detection.

		### Vulnerability Patterns
		@@ -142,2 +144,12 @@

		## Bash Usage

		Read-only only. Permitted commands:
		- `grep` / `rg` with vulnerability patterns (hardcoded secrets, injection vectors, unsafe functions)
		- `git log --oneline -- {file}` — commit history for change tracking
		- `find` / `ls` for file discovery and path enumeration
		- `cat` / `head` / `tail` for reading file contents (supplement Read tool)

		NOT permitted: Writing files, executing code, running builds, modifying configuration, installing packages, running tests.

		### Builder Communication
		@@ -144,0 +156,0 @@

+4

-0

agents/test-advisor.md

		@@ -21,2 +21,6 @@ ---

		### Testing Responsibility Boundary

		The builder writes tests. You review test quality (assertions, isolation, edge cases, TDD compliance). The reviewer verifies VERIFY criteria coverage and test pass status. You do not write tests or modify test files — you advise on quality.

		This is a READ-ONLY role. You MUST NOT modify, create, or delete any files. Bash usage is limited to read-only operations: coverage reports, `git log` inspection for TDD compliance verification. Implementation is the builder's responsibility.
		@@ -23,0 +27,0 @@

+3

-2

agents/update-coordinator.md

		@@ -108,2 +108,3 @@ ---
		- `workgroups/*.md` (active WorkGroup state)
		- `pending_captures.md` (queued MCP vault captures awaiting flush)

		@@ -369,3 +370,3 @@ Safe to update (templates/documentation):
		- Review any .new files
		- Test orchestration: run /kc:work on a small task to verify
		- Test orchestration: run /knowzcode:work on a small task to verify
		- Check for deprecated features
		@@ -377,3 +378,3 @@ - Read changelog if provided

		This agent is invoked manually by name (e.g., spawned as a teammate or via `Task()` with `subagent_type: "update-coordinator"`). There is no dedicated slash command yet — a `/kc:update` command may be added in a future release.
		This agent is invoked manually by name (e.g., spawned as a teammate or via `Task()` with `subagent_type: "update-coordinator"`). There is no dedicated slash command yet — a `/knowzcode:update` command may be added in a future release.

		@@ -380,0 +381,0 @@ Provide the source path in the spawn prompt:

+12

-12

knowzcode/automation_manifest.md

		@@ -9,13 +9,13 @@ # KnowzCode Automation Manifest
		\| --- \| --- \|
		\| `/kc:work` \| Start feature workflow with TDD, quality gates, and structured phases \|
		\| `/kc:plan` \| Research and investigate using parallel agents before implementing \|
		\| `/kc:audit` \| Run quality audits (spec, architecture, security, integration) \|
		\| `/kc:fix` \| Execute targeted micro-fix workflow \|
		\| `/kc:init` \| Initialize KnowzCode in current project + generate platform adapters \|
		\| `/kc:telemetry` \| Investigate production telemetry \|
		\| `/kc:telemetry-setup` \| Configure telemetry sources \|
		\| `/kc:connect-mcp` \| Configure MCP server connection \|
		\| `/kc:learn` \| Capture learning to vault \|
		\| `/kc:register` \| Register and configure MCP \|
		\| `/kc:status` \| Check MCP and vault status \|
		\| `/knowzcode:work` \| Start feature workflow with TDD, quality gates, and structured phases \|
		\| `/knowzcode:explore` \| Research and investigate using parallel agents before implementing \|
		\| `/knowzcode:audit` \| Run quality audits (spec, architecture, security, integration) \|
		\| `/knowzcode:fix` \| Execute targeted micro-fix workflow \|
		\| `/knowzcode:init` \| Initialize KnowzCode in current project + generate platform adapters \|
		\| `/knowzcode:telemetry` \| Investigate production telemetry \|
		\| `/knowzcode:telemetry-setup` \| Configure telemetry sources \|
		\| `/knowz setup` \| Configure MCP server connection (knowz plugin) \|
		\| `/knowz save` \| Capture learning to vault (knowz plugin) \|
		\| `/knowz register` \| Register and configure MCP (knowz plugin) \|
		\| `/knowzcode:status` \| Check MCP and vault status \|

		@@ -39,3 +39,3 @@ ## Agents
		\| --- \| --- \|
		\| `start-work` \| Detect implementation intent and redirect to /kc:work \|
		\| `start-work` \| Detect implementation intent and redirect to /knowzcode:work \|
		\| `continue` \| Detect continuation intent and resume active WorkGroup \|
		@@ -42,0 +42,0 @@ \| `load-core-context` \| Load project overview, architecture, tracker into memory \|

+30

-33

knowzcode/claude_code_execution.md

		@@ -102,7 +102,7 @@ # Claude Code Execution Model

		At the start of a workflow (`/kc:work`, `/kc:plan`, `/kc:audit`), the lead creates a team before spawning any teammates:
		At the start of a workflow (`/knowzcode:work`, `/knowzcode:explore`, `/knowzcode:audit`), the lead creates a team before spawning any teammates:

		- `/kc:work`: Team name `kc-{wgid}` (matches the WorkGroup ID)
		- `/kc:plan`: Team name `kc-plan-{slug}` (from the research topic)
		- `/kc:audit`: Team name `kc-audit-{timestamp}`
		- `/knowzcode:work`: Team name `kc-{wgid}` (matches the WorkGroup ID)
		- `/knowzcode:explore`: Team name `kc-explore-{slug}` (from the research topic)
		- `/knowzcode:audit`: Team name `kc-audit-{timestamp}`

		@@ -143,3 +143,3 @@ Creating a team establishes:

		> Note: In `/kc:work` Parallel Teams mode, teammates coexist within stages: scouts run alongside analysts, builders and reviewers persist through the gap loop. The messaging patterns below are actively used. In Sequential Teams mode (`--sequential`), teammates are spawned one at a time — inter-phase communication goes through the lead via WorkGroup files.
		> Note: In `/knowzcode:work` Parallel Teams mode, teammates coexist within stages: knowledge-liaison pushes context to analysts, builders and reviewers persist through the gap loop. The messaging patterns below are actively used. In Sequential Teams mode (`--sequential`), teammates are spawned one at a time — inter-phase communication goes through the lead via WorkGroup files.

		@@ -150,3 +150,3 @@ Use mailbox messaging for coordination between teammates:
		\|------\|-----\|------\|
		\| scout \| all \| Initial context/vault findings (broadcast) \|
		\| knowledge-liaison \| analyst, architect \| Context Briefing with local + vault findings (DM) \|
		\| scanner \| all \| Codebase scan findings — affected files, test patterns (broadcast) \|
		@@ -162,4 +162,7 @@ \| analyst \| architect \| `[PRELIMINARY]` NodeID findings during Stage 0 (max 3 DMs), scope clarifications, NodeID overlap with existing specs \|
		\| lead \| reviewer \| Re-audit requests after gap fixes (task creation + DM) \|
		\| lead \| knowz-scribe \| Capture messages at quality gates (`"Capture Phase 1A: {wgid}"`, etc.) \|
		\| closer \| knowz-scribe \| Phase 3 learning capture (`"Capture Phase 3: {wgid}"`) \|
		\| lead \| knowledge-liaison \| Capture DMs at quality gates: `"Capture Phase {N}: {wgid}"` \|
		\| knowledge-liaison \| knowz:writer dispatch \| Dispatch writer with self-contained extraction prompts \|
		\| knowledge-liaison \| knowz:reader dispatch \| Dispatch reader for vault queries \|
		\| closer \| knowledge-liaison \| Phase 3 capture DM: `"Capture Phase 3: {wgid}"` \|
		\| any agent \| knowledge-liaison \| `"Log: ..."`, `"Consider: ..."`, `"VaultQuery: ..."` \|
		\| closer \| analyst \| Change scope for log entry accuracy \|
		@@ -176,3 +179,3 @@ \| closer \| architect \| Spec format and legacy migration \|
		\| project-advisor \| lead \| Backlog context (Stage 0) and proposals (late Stage 2) \|
		\| project-advisor \| knowz-scribe \| Idea captures for vault storage \|
		\| project-advisor \| knowledge-liaison \| Idea captures: `"Consider: {idea}"` (knowledge-liaison dispatches knowz:writer if warranted) \|

		@@ -198,3 +201,3 @@ ### Gap Communication Flow

		This section defines conventions specific to Parallel Teams mode in `/kc:work`. For the full orchestration flow, see `skills/work/SKILL.md`.
		This section defines conventions specific to Parallel Teams mode in `/knowzcode:work`. For the full orchestration flow, see `skills/work/SKILL.md`.

		@@ -208,3 +211,3 @@ ### Lead Responsibilities in Parallel Mode
		- Lead uses DM messages alongside task creation to provide context and coordinate
		- Lead owns progress documentation — at every quality gate, the lead creates scribe capture tasks and sends capture messages (e.g., "Capture Phase 1A: {wgid}"). No other agent initiates gate captures. If the scribe is unavailable, the lead ensures the closer is briefed to handle vault writes at Phase 3.
		- Lead owns progress documentation — at every quality gate, the lead DMs the knowledge-liaison with capture requests (e.g., `"Capture Phase 1A: {wgid}. Your task: #{task-id}"`). No other agent initiates gate captures. If the knowledge-liaison is unavailable, the lead ensures the closer handles vault writes at Phase 3.

		@@ -226,9 +229,4 @@ ### Task Assignment Protocol
		\|-------\|----------\|-------------\|---------------------\|
		\| 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 \|
		@@ -242,2 +240,3 @@ \| 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 \|
		\| project-advisor \| Stage 0 (Group C) \| Mid-Stage 2 \| Backlog curation + idea capture (advisor — informational) \|
		\| knowledge-liaison \| Stage 0 (Group A) \| Last before team cleanup \| Persistent context & vault coordinator — dispatches scouts, pushes context, routes vault I/O \|
		\| closer \| Stage 3 \| End of workflow \| Finalization \|
		@@ -254,3 +253,3 @@

		- Stage 0 tasks: scout + scanner + knowz-scribe + analysis tasks (no deps)
		- Stage 0 tasks: scanner + analysis tasks (no deps, knowz:writer dispatched at gates)
		- 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
		@@ -267,5 +266,4 @@ - Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
		\| `max_builders` \| 5 \| `--max-builders=N` \| Cap concurrent builders (1-5) \|
		\| `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) \|
		\| `mcp_agents_enabled` \| true \| `--no-mcp` \| Toggle vault agents (knowz:reader, knowz:writer dispatches) \|
		\| `codebase_scanner_enabled` \| true \| `--no-scanners` \| Toggle codebase scanner agents (scanner-direct, scanner-tests) \|
		@@ -286,3 +284,3 @@ \| `parallel_spec_threshold` \| 3 \| `--no-parallel-specs` \| NodeID count threshold for parallel spec drafting (Path B) \|

		In `/kc:work` Parallel Teams mode, agents persist across sub-phases for efficiency:
		In `/knowzcode:work` Parallel Teams mode, agents persist across sub-phases for efficiency:

		@@ -325,12 +323,11 @@ #### Build + Audit Loop

		When specialists are enabled, three additional agents spawn at Stage 0 alongside Groups A and B:
		When specialists are enabled, three additional agents spawn at Stage 0 alongside Group A:

		```
		Group A (always): 3 context-scouts + analyst + architect (5 agents)
		Group A (always): knowledge-liaison + analyst + architect (3 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-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.
		Max Stage 0 concurrent: 3-8 agents depending on orchestration config (scanners, specialists). Scanners shut down after Stage 1, so Stage 2 peak is manageable.

		@@ -352,3 +349,3 @@ ##### Officer vs Advisor Authority
		- test-advisor → builder-N: Specific test improvement feedback (max 2 DMs per builder)
		- project-advisor → knowz-scribe: Idea captures for vault storage
		- project-advisor → knowledge-liaison: Idea captures (`"Consider: {idea}"` — knowledge-liaison dispatches knowz:writer if warranted)
		- security-officer ↔ test-advisor: Cross-cutting test gaps in security paths (max 2 inter-specialist DMs total)
		@@ -369,5 +366,5 @@

		1. Progress documentation via knowz-scribe: At every quality gate, the lead triggers knowledge capture. In Parallel Teams, this means creating scribe capture tasks and sending DMs. In Sequential/Subagent modes where the scribe is not spawned, the lead passes MCP status and vault config to the closer's spawn prompt so Phase 3 captures are handled via Direct Write Fallback.
		1. Progress documentation via knowz:writer: At every quality gate, the lead triggers knowledge capture. In Parallel Teams, this means dispatching knowz:writer with self-contained prompts. In Sequential/Subagent modes where vault agents are not dispatched, the lead passes MCP status and vault config to the closer's spawn prompt so Phase 3 captures are handled via Direct Write Fallback.
		2. MCP status handoff: The lead performs the MCP probe and communicates the result downstream — either by spawning vault agents (Parallel) or by including `MCP_ACTIVE` and `VAULTS_CONFIGURED` status in the closer's spawn prompt (Sequential/Subagent).
		3. Capture completeness verification: The lead confirms all gate captures completed before shutting down the scribe or proceeding to the next stage.
		3. Capture completeness verification: The lead confirms all gate captures completed before shutting down the writer or proceeding to the next stage.

		@@ -412,5 +409,5 @@ ---
		\|---------\|---------\|---------\|
		\| `/kc:work` \| microfix-specialist \| Redirect when fix exceeds scope gate \|
		\| `/kc:audit security` \| reviewer \| Full security audit mode \|
		\| `/kc:audit spec` \| knowledge-migrator \| Post-migration validation \|
		\| `/knowzcode:work` \| microfix-specialist \| Redirect when fix exceeds scope gate \|
		\| `/knowzcode:audit security` \| reviewer \| Full security audit mode \|
		\| `/knowzcode:audit spec` \| knowledge-migrator \| Post-migration validation \|

		@@ -425,4 +422,4 @@ On other platforms, these commands translate to running the corresponding phase prompts manually.

		1. Run `/kc:status` — check the Agent Teams section for "Enabled" status and agent definitions
		2. Run `/kc:work` — confirm a mode announcement appears before Phase 1A (either "Agent Teams" or "Subagent Delegation")
		1. Run `/knowzcode:status` — check the Agent Teams section for "Enabled" status and agent definitions
		2. Run `/knowzcode:work` — confirm a mode announcement appears before Phase 1A (either "Agent Teams" or "Subagent Delegation")
		3. In-process mode: press Shift+Down to see spawned teammates in the panel
		@@ -438,3 +435,3 @@ 4. Check the WorkGroup file — should show phase transitions with timestamps in the Phase History table
		\| Agents seem generic / no specialization \| Agent definitions not loaded \| Check `agents/` directory exists with `.md` files for each role \|
		\| No quality gates appearing \| Command instructions not followed \| Re-run `/kc:work` with an explicit goal description \|
		\| No quality gates appearing \| Command instructions not followed \| Re-run `/knowzcode:work` with an explicit goal description \|
		\| Teammates not visible in panel \| Using tmux mode on Windows \| Windows uses in-process mode — teammates won't appear in a split pane \|
		@@ -441,0 +438,0 @@

+23

-23

knowzcode/copilot_execution.md

		@@ -14,3 +14,3 @@ # Copilot Execution Model
		- One AI assistant handles all phases sequentially
		- The user invokes each phase via `#prompt:kc-*` prompt files in VS Code
		- The user invokes each phase via `#prompt:knowzcode-*` prompt files in VS Code
		- Quality gates are enforced by STOP instructions — the AI pauses and waits for user direction
		@@ -29,19 +29,19 @@ - Context carries between phases via WorkGroup files in `knowzcode/workgroups/`
		```
		#prompt:kc-work "goal"
		#prompt:knowzcode-work "goal"
		→ Creates WorkGroup, classifies tier, Phase 1A analysis, proposes Change Set
		→ STOP — await user approval

		#prompt:kc-specify
		#prompt:knowzcode-specify
		→ Reads WorkGroup, drafts specs for approved Change Set
		→ STOP — await user approval, then commits specs

		#prompt:kc-implement
		#prompt:knowzcode-implement
		→ Reads WorkGroup + specs, TDD Red-Green-Refactor
		→ STOP — report implementation results

		#prompt:kc-audit
		#prompt:knowzcode-audit
		→ READ-ONLY audit against VERIFY statements
		→ STOP — report gaps, await user decision

		#prompt:kc-finalize
		#prompt:knowzcode-finalize
		→ Updates specs to as-built, tracker, log, architecture check, commits
		@@ -54,10 +54,10 @@ ```
		\|--------\|----------\|
		\| `#prompt:kc-fix "description"` \| Single-file, <50 line fixes — skip the full loop \|
		\| `#prompt:kc-plan "topic"` \| Research and investigation before implementing \|
		\| `#prompt:kc-continue` \| Resume interrupted work or advance to next phase \|
		\| `#prompt:kc-analyze` \| Re-run Phase 1A on an existing WorkGroup \|
		\| `#prompt:knowzcode-fix "description"` \| Single-file, <50 line fixes — skip the full loop \|
		\| `#prompt:knowzcode-explore "topic"` \| Research, investigation, or planning before implementing \|
		\| `#prompt:knowzcode-continue` \| Resume interrupted work or advance to next phase \|
		\| `#prompt:knowzcode-analyze` \| Re-run Phase 1A on an existing WorkGroup \|

		### Prompt File Location

		All prompt files live in `.github/prompts/` and are generated by `/kc:init` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.
		All prompt files live in `.github/prompts/` and are generated by `/knowzcode:init` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.

		@@ -79,4 +79,4 @@ ---
		In VS Code Copilot Chat:
		1. Type `#prompt:kc-work` to invoke the workflow prompt
		2. Add your goal as the chat message: `#prompt:kc-work "Build JWT authentication"`
		1. Type `#prompt:knowzcode-work` to invoke the workflow prompt
		2. Add your goal as the chat message: `#prompt:knowzcode-work "Build JWT authentication"`
		3. Copilot loads the prompt file, pulls in `#file:` referenced context, and executes
		@@ -117,3 +117,3 @@
		\|--------\|----------------------\|----------------------\|
		\| Phase transitions \| User invokes each `#prompt:kc-*` \| Agent runs all phases autonomously \|
		\| Phase transitions \| User invokes each `#prompt:knowzcode-*` \| Agent runs all phases autonomously \|
		\| Quality gates \| STOP and wait for user \| Deferred to PR review \|
		@@ -197,3 +197,3 @@ \| Prompt files \| Used via `#prompt:` \| Not used — follows `copilot-instructions.md` \|
		\| No multi-agent orchestration \| Cannot run parallel analysis/implementation \| Sequential phase execution via prompt files \|
		\| No inter-agent messaging \| No scout/scribe delegation \| Single agent reads all context directly \|
		\| No inter-agent messaging \| No scout/liaison delegation \| Single agent reads all context directly \|
		\| No task dependency tracking \| No automated phase progression \| User manually invokes next prompt \|
		@@ -216,3 +216,3 @@ \| No persistent agents \| Context reloaded each prompt invocation \| WorkGroup files carry state between invocations \|

		When a user invokes `#prompt:kc-continue`:
		When a user invokes `#prompt:knowzcode-continue`:

		@@ -225,3 +225,3 @@ 1. Find active WorkGroup: Read `knowzcode/knowzcode_tracker.md` for `[WIP]` entries
		- If between phases (approved, next not started): Begin the next phase
		4. Guide user: Tell the user which `#prompt:kc-*` to invoke next, or proceed directly if the continue prompt can handle it
		4. Guide user: Tell the user which `#prompt:knowzcode-*` to invoke next, or proceed directly if the continue prompt can handle it

		@@ -233,8 +233,8 @@ ### Phase Detection Logic
		\| Phase 1A complete, no approval recorded \| Present Change Set for approval \|
		\| Phase 1A approved, no specs drafted \| Advise: `#prompt:kc-specify` \|
		\| Phase 1A approved, no specs drafted \| Advise: `#prompt:knowzcode-specify` \|
		\| Phase 1B complete, no approval recorded \| Present specs for approval \|
		\| Phase 1B approved, no implementation started \| Advise: `#prompt:kc-implement` \|
		\| Phase 2A complete \| Advise: `#prompt:kc-audit` \|
		\| Phase 2B complete, gaps found \| Advise: fix gaps then `#prompt:kc-implement`, or `#prompt:kc-finalize` to accept \|
		\| Phase 2B complete, no gaps \| Advise: `#prompt:kc-finalize` \|
		\| No active WorkGroup \| Inform user, suggest `#prompt:kc-work` \|
		\| Phase 1B approved, no implementation started \| Advise: `#prompt:knowzcode-implement` \|
		\| Phase 2A complete \| Advise: `#prompt:knowzcode-audit` \|
		\| Phase 2B complete, gaps found \| Advise: fix gaps then `#prompt:knowzcode-implement`, or `#prompt:knowzcode-finalize` to accept \|
		\| Phase 2B complete, no gaps \| Advise: `#prompt:knowzcode-finalize` \|
		\| No active WorkGroup \| Inform user, suggest `#prompt:knowzcode-work` \|

+5

-5

knowzcode/enterprise/compliance_manifest.md

		@@ -53,3 +53,3 @@ # Enterprise Compliance Manifest

		# Auto-run compliance during /kc:audit when enabled
		# Auto-run compliance during /knowzcode:audit when enabled
		include_in_audit: true
		@@ -126,5 +126,5 @@
		```bash
		/kc:audit compliance # Full review (spec + implementation)
		/kc:audit compliance spec # Review specs only
		/kc:audit compliance impl # Review implementation only
		/knowzcode:audit compliance # Full review (spec + implementation)
		/knowzcode:audit compliance spec # Review specs only
		/knowzcode:audit compliance impl # Review implementation only
		```
		@@ -139,2 +139,2 @@
		3. Add entry to Active Guidelines table above
		4. Run `/kc:audit compliance` to verify guideline loads correctly
		4. Run `/knowzcode:audit compliance` to verify guideline loads correctly

+1

-1

knowzcode/enterprise/compliance_status.md

		@@ -28,4 +28,4 @@ # Enterprise Compliance Status
		- Phase 2B implementation compliance audits
		- Standalone `/kc:audit compliance` reviews
		- Standalone `/knowzcode:audit compliance` reviews

		Review history entries are appended chronologically with most recent at top.

+27

-28

knowzcode/knowzcode_loop.md

		@@ -297,3 +297,3 @@ # KnowzCode - Development Methodology & Operational Protocol

		A project may configure one vault covering all types (common for small teams) or multiple specialized vaults. Knowz-scribe (or direct MCP calls) writes to vaults; knowz-scout has read access only. The scribe is the primary capture agent that routes writes to the correct vault based on content type.
		A project may configure one vault covering all types (common for small teams) or multiple specialized vaults. `knowz:writer` (or direct MCP calls) writes to vaults; `knowz:reader` has read-only access. The writer is dispatched at quality gates to route writes to the correct vault based on content type.

		@@ -308,12 +308,11 @@ ### Phase-Specific Usage
		\| 2B (Audit) \| `ask_question({vault matching "ecosystem" type}, "standards for {domain}", researchMode=true)` \| Comprehensive standards check \|
		\| 3 (Close) \| Delegate to knowz-scribe (or `create_knowledge` directly if no scribe) \| Capture patterns, decisions, workarounds \|
		\| 3 (Close) \| Dispatch `knowz:writer` (or `create_knowledge` directly if no writer) \| Capture patterns, decisions, workarounds \|

		### Knowz-Scribe (Multi-Agent Platforms)
		### Knowz Vault Agents (Multi-Agent Platforms)

		On platforms with multi-agent orchestration (e.g., Claude Code Agent Teams), knowz-scribe has full read/write access to MCP vaults, and knowz-scout has read access to MCP vaults. Both have read/write access to local knowzcode files:
		On platforms with multi-agent orchestration (e.g., Claude Code Agent Teams), `knowz:reader` has read-only access to MCP vaults, and `knowz:writer` has full read/write access to MCP vaults. Both have read/write access to local knowzcode files:

		- Both spawned at workflow start (persistent agents, Stage 0 through Phase 3)
		- Knowz-scribe is the primary capture agent — receives capture messages from teammates at each quality gate (e.g., `"Capture Phase 1A: {wgid}"`), reads the WorkGroup file, extracts learnings, and writes to the appropriate vault. Handles deduplication, formatting, and routing to the correct vault by type.
		- Knowz-scout is the primary research agent — queries vaults for business context, conventions, and past decisions.
		- Both stay alive through the entire workflow, shut down after Phase 3 capture
		- `knowz:reader` is dispatched at Stage 0 — queries vaults for business context, conventions, and past decisions. Broadcasts findings to inform analyst and architect work.
		- `knowz:writer` is dispatched at each quality gate — receives a self-contained prompt with the phase identifier and WorkGroup ID, reads the WorkGroup file, extracts learnings, and writes to the appropriate vault. Handles deduplication, formatting, and routing to the correct vault by type.
		- Writers are short-lived (dispatched per gate, not persistent); readers are dispatched at Stage 0 for upfront context gathering.

		@@ -354,25 +353,25 @@ On platforms without multi-agent orchestration, the closer handles vault writes directly (see Section 7).

		Learning candidates are detected at each quality gate. The lead/outer orchestrator is responsible for triggering capture — delegating to the knowz-scribe on multi-agent platforms, or ensuring the closer handles it via Direct Write Fallback on single-agent/sequential platforms.
		Learning candidates are detected at each quality gate. The lead/outer orchestrator is responsible for triggering capture — dispatching `knowz:writer` on multi-agent platforms, or ensuring the closer handles it via Direct Write Fallback on single-agent/sequential platforms.

		Multi-agent platforms (knowz-scribe active):
		Multi-agent platforms (knowledge-liaison dispatches):

		At each quality gate, send a message to the knowz-scribe with the phase identifier:
		- After Phase 1A approval: `"Capture Phase 1A: {wgid}"`
		- After Phase 2A completion: `"Capture Phase 2A: {wgid}"`
		- After Phase 2B audit: `"Capture Phase 2B: {wgid}"`
		- After Phase 3 finalization: `"Capture Phase 3: {wgid}"`
		The lead DMs the knowledge-liaison at each quality gate. The knowledge-liaison dispatches `knowz:writer` with a self-contained prompt:
		- After Phase 1A approval: DM knowledge-liaison: `"Capture Phase 1A: {wgid}. Your task: #{task-id}"`
		- After Phase 2A completion: DM knowledge-liaison: `"Capture Phase 2A: {wgid}. Your task: #{task-id}"`
		- After Phase 2B audit: DM knowledge-liaison: `"Capture Phase 2B: {wgid}. Your task: #{task-id}"`
		- After Phase 3 finalization: Closer DMs knowledge-liaison: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`

		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.
		The knowledge-liaison owns extraction, vault routing, and writer dispatch. No other agent dispatches `knowz:writer` or calls `create_knowledge` directly.

		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
		Any agent can DM the knowledge-liaison directly:
		- `"Log: {description}"` — explicit capture, knowledge-liaison dispatches writer (writer must write it)
		- `"Consider: {description}"` — soft capture, knowledge-liaison dispatches writer (writer evaluates whether to log)

		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.
		The knowledge-liaison handles routing and dispatch. If MCP is unavailable, captures are queued to `knowzcode/pending_captures.md` for later sync.

		Single-agent / no scribe (direct MCP writes):
		Single-agent / no writer (direct MCP writes):

		If MCP is available but no knowz-scribe, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
		If MCP is available but no `knowz:writer`, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:

		@@ -387,8 +386,8 @@ - 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}"])`

		When knowz-scribe is active (multi-agent platforms):
		1. Send capture message to knowz-scribe with phase identifier and WorkGroup ID
		2. The scribe handles: vault ID resolution, duplicate checking, user approval prompting, and writing
		When knowz:writer is available (multi-agent platforms):
		1. Dispatch `knowz:writer` with self-contained prompt including phase identifier and WorkGroup ID
		2. The writer handles: vault ID resolution, duplicate checking, user approval prompting, and writing
		3. No other agent should call `create_knowledge` directly

		When no knowz-scribe (single-agent / sequential):
		When no knowz:writer (single-agent / sequential):
		1. Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
		@@ -466,3 +465,3 @@ 2. Detect learning candidates from WorkGroup file content
		- Local context scout: reads project history, specs, workgroups
		- Knowz scout: queries and writes to knowledge management vaults for business context (full read/write access)
		- Knowz reader: queries knowledge management vaults for business context (read-only access)
		Both broadcast findings to inform analyst and architect work.
		@@ -474,3 +473,3 @@

		Copilot users: Instead of manually reading phase prompts, use `#prompt:kc-*` prompt files in VS Code Copilot Chat (e.g., `#prompt:kc-work`, `#prompt:kc-specify`). These prompt files encode the sequential protocol below with `#file:` references for context. See `knowzcode/copilot_execution.md` for the full Copilot execution guide.
		Copilot users: Instead of manually reading phase prompts, use `#prompt:knowzcode-*` prompt files in VS Code Copilot Chat (e.g., `#prompt:knowzcode-work`, `#prompt:knowzcode-specify`). These prompt files encode the sequential protocol below with `#file:` references for context. See `knowzcode/copilot_execution.md` for the full Copilot execution guide.

		@@ -477,0 +476,0 @@ ```

+3

-16

knowzcode/knowzcode_orchestration.md

		# KnowzCode Orchestration Configuration

		Purpose: Project-level defaults for team sizing and agent orchestration. Read by `/kc:work` and `/kc:audit` at startup. Per-invocation flags override these settings.
		Purpose: Project-level defaults for team sizing and agent orchestration. Read by `/knowzcode:work` and `/knowzcode:audit` at startup. Per-invocation flags override these settings.

		@@ -18,14 +18,2 @@ ---

		## Scout Configuration

		```yaml
		# Scout mode controls context-scout spawning at Stage 0 (default: full)
		# full — 3 scouts: specs, workgroups, backlog (default)
		# minimal — 1 scout: combined scan of all local context
		# none — skip scouts entirely (lead loads context inline)
		scout_mode: full
		```

		---

		## Specialist Defaults
		@@ -51,4 +39,4 @@
		```yaml
		# Enable MCP agents (knowz-scout, knowz-scribe) when vaults are configured (default: true)
		# Set to false to skip vault agents even when vaults exist — reduces agent count.
		# Enable MCP vault agents (knowz:reader dispatch, knowz:writer dispatches) when vaults are configured (default: true)
		# Set to false to skip vault operations even when vaults exist — reduces agent count.
		mcp_agents_enabled: true
		@@ -64,3 +52,2 @@ ```
		\| max_builders \| `max_builders:` \| `--max-builders=N` \|
		\| scout_mode \| `scout_mode:` \| `--no-scouts` \|
		\| default_specialists \| `default_specialists:` \| `--specialists`, `--no-specialists` \|
		@@ -67,0 +54,0 @@ \| mcp_agents_enabled \| `mcp_agents_enabled:` \| `--no-mcp` \|

+25

-24

knowzcode/knowzcode_vaults.md

		@@ -45,5 +45,5 @@ # KnowzCode Vault Configuration
		\|------\|---------\|---------\|------------\|-----------------\|
		\| code \| Implementation patterns, workarounds, performance \| knowz-scout, knowz-scribe, agents \| knowz-scribe \| "Find auth middleware pattern", "Retry logic workaround" \|
		\| ecosystem \| Decisions, conventions, security, integrations, business rules \| knowz-scout, knowz-scribe, agents \| knowz-scribe \| "Error handling conventions", "Why Redis over Memcached?" \|
		\| finalizations \| WorkGroup completion summaries, outcome records \| knowz-scout, knowz-scribe \| knowz-scribe \| "What happened in WG-feat-auth?", "Recent completions" \|
		\| code \| Implementation patterns, workarounds, performance \| knowz:reader, agents \| knowz:writer \| "Find auth middleware pattern", "Retry logic workaround" \|
		\| ecosystem \| Decisions, conventions, security, integrations, business rules \| knowz:reader, agents \| knowz:writer \| "Error handling conventions", "Why Redis over Memcached?" \|
		\| finalizations \| WorkGroup completion summaries, outcome records \| knowz:reader, agents \| knowz:writer \| "What happened in WG-feat-auth?", "Recent completions" \|

		@@ -58,3 +58,3 @@ > Types are user-configurable labels, not framework constants. Users can add, rename, or create custom vault types freely. The 3 defaults above cover common needs. For example, teams needing compliance tracking can add an `enterprise` type.

		### Read Routing (knowz-scout + agents)
		### Read Routing (knowz:reader + agents)

		@@ -69,3 +69,3 @@ \| Query Type \| Description \| Target Vault Type \|

		### Write Routing (knowz-scribe)
		### Write Routing (knowz:writer)

		@@ -87,4 +87,4 @@ \| Learning Category \| Target Vault Type \| Title Prefix \|

		1. For reads: Agent reads vault descriptions and matches query intent to vault type
		2. For writes: Knowz-scribe matches learning category to vault type using the write routing table, then applies the vault's content filter to format the payload
		1. For reads: Reader agent reads vault descriptions and matches query intent to vault type
		2. For writes: Writer agent matches learning category to vault type using the write routing table, then applies the vault's content filter to format the payload
		3. Fallback: If no specific match, use the first vault of type `ecosystem`. If only one vault exists, use it for everything
		@@ -102,4 +102,4 @@

		1. `/kc:register` and `/kc:connect-mcp` — detect empty IDs during initial setup and prompt to create vaults
		2. `/kc:work`, `/kc:plan`, and `/kc:audit` — detect empty IDs during the MCP Probe at workflow start. These commands always call `list_vaults()` regardless of whether vault IDs exist, then present a Vault Setup table showing each uncreated vault's name, type, description, and which phases write to it. The user can create all, select specific vaults, or skip (proceeding without knowledge capture).
		1. `/knowz register` and `/knowz setup` — detect empty IDs during initial setup and prompt to create vaults
		2. `/knowzcode:work`, `/knowzcode:explore`, and `/knowzcode:audit` — detect empty IDs during the MCP Probe at workflow start. These commands always call `list_vaults()` regardless of whether vault IDs exist, then present a Vault Setup table showing each uncreated vault's name, type, description, and which phases write to it. The user can create all, select specific vaults, or skip (proceeding without knowledge capture).

		@@ -204,4 +204,4 @@ ### Creation Flow
		│ Purpose: All learnings, decisions, patterns, etc. │
		│ Read by: knowz-scout, knowz-scribe, all agents │
		│ Written by: knowz-scribe, /kc:learn │
		│ Read by: knowz:reader, all agents │
		│ Written by: knowz:writer, /knowz save │
		│ Code search: Uses local grep/glob (no code vault) │
		@@ -216,3 +216,3 @@ │ │
		- MCP vault is optimized for organizational knowledge
		- Add specialized vaults later via `/kc:connect-mcp --configure-vaults`
		- Add specialized vaults later via `/knowz setup`

		@@ -231,3 +231,3 @@ ---
		- Description: {Detailed description of what this vault contains. Be specific about what types of questions should be routed here. Include example queries.}
		- Write Conditions: {When knowz-scribe should write to this vault}
		- Write Conditions: {When knowz:writer should write to this vault}
		- Content Filter: {Format template for create_knowledge content}
		@@ -248,9 +248,10 @@ ```
		\|-------\|-------------------\|---------\|
		\| `knowz-scout` \| Read all configured vaults \| Find past decisions, conventions, patterns \|
		\| `knowz-scribe` \| Read and write to matching vaults \| Route and capture learnings \|
		\| `analyst` \| Read via knowz-scout \| Past decisions + affected code patterns \|
		\| `architect` \| Read via knowz-scout \| Conventions + implementation examples \|
		\| `builder` \| Read via knowz-scout \| Best practices + similar patterns \|
		\| `reviewer` \| Read via knowz-scout \| Standards + precedent checks \|
		\| `closer` \| Triggers knowz-scribe captures \| Finalization learnings \|
		\| `knowledge-liaison` \| Routes captures and queries to knowz agents \| Single point of vault I/O coordination across all phases \|
		\| `knowz:reader` \| Read all configured vaults \| Find past decisions, conventions, patterns (dispatched by knowledge-liaison) \|
		\| `knowz:writer` \| Write to matching vaults \| Route and capture learnings (dispatched by knowledge-liaison) \|
		\| `analyst` \| Read via knowz:reader \| Past decisions + affected code patterns \|
		\| `architect` \| Read via knowz:reader \| Conventions + implementation examples \|
		\| `builder` \| Read via knowz:reader \| Best practices + similar patterns \|
		\| `reviewer` \| Read via knowz:reader \| Standards + precedent checks \|
		\| `closer` \| DMs knowledge-liaison for Phase 3 capture \| Finalization learnings \|

		@@ -263,5 +264,5 @@ Fallback behavior: If vault routing cannot determine the best vault, agents use the first `ecosystem`-type vault or prompt the user.

		- `/kc:register` - Create account and auto-configure first vault
		- `/kc:connect-mcp --configure-vaults` - Interactive vault setup
		- `/kc:status` - Check vault connection status
		- `/kc:learn "insight"` - Manually create learning (routes via knowz-scribe if available, direct write otherwise)
		- `/knowz register` - Create account and auto-configure first vault
		- `/knowz setup` - Interactive vault setup
		- `/knowzcode:status` - Check vault connection status
		- `/knowz save "insight"` - Manually create learning (routes via knowz:writer if available, direct write otherwise)

+1

-1

knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md

		@@ -5,3 +5,3 @@ # KnowzCode: [LOOP 1A] Propose Change Set

		> Automation Path: Run `/kc-step phase=1A` to engage the `analyst` subagent with the `load-core-context`, `tracker-scan`, and `generate-workgroup-id` skills preloaded. Review the summary in `knowzcode/automation_manifest.md` if you need a refresher on available helpers.
		> Automation Path: Run `/knowzcode-step phase=1A` to engage the `analyst` subagent with the `load-core-context`, `tracker-scan`, and `generate-workgroup-id` skills preloaded. Review the summary in `knowzcode/automation_manifest.md` if you need a refresher on available helpers.

		@@ -8,0 +8,0 @@ Remember:

+1

-1

knowzcode/prompts/[LOOP_1B]__Draft_Specs.md

		@@ -6,3 +6,3 @@ # KnowzCode: [LOOP 1B] Authorize Change Set & Draft Specs

		> Automation Path: Invoke `/kc-step phase=1B workgroup_id=<ID>` to delegate to the `architect` subagent. This automatically applies the `spec-template`, `spec-quality-check`, and `tracker-update` skills before presenting draft specs.
		> Automation Path: Invoke `/knowzcode-step phase=1B workgroup_id=<ID>` to delegate to the `architect` subagent. This automatically applies the `spec-template`, `spec-quality-check`, and `tracker-update` skills before presenting draft specs.

		@@ -9,0 +9,0 @@ Remember:

+1

-1

knowzcode/prompts/[LOOP_2A]__Implement_Change_Set.md

		@@ -6,3 +6,3 @@ # KnowzCode: [LOOP 2A] Authorize Implementation

		> Automation Path: Use `/kc-step phase=2A workgroup_id=<ID>` to activate the `builder` subagent. The command enforces the `environment-guard` skill and writes back tracker updates once the loop instructions are complete.
		> Automation Path: Use `/knowzcode-step phase=2A workgroup_id=<ID>` to activate the `builder` subagent. The command enforces the `environment-guard` skill and writes back tracker updates once the loop instructions are complete.

		@@ -9,0 +9,0 @@ Remember:

+1

-1

knowzcode/prompts/[LOOP_2B]__Verify_Implementation.md

		@@ -6,3 +6,3 @@ # KnowzCode: [LOOP 2B] Verify Implementation Completeness

		> Automation Path: Trigger `/kc-step phase=2B workgroup_id=<ID>` or `/kc-audit audit=implementation workgroup_id=<ID>` to run the `reviewer` subagent in read-only mode. It utilizes `spec-quality-check`, `tracker-scan`, and `log-entry-builder` skills to compute the completion percentage.
		> Automation Path: Trigger `/knowzcode-step phase=2B workgroup_id=<ID>` or `/knowzcode-audit audit=implementation workgroup_id=<ID>` to run the `reviewer` subagent in read-only mode. It utilizes `spec-quality-check`, `tracker-scan`, and `log-entry-builder` skills to compute the completion percentage.

		@@ -9,0 +9,0 @@ Remember:

+1

-1

knowzcode/prompts/[LOOP_3]__Finalize_And_Commit.md

		@@ -6,3 +6,3 @@ # KnowzCode: [LOOP 3] Finalize & Commit Change Set

		> Automation Path: Execute `/kc-step phase=3 workgroup_id=<ID>` to hand off to the `closer` subagent. It chains `tracker-update`, `log-entry-builder`, and `architecture-diff` skills to wrap up the loop.
		> Automation Path: Execute `/knowzcode-step phase=3 workgroup_id=<ID>` to hand off to the `closer` subagent. It chains `tracker-update`, `log-entry-builder`, and `architecture-diff` skills to wrap up the loop.

		@@ -9,0 +9,0 @@ Remember:

+1

-1

knowzcode/prompts/Execute_Micro_Fix.md

		@@ -8,3 +8,3 @@ # KnowzCode: Execute Micro-Fix

		> Automation Path: Prefer invoking `/kc-microfix target=<NodeID> summary="..."` to delegate to the `microfix-specialist` subagent while keeping scope under the 50-line threshold.
		> Automation Path: Prefer invoking `/knowzcode-microfix target=<NodeID> summary="..."` to delegate to the `microfix-specialist` subagent while keeping scope under the 50-line threshold.

		@@ -11,0 +11,0 @@ ---

+1

-1

knowzcode/prompts/Investigate_Codebase.md

		# KnowzCode: Investigate Codebase

		> Automation Path: On Claude Code, run `/kc:plan "your question"` to orchestrate this automatically.
		> Automation Path: On Claude Code, run `/knowzcode:explore "your question"` to orchestrate this automatically.

		@@ -5,0 +5,0 @@ ## Your Mission

+1

-1

knowzcode/prompts/Refactor_Node.md

		@@ -6,3 +6,3 @@ # KnowzCode: Refactor Node

		> Automation Path: Begin with `/kc-step phase=1A` targeting the `REFACTOR_<NodeID>` tracker entry to scope the Change Set before executing this prompt.
		> Automation Path: Begin with `/knowzcode-step phase=1A` targeting the `REFACTOR_<NodeID>` tracker entry to scope the Change Set before executing this prompt.

		@@ -9,0 +9,0 @@ ---

+1

-1

knowzcode/prompts/Spec_Verification_Checkpoint.md

		@@ -6,3 +6,3 @@ # KnowzCode: Spec Verification Checkpoint

		> Automation Path: Use `/kc-audit audit=spec workgroup_id=<ID>` to run the `reviewer` subagent against the draft specs before implementation.
		> Automation Path: Use `/knowzcode-audit audit=spec workgroup_id=<ID>` to run the `reviewer` subagent against the draft specs before implementation.

		@@ -9,0 +9,0 @@ WorkGroupID: `[wip-timestamp-to-verify]`

+3

-3

knowzcode/telemetry_config.md

		# Telemetry Configuration

		> This file configures telemetry sources for `/kc:telemetry` investigations.
		> This file configures telemetry sources for `/knowzcode:telemetry` investigations.
		>
		> Run `/kc:telemetry-setup` to auto-discover and configure sources.
		> Run `/knowzcode:telemetry-setup` to auto-discover and configure sources.

		@@ -55,3 +55,3 @@ ---

		Run `/kc:telemetry-setup` to:
		Run `/knowzcode:telemetry-setup` to:
		1. Detect installed telemetry tools (sentry-cli, az CLI)
		@@ -58,0 +58,0 @@ 2. Verify authentication status

+4

-4

package.json

		{
		"name": "knowzcode",
		"version": "0.7.2",
		"version": "0.8.3",
		"description": "Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
		@@ -37,9 +37,9 @@ "type": "module",
		},
		"homepage": "https://github.com/knowz-io/knowzcode",
		"homepage": "https://github.com/knowz-io/knowz-skills",
		"bugs": {
		"url": "https://github.com/knowz-io/knowzcode/issues"
		"url": "https://github.com/knowz-io/knowz-skills/issues"
		},
		"repository": {
		"type": "git",
		"url": "git+https://github.com/knowz-io/knowzcode.git"
		"url": "git+https://github.com/knowz-io/knowz-skills.git"
		},
		@@ -46,0 +46,0 @@ "publishConfig": {

+64

-61

README.md

		@@ -8,4 +8,4 @@ # KnowzCode
		[![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.7.2-blue)](https://github.com/knowz-io/knowzcode/releases)
		[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowz-skills)
		[![Version](https://img.shields.io/badge/version-0.8.3-blue)](https://github.com/knowz-io/knowz-skills/releases)

		@@ -73,3 +73,3 @@ [Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)
		KnowzCode automatically classifies tasks by complexity:
		- Micro — single-file fixes skip the loop entirely (`/kc:fix`)
		- Micro — single-file fixes skip the loop entirely (`/knowzcode:fix`)
		- Light — small changes (≤3 files) use a streamlined 2-phase path
		@@ -85,7 +85,7 @@ - Full — complex features get the complete 5-phase workflow above
		```bash
		/plugin marketplace add knowz-io/knowzcode
		/plugin install kc@knowzcode
		/plugin marketplace add knowz-io/knowz-skills
		/plugin install knowzcode@knowz-skills
		cd your-project/
		/kc:init
		/kc:work "Build user authentication"
		/knowzcode:init
		/knowzcode:work "Build user authentication"
		```
		@@ -102,3 +102,3 @@
		Commands available as `/work`, `/plan`, `/fix` (without `kc:` prefix).
		For `/kc:` prefix, also run: `/plugin install kc@knowzcode`.
		For `/knowzcode:` prefix, also run: `/plugin install knowzcode@knowz-skills`.

		@@ -113,4 +113,4 @@ <details>
		\| Claude Code \| `CLAUDE.md` + `.claude/{agents,skills}/` \| Plugin + 14 agents + 13 skills \|
		\| OpenAI Codex \| `AGENTS.md` + `.agents/skills/kc-*/SKILL.md` (12 skills) \| Instruction file + discoverable skill files \|
		\| Gemini CLI \| `GEMINI.md` + `.gemini/commands/kc/.toml` (12 commands) + `.gemini/skills/kc-/SKILL.md` (12 skills) + `.gemini/agents/kc-*.md` (14 subagents, experimental) \| Native commands + skills + subagents + instruction file \|
		\| OpenAI Codex \| `AGENTS.md` + `.agents/skills/knowzcode-*/SKILL.md` (12 skills) \| Instruction file + discoverable skill files \|
		\| Gemini CLI \| `GEMINI.md` + `.gemini/commands/knowzcode/.toml` (12 commands) + `.gemini/skills/knowzcode-/SKILL.md` (12 skills) + `.gemini/agents/knowzcode-*.md` (14 subagents, experimental) \| Native commands + skills + subagents + instruction file \|

		@@ -121,3 +121,3 @@ Experimental (functional, under refinement):
		\|----------\|----------------\|---------------\|
		\| GitHub Copilot \| `.github/copilot-instructions.md` + `.github/prompts/kc-*.prompt.md` (9 prompts) + `.vscode/mcp.json` \| Instruction file + prompt files + MCP \|
		\| GitHub Copilot \| `.github/copilot-instructions.md` + `.github/prompts/knowzcode-*.prompt.md` (9 prompts) + `.vscode/mcp.json` \| Instruction file + prompt files + MCP \|
		\| Cursor \| `.cursor/rules/knowzcode.mdc` \| Rules file (commands via `.cursor/commands/` beta) \|
		@@ -131,3 +131,3 @@ \| Windsurf \| `.windsurf/rules/knowzcode.md` \| Rules file (workflows via `.windsurf/workflows/`) \|
		```bash
		git clone https://github.com/knowz-io/knowzcode.git
		git clone https://github.com/knowz-io/knowz-skills.git
		cd KnowzCode
		@@ -149,3 +149,3 @@ ./install.sh install --target /path/to/your/project # Linux/macOS
		```bash
		/kc:work "Build user authentication with email and password"
		/knowzcode:work "Build user authentication with email and password"
		```
		@@ -158,6 +158,6 @@
		```bash
		/kc:plan "how is authentication implemented?"
		/knowzcode:explore "how is authentication implemented?"
		```

		Explores your codebase first. Say "implement" to transition into `/kc:work` with findings pre-loaded.
		Explores your codebase first. Say "implement" to transition into `/knowzcode:work` with findings pre-loaded.

		@@ -167,3 +167,3 @@ ### Quick Fix
		```bash
		/kc:fix "Fix typo in login button text"
		/knowzcode:fix "Fix typo in login button text"
		```
		@@ -177,15 +177,12 @@
		\|:--------\|:------------\|
		\| `/kc:init` \| Initialize KnowzCode in project \|
		\| `/kc:work <goal>` \| Start feature workflow \|
		\| `/kc:plan <topic>` \| Research before implementing \|
		\| `/kc:audit [type]` \| Run quality audits \|
		\| `/kc:fix <target>` \| Quick targeted fix \|
		\| `/kc:connect-mcp` \| Configure MCP server \|
		\| `/kc:register` \| Register and configure MCP \|
		\| `/kc:status` \| Check MCP connection \|
		\| `/kc:learn` \| Capture learnings to vault \|
		\| `/kc:telemetry` \| Investigate production telemetry \|
		\| `/kc:telemetry-setup` \| Configure telemetry sources \|
		\| `/kc:continue` \| Resume active workflow (auto-triggered on "continue", "keep going", etc.) \|
		\| `/kc:start-work` \| Auto-redirect implementation intent to `/kc:work` with context \|
		\| `/knowzcode:init` \| Initialize KnowzCode in project \|
		\| `/knowzcode:work <goal>` \| Start feature workflow \|
		\| `/knowzcode:explore <topic>` \| Research before implementing \|
		\| `/knowzcode:audit [type]` \| Run quality audits \|
		\| `/knowzcode:fix <target>` \| Quick targeted fix \|
		\| `/knowzcode:status` \| Check MCP connection \|
		\| `/knowzcode:telemetry` \| Investigate production telemetry \|
		\| `/knowzcode:telemetry-setup` \| Configure telemetry sources \|
		\| `/knowzcode:continue` \| Resume active workflow (auto-triggered on "continue", "keep going", etc.) \|
		\| `/knowzcode:start-work` \| Auto-redirect implementation intent to `/knowzcode:work` with context \|

		@@ -216,7 +213,7 @@ ## Architecture

		When using Claude Code, `/kc:work` automatically selects an execution strategy based on task complexity and available features:
		When using Claude Code, `/knowzcode:work` automatically selects an execution strategy based on task complexity and available features:

		\| Mode \| When Used \| How It Works \|
		\|------\|-----------\|-------------\|
		\| Parallel Teams \| Complex features (default for >3 files) \| Multiple agents work concurrently — scouts gather context, builders implement in parallel, reviewer audits incrementally \|
		\| Parallel Teams \| Complex features (default for >3 files) \| Multiple agents work concurrently — knowledge-liaison gathers context, builders implement in parallel, reviewer audits incrementally \|
		\| Sequential Teams \| Lighter features or `--sequential` flag \| One agent per phase with persistent team context \|
		@@ -238,5 +235,3 @@ \| Subagent Delegation \| Agent Teams not enabled \| One agent spawned per phase via fallback — works on all Claude Code instances \|
		\|-------\|------\|-------\|
		\| `context-scout` \| Local context research (specs, tracker, history) \| Discovery \|
		\| `knowz-scout` \| MCP vault research (conventions, decisions) \| Discovery \|
		\| `knowz-scribe` \| MCP vault writes (learning capture, audit trails) \| All phases \|
		\| `knowledge-liaison` \| Context & vault coordination (specs, tracker, history, vault queries) \| Discovery \|
		\| `analyst` \| Impact analysis, Change Set proposals \| 1A \|
		@@ -259,8 +254,8 @@ \| `architect` \| Specification drafting, architecture review \| 1B \|

		Activate specialists with `--specialists` in `/kc:work` or `/kc:audit`:
		Activate specialists with `--specialists` in `/knowzcode:work` or `/knowzcode:audit`:

		```bash
		/kc:work "Build auth system" --specialists # All 3 specialists
		/kc:work "Build auth system" --specialists=security # Security officer only
		/kc:audit --specialists # Deep audit with specialists
		/knowzcode:work "Build auth system" --specialists # All 3 specialists
		/knowzcode:work "Build auth system" --specialists=security # Security officer only
		/knowzcode:audit --specialists # Deep audit with specialists
		```
		@@ -280,9 +275,9 @@

		Codex users get discoverable skills via `.agents/skills/kc-*/`:
		Codex users get discoverable skills via `.agents/skills/knowzcode-*/`:

		```bash
		/kc:work "Build user authentication" # Start feature workflow
		/kc:plan "how is auth implemented?" # Research first
		/kc:fix "Fix login bug" # Quick fix
		/kc:audit # Quality audit
		/knowzcode:work "Build user authentication" # Start feature workflow
		/knowzcode:explore "how is auth implemented?" # Research first
		/knowzcode:fix "Fix login bug" # Quick fix
		/knowzcode:audit # Quality audit
		```
		@@ -294,3 +289,3 @@
		```bash
		npx knowzcode install --platforms codex --global # Skills → ~/.agents/skills/kc-*/
		npx knowzcode install --platforms codex --global # Skills → ~/.agents/skills/knowzcode-*/
		```
		@@ -300,19 +295,19 @@

		Gemini users get native `/kc:` commands via TOML files, discoverable skills, and optional subagents:
		Gemini users get native `/knowzcode:` commands via TOML files, discoverable skills, and optional subagents:

		```bash
		/kc:work "Build JWT authentication" # Start feature workflow
		/kc:plan "how is auth implemented?" # Research first
		/kc:fix "Fix login redirect bug" # Quick fix
		/kc:audit # Quality audit
		/kc:continue # Resume where you left off
		/kc:connect-mcp <api-key> # Configure MCP
		/kc:telemetry "500 errors in prod" # Investigate telemetry
		/knowzcode:work "Build JWT authentication" # Start feature workflow
		/knowzcode:explore "how is auth implemented?" # Research first
		/knowzcode:fix "Fix login redirect bug" # Quick fix
		/knowzcode:audit # Quality audit
		/knowzcode:continue # Resume where you left off
		/knowz setup # Configure MCP (requires knowz plugin)
		/knowzcode:telemetry "500 errors in prod" # Investigate telemetry
		```

		Generated by `npx knowzcode install --platforms gemini` into `.gemini/commands/kc/`, `.gemini/skills/kc-/`, and `.gemini/agents/kc-.md`.
		Generated by `npx knowzcode install --platforms gemini` into `.gemini/commands/knowzcode/`, `.gemini/skills/knowzcode-/`, and `.gemini/agents/knowzcode-.md`.

		For cross-project availability, install skills globally:
		```bash
		npx knowzcode install --platforms gemini --global # Skills → ~/.gemini/skills/kc-*/
		npx knowzcode install --platforms gemini --global # Skills → ~/.gemini/skills/knowzcode-*/
		```
		@@ -332,11 +327,11 @@
		```bash
		#prompt:kc-work "Build JWT authentication" # Start feature workflow
		#prompt:kc-specify # Draft specs (after Change Set approved)
		#prompt:kc-implement # TDD implementation
		#prompt:kc-audit # READ-ONLY audit
		#prompt:kc-finalize # Finalize and commit
		#prompt:kc-continue # Resume where you left off
		#prompt:knowzcode-work "Build JWT authentication" # Start feature workflow
		#prompt:knowzcode-specify # Draft specs (after Change Set approved)
		#prompt:knowzcode-implement # TDD implementation
		#prompt:knowzcode-audit # READ-ONLY audit
		#prompt:knowzcode-finalize # Finalize and commit
		#prompt:knowzcode-continue # Resume where you left off
		```

		Generated by `/kc:init` into `.github/prompts/`. See `knowzcode/copilot_execution.md` for details.
		Generated by `/knowzcode:init` into `.github/prompts/`. See `knowzcode/copilot_execution.md` for details.

		@@ -377,2 +372,10 @@ </details>

		## Companion Plugins

		\| Plugin \| Purpose \| Install \|
		\|:-------\|:--------\|:--------\|
		\| [knowz](https://github.com/knowz-io/knowz-skill) \| MCP vault features — setup, registration, learning capture, flush \| `claude plugin install knowz` \|

		KnowzCode works without companion plugins. The knowz plugin adds `/knowz setup`, `/knowz register`, `/knowz save`, and `/knowz flush` for MCP vault management.

		## Contributing
		@@ -379,0 +382,0 @@

+64

-38

skills/audit/SKILL.md

		---
		name: audit
		description: "Run KnowzCode quality audits (spec, architecture, security, integration, compliance). Use when asked to audit code quality, review health, or scan for vulnerabilities."
		description: "Run read-only quality audits on the existing codebase — spec completeness, architecture health, OWASP security scanning, integration consistency. Use when the user wants to AUDIT or SCAN existing code, not build new features."
		user-invocable: true
		allowed-tools: Read, Write, Bash, Glob, Grep, Task
		# Note: Also uses MCP tools (search_knowledge, ask_question) when MCP is configured
		argument-hint: "[audit_type]"
		@@ -13,7 +14,21 @@ ---

		Usage: `/kc:audit [audit_type]`
		Example: `/kc:audit spec` or `/kc:audit security`
		Usage: `/knowzcode:audit [audit_type]`
		Example: `/knowzcode:audit spec` or `/knowzcode:audit security`

		Audit Type: $ARGUMENTS

		## When NOT to Trigger

		- User wants to build or implement a new feature → use `/knowzcode:work`
		- User wants a single-file fix → use `/knowzcode:fix`
		- User wants to research or explore a topic → use `/knowzcode:explore`
		- User wants to save a learning → use `/knowz save`

		## Common Invocation Patterns

		These phrases indicate `/knowzcode:audit` intent:
		- "audit the codebase", "run a security scan"
		- "check code quality", "scan for vulnerabilities"
		- "review architecture health", "check spec completeness"

		---
		@@ -46,8 +61,6 @@

		1. `SCOUT_MODE` = `scout_mode` value (default: "full")
		2. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
		3. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
		1. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
		2. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)

		Apply flag overrides (flags win over config):
		- `--no-scouts` in `$ARGUMENTS` → override `SCOUT_MODE = "none"`
		- `--no-specialists` in `$ARGUMENTS` → override `DEFAULT_SPECIALISTS = []`
		@@ -99,3 +112,3 @@ - `--no-mcp` in `$ARGUMENTS` → override `MCP_AGENTS_ENABLED = false`
		B) Select which to create
		C) Skip — proceed without vaults (can create later with `/kc:connect-mcp --configure-vaults`)
		C) Skip — proceed without vaults (can create later with `/knowz setup`)
		```
		@@ -107,2 +120,3 @@
		- C: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
		- If BOTH `create_vault()` and name-matching fail: log failure, set `VAULTS_CONFIGURED = false`, continue without vault. Report: `"⚠️ Vault creation failed — proceeding without knowledge capture. Run /knowz setup to retry."`
		6. After resolution, set:
		@@ -113,2 +127,4 @@ - `MCP_ACTIVE = true` (MCP works regardless of vault creation outcome)

		> Vault research is mandatory when available. If `VAULTS_CONFIGURED = true` and `MCP_AGENTS_ENABLED = true`, the `knowz:reader` dispatch MUST execute in both Exploration and Planning modes. The 10-tool-call budget in Exploration Mode is a scope limit, not a reason to skip. Only skip when MCP is genuinely unavailable (`MCP_ACTIVE = false`).

		### Agent Teams Mode
		@@ -147,3 +163,3 @@
		- (Optional) `TaskCreate("Audit: compliance")` → `TaskUpdate(owner: "reviewer-compliance")` (if enterprise configured)
		- `TaskCreate("Scout: vault standards")` → `TaskUpdate(owner: "knowz-scout")` (if `VAULTS_CONFIGURED = true`)
		- Dispatch `knowz:reader` for vault standards (if `VAULTS_CONFIGURED = true`)

		@@ -183,5 +199,6 @@ Spawn reviewers with their task IDs:

		4. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, spawn `knowz-scout` for standards lookup in parallel with reviewers:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type. Query for team standards: `ask_question({vault matching "ecosystem" type}, "standards for {project_type}", researchMode=true)`
		4. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, dispatch `knowz:reader` for standards lookup in parallel with reviewers:
		> Read `knowzcode/knowzcode_vaults.md` to discover configured vaults — their IDs, types, descriptions.
		> Query for team standards: search ecosystem-type vaults for standards, conventions, and past audit decisions.
		> Return synthesized findings.

		@@ -238,16 +255,8 @@ Wait for all to complete.

		Launch scouts + reviewer in parallel via `Task()`:
		Launch knowledge-liaison + reviewer in parallel via `Task()`:

		1. context-scout — Local context (if `SCOUT_MODE != "none"`):
		- `SCOUT_MODE = "full"` (default): 3 parallel instances:
		- `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
		- `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for related audit findings. Max 10 tool calls. Write findings to a concise summary.")`
		- `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md — scan for active WIP, prior audit results, architecture health. Max 10 tool calls. Write findings to a concise summary.")`
		- `SCOUT_MODE = "minimal"`: 1 combined instance:
		- `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research audit scope: {audit_type}. Focus: ALL local context — knowzcode/specs/.md, knowzcode/workgroups/.md, knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md. Max 10 tool calls. Write findings to a concise summary.")`
		1. knowledge-liaison — Local context + vault knowledge:
		- `Task(subagent_type="knowzcode:knowledge-liaison", description="Liaison: audit context", prompt="Research audit scope: {audit_type}. Gather local context (specs, workgroups, tracker, log, architecture) and vault knowledge (standards, conventions, past audit decisions). Push Context Briefing with findings. Max 15 tool calls. Write findings to a concise summary.")`

		2. knowz-scout — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
		- `Task(subagent_type="knowz-scout", description="Scout: vault standards", prompt="Research audit scope: {audit_type}. Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query for team standards, conventions, and past audit decisions. Max 10 tool calls. Write findings to a concise summary.")`

		3. reviewer — The audit itself:
		2. reviewer — The audit itself:
		- `subagent_type`: `"reviewer"`
		@@ -262,20 +271,12 @@ - `prompt`: Task-specific context only (role definition is auto-loaded from `agents/reviewer.md`):

		All launched in parallel. Synthesize scout findings alongside reviewer results.
		All launched in parallel. Synthesize knowledge-liaison context alongside reviewer results.

		#### Full Audit

		Launch scouts + parallel reviewers via `Task()`:
		Launch knowledge-liaison + parallel reviewers via `Task()`:

		1. context-scout — Local context (if `SCOUT_MODE != "none"`):
		- `SCOUT_MODE = "full"` (default): 3 parallel instances:
		- `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research for comprehensive audit. Focus: knowzcode/specs/*.md — scan all specifications for quality, completeness, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
		- `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research for comprehensive audit. Focus: knowzcode/workgroups/*.md — scan all WorkGroups for patterns, recurring issues, audit history. Max 10 tool calls. Write findings to a concise summary.")`
		- `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research for comprehensive audit. Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md — scan for WIP status, prior audit results, architecture health. Max 10 tool calls. Write findings to a concise summary.")`
		- `SCOUT_MODE = "minimal"`: 1 combined instance:
		- `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research for comprehensive audit. Focus: ALL local context — knowzcode/specs/.md, knowzcode/workgroups/.md, knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md. Max 10 tool calls. Write findings to a concise summary.")`
		1. knowledge-liaison — Local context + vault knowledge:
		- `Task(subagent_type="knowzcode:knowledge-liaison", description="Liaison: audit context", prompt="Research for comprehensive audit. Gather local context (specs, workgroups, tracker, log, architecture) and vault knowledge (standards, conventions, security policies, compliance requirements). Push Context Briefing with findings. Max 15 tool calls. Write findings to a concise summary.")`

		2. knowz-scout — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
		- `Task(subagent_type="knowz-scout", description="Scout: vault standards", prompt="Research for comprehensive audit. Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query for team standards, conventions, security policies, and compliance requirements. Max 10 tool calls. Write findings to a concise summary.")`

		3. Parallel reviewers:
		2. Parallel reviewers:
		- `Task(subagent_type="reviewer", description="Audit: spec + architecture", prompt="Audit scope: Specification quality AND architecture health ONLY. ...")`
		@@ -285,3 +286,3 @@ - `Task(subagent_type="reviewer", description="Audit: security + integration", prompt="Audit scope: Security vulnerability scan AND integration consistency ONLY. ...")`

		Synthesize scout context alongside reviewer results.
		Synthesize knowledge-liaison context alongside reviewer results.

		@@ -334,2 +335,20 @@ #### Specialist Integration (Subagent Mode — Optional)

		## Step 4.5: Vault Capture Prompt

		If `VAULTS_CONFIGURED = true` AND `MCP_ACTIVE = true`, present after audit results:

		```markdown
		Save to vault? These audit findings can be captured to Knowz for future reference.
		A) Save all findings (scores + issues + recommendations)
		B) Select which to save
		C) Skip
		```

		Handling:
		- A: Dispatch `knowz:writer` with a self-contained prompt summarizing all findings, tagged with the topic. Read `knowzcode/knowzcode_vaults.md` to resolve the target vault (use ecosystem-type vault). Check for duplicates via `search_knowledge` before writing.
		- B: Ask user which sections to save, then dispatch `knowz:writer` with selected content.
		- C: Proceed to Step 5.

		If `VAULTS_CONFIGURED = false` or `MCP_ACTIVE = false`, skip this step silently.

		## Step 5: Log Audit
		@@ -343,1 +362,8 @@
		If MCP is configured and enterprise vault exists: push audit results via `create_knowledge` for team audit trail.

		## Related Skills

		- `/knowzcode:work` — Build features (not audit)
		- `/knowzcode:fix` — Fix a specific bug found during audit
		- `/knowz save` — Capture audit findings to vault
		- `/knowzcode:telemetry` — Investigate production errors

+12

-7

skills/continue/SKILL.md

		@@ -33,3 +33,3 @@ ---
		- User is asking a question
		- Already executing a /kc:* command
		- Already executing a /knowzcode:* command
		- knowzcode/ directory doesn't exist
		@@ -47,3 +47,3 @@
		- Multiple active: Present options to user
		- None active: Inform user and suggest `/kc:work`
		- None active: Inform user and suggest `/knowzcode:work`

		@@ -58,3 +58,3 @@ ### Step 2: Load WorkGroup Context
		- Autonomous Mode: If the WorkGroup file contains `Autonomous Mode: Active`, restore `AUTONOMOUS_MODE = true` and announce: `> Autonomous Mode: RESTORED — continuing with auto-approved gates.`
		- Orchestration Config: If `knowzcode/knowzcode_orchestration.md` exists, parse and restore `MAX_BUILDERS`, `SCOUT_MODE`, `MCP_AGENTS_ENABLED`, `DEFAULT_SPECIALISTS` (same logic as work.md Step 2.4). Defaults apply if file is absent.
		- Orchestration Config: If `knowzcode/knowzcode_orchestration.md` exists, parse and restore `MAX_BUILDERS`, `MCP_AGENTS_ENABLED`, `DEFAULT_SPECIALISTS` (same logic as work.md Step 2.4). Defaults apply if file is absent.

		@@ -71,3 +71,3 @@ ### Step 3: Resume at Current Phase
		- Resume by recreating the team and spawning agents appropriate for the current stage:
		- Stage 0/1: Spawn analyst + architect. If `SCOUT_MODE != "none"` and context is stale, re-spawn scout(s) per SCOUT_MODE.
		- Stage 0/1: Spawn analyst + architect. If context is stale, spawn knowledge-liaison to refresh local + vault context.
		- Stage 2: Spawn builder(s) per the dependency map + reviewer if any NodeIDs are past implementation
		@@ -96,7 +96,7 @@ - Stage 3: Spawn closer

		Set up execution mode — check `~/.claude/settings.json` and `.claude/settings.json` for `"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"` in the `env` block. If found, Agent Teams is available — create a team named `kc-{wgid}` and activate delegate mode (you coordinate only, never write code directly). Read `knowzcode/claude_code_execution.md` for team conventions. For each remaining phase, spawn one teammate with the spawn prompt from the corresponding phase section of `/kc:work`, create a task, wait for completion, present quality gate, shut down teammate. Shut down all teammates when done or on cancel.
		Set up execution mode — check `~/.claude/settings.json` and `.claude/settings.json` for `"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"` in the `env` block. If found, Agent Teams is available — create a team named `kc-{wgid}` and activate delegate mode (you coordinate only, never write code directly). Read `knowzcode/claude_code_execution.md` for team conventions. For each remaining phase, spawn one teammate with the spawn prompt from the corresponding phase section of `/knowzcode:work`, create a task, wait for completion, present quality gate, shut down teammate. Shut down all teammates when done or on cancel.

		If Agent Teams is not available, announce `Execution Mode: Subagent Delegation — Agent Teams not available (add "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" to the env block in settings.json, then restart Claude Code)` and use `Task()` calls to delegate each remaining phase to the named agent.

		Follow the same phase delegation patterns (spawn prompts, quality gates, gap loop) as `/kc:work`.
		Follow the same phase delegation patterns (spawn prompts, quality gates, gap loop) as `/knowzcode:work`.

		@@ -118,4 +118,9 @@ ### Step 4: Present Status

		Then proceed with the appropriate phase using the same agents as `/kc:work`.
		Then proceed with the appropriate phase using the same agents as `/knowzcode:work`.

		## Related Skills

		- `/knowzcode:work` — Start a new WorkGroup (if nothing to continue)
		- `/knowzcode:status` — Check current project state

		## Logging
		@@ -122,0 +127,0 @@

+20

-7

skills/fix/SKILL.md

		---
		name: fix
		description: "Execute a targeted micro-fix for single-file changes under 50 lines. Use when asked to fix a small bug, typo, or localized issue. Redirects to /kc:work for larger changes."
		description: "Execute a targeted micro-fix for single-file changes under 50 lines. Use when asked to fix a small bug, typo, or localized issue. Redirects to /knowzcode:work for larger changes."
		user-invocable: true
		@@ -13,5 +13,12 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep

		Usage: `/kc:fix <target> <summary>`
		Example: `/kc:fix src/auth/login.ts "Fix null reference in password validation"`
		Usage: `/knowzcode:fix <target> <summary>`
		Example: `/knowzcode:fix src/auth/login.ts "Fix null reference in password validation"`

		## When NOT to Trigger

		- Change spans multiple files or >50 lines → use `/knowzcode:work`
		- Change needs exploration first before fixing → use `/knowzcode:explore`
		- User wants a codebase audit, not a targeted fix → use `/knowzcode:audit`
		- User is asking "how to fix" (question, not action) → answer directly, don't invoke skill

		---
		@@ -31,3 +38,3 @@

		If ANY criteria fails: Stop and suggest `/kc:work` for full orchestration.
		If ANY criteria fails: Stop and suggest `/knowzcode:work` for full orchestration.

		@@ -40,3 +47,3 @@ ---
		- Confirm the fix meets micro-fix criteria above
		- If scope exceeds limits, redirect to `/kc:work`
		- If scope exceeds limits, redirect to `/knowzcode:work`

		@@ -98,4 +105,4 @@ ### 2. Load Context
		```
		/kc:fix src/auth/login.ts "Fix null reference in password validation"
		/kc:fix NODE_AUTH_123 "Update error message formatting"
		/knowzcode:fix src/auth/login.ts "Fix null reference in password validation"
		/knowzcode:fix NODE_AUTH_123 "Update error message formatting"
		```
		@@ -115,1 +122,7 @@
		> Note: Micro-fixes use subagent delegation only. Agent Teams overhead is not justified for single-file, <50 line fixes.

		## Related Skills

		- `/knowzcode:work` — Full workflow for multi-file or >50 line changes
		- `/knowzcode:explore` — Research before deciding on a fix approach
		- `/knowzcode:audit` — Read-only scan to find issues

+3

-12

skills/init/references/templates.md

		# KnowzCode Init — Template Files

		These templates are generated during `/kc:init` Step 3. Create each file in the `knowzcode/` directory.
		These templates are generated during `/knowzcode:init` Step 3. Create each file in the `knowzcode/` directory.

		@@ -43,3 +43,3 @@ ## knowzcode_project.md

		None yet. Run `/kc:work "your feature description"` to create your first WorkGroup.
		None yet. Run `/knowzcode:work "your feature description"` to create your first WorkGroup.

		@@ -109,3 +109,3 @@ ## Completed WorkGroups

		Purpose: Project-level defaults for team sizing and agent orchestration. Read by `/kc:work` and `/kc:audit` at startup. Per-invocation flags override these settings.
		Purpose: Project-level defaults for team sizing and agent orchestration. Read by `/knowzcode:work` and `/knowzcode:audit` at startup. Per-invocation flags override these settings.

		@@ -122,10 +122,2 @@ ---

		## Scout Configuration

		```yaml
		scout_mode: full
		```

		---

		## Specialist Defaults
		@@ -152,3 +144,2 @@
		\| max_builders \| `max_builders:` \| `--max-builders=N` \|
		\| scout_mode \| `scout_mode:` \| `--no-scouts` \|
		\| default_specialists \| `default_specialists:` \| `--specialists`, `--no-specialists` \|
		@@ -155,0 +146,0 @@ \| mcp_agents_enabled \| `mcp_agents_enabled:` \| `--no-mcp` \|

+120

-119

skills/init/SKILL.md

		@@ -20,2 +20,9 @@ ---

		## When NOT to Trigger

		- Project is already initialized (knowzcode/ directory exists with content) — inform user, offer merge/overwrite
		- User is asking about KnowzCode features, not requesting setup → answer directly
		- User wants to start a feature → use `/knowzcode:work` (which checks initialization itself)
		- User wants to connect MCP → use `/knowz setup`

		## Steps to Execute
		@@ -137,15 +144,16 @@
		1. Create .agents/skills/ directory
		2. Generate 12 skill files from platform_adapters.md "Codex Skill Files" section:
		- .agents/skills/kc-work/SKILL.md
		- .agents/skills/kc-plan/SKILL.md
		- .agents/skills/kc-fix/SKILL.md
		- .agents/skills/kc-audit/SKILL.md
		- .agents/skills/kc-learn/SKILL.md
		- .agents/skills/kc-continue/SKILL.md
		- .agents/skills/kc-init/SKILL.md
		- .agents/skills/kc-status/SKILL.md
		- .agents/skills/kc-connect-mcp/SKILL.md
		- .agents/skills/kc-register/SKILL.md
		- .agents/skills/kc-telemetry/SKILL.md
		- .agents/skills/kc-telemetry-setup/SKILL.md
		2. Generate 12 skill files from platform_adapters.md "Codex Skill Files" section.
		Each generated SKILL.md should include `allowed-tools:` in frontmatter matching the platform's available tools.
		- .agents/skills/knowzcode-work/SKILL.md
		- .agents/skills/knowzcode-explore/SKILL.md
		- .agents/skills/knowzcode-fix/SKILL.md
		- .agents/skills/knowzcode-audit/SKILL.md
		- .agents/skills/knowzcode-learn/SKILL.md
		- .agents/skills/knowzcode-continue/SKILL.md
		- .agents/skills/knowzcode-init/SKILL.md
		- .agents/skills/knowzcode-status/SKILL.md
		- .agents/skills/knowzcode-connect-mcp/SKILL.md
		- .agents/skills/knowzcode-register/SKILL.md
		- .agents/skills/knowzcode-telemetry/SKILL.md
		- .agents/skills/knowzcode-telemetry-setup/SKILL.md
		3. Replace "vX.Y.Z" with current KnowzCode version
		@@ -158,14 +166,11 @@ ```
		AGENTS.md (primary instructions)
		.agents/skills/kc-work/SKILL.md (/kc:work — start workflow)
		.agents/skills/kc-plan/SKILL.md (/kc:plan — research)
		.agents/skills/kc-fix/SKILL.md (/kc:fix — quick fix)
		.agents/skills/kc-audit/SKILL.md (/kc:audit — quality audit)
		.agents/skills/kc-learn/SKILL.md (/kc:learn — capture learning)
		.agents/skills/kc-continue/SKILL.md (/kc:continue — resume workflow)
		.agents/skills/kc-init/SKILL.md (/kc:init — initialize project)
		.agents/skills/kc-status/SKILL.md (/kc:status — check status)
		.agents/skills/kc-connect-mcp/SKILL.md (/kc:connect-mcp — configure MCP)
		.agents/skills/kc-register/SKILL.md (/kc:register — register account)
		.agents/skills/kc-telemetry/SKILL.md (/kc:telemetry — investigate errors)
		.agents/skills/kc-telemetry-setup/SKILL.md (/kc:telemetry-setup — configure sources)
		.agents/skills/knowzcode-work/SKILL.md (/knowzcode:work — start workflow)
		.agents/skills/knowzcode-explore/SKILL.md (/knowzcode:explore — research)
		.agents/skills/knowzcode-fix/SKILL.md (/knowzcode:fix — quick fix)
		.agents/skills/knowzcode-audit/SKILL.md (/knowzcode:audit — quality audit)
		.agents/skills/knowzcode-continue/SKILL.md (/knowzcode:continue — resume workflow)
		.agents/skills/knowzcode-init/SKILL.md (/knowzcode:init — initialize project)
		.agents/skills/knowzcode-status/SKILL.md (/knowzcode:status — check status)
		.agents/skills/knowzcode-telemetry/SKILL.md (/knowzcode:telemetry — investigate errors)
		.agents/skills/knowzcode-telemetry-setup/SKILL.md (/knowzcode:telemetry-setup — configure sources)

		@@ -210,4 +215,4 @@ Tip: Run `npx knowzcode install --platforms codex --global` to install
		3. Update `knowzcode/mcp_config.md` with connection status
		- If "Yes, register first": Direct to `/kc:register`
		- If "No": Skip, mention `/kc:connect-mcp` for later setup
		- If "Yes, register first": Direct to `/knowz setup`
		- If "No": Skip, mention `/knowz setup` for later setup

		@@ -219,30 +224,30 @@ Step 7c-gemini: Generate Gemini TOML commands, skills, and subagents
		```
		1. Create .gemini/commands/kc/ directory
		1. Create .gemini/commands/knowzcode/ directory
		2. Generate 12 TOML files from platform_adapters.md "Native Commands" section:
		- .gemini/commands/kc/work.toml
		- .gemini/commands/kc/plan.toml
		- .gemini/commands/kc/fix.toml
		- .gemini/commands/kc/audit.toml
		- .gemini/commands/kc/learn.toml
		- .gemini/commands/kc/status.toml
		- .gemini/commands/kc/continue.toml
		- .gemini/commands/kc/init.toml
		- .gemini/commands/kc/connect-mcp.toml
		- .gemini/commands/kc/register.toml
		- .gemini/commands/kc/telemetry.toml
		- .gemini/commands/kc/telemetry-setup.toml
		- .gemini/commands/knowzcode/work.toml
		- .gemini/commands/knowzcode/explore.toml
		- .gemini/commands/knowzcode/fix.toml
		- .gemini/commands/knowzcode/audit.toml
		- .gemini/commands/knowzcode/learn.toml
		- .gemini/commands/knowzcode/status.toml
		- .gemini/commands/knowzcode/continue.toml
		- .gemini/commands/knowzcode/init.toml
		- .gemini/commands/knowzcode/connect-mcp.toml
		- .gemini/commands/knowzcode/register.toml
		- .gemini/commands/knowzcode/telemetry.toml
		- .gemini/commands/knowzcode/telemetry-setup.toml
		3. Create .gemini/skills/ directory
		4. Generate 12 skill files from platform_adapters.md "Gemini Skill Files" section:
		- .gemini/skills/kc-work/SKILL.md
		- .gemini/skills/kc-plan/SKILL.md
		- .gemini/skills/kc-fix/SKILL.md
		- .gemini/skills/kc-audit/SKILL.md
		- .gemini/skills/kc-learn/SKILL.md
		- .gemini/skills/kc-continue/SKILL.md
		- .gemini/skills/kc-init/SKILL.md
		- .gemini/skills/kc-status/SKILL.md
		- .gemini/skills/kc-connect-mcp/SKILL.md
		- .gemini/skills/kc-register/SKILL.md
		- .gemini/skills/kc-telemetry/SKILL.md
		- .gemini/skills/kc-telemetry-setup/SKILL.md
		- .gemini/skills/knowzcode-work/SKILL.md
		- .gemini/skills/knowzcode-explore/SKILL.md
		- .gemini/skills/knowzcode-fix/SKILL.md
		- .gemini/skills/knowzcode-audit/SKILL.md
		- .gemini/skills/knowzcode-learn/SKILL.md
		- .gemini/skills/knowzcode-continue/SKILL.md
		- .gemini/skills/knowzcode-init/SKILL.md
		- .gemini/skills/knowzcode-status/SKILL.md
		- .gemini/skills/knowzcode-connect-mcp/SKILL.md
		- .gemini/skills/knowzcode-register/SKILL.md
		- .gemini/skills/knowzcode-telemetry/SKILL.md
		- .gemini/skills/knowzcode-telemetry-setup/SKILL.md
		5. Replace "vX.Y.Z" with current KnowzCode version
		@@ -258,17 +263,14 @@ ```
		1. Create .gemini/agents/ directory
		2. Generate 14 subagent files from platform_adapters.md "Gemini Subagents" section:
		- .gemini/agents/kc-analyst.md
		- .gemini/agents/kc-architect.md
		- .gemini/agents/kc-builder.md
		- .gemini/agents/kc-reviewer.md
		- .gemini/agents/kc-closer.md
		- .gemini/agents/kc-context-scout.md
		- .gemini/agents/kc-knowz-scout.md
		- .gemini/agents/kc-knowz-scribe.md
		- .gemini/agents/kc-microfix.md
		- .gemini/agents/kc-knowledge-migrator.md
		- .gemini/agents/kc-update-coordinator.md
		- .gemini/agents/kc-security-officer.md
		- .gemini/agents/kc-test-advisor.md
		- .gemini/agents/kc-project-advisor.md
		2. Generate 11 subagent files from platform_adapters.md "Gemini Subagents" section:
		- .gemini/agents/knowzcode-analyst.md
		- .gemini/agents/knowzcode-architect.md
		- .gemini/agents/knowzcode-builder.md
		- .gemini/agents/knowzcode-reviewer.md
		- .gemini/agents/knowzcode-closer.md
		- .gemini/agents/knowzcode-microfix.md
		- .gemini/agents/knowzcode-knowledge-migrator.md
		- .gemini/agents/knowzcode-update-coordinator.md
		- .gemini/agents/knowzcode-security-officer.md
		- .gemini/agents/knowzcode-test-advisor.md
		- .gemini/agents/knowzcode-project-advisor.md
		3. Replace "vX.Y.Z" with current KnowzCode version
		@@ -281,29 +283,23 @@ ```
		GEMINI.md (primary instructions)
		.gemini/commands/kc/work.toml (/kc:work — start workflow)
		.gemini/commands/kc/plan.toml (/kc:plan — research)
		.gemini/commands/kc/fix.toml (/kc:fix — quick fix)
		.gemini/commands/kc/audit.toml (/kc:audit — quality audit)
		.gemini/commands/kc/learn.toml (/kc:learn — capture learning)
		.gemini/commands/kc/status.toml (/kc:status — connection status)
		.gemini/commands/kc/continue.toml (/kc:continue — resume workflow)
		.gemini/commands/kc/init.toml (/kc:init — initialize project)
		.gemini/commands/kc/connect-mcp.toml (/kc:connect-mcp — configure MCP)
		.gemini/commands/kc/register.toml (/kc:register — register account)
		.gemini/commands/kc/telemetry.toml (/kc:telemetry — investigate errors)
		.gemini/commands/kc/telemetry-setup.toml (/kc:telemetry-setup — configure sources)
		.gemini/skills/kc-work/SKILL.md (discoverable skill)
		.gemini/skills/kc-plan/SKILL.md (discoverable skill)
		.gemini/skills/kc-fix/SKILL.md (discoverable skill)
		.gemini/skills/kc-audit/SKILL.md (discoverable skill)
		.gemini/skills/kc-learn/SKILL.md (discoverable skill)
		.gemini/skills/kc-continue/SKILL.md (discoverable skill)
		.gemini/skills/kc-init/SKILL.md (discoverable skill)
		.gemini/skills/kc-status/SKILL.md (discoverable skill)
		.gemini/skills/kc-connect-mcp/SKILL.md (discoverable skill)
		.gemini/skills/kc-register/SKILL.md (discoverable skill)
		.gemini/skills/kc-telemetry/SKILL.md (discoverable skill)
		.gemini/skills/kc-telemetry-setup/SKILL.md (discoverable skill)
		.gemini/agents/kc-*.md (14 subagents) (experimental — if opted in)
		.gemini/commands/knowzcode/work.toml (/knowzcode:work — start workflow)
		.gemini/commands/knowzcode/explore.toml (/knowzcode:explore — research)
		.gemini/commands/knowzcode/fix.toml (/knowzcode:fix — quick fix)
		.gemini/commands/knowzcode/audit.toml (/knowzcode:audit — quality audit)
		.gemini/commands/knowzcode/status.toml (/knowzcode:status — connection status)
		.gemini/commands/knowzcode/continue.toml (/knowzcode:continue — resume workflow)
		.gemini/commands/knowzcode/init.toml (/knowzcode:init — initialize project)
		.gemini/commands/knowzcode/telemetry.toml (/knowzcode:telemetry — investigate errors)
		.gemini/commands/knowzcode/telemetry-setup.toml (/knowzcode:telemetry-setup — configure sources)
		.gemini/skills/knowzcode-work/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-explore/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-fix/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-audit/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-continue/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-init/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-status/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-telemetry/SKILL.md (discoverable skill)
		.gemini/skills/knowzcode-telemetry-setup/SKILL.md (discoverable skill)
		.gemini/agents/knowzcode-*.md (14 subagents) (experimental — if opted in)

		MCP: [Configured (.gemini/settings.json) \| Not configured — run /kc:connect-mcp later]
		MCP: [Configured (.gemini/settings.json) \| Not configured — run /knowz setup later]

		@@ -333,11 +329,11 @@ Tip: Run `npx knowzcode install --platforms gemini --global` to install
		4. Generate all 9 prompt files from platform_adapters.md template Section B:
		- .github/prompts/kc-work.prompt.md
		- .github/prompts/kc-analyze.prompt.md
		- .github/prompts/kc-specify.prompt.md
		- .github/prompts/kc-implement.prompt.md
		- .github/prompts/kc-audit.prompt.md
		- .github/prompts/kc-finalize.prompt.md
		- .github/prompts/kc-fix.prompt.md
		- .github/prompts/kc-plan.prompt.md
		- .github/prompts/kc-continue.prompt.md
		- .github/prompts/knowzcode-work.prompt.md
		- .github/prompts/knowzcode-analyze.prompt.md
		- .github/prompts/knowzcode-specify.prompt.md
		- .github/prompts/knowzcode-implement.prompt.md
		- .github/prompts/knowzcode-audit.prompt.md
		- .github/prompts/knowzcode-finalize.prompt.md
		- .github/prompts/knowzcode-fix.prompt.md
		- .github/prompts/knowzcode-explore.prompt.md
		- .github/prompts/knowzcode-continue.prompt.md
		5. Replace "vX.Y.Z" in generated files with the current KnowzCode version
		@@ -354,16 +350,16 @@ 6. Optionally create .vscode/mcp.json skeleton from template Section C
		.github/copilot-instructions.md (repository-level instructions)
		.github/prompts/kc-work.prompt.md (start workflow: #prompt:kc-work)
		.github/prompts/kc-analyze.prompt.md
		.github/prompts/kc-specify.prompt.md
		.github/prompts/kc-implement.prompt.md
		.github/prompts/kc-audit.prompt.md
		.github/prompts/kc-finalize.prompt.md
		.github/prompts/kc-fix.prompt.md (quick fix: #prompt:kc-fix)
		.github/prompts/kc-plan.prompt.md (research: #prompt:kc-plan)
		.github/prompts/kc-continue.prompt.md (resume: #prompt:kc-continue)
		.github/prompts/knowzcode-work.prompt.md (start workflow: #prompt:knowzcode-work)
		.github/prompts/knowzcode-analyze.prompt.md
		.github/prompts/knowzcode-specify.prompt.md
		.github/prompts/knowzcode-implement.prompt.md
		.github/prompts/knowzcode-audit.prompt.md
		.github/prompts/knowzcode-finalize.prompt.md
		.github/prompts/knowzcode-fix.prompt.md (quick fix: #prompt:knowzcode-fix)
		.github/prompts/knowzcode-explore.prompt.md (research: #prompt:knowzcode-explore)
		.github/prompts/knowzcode-continue.prompt.md (resume: #prompt:knowzcode-continue)

		Usage in VS Code:
		#prompt:kc-work "Build user authentication" — Start a feature
		#prompt:kc-fix "Fix login redirect bug" — Quick fix
		#prompt:kc-continue — Resume where you left off
		#prompt:knowzcode-work "Build user authentication" — Start a feature
		#prompt:knowzcode-fix "Fix login redirect bug" — Quick fix
		#prompt:knowzcode-continue — Resume where you left off

		@@ -430,5 +426,3 @@ See knowzcode/copilot_execution.md for the full execution guide.
		```
		Optional: Connect to KnowzCode Cloud for AI-powered capabilities:
		New user? /kc:register
		Have a key? /kc:connect-mcp <api-key>
		Optional: For knowledge vault features: `claude plugin install knowz` then `/knowz setup`
		```
		@@ -460,4 +454,4 @@
		1. Review knowzcode/knowzcode_project.md and add project details
		2. Start your first feature: /kc:work "your feature description"
		3. Research first: /kc:plan "your question"
		2. Start your first feature: /knowzcode:work "your feature description"
		3. Research first: /knowzcode:explore "your question"
		```
		@@ -475,2 +469,9 @@

		## Related Skills

		- `/knowzcode:work` — Start first feature after initialization
		- `/knowzcode:explore` — Research the codebase after initialization
		- `/knowz setup` — Configure MCP and vaults
		- `/knowzcode:status` — Verify setup

		## Error Handling
		@@ -477,0 +478,0 @@

+25

-19

skills/start-work/SKILL.md

		---
		name: start-work
		description: "Detect plan implementation intent and redirect to /kc:work with extracted context. Triggers when user expresses intent to implement a plan, findings, or spec"
		description: "Detect plan implementation intent and redirect to /knowzcode:work with extracted context. Triggers when user expresses intent to implement a plan, findings, or spec"
		user-invocable: false
		@@ -10,3 +10,3 @@ allowed-tools: Read, Glob, Grep

		Purpose: Intercept implementation intent phrases and auto-invoke `/kc:work` with appropriate context from plans, investigations, or user statements.
		Purpose: Intercept implementation intent phrases and auto-invoke `/knowzcode:work` with appropriate context from plans, investigations, or user statements.

		@@ -40,3 +40,3 @@ ## Trigger Patterns
		- Must be in a KnowzCode-initialized project (knowzcode/ directory exists)
		- Should NOT trigger during active /kc:* command execution
		- Should NOT trigger during active /knowzcode:* command execution
		- Should have some prior context to extract goal from (plan, investigation, or user statement)
		@@ -50,3 +50,3 @@
		- User says "implement" but in context of explaining something to someone else
		- Already inside a /kc:* command execution
		- Already inside a /knowzcode:* command execution
		- knowzcode/ directory doesn't exist (not a KnowzCode project)
		@@ -91,3 +91,3 @@ - User's message is a continuation of giving new feature requirements (not referencing a prior plan)
		#### Priority B: Recent Investigation
		1. Check `knowzcode/planning/investigation-*.md` for files < 30 min old
		1. Check `knowzcode/planning/*.md` for files < 30 min old
		2. If found: Extract top recommendation and key findings
		@@ -115,9 +115,9 @@ 3. Handle "option N" phrases by extracting that specific option

		Pass full context to /kc:work and let it extract the goal:
		Pass full context to /knowzcode:work and let it extract the goal:

		```
		/kc:work --context "{plan_or_investigation_content}"
		/knowzcode:work --context "{plan_or_investigation_content}"
		```

		The /kc:work command will:
		The /knowzcode:work command will:
		- Parse the context to extract the implementation goal
		@@ -134,4 +134,4 @@ - Handle "option N" references from investigations
		Loading plan context from recent session.
		[Reads plan content, passes full context to /kc:work]
		[/kc:work extracts goal: "Add user authentication with JWT tokens"]
		[Reads plan content, passes full context to /knowzcode:work]
		[/knowzcode:work extracts goal: "Add user authentication with JWT tokens"]
		```
		@@ -144,4 +144,4 @@
		Loading context from: knowzcode/planning/investigation-20250116-143022.md
		[Extracts option 2 content, passes to /kc:work]
		[/kc:work interprets: "Option 2: Refactor error handling with centralized middleware"]
		[Extracts option 2 content, passes to /knowzcode:work]
		[/knowzcode:work interprets: "Option 2: Refactor error handling with centralized middleware"]
		```
		@@ -154,3 +154,3 @@
		Loading context from: knowzcode/planning/investigation-20250116-143022.md
		[Passes top recommendation to /kc:work]
		[Passes top recommendation to /knowzcode:work]
		```
		@@ -164,3 +164,3 @@
		User: Add dark mode toggle to the settings page
		[Passes goal to /kc:work "Add dark mode toggle to the settings page"]
		[Passes goal to /knowzcode:work "Add dark mode toggle to the settings page"]
		```
		@@ -173,3 +173,3 @@
		[Extracts "build the payment integration" as goal]
		[Invokes /kc:work "Build the payment integration"]
		[Invokes /knowzcode:work "Build the payment integration"]
		```
		@@ -184,3 +184,3 @@
		3. Extract the description following that marker
		4. Pass to /kc:work with full option description
		4. Pass to /knowzcode:work with full option description

		@@ -199,5 +199,5 @@ Example investigation content:

		## Integration with /kc:work
		## Integration with /knowzcode:work

		This skill prepares context for /kc:work, which will then:
		This skill prepares context for /knowzcode:work, which will then:
		1. Apply Step 4.5 spec detection to check for existing comprehensive specs
		@@ -219,3 +219,3 @@ 2. Offer optimization paths (Quick/Validation/Full workflow)
		Goal Extracted: "{goal or context summary}"
		Action: Invoked /kc:work
		Action: Invoked /knowzcode:work
		Logged By: AI-Agent
		@@ -225,2 +225,8 @@ ---

		## Related Skills

		- `/knowzcode:work` — The workflow this skill invokes
		- `/knowzcode:explore` — Research before implementing
		- `/knowzcode:continue` — Resume an active WorkGroup instead

		## Skill Configuration
		@@ -227,0 +233,0 @@

+85

-269

skills/status/SKILL.md

		---
		name: status
		description: "Check KnowzCode MCP server connection status and available tools. Use when asked about MCP connectivity, vault health, server status, or to verify KnowzCode setup."
		description: "Check KnowzCode project status — framework health, agent availability, and a brief MCP/vault summary. Use when asked about project status, framework health, or to verify KnowzCode setup."
		user-invocable: true
		@@ -8,25 +8,51 @@ allowed-tools: Read, Glob, Grep, Bash

		# KnowzCode MCP Connection Status
		# KnowzCode Project Status

		You are the KnowzCode Status Agent. Your task is to verify the KnowzCode MCP server configuration and test connectivity.
		You are the KnowzCode Status Agent. Your task is to check the project's framework health and provide a brief MCP/vault summary.

		## What This Checks

		- MCP server configuration status
		- Connection to KnowzCode API
		- Available tools and their status
		- API key validity
		- Code Vault configuration and status
		- Ecosystem Vault configuration and status
		- Finalizations Vault configuration and status
		- Project indexing status
		- KnowzCode framework initialization and file health
		- Agent definitions and availability
		- Active WorkGroups and tracker status
		- Brief MCP/vault connectivity summary

		## When NOT to Trigger

		- User wants to configure MCP or vaults → use `/knowz setup`
		- User wants to save a learning → use `/knowz save`
		- User wants to start building → use `/knowzcode:work`

		## Your Task

		Check Agent Teams status, then check the KnowzCode MCP server status, and report findings to the user.
		Check KnowzCode project status and report findings to the user.

		### Steps to Execute

		1. Check Agent Teams status
		1. Check Framework Initialization

		Verify the `knowzcode/` directory exists and check for required files:
		- `knowzcode/knowzcode_loop.md`
		- `knowzcode/knowzcode_tracker.md`
		- `knowzcode/knowzcode_project.md`
		- `knowzcode/knowzcode_architecture.md`
		- `knowzcode/knowzcode_orchestration.md`

		Report:
		```
		## Framework Status

		KnowzCode Directory: {Found \| Not found}
		Core Files: {count}/{total} present
		- knowzcode_loop.md: {Present \| Missing}
		- knowzcode_tracker.md: {Present \| Missing}
		- knowzcode_project.md: {Present \| Missing}
		- knowzcode_architecture.md: {Present \| Missing}
		- knowzcode_orchestration.md: {Present \| Missing}
		```

		If `knowzcode/` is missing: suggest `/knowzcode:init` and STOP.

		2. Check Agent Teams Status

		Check for agent definition files:
		@@ -44,296 +70,86 @@ - Glob for `agents/*.md`

		Note: Agent Teams availability is no longer checked via settings files. Commands (`/kc:work`, `/kc:plan`, `/kc:audit`) detect availability at runtime by attempting `TeamCreate()` and falling back gracefully. The `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var must still be set at the Claude Code level for Agent Teams to work, but commands do not check for it directly.
		3. Check Active WorkGroups and Tracker

		2. Check MCP server configuration
		- Glob for `knowzcode/workgroups/*.md` — count active (Status: Active) vs completed
		- Read `knowzcode/knowzcode_tracker.md` — count NodeIDs by status ([WIP], [VERIFIED], [PLANNED])
		- Check `knowzcode/knowzcode_log.md` — show last 3 log entries if available

		Detect the current platform and use the appropriate check:
		- Claude Code: `CLAUDECODE= claude mcp get knowz`
		- Gemini CLI: Read `.gemini/settings.json` for `mcpServers.knowz` entry, or run `gemini mcp list`
		- Copilot: Read `.vscode/mcp.json` for knowz server entry
		- Codex: Read `.mcp.json` for knowz server entry
		- Fallback: Read `knowzcode/mcp_config.md` for connection status
		Report:
		```
		## Project Activity

		- If configured: Extract scope, endpoint, headers
		- If not configured: Report and suggest `/kc:connect-mcp`
		Active WorkGroups: {count}
		Completed WorkGroups: {count}
		Tracker: {WIP count} WIP, {VERIFIED count} verified, {PLANNED count} planned
		Recent Log: {last 3 entries or "No entries"}
		```

		3. Cross-Platform Config Discovery
		4. Check Pending Captures

		Check all known MCP config locations and report:
		Check if `knowzcode/pending_captures.md` exists and contains pending capture blocks.

		1. `KNOWZ_API_KEY` env var: Set (ending ...{last4}) \| Not set
		2. `knowzcode/mcp_config.md`: Connected / Not configured
		3. Claude Code (`claude mcp get knowz`): Configured \| Not found
		4. Gemini (`.gemini/settings.json` → `mcpServers.knowz`): Configured \| Not found
		5. Copilot (`.vscode/mcp.json` → `servers.knowz`): Configured \| Not found
		6. Codex (`.mcp.json` → knowz): Configured \| Not found

		Include in output:
		Report:
		```
		Config Sources:
		- Environment (KNOWZ_API_KEY): {status}
		- Project config (mcp_config.md): {status}
		- Claude Code: {status}
		- Gemini CLI: {status}
		- VS Code / Copilot: {status}
		- Codex (.mcp.json): {status}
		```
		## Pending Captures

		If configs found on other platforms but not current:
		"Tip: An API key was found in {source}. Run /kc:connect-mcp to configure for this platform."

		4. Check vault configuration
		- Primary: Read `knowzcode/knowzcode_vaults.md` for multi-vault routing
		- Parse `## Connected Vaults` section
		- Extract all configured vaults (ID, Name, Type, Description)
		- Fallback: Read `knowzcode/mcp_config.md` for legacy single-vault config
		- Extract Code Vault ID and name
		- Extract Ecosystem Vault ID and name
		- Note if no vaults are configured

		5. Verify connection and vault health (if configured)
		- The MCP server should automatically list its available tools
		- Check if tools are accessible
		- If vaults are configured, attempt `list_vaults(includeStats=true)` to verify vault accessibility
		- Report vault document counts and last sync times
		- If vault IDs are configured but inaccessible, show warning with remediation steps

		6. Report status

		If configured and working:
		Pending: {count} capture(s) waiting to be flushed
		```
		✅ KnowzCode MCP Server: Connected

		Configuration:
		• Scope: <local\|project\|user>
		• Endpoint: https://mcp.knowz.io/mcp
		• Status: Active
		If pending captures exist: suggest `/knowz flush` to write them to vaults.

		Connected Vaults (from knowzcode_vaults.md):
		┌────┬──────────────────────┬──────────┬─────────────────────────────────┐
		│ # │ Name │ Type │ Description (routing) │
		├────┼──────────────────────┼──────────┼─────────────────────────────────┤
		│ 1 │ Engineering Knowledge│ ecosystem│ Patterns, decisions, conventions│
		│ 2 │ my-project-code │ code │ Source code for main API │
		│ 3 │ Team Wiki │ ecosystem│ Processes, onboarding │
		└────┴──────────────────────┴──────────┴─────────────────────────────────┘
		5. Brief MCP/Vault Summary

		Vault Routing:
		• Code questions → my-project-code
		• Convention questions → Engineering Knowledge (default ecosystem)
		• Completion records → Finalizations
		• Learning capture → Engineering Knowledge (or prompt if ambiguous)
		Check if `mcp__knowz__list_vaults` is available:
		- If available: call `list_vaults(includeStats=true)` and report vault count + names
		- If not available: report "Knowz MCP not connected. Run `/knowz setup` or configure manually."

		Available Tools:
		✓ search_knowledge - Vector search across vaults
		✓ ask_question - AI Q&A with research mode
		✓ create_knowledge - Save learnings to vault
		✓ update_knowledge - Update existing items
		✓ find_entities - Find people/locations/events

		Project: <project-path>
		Last sync: <if available>

		All systems operational. Agents can use MCP tools.
		Report:
		```
		## MCP & Vaults

		If configured but not working:
		MCP Status: {Connected \| Not connected}
		Vaults: {count} available ({comma-separated names})
		```
		⚠️ KnowzCode MCP Server: Configured but unavailable

		Configuration:
		• Scope: <scope>
		• Endpoint: <endpoint>
		• Status: Cannot connect

		Possible issues:
		• API key may be invalid or expired
		• Network connectivity issues
		• KnowzCode API may be down

		Troubleshooting:
		1. Check your internet connection
		2. Verify API key: https://knowz.io/api-keys
		3. Reconfigure: /kc:connect-mcp <new-key>
		4. Check status: https://status.knowz.io
		Or if not connected:
		```
		## MCP & Vaults

		If MCP connected but vaults not configured:
		MCP Status: Not connected
		Knowz MCP not connected. Run `/knowz setup` or configure manually.
		```
		⚠️ KnowzCode MCP Server: Connected (vaults not configured)

		Configuration:
		• Scope: <scope>
		• Endpoint: <endpoint>
		• Status: Active
		6. Report Overall Status

		Connected Vaults: ⚠️ None configured
		Combine all sections into a single status report.

		MCP is connected but you haven't configured your vaults yet.
		Vaults enable semantic search and learning capture.
		```
		## Overall

		To configure vaults:
		/kc:connect-mcp --configure-vaults
		(Interactive vault discovery and selection)

		Or manually edit: knowzcode/knowzcode_vaults.md
		All systems operational. Ready for /knowzcode:work.
		```

		If not configured at all:
		Or if issues found:
		```
		ℹ️ KnowzCode MCP Server: Not configured
		## Issues Found

		KnowzCode works fine without MCP! All core features work:
		✓ TDD workflow (/kc:work)
		✓ Spec generation
		✓ Impact analysis
		✓ Quality audits

		MCP adds enhanced capabilities:
		• Vector search across indexed code (Code Vault)
		• Convention and pattern lookups (Ecosystem Vault)
		• AI-powered Q&A with research mode
		• Automatic learning capture

		To enable these features:
		New user? /kc:register (creates account + configures)
		Have a key? /kc:connect-mcp <api-key>
		{list issues with suggested remediation}
		```

		7. Additional diagnostics (if helpful)
		- Check if project is indexed (if MCP connected)
		- Show vault document counts and last sync times
		- Report any rate limiting or quota issues
		- List any cached data available
		- Show learning capture status (enabled/disabled)

		## Output Format

		Use clear status indicators:
		- ✅ Green check: Working perfectly
		- ⚠️ Warning: Configured but issues
		- ℹ️ Info: Not configured
		- ❌ Error: Critical failure
		- Present: Working perfectly
		- Missing: File or component not found
		- Warning: Configured but issues detected

		## Connection Details
		## Related Skills

		If connection is active, optionally show:
		- `/knowz setup` — Configure MCP server and vaults
		- `/knowz register` — Register a new Knowz account
		- `/knowzcode:init` — Initialize KnowzCode in project
		- `/knowzcode:work` — Start feature (uses MCP if available)

		```
		Connection Details:
		• Response time: <ms>
		• Tools loaded: <count>
		• Cache status: <enabled/disabled>
		• Rate limit: <remaining/total>
		```

		## MCP Tool Details

		For each available tool, can optionally show:

		```
		search_knowledge
		Description: Vector similarity search across vaults
		Vaults: Code Vault, Ecosystem Vault
		Status: ✓ Available
		Last used: <time>

		ask_question
		Description: AI-powered Q&A with optional research mode
		Vaults: Ecosystem Vault (primary)
		Research Mode: Enabled (8000+ token comprehensive answers)
		Status: ✓ Available
		Last used: <time>

		create_knowledge
		Description: Save learnings to vault
		Vaults: Ecosystem Vault (write)
		Used by: closer, /kc:learn
		Status: ✓ Available
		Last used: <time>
		```

		## Vault Status Details

		If vaults are configured, optionally show:

		```
		Code Vault: my-project-code
		• Documents indexed: <count>
		• Last index: <timestamp>
		• Index status: Up to date / Stale / Indexing...
		• Paths: src/, tests/, packages/

		Ecosystem Vault: engineering-knowledge
		• Documents: <count>
		• Notes: <count>
		• Last updated: <timestamp>
		• Top tags: architecture, security, patterns
		```

		## Error States

		### Invalid API Key
		```
		❌ Authentication Error
		The API key is invalid or expired.

		Update: /kc:connect-mcp <new-key>
		```

		### Network Issues
		```
		❌ Connection Error
		Cannot reach KnowzCode API at <endpoint>

		Check:
		• Internet connection
		• Firewall settings
		• VPN configuration
		```

		### Service Down
		```
		❌ Service Unavailable
		KnowzCode API is not responding.

		Status: https://status.knowz.io
		```

		## Usage Examples

		### Basic status check
		```bash
		/kc:status
		```

		### After configuration
		```bash
		/kc:connect-mcp <api-key>
		# ... restart your AI coding assistant ...
		/kc:status # Verify everything works
		```

		### Troubleshooting
		```bash
		/kc:status # Check what's wrong
		# Follow suggested remediation steps
		```

		## Integration Notes

		This command is useful:
		- After initial setup: Verify `/kc:connect` worked
		- When tools seem unavailable: Debug MCP connection
		- Before starting work: Confirm enhanced features active
		- Troubleshooting: Diagnose connectivity issues

		## Related Commands

		- `/kc:connect-mcp` - Configure MCP server
		- `/kc:init` - Initialize KnowzCode
		- `/kc:work` - Start feature (uses MCP if available)

		## Important Notes

		- Restart required: After `/kc:connect-mcp`, restart your AI coding assistant (Claude Code, Gemini CLI, etc.)
		- Graceful degradation: KnowzCode works without MCP (just less powerful)
		@@ -340,0 +156,0 @@ - No credentials shown: Never display full API keys

+25

-11

skills/telemetry-setup/SKILL.md

		---
		name: telemetry-setup
		description: "Configure telemetry sources (Sentry, App Insights) for /kc:telemetry. Use when the user wants to set up or reconfigure telemetry connections."
		description: "Configure telemetry sources (Sentry, App Insights) for /knowzcode:telemetry. Use when the user wants to set up or reconfigure telemetry connections."
		user-invocable: true
		@@ -11,5 +11,5 @@ allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion

		Configure telemetry sources for `/kc:telemetry` investigations.
		Configure telemetry sources for `/knowzcode:telemetry` investigations.

		Usage: `/kc:telemetry-setup [scope]`
		Usage: `/knowzcode:telemetry-setup [scope]`

		@@ -24,7 +24,14 @@ \| Scope \| Description \|
		```
		/kc:telemetry-setup
		/kc:telemetry-setup sentry
		/kc:telemetry-setup appinsights
		/knowzcode:telemetry-setup
		/knowzcode:telemetry-setup sentry
		/knowzcode:telemetry-setup appinsights
		```

		## When NOT to Trigger

		- User wants to investigate an issue using already-configured telemetry → use `/knowzcode:telemetry`
		- User wants to fix a bug → use `/knowzcode:fix` or `/knowzcode:work`
		- User wants to check MCP status → use `/knowzcode:status`
		- Telemetry sources are already properly configured → suggest `/knowzcode:telemetry` instead

		---
		@@ -117,3 +124,3 @@

		Then run `/kc:telemetry-setup sentry` again.
		Then run `/knowzcode:telemetry-setup sentry` again.
		```
		@@ -131,3 +138,3 @@

		Then run `/kc:telemetry-setup appinsights` again.
		Then run `/knowzcode:telemetry-setup appinsights` again.
		```
		@@ -280,3 +287,3 @@
		You can now run:
		/kc:telemetry "error 500 in staging in the last hour"
		/knowzcode:telemetry "error 500 in staging in the last hour"

		@@ -328,3 +335,3 @@ The telemetry investigator will automatically use the correct

		Then run `/kc:telemetry-setup` again.
		Then run `/knowzcode:telemetry-setup` again.
		```
		@@ -370,3 +377,3 @@
		```bash
		/kc:telemetry "test query in production in the last 5 min"
		/knowzcode:telemetry "test query in production in the last 5 min"
		```
		@@ -379,1 +386,8 @@
		4. Return results (or "no events found" if no matching errors)

		## Related Skills

		- `/knowzcode:telemetry` — Investigate issues using configured sources
		- `/knowzcode:fix` — Fix discovered issues
		- `/knowzcode:work` — Larger remediation workflows
		- `/knowzcode:status` — Check overall KnowzCode/MCP status

+25

-11

skills/telemetry/SKILL.md

		@@ -13,3 +13,3 @@ ---

		Usage: `/kc:telemetry "<natural language description>"`
		Usage: `/knowzcode:telemetry "<natural language description>"`

		@@ -20,8 +20,15 @@ Describe everything in plain English - environment, timeframe, and error context will be extracted automatically.
		```
		/kc:telemetry "in staging in the last 20 min, error 500"
		/kc:telemetry "NullReferenceException in production over the past hour"
		/kc:telemetry "checkout failures in dev since this morning"
		/kc:telemetry "slow API responses in user service today"
		/knowzcode:telemetry "in staging in the last 20 min, error 500"
		/knowzcode:telemetry "NullReferenceException in production over the past hour"
		/knowzcode:telemetry "checkout failures in dev since this morning"
		/knowzcode:telemetry "slow API responses in user service today"
		```

		## When NOT to Trigger

		- User wants to configure telemetry sources → use `/knowzcode:telemetry-setup`
		- User wants to fix a bug identified from telemetry → use `/knowzcode:fix` or `/knowzcode:work`
		- User wants to audit code quality → use `/knowzcode:audit`
		- Telemetry sources are not configured yet → suggest `/knowzcode:telemetry-setup` first

		---
		@@ -87,3 +94,3 @@

		Run `/kc:telemetry-setup` to:
		Run `/knowzcode:telemetry-setup` to:
		1. Detect available telemetry tools
		@@ -105,3 +112,3 @@ 2. Verify authentication

		Run `/kc:telemetry-setup` to verify authentication and configure sources.
		Run `/knowzcode:telemetry-setup` to verify authentication and configure sources.
		```
		@@ -164,4 +171,4 @@
		Next Steps:
		- `/kc:fix {target}` - Apply a micro-fix
		- `/kc:work "Fix {issue}"` - Full implementation workflow
		- `/knowzcode:fix {target}` - Apply a micro-fix
		- `/knowzcode:work "Fix {issue}"` - Full implementation workflow
		```
		@@ -175,4 +182,4 @@
		\|---------\|--------------\|
		\| `/kc:fix` \| Hand off quick fixes discovered \|
		\| `/kc:work` \| Hand off larger remediation tasks \|
		\| `/knowzcode:fix` \| Hand off quick fixes discovered \|
		\| `/knowzcode:work` \| Hand off larger remediation tasks \|
		\| `builder` \| Can invoke telemetry investigation during debugging \|
		@@ -198,1 +205,8 @@ \| `microfix-specialist` \| Can invoke telemetry investigation for verification \|
		```

		## Related Skills

		- `/knowzcode:telemetry-setup` — Configure telemetry sources
		- `/knowzcode:fix` — Apply a micro-fix for discovered issues
		- `/knowzcode:work` — Full implementation for larger remediation
		- `/knowzcode:audit` — Broader code quality scan

+40

-43

skills/work/references/parallel-orchestration.md

		@@ -17,3 +17,3 @@ # Parallel Teams Orchestration — Work Skill (Tier 3)
		- If CONFIGURED entries exist: Set `MCP_ACTIVE = true`, `VAULTS_CONFIGURED = true` — vault agents will verify connectivity independently via their Startup Verification. Announce `MCP Status: Lead probe failed — delegating verification to vault agents`. Proceed to Step 4.
		- If no CONFIGURED entries (all empty IDs or no file): Set `MCP_ACTIVE = false`, announce `MCP Status: Not connected`, skip Group B spawn
		- If no CONFIGURED entries (all empty IDs or no file): Set `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`, announce `MCP Status: Not connected`. Knowledge-liaison still spawns (Group A, unconditional) but provides local context only.
		d. If `list_vaults()` succeeds AND UNCREATED list is non-empty → present the Vault Creation Prompt:
		@@ -41,3 +41,3 @@
		B) Select which to create
		C) Skip — proceed without vaults (can create later with `/kc:connect-mcp --configure-vaults`)
		C) Skip — proceed without vaults (can create later with `/knowz setup`)
		```
		@@ -55,9 +55,4 @@
		Create tasks first, pre-assign, then spawn with task IDs:
		- If `SCOUT_MODE = "full"` (default): spawn 3 context scouts (specs, workgroups, backlog) + analyst + architect (5 agents):
		- `TaskCreate("Scout: specs context")` → `TaskUpdate(owner: "context-scout-specs")`
		- `TaskCreate("Scout: workgroups context")` → `TaskUpdate(owner: "context-scout-workgroups")`
		- `TaskCreate("Scout: backlog context")` → `TaskUpdate(owner: "context-scout-backlog")`
		- If `SCOUT_MODE = "minimal"`: spawn 1 context-scout (combined scan) + analyst + architect (3 agents):
		- `TaskCreate("Scout: combined context")` → `TaskUpdate(owner: "context-scout")`
		- If `SCOUT_MODE = "none"`: spawn analyst + architect only (2 agents). Analyst and architect scan the codebase independently without pre-loaded scout context.
		- Always (knowledge-liaison is unconditional — first agent spawned):
		- `TaskCreate("Knowledge liaison: context & vault coordination")` → `TaskUpdate(owner: "knowledge-liaison")`
		- Always:
		@@ -73,10 +68,6 @@ - `TaskCreate("Phase 1A: Impact analysis for {goal}")` → `TaskUpdate(owner: "analyst")`
		Spawn all Group A agents with their `{task-id}` in the spawn prompt (use spawn prompts from [spawn-prompts.md](spawn-prompts.md)).
		5. Spawn Group B (MCP agents — same turn as Group A): If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`:
		The knowledge-liaison internally dispatches local context scouts and vault reader as subagents — no separate scout agents needed.
		5. Vault status note: The knowledge-liaison handles vault availability internally. If `VAULTS_CONFIGURED = true`, it dispatches `knowz:reader` for vault research. If `VAULTS_CONFIGURED = false`, it still provides local context (scout subagents only). No separate Group B spawn needed.
		6. Spawn Group C (specialist agents — same turn as Group A): If `SPECIALISTS_ENABLED` is non-empty:
		Create tasks first, pre-assign, then spawn with task IDs:
		- `TaskCreate("Knowz-scout: vault queries")` → `TaskUpdate(owner: "knowz-scout")`
		- `TaskCreate("Knowz-scribe: listen")` → `TaskUpdate(owner: "knowz-scribe")`
		Spawn both agents with their `{task-id}` in the spawn prompt.
		If `VAULTS_CONFIGURED = false` or `MCP_AGENTS_ENABLED = false`, skip Group B and log: `Vault agents skipped — no vaults configured` or `Vault agents skipped — MCP agents disabled in orchestration config.`
		6. Spawn Group C (specialist agents — same turn as Groups A and B): If `SPECIALISTS_ENABLED` is non-empty:
		Create tasks first, pre-assign, then spawn with task IDs:
		- If `security-officer` in list: `TaskCreate("Security officer: initial threat scan")` → `TaskUpdate(owner: "security-officer")`
		@@ -87,7 +78,7 @@ - If `test-advisor` in list: `TaskCreate("Test advisor: coverage baseline")` → `TaskUpdate(owner: "test-advisor")`
		If `SPECIALISTS_ENABLED` is empty, skip Group C.
		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.
		7. Roster confirmation — lead lists every spawned agent by name to the user. Include scanners and Group C specialists if active.
		8. All spawned agents work immediately in parallel (knowledge-liaison dispatches scouts and vault reader as subagents; scanners are lightweight general-purpose agents; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-8 agents at Stage 0.
		9. Knowledge-liaison pushes Context Briefings to analyst and architect as results arrive. Specialists work independently on their Stage 0 tasks.

		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.
		Key: The analyst does NOT wait for the knowledge-liaison, scanners, or specialists to finish. It starts scanning the codebase immediately. The knowledge-liaison pushes Context Briefings to analyst and architect as local context and vault results arrive. Scanner findings arrive as broadcasts. The analyst streams `[PRELIMINARY]` NodeID findings to the architect as it discovers them (see Preliminary Findings Protocol). Specialist findings are consumed by the lead at gates.

		@@ -101,3 +92,3 @@ ---
		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:
		4. 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."`
		@@ -137,5 +128,4 @@ - 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."`
		12. Pre-implementation commit: `git add knowzcode/ && git commit -m "KnowzCode: Specs approved for {wgid}"`
		13. Shut down context-scouts (no longer needed after specs approved). Keep knowz-scout alive for vault queries during implementation.
		14. Keep analyst alive briefly (available for scope questions during early implementation)
		15. Keep architect alive through Stage 2 (consultative role — spec clarifications for builders, no code or spec edits)
		13. Keep analyst alive briefly (available for scope questions during early implementation)
		14. Keep architect alive through Stage 2 (consultative role — spec clarifications for builders, no code or spec edits)

		@@ -204,3 +194,3 @@ ---
		- Lead creates parallel compliance task for each reviewer (scoped to their partition)
		- Reviewer checks compliance requirements from knowz-scout findings
		- Reviewer checks compliance requirements from vault research findings
		- Runs alongside ARC audits
		@@ -219,3 +209,3 @@
		- security-officer ↔ test-advisor: Cross-cutting test gaps in security paths (max 2 inter-specialist DMs)
		- project-advisor → knowz-scribe: Idea captures for vault storage
		- project-advisor → knowledge-liaison: Idea captures (`"Consider: {idea}"` — knowledge-liaison dispatches `knowz:writer` if warranted)
		- project-advisor → lead: Backlog proposals (before gap loop)
		@@ -244,11 +234,9 @@
		- Schedule REFACTOR tasks for tech debt
		- Create capture task for knowz-scribe (if active): `TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`, then send DM with task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. Knowz-scout remains available for vault queries during finalization.
		- DM knowledge-liaison for Phase 3 capture (if vaults configured): `"Capture Phase 3: {wgid}. Your task: #{task-id}"` — knowledge-liaison dispatches writer
		- Create final atomic commit
		4. Lead presents completion summary
		5. Wait for scribe Phase 3 capture (if knowz-scribe is active):
		- Check scribe capture task via `TaskGet(task-id)` — wait until status is `completed`
		- Also wait for scribe's Phase 3 confirmation DM
		- Timeout: If >2 minutes after closer completes and scribe task still not complete → DM scribe: `"Status check: Phase 3 capture for {wgid}?"`
		- Hard timeout: If another minute passes with no completion → proceed with shutdown and log `WARNING: Scribe Phase 3 capture did not complete for {wgid}. Vault writes may be incomplete.`
		6. Shutdown order: knowz-scout, knowz-scribe, closer, remaining agents
		5. Wait for writer Phase 3 capture (if knowledge-liaison dispatched a writer):
		- Check writer task via `TaskGet(task-id)` — wait until status is `completed`
		- Timeout: If >2 minutes after closer completes and writer task still not complete → proceed with shutdown and log `WARNING: Writer Phase 3 capture did not complete for {wgid}. Vault writes may be incomplete.`
		6. Shutdown order: closer first, then knowledge-liaison (last agent before team cleanup)
		7. Delete team
		@@ -285,10 +273,6 @@
		\|------\|-----------\|-------\|
		\| Scout: specs context \| (none) \| context-scout-specs \|
		\| Scout: workgroups context \| (none) \| context-scout-workgroups \|
		\| Scout: backlog context \| (none) \| context-scout-backlog \|
		\| Knowz-scout: vault queries \| (none — persistent) \| knowz-scout \|
		\| Knowz-scribe: listen \| (none — persistent) \| knowz-scribe \|
		\| Knowledge liaison: context & vault coordination \| (none — Group A, unconditional) \| knowledge-liaison \|
		\| Scanner: direct codebase scan \| (none) \| scanner-direct \|
		\| Scanner: test coverage scan \| (none) \| scanner-tests \|
		\| Phase 1A analysis \| (none — scouts + scanners enrich via broadcast) \| analyst \|
		\| Phase 1A analysis \| (none — knowledge-liaison pushes context via DM, scanners enrich via broadcast) \| analyst \|
		\| Architect pre-load + speculative research \| (none — receives [PRELIMINARY] DMs from analyst) \| architect \|
		@@ -311,6 +295,7 @@ \| Security officer: initial threat scan \| (none — Group C) \| security-officer \|
		\| Phase 3 finalization \| All audits approved \| closer \|
		\| Scribe: Capture Phase 1A \| Phase 1A (gate approval) \| knowz-scribe \|
		\| Scribe: Capture Phase 2A \| Implement: NodeID-X \| knowz-scribe \|
		\| Scribe: Capture Phase 2B \| All audits approved \| knowz-scribe \|
		\| Scribe: Capture Phase 3 \| Phase 3 finalization \| knowz-scribe \|
		\| Reader: vault queries \| (none — dispatched by knowledge-liaison) \| knowz:reader \|
		\| Writer: Capture Phase 1A \| Phase 1A (gate approval — dispatched by knowledge-liaison) \| knowz:writer \|
		\| Writer: Capture Phase 2A \| Implement: NodeID-X (dispatched by knowledge-liaison) \| knowz:writer \|
		\| Writer: Capture Phase 2B \| All audits approved (dispatched by knowledge-liaison) \| knowz:writer \|
		\| Writer: Capture Phase 3 \| Phase 3 finalization (dispatched by knowledge-liaison) \| knowz:writer \|

		@@ -338,1 +323,13 @@ ---
		The closer agent independently verifies MCP at Phase 3 regardless of this result (see `agents/closer.md` — Startup MCP Verification). This probe is for the user announcement and vault creation opportunity only.

		### Pre-Phase: Context & Knowledge Research (Sequential/Subagent)

		Before spawning the analyst, dispatch the knowledge-liaison for local + vault context:

		1. Dispatch knowledge-liaison:
		- Sequential Teams: Spawn as first teammate. Create task `"Context & knowledge: research for {goal}"`. Wait for completion.
		- Subagent: `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & knowledge research", prompt=<liaison spawn prompt from spawn-prompts.md>)`.
		2. Collect findings from the knowledge-liaison's task summary.
		3. Inject into the analyst spawn prompt as: `> Context Briefing: {liaison findings}`.

		This ensures the analyst and architect receive local project context and vault knowledge even without persistent teammate messaging.

+11

-13

skills/work/references/quality-gates.md

		@@ -36,7 +36,5 @@ # Quality Gates — Work Skill

		Lead responsibility. After gate approval, the lead triggers progress capture. If knowz-scribe is active (Parallel Teams with vaults configured):
		- Create capture task: `TaskCreate("Scribe: Capture Phase 1A")` → `TaskUpdate(owner: "knowz-scribe")`
		- Send message to knowz-scribe with task ID: `"Capture Phase 1A: {wgid}. Your task: #{task-id}"` — the scribe reads the WorkGroup file, extracts scope/risk/decision data, and writes to the appropriate vault
		- `search_knowledge({resolved_domain_vault_id}, "patterns for {domain}")` — pull relevant past learnings to inform specification
		- Share any relevant findings with the architect in the Phase 1B prompt
		Lead responsibility. After gate approval, the lead triggers progress capture. If vaults are configured and knowledge-liaison is active:
		- DM knowledge-liaison: `"Capture Phase 1A: {wgid}. Your task: #{task-id}"`
		- The knowledge-liaison owns extraction, vault routing, and writer dispatch (see `agents/knowledge-liaison.md` — Phase Extraction Guide)

		@@ -81,5 +79,5 @@ ---

		Lead responsibility. After gate approval, the lead triggers progress capture. If knowz-scribe is active (Parallel Teams with vaults configured):
		- Create capture task: `TaskCreate("Scribe: Capture Phase 2A")` → `TaskUpdate(owner: "knowz-scribe")`
		- Send message to knowz-scribe with task ID: `"Capture Phase 2A: {wgid}. Your task: #{task-id}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
		Lead responsibility. After Phase 2A completion, the lead triggers progress capture. If vaults are configured and knowledge-liaison is active:
		- DM knowledge-liaison: `"Capture Phase 2A: {wgid}. Your task: #{task-id}"`
		- The knowledge-liaison owns extraction, vault routing, and writer dispatch (see `agents/knowledge-liaison.md` — Phase Extraction Guide)

		@@ -147,5 +145,5 @@ ---

		Lead responsibility. After gate approval, the lead triggers progress capture. If knowz-scribe is active (Parallel Teams with vaults configured):
		- Create capture task: `TaskCreate("Scribe: Capture Phase 2B")` → `TaskUpdate(owner: "knowz-scribe")`
		- Send message to knowz-scribe with task ID: `"Capture Phase 2B: {wgid}. Your task: #{task-id}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
		Lead responsibility. After gate approval, the lead triggers progress capture. If vaults are configured and knowledge-liaison is active:
		- DM knowledge-liaison: `"Capture Phase 2B: {wgid}. Your task: #{task-id}"`
		- The knowledge-liaison owns extraction, vault routing, and writer dispatch (see `agents/knowledge-liaison.md` — Phase Extraction Guide)

		@@ -156,4 +154,4 @@ ---

		When complete, if MCP is configured and knowz-scribe is active:
		- The closer creates a capture task (`TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`) and sends a message with the task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. The lead waits for the scribe's capture task to complete before shutdown.
		When complete, if MCP is configured, vaults are available, and knowledge-liaison is active:
		- The closer DMs knowledge-liaison: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. The knowledge-liaison dispatches `knowz:writer` for Phase 3 capture. The lead waits for the writer task to complete before shutdown.

		@@ -160,0 +158,0 @@ Update workgroup to "Closed" and report:

+27

-85

skills/work/references/spawn-prompts.md

		@@ -7,57 +7,2 @@ # Agent Spawn Prompts — Work Skill

		## Stage 0: Context Scouts (3 instances)

		Agent: `context-scout` (x3) \| Read-only local context researchers

		Three instances of the same agent, each focused on a different local folder group:

		context-scout-specs spawn prompt:
		> You are `context-scout-specs` for WorkGroup `{wgid}`.
		> Read `agents/context-scout.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> Focus area: `knowzcode/specs/*.md` — scan existing specifications.
		> Goal: {goal}
		> READ-ONLY. Do NOT modify any files.
		> Deliverable: Broadcast relevant spec findings (NodeIDs, status, VERIFY criteria overlapping with goal).

		context-scout-workgroups spawn prompt:
		> You are `context-scout-workgroups` for WorkGroup `{wgid}`.
		> Read `agents/context-scout.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> Focus area: `knowzcode/workgroups/*.md` — scan previous WorkGroups for similar goals.
		> Goal: {goal}
		> READ-ONLY. Do NOT modify any files.
		> Deliverable: Broadcast prior WorkGroup context (what was tried, what succeeded/failed, patterns).

		context-scout-backlog spawn prompt:
		> You are `context-scout-backlog` for WorkGroup `{wgid}`.
		> Read `agents/context-scout.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> Focus area: `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_log.md`, `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_project.md`
		> Goal: {goal}
		> READ-ONLY. Do NOT modify any files.
		> Deliverable: Broadcast active WIP, REFACTOR tasks, architecture summary, and recent log patterns relevant to goal.

		context-scout (combined) spawn prompt (used when `SCOUT_MODE = "minimal"`):
		> You are `context-scout` for WorkGroup `{wgid}`.
		> Read `agents/context-scout.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately. Mark completed with summary when done.
		> Focus area: ALL local context — `knowzcode/specs/.md`, `knowzcode/workgroups/.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_log.md`, `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_project.md`
		> Goal: {goal}
		> READ-ONLY. Do NOT modify any files.
		> Deliverable: Broadcast consolidated findings covering specs, prior workgroups, active WIP, REFACTOR tasks, and architecture context.

		Dispatch:
		- Parallel Teams:
		- `SCOUT_MODE = "full"`: 3 context scouts spawned at Stage 0. Shut down after Gate #2.
		- `SCOUT_MODE = "minimal"`: 1 context-scout (combined) spawned at Stage 0. Shut down after Gate #2.
		- `SCOUT_MODE = "none"`: No scouts spawned.
		- Sequential Teams: Not applicable (scouts are Parallel Teams only).
		- Subagent:
		- `SCOUT_MODE = "full"`: 3 parallel `Task()` calls (specs, workgroups, backlog).
		- `SCOUT_MODE = "minimal"`: 1 `Task()` call with combined prompt.
		- `SCOUT_MODE = "none"`: Skip scout tasks.

		---

		## Stage 0: Codebase Scanners (2 instances — conditional)
		@@ -108,39 +53,33 @@

		## Stage 0: Knowz Scout
		## Stage 0: Context & Knowledge Liaison (Persistent)

		Agent: `knowz-scout` \| MCP vault researcher and knowledge agent
		Agent: `knowledge-liaison` \| Persistent context and vault coordination agent

		Spawn prompt:
		> You are the knowz-scout for WorkGroup `{wgid}`.
		> Read `agents/knowz-scout.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are the knowledge-liaison for WorkGroup `{wgid}`.
		> Read `agents/knowledge-liaison.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`).
		> Goal: {goal}
		> Step 1: Read `knowzcode/knowzcode_vaults.md` to discover configured vaults — their IDs, types, descriptions, and what knowledge each contains.
		> Step 2: For each configured vault, construct goal-relevant queries using the vault's description to guide what to ask. If a single vault covers all knowledge, consolidate queries there.
		> Deliverable: Broadcast vault knowledge findings to all teammates.
		> Vault config: `knowzcode/knowzcode_vaults.md`
		> Lifecycle: You persist from Stage 0 through team shutdown. You are the last agent shut down before team cleanup.
		> Parallel dispatch: At startup, dispatch scout and reader subagents in parallel (see `agents/knowledge-liaison.md` Startup). Push Context Briefing to analyst and architect.
		> Ongoing: Accept capture DMs from the lead (at quality gates) and closer (Phase 3). Accept `"Log: ..."` and `"Consider: ..."` from any agent. Accept `"VaultQuery: ..."` from any agent. Dispatch `knowz:writer` and `knowz:reader` as needed.

		Dispatch:
		- Parallel Teams: Group B — spawned at Stage 0 if `VAULTS_CONFIGURED = true`, no blockedBy. Persistent — stays alive through the entire workflow. Shut down after Phase 3 capture is complete.
		- Sequential Teams: Not applicable (scouts are Parallel Teams only).
		- Subagent: `Task(subagent_type="knowz-scout", description="Query vault for domain knowledge", prompt=<above>)` (only if MCP Probe passes)
		- Parallel Teams: Group A — always spawned at Stage 0. Persistent — last agent shut down before team cleanup.
		- Sequential Teams: Spawn as first teammate. Create task `"Context & knowledge: research for {goal}"`. Wait for completion. Include findings in analyst spawn prompt as `> Context Briefing: {liaison findings}`.
		- Subagent: `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & knowledge research", prompt=<spawn prompt>)`. Include results in analyst spawn prompt.

		---

		## Stage 0: Knowz Scribe
		## Quality Gate Writer Dispatches

		Agent: `knowz-scribe` \| Persistent vault write agent (Haiku)
		Agent: `knowz:writer` \| Dispatched by knowledge-liaison at each quality gate

		Spawn prompt:
		> You are the knowz-scribe for WorkGroup `{wgid}`.
		> Read `agents/knowz-scribe.md` for your full role definition.
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> WorkGroup file: `knowzcode/workgroups/{wgid}.md`
		> Vault config: Read `knowzcode/knowzcode_vaults.md` to discover configured vaults and resolve vault IDs by type.
		> You are a message-driven agent. Wait for capture messages from teammates (e.g., "Capture Phase 1A: {wgid}"). On each message, read the WorkGroup file, extract relevant learnings, and write to the appropriate vault.
		> Do NOT read or modify source code. You only read knowzcode/ files and write to MCP vaults.
		Writers are dispatched by the knowledge-liaison at each quality gate. The lead DMs knowledge-liaison with capture requests (see [quality-gates.md](quality-gates.md)); knowledge-liaison constructs self-contained writer prompts and dispatches. Writers are non-persistent — each dispatch completes its writes and exits.

		Dispatch:
		- Parallel Teams: Group B — spawned at Stage 0 if `VAULTS_CONFIGURED = true`, no blockedBy. Persistent — stays alive through the entire workflow. Shut down after Phase 3 capture is complete.
		- Sequential Teams: Not applicable (knowz-scribe is Parallel Teams only).
		- Subagent: Not applicable — vault writes in subagent mode are handled by the closer during Phase 3 finalization (see Direct Write Fallback in `agents/closer.md`).
		- Parallel Teams: Lead DMs knowledge-liaison at Gates #1, Phase 2A, Phase 2B. Closer DMs knowledge-liaison at Phase 3. Knowledge-liaison dispatches `knowz:writer` for each.
		- Sequential Teams: Not applicable — vault writes are handled by the closer during Phase 3 finalization (see Learning Capture in `agents/closer.md`).
		- Subagent: `Task(subagent_type="knowz:writer", description="Capture Phase {N} learnings", prompt=<gate-specific prompt>)`

		@@ -199,3 +138,3 @@ ---
		> Lifecycle: You shut down mid-Stage 2 after delivering backlog proposals — before the gap loop.
		> Communication: DM lead with backlog context and proposals. DM knowz-scribe with idea captures (if active). Do NOT DM builders or other specialists.
		> Communication: DM lead with backlog context and proposals. Include idea captures in your proposals — the lead dispatches `knowz:writer` if warranted. Do NOT DM builders or other specialists.
		> Enterprise Compliance: If `knowzcode/enterprise/compliance_manifest.md` exists, note compliance configuration gaps in backlog proposals.
		@@ -219,2 +158,3 @@
		> Conventions: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
		> Context: The knowledge-liaison will DM you a Context Briefing with local project context and vault knowledge. Incorporate its findings into your analysis. For additional queries, DM: `"VaultQuery: {question}"`.
		> 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.
		@@ -225,3 +165,3 @@ > 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.
		Dispatch:
		- Parallel Teams: Spawned at Stage 0 alongside scouts, scanners, and architect. Starts immediately (no blockedBy).
		- Parallel Teams: Spawned at Stage 0 alongside knowledge-liaison, scanners, and architect. Starts immediately (no blockedBy).
		- Sequential Teams: Spawn teammate `analyst`, create task `Phase 1A: Impact analysis for "{goal}"`, wait for completion.
		@@ -248,2 +188,3 @@ - Subagent: `Task(subagent_type="analyst", description="Phase 1A impact analysis", prompt=<above>)`
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> Context: The knowledge-liaison will DM you a Context Briefing with local project context and vault knowledge. Incorporate its findings into speculative research. For additional queries, DM: `"VaultQuery: {question}"`.
		> 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.
		@@ -316,2 +257,3 @@ > 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.
		> Conventions: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
		> Context: The knowledge-liaison can provide vault knowledge. DM: `"VaultQuery: {question}"` for patterns and best practices before writing tests.
		> TDD mandatory: Write failing tests first, then implement, then refactor. Every NodeID must have tests.
		@@ -370,4 +312,4 @@ > Blocker protocol: If you hit a blocker, document it as a Blocker Report in the WorkGroup file (see loop.md Section 11 format) and report to the lead immediately instead of guessing.
		> Conventions: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
		> Vault writes: Knowz-scribe is active. Create a capture task (`TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`), then send `"Capture Phase 3: {wgid}. Your task: #{task-id}"` to delegate learning capture and audit trail writes. Do NOT call `create_knowledge` directly.
		> Deliverable: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, delegate learning capture to knowz-scribe, and create final commit.
		> Vault writes: DM knowledge-liaison for Phase 3 capture: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. The knowledge-liaison dispatches `knowz:writer`. Do NOT call `create_knowledge` directly.
		> Deliverable: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, dispatch learning capture to `knowz:writer`, and create final commit.

		@@ -386,3 +328,3 @@ Spawn prompt (Sequential Teams / Subagent):
		> Conventions: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
		> Vault writes: No knowz-scribe — you own all vault writes. Follow the Direct Write Fallback in `agents/closer.md`.
		> Vault writes: You own all vault writes directly. Follow the Learning Capture instructions in `agents/closer.md`.
		> MCP Status: {MCP_ACTIVE} — Vaults configured: {VAULTS_CONFIGURED}. Vault config: `knowzcode/knowzcode_vaults.md`.
		@@ -392,4 +334,4 @@ > Deliverable: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, write learnings to vaults, and create final commit.
		Dispatch:
		- Parallel Teams: Spawned at Stage 3 (`addBlockedBy`: last audit/re-audit task). Use the Parallel Teams spawn prompt. All other agents shut down before closer starts, except knowz-scout and knowz-scribe (stay alive for Phase 3 capture).
		- Parallel Teams: Spawned at Stage 3 (`addBlockedBy`: last audit/re-audit task). Use the Parallel Teams spawn prompt. All other agents shut down before closer starts.
		- Sequential Teams: Spawn teammate `closer`, create task `Phase 3: Finalize WorkGroup {wgid}`, wait for completion. Use the Sequential Teams / Subagent spawn prompt.
		- Subagent: `Task(subagent_type="closer", description="Phase 3 finalization", prompt=<Sequential/Subagent spawn prompt above>)`

+42

-16

skills/work/SKILL.md

		---
		name: work
		description: "Start a new KnowzCode development workflow with TDD, quality gates, and structured phases. Use when asked to build, implement, create, or develop a feature or capability."
		description: "Execute a full KnowzCode development workflow — TDD, quality gates, agent coordination, and structured implementation phases. Use when the user wants to BUILD, IMPLEMENT, or CREATE code, not just research or audit."
		user-invocable: true
		allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task
		# Note: Also uses MCP tools (create_knowledge, search_knowledge) when MCP is configured
		argument-hint: "[feature_description]"
		@@ -13,7 +14,22 @@ ---

		Usage: `/kc:work "feature description"`
		Example: `/kc:work "Build user authentication with JWT"`
		Usage: `/knowzcode:work "feature description"`
		Example: `/knowzcode:work "Build user authentication with JWT"`

		Primary Goal: $ARGUMENTS

		## When NOT to Trigger

		- User wants to research or explore without implementing → use `/knowzcode:explore`
		- User wants a single-file micro-fix (<50 lines, no ripple effects) → use `/knowzcode:fix`
		- User wants to audit or scan existing code quality → use `/knowzcode:audit`
		- User is asking a question (starts with how/why/what/should, contains `?`)
		- User wants to save a learning → use `/knowz save`

		## Common Invocation Patterns

		These phrases indicate `/knowzcode:work` intent:
		- "build X", "implement X", "create X", "develop X"
		- "add feature for X", "make X work", "set up X"
		- "refactor X to Y", "migrate X to Y"

		---
		@@ -27,3 +43,3 @@

		If missing: inform user to run `/kc:init` first. STOP.
		If missing: inform user to run `/knowzcode:init` first. STOP.

		@@ -71,11 +87,9 @@ ## Step 1: Generate WorkGroup ID
		1. `MAX_BUILDERS` = `max_builders` value (default: 5, clamp to 1-5)
		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)
		2. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
		3. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
		4. `CODEBASE_SCANNER_ENABLED` = `codebase_scanner_enabled` value (default: true)
		5. `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`
		@@ -182,3 +196,3 @@ - `--no-scanners` in `$ARGUMENTS` → override `CODEBASE_SCANNER_ENABLED = false`

		Question indicators (suggest `/kc:plan` instead): starts with is/does/how/why/what/should, contains `?`, phrased as inquiry.
		Question indicators (suggest `/knowzcode:explore` instead): starts with is/does/how/why/what/should, contains `?`, phrased as inquiry.

		@@ -193,3 +207,3 @@ Implementation indicators (proceed): starts with build/add/create/implement/fix/refactor, action-oriented verbs.

		### Tier 1: Micro → redirect to `/kc:fix`
		### Tier 1: Micro → redirect to `/knowzcode:fix`
		- Single file, <50 lines, no ripple effects
		@@ -318,6 +332,10 @@

		- Stage 0: Create team, MCP probe, spawn scout/analyst/architect/scanner/MCP/specialist agents in parallel
		> MCP Probe Design Note: Multiple agents perform independent MCP verification (`list_vaults()`) at different points in the workflow. This redundancy is intentional — agents spawn at different times and MCP connectivity can change between spawns. Each agent's probe is authoritative for its own MCP state.
		>
		> Vault Creation Failure Recovery: If BOTH `create_vault()` and name-matching fallback fail: log failure, set `VAULTS_CONFIGURED = false`, continue without vault. Report: `"⚠️ Vault creation failed — proceeding without knowledge capture. Run /knowz setup to retry."`

		- Stage 0: Create team, MCP probe, spawn knowledge-liaison/analyst/architect/scanner/specialist agents in parallel
		- Stage 1: Analyst completes Change Set → Gate #1 → Architect drafts specs → Gate #2
		- Stage 2: Parallel builders (1 per independent partition) + paired reviewers + gap loop
		- Stage 3: Closer finalizes, scribe captures, shutdown
		- Stage 3: Closer finalizes, dispatches writer for captures, shutdown

		@@ -328,3 +346,3 @@ ---

		Spawn Prompts: Read [references/spawn-prompts.md](references/spawn-prompts.md) before spawning any agent. Contains spawn prompts for all phases: context scouts, codebase scanners, knowz-scout, knowz-scribe, specialists (security-officer, test-advisor, project-advisor), analyst (Phase 1A), architect (Phase 1B), builder (Phase 2A), reviewer (Phase 2B), and closer (Phase 3).
		Spawn Prompts: Read [references/spawn-prompts.md](references/spawn-prompts.md) before spawning any agent. Contains spawn/dispatch prompts for all phases: knowledge-liaison, codebase scanners, knowz:reader, knowz:writer dispatches, specialists (security-officer, test-advisor, project-advisor), analyst (Phase 1A), architect (Phase 1B), builder (Phase 2A), reviewer (Phase 2B), and closer (Phase 3).

		@@ -368,3 +386,3 @@ Quality Gates: Read [references/quality-gates.md](references/quality-gates.md) at quality gate checkpoints. Contains gate templates (#1 Change Set, #2 Specifications, #3 Audit Results), autonomous mode handling, specialist report sections, gap loop mechanics, and progress capture instructions.

		The WorkGroup file remains in `knowzcode/workgroups/` for reference. It can be resumed later with `/kc:work` referencing the same goal.
		The WorkGroup file remains in `knowzcode/workgroups/` for reference. It can be resumed later with `/knowzcode:work` referencing the same goal.

		@@ -381,4 +399,12 @@ ---

		## Related Skills

		- `/knowzcode:explore` — Research and explore before implementing
		- `/knowzcode:fix` — Single-file micro-fix (<50 lines)
		- `/knowzcode:audit` — Read-only quality and security scan
		- `/knowz save` — Capture learnings to vault
		- `/knowzcode:continue` — Resume an active WorkGroup

		## KnowzCode: Prefix Enforcement

		Every task item in workgroup files MUST start with `KnowzCode:`. Pass this to all agents.

-22

.claude-plugin/marketplace.json

		{
		"name": "knowzcode-marketplace",
		"owner": {
		"name": "Alex Headscarf",
		"email": "alexheadscarf@gmail.com"
		},
		"metadata": {
		"description": "Official KnowzCode plugin marketplace - Platform-agnostic AI development methodology",
		"version": "0.7.2"
		},
		"plugins": [
		{
		"name": "kc",
		"source": "./",
		"description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
		"version": "0.7.2",
		"author": {
		"name": "Alex Headscarf"
		}
		}
		]
		}

-54

agents/context-scout.md

 ---
 name: context-scout
 description: "KnowzCode: Local context researcher — specs, workgroups, history"
 tools: Read, Glob, Grep
 model: sonnet
 permissionMode: default
 maxTurns: 15
 ---
 # Context Scout
 You are the **Context Scout** in a KnowzCode development workflow.
 Your expertise: Local knowzcode context research — specs, workgroups, tracker history, and architecture.
 ## Your Job
 Read all local knowzcode context files and broadcast key findings to the team. You run in parallel with the analyst and architect during Stage 0, providing them with historical and structural context.
 **This is a READ-ONLY role.** You MUST NOT modify, create, or delete any files. You do not write code, specs, or project files. You only read and broadcast findings. Implementation is the builder's responsibility.
 ## What to Read
 Your spawn prompt assigns your specific focus area from the list below. Read only the files in your assigned focus area. If your spawn prompt assigns ALL focus areas (combined scan), read across all file types listed below and deliver consolidated findings covering all five deliverable categories.
 **Full file landscape** (for reference — your focus area is a subset):
 - `knowzcode/knowzcode_tracker.md` — active NodeIDs, WIP items, REFACTOR tasks
 - `knowzcode/knowzcode_log.md` — recent completions, patterns, past decisions
 - `knowzcode/knowzcode_architecture.md` — component map, layer structure
 - `knowzcode/knowzcode_project.md` — project goals, stack, standards
 - `knowzcode/specs/*.md` — existing specifications (scan titles + key sections)
 - `knowzcode/workgroups/*.md` — previous WorkGroups for similar goals
 ## Deliverables
 Broadcast to team (1-2 focused broadcasts, NOT one per file):
 . **Relevant existing specs** — NodeIDs, status, key VERIFY criteria that overlap with current goal
 . **Prior WorkGroup context** — what was tried before, what succeeded/failed
 . **Active WIP** — anything currently in progress that might conflict
 . **REFACTOR tasks** — outstanding debt items that overlap with current scope
 . **Architecture summary** — component map and layer info relevant to the goal
 ## Communication
 - Use `broadcast` to share findings with all teammates
 - Send 1-2 focused broadcasts consolidating all findings (not one per file read)
 - Stay available for follow-up questions from analyst/architect via direct messages
 - Keep responses concise — teammates need actionable context, not raw file dumps
 ## Exit Expectations
 - All relevant local context broadcast to the team
 - Available for follow-up queries until shut down by the lead (typically after Gate #2)

-83

agents/knowz-scout.md

		---
		name: knowz-scout
		description: "KnowzCode: MCP vault researcher — business knowledge, conventions, decisions"
		tools: Read, Glob, Grep
		model: sonnet
		permissionMode: default
		maxTurns: 15
		---

		# Knowz Scout

		You are the Knowz Scout in a KnowzCode development workflow.
		Your expertise: MCP vault research — business knowledge, team conventions, and past decisions.

		Only spawned if MCP is connected (lead checks `knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`).

		## Your Job

		Query MCP vaults for business knowledge, team conventions, and past decisions relevant to the current goal. You run in parallel with the analyst and architect during Stage 0, providing them with organizational knowledge.

		Your primary job is vault research and local context discovery. You have read access to MCP vaults and read/write access to local knowzcode files. You do not write source code — implementation is the builder's responsibility.

		## Lifecycle

		- Spawned: Stage 0 Group B (alongside knowz-scribe, if `MCP_ACTIVE = true`)
		- Active through: Phase 3 finalization
		- Shutdown: After closer completes and Phase 3 capture is done, lead shuts you down

		## Startup Verification

		On spawn, as your first action before any queries:

		1. Read `knowzcode/knowzcode_vaults.md` for configured vaults and their IDs
		2. Call `list_vaults(includeStats=true)` to verify MCP connectivity
		3. If fails: broadcast `"Knowz-scout: MCP unavailable — {error}"`, mark your task complete, and exit
		4. If succeeds: proceed to Query Process below

		## Query Process (2-Step Dynamic Discovery)

		### Step 1: Discover Configured Vaults

		1. Read `knowzcode/knowzcode_vaults.md` to find configured vaults — their IDs, types, descriptions, and what knowledge each contains
		2. If no vaults are configured in the file, call `list_vaults(includeStats=true)` as fallback to discover available vaults
		3. Identify each vault's ID, type (e.g., "code", "ecosystem", "finalizations"), description, and example queries
		4. Skip vault entries with empty ID fields — these haven't been created on the server yet
		5. Treat backwards-compat aliases identically: `research`/`domain`/`platform` = `ecosystem`, `sessions` = `finalizations`

		### Step 2: Query Each Vault Based on Its Description

		For each configured vault, construct goal-relevant queries using the vault's declared description and type to determine what questions are appropriate:

		- Code-type vault → similar implementations, component patterns (`search_knowledge` for targeted lookups)
		- Ecosystem-type vault → conventions, past decisions, best practices, integrations, business rules (`search_knowledge` for targeted lookups, `ask_question(researchMode=true)` for comprehensive pulls)
		- Finalizations-type vault → past WorkGroup completions, outcome records, finalization details (`search_knowledge` for targeted lookups)
		- User-added types (e.g., enterprise) → query based on the vault's declared description and purpose
		- Single vault covering all types (common for new users) → consolidate all questions to that one vault

		Never hardcode vault names. Always resolve vault IDs from the config.

		## Deliverables

		Broadcast to team (1-2 focused broadcasts):

		1. Team conventions relevant to the goal
		2. Past decisions that constrain or inform the approach
		3. Similar implementations found in the code vault
		4. Compliance requirements (if enterprise enabled)

		## Communication

		- Use `broadcast` to share findings with all teammates
		- Send 1-2 focused broadcasts consolidating all vault results
		- Stay available for follow-up vault queries from any teammate
		- Keep responses concise — teammates need actionable knowledge, not raw vault dumps

		## MCP Graceful Degradation

		If MCP queries fail or return no results, broadcast that finding too — the team should know that no prior organizational knowledge exists for this domain.

		## Exit Expectations

		- All relevant vault knowledge broadcast to the team
		- Available for follow-up vault queries until shut down by the lead (after Phase 3 finalization)

-180

agents/knowz-scribe.md

		---
		name: knowz-scribe
		description: "KnowzCode: MCP vault writer — routes and captures learnings to vaults"
		tools: Read, Write, Edit, Glob, Grep
		model: sonnet
		permissionMode: acceptEdits
		maxTurns: 20
		---

		# Knowz Scribe

		You are the Knowz Scribe in a KnowzCode development workflow.
		Your expertise: MCP vault writes — routing learnings, decisions, and audit records to the correct vaults.

		Only spawned if MCP is connected (lead checks `knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`).

		## Your Job

		Receive capture requests from the lead or other agents, read the WorkGroup to extract relevant content, determine the correct target vault(s) using write conditions and content filters, dedup-check, and write. You run as a persistent agent from Stage 0 through Phase 3.

		Your primary job is vault capture and routing. You have full read/write access to both local knowzcode files and MCP vaults. You own all `create_knowledge` calls. You do not write source code — implementation is the builder's responsibility.

		## Lifecycle

		- Spawned: Stage 0 Group B (alongside knowz-scout, if `MCP_ACTIVE = true`)
		- Active through: Phase 3 finalization
		- Shutdown: After closer completes, lead shuts you down

		## Startup Verification

		On spawn, BEFORE waiting for capture messages, perform these checks:

		1. Read `knowzcode/knowzcode_vaults.md` to discover configured vaults and their IDs
		2. Call `list_vaults()` to verify MCP connectivity and warm the session
		3. DM the lead with your status:
		- Success: `"Knowz-scribe ready. MCP verified. N vault(s) accessible."`
		- Failure: `"Knowz-scribe: MCP verification failed — {error}. Vault writes will be unavailable."`

		This catches MCP issues at Stage 0 instead of 10+ minutes later at first capture, and warms the MCP session to prevent timeout during idle gaps between phases.

		## Capture Request Format

		You receive capture requests from the lead or other agents in three forms:

		### Phase Captures (task-tracked)
		Format: `"Capture Phase {phase}: {wgid}. Your task: #{task-id}"`

		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
		2. Read `knowzcode/knowzcode_vaults.md` to discover configured vaults, their write conditions, and content filters
		3. Skip vault entries with empty ID fields — these haven't been created on the server yet
		4. Treat backwards-compat aliases identically: `research`/`domain`/`platform` = `ecosystem`, `sessions` = `finalizations`

		### Step 2: Determine Target Vaults

		Match the capture content against each vault's Write Conditions. A vault is a target if the content satisfies its conditions. Multiple vaults may match (e.g., a decision learning goes to `ecosystem`, an audit trail goes to `enterprise`).

		Use the Learning Category Routing table to map detected learning types to vault types:

		\| Learning Category \| Target Vault Type \|
		\|-------------------\|-------------------\|
		\| Pattern \| `code` \|
		\| Workaround \| `code` \|
		\| Performance \| `code` \|
		\| Decision \| `ecosystem` \|
		\| Convention \| `ecosystem` \|
		\| Security \| `ecosystem` \|
		\| Integration \| `ecosystem` \|
		\| Scope \| `ecosystem` \|
		\| Audit trail \| user's enterprise vault (if configured) \|
		\| Completion record \| `finalizations` \|

		If only a single vault is configured (common for new users), route everything there.

		If multiple vaults match the target type, use the first one listed in `knowzcode/knowzcode_vaults.md`. Users control priority by ordering entries.

		### Step 3: Format Content

		For each target vault, apply its Content Filter to format the `create_knowledge` payload:

		> 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

		Before writing, call `search_knowledge(title, vaultId, 3)` on the target vault. If a result with a substantially similar title AND content already exists, skip the write and log the dedup catch.

		### Step 5: Write

		Call `create_knowledge` with the formatted payload for each target vault.

		## Phase-Specific Extraction

		### Phase 1A (Scope Approved)
		Extract from WorkGroup:
		- 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:
		- 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 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: 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 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 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 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

-196

knowzcode/mcp_config.md

		# KnowzCode MCP Configuration

		## Connection Status
		- Connected: Yes (OAuth)
		- Endpoint: https://mcp.knowz.io/mcp
		- Last Verified: 2026-03-08
		- API Key (last 4): OAuth Token

		> Not configured? Run `/kc:register` to create an account and set up MCP automatically,
		> or `/kc:connect-mcp <api-key>` if you already have a key.

		> Environment variable: Set `KNOWZ_API_KEY` in your shell to enable automatic
		> MCP authentication on any platform without interactive prompts.
		> All `/kc:connect-mcp` and `/kc:register` commands check this variable first.

		---

		## Vaults

		### Ecosystem Vault (Primary)
		- Vault ID: (not configured)
		- Vault Name: (not configured)
		- Purpose: Decisions, conventions, security practices, integrations, business rules, domain knowledge
		- Auto-configured: Yes

		Query Patterns (when configured):
		- "Our error handling conventions"
		- "What patterns for API versioning?"
		- "Security best practices we use"
		- "Why did we choose Redis cache?"
		- "Stripe webhook setup"

		> Backwards compatibility: Vaults previously configured as type `research`, `domain`, or `platform` are treated identically to `ecosystem`. No migration needed.

		### Code Vault (Optional)
		- Vault ID: (not configured)
		- Vault Name: (not configured)
		- Purpose: Implementation patterns, workarounds, performance optimizations

		Note: Code search works well with local grep/glob for most projects.
		Configure a code vault for teams that want semantic search over implementation patterns and reusable utilities.

		Query Patterns (when configured):
		- "Retry logic pattern"
		- "Workaround for rate limiting"
		- "Performance optimization for bulk inserts"
		- "JWT validation pattern"

		### Finalizations Vault (Optional)
		- Vault ID: (not configured)
		- Vault Name: (not configured)
		- Purpose: WorkGroup completion summaries, outcome records, finalization details

		Note: Finalizations vault provides a searchable history of completed work.
		Useful for teams that want to review past work patterns and outcomes.

		Query Patterns (when configured):
		- "What happened in WG-feat-auth?"
		- "Recent completion outcomes"
		- "Goals we worked on last week"

		---

		## Single Vault Model (Recommended for New Users)

		KnowzCode recommends starting with a single "KnowzCode" vault for simplicity:

		```
		┌──────────────────────────────────────────────────────┐
		│ KnowzCode Vault │
		│ │
		│ Purpose: All learnings, decisions, patterns, etc. │
		│ Read by: knowz-scout, knowz-scribe, all agents │
		│ Written by: knowz-scribe, knowz-scout, /kc:learn │
		│ Code search: Uses local grep/glob (no code vault) │
		│ │
		└──────────────────────────────────────────────────────┘
		```

		Why single vault?
		- Simpler onboarding (no vault type decisions needed)
		- Code search works fine with grep/glob for most projects
		- MCP vault is optimized for organizational knowledge, not code indexing
		- Advanced users can add specialized vaults later via `/kc:connect-mcp --configure-vaults`

		---

		## Usage in Agents

		\| Agent \| Vault Interaction \| Purpose \|
		\|-------\|-------------------\|---------\|
		\| knowz-scout \| Read all configured vaults \| Find past decisions, conventions, patterns \|
		\| knowz-scribe \| Read and write to matching vaults \| Route learnings per write conditions \|
		\| analyst \| Read via knowz-scout \| Past decisions + affected code patterns \|
		\| architect \| Read via knowz-scout \| Conventions + implementation examples \|
		\| builder \| Read via knowz-scout \| Best practices + similar patterns \|
		\| reviewer \| Read via knowz-scout \| Standards + precedent check \|
		\| closer \| Triggers knowz-scribe captures \| Finalization learnings \|

		Fallback behavior: When specialized vaults are not configured, agents use local grep/glob
		for code search and the single vault for all knowledge queries.

		---

		## MCP Tools Reference

		### Query Tools (Read — used by knowz-scout)

		search_knowledge(query, vaultId, limit)
		- Vector similarity search across indexed content
		- Use for: finding code patterns or documentation
		- Example: `search_knowledge("authentication logic", ecosystem_vault_id, 10)`

		ask_question(question, vaultId, researchMode)
		- AI-powered question answering with document synthesis
		- `researchMode: false` - Quick answer (faster)
		- `researchMode: true` - Comprehensive answer (8000+ tokens, multi-document)
		- Example: `ask_question("What are our error handling conventions?", ecosystem_vault_id, true)`

		find_entities(entityType, query, limit)
		- Find people, locations, or events extracted from knowledge base
		- `entityType`: "person", "location", or "event"
		- Example: `find_entities("person", "John", 25)`

		get_knowledge_item(id, includeRelated)
		- Retrieve a specific knowledge item by ID
		- `includeRelated: true` to include related items

		list_vaults(includeStats)
		- List all accessible vaults with optional statistics

		### Write Tools (used by knowz-scribe and /kc:learn)

		create_knowledge(content, title, knowledgeType, vaultId, tags, source)
		- Create new knowledge item in vault
		- `knowledgeType`: "Document", "Note", or "Transcript"
		- Example:
		```json
		{
		"content": "[CONTEXT]...\n[INSIGHT]...\n[RATIONALE]...",
		"title": "Decision: JWT Refresh Flow",
		"knowledgeType": "Note",
		"vaultId": "{ecosystem_vault_id}",
		"tags": ["security", "jwt", "decision"],
		"source": "KnowzCode WorkGroup WG-feat-auth-20260128"
		}
		```

		create_vault(name, description)
		- Create a new vault on the Knowz server
		- `name`: Display name for the vault (e.g., "Code Patterns")
		- `description`: Description of the vault's purpose and content
		- Returns the created vault's ID
		- Used during vault setup when default entries have empty IDs
		- Note: Availability depends on MCP server version. If not available, fall back to matching by name against `list_vaults()` results.

		---

		## Auto-Learning Configuration

		- Enabled: Yes
		- Prompt on Detection: Yes
		- Learning Categories: Pattern, Decision, Workaround, Performance, Security, Convention, Integration

		### Detection Signals

		Learnings are auto-detected when WorkGroup contains:
		- Pattern signals: "created utility for", "new helper", "reusable"
		- Decision signals: "chose X over Y", "decided to", "opted for"
		- Workaround signals: "workaround", "limitation", "temporary"
		- Performance signals: "optimized", "reduced from X to Y"
		- Security signals: "security", "vulnerability", "sanitize"
		- Integration signals: "integrated with", "API behavior", "third-party"

		### Learning Category Routing

		\| Category \| Target Vault Type \|
		\|----------\|-------------------\|
		\| Pattern \| `code` \|
		\| Workaround \| `code` \|
		\| Performance \| `code` \|
		\| Decision \| `ecosystem` \|
		\| Convention \| `ecosystem` \|
		\| Security \| `ecosystem` \|
		\| Integration \| `ecosystem` \|
		\| Completion record \| `finalizations` \|

		---

		## Configuration Commands

		- `/kc:register` - Create account and auto-configure MCP + vault
		- `/kc:connect-mcp` - Configure MCP server (use existing API key)
		- `/kc:connect-mcp --configure-vaults` - Reconfigure vault IDs
		- `/kc:status` - Check connection status and vault info
		- `/kc:learn "insight"` - Manually create learning (routes via knowz-scribe if available)

-34

skills/connect-mcp/references/agent-integration.md

		# Agent-to-Vault Integration

		How KnowzCode agents use MCP tools once configured via `/kc:connect-mcp`.

		---

		## Agent Vault Mapping

		Once configured, agents automatically detect and use MCP tools with dual vault support:

		analyst:
		- Uses `search_knowledge` with code vault to find related code
		- Uses `search_knowledge` with ecosystem vault to find past decisions
		- Uses `ask_question` with ecosystem vault for architectural context

		architect:
		- Uses `search_knowledge` with code vault for implementation examples
		- Uses `ask_question` with ecosystem vault for conventions

		builder:
		- Uses `search_knowledge` with code vault for similar patterns
		- Uses `search_knowledge` with ecosystem vault for best practices

		reviewer:
		- Uses `search_knowledge` with ecosystem vault for standards
		- Uses `search_knowledge` with code vault for precedent checks

		closer:
		- Uses `search_knowledge` with ecosystem vault to check for duplicate learnings
		- Uses `create_knowledge` to save new learnings to ecosystem vault

		All agents:
		- Automatically leverage MCP tools when available
		- Gracefully degrade if MCP server unavailable

-178

skills/connect-mcp/references/vault-setup.md

		# Vault Configuration Details

		Detailed sub-steps for configuring vault IDs in `/kc:connect-mcp`.

		---

		## Step 7a: Fetch available vaults using list_vaults()

		Call the `list_vaults` MCP tool to discover available vaults:
		```
		list_vaults(includeStats: true)
		```

		If successful, display available vaults:
		```
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		◆ VAULT DISCOVERY
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		Fetching your available vaults...

		Available Vaults:
		┌────┬──────────────────────┬──────────────────┬───────────┐
		│ # │ Name │ Type │ Documents │
		├────┼──────────────────────┼──────────────────┼───────────┤
		│ 1 │ KnowzCode │ ecosystem │ 42 │
		│ 2 │ my-project-code │ code │ 1,234 │
		│ 3 │ team-wiki │ ecosystem │ 89 │
		└────┴──────────────────────┴──────────────────┴───────────┘
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		```

		If `list_vaults` fails or returns empty:
		- Fall back to manual vault ID entry (legacy behavior)
		- Prompt:
		```
		Could not fetch vaults automatically.

		Enter vault IDs manually:

		Ecosystem Vault ID (required for /kc:learn):
		• Get from: https://knowz.io/vaults

		Code Vault ID (optional):
		• Leave blank to use grep/glob for code search
		```

		## Step 7b: Interactive vault selection

		For each discovered vault, ask if user wants to connect it:

		```
		Would you like to connect "KnowzCode" (research)?
		```
		Use AskUserQuestion with options: [Yes] [No]

		If "Yes":
		- Prompt for description:
		```
		Describe what this vault contains (for intelligent routing):

		Tips for good descriptions:
		• Be specific about content type
		• Include example queries that should route here
		• Mention key topics covered

		Examples:
		• "Team learnings, conventions, architectural decisions. Use for 'why did we choose X?' questions."
		• "Source code for the main API. Use for 'where is X defined?' questions."
		```

		- Collect description via AskUserQuestion (free text input)

		## Step 7c: Loop for additional vaults

		After each vault selection:
		```
		Would you like to connect another vault?
		```
		Options: [Yes] [No]

		- If "Yes" and more vaults available: Continue selection loop
		- If "No" or no more vaults: Exit loop

		## Step 7d: Write vault configuration

		Write selected vaults to `knowzcode/knowzcode_vaults.md`:

		```markdown
		# KnowzCode Vault Configuration

		Multi-vault routing configuration for intelligent vault selection.

		---

		## Connected Vaults

		### {vault_id_1}
		- Name: {vault_name}
		- ID: {vault_id}
		- Type: {code \| ecosystem \| finalizations}
		- Description: {user_provided_description}

		### {vault_id_2}
		- Name: {vault_name}
		- ID: {vault_id}
		- Type: {code \| ecosystem \| finalizations}
		- Description: {user_provided_description}

		---

		## Vault Routing Rules

		- Code questions (implementations, files, structure) → {first code vault ID}
		- Convention questions (patterns, decisions, best practices) → {first ecosystem vault ID}
		- Completion records → {first finalizations vault ID}
		- Learning capture → {default ecosystem vault ID}
		```

		Also update `knowzcode/mcp_config.md` to reflect primary vault (for backwards compatibility):
		- Set Ecosystem Vault ID to first ecosystem vault selected
		- Set Code Vault ID to first code vault selected (or "not configured")

		### Step 7d.5: Detect uncreated default vaults

		After writing vault configuration, check `knowzcode/knowzcode_vaults.md` for entries with empty ID fields:

		1. Parse all vault entries in the Connected Vaults section
		2. Find entries where the ID field is empty (null GUID — indicates "not yet created on server")
		3. If uncreated entries found:
		```
		Found {N} default vault(s) not yet created: {names}. Create them now?
		```
		Use AskUserQuestion with options: [Yes, create them] [No, skip for now]
		4. If user confirms: for each uncreated entry, call MCP tool to create the vault on the server. Update the entry's ID field with the server-returned vault ID. Update the H3 heading from `(not created)` to the vault ID.
		5. If user declines: proceed normally — vaults can be created later via `/kc:register` or `/kc:connect-mcp --configure-vaults`

		## Step 7e: Show vault configuration summary

		```
		Vault configuration saved to knowzcode/knowzcode_vaults.md

		Connected Vaults:
		• KnowzCode (ecosystem) - "Team learnings and conventions"
		• my-code (code) - "Source code for API project"

		Routing:
		• Code questions → my-code
		• Convention questions → KnowzCode
		• Completion records → Finalizations
		• Learning capture → KnowzCode

		You can edit knowzcode/knowzcode_vaults.md to update descriptions or routing rules.
		```

		## Step 7f: 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.

-474

skills/connect-mcp/SKILL.md

		---
		name: connect-mcp
		description: "Configure KnowzCode MCP server for vector-powered code search and context. Use when asked to connect to KnowzCode, set up MCP, configure vector search, or link vaults."
		user-invocable: true
		allowed-tools: Read, Write, Bash, Glob, Grep
		---

		# KnowzCode MCP Server Connection

		You are the KnowzCode MCP Connection Agent. Your task is to configure the KnowzCode MCP (Model Context Protocol) server to enable vector-based code search and context retrieval.

		## Command Syntax

		```bash
		/kc:connect-mcp <api-key> [--endpoint <url>] [--scope <local\|project\|user>] [--dev] [--configure-vaults]
		/kc:connect-mcp --oauth # Configure with OAuth (recommended for Gemini CLI)
		/kc:connect-mcp kz_live_abc123 # Configure with API key (all platforms)
		```

		Note: If you don't have an API key yet, run `/kc:register` to create an account and get one automatically.
		Registration also auto-configures your vault - no manual setup needed!

		Parameters:
		- `<api-key>` - Required. Your KnowzCode API key (or omit for interactive prompt)
		- `--oauth` - Use OAuth dynamic discovery (RFC 9728). The server returns 401 + WWW-Authenticate, and the client opens a browser for authentication. Recommended for Gemini CLI.
		- `--endpoint <url>` - Optional. Custom MCP endpoint (overrides environment default)
		- `--scope <scope>` - Optional. Configuration scope: local (default), project, or user
		- `--dev` - Optional. Use development environment instead of production
		- `--configure-vaults` - Optional. Force vault configuration prompts (even if already configured)

		Environments:
		\| Environment \| Endpoint \| When to Use \|
		\|:------------\|:---------\|:------------\|
		\| Production (default) \| `https://mcp.knowz.io/mcp` \| Normal usage \|
		\| Development \| `https://mcp.dev.knowz.io/mcp` \| Testing new features \|

		Examples:
		```bash
		# Basic usage (production - default)
		/kc:connect-mcp kz_live_abc123...

		# Interactive mode (production)
		/kc:connect-mcp

		# Development environment
		/kc:connect-mcp kz_test_abc123... --dev

		# Self-hosted endpoint
		/kc:connect-mcp kz_live_abc123... --endpoint https://your-domain.com/mcp

		# Project-wide configuration (production)
		/kc:connect-mcp kz_live_team456... --scope project

		# Development with project scope
		/kc:connect-mcp kz_test_team456... --dev --scope project
		```

		## What This Enables

		Once connected, you get access to these tools:

		- `search_knowledge` - Vector similarity search across vaults
		- `ask_question` - Q&A with optional research mode
		- `create_knowledge` - Save learnings to vault (used by finalization)
		- `update_knowledge` - Update existing knowledge items
		- `find_entities` - Find people, locations, or events in your knowledge

		### Default Vault Types

		KnowzCode ships with three default vault types:

		\| Vault Type \| Purpose \| Query Examples \|
		\|------------\|---------\|----------------\|
		\| Code \| Implementation patterns, workarounds, performance \| "Find auth middleware", "JWT validation" \|
		\| Ecosystem \| Conventions, decisions, integrations, business rules \| "Error handling conventions", "Why Redis?" \|
		\| Finalizations \| WorkGroup completion summaries, outcome records \| "What happened in WG-feat-auth?" \|

		Types are user-configurable labels — users can add custom types freely.

		## Your Task

		Configure the KnowzCode MCP server using Claude Code's built-in MCP management.

		### Steps to Execute

		1. Parse command arguments
		- Extract API key from first positional argument (if provided)
		- Parse `--oauth` flag (use OAuth dynamic discovery instead of API key)
		- Parse `--dev` flag to determine environment
		- Parse `--endpoint <url>` flag (overrides environment default if provided)
		- Default endpoint: `https://mcp.knowz.io/mcp` (production)
		- With `--dev` flag: `https://mcp.dev.knowz.io/mcp` (development)
		- Parse `--scope <scope>` flag (default: `local`)
		- Parse `--configure-vaults` flag (forces vault prompts)
		- Store parsed values for use in configuration

		If `--oauth` flag is set:

		Configure OAuth for all supported platforms. No API key is required — authentication happens via browser on first use.

		- Claude Code — Add MCP server without the Authorization header:
		```bash
		claude mcp add --transport http \
		--scope <chosen-scope> \
		knowz \
		<endpoint-url> \
		--header "X-Project-Path: $(pwd)"
		```
		On first tool call after restart, the server returns `401 + WWW-Authenticate` and Claude Code opens a browser for the user to log in.

		- Gemini CLI — Write OAuth config to `.gemini/settings.json`:
		```json
		{ "mcpServers": { "knowz": { "httpUrl": "<endpoint>", "authProviderType": "dynamic_discovery" } } }
		```
		If `.gemini/` directory exists in the project or user home, configure it automatically.

		After writing the config, instruct the user:
		```
		To complete Gemini authentication, run in Gemini CLI:
		/mcp auth knowz
		This will open your browser for OAuth login.
		```

		- Cross-platform — If both Claude Code and Gemini are detected (`.gemini/` directory exists), configure both and report each.

		- Other platforms (Cursor, Copilot, Windsurf): OAuth not supported for MCP servers. Report this and suggest using an API key: `/kc:connect-mcp <api-key>`.

		OAuth flow shortcut: After configuring, proceed to Step 3 (check existing config), then Step 5 (confirm scope for Claude Code), then skip to Step 7 (vault configuration). Steps 2, 4, 6, and 8 are skipped — no API key discovery or entry needed, and the MCP server is already added above.

		2. Smart Config Discovery (if no API key in arguments)

		Before prompting for an API key, check known config sources:

		a. Environment variable: Check `KNOWZ_API_KEY`
		- If set: use as the API key, display "Using API key from KNOWZ_API_KEY (ending ...{last4})"

		b. Project config: Read `knowzcode/mcp_config.md`
		- If `Connected: Yes` and endpoint set: pre-populate endpoint for Step 5
		- If `Endpoint` is set and different from the production default (`https://mcp.knowz.io/mcp`): use as the default endpoint for this session unless `--endpoint` or `--dev` overrides (e.g., if `Endpoint: https://mcp.dev.knowz.io/mcp`, use dev endpoint)
		- If `API Key (last 4)` is `OAuth Token`: OAuth is already configured — offer to keep or reconfigure
		- If `API Key (last 4)` set (and not `OAuth Token`): note for confirmation prompt

		c. Vault config: Read `knowzcode/knowzcode_vaults.md`
		- If vaults have non-empty IDs: note for Step 7 (skip vault prompts unless `--configure-vaults`)

		d. Cross-platform config files (check for API key or OAuth in other platforms):
		- `.gemini/settings.json` → check `mcpServers.knowz.authProviderType` first (OAuth), then `mcpServers.knowz.headers.Authorization` (API key)
		- `~/.gemini/settings.json` → same
		- `.vscode/mcp.json` → `servers.knowz.headers`
		- If OAuth config found in another platform:
		```
		Found existing OAuth configuration in {source}.
		Would you like to configure Claude Code with OAuth as well?
		```
		Use AskUserQuestion with options: [OAuth (recommended)] [API Key] [Skip]
		- If "OAuth": configure Claude Code with OAuth (same as `--oauth` in Step 1), skip Step 3
		- If "API Key": continue to Step 3
		- If "Skip": abort
		- If API key found: extract Bearer token, offer to reuse:
		"Found existing API key (ending ...{last4}) in {source}. Use this key? [Yes/No]"

		If a key was discovered, skip Step 3 (interactive API key prompt).
		If OAuth was selected, skip Step 3 (no key needed).
		If vaults were discovered, skip vault prompts in Step 7.

		3. Check for existing configuration
		- Check if MCP server already configured: `CLAUDECODE= claude mcp get knowz`
		- If already configured, ask if user wants to reconfigure
		- If yes, run `CLAUDECODE= claude mcp remove knowz` first

		4. Prompt for authentication method (if not already determined)

		If auth method was already set by Step 1 (`--oauth` flag) or Step 1.5 (discovered config), skip this step.

		Otherwise, present both options:
		```
		How would you like to authenticate with the MCP server?

		OAuth (recommended) — log in via browser, no key stored locally
		API Key — enter a KnowzCode API key

		Don't have an account yet? Run /kc:register to create one.
		```
		Use AskUserQuestion with options: [OAuth (recommended)] [API Key]

		If OAuth selected:
		- Configure Claude Code with OAuth (same as `--oauth` in Step 1)
		- If `.gemini/` directory exists, also configure Gemini CLI with OAuth
		- Skip Steps 6 and 8 (no API key to validate, server already added)
		- Continue to Step 5 (scope), then Step 7 (vaults)

		If API Key selected:
		- Prompt for API key:
		```
		Enter your KnowzCode API key
		(Get one at https://knowz.io/api-keys)
		```
		- Validate format (should start with `kz_live_` or `kz_test_`)
		- Never display the full API key back to user
		- Continue to Step 4 as normal

		5. Confirm scope (if not provided)
		- If `--scope` not provided, ask user which scope to use:
		- local (default): Only this project, private to you
		- project: Shared with team via `.mcp.json` (committed to git)
		- user: Available across all your projects

		Present as options to user if not specified in command.

		6. Validate endpoint URL (if custom)
		- If custom endpoint provided via `--endpoint`, validate it's a valid URL
		- Ensure it starts with `https://` (or `http://` for local dev)
		- Show which endpoint will be used

		7. Configure Vault IDs (Conditional with Discovery)

		First, check if vaults are already configured in `knowzcode/knowzcode_vaults.md`:
		- Read the file and check for connected vaults section

		If vaults already configured AND `--configure-vaults` NOT set:
		- Skip vault prompts entirely
		- Display:
		```
		Vaults already configured (from previous setup or /kc:register):
		{List vaults from knowzcode_vaults.md}

		To reconfigure vaults, run: /kc:connect-mcp --configure-vaults
		```

		If vaults NOT configured OR `--configure-vaults` IS set:

		Vault Setup Details: Read [references/vault-setup.md](references/vault-setup.md) for detailed vault configuration steps (7a-7f: vault discovery, interactive selection, writing config, detecting uncreated vaults, summary display, and CLAUDE.md update).

		8. Add MCP server using CLI (skip if `--oauth` was used — server already added in Step 1)
		```bash
		claude mcp add --transport http \
		--scope <chosen-scope> \
		knowz \
		<endpoint-url> \
		--header "Authorization: Bearer <api-key>" \
		--header "X-Project-Path: $(pwd)"
		```

		9. Verify configuration
		- Run: `CLAUDECODE= claude mcp get knowz`
		- Confirm server appears in the list
		- Check for any error messages

		10. Update mcp_config.md
		- Update `knowzcode/mcp_config.md` with connection details:
		- Set `Connected: Yes`
		- Set `Endpoint: <endpoint-url>`
		- Set `Last Verified: <timestamp>`
		- Set `API Key (last 4):` — if `--oauth`, set to `OAuth Token`; otherwise, last 4 characters of the API key
		- Set Ecosystem Vault ID and name (if provided or already set)
		- Set Code Vault ID and name (if provided)
		- Set `Auto-configured: No` (to distinguish from /kc:register setup)

		11. Test connection (conditional)
		- If API key was used: Optionally test with a simple tool call to validate the key.
		- If OAuth was used: Skip connection test. OAuth requires browser login after restart, so a 401 at this point is expected.
		Display: `ℹ️ Connection test skipped — OAuth requires browser login after restart.`

		12. Report success

		If `--oauth` was used:
		```
		✅ KnowzCode MCP configured with OAuth!

		Platforms configured:
		• Claude Code: OAuth (scope: <chosen-scope>)
		• Gemini CLI: OAuth (dynamic_discovery) ← only if configured
		→ Run `/mcp auth knowz` in Gemini CLI to complete authentication

		Endpoint: <endpoint-url>
		Auth: OAuth — you'll be prompted to log in via browser on first use

		Vaults Configured:
		• Code Vault: <vault-name or "Not configured">
		• Ecosystem Vault: <vault-name or "Not configured">
		• Finalizations Vault: <vault-name or "Not configured">

		🔄 Please restart Claude Code to activate MCP features.
		On first tool call, your browser will open for authentication.

		Check connection status: /kc:status
		```

		If API key was used:
		```
		✅ KnowzCode MCP server configured!

		Scope: <chosen-scope>
		Endpoint: <endpoint-url>

		Vaults Configured:
		• Code Vault: <vault-name or "Not configured">
		• Ecosystem Vault: <vault-name or "Not configured">
		• Finalizations Vault: <vault-name or "Not configured">

		🔄 Please restart Claude Code to activate these features:
		• search_knowledge - Vector search across vaults
		• ask_question - AI Q&A with research mode
		• create_knowledge - Save learnings (via finalization)
		• update_knowledge - Update existing items
		• find_entities - Find people/locations/events

		After restart, these tools will be available to all KnowzCode agents.

		Check connection status: /kc:status
		```

		## Configuration Details

		### Scope Comparison

		Local (default):
		- ✅ Private to you
		- ✅ Project-specific
		- ❌ Not shared with team
		- Use when: Personal API key, working solo

		Project:
		- ✅ Shared with team
		- ✅ Committed to git via `.mcp.json`
		- ⚠️ API key visible to team
		- Use when: Team API key, collaborative project

		User:
		- ✅ Available everywhere
		- ✅ Set once, works across projects
		- ❌ Not project-specific
		- Use when: Single API key for all your work

		### Security Considerations

		- Never log API keys in command output
		- Mask displayed keys: Show only first/last 4 chars (e.g., `kz_live_abc...xyz`)
		- Warn about project scope: API key will be in git-committed `.mcp.json`
		- Suggest environment variables: For team setups, recommend storing in CI/CD secrets

		### MCP Server Details

		The KnowzCode MCP server (default: `https://mcp.knowz.io/mcp`):
		- Protocol: HTTP transport with JSON-RPC
		- Authentication: Bearer token in `Authorization` header
		- Project Context: `X-Project-Path` header identifies project
		- Rate Limiting: Standard API rate limits apply
		- Caching: Responses cached for performance

		## Error Handling

		### OAuth Authentication Required
		```
		⚠️ OAuth authentication needed

		This is expected if:
		• First-time setup — you haven't completed browser login yet
		• Token expired — your OAuth session needs renewal

		To authenticate:
		Claude Code: Restart Claude Code — browser will open on first tool call
		Gemini CLI: Run /mcp auth knowz to re-authenticate via browser

		If the problem persists:
		• Re-configure: /kc:connect-mcp --oauth
		• Or switch to API key: /kc:connect-mcp <api-key>
		```

		### API Key Invalid
		```
		❌ Authentication failed
		The API key appears to be invalid or expired.

		Get a new key at: https://knowz.io/api-keys
		Or switch to OAuth (no key needed): /kc:connect-mcp --oauth
		Then run: /kc:connect-mcp <new-key>
		```

		### Already Configured
		```
		⚠️ KnowzCode MCP server is already configured
		Current scope: <scope>

		Do you want to reconfigure?
		```

		### Claude CLI Not Available
		```
		❌ Cannot configure MCP server
		The 'claude' CLI command is not available.

		This is unusual - Claude Code should provide this command.
		Please restart Claude Code or report this issue.
		```

		### Network/Connection Error
		```
		❌ Cannot reach KnowzCode API
		Failed to connect to {endpoint}

		Check your internet connection and try again.
		If using --dev environment, verify the dev server is running.
		```

		## Advanced Usage

		### Switching Scopes
		To change from local to project scope:
		```bash
		# Remove existing (or the command will prompt to reconfigure)
		CLAUDECODE= claude mcp remove knowz

		# Re-add with new scope
		/kc:connect-mcp <api-key> --scope project
		```

		### Switching Endpoints
		To switch between environments or self-hosted:
		```bash
		# Switch to development
		/kc:connect-mcp <api-key> --dev

		# Switch back to production (default)
		/kc:connect-mcp <api-key>

		# Switch to self-hosted
		/kc:connect-mcp <api-key> --endpoint https://knowzcode.mycompany.com/mcp
		```

		## Integration with KnowzCode Agents

		Agent Integration: Read [references/agent-integration.md](references/agent-integration.md) for agent-to-vault mapping.

		All agents automatically leverage MCP tools when available and gracefully degrade if MCP server is unavailable.

		## Next Steps

		After configuration:
		1. Restart Claude Code (required to activate MCP server)
		2. Verify connection: `/kc:status`
		3. Start building: `/kc:work "your feature"`
		4. Watch agents use MCP tools automatically during workflow

		## Tool Control & Filtering

		Tools are controlled server-side at the MCP endpoint:

		Server controls which tools to expose based on:
		- API key tier (free/pro/enterprise)
		- Project type (monorepo, microservices, etc.)
		- Feature flags per user
		- Runtime conditions

		Agents automatically discover and use available tools - no client-side filtering needed.

		See `docs/MCP_SERVER_IMPLEMENTATION.md` for complete server implementation guide.

		## Related Commands

		- `/kc:register` - Register for KnowzCode and configure MCP automatically
		- `/kc:status` - Check MCP connection status and available tools
		- `/kc:init` - Initialize KnowzCode in project
		- `/kc:work` - Start feature development (uses MCP tools)

		## Implementation Notes

		For Server Developers:
		- See `docs/MCP_SERVER_IMPLEMENTATION.md` for complete specification
		- Required methods: `initialize`, `tools/list`, `tools/call`
		- Authentication via `Authorization: Bearer` header
		- Project context via `X-Project-Path` header

		Execute this configuration now.

-335

skills/learn/SKILL.md

		---
		name: learn
		description: "Capture learnings to the KnowzCode ecosystem vault for organizational knowledge. Use when the user wants to save an insight, lesson learned, decision, pattern, or convention."
		user-invocable: true
		allowed-tools: Read, Write, Glob, Grep, AskUserQuestion
		---

		# KnowzCode Learning Capture

		You are the KnowzCode Learning Agent. Your task is to capture insights, patterns, decisions, and best practices to the appropriate vault for future reference.

		## Command Syntax

		```bash
		/kc:learn "<insight>" [--category <type>] [--tags <tag1,tag2,...>] [--vault <name-or-id>] [--source <origin>] [--workgroup <wgid>]
		```

		Parameters:
		- `"<insight>"` - Required. The learning to capture (in quotes)
		- `--category <type>` - Optional. Category prefix (pattern, decision, workaround, performance, security, convention)
		- `--tags <tags>` - Optional. Comma-separated tags for categorization
		- `--vault <name-or-id>` - Optional. Target vault for multi-vault setups
		- `--source <origin>` - Optional. Where this learning came from (e.g., "code review", "incident", "meeting", "pair programming")
		- `--workgroup <wgid>` - Optional. Explicitly link this learning to a WorkGroup for traceability

		Examples:
		```bash
		# Simple learning (auto-routes to appropriate vault)
		/kc:learn "JWT refresh tokens work better than session cookies for stateless APIs"

		# With category
		/kc:learn "Always sanitize user input before SQL queries" --category security

		# With tags
		/kc:learn "Repository pattern isolates data access from business logic" --category pattern --tags architecture,data-access

		# Workaround documentation
		/kc:learn "Azure Blob SDK v12 has memory leak with large files; use streaming instead" --category workaround --tags azure,blob-storage

		# Explicit vault selection (multi-vault setup)
		/kc:learn "New hire checklist for backend developers" --vault "Company Wiki"
		/kc:learn "We use Repository pattern for all data access" --vault engineering-knowledge

		# With source and WorkGroup linking
		/kc:learn "Rate limiting should be per-user not per-IP" --source "incident postmortem" --category decision
		/kc:learn "Use streaming for files >10MB" --workgroup kc-feat-file-upload-20260201-120000
		```

		## Prerequisites

		- KnowzCode MCP server must be connected
		- Ecosystem vault must be configured (auto-configured via `/kc:register`)
		- Project must be initialized (`/kc:init`)

		Quickest setup: Run `/kc:register` - it creates your account AND configures your vault automatically.

		## Your Task

		Capture the provided insight to the appropriate vault using the MCP `create_knowledge` tool.

		### Steps to Execute

		1. Quick MCP and Vault Detection (FIRST)

		Step 1a: Check for `create_knowledge` in your available tools list

		If `create_knowledge` is NOT available:
		- MCP server is not connected
		- Show helpful setup guidance (see Error Handling section)
		- Do NOT attempt any MCP operations
		- STOP here

		Step 1b: Read vault configuration
		- Read `knowzcode/knowzcode_vaults.md` (canonical vault config)
		- Look for a vault entry with type `ecosystem` that has a non-empty ID
		- If not found, fall back to `knowzcode/mcp_config.md` for backwards compatibility
		- Check if Vault ID is set (not empty or "(not configured)")

		If Ecosystem Vault ID IS configured:
		- Proceed to step 2

		If Ecosystem Vault ID is "(not configured)" or missing:
		- Show "vault not configured" error:
		```
		❌ Ecosystem vault not configured

		Your MCP server is connected, but no vault is set up for learnings.

		Quickest fix:
		/kc:register
		(Creates account + auto-configures vault)

		Already have an account?
		/kc:connect-mcp --configure-vaults
		(Prompts for vault ID)

		After setup, run /kc:learn again.
		```
		- STOP here

		2. Determine Target Vault (Multi-Vault Support)

		a. Read `knowzcode/knowzcode_vaults.md` for connected vaults
		b. Route based on category (see Category-to-Vault Routing below)
		c. If only one vault of the target type → use it automatically
		d. If multiple vaults of the target type:
		- Analyze learning content against vault descriptions
		- Look for keyword matches:
		- "architecture", "pattern", "decision" → vault with architectural content
		- "process", "onboarding", "team" → vault with organizational content
		- "convention", "standard", "rule" → vault with conventions
		- If clear match → use that vault
		- If ambiguous → prompt user:
		```
		Where should this learning be saved?

		Available vaults:
		1. Engineering Knowledge - "architectural decisions, patterns, conventions"
		2. Company Wiki - "processes, onboarding, team structure"

		Select vault (1-2) or type vault name:
		```
		Use AskUserQuestion with vault options.
		e. If no vaults in knowzcode_vaults.md:
		- Fall back to `knowzcode/mcp_config.md` Ecosystem Vault ID
		- If still not configured → show "vault not configured" error

		### Category-to-Vault Routing

		\| Category \| Target Vault Type \|
		\|----------\|------------------\|
		\| `Pattern` \| code \|
		\| `Workaround` \| code \|
		\| `Performance` \| code \|
		\| `Decision` \| ecosystem \|
		\| `Convention` \| ecosystem \|
		\| `Security` \| ecosystem \|
		\| `Integration` \| ecosystem \|
		\| (completion records) \| finalizations \|
		\| (no category / Note) \| ecosystem (default) \|

		If a `finalizations` vault is configured, completion-specific context (e.g., learnings tagged with `--workgroup` or about completed sessions) may be routed there.

		3. Parse command arguments
		- Extract insight text from quotes
		- Parse `--category` flag (default: auto-detect)
		- Parse `--tags` flag (default: extract from content)
		- Parse `--vault` flag (optional: explicit vault selection)
		- Parse `--source` flag (optional: origin context like "code review", "incident", "meeting")
		- Parse `--workgroup` flag (optional: explicit WorkGroup link for traceability)

		4. Detect category (if not provided)
		- Scan insight for signal words:
		```
		pattern: "pattern", "reusable", "utility", "helper"
		decision: "chose", "decided", "opted", "because"
		workaround: "workaround", "limitation", "instead"
		performance: "optimized", "faster", "reduced", "cache"
		security: "security", "vulnerability", "sanitize", "auth"
		convention: "always", "never", "standard", "rule"
		```
		- Default to "Note" if no clear category detected

		5. Extract/validate tags
		- If `--tags` provided, use those
		- Otherwise, extract key terms from insight
		- Always include current project name
		- Add active WorkGroup ID if applicable

		6. Check for duplicates in selected vault
		```bash
		search_knowledge(
		query: "{insight summary}",
		vaultId: "{selected_vault_id}",
		limit: 3
		)
		```
		- If similar exists (>80% match), warn user:
		```
		⚠️ Similar knowledge exists:
		> "{existing title}"

		Options:
		[Create anyway] [Skip] [Update existing]
		```

		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}
		WorkGroup: {--workgroup value or active-workgroup-id or "Manual capture"}
		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
		Origin: {--source value or "direct capture"}
		```

		8. Create knowledge item in selected vault
		```json
		create_knowledge({
		"content": "{formatted content}",
		"title": "{Category}: {Descriptive summary — include key technology names for search discoverability}",
		"knowledgeType": "Note",
		"vaultId": "{selected_vault_id}",
		"tags": ["{category}", "{extracted-tags}", "{project-name}"],
		"source": "KnowzCode /kc:learn"
		})
		```

		9. Report success with vault info
		```
		✅ Learning captured!

		Title: {Category}: {Brief summary}
		Vault: {selected_vault_name} ({vault_id prefix...})
		Tags: {tag list}

		This knowledge is now available to all KnowzCode agents when querying this vault.
		```

		## Category Reference

		\| Category \| When to Use \| Signal Words \|
		\|----------\|-------------\|--------------\|
		\| `Pattern:` \| Reusable code pattern \| pattern, reusable, utility, helper, abstraction \|
		\| `Decision:` \| Architecture/design choice \| chose, decided, opted, because, trade-off \|
		\| `Workaround:` \| Limitation bypass \| workaround, limitation, instead, temporary, bug \|
		\| `Performance:` \| Optimization insight \| faster, optimized, reduced, improved, cache \|
		\| `Security:` \| Security consideration \| security, vulnerability, sanitize, auth, encrypt \|
		\| `Convention:` \| Team standard \| always, never, standard, rule, convention \|

		## Error Handling

		### MCP Not Connected (Most Common)
		```
		❌ Learning capture requires MCP connection

		The /kc:learn command needs the KnowzCode MCP server to store
		learnings in your organization's knowledge vault.

		To get started:

		Recommended (easiest):
		/kc:register
		(Creates account + configures MCP + sets up vault - all automatic!)

		Already have an API key?
		/kc:connect-mcp <your-api-key>

		After setup, run /kc:learn again to capture your insight.
		```

		### Ecosystem Vault Not Configured
		```
		❌ Ecosystem vault not configured

		MCP is connected, but no vault is set up for learnings.

		Quickest fix:
		/kc:register
		(Creates account + auto-configures vault)

		Already have an account?
		/kc:connect-mcp --configure-vaults
		(Prompts for vault ID)

		After setup, run /kc:learn again.
		```

		### Project Not Initialized
		```
		❌ KnowzCode not initialized

		Run /kc:init first to set up this project, then:
		/kc:register (to enable learning capture)
		/kc:learn "your insight"
		```

		### Empty Insight
		```
		❌ No insight provided

		Usage: /kc:learn "your insight here"

		Example:
		/kc:learn "Always validate user input at API boundaries"
		```

		## Integration with Workflow

		### Automatic Capture (via closer)
		The `closer` agent automatically detects and offers to capture learnings during WorkGroup finalization. This is the recommended flow for workflow-related insights.

		### Manual Capture (via /kc:learn)
		Use this command for:
		- Ad-hoc insights discovered outside of WorkGroups
		- Documenting existing team knowledge
		- Capturing external learnings (from reviews, meetings, etc.)

		## Querying Captured Learnings

		After capturing, learnings are queryable by all agents:

		```bash
		# Resolve vault IDs from knowzcode/knowzcode_vaults.md first, then query by type:

		# By analyst
		search_knowledge("authentication patterns", {vault matching "ecosystem" type})

		# By architect
		ask_question("What are our error handling conventions?", {vault matching "ecosystem" type})

		# By builder
		search_knowledge("database connection best practices", {vault matching "ecosystem" type})
		```

		## Related Commands

		- `/kc:connect-mcp` - Configure MCP server and vaults
		- `/kc:status` - Check vault configuration
		- `/kc:work` - Start feature (uses captured learnings)
		- `/kc:audit` - Run audits (checks against documented patterns)

		Execute this learning capture now.

-275

skills/plan/SKILL.md

		---
		name: plan
		description: "Research and investigate a topic using parallel agents before implementing. Use when asked to explore, plan, research, or analyze a feature, question, or codebase area."
		user-invocable: true
		allowed-tools: Read, Write, Bash, Glob, Grep, Task
		argument-hint: "[topic or question]"
		---

		# KnowzCode Plan

		Research a topic, feature, or question using parallel investigation before committing to implementation.

		Usage: `/kc:plan <topic or question>`

		Examples:
		```
		/kc:plan "is the API using proper error handling?"
		/kc:plan "add user authentication with JWT"
		/kc:plan "how does caching work in this codebase?"
		```

		---

		## Step 1: Validate Input

		If no argument provided, ask: "What would you like me to research?"

		## Step 2: Check Initialization

		If `knowzcode/` doesn't exist, inform user to run `/kc:init` first. STOP.

		## Step 3: Set Up Execution Mode

		Attempt `TeamCreate(team_name="kc-plan-{slug}")` (2-4 word kebab-case from topic):

		- If TeamCreate succeeds → Agent Teams mode:
		1. Announce: `Execution Mode: Agent Teams — created team kc-plan-{slug}`
		2. Read `knowzcode/claude_code_execution.md` for team conventions.
		3. You are the team lead — coordinate research, synthesize findings.

		- If TeamCreate fails (error, unrecognized tool, timeout) → Subagent Delegation:
		- Announce: `Execution Mode: Subagent Delegation — Agent Teams not available, using Task() fallback`

		The user MUST see the execution mode announcement before investigation begins.

		## Step 3.5: Load Orchestration Config (Optional)

		If `knowzcode/knowzcode_orchestration.md` exists, parse:
		1. `SCOUT_MODE` = `scout_mode` value (default: "full")
		2. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)

		Flag overrides: `--no-scouts` → `SCOUT_MODE = "none"`, `--no-mcp` → `MCP_AGENTS_ENABLED = false`

		If file doesn't exist, use defaults. Other config settings (`max_builders`, `default_specialists`) are not applicable to `/kc:plan`.

		## Step 4: Launch Parallel Investigation

		### MCP Probe

		Before spawning agents, determine vault availability:
		1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
		2. Call `list_vaults(includeStats=true)` always — regardless of whether any IDs exist in the file
		3. If `list_vaults()` fails → set `MCP_ACTIVE = false`, announce `MCP Status: Not connected`, skip vault setup
		4. If `list_vaults()` succeeds AND UNCREATED list is non-empty → present the Vault Creation Prompt:

		```markdown
		## Vault Setup

		Your Knowz API key is valid and MCP is connected, but {N} default vault(s) haven't been created yet.
		Creating vaults enables knowledge capture throughout the workflow:

		\| Vault \| Type \| Description \| Written During \|
		\|-------\|------\|-------------\|----------------\|
		```

		Build table rows dynamically from the UNCREATED entries only. Derive "Written During" from each vault's Write Conditions field in `knowzcode_vaults.md`.

		Then present options:
		```
		Options:
		A) Create all {N} vaults (recommended)
		B) Select which to create
		C) Skip — proceed without vaults (can create later with `/kc:connect-mcp --configure-vaults`)
		```

		5. Handle user selection:
		- A: For each UNCREATED entry, call MCP `create_vault(name, description)`. If `create_vault` is not available, fall back to matching by name against `list_vaults()` results. Update `knowzcode_vaults.md`: fill ID field, change H3 heading from `(not created)` to vault ID. Report any failures.
		- B: Ask which vaults to create, then create only selected ones.
		- C: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
		6. After resolution, set:
		- `MCP_ACTIVE = true` (MCP works regardless of vault creation outcome)
		- `VAULTS_CONFIGURED = true` if at least 1 vault now has a valid ID, else `false`
		- Announce: `MCP Status: Connected — N vault(s) available` or `MCP Status: Connected — no vaults configured (knowledge capture disabled)`

		### Agent Teams Mode (with scouts)

		Create tasks first, pre-assign, then spawn with task IDs:

		1. If `SCOUT_MODE != "none"`: `TaskCreate("Scout: local context for {topic}")` → `TaskUpdate(owner: "context-scout")`
		2. `TaskCreate("Scout: vault knowledge for {topic}")` → `TaskUpdate(owner: "knowz-scout")` (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`)
		3. `TaskCreate("Research: code exploration")` → `TaskUpdate(owner: "analyst")`
		4. `TaskCreate("Research: architecture")` → `TaskUpdate(owner: "architect")`
		5. `TaskCreate("Research: security + quality")` → `TaskUpdate(owner: "reviewer")`

		Spawn teammates with their task IDs (count depends on SCOUT_MODE and MCP settings):

		1. If `SCOUT_MODE != "none"`, spawn `context-scout` teammate:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a knowzcode history angle.
		> Read `agents/context-scout.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Find: existing specs, prior WorkGroups, tracker entries relevant to this topic.
		> Broadcast findings to all teammates.

		2. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, spawn `knowz-scout` teammate:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a vault knowledge angle.
		> Read `agents/knowz-scout.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Query: team conventions, past decisions, similar implementations.
		> Broadcast findings to all teammates.

		3. Spawn `analyst` teammate:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a code exploration angle.
		> Read `agents/analyst.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: affected files, dependencies, existing patterns.
		> Max 10 tool calls. Write findings to a concise summary.

		4. Spawn `architect` teammate:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from an architecture angle.
		> Read `agents/architect.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: layer analysis, design implications, pattern fit.
		> Max 10 tool calls. Write findings to a concise summary.

		5. Spawn `reviewer` teammate:
		> Your Task: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
		> You are researching "{topic}" from a security and quality angle.
		> Read `agents/reviewer.md` for your role definition.
		> Read `knowzcode/claude_code_execution.md` for team conventions.
		> Investigate: risks, performance concerns, quality gaps.
		> Max 10 tool calls. Write findings to a concise summary.

		Scouts broadcast findings; all three core researchers consume them.
		Wait for all to complete, then synthesize in Step 5.

		### Subagent Mode

		Delegate to up to five agents in parallel via `Task()`:

		1. context-scout — Local context (if `SCOUT_MODE != "none"`):
		- `SCOUT_MODE = "full"` (default): 3 parallel instances:
		- `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research \"{topic}\". Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
		- `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research \"{topic}\". Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for similar goals, what was tried, what succeeded/failed. Max 10 tool calls. Write findings to a concise summary.")`
		- `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research \"{topic}\". Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md, knowzcode/knowzcode_project.md — scan for active WIP, REFACTOR tasks, architecture summary, recent log patterns. Max 10 tool calls. Write findings to a concise summary.")`
		- `SCOUT_MODE = "minimal"`: 1 combined instance:
		- `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research \"{topic}\". Focus: ALL local context — knowzcode/specs/.md, knowzcode/workgroups/.md, knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md, knowzcode/knowzcode_project.md. Max 10 tool calls. Write findings to a concise summary.")`

		2. knowz-scout — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
		- `Task(subagent_type="knowz-scout", description="Scout: vault knowledge", prompt="Research \"{topic}\". Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query each for relevant knowledge: team conventions, past decisions, similar implementations. Max 10 tool calls. Write findings to a concise summary.")`

		3. analyst — Code exploration:
		- `subagent_type`: `"analyst"`
		- `prompt`: Task-specific context only (role definition is auto-loaded from `agents/analyst.md`):
		> Research "{topic}" from a code exploration angle.
		> Investigate: affected files, dependencies, existing patterns.
		> Max 10 tool calls. Write findings to a concise summary.
		- `description`: `"Plan research: code exploration"`

		4. architect — Architecture assessment:
		- `subagent_type`: `"architect"`
		- `prompt`: Task-specific context only (role definition is auto-loaded from `agents/architect.md`):
		> Research "{topic}" from an architecture angle.
		> Investigate: layer analysis, design implications, pattern fit.
		> Max 10 tool calls. Write findings to a concise summary.
		- `description`: `"Plan research: architecture"`

		5. reviewer — Security and quality:
		- `subagent_type`: `"reviewer"`
		- `prompt`: Task-specific context only (role definition is auto-loaded from `agents/reviewer.md`):
		> Research "{topic}" from a security and quality angle.
		> Investigate: risks, performance concerns, quality gaps.
		> Max 10 tool calls. Write findings to a concise summary.
		- `description`: `"Plan research: security and quality"`

		Each uses focused, efficient scoping (max 10 tool calls).

		## Step 5: Synthesize Findings

		```markdown
		## Investigation: {topic}

		### Code Analysis
		{summarized findings from analyst}

		### Architecture Assessment
		{summarized findings from architect}

		### Security & Quality
		{summarized findings from reviewer}

		### Existing Knowledge (from scouts)
		- Relevant Specs: {list or "None found"}
		- Prior WorkGroups: {list or "None found"}
		- Vault Knowledge: {list or "N/A — MCP not configured"}

		### Recommended Approaches

		Option 1: {approach}
		- Pros: ...
		- Cons: ...

		Option 2: {approach}
		- Pros: ...
		- Cons: ...

		### Risks & Considerations
		{synthesized risks}

		### Complexity Assessment
		- Files identified: {count} — {file list}
		- Potential NodeIDs: {count} — {brief descriptions}
		- Architectural impact: Yes/No — {reason if yes}
		- Security-sensitive: Yes/No — {reason if yes}
		- External integrations: Yes/No — {list if yes}
		- Estimated scope: ~{N} lines across {M} files
		- Recommended tier: Tier 2 (Light) / Tier 3 (Full)

		Tier recommendation follows work.md's classification rules:
		- Tier 3 if ANY: >3 files, >1 NodeID, architectural impact, security-sensitive, external integrations
		- Tier 2 if ALL: ≤3 files, single NodeID, no arch changes, no security, no external APIs

		---

		Ready to implement? Say "implement", "do option 1", or "go ahead" to start `/kc:work` with this context.
		```

		## Step 6: Listen for Implementation Intent

		Watch for: "implement", "do it", "go ahead", "option N", "start work", "build this"

		When triggered, invoke `/kc:work "{original_topic}" --tier {recommended_tier}` and include
		a summary of investigation findings:

		> Plan investigation context:
		> - Files: {file list from complexity assessment}
		> - Potential NodeIDs: {list}
		> - Key risks: {top risks}
		> - Recommended approach: {selected option or top recommendation}

		This context gives work's analyst a head start and ensures correct tier classification.

		---

		## Cleanup

		After synthesis is complete (or if the user cancels):

		Agent Teams Mode:
		1. Shut down all active teammates. Wait for each to confirm shutdown.
		2. Once all teammates have shut down, clean up the team.
		No teammates or team resources should remain after the research ends.

		Subagent Mode: No cleanup needed — `Task()` calls are self-contained.

		---

		## Notes

		- Research agents use focused, efficient scoping (max 10 tool calls each)
		- Investigation context is preserved when transitioning to `/kc:work`
		- This replaces the old planning types (strategy, ideas, pre-flight, etc.)

-115

skills/register/references/error-handling.md

		# Error Handling Reference

		## Email Already Registered (HTTP 409)

		```
		⚠️ Email Already Registered

		The email {email} is already associated with a KnowzCode account.

		Options:
		1. Use a different email → Run /kc:register again
		2. Retrieve existing API key → Visit https://knowz.io/api-keys
		3. Reset password → https://knowz.io/forgot-password

		If this is your account, you can configure your existing key:
		/kc:connect-mcp <your-existing-api-key>
		```

		## Invalid Input (HTTP 400)

		```
		❌ Registration Failed

		The server reported validation errors:
		{error_message_from_response}

		Please correct the issue and try again.
		```

		Return to the step corresponding to the invalid field.

		## Rate Limited (HTTP 429)

		```
		⏳ Too Many Requests

		Registration is temporarily rate limited.
		Please wait a few minutes and try again.

		If you continue to see this error, contact support:
		https://knowz.io/support
		```

		## Network Error

		```
		❌ Network Error

		Cannot reach KnowzCode registration server.

		Troubleshooting:
		1. Check your internet connection
		2. Verify firewall/proxy settings allow HTTPS to api.knowz.io (or api.dev.knowz.io for --dev)
		3. Try again in a few moments

		If the issue persists:
		• Status page: https://status.knowz.io
		• Support: https://knowz.io/support
		```

		## Server Error (HTTP 500+)

		```
		❌ Server Error

		KnowzCode registration service encountered an error.

		This is not your fault. Please:
		1. Try again in a few minutes
		2. Check status: https://status.knowz.io
		3. Contact support if persists: https://knowz.io/support
		```

		## MCP Configuration Failed

		If registration succeeds but MCP configuration fails:

		```
		⚠️ Account Created, but MCP Configuration Failed

		Your account was created successfully:
		• Email: {email}
		• API Key: {masked_key}
		• Vault: {vault_name} ({vault_id prefix...})

		However, automatic MCP configuration failed:
		{error_details}

		You can configure manually:
		/kc:connect-mcp {masked_key}

		Or visit https://knowz.io/api-keys to retrieve your key later.
		```

		## API Response Missing Vault ID

		If registration succeeds but API returns no vault_id:

		```
		⚠️ Account Created, but Vault Not Provisioned

		Your account was created and MCP is configured:
		• Email: {email}
		• API Key: {masked_key}
		• MCP: Configured

		However, no vault was auto-created. This may indicate:
		• Account provisioning is still in progress
		• Server-side configuration needed

		You can:
		1. Wait a few minutes and run /kc:status to check
		2. Contact support: https://knowz.io/support
		3. Manually configure vault later: /kc:connect-mcp --configure-vaults
		```

-143

skills/register/references/vault-discovery.md

		# Vault Discovery and Multi-Vault Selection

		After MCP is configured and before showing the final success message, offer vault discovery:

		## 1. Fetch Available Vaults

		Use the `list_vaults` MCP tool (if available after restart) or display guidance:

		```
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		◆ VAULT CONFIGURATION
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		Your account includes one vault by default:
		• {vault_name} ({vault_id prefix...})

		You can connect additional vaults for multi-vault routing.
		This allows queries to be automatically routed to the right vault
		based on the type of question (code vs. conventions vs. processes).

		Would you like to configure additional vaults now?
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		```

		Use AskUserQuestion with options:
		- Yes - Configure additional vaults now
		- No - Skip for now (can configure later with /kc:connect-mcp --configure-vaults)

		STOP HERE and wait for user response.

		- If "No": Proceed to write single vault to `knowzcode_vaults.md` and show success message
		- If "Yes": Continue with vault discovery

		## 2. Call list_vaults() to Discover Available Vaults

		If MCP tools are already active (rare after fresh registration):
		```
		list_vaults(includeStats: true)
		```

		If MCP tools not yet available (common - requires restart):
		```
		Note: MCP tools require a restart to activate.
		After restart, run /kc:connect-mcp --configure-vaults to add more vaults.
		```

		If vaults are returned, display them:
		```
		Available Vaults:
		┌────┬──────────────────────┬──────────────────┬───────────┐
		│ # │ Name │ Type │ Documents │
		├────┼──────────────────────┼──────────────────┼───────────┤
		│ 1 │ KnowzCode (default) │ ecosystem │ 0 │
		│ 2 │ my-project-code │ code │ 1,234 │
		│ 3 │ engineering-wiki │ ecosystem │ 89 │
		└────┴──────────────────────┴──────────────────┴───────────┘
		```

		## 3. Interactive Vault Selection Loop

		For each vault discovered (including the default one):

		a. Ask if user wants to connect this vault:
		```
		Would you like to connect vault "KnowzCode" (research)?
		```
		Options: [Yes] [No]

		b. If "Yes", prompt for description:
		```
		Describe what this vault contains (for intelligent routing):

		Example descriptions:
		• "Team learnings, conventions, architectural decisions"
		• "Source code for the main API project"
		• "Company processes, onboarding docs, team structure"

		This helps KnowzCode route queries to the right vault automatically.
		```

		Use AskUserQuestion to collect description (free text).

		c. Store vault info: ID, name, type, description

		d. Ask if user wants to connect another vault:
		```
		Would you like to connect another vault?
		```
		Options: [Yes] [No]

		- If "Yes" and more vaults available: Loop back to step a
		- If "No" or no more vaults: Exit loop

		## 4. Write Vault Configuration to knowzcode_vaults.md

		Create or update `knowzcode/knowzcode_vaults.md` with selected vaults:

		```markdown
		# KnowzCode Vault Configuration

		Multi-vault routing configuration for intelligent vault selection.

		---

		## Connected Vaults

		### {vault_id_1}
		- Name: {vault_name}
		- ID: {vault_id}
		- Type: {code \| ecosystem \| finalizations}
		- Description: {user_provided_description}

		### {vault_id_2}
		- Name: {vault_name}
		- ID: {vault_id}
		- Type: {code \| ecosystem \| finalizations}
		- Description: {user_provided_description}

		---

		## Vault Routing Rules

		- Code questions (implementations, files, structure) → {first code vault}
		- Convention questions (patterns, decisions, best practices) → {first ecosystem vault}
		- Completion records → {first finalizations vault}
		- Learning capture → {default ecosystem vault}
		```

		Null GUID detection: After writing vault configuration to `knowzcode_vaults.md`, check for entries with empty ID fields. If found, prompt: "Found {N} default vault(s) not yet created. Create them now?" On confirmation, create each vault via MCP and update the ID fields.

		## 5. Show Vault Configuration Summary

		After writing configuration:
		```
		Vault configuration saved to knowzcode/knowzcode_vaults.md

		Connected Vaults:
		• KnowzCode (ecosystem) - "Team learnings and conventions"
		• my-code (code) - "Source code for API project"

		Queries will be automatically routed based on your descriptions.
		You can edit knowzcode/knowzcode_vaults.md to update routing rules.
		```

-550

skills/register/SKILL.md

		---
		name: register
		description: "Register for KnowzCode and configure MCP server automatically. Use when the user wants to create a KnowzCode account, sign up, or set up API access."
		user-invocable: true
		allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
		argument-hint: "[--scope local\|project\|user] [--dev]"
		---

		# KnowzCode Registration

		You are the KnowzCode Registration Agent. Your task is to guide users through account registration and automatically configure the MCP server connection.

		## Command Syntax

		```bash
		/kc:register [--scope <local\|project\|user>] [--dev]
		```

		Parameters:
		- `--scope <scope>` - Optional. Configuration scope: local (default), project, or user
		- `--dev` - Optional. Use development environment instead of production

		Environments:
		\| Environment \| API Endpoint \| MCP Endpoint \| When to Use \|
		\|:------------\|:-------------\|:-------------\|:------------\|
		\| Production (default) \| `https://api.knowz.io/api/v1/auth/register` \| `https://mcp.knowz.io/mcp` \| Normal usage \|
		\| Development \| `https://api.dev.knowz.io/api/v1/auth/register` \| `https://mcp.dev.knowz.io/mcp` \| Testing new features \|

		Examples:
		```bash
		# Standard registration (production)
		/kc:register

		# Register with project-wide scope (production)
		/kc:register --scope project

		# Register with user-wide scope (production)
		/kc:register --scope user

		# Register against development environment
		/kc:register --dev

		# Development with specific scope
		/kc:register --dev --scope project
		```

		## What Registration Provides

		Registering for KnowzCode gives you:

		- API Key - Unique key for MCP server authentication
		- KnowzCode Vault - Auto-created vault for learnings, conventions, and patterns
		- Vector Search - AI-powered code search across your projects
		- Spec Queries - Query your specifications and documentation
		- Context Retrieval - Intelligent context for agent decisions
		- Dependency Analysis - Understand code relationships

		Free tier includes:
		- 1,000 API calls/month
		- Single user
		- Basic vector search

		Upgrades available at: https://knowz.io/pricing

		## API Response Structure

		The registration API returns:

		```json
		{
		"api_key": "kz_live_abc123...",
		"vault_id": "vault_xyz789...",
		"vault_name": "KnowzCode"
		}
		```

		This vault is automatically configured for you - no manual setup required.

		## Your Task

		Guide the user through registration step-by-step, one question at a time. This is an interactive conversational flow - do NOT ask multiple questions at once.

		CRITICAL: Interactive Flow Rules
		1. Ask ONE question, then WAIT for user response
		2. After each response, validate and then ask the NEXT question
		3. Never combine multiple questions into a single message
		4. Use AskUserQuestion tool for each input collection step
		5. After each AskUserQuestion, STOP and wait for the user's answer

		### Conversation Flow Summary

		```
		YOU USER
		─────────────────────────────────────────────────
		1. Check MCP config
		2. Welcome + Ask name ──────────► [User types name]
		3. Validate name
		4. Ask email ───────────────────► [User types email]
		5. Validate email
		6. Ask password ────────────────► [User types password]
		7. Validate password
		8. Show summary + confirm ──────► [User confirms: Yes/No/Edit]
		9. Call API
		10. Configure MCP + base vault
		11. Vault discovery ───────────► [User: Yes/No to configure more]
		12. (If Yes) Vault selection ──► [User selects vaults + descriptions]
		13. Write vault config
		14. Show success
		```

		### Steps to Execute

		#### Step 0: Smart Discovery

		Before starting registration, check if user already has a KnowzCode API key:

		1. Check `KNOWZ_API_KEY` environment variable
		2. Check `knowzcode/mcp_config.md` — if `Connected: Yes`, existing config exists
		3. Check cross-platform configs: `.gemini/settings.json`, `.vscode/mcp.json`, `.mcp.json`
		- Extract Bearer token from Authorization headers if found

		If existing API key found:
		```
		You already have a KnowzCode API key configured (ending ...{last4}) from {source}.

		Options:
		1. Use existing key — run /kc:connect-mcp to configure this platform
		2. Register a new account anyway
		3. Cancel
		```

		If user chooses option 1: advise running `/kc:connect-mcp` with discovered key.
		If user chooses option 2: proceed with registration normally (Step 1).
		If user chooses option 3: stop.

		#### Step 1: Check Existing Configuration

		1. Check if MCP server already configured:
		```bash
		CLAUDECODE= claude mcp get knowz
		```

		2. If already configured, display:
		```
		⚠️ KnowzCode MCP server is already configured.

		Options:
		1. Keep existing configuration (abort registration)
		2. Remove existing and register new account

		If you want to register a new account, the existing configuration
		will be replaced with the new API key.
		```

		Use AskUserQuestion to get user choice. If they choose to keep existing, STOP.
		If they choose to continue, run `CLAUDECODE= claude mcp remove knowz` first.

		3. If not configured: Continue to Step 2.

		#### Step 2: Welcome Message and First Question

		Display welcome message, then IMMEDIATELY ask the first question (name):

		```
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		◆ KnowzCode REGISTRATION
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		Welcome! Let's set up your KnowzCode account.

		This will:
		1. Create your KnowzCode account
		2. Generate an API key
		3. Configure the MCP server automatically

		I'll ask you a few questions one at a time.
		All data transmitted securely over HTTPS.
		Privacy policy: https://knowz.io/privacy
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		```

		Then immediately use AskUserQuestion to collect name:

		Question: "What name would you like for your account?"

		STOP HERE and wait for user response.

		#### Step 3: Validate Name and Ask Email

		After receiving the name:

		Validation:
		- Must be non-empty
		- Must be 2-100 characters
		- Allow: letters, spaces, hyphens, apostrophes

		If invalid, explain the issue and re-prompt for name.

		If valid, store the name and proceed to ask for email.

		#### Step 4: Ask for Email

		Use AskUserQuestion to collect the user's email:

		Question: "What is your email address?"

		STOP HERE and wait for user response.

		#### Step 5: Validate Email and Ask Password

		After receiving the email:

		Validation:
		- Must match email pattern (contains @ and domain)
		- No leading/trailing whitespace

		If invalid:
		```
		⚠️ Invalid email format.
		Please enter a valid email address (e.g., user@example.com)
		```
		Re-prompt for email.

		If valid, store the email and proceed to ask for password.

		Use AskUserQuestion to collect the password:

		Question: "Create a password (minimum 8 characters)"

		Display this note with the question:
		```
		Your password will be sent securely over HTTPS to create your account.
		It will NOT be stored locally or displayed in any logs.
		```

		STOP HERE and wait for user response.

		#### Step 6: Validate Password

		After receiving the password:

		Validation:
		- Minimum 8 characters

		If invalid:
		```
		⚠️ Password must be at least 8 characters.
		```
		Re-prompt for password.

		If valid, store the password and proceed to confirmation.

		#### Step 7: Confirm Details

		Display collected information for confirmation:

		```
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		◆ CONFIRM REGISTRATION DETAILS
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		Please confirm your registration details:

		Name: {collected_name}
		Email: {collected_email}
		Password: ********

		Is this correct?
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		```

		Use AskUserQuestion with options:
		- Yes - Proceed with registration
		- No - Cancel registration
		- Edit - Go back and re-enter information

		STOP HERE and wait for user response.

		- If "Edit": Return to Step 2 to re-collect all information (name first).
		- If "No": Display cancellation message and STOP.
		- If "Yes": Proceed to Step 8.

		#### Step 8: Call Registration API

		Determine endpoint based on `--dev` flag:
		- If `--dev` flag present: Use `https://api.dev.knowz.io/api/v1/auth/register`
		- Otherwise (default): Use `https://api.knowz.io/api/v1/auth/register`

		Make HTTP POST request to registration endpoint:

		```bash
		# Production (default)
		curl -X POST https://api.knowz.io/api/v1/auth/register \
		-H "Content-Type: application/json" \
		-d '{
		"name": "{collected_name}",
		"email": "{collected_email}",
		"password": "{collected_password}"
		}'

		# Development (with --dev flag)
		curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
		-H "Content-Type: application/json" \
		-d '{
		"name": "{collected_name}",
		"email": "{collected_email}",
		"password": "{collected_password}"
		}'
		```

		Handle Response Codes:

		\| Code \| Meaning \| Action \|
		\|------\|---------\|--------\|
		\| 200/201 \| Success \| Extract API key AND vault_id, continue to Step 9 \|
		\| 400 \| Validation error \| Show error details, return to relevant step \|
		\| 409 \| Email exists \| Show recovery options (see Error Handling) \|
		\| 429 \| Rate limited \| Show wait message (see Error Handling) \|
		\| 500+ \| Server error \| Show error and support link \|

		Parse Response:
		- Extract `api_key` (or `apiKey` or `token` field)
		- Extract `vault_id` (auto-created "KnowzCode" vault)
		- Extract `vault_name` (typically "KnowzCode")

		#### Step 9: Configure MCP, Vault, and Show Success

		On successful registration:

		1. Extract from response:
		- API key (look for `apiKey`, `api_key`, or `token` field)
		- Vault ID (look for `vault_id` or `vaultId` field)
		- Vault name (look for `vault_name` or `vaultName` field, default: "KnowzCode")

		2. Parse scope from command arguments (default: `local`)

		3. If scope is `project`, show security warning:
		```
		⚠️ Security Note: Project Scope Selected

		With project scope, your API key will be stored in .mcp.json
		which is typically committed to git.

		This is appropriate for:
		• Team/shared API keys
		• CI/CD automation keys

		For personal keys, consider using --scope local (default)

		Continue with project scope?
		```
		Use AskUserQuestion to confirm. If user declines, use `local` scope instead.

		4. Configure MCP server (use same environment as registration):

		Ask the user which auth method to use:
		```
		How would you like to authenticate with the MCP server?

		OAuth (recommended) — log in via browser, no key stored locally
		API Key — use the key from registration
		```
		Use AskUserQuestion with options: [OAuth (recommended)] [API Key]

		If OAuth selected:

		For Claude Code — add MCP server without Authorization header:
		```bash
		claude mcp add --transport http \
		--scope <chosen-scope> \
		knowz \
		<endpoint-url> \
		--header "X-Project-Path: $(pwd)"
		```
		On first tool call after restart, the server returns `401 + WWW-Authenticate` and Claude Code opens a browser for the user to log in.

		For Gemini CLI (if `.gemini/` directory exists) — write OAuth config:
		```json
		{ "mcpServers": { "knowz": { "httpUrl": "<endpoint>", "authProviderType": "dynamic_discovery" } } }
		```

		Set `API Key (last 4): OAuth Token` in mcp_config.md (Step 6).

		If API Key selected:

		For Claude Code — use `claude mcp add` with API key:
		```bash
		claude mcp add --transport http \
		--scope <chosen-scope> \
		knowz \
		<endpoint-url> \
		--header "Authorization: Bearer <api_key>" \
		--header "X-Project-Path: $(pwd)"
		```

		For Gemini CLI (if `.gemini/` directory exists) — write API key config:
		```json
		{
		"mcpServers": {
		"knowz": {
		"httpUrl": "<endpoint>",
		"headers": {
		"Authorization": "Bearer <api_key>",
		"X-Project-Path": "<project_path>"
		}
		}
		}
		}
		```

		Cross-platform: If both Claude Code and Gemini are detected (`.gemini/` directory exists), configure both with the chosen auth method and report each.

		5. Verify MCP configuration:
		```bash
		CLAUDECODE= claude mcp get knowz
		```

		6. Configure vault in mcp_config.md:

		Check if `knowzcode/mcp_config.md` exists:
		- If exists: Merge vault configuration (preserve existing Code Vault if set)
		- If not exists: Create from template with vault configured

		Update `knowzcode/mcp_config.md` with:
		```markdown
		# KnowzCode MCP Configuration

		## Connection Status
		- Connected: Yes
		- Endpoint: {endpoint}
		- Last Verified: {ISO timestamp}
		- API Key (last 4): {last 4 characters of the API key}

		---

		## Vaults

		### Ecosystem Vault (Primary)
		- Vault ID: {vault_id from registration}
		- Vault Name: {vault_name from registration}
		- Purpose: Decisions, conventions, security, integrations, business rules
		- Auto-configured: Yes (via /kc:register)

		### Code Vault (Optional)
		- Vault ID: (not configured)
		- Purpose: Implementation patterns, workarounds, performance
		- Note: Code search uses local grep/glob by default.
		Configure code vault for large codebases with /kc:connect-mcp --configure-vaults

		### Finalizations Vault (Optional)
		- Vault ID: (not configured)
		- Purpose: WorkGroup completion summaries, outcome records
		- Note: Finalizations vault tracks completed work.
		Configure for teams that want searchable completion history.
		```

		Edge case - existing vault config:
		If `knowzcode/mcp_config.md` already has an Ecosystem Vault ID configured:
		- Use AskUserQuestion: "You already have a vault configured. Replace with new vault from registration? [Yes/No/Keep both]"
		- If "Yes": Replace Ecosystem Vault ID
		- If "No": Keep existing vault config
		- If "Keep both": Add new vault as secondary

		7. Display success message with vault info:

		```
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		◆ KnowzCode REGISTRATION COMPLETE
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		✅ Account created and configured!

		Account Details:
		• Email: {email}
		• Auth: {OAuth OR API Key: masked_key}

		MCP Configuration:
		• Scope: {chosen-scope}
		• Endpoint: {endpoint}
		• Environment: {Production OR Development}
		• Platforms: {list configured platforms, e.g. "Claude Code, Gemini CLI"}
		• Status: Configured

		Vault Configuration:
		• Vault: {vault_name} ({vault_id prefix...})
		• Purpose: Learnings, conventions, patterns
		• Status: Ready for use

		🔄 Please restart Claude Code to activate MCP features.
		{If OAuth: "On first tool call, your browser will open for authentication."}

		After restart, you'll have access to:
		• search_knowledge - Vector search across vaults
		• ask_question - AI Q&A with research mode
		• create_knowledge - Save learnings (via /kc:learn)
		• update_knowledge - Update existing knowledge items

		━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		📋 Next Steps:
		1. Restart Claude Code
		2. Verify connection: /kc:status
		3. Try learning capture: /kc:learn "Your first insight"
		4. Start building: /kc:work "your feature"

		Need help? https://knowz.io/docs
		◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		```

		Masking:
		- API Key: Show only first 6 and last 4 characters (e.g., `kz_liv...wxyz`)
		- Vault ID: Show only first 8 characters (e.g., `vault_xy...`)

		#### Step 10: Vault Discovery and Multi-Vault Selection

		Vault Discovery: Read [references/vault-discovery.md](references/vault-discovery.md) for vault discovery flow.

		## Error Handling

		Error Handling: Read [references/error-handling.md](references/error-handling.md) when handling API errors.

		## Security Considerations

		### Data Protection
		- HTTPS only - All API calls use HTTPS
		- Password not stored - Password sent once, never saved locally
		- Password not logged - Never display password in output
		- Minimal data - Only collect what's needed for registration

		### API Key Security
		- Mask displayed keys: Show only `kz_abc...xyz` format (first 6 + last 4 chars)
		- Never log full keys: Exclude from any diagnostic output
		- Warn about project scope: If `--scope project`, warn that API key will be in `.mcp.json`
		- Recommend local scope: Default to most secure option

		## Scope Comparison

		\| Scope \| Storage \| Visibility \| Best For \|
		\|-------\|---------\|------------\|----------\|
		\| local (default) \| Claude Code internal \| Only you, this project \| Personal development \|
		\| project \| `.mcp.json` (git) \| Team via git \| Shared team key \|
		\| user \| Claude Code user config \| Only you, all projects \| Personal, multi-project \|

		## Related Commands

		- `/kc:connect-mcp` - Configure MCP with existing API key
		- `/kc:status` - Check MCP connection status
		- `/kc:init` - Initialize KnowzCode in project

		Execute this registration flow now.

bin/knowzcode.mjs

Sorry, the diff of this file is too big to display

knowzcode/platform_adapters.md

Sorry, the diff of this file is too big to display

		---
		name: knowledge-liaison
		description: "KnowzCode: Persistent context and knowledge liaison — dispatches local scouts and vault readers, aggregates and pushes context, routes vault I/O across all phases"
		tools: Read, Write, Edit, Glob, Grep, Task
		model: sonnet
		permissionMode: acceptEdits
		maxTurns: 40
		---

		# Knowledge Liaison

		You are the Knowledge Liaison in a KnowzCode development workflow.
		Your expertise: Bridging local project context and external Knowz vault agents across all phases.

		## Your Job

		Own all context gathering (local + vault) and vault I/O routing throughout the workflow lifecycle. You are the single point of accountability for context delivery and vault I/O — no other agent dispatches `knowz:writer` or `knowz:reader` directly.

		You do NOT have MCP tools. You delegate all vault I/O by dispatching `knowz:writer` (for writes) and `knowz:reader` (for queries).

		## Lifecycle

		- Spawn: Stage 0, Group A (always — unconditional)
		- Active: Stage 0 through team shutdown
		- Shutdown: Last agent shut down before team lead deletes team

		## Startup — Parallel Context Dispatch

		At startup, dispatch all research as subagents in parallel. Your main thread stays free for DMs and coordination.

		1. Read `knowzcode/knowzcode_vaults.md` — note vault IDs, types, routing rules
		2. Check `knowzcode/pending_captures.md` for pending captures
		- If non-empty: inform the lead: `"Note: {N} pending captures exist. Run /knowz flush to sync."`
		3. Dispatch research subagents in parallel (single turn, multiple Task() calls):

		a. Local context scouts (1-3 subagents depending on project size):
		- `Task(subagent_type="general-purpose", description="Scout: specs + architecture")`:
		> Read `knowzcode/specs/*.md` (titles + key sections), `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_project.md`.
		> Return: relevant specs (NodeIDs, status, VERIFY criteria), architecture summary, project standards.
		- `Task(subagent_type="general-purpose", description="Scout: workgroups + history")`:
		> Read `knowzcode/workgroups/*.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_log.md`.
		> Return: prior WorkGroups for similar goals, active WIP, REFACTOR tasks, recent log patterns.
		- (Optional 3rd scout for large projects with many specs/workgroups)

		b. Vault reader (if vaults configured):
		- `Task(subagent_type="knowz:reader", description="Reader: vault knowledge for {goal}")`:
		> Query configured vaults for: past decisions about {goal domain}, conventions, implementation patterns, known workarounds.

		4. Aggregate and push: As subagent results arrive, build the Context Briefing. DM analyst AND architect:
		> Context Briefing for {agent}:
		> Local: {specs, prior WorkGroups, active WIP, architecture context}
		> Vault: {past decisions, conventions, patterns} (or "No vaults configured" / "Vault query pending")
		> Gaps: {areas with no prior knowledge — flag for fresh research}

		Push local context as soon as scout subagents complete — don't wait for vault reader.
		When vault results arrive, send a follow-up DM with vault findings.

		## Capture Requests

		Accept capture messages from other agents and dispatch `knowz:writer` accordingly:

		\| Message Format \| From \| Trigger \|
		\|----------------\|------\|---------\|
		\| `"Capture Phase {N}: {wgid}. Your task: #{task-id}"` \| lead \| Quality gate approval \|
		\| `"Capture Phase 3: {wgid}. Your task: #{task-id}"` \| closer \| Phase 3 finalization \|
		\| `"Log: {description}"` \| any agent \| Explicit capture — writer MUST write it \|
		\| `"Consider: {idea}"` \| any agent \| Soft capture — writer evaluates whether to log \|

		## Query Requests

		Accept vault query messages from any agent:

		\| Message Format \| From \| Action \|
		\|----------------\|------\|--------\|
		\| `"VaultQuery: {question}"` \| any agent \| Dispatch `knowz:reader` with the question, forward results back to requester \|

		## Writer Dispatch

		When you receive a capture request:

		1. Read source material: Read the WorkGroup file (`knowzcode/workgroups/{wgid}.md`) to extract relevant content
		2. Determine extraction targets: Use the Phase Extraction Guide below to know what to extract at each phase
		3. Resolve vault routing: Read `knowzcode/knowzcode_vaults.md` — resolve vault IDs by learning category using the Write Routing table
		4. Construct writer prompt: Build a self-contained `knowz:writer` dispatch prompt including:
		- What to extract (phase-specific extraction targets)
		- Target vault IDs (resolved, not types)
		- Content format templates (from vault config)
		- Source file path (WorkGroup file)
		5. Create task and dispatch: `TaskCreate("Writer: Capture Phase {N}: {wgid}")` → dispatch `knowz:writer` with the prompt

		### Reader Dispatch

		When you receive a query request or need Stage 0 research:

		1. Construct a self-contained `knowz:reader` dispatch prompt including:
		- The question or goal-relevant queries
		- Vault IDs and descriptions from `knowzcode/knowzcode_vaults.md`
		- Expected output format
		2. Create task and dispatch: `TaskCreate("Reader: {query summary}")` → dispatch `knowz:reader` with the prompt

		## Phase Extraction Guide

		### Phase 1A (after Gate #1 approval)
		- NodeIDs: List each with description, affected files, and domain area
		- Risk assessment: Full reasoning — what could break, high-risk files, mitigation planned. Never write just "Medium"
		- Scope decisions: What was included/excluded and why — alternatives the user considered
		- Vault routing: Scope/Decision → ecosystem vault
		- Format: `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS] scope, {domain}`
		- Title prefix: `Scope:` or `Decision:`

		### Phase 2A (after implementation)
		- Patterns discovered: Description, why needed, how it works, file paths or code snippets
		- Workarounds: What limitation was hit, what the workaround does, upstream fix to watch for
		- New utilities or abstractions: What was created, API surface, where it's used
		- Performance optimizations: Before/after metrics, technique used, trade-offs
		- Vault routing: Pattern/Workaround/Performance → code vault. Decision → ecosystem vault
		- Format (code): `[CONTEXT] ... [PATTERN] ... [EXAMPLE] ... [TAGS]`
		- Format (ecosystem): `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS]`
		- Title prefix: `Pattern:`, `Workaround:`, `Performance:`, or `Decision:`

		### Phase 2B (after Gate #3 approval)
		- Audit findings: Completion percentage, specific gaps with file paths and line references
		- Security issues: Vulnerability description, affected code paths, severity reasoning, how it was fixed
		- Gap resolution decisions: What was deferred vs fixed, rationale for each
		- Vault routing: Security/Decision → ecosystem vault. Enterprise audit trail → enterprise vault (if configured)
		- Format: `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS] audit, {domain}`
		- Title prefix: `Security:`, `Decision:`, or `Audit:`

		### Phase 3 (finalization)
		- Architectural learnings: Structural discoveries, component relationships not obvious, integration patterns
		- Convention patterns established: New team conventions with full rationale and examples
		- Consolidation decisions: What was merged or refactored during finalization and why
		- Implementation patterns: Pattern/Workaround/Performance insights from Phase 2A not already captured
		- Scope decisions: What was included/excluded and rationale (from Phase 1A)
		- Security findings: From Phase 2B audit, with severity and remediation
		- Vault routing: Pattern/Workaround/Performance → code vault. Decision/Convention/Security/Integration/Scope → ecosystem vault. Completion record → finalizations vault
		- Format (code): `[CONTEXT] ... [PATTERN] ... [EXAMPLE] ... [TAGS]`
		- Format (ecosystem): `[CONTEXT] ... [INSIGHT] ... [RATIONALE] ... [TAGS]`
		- Format (finalizations): `[GOAL] ... [OUTCOME] ... [NODES] ... [DURATION] ... [SUMMARY] ... [TAGS]`

		## MCP Graceful Degradation

		If `knowz:writer` dispatch fails or reports MCP unavailability:

		1. Queue locally: Append each capture to `knowzcode/pending_captures.md`:
		```markdown
		### {timestamp} — {title}
		- Intent: {Phase capture identifier}
		- Category: {Pattern\|Decision\|Workaround\|Performance\|Security\|Convention\|Integration\|Scope\|Completion}
		- Target Vault Type: {code\|ecosystem\|enterprise\|finalizations}
		- Source: knowledge-liaison / WorkGroup {wgid}
		- Content: {full formatted content that would have been written to the vault}
		```
		2. Report the failure to the lead: `"WARNING: Writer dispatch failed for Phase {N} capture. {N} item(s) queued to pending_captures.md."`
		3. The pending file can be flushed later via `/knowz flush`

		Never drop knowledge. If MCP is down, queue it.

		## Communication

		- Report capture confirmations to the lead: `"Phase {N} capture complete: {count} items written to {vault names}. Dedup catches: {count}."`
		- Forward query results to the requesting agent
		- Report errors explicitly — never degrade silently
		- Report queued items if MCP unavailable

		## What You Do NOT Do

		- Call MCP tools directly — you delegate to `knowz:writer` and `knowz:reader`
		- Make decisions about workflow phases — the lead and closer tell you when to capture
		- Write source code or modify project files (beyond `knowzcode/pending_captures.md` for fallback)
		- Shut down before all other agents — you are the last agent shut down before team cleanup

		@@ -9,13 +9,13 @@ # KnowzCode Automation Manifest
		\| --- \| --- \|
		\| `/kc:work` \| Start feature workflow with TDD, quality gates, and structured phases \|
		\| `/kc:plan` \| Research and investigate using parallel agents before implementing \|
		\| `/kc:audit` \| Run quality audits (spec, architecture, security, integration) \|
		\| `/kc:fix` \| Execute targeted micro-fix workflow \|
		\| `/kc:init` \| Initialize KnowzCode in current project + generate platform adapters \|
		\| `/kc:telemetry` \| Investigate production telemetry \|
		\| `/kc:telemetry-setup` \| Configure telemetry sources \|
		\| `/kc:connect-mcp` \| Configure MCP server connection \|
		\| `/kc:learn` \| Capture learning to vault \|
		\| `/kc:register` \| Register and configure MCP \|
		\| `/kc:status` \| Check MCP and vault status \|
		\| `/knowzcode:work` \| Start feature workflow with TDD, quality gates, and structured phases \|
		\| `/knowzcode:explore` \| Research and investigate using parallel agents before implementing \|
		\| `/knowzcode:audit` \| Run quality audits (spec, architecture, security, integration) \|
		\| `/knowzcode:fix` \| Execute targeted micro-fix workflow \|
		\| `/knowzcode:init` \| Initialize KnowzCode in current project + generate platform adapters \|
		\| `/knowzcode:telemetry` \| Investigate production telemetry \|
		\| `/knowzcode:telemetry-setup` \| Configure telemetry sources \|
		\| `/knowz setup` \| Configure MCP server connection (knowz plugin) \|
		\| `/knowz save` \| Capture learning to vault (knowz plugin) \|
		\| `/knowz register` \| Register and configure MCP (knowz plugin) \|
		\| `/knowzcode:status` \| Check MCP and vault status \|

		@@ -39,3 +39,3 @@ ## Agents
		\| --- \| --- \|
		\| `start-work` \| Detect implementation intent and redirect to /kc:work \|
		\| `start-work` \| Detect implementation intent and redirect to /knowzcode:work \|
		\| `continue` \| Detect continuation intent and resume active WorkGroup \|
		@@ -42,0 +42,0 @@ \| `load-core-context` \| Load project overview, architecture, tracker into memory \|

		@@ -102,7 +102,7 @@ # Claude Code Execution Model

		At the start of a workflow (`/kc:work`, `/kc:plan`, `/kc:audit`), the lead creates a team before spawning any teammates:
		At the start of a workflow (`/knowzcode:work`, `/knowzcode:explore`, `/knowzcode:audit`), the lead creates a team before spawning any teammates:

		- `/kc:work`: Team name `kc-{wgid}` (matches the WorkGroup ID)
		- `/kc:plan`: Team name `kc-plan-{slug}` (from the research topic)
		- `/kc:audit`: Team name `kc-audit-{timestamp}`
		- `/knowzcode:work`: Team name `kc-{wgid}` (matches the WorkGroup ID)
		- `/knowzcode:explore`: Team name `kc-explore-{slug}` (from the research topic)
		- `/knowzcode:audit`: Team name `kc-audit-{timestamp}`

		@@ -143,3 +143,3 @@ Creating a team establishes:

		> Note: In `/kc:work` Parallel Teams mode, teammates coexist within stages: scouts run alongside analysts, builders and reviewers persist through the gap loop. The messaging patterns below are actively used. In Sequential Teams mode (`--sequential`), teammates are spawned one at a time — inter-phase communication goes through the lead via WorkGroup files.
		> Note: In `/knowzcode:work` Parallel Teams mode, teammates coexist within stages: knowledge-liaison pushes context to analysts, builders and reviewers persist through the gap loop. The messaging patterns below are actively used. In Sequential Teams mode (`--sequential`), teammates are spawned one at a time — inter-phase communication goes through the lead via WorkGroup files.

		@@ -150,3 +150,3 @@ Use mailbox messaging for coordination between teammates:
		\|------\|-----\|------\|
		\| scout \| all \| Initial context/vault findings (broadcast) \|
		\| knowledge-liaison \| analyst, architect \| Context Briefing with local + vault findings (DM) \|
		\| scanner \| all \| Codebase scan findings — affected files, test patterns (broadcast) \|
		@@ -162,4 +162,7 @@ \| analyst \| architect \| `[PRELIMINARY]` NodeID findings during Stage 0 (max 3 DMs), scope clarifications, NodeID overlap with existing specs \|
		\| lead \| reviewer \| Re-audit requests after gap fixes (task creation + DM) \|
		\| lead \| knowz-scribe \| Capture messages at quality gates (`"Capture Phase 1A: {wgid}"`, etc.) \|
		\| closer \| knowz-scribe \| Phase 3 learning capture (`"Capture Phase 3: {wgid}"`) \|
		\| lead \| knowledge-liaison \| Capture DMs at quality gates: `"Capture Phase {N}: {wgid}"` \|
		\| knowledge-liaison \| knowz:writer dispatch \| Dispatch writer with self-contained extraction prompts \|
		\| knowledge-liaison \| knowz:reader dispatch \| Dispatch reader for vault queries \|
		\| closer \| knowledge-liaison \| Phase 3 capture DM: `"Capture Phase 3: {wgid}"` \|
		\| any agent \| knowledge-liaison \| `"Log: ..."`, `"Consider: ..."`, `"VaultQuery: ..."` \|
		\| closer \| analyst \| Change scope for log entry accuracy \|
		@@ -176,3 +179,3 @@ \| closer \| architect \| Spec format and legacy migration \|
		\| project-advisor \| lead \| Backlog context (Stage 0) and proposals (late Stage 2) \|
		\| project-advisor \| knowz-scribe \| Idea captures for vault storage \|
		\| project-advisor \| knowledge-liaison \| Idea captures: `"Consider: {idea}"` (knowledge-liaison dispatches knowz:writer if warranted) \|

		@@ -198,3 +201,3 @@ ### Gap Communication Flow

		This section defines conventions specific to Parallel Teams mode in `/kc:work`. For the full orchestration flow, see `skills/work/SKILL.md`.
		This section defines conventions specific to Parallel Teams mode in `/knowzcode:work`. For the full orchestration flow, see `skills/work/SKILL.md`.

		@@ -208,3 +211,3 @@ ### Lead Responsibilities in Parallel Mode
		- Lead uses DM messages alongside task creation to provide context and coordinate
		- Lead owns progress documentation — at every quality gate, the lead creates scribe capture tasks and sends capture messages (e.g., "Capture Phase 1A: {wgid}"). No other agent initiates gate captures. If the scribe is unavailable, the lead ensures the closer is briefed to handle vault writes at Phase 3.
		- Lead owns progress documentation — at every quality gate, the lead DMs the knowledge-liaison with capture requests (e.g., `"Capture Phase 1A: {wgid}. Your task: #{task-id}"`). No other agent initiates gate captures. If the knowledge-liaison is unavailable, the lead ensures the closer handles vault writes at Phase 3.

		@@ -226,9 +229,4 @@ ### Task Assignment Protocol
		\|-------\|----------\|-------------\|---------------------\|
		\| 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 \|
		@@ -242,2 +240,3 @@ \| 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 \|
		\| project-advisor \| Stage 0 (Group C) \| Mid-Stage 2 \| Backlog curation + idea capture (advisor — informational) \|
		\| knowledge-liaison \| Stage 0 (Group A) \| Last before team cleanup \| Persistent context & vault coordinator — dispatches scouts, pushes context, routes vault I/O \|
		\| closer \| Stage 3 \| End of workflow \| Finalization \|
		@@ -254,3 +253,3 @@

		- Stage 0 tasks: scout + scanner + knowz-scribe + analysis tasks (no deps)
		- Stage 0 tasks: scanner + analysis tasks (no deps, knowz:writer dispatched at gates)
		- 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
		@@ -267,5 +266,4 @@ - Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
		\| `max_builders` \| 5 \| `--max-builders=N` \| Cap concurrent builders (1-5) \|
		\| `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) \|
		\| `mcp_agents_enabled` \| true \| `--no-mcp` \| Toggle vault agents (knowz:reader, knowz:writer dispatches) \|
		\| `codebase_scanner_enabled` \| true \| `--no-scanners` \| Toggle codebase scanner agents (scanner-direct, scanner-tests) \|
		@@ -286,3 +284,3 @@ \| `parallel_spec_threshold` \| 3 \| `--no-parallel-specs` \| NodeID count threshold for parallel spec drafting (Path B) \|

		In `/kc:work` Parallel Teams mode, agents persist across sub-phases for efficiency:
		In `/knowzcode:work` Parallel Teams mode, agents persist across sub-phases for efficiency:

		@@ -325,12 +323,11 @@ #### Build + Audit Loop

		When specialists are enabled, three additional agents spawn at Stage 0 alongside Groups A and B:
		When specialists are enabled, three additional agents spawn at Stage 0 alongside Group A:

		```
		Group A (always): 3 context-scouts + analyst + architect (5 agents)
		Group A (always): knowledge-liaison + analyst + architect (3 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-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.
		Max Stage 0 concurrent: 3-8 agents depending on orchestration config (scanners, specialists). Scanners shut down after Stage 1, so Stage 2 peak is manageable.

		@@ -352,3 +349,3 @@ ##### Officer vs Advisor Authority
		- test-advisor → builder-N: Specific test improvement feedback (max 2 DMs per builder)
		- project-advisor → knowz-scribe: Idea captures for vault storage
		- project-advisor → knowledge-liaison: Idea captures (`"Consider: {idea}"` — knowledge-liaison dispatches knowz:writer if warranted)
		- security-officer ↔ test-advisor: Cross-cutting test gaps in security paths (max 2 inter-specialist DMs total)
		@@ -369,5 +366,5 @@

		1. Progress documentation via knowz-scribe: At every quality gate, the lead triggers knowledge capture. In Parallel Teams, this means creating scribe capture tasks and sending DMs. In Sequential/Subagent modes where the scribe is not spawned, the lead passes MCP status and vault config to the closer's spawn prompt so Phase 3 captures are handled via Direct Write Fallback.
		1. Progress documentation via knowz:writer: At every quality gate, the lead triggers knowledge capture. In Parallel Teams, this means dispatching knowz:writer with self-contained prompts. In Sequential/Subagent modes where vault agents are not dispatched, the lead passes MCP status and vault config to the closer's spawn prompt so Phase 3 captures are handled via Direct Write Fallback.
		2. MCP status handoff: The lead performs the MCP probe and communicates the result downstream — either by spawning vault agents (Parallel) or by including `MCP_ACTIVE` and `VAULTS_CONFIGURED` status in the closer's spawn prompt (Sequential/Subagent).
		3. Capture completeness verification: The lead confirms all gate captures completed before shutting down the scribe or proceeding to the next stage.
		3. Capture completeness verification: The lead confirms all gate captures completed before shutting down the writer or proceeding to the next stage.

		@@ -412,5 +409,5 @@ ---
		\|---------\|---------\|---------\|
		\| `/kc:work` \| microfix-specialist \| Redirect when fix exceeds scope gate \|
		\| `/kc:audit security` \| reviewer \| Full security audit mode \|
		\| `/kc:audit spec` \| knowledge-migrator \| Post-migration validation \|
		\| `/knowzcode:work` \| microfix-specialist \| Redirect when fix exceeds scope gate \|
		\| `/knowzcode:audit security` \| reviewer \| Full security audit mode \|
		\| `/knowzcode:audit spec` \| knowledge-migrator \| Post-migration validation \|

		@@ -425,4 +422,4 @@ On other platforms, these commands translate to running the corresponding phase prompts manually.

		1. Run `/kc:status` — check the Agent Teams section for "Enabled" status and agent definitions
		2. Run `/kc:work` — confirm a mode announcement appears before Phase 1A (either "Agent Teams" or "Subagent Delegation")
		1. Run `/knowzcode:status` — check the Agent Teams section for "Enabled" status and agent definitions
		2. Run `/knowzcode:work` — confirm a mode announcement appears before Phase 1A (either "Agent Teams" or "Subagent Delegation")
		3. In-process mode: press Shift+Down to see spawned teammates in the panel
		@@ -438,3 +435,3 @@ 4. Check the WorkGroup file — should show phase transitions with timestamps in the Phase History table
		\| Agents seem generic / no specialization \| Agent definitions not loaded \| Check `agents/` directory exists with `.md` files for each role \|
		\| No quality gates appearing \| Command instructions not followed \| Re-run `/kc:work` with an explicit goal description \|
		\| No quality gates appearing \| Command instructions not followed \| Re-run `/knowzcode:work` with an explicit goal description \|
		\| Teammates not visible in panel \| Using tmux mode on Windows \| Windows uses in-process mode — teammates won't appear in a split pane \|
		@@ -441,0 +438,0 @@

		@@ -45,5 +45,5 @@ # KnowzCode Vault Configuration
		\|------\|---------\|---------\|------------\|-----------------\|
		\| code \| Implementation patterns, workarounds, performance \| knowz-scout, knowz-scribe, agents \| knowz-scribe \| "Find auth middleware pattern", "Retry logic workaround" \|
		\| ecosystem \| Decisions, conventions, security, integrations, business rules \| knowz-scout, knowz-scribe, agents \| knowz-scribe \| "Error handling conventions", "Why Redis over Memcached?" \|
		\| finalizations \| WorkGroup completion summaries, outcome records \| knowz-scout, knowz-scribe \| knowz-scribe \| "What happened in WG-feat-auth?", "Recent completions" \|
		\| code \| Implementation patterns, workarounds, performance \| knowz:reader, agents \| knowz:writer \| "Find auth middleware pattern", "Retry logic workaround" \|
		\| ecosystem \| Decisions, conventions, security, integrations, business rules \| knowz:reader, agents \| knowz:writer \| "Error handling conventions", "Why Redis over Memcached?" \|
		\| finalizations \| WorkGroup completion summaries, outcome records \| knowz:reader, agents \| knowz:writer \| "What happened in WG-feat-auth?", "Recent completions" \|

		@@ -58,3 +58,3 @@ > Types are user-configurable labels, not framework constants. Users can add, rename, or create custom vault types freely. The 3 defaults above cover common needs. For example, teams needing compliance tracking can add an `enterprise` type.

		### Read Routing (knowz-scout + agents)
		### Read Routing (knowz:reader + agents)

		@@ -69,3 +69,3 @@ \| Query Type \| Description \| Target Vault Type \|

		### Write Routing (knowz-scribe)
		### Write Routing (knowz:writer)

		@@ -87,4 +87,4 @@ \| Learning Category \| Target Vault Type \| Title Prefix \|

		1. For reads: Agent reads vault descriptions and matches query intent to vault type
		2. For writes: Knowz-scribe matches learning category to vault type using the write routing table, then applies the vault's content filter to format the payload
		1. For reads: Reader agent reads vault descriptions and matches query intent to vault type
		2. For writes: Writer agent matches learning category to vault type using the write routing table, then applies the vault's content filter to format the payload
		3. Fallback: If no specific match, use the first vault of type `ecosystem`. If only one vault exists, use it for everything
		@@ -102,4 +102,4 @@

		1. `/kc:register` and `/kc:connect-mcp` — detect empty IDs during initial setup and prompt to create vaults
		2. `/kc:work`, `/kc:plan`, and `/kc:audit` — detect empty IDs during the MCP Probe at workflow start. These commands always call `list_vaults()` regardless of whether vault IDs exist, then present a Vault Setup table showing each uncreated vault's name, type, description, and which phases write to it. The user can create all, select specific vaults, or skip (proceeding without knowledge capture).
		1. `/knowz register` and `/knowz setup` — detect empty IDs during initial setup and prompt to create vaults
		2. `/knowzcode:work`, `/knowzcode:explore`, and `/knowzcode:audit` — detect empty IDs during the MCP Probe at workflow start. These commands always call `list_vaults()` regardless of whether vault IDs exist, then present a Vault Setup table showing each uncreated vault's name, type, description, and which phases write to it. The user can create all, select specific vaults, or skip (proceeding without knowledge capture).

		@@ -204,4 +204,4 @@ ### Creation Flow
		│ Purpose: All learnings, decisions, patterns, etc. │
		│ Read by: knowz-scout, knowz-scribe, all agents │
		│ Written by: knowz-scribe, /kc:learn │
		│ Read by: knowz:reader, all agents │
		│ Written by: knowz:writer, /knowz save │
		│ Code search: Uses local grep/glob (no code vault) │
		@@ -216,3 +216,3 @@ │ │
		- MCP vault is optimized for organizational knowledge
		- Add specialized vaults later via `/kc:connect-mcp --configure-vaults`
		- Add specialized vaults later via `/knowz setup`

		@@ -231,3 +231,3 @@ ---
		- Description: {Detailed description of what this vault contains. Be specific about what types of questions should be routed here. Include example queries.}
		- Write Conditions: {When knowz-scribe should write to this vault}
		- Write Conditions: {When knowz:writer should write to this vault}
		- Content Filter: {Format template for create_knowledge content}
		@@ -248,9 +248,10 @@ ```
		\|-------\|-------------------\|---------\|
		\| `knowz-scout` \| Read all configured vaults \| Find past decisions, conventions, patterns \|
		\| `knowz-scribe` \| Read and write to matching vaults \| Route and capture learnings \|
		\| `analyst` \| Read via knowz-scout \| Past decisions + affected code patterns \|
		\| `architect` \| Read via knowz-scout \| Conventions + implementation examples \|
		\| `builder` \| Read via knowz-scout \| Best practices + similar patterns \|
		\| `reviewer` \| Read via knowz-scout \| Standards + precedent checks \|
		\| `closer` \| Triggers knowz-scribe captures \| Finalization learnings \|
		\| `knowledge-liaison` \| Routes captures and queries to knowz agents \| Single point of vault I/O coordination across all phases \|
		\| `knowz:reader` \| Read all configured vaults \| Find past decisions, conventions, patterns (dispatched by knowledge-liaison) \|
		\| `knowz:writer` \| Write to matching vaults \| Route and capture learnings (dispatched by knowledge-liaison) \|
		\| `analyst` \| Read via knowz:reader \| Past decisions + affected code patterns \|
		\| `architect` \| Read via knowz:reader \| Conventions + implementation examples \|
		\| `builder` \| Read via knowz:reader \| Best practices + similar patterns \|
		\| `reviewer` \| Read via knowz:reader \| Standards + precedent checks \|
		\| `closer` \| DMs knowledge-liaison for Phase 3 capture \| Finalization learnings \|

		@@ -263,5 +264,5 @@ Fallback behavior: If vault routing cannot determine the best vault, agents use the first `ecosystem`-type vault or prompt the user.

		- `/kc:register` - Create account and auto-configure first vault
		- `/kc:connect-mcp --configure-vaults` - Interactive vault setup
		- `/kc:status` - Check vault connection status
		- `/kc:learn "insight"` - Manually create learning (routes via knowz-scribe if available, direct write otherwise)
		- `/knowz register` - Create account and auto-configure first vault
		- `/knowz setup` - Interactive vault setup
		- `/knowzcode:status` - Check vault connection status
		- `/knowz save "insight"` - Manually create learning (routes via knowz:writer if available, direct write otherwise)

		@@ -5,3 +5,3 @@ # KnowzCode: [LOOP 1A] Propose Change Set

		> Automation Path: Run `/kc-step phase=1A` to engage the `analyst` subagent with the `load-core-context`, `tracker-scan`, and `generate-workgroup-id` skills preloaded. Review the summary in `knowzcode/automation_manifest.md` if you need a refresher on available helpers.
		> Automation Path: Run `/knowzcode-step phase=1A` to engage the `analyst` subagent with the `load-core-context`, `tracker-scan`, and `generate-workgroup-id` skills preloaded. Review the summary in `knowzcode/automation_manifest.md` if you need a refresher on available helpers.

		@@ -8,0 +8,0 @@ Remember:

knowzcode - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics