knowzcode 0.3.7 → 0.5.2

package/knowzcode/platform_adapters.md

@@ -91,7 +91,7 @@ Any agent can send ad-hoc knowledge to the scribe at any time. The scribe handle
 
 ## OpenAI Codex (AGENTS.md)
 
-Create `AGENTS.md` in project root. Notes: `AGENTS.override.md` can be used for user-local overrides. 32KB file size limit. Plain text format (no YAML frontmatter). Codex (2026) also supports `SKILL.md` files for discoverable skills — these appear as available commands in the Codex UI. `AGENTS.md` remains the primary instruction mechanism for KnowzCode methodology.
+Create `AGENTS.md` in project root. Notes: `AGENTS.override.md` can be used for user-local overrides. 32KB file size limit. Plain text format (no YAML frontmatter). Codex (2026) also supports `SKILL.md` files for discoverable skills — each skill is a directory containing `SKILL.md` with YAML frontmatter (`name` and `description`). Skills go in `.agents/skills/` (repo-level) or `~/.agents/skills/` (user-level). `AGENTS.md` remains the primary instruction mechanism for KnowzCode methodology.
 
 ```markdown
 # KnowzCode Development Methodology
@@ -176,112 +176,1627 @@ For single-file, <50 line, no-ripple-effect changes:
 - `knowzcode/workgroups/` — Active session data (gitignored)
 ```
 
+### Codex Skill Files (`.agents/skills/`)
+
+Codex (2026) supports `SKILL.md` files for discoverable skills. Each skill is a directory containing `SKILL.md` with YAML frontmatter (`name` and `description`). Place in `.agents/skills/` (repo-level) or `~/.agents/skills/` (user-level). The `description` field drives implicit invocation — Codex auto-triggers skills based on task matching.
+
+#### .agents/skills/kc-work/SKILL.md
+
+```markdown
+---
+name: kc-work
+description: Start a structured KnowzCode development workflow with TDD, quality gates, and phased implementation. Triggers on feature requests, new functionality, or complex multi-file changes.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:work — Start KnowzCode Workflow
+
+Start a structured KnowzCode development workflow for the given goal.
+
+## Instructions
+
+Read these files for methodology and project context:
+- `knowzcode/knowzcode_loop.md` — Complete methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+
+### Step 1: Classify Tier
+- **Micro** (single file, <50 lines): Use `/kc:fix` instead
+- **Light** (≤3 files): Streamlined 2-phase path
+- **Full** (>3 files or complex): Complete 5-phase workflow
+
+### Step 2: Create WorkGroup
+Generate WorkGroupID: `kc-{type}-{slug}-YYYYMMDD-HHMMSS`
+Create `knowzcode/workgroups/{WorkGroupID}.md`
+
+### Step 3: Phase 1A — Impact Analysis
+1. Identify affected components
+2. Create NodeIDs for new capabilities (PascalCase)
+3. Check `knowzcode/specs/` for existing domain overlap
+4. Propose Change Set with NodeIDs, affected files, risk assessment
+
+**STOP** — Present Change Set for user approval before continuing.
+
+After approval, continue through Phase 1B (Specification) → Phase 2A (TDD Implementation) → Phase 2B (Audit) → Phase 3 (Finalization), stopping at each quality gate.
+```
+
+#### .agents/skills/kc-plan/SKILL.md
+
+```markdown
+---
+name: kc-plan
+description: Research and investigate a topic in the codebase before implementing changes. Triggers on exploratory questions, architecture review, or pre-implementation research.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:plan — Research Before Implementing
+
+Investigate a topic in the codebase before implementing changes.
+
+## Instructions
+
+Read these files for context:
+- `knowzcode/knowzcode_loop.md` — Methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+
+1. Explore the codebase for relevant files, patterns, and implementations
+2. Check `knowzcode/specs/` for related component specs
+3. Scan `knowzcode/workgroups/` for past WorkGroups in similar areas
+4. Review `knowzcode/knowzcode_architecture.md` for structural context
+5. Present findings with current state, patterns, options, and recommended approach
+
+**STOP** — Present research findings. To implement, use `/kc:work` with the chosen approach.
+```
+
+#### .agents/skills/kc-fix/SKILL.md
+
+```markdown
+---
+name: kc-fix
+description: Quick targeted fix for single-file changes using the micro-fix protocol. Triggers on bug fixes, typos, small corrections, and CSS tweaks.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:fix — Quick Targeted Fix
+
+Apply a targeted fix using the micro-fix protocol.
+
+## Scope Guard
+
+This workflow is for changes that are:
+- Single file (or minimal multi-file with no ripple effects)
+- <50 lines changed
+- No architectural impact
+
+If the fix exceeds this scope, suggest `/kc:work` instead.
+
+## Instructions
+
+Read `knowzcode/knowzcode_loop.md` section on Micro-Fix.
+
+1. Implement the fix
+2. Run targeted tests for the affected code
+3. Prepend a MicroFix entry to `knowzcode/knowzcode_log.md`
+4. Commit with `fix: {description}` message
+```
+
+#### .agents/skills/kc-audit/SKILL.md
+
+```markdown
+---
+name: kc-audit
+description: Read-only quality audit comparing implementation against specs. Triggers on audit requests, quality checks, security reviews, and compliance verification.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:audit — Quality Audit
+
+Perform a READ-ONLY audit comparing implementation against specs.
+
+## Instructions
+
+Read these files:
+- `knowzcode/knowzcode_loop.md` — Phase 2B methodology
+- `knowzcode/knowzcode_tracker.md` — Find active WorkGroups
+
+**CRITICAL: This is a READ-ONLY audit. Do NOT modify source files.**
+
+1. Compare implementation against all VERIFY statements in specs from `knowzcode/specs/`
+2. Calculate completion percentage per NodeID and overall
+3. Identify gaps: missing features, incomplete criteria, untested paths
+4. Check for security concerns
+5. Assess risk for any gaps found
+
+### Standalone Audit Types
+- **spec**: Audit spec quality and VERIFY statement coverage
+- **architecture**: Compare architecture doc against codebase
+- **security**: OWASP top 10, input validation, auth flows
+- **integration**: API contracts, dependency health
+
+**STOP** — Present audit results with completion percentage and gap list.
+```
+
+#### .agents/skills/kc-learn/SKILL.md
+
+```markdown
+---
+name: kc-learn
+description: Capture learnings, decisions, patterns, and conventions to the KnowzCode knowledge vault. Triggers on knowledge capture, documentation of decisions, or pattern recording.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:learn — Capture Learning
+
+Capture a learning, decision, or pattern to the KnowzCode knowledge vault.
+
+## Instructions
+
+Read `knowzcode/knowzcode_vaults.md` for vault configuration and routing rules.
+
+1. Analyze the learning provided
+2. Categorize: Pattern, Workaround, Decision, Convention, Security, Integration, Performance, Completion
+3. Route to the appropriate vault:
+   - Pattern/Workaround/Performance → `code` vault
+   - Decision/Convention/Security/Integration → `ecosystem` vault
+   - Completion → `finalizations` vault
+4. If MCP is connected: call `create_knowledge` with appropriate `vaultId`
+5. If MCP is unavailable: append to `knowzcode/pending_captures.md`
+
+Write detailed, self-contained entries — vault entries are retrieved via semantic search.
+```
+
+#### .agents/skills/kc-continue/SKILL.md
+
+```markdown
+---
+name: kc-continue
+description: Resume an interrupted KnowzCode workflow or advance to the next phase. Triggers on continuation requests, workflow resumption, or phase advancement.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:continue — Resume Workflow
+
+Resume an interrupted KnowzCode workflow or advance to the next phase.
+
+## Instructions
+
+Read `knowzcode/knowzcode_tracker.md` to find active `[WIP]` WorkGroups.
+
+### Step 1: Find Active WorkGroup
+- One active: use it
+- Multiple active: ask user which to resume
+- None active: suggest `/kc:work`
+
+### Step 2: Determine Current Phase
+Read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
+Check the Phase History table to determine current state.
+
+### Step 3: Resume
+
+| State | Action |
+|-------|--------|
+| 1A in progress | Complete impact analysis |
+| 1A approved, specs not started | Begin Phase 1B |
+| 1B approved, not implemented | Begin Phase 2A |
+| 2A complete | Run Phase 2B audit |
+| 2B complete, gaps found | Present fix/accept options |
+| 2B complete, no gaps | Begin Phase 3 |
+
+Resume from the appropriate phase following `knowzcode/knowzcode_loop.md`.
+```
+
+#### .agents/skills/kc-init/SKILL.md
+
+```markdown
+---
+name: kc-init
+description: Initialize KnowzCode in a project. Triggers on project setup, framework initialization, or first-time configuration.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:init — Initialize KnowzCode
+
+Set up the KnowzCode framework in the current project.
+
+## Instructions
+
+1. Check for existing `knowzcode/` directory
+   - If exists: ask user to Abort, Merge, or Overwrite
+2. Create directory structure: `knowzcode/`, `knowzcode/specs/`, `knowzcode/workgroups/`, `knowzcode/prompts/`
+3. Generate template files from the KnowzCode framework source
+4. Detect project stack (language, frameworks, test runners, build tools)
+5. Select platform adapter(s): Claude Code, Codex, Gemini, Cursor, Copilot, Windsurf
+6. Generate platform instruction file(s) with detected stack context
+7. Report generated files and suggest next steps (`/kc:work`, `/kc:register`)
+```
+
+#### .agents/skills/kc-status/SKILL.md
+
+```markdown
+---
+name: kc-status
+description: Check KnowzCode MCP connection, vault health, and agent status. Triggers on status checks, diagnostics, or troubleshooting.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:status — Check Status
+
+Check KnowzCode MCP connection, vault health, and agent status.
+
+## Instructions
+
+1. Check for agent definition files (glob `agents/*.md`)
+2. Read `knowzcode/knowzcode_vaults.md` for vault configuration
+2.5. **Cross-Platform Config Discovery**:
+   - Check `KNOWZ_API_KEY` env var: Set (ending ...{last4}) | Not set
+   - Check `knowzcode/mcp_config.md`: Connected / Not configured
+   - Check `.gemini/settings.json` for `mcpServers.knowz`: Configured | Not found
+   - Check `.vscode/mcp.json` for `servers.knowz`: Configured | Not found
+   - Include all sources in status output
+   - If current platform not configured but another is: "Tip: An API key was found in {source}. Run /kc:connect-mcp to configure for this platform."
+3. Test MCP connectivity by calling `list_vaults`
+4. Check each configured vault's health and item count
+5. Read `knowzcode/knowzcode_tracker.md` for active WorkGroups
+
+Report connection status, vault health, agent availability, and active WorkGroups.
+```
+
+#### .agents/skills/kc-connect-mcp/SKILL.md
+
+```markdown
+---
+name: kc-connect-mcp
+description: Configure KnowzCode MCP server for vector search and vault access. Triggers on MCP configuration, API key setup, or vault connection.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:connect-mcp — Configure MCP Server
+
+Configure the KnowzCode MCP server for vector-based code search and context retrieval.
+
+## Instructions
+
+Requires an API key. If the user doesn't have one, suggest `/kc:register` first.
+
+**Default endpoint:** `https://mcp.knowz.io/mcp`
+**Dev endpoint:** `https://mcp.dev.knowz.io/mcp`
+
+1. Accept API key and optional parameters (endpoint, dev mode)
+1.5. **Smart Config Discovery (if no API key provided)**:
+   - Check `KNOWZ_API_KEY` environment variable — if set, use as API key
+   - Check `knowzcode/mcp_config.md` — if `Connected: Yes`, pre-populate endpoint
+   - Check `knowzcode/knowzcode_vaults.md` — if vaults configured, skip vault prompts
+   - Check cross-platform configs (`.gemini/settings.json`, `.vscode/mcp.json`) for existing Bearer token
+   - If key found: "Found existing API key (ending ...{last4}) in {source}. Use this key? [Yes/No]"
+2. Validate the API key against the KnowzCode API
+3. Write MCP server configuration:
+   - Add server `knowz` with HTTP transport to endpoint URL
+   - Set `Authorization: Bearer <api-key>` header
+   - Set `X-Project-Path` header to current project path
+   - Write to the platform's MCP config file (e.g., `.mcp.json` for project-level)
+4. Test connectivity by calling `list_vaults`
+5. Configure vault mappings — check `knowzcode/knowzcode_vaults.md` first; if vaults already configured from another platform, skip vault prompts
+6. Update `knowzcode/mcp_config.md` with connection status and `API Key (last 4)`
+
+Report connection status and available vaults.
+```
+
+#### .agents/skills/kc-register/SKILL.md
+
+```markdown
+---
+name: kc-register
+description: Register for KnowzCode and auto-configure MCP server. Triggers on account creation, registration, or first-time setup.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:register — Register & Configure
+
+Register for KnowzCode and automatically configure the MCP server.
+
+## Instructions
+
+**Registration API:** `https://api.knowz.io/api/v1/auth/register`
+**Dev API:** `https://api.dev.knowz.io/api/v1/auth/register`
+
+0. **Smart Discovery**: Check `KNOWZ_API_KEY`, `knowzcode/mcp_config.md`, and cross-platform configs (`.gemini/settings.json`, `.vscode/mcp.json`) for existing API key. If found, offer: "Use existing key via /kc:connect-mcp" or "Register new account"
+1. Prompt user for name, email, and password (one at a time)
+2. Call the KnowzCode registration API via HTTP POST
+3. Extract API key and vault ID from response
+4. Configure MCP server connection:
+   - Add server `knowz` with HTTP transport to `https://mcp.knowz.io/mcp`
+   - Set `Authorization: Bearer <api-key>` header
+   - Set `X-Project-Path` header to current project path
+   - Write to the platform's MCP config file (e.g., `.mcp.json` for project-level)
+5. Update `knowzcode/knowzcode_vaults.md` with returned vault IDs — check first if vaults already configured from another platform
+6. Update `knowzcode/mcp_config.md` with connection status and `API Key (last 4)`
+
+The user will be ready to use MCP-powered features after registration.
+```
+
+#### .agents/skills/kc-telemetry/SKILL.md
+
+```markdown
+---
+name: kc-telemetry
+description: Investigate production telemetry from Sentry and App Insights. Triggers on error investigation, production debugging, or telemetry queries.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:telemetry — Investigate Telemetry
+
+Investigate production telemetry to diagnose errors, trace issues, and identify root causes.
+
+## Instructions
+
+Usage: `/kc:telemetry "<natural language description>"`
+
+1. Parse the natural language query for environment, timeframe, and error context
+2. Read `knowzcode/knowzcode_telemetry.md` for configured sources
+3. Query configured telemetry sources (Sentry, App Insights) via MCP tools
+4. Correlate findings across sources
+5. Present timeline, root cause analysis, and recommended fixes
+
+If no telemetry sources are configured, suggest `/kc:telemetry-setup`.
+```
+
+#### .agents/skills/kc-telemetry-setup/SKILL.md
+
+```markdown
+---
+name: kc-telemetry-setup
+description: Configure telemetry sources (Sentry, App Insights) for /kc:telemetry. Triggers on telemetry configuration or source setup.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:telemetry-setup — Configure Telemetry Sources
+
+Configure telemetry sources for `/kc:telemetry` investigations.
+
+## Instructions
+
+Usage: `/kc:telemetry-setup [sentry|appinsights|all]`
+
+1. Detect available telemetry MCP tools (Sentry, App Insights)
+2. For each selected source:
+   - Verify MCP tool connectivity
+   - Test authentication and permissions
+   - Detect available projects/resources
+3. Write configuration to `knowzcode/knowzcode_telemetry.md`
+4. Run a test query to verify end-to-end connectivity
+
+Report configured sources and their status.
+```
+
+---
+
+## Google Gemini CLI (GEMINI.md)
+
+Create `GEMINI.md` in project root. Notes: Gemini CLI supports `@file.md` imports for pulling in methodology files (e.g., `@knowzcode/knowzcode_loop.md`). User-global preferences can be placed in `~/.gemini/GEMINI.md`.
+
+### Native Commands (`.gemini/commands/kc/*.toml`)
+
+Gemini CLI (2026) supports native custom commands via TOML files in `.gemini/commands/`. Subdirectory namespacing gives the `/kc:` prefix automatically:
+
+```toml
+# .gemini/commands/kc/work.toml
+description = "Start a new KnowzCode development workflow"
+prompt = """Read .gemini/skills/kc-work/SKILL.md for full instructions.
+Start a structured KnowzCode development workflow for: <ARGS/>
+Classify tier (Micro/Light/Full), create WorkGroup, run Phase 1A Impact Analysis.
+Read knowzcode/knowzcode_loop.md for methodology, knowzcode/knowzcode_project.md for context.
+STOP at each quality gate for user approval."""
+```
+
+```toml
+# .gemini/commands/kc/plan.toml
+description = "Research before implementing"
+prompt = """Read .gemini/skills/kc-plan/SKILL.md for full instructions.
+Investigate the codebase for: <ARGS/>
+Explore files, check specs, review architecture, scan workgroup history.
+Present findings with current state, patterns, options, and recommended approach.
+Say 'implement' to transition to /kc:work."""
+```
+
+```toml
+# .gemini/commands/kc/fix.toml
+description = "Quick targeted fix (micro-fix workflow)"
+prompt = """Read .gemini/skills/kc-fix/SKILL.md for full instructions.
+Apply a targeted fix for: <ARGS/>
+Scope guard: single file, <50 lines, no architectural impact. If larger, suggest /kc:work.
+Run tests, log a MicroFix entry in knowzcode/knowzcode_log.md, commit with fix: prefix."""
+```
+
+```toml
+# .gemini/commands/kc/audit.toml
+description = "Run quality audit against specs"
+prompt = """Read .gemini/skills/kc-audit/SKILL.md for full instructions.
+Perform a READ-ONLY audit for: <ARGS/>
+Audit types: spec (VERIFY coverage), architecture (doc vs code), security (OWASP), integration (API contracts).
+Compare implementation against specs in knowzcode/specs/. Do NOT modify source files.
+Report completion percentage, gaps, and security concerns."""
+```
+
+```toml
+# .gemini/commands/kc/learn.toml
+description = "Capture a learning to KnowzCode vault"
+prompt = """Read .gemini/skills/kc-learn/SKILL.md for full instructions.
+Capture the following learning: <ARGS/>
+Route to the appropriate vault per knowzcode/knowzcode_vaults.md routing table.
+Vault types: code (patterns/workarounds), ecosystem (decisions/conventions), finalizations (completions).
+If MCP is unavailable, save to knowzcode/pending_captures.md."""
+```
+
+```toml
+# .gemini/commands/kc/status.toml
+description = "Check KnowzCode MCP connection and vault status"
+prompt = """Read .gemini/skills/kc-status/SKILL.md for full instructions.
+Check MCP connection: read .gemini/settings.json for mcpServers.knowz entry, run gemini mcp list.
+Report vault config from knowzcode/knowzcode_vaults.md, test connectivity via list_vaults.
+Show active WorkGroups from knowzcode/knowzcode_tracker.md."""
+```
+
+```toml
+# .gemini/commands/kc/continue.toml
+description = "Resume interrupted KnowzCode workflow"
+prompt = """Read .gemini/skills/kc-continue/SKILL.md for full instructions.
+Read knowzcode/knowzcode_tracker.md to find active [WIP] WorkGroups.
+Read the most recent WorkGroup file from knowzcode/workgroups/.
+Determine the current phase from the Phase History table.
+Resume from where the workflow left off, following knowzcode/knowzcode_loop.md."""
+```
+
+```toml
+# .gemini/commands/kc/init.toml
+description = "Initialize KnowzCode in this project"
+prompt = """Read .gemini/skills/kc-init/SKILL.md for full instructions.
+Set up the KnowzCode framework in the current project.
+Check for existing knowzcode/ directory. If present, ask: Abort, Merge, or Overwrite.
+Create knowzcode/ with template files. Detect project stack.
+Generate platform adapter(s) as needed. Offer MCP configuration.
+Report generated files and suggest /kc:work as next step.
+<ARGS/>"""
+```
+
+```toml
+# .gemini/commands/kc/connect-mcp.toml
+description = "Configure KnowzCode MCP server connection for Gemini CLI"
+prompt = """Read .gemini/skills/kc-connect-mcp/SKILL.md for full instructions.
+Configure the KnowzCode MCP server for Gemini CLI.
+Check KNOWZ_API_KEY env var and knowzcode/mcp_config.md before prompting for API key.
+Primary method: gemini mcp add --transport sse -s <scope> -H "Authorization: Bearer <key>" -H "X-Project-Path: $(pwd)" knowz https://mcp.knowz.io/mcp
+Fallback: write .gemini/settings.json with mcpServers.knowz entry (url + headers).
+Scopes: project (default), user. Verify: gemini mcp list. Remove: gemini mcp remove knowz.
+If user has no API key, suggest /kc:register.
+<ARGS/>"""
+```
+
+```toml
+# .gemini/commands/kc/register.toml
+description = "Register for KnowzCode and configure MCP for Gemini CLI"
+prompt = """Read .gemini/skills/kc-register/SKILL.md for full instructions.
+Register for KnowzCode and auto-configure MCP for Gemini CLI.
+Check for existing API key in KNOWZ_API_KEY, mcp_config.md, or other platform configs before registration.
+Registration API: https://api.knowz.io/api/v1/auth/register
+Prompt for name, email, password. Call API. Extract API key and vault ID.
+Configure MCP via: gemini mcp add --transport sse -H "Authorization: Bearer <key>" -H "X-Project-Path: $(pwd)" knowz https://mcp.knowz.io/mcp
+Fallback: write .gemini/settings.json with mcpServers.knowz entry.
+Update knowzcode/knowzcode_vaults.md with vault IDs.
+<ARGS/>"""
+```
+
+```toml
+# .gemini/commands/kc/telemetry.toml
+description = "Investigate production telemetry"
+prompt = """Read .gemini/skills/kc-telemetry/SKILL.md for full instructions.
+Investigate production telemetry to diagnose errors and trace issues.
+Parse query for environment, timeframe, error context: <ARGS/>
+Read knowzcode/knowzcode_telemetry.md for configured sources.
+Query Sentry/App Insights via MCP tools. Correlate findings across sources.
+Present timeline, root cause analysis, and recommended fixes.
+If no sources configured, suggest /kc:telemetry-setup."""
+```
+
+```toml
+# .gemini/commands/kc/telemetry-setup.toml
+description = "Configure telemetry sources for /kc:telemetry"
+prompt = """Read .gemini/skills/kc-telemetry-setup/SKILL.md for full instructions.
+Configure telemetry sources for /kc:telemetry investigations.
+Detect available telemetry MCP tools (Sentry, App Insights).
+For each source: verify connectivity, test auth, detect projects.
+Write config to knowzcode/knowzcode_telemetry.md.
+Run a test query to verify end-to-end connectivity.
+<ARGS/>"""
+```
+
+Gemini also supports extensions (`gemini-extension.json`) for tool integration and `@file.md` imports for including methodology files directly in prompts.
+
+```markdown
+# KnowzCode Development Methodology
+
+This project uses KnowzCode for structured TDD development.
+
+## Required Reading
+Read these files before starting any feature work (use @import syntax for direct inclusion):
+- `knowzcode/knowzcode_loop.md` — Complete workflow methodology
+- `knowzcode/knowzcode_project.md` — Project context and tech stack
+- `knowzcode/knowzcode_architecture.md` — Architecture documentation
+- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
+
+## Phase Walkthrough
+
+### Phase 1A: Impact Analysis
+- Identify components affected by the goal
+- Create NodeIDs for new capabilities (PascalCase domain concepts)
+- Check existing specs for domain overlap before creating new ones
+- Present Change Set for user approval — STOP until approved
+
+### Phase 1B: Specification
+- Draft specs using 4-section format (Rules, Interfaces, Verification Criteria, Debt)
+- Each spec needs 2+ VERIFY statements
+- Present for approval — STOP until approved
+- Commit specs as a pre-implementation checkpoint
+
+### Phase 2A: Implementation (TDD Required)
+- Follow Red-Green-Refactor for every feature
+- Write failing test FIRST, then minimal code to pass, then refactor
+- Run full test suite + linter + build when all features done
+- STOP and report results
+
+### Phase 2B: Completeness Audit
+- READ-ONLY comparison of implementation vs specs
+- Calculate completion percentage
+- Report gaps and security concerns
+- STOP for user decision
+
+### Phase 3: Finalization
+- Update specs to As-Built, update tracker, write log entry
+- Check architecture doc for drift
+- Final commit
+
+## Rules
+- Follow quality gates strictly — STOP at each gate for user approval
+- TDD is mandatory for all feature work
+- Propose Change Sets before implementing
+- Update specs and tracker after implementation
+- Log completions in `knowzcode/knowzcode_log.md`
+- Target <20 specs — consolidate when domains overlap >50%
+
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+## MCP Server Configuration (Gemini CLI)
+MCP servers are configured in `.gemini/settings.json` (project) or `~/.gemini/settings.json` (user).
+To connect: `/kc:connect-mcp <api-key>` or `/kc:register`.
+To verify: `gemini mcp list` or `/mcp` in session.
+Manual config: add a `mcpServers.knowz` entry with `url` and `headers` — see `/kc:connect-mcp` skill for format.
+
+## Micro-Fix (for small changes)
+Single file, <50 lines, no ripple effects:
+1. Implement fix → 2. Run tests → 3. Log MicroFix → 4. Commit with `fix:`
+```
+
+### Gemini Skill Files (`.gemini/skills/`)
+
+Gemini CLI (2026) supports `SKILL.md` files for discoverable skills, identical to the Codex format. Each skill is a directory containing `SKILL.md` with YAML frontmatter (`name` and `description`). Place in `.gemini/skills/` (repo-level) or `~/.gemini/skills/` (user-level). The `description` field drives implicit invocation — Gemini auto-triggers skills based on task matching. Note: `.agents/skills/` also works as an alias path.
+
+#### .gemini/skills/kc-work/SKILL.md
+
+```markdown
+---
+name: kc-work
+description: Start a structured KnowzCode development workflow with TDD, quality gates, and phased implementation. Triggers on feature requests, new functionality, or complex multi-file changes.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:work — Start KnowzCode Workflow
+
+Start a structured KnowzCode development workflow for the given goal.
+
+## Instructions
+
+Read these files for methodology and project context:
+- `knowzcode/knowzcode_loop.md` — Complete methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+
+### Step 1: Classify Tier
+- **Micro** (single file, <50 lines): Use `/kc:fix` instead
+- **Light** (≤3 files): Streamlined 2-phase path
+- **Full** (>3 files or complex): Complete 5-phase workflow
+
+### Step 2: Create WorkGroup
+Generate WorkGroupID: `kc-{type}-{slug}-YYYYMMDD-HHMMSS`
+Create `knowzcode/workgroups/{WorkGroupID}.md`
+
+### Step 3: Phase 1A — Impact Analysis
+1. Identify affected components
+2. Create NodeIDs for new capabilities (PascalCase)
+3. Check `knowzcode/specs/` for existing domain overlap
+4. Propose Change Set with NodeIDs, affected files, risk assessment
+
+**STOP** — Present Change Set for user approval before continuing.
+
+After approval, continue through Phase 1B (Specification) → Phase 2A (TDD Implementation) → Phase 2B (Audit) → Phase 3 (Finalization), stopping at each quality gate.
+```
+
+#### .gemini/skills/kc-plan/SKILL.md
+
+```markdown
+---
+name: kc-plan
+description: Research and investigate a topic in the codebase before implementing changes. Triggers on exploratory questions, architecture review, or pre-implementation research.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:plan — Research Before Implementing
+
+Investigate a topic in the codebase before implementing changes.
+
+## Instructions
+
+Read these files for context:
+- `knowzcode/knowzcode_loop.md` — Methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+
+1. Explore the codebase for relevant files, patterns, and implementations
+2. Check `knowzcode/specs/` for related component specs
+3. Scan `knowzcode/workgroups/` for past WorkGroups in similar areas
+4. Review `knowzcode/knowzcode_architecture.md` for structural context
+5. Present findings with current state, patterns, options, and recommended approach
+
+**STOP** — Present research findings. To implement, use `/kc:work` with the chosen approach.
+```
+
+#### .gemini/skills/kc-fix/SKILL.md
+
+```markdown
+---
+name: kc-fix
+description: Quick targeted fix for single-file changes using the micro-fix protocol. Triggers on bug fixes, typos, small corrections, and CSS tweaks.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:fix — Quick Targeted Fix
+
+Apply a targeted fix using the micro-fix protocol.
+
+## Scope Guard
+
+This workflow is for changes that are:
+- Single file (or minimal multi-file with no ripple effects)
+- <50 lines changed
+- No architectural impact
+
+If the fix exceeds this scope, suggest `/kc:work` instead.
+
+## Instructions
+
+Read `knowzcode/knowzcode_loop.md` section on Micro-Fix.
+
+1. Implement the fix
+2. Run targeted tests for the affected code
+3. Prepend a MicroFix entry to `knowzcode/knowzcode_log.md`
+4. Commit with `fix: {description}` message
+```
+
+#### .gemini/skills/kc-audit/SKILL.md
+
+```markdown
+---
+name: kc-audit
+description: Read-only quality audit comparing implementation against specs. Triggers on audit requests, quality checks, security reviews, and compliance verification.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:audit — Quality Audit
+
+Perform a READ-ONLY audit comparing implementation against specs.
+
+## Instructions
+
+Read these files:
+- `knowzcode/knowzcode_loop.md` — Phase 2B methodology
+- `knowzcode/knowzcode_tracker.md` — Find active WorkGroups
+
+**CRITICAL: This is a READ-ONLY audit. Do NOT modify source files.**
+
+1. Compare implementation against all VERIFY statements in specs from `knowzcode/specs/`
+2. Calculate completion percentage per NodeID and overall
+3. Identify gaps: missing features, incomplete criteria, untested paths
+4. Check for security concerns
+5. Assess risk for any gaps found
+
+### Standalone Audit Types
+- **spec**: Audit spec quality and VERIFY statement coverage
+- **architecture**: Compare architecture doc against codebase
+- **security**: OWASP top 10, input validation, auth flows
+- **integration**: API contracts, dependency health
+
+**STOP** — Present audit results with completion percentage and gap list.
+```
+
+#### .gemini/skills/kc-learn/SKILL.md
+
+```markdown
+---
+name: kc-learn
+description: Capture learnings, decisions, patterns, and conventions to the KnowzCode knowledge vault. Triggers on knowledge capture, documentation of decisions, or pattern recording.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:learn — Capture Learning
+
+Capture a learning, decision, or pattern to the KnowzCode knowledge vault.
+
+## Instructions
+
+Read `knowzcode/knowzcode_vaults.md` for vault configuration and routing rules.
+
+1. Analyze the learning provided
+2. Categorize: Pattern, Workaround, Decision, Convention, Security, Integration, Performance, Completion
+3. Route to the appropriate vault:
+   - Pattern/Workaround/Performance → `code` vault
+   - Decision/Convention/Security/Integration → `ecosystem` vault
+   - Completion → `finalizations` vault
+4. If MCP is connected: call `create_knowledge` with appropriate `vaultId`
+5. If MCP is unavailable: append to `knowzcode/pending_captures.md`
+
+Write detailed, self-contained entries — vault entries are retrieved via semantic search.
+```
+
+#### .gemini/skills/kc-continue/SKILL.md
+
+```markdown
+---
+name: kc-continue
+description: Resume an interrupted KnowzCode workflow or advance to the next phase. Triggers on continuation requests, workflow resumption, or phase advancement.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:continue — Resume Workflow
+
+Resume an interrupted KnowzCode workflow or advance to the next phase.
+
+## Instructions
+
+Read `knowzcode/knowzcode_tracker.md` to find active `[WIP]` WorkGroups.
+
+### Step 1: Find Active WorkGroup
+- One active: use it
+- Multiple active: ask user which to resume
+- None active: suggest `/kc:work`
+
+### Step 2: Determine Current Phase
+Read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
+Check the Phase History table to determine current state.
+
+### Step 3: Resume
+
+| State | Action |
+|-------|--------|
+| 1A in progress | Complete impact analysis |
+| 1A approved, specs not started | Begin Phase 1B |
+| 1B approved, not implemented | Begin Phase 2A |
+| 2A complete | Run Phase 2B audit |
+| 2B complete, gaps found | Present fix/accept options |
+| 2B complete, no gaps | Begin Phase 3 |
+
+Resume from the appropriate phase following `knowzcode/knowzcode_loop.md`.
+```
+
+#### .gemini/skills/kc-init/SKILL.md
+
+```markdown
+---
+name: kc-init
+description: Initialize KnowzCode in a project. Triggers on project setup, framework initialization, or first-time configuration.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:init — Initialize KnowzCode
+
+Set up the KnowzCode framework in the current project.
+
+## Instructions
+
+1. Check for existing `knowzcode/` directory
+   - If exists: ask user to Abort, Merge, or Overwrite
+2. Create directory structure: `knowzcode/`, `knowzcode/specs/`, `knowzcode/workgroups/`, `knowzcode/prompts/`
+3. Generate template files from the KnowzCode framework source
+4. Detect project stack (language, frameworks, test runners, build tools)
+5. Select platform adapter(s): Claude Code, Codex, Gemini, Cursor, Copilot, Windsurf
+6. Generate platform instruction file(s) with detected stack context
+7. Report generated files and suggest next steps (`/kc:work`, `/kc:register`)
+```
+
+#### .gemini/skills/kc-status/SKILL.md
+
+```markdown
+---
+name: kc-status
+description: Check KnowzCode MCP connection, vault health, and agent status for Gemini CLI. Triggers on status checks, diagnostics, or troubleshooting.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:status — Check Status (Gemini CLI)
+
+Check KnowzCode MCP connection, vault health, and agent status.
+
+## Instructions
+
+1. Check for agent definition files (glob `.gemini/agents/kc-*.md` or `agents/*.md`)
+2. **Check MCP server configuration (Gemini-specific)**:
+   - Read `.gemini/settings.json` (project) for `mcpServers.knowz` entry
+   - If not found, check `~/.gemini/settings.json` (user-level)
+   - Run `gemini mcp list` to verify server status
+   - Use `/mcp` as in-session alternative for verification
+2.5. **Cross-Platform Config Discovery**:
+   - Check `KNOWZ_API_KEY` env var: Set (ending ...{last4}) | Not set
+   - Check `knowzcode/mcp_config.md`: Connected / Not configured
+   - Check `.mcp.json` (Codex) for knowz entry: Configured | Not found
+   - Check `.vscode/mcp.json` (Copilot) for knowz entry: Configured | Not found
+   - Include all sources in status output
+   - If Gemini not configured but another platform is: "Tip: An API key was found in {source}. Run /kc:connect-mcp to configure for Gemini."
+3. Read `knowzcode/knowzcode_vaults.md` for vault configuration
+4. Test MCP connectivity by calling `list_vaults`
+5. Check each configured vault's health and item count
+6. Read `knowzcode/knowzcode_tracker.md` for active WorkGroups
+
+Report connection status, vault health, agent availability, and active WorkGroups.
+If MCP is not configured, suggest `/kc:connect-mcp <api-key>` or `/kc:register`.
+```
+
+#### .gemini/skills/kc-connect-mcp/SKILL.md
+
+```markdown
+---
+name: kc-connect-mcp
+description: Configure KnowzCode MCP server for Gemini CLI. Triggers on MCP configuration, API key setup, or vault connection.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:connect-mcp — Configure MCP Server (Gemini CLI)
+
+Configure the KnowzCode MCP server for vector-based code search and context retrieval.
+
+## Instructions
+
+Requires an API key. If the user doesn't have one, suggest `/kc:register` first.
+
+**Default endpoint:** `https://mcp.knowz.io/mcp`
+**Dev endpoint:** `https://mcp.dev.knowz.io/mcp`
+
+### Step 1: Parse Arguments
+- Accept API key (optional — may be discovered) and optional parameters:
+  - `--dev` → use dev endpoint
+  - `--scope user` → user-level config (`~/.gemini/settings.json`); default is `project` (`.gemini/settings.json`)
+
+### Step 1.5: Smart Config Discovery (if no API key in arguments)
+
+Before prompting for an API key, check known config sources:
+
+1. **Environment variable**: Check `KNOWZ_API_KEY`
+   - If set: use as the API key, display "Using API key from KNOWZ_API_KEY (ending ...{last4})"
+
+2. **Project config**: Read `knowzcode/mcp_config.md`
+   - If `Connected: Yes` and endpoint set: pre-populate endpoint
+   - If `API Key (last 4)` set: note for confirmation
+
+3. **Vault config**: Read `knowzcode/knowzcode_vaults.md`
+   - If vaults have non-empty IDs: skip vault prompts in Step 5 (unless `--configure-vaults`)
+
+4. **Cross-platform config files** (check for API key in other platforms):
+   - `.mcp.json` → knowz entry Authorization header
+   - `.vscode/mcp.json` → `servers.knowz.headers`
+   - If 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 interactive API key prompt.
+
+### Step 2: Check Existing Configuration
+- Run `gemini mcp list` to check if `knowz` server is already configured
+- If found, ask user: **Replace** existing config or **Cancel**
+- To remove existing: `gemini mcp remove knowz`
+
+### Step 3: Configure MCP Server
+**Primary method** — use Gemini CLI:
+```bash
+gemini mcp add --transport sse -s <scope> \
+  -H "Authorization: Bearer <api-key>" \
+  -H "X-Project-Path: $(pwd)" \
+  knowz <endpoint>
+```
+Where `<scope>` is `project` (default) or `user`.
+
+**Fallback** — if `gemini` CLI is not available, write `.gemini/settings.json` directly:
+```json
+{
+  "mcpServers": {
+    "knowz": {
+      "url": "<endpoint>",
+      "headers": {
+        "Authorization": "Bearer <api-key>",
+        "X-Project-Path": "<project-path>"
+      }
+    }
+  }
+}
+```
+If the file exists, read it first and merge — preserve existing settings, only add/update the `mcpServers.knowz` entry.
+
+### Step 4: Verify Configuration
+- Run `gemini mcp list` to confirm `knowz` appears
+- Test connectivity by calling `list_vaults`
+
+### Step 5: Configure Vaults (Conditional)
+- First check `knowzcode/knowzcode_vaults.md` — if vaults already have non-empty IDs from a previous platform setup, skip vault prompts and report "Vaults already configured from previous setup"
+- Otherwise, if `list_vaults` returns vaults, offer to update `knowzcode/knowzcode_vaults.md`
+- If vaults have null IDs, offer to create them via `create_vault`
+
+### Step 5.5: Update GEMINI.md with Vault Targeting Guidance
+Ensure agents know to pass `vaultId` by adding a reference section to the project's GEMINI.md:
+1. Read the project's `GEMINI.md`
+2. Search for an existing `### Vault Targeting` section
+3. If found: replace. If not found: append after Knowledge Capture section
+4. Insert:
+   ```
+   ### Vault Targeting (MCP Writes)
+   **Always pass `vaultId`** when calling `create_knowledge` or `update_knowledge`.
+   Vault IDs and routing rules: `knowzcode/knowzcode_vaults.md`
+   ```
+
+### Step 6: Update Status Files
+- Update `knowzcode/mcp_config.md` with connection status:
+  - Set `Connected: Yes`, endpoint, timestamp
+  - Set `API Key (last 4): <last 4 characters of the API key>`
+
+### Step 7: Report Success
+Report connection status, available vaults, and remind user:
+"Restart your Gemini CLI session to activate MCP tools, or run `/mcp` to verify in-session."
+
+### Error Handling
+- If `gemini` CLI not found → use manual `.gemini/settings.json` fallback with JSON snippet
+- If API key is invalid → report error, suggest checking key at https://knowz.io/api-keys
+- If network error → suggest checking connectivity and firewall
+```
+
+#### .gemini/skills/kc-register/SKILL.md
+
+```markdown
+---
+name: kc-register
+description: Register for KnowzCode and auto-configure MCP server for Gemini CLI. Triggers on account creation, registration, or first-time setup.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:register — Register & Configure (Gemini CLI)
+
+Register for KnowzCode and automatically configure the MCP server.
+
+## Instructions
+
+**Registration API:** `https://api.knowz.io/api/v1/auth/register`
+**Dev API:** `https://api.dev.knowz.io/api/v1/auth/register`
+
+### 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: `.mcp.json`, `.vscode/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 via /kc:connect-mcp  2. Register new account anyway  3. Cancel"
+
+If user chooses option 1: advise running `/kc:connect-mcp`.
+If user chooses option 2: proceed with registration (Step 1).
+
+### Step 1: Collect User Info
+Prompt user for name, email, and password (one at a time).
+
+### Step 2: Register
+Call the KnowzCode registration API via HTTP POST. Extract API key and vault ID from response.
+
+### Step 3: Check Existing MCP Config
+- Run `gemini mcp list` to check if `knowz` is already configured
+- If found, remove with `gemini mcp remove knowz` before reconfiguring
+
+### Step 4: Configure MCP Server
+**Primary method** — use Gemini CLI:
+```bash
+gemini mcp add --transport sse \
+  -H "Authorization: Bearer <api-key>" \
+  -H "X-Project-Path: $(pwd)" \
+  knowz https://mcp.knowz.io/mcp
+```
+
+**Fallback** — if `gemini` CLI not available, write `.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "knowz": {
+      "url": "https://mcp.knowz.io/mcp",
+      "headers": {
+        "Authorization": "Bearer <api-key>",
+        "X-Project-Path": "<project-path>"
+      }
+    }
+  }
+}
+```
+Merge with existing settings if file exists.
+
+### Step 5: Verify
+- Run `gemini mcp list` to confirm `knowz` appears
+- Test connectivity by calling `list_vaults`
+
+### Step 6: Configure Vaults
+- Check `knowzcode/knowzcode_vaults.md` first — if vaults already configured from another platform, reuse them
+- Otherwise, update `knowzcode/knowzcode_vaults.md` with returned vault IDs
+- Update `knowzcode/mcp_config.md` with connection status and `API Key (last 4)`
+
+### Step 7: Report Success
+The user is ready to use MCP-powered features.
+Remind: "Restart your Gemini CLI session or run `/mcp` to verify."
+```
+
+#### .gemini/skills/kc-telemetry/SKILL.md
+
+```markdown
+---
+name: kc-telemetry
+description: Investigate production telemetry from Sentry and App Insights. Triggers on error investigation, production debugging, or telemetry queries.
 ---
+<!-- Generated by KnowzCode vX.Y.Z -->
 
-## Google Gemini CLI (GEMINI.md)
+# /kc:telemetry — Investigate Telemetry
 
-Create `GEMINI.md` in project root. Notes: Gemini CLI supports `@file.md` imports for pulling in methodology files (e.g., `@knowzcode/knowzcode_loop.md`). User-global preferences can be placed in `~/.gemini/GEMINI.md`.
+Investigate production telemetry to diagnose errors, trace issues, and identify root causes.
 
-### Native Commands (`.gemini/commands/kc/*.toml`)
+## Instructions
 
-Gemini CLI (2026) supports native custom commands via TOML files in `.gemini/commands/`. Subdirectory namespacing gives the `/kc:` prefix automatically:
+Usage: `/kc:telemetry "<natural language description>"`
 
-```toml
-# .gemini/commands/kc/work.toml
-description = "Start a new KnowzCode development workflow"
-prompt = """Read knowzcode/knowzcode_loop.md. Follow Phase 1A→3 workflow for:
-<ARGS/>
-Read knowzcode/knowzcode_project.md for project context.
-Read knowzcode/knowzcode_tracker.md for active work."""
+1. Parse the natural language query for environment, timeframe, and error context
+2. Read `knowzcode/knowzcode_telemetry.md` for configured sources
+3. Query configured telemetry sources (Sentry, App Insights) via MCP tools
+4. Correlate findings across sources
+5. Present timeline, root cause analysis, and recommended fixes
+
+If no telemetry sources are configured, suggest `/kc:telemetry-setup`.
 ```
 
-```toml
-# .gemini/commands/kc/plan.toml
-description = "Research before implementing"
-prompt = """Read knowzcode/knowzcode_loop.md and knowzcode/knowzcode_project.md.
-Investigate the codebase for: <ARGS/>
-Present findings with options. Say 'implement' to transition to /kc:work."""
+#### .gemini/skills/kc-telemetry-setup/SKILL.md
+
+```markdown
+---
+name: kc-telemetry-setup
+description: Configure telemetry sources (Sentry, App Insights) for /kc:telemetry. Triggers on telemetry configuration or source setup.
+---
+<!-- Generated by KnowzCode vX.Y.Z -->
+
+# /kc:telemetry-setup — Configure Telemetry Sources
+
+Configure telemetry sources for `/kc:telemetry` investigations.
+
+## Instructions
+
+Usage: `/kc:telemetry-setup [sentry|appinsights|all]`
+
+1. Detect available telemetry MCP tools (Sentry, App Insights)
+2. For each selected source:
+   - Verify MCP tool connectivity
+   - Test authentication and permissions
+   - Detect available projects/resources
+3. Write configuration to `knowzcode/knowzcode_telemetry.md`
+4. Run a test query to verify end-to-end connectivity
+
+Report configured sources and their status.
 ```
 
-```toml
-# .gemini/commands/kc/fix.toml
-description = "Quick targeted fix (micro-fix workflow)"
-prompt = """Read knowzcode/knowzcode_loop.md section on Micro-Fix.
-Apply a targeted fix for: <ARGS/>
-Run tests, log a MicroFix entry, commit with fix: prefix."""
+### Gemini Subagents (`.gemini/agents/`) — Experimental
+
+Gemini CLI supports local subagents via `.gemini/agents/*.md` files with YAML frontmatter. Requires `experimental.enableAgents: true` in Gemini `settings.json`. Each agent definition is a concise, platform-neutral description of the agent's role. Refer to `knowzcode/knowzcode_loop.md` for full methodology details.
+
+#### .gemini/agents/kc-analyst.md
+
+```markdown
+---
+name: kc-analyst
+description: "KnowzCode: Impact analysis and Change Set proposals"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 25
+timeout_mins: 10
+---
+
+# KnowzCode Analyst
+
+You are the **Impact Analyst** for the KnowzCode development workflow.
+
+## Role
+Perform Phase 1A: Impact Analysis. Identify all components affected by a proposed change, create NodeIDs for new capabilities, and propose a Change Set for user approval.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_loop.md` for the complete Phase 1A methodology
+2. Read `knowzcode/knowzcode_project.md` for project context and tech stack
+3. Read `knowzcode/knowzcode_tracker.md` for active work
+4. Scan `knowzcode/specs/` for existing specs that may overlap with the proposed change
+5. Search the codebase for files affected by the change goal
+
+## Output: Change Set Proposal
+- **NodeIDs**: PascalCase domain concepts (not tasks) for each new capability
+- **Affected files**: List of files that will need changes
+- **Risk assessment**: Impact scope, complexity, potential regressions
+- **Dependency map**: Which NodeIDs depend on others
+
+**STOP** after presenting the Change Set — wait for user approval before Phase 1B begins.
 ```
 
-```toml
-# .gemini/commands/kc/audit.toml
-description = "Run quality audit against specs"
-prompt = """Read knowzcode/knowzcode_loop.md Phase 2B.
-Perform a READ-ONLY audit comparing implementation against specs in knowzcode/specs/.
-Report completion percentage, gaps, and security concerns for: <ARGS/>"""
+#### .gemini/agents/kc-architect.md
+
+```markdown
+---
+name: kc-architect
+description: "KnowzCode: Specification drafting, architecture review, and design decisions"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - list_directory
+max_turns: 20
+timeout_mins: 8
+---
+
+# KnowzCode Architect
+
+You are the **Specification Architect** for the KnowzCode development workflow.
+
+## Role
+Perform Phase 1B: Specification. Draft component specs for all NodeIDs in the approved Change Set. Review architecture for consistency.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_loop.md` for the complete Phase 1B methodology
+2. Read the approved Change Set from the active WorkGroup file
+3. For each NodeID, draft a spec using the 4-section format:
+   - **Rules & Decisions**: Constraints, invariants, design choices
+   - **Interfaces**: Public API, data shapes, contracts
+   - **Verification Criteria**: 2+ VERIFY statements per spec
+   - **Debt & Gaps**: Known limitations, future work
+4. Write specs to `knowzcode/specs/{NodeID}.md`
+5. Review `knowzcode/knowzcode_architecture.md` for consistency
+
+**STOP** after presenting specs — wait for user approval before Phase 2A begins. Commit approved specs.
 ```
 
-Gemini also supports extensions (`gemini-extension.json`) for tool integration and `@file.md` imports for including methodology files directly in prompts.
+#### .gemini/agents/kc-builder.md
 
 ```markdown
-# KnowzCode Development Methodology
+---
+name: kc-builder
+description: "KnowzCode: TDD implementation, verification loops, and code quality"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 40
+timeout_mins: 15
+---
 
-This project uses KnowzCode for structured TDD development.
+# KnowzCode Builder
 
-## Required Reading
-Read these files before starting any feature work (use @import syntax for direct inclusion):
-- `knowzcode/knowzcode_loop.md` — Complete workflow methodology
-- `knowzcode/knowzcode_project.md` — Project context and tech stack
-- `knowzcode/knowzcode_architecture.md` — Architecture documentation
-- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
+You are the **TDD Builder** for the KnowzCode development workflow.
 
-## Phase Walkthrough
+## Role
+Perform Phase 2A: Implementation. Implement all NodeIDs using strict TDD (Red-Green-Refactor). Every feature must have a failing test before production code is written.
 
-### Phase 1A: Impact Analysis
-- Identify components affected by the goal
-- Create NodeIDs for new capabilities (PascalCase domain concepts)
-- Check existing specs for domain overlap before creating new ones
-- Present Change Set for user approval — STOP until approved
+## Instructions
 
-### Phase 1B: Specification
-- Draft specs using 4-section format (Rules, Interfaces, Verification Criteria, Debt)
-- Each spec needs 2+ VERIFY statements
-- Present for approval — STOP until approved
-- Commit specs as a pre-implementation checkpoint
+1. Read `knowzcode/knowzcode_loop.md` for the complete Phase 2A methodology
+2. Read approved specs from `knowzcode/specs/` for the assigned NodeIDs
+3. For each NodeID:
+   a. **Red**: Write a failing test that verifies spec VERIFY statements
+   b. **Green**: Write minimal production code to make the test pass
+   c. **Refactor**: Clean up while keeping tests green
+4. Run the full test suite after all NodeIDs are implemented
+5. Run linter and build if configured in `knowzcode/environment_context.md`
+6. Maximum 10 verification iterations before pausing
+
+**STOP** after implementation — report test results, build status, and any issues.
+```
 
-### Phase 2A: Implementation (TDD Required)
-- Follow Red-Green-Refactor for every feature
-- Write failing test FIRST, then minimal code to pass, then refactor
-- Run full test suite + linter + build when all features done
-- STOP and report results
+#### .gemini/agents/kc-reviewer.md
 
-### Phase 2B: Completeness Audit
-- READ-ONLY comparison of implementation vs specs
-- Calculate completion percentage
-- Report gaps and security concerns
-- STOP for user decision
+```markdown
+---
+name: kc-reviewer
+description: "KnowzCode: Quality audit, security review, and compliance verification"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 30
+timeout_mins: 10
+---
 
-### Phase 3: Finalization
-- Update specs to As-Built, update tracker, write log entry
-- Check architecture doc for drift
-- Final commit
+# KnowzCode Reviewer
 
-## Rules
-- Follow quality gates strictly — STOP at each gate for user approval
-- TDD is mandatory for all feature work
-- Propose Change Sets before implementing
-- Update specs and tracker after implementation
-- Log completions in `knowzcode/knowzcode_log.md`
-- Target <20 specs — consolidate when domains overlap >50%
+You are the **Quality Reviewer** for the KnowzCode development workflow.
 
-## Knowledge Capture (CRITICAL — DO NOT SKIP)
-Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
-When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
-When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
-Use `/kc:learn "insight"` for automatic routing.
-Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+## Role
+Perform Phase 2B: Completeness Audit. Conduct a READ-ONLY audit comparing implementation against specs. Do NOT modify source files.
 
-## Micro-Fix (for small changes)
-Single file, <50 lines, no ripple effects:
-1. Implement fix → 2. Run tests → 3. Log MicroFix → 4. Commit with `fix:`
+## Instructions
+
+1. Read `knowzcode/knowzcode_loop.md` for the complete Phase 2B methodology
+2. Read all specs from `knowzcode/specs/` for the active WorkGroup
+3. For each spec, check every VERIFY statement against the implementation
+4. Calculate completion percentage per NodeID and overall
+5. Check for security concerns (OWASP top 10, input validation, auth flows)
+6. Assess integration health (API contracts, dependency compatibility)
+
+## Output: Audit Report
+- **Completion percentage**: Per NodeID and overall
+- **Gaps**: Missing features, incomplete criteria, untested paths
+- **Security concerns**: Vulnerabilities found
+- **Risk assessment**: For each gap
+
+**CRITICAL: This is a READ-ONLY audit. Do NOT modify source files.**
+
+**STOP** after presenting audit results — wait for user decision on gaps.
+```
+
+#### .gemini/agents/kc-closer.md
+
+```markdown
+---
+name: kc-closer
+description: "KnowzCode: Finalization — specs, tracker, log, architecture, learning capture"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - list_directory
+max_turns: 25
+timeout_mins: 10
+---
+
+# KnowzCode Closer
+
+You are the **Finalization Agent** for the KnowzCode development workflow.
+
+## Role
+Perform Phase 3: Finalization. Update all project documentation to reflect the completed work, capture learnings, and create the final commit.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_loop.md` for the complete Phase 3 methodology
+2. Update specs in `knowzcode/specs/` to "As-Built" status
+3. Update `knowzcode/knowzcode_tracker.md` — set WorkGroup status to `[VERIFIED]`
+4. Prepend a log entry to `knowzcode/knowzcode_log.md`
+5. Review `knowzcode/knowzcode_architecture.md` for drift — update if needed
+6. Capture learnings to vaults if MCP is connected (per `knowzcode/knowzcode_vaults.md`)
+7. Create final commit with all documentation updates
+```
+
+#### .gemini/agents/kc-context-scout.md
+
+```markdown
+---
+name: kc-context-scout
+description: "KnowzCode: Local context researcher — specs, workgroups, history"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+max_turns: 15
+timeout_mins: 5
+---
+
+# KnowzCode Context Scout
+
+You are the **Local Context Scout** for the KnowzCode development workflow.
+
+## Role
+Gather local project context at the start of a workflow. Research specs, workgroups, history, and architecture to provide context to other agents.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_tracker.md` for active and recent WorkGroups
+2. Scan `knowzcode/specs/` for existing component specifications
+3. Read recent entries from `knowzcode/knowzcode_log.md`
+4. Review `knowzcode/knowzcode_architecture.md` for structural context
+5. Check `knowzcode/workgroups/` for recent session data
+
+Report findings as a structured context summary that other agents can consume.
+```
+
+#### .gemini/agents/kc-knowz-scout.md
+
+```markdown
+---
+name: kc-knowz-scout
+description: "KnowzCode: MCP vault researcher — business knowledge, conventions, decisions"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+max_turns: 15
+timeout_mins: 5
+---
+
+# KnowzCode Knowz Scout
+
+You are the **MCP Vault Researcher** for the KnowzCode development workflow.
+
+## Role
+Search MCP vaults for relevant business knowledge, conventions, decisions, and patterns that inform the current work.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_vaults.md` for vault configuration
+2. Search vaults for knowledge related to the current goal using `search_knowledge`
+3. Look for: conventions, past decisions, known patterns, workarounds, security policies
+4. Correlate vault findings with local specs and architecture
+
+Report relevant vault knowledge as a structured summary for other agents.
+```
+
+#### .gemini/agents/kc-knowz-scribe.md
+
+```markdown
+---
+name: kc-knowz-scribe
+description: "KnowzCode: MCP vault writer — routes and captures learnings to vaults"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - list_directory
+max_turns: 20
+timeout_mins: 8
+---
+
+# KnowzCode Knowz Scribe
+
+You are the **MCP Vault Writer** for the KnowzCode development workflow.
+
+## Role
+Capture durable knowledge — decisions, patterns, gotchas, workarounds — to MCP vaults throughout the workflow. Route each learning to the appropriate vault.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_vaults.md` for vault IDs and routing rules
+2. For each learning, categorize and route:
+   - Pattern/Workaround/Performance → `code` vault
+   - Decision/Convention/Security/Integration → `ecosystem` vault
+   - Completion → `finalizations` vault
+3. Deduplicate via `search_knowledge` before writing
+4. Write detailed, self-contained entries (vault retrieval is via semantic search)
+5. If MCP is unavailable, queue to `knowzcode/pending_captures.md`
+```
+
+#### .gemini/agents/kc-microfix.md
+
+```markdown
+---
+name: kc-microfix
+description: "KnowzCode: Executes targeted micro-fix tasks with minimal surface area"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - run_shell_command
+max_turns: 15
+timeout_mins: 7
+---
+
+# KnowzCode Microfix Specialist
+
+You are the **Microfix Specialist** for the KnowzCode development workflow.
+
+## Role
+Execute targeted, single-file fixes using the micro-fix protocol. Scope: single file, <50 lines, no ripple effects.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_loop.md` section on Micro-Fix
+2. Implement the fix in the target file
+3. Run targeted tests for the affected code
+4. Prepend a MicroFix entry to `knowzcode/knowzcode_log.md`
+5. If the fix exceeds scope (multi-file, >50 lines, architectural impact), escalate to `/kc:work`
+```
+
+#### .gemini/agents/kc-knowledge-migrator.md
+
+```markdown
+---
+name: kc-knowledge-migrator
+description: "KnowzCode: Migrates external knowledge into specs"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 20
+timeout_mins: 10
+---
+
+# KnowzCode Knowledge Migrator
+
+You are the **Knowledge Migrator** for the KnowzCode development workflow.
+
+## Role
+Migrate external knowledge sources (documentation, wikis, READMEs, code comments) into KnowzCode specs and vault entries.
+
+## Instructions
+
+1. Read the source material provided by the user
+2. Extract structured knowledge: decisions, patterns, interfaces, constraints
+3. Map extracted knowledge to existing specs in `knowzcode/specs/` or create new ones
+4. Route vault-worthy learnings per `knowzcode/knowzcode_vaults.md`
+5. Preserve attribution and source references
+```
+
+#### .gemini/agents/kc-update-coordinator.md
+
+```markdown
+---
+name: kc-update-coordinator
+description: "KnowzCode: Coordinates intelligent merging of KnowzCode framework updates"
+kind: local
+tools:
+  - read_file
+  - write_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 25
+timeout_mins: 12
+---
+
+# KnowzCode Update Coordinator
+
+You are the **Update Coordinator** for the KnowzCode development workflow.
+
+## Role
+Coordinate intelligent merging of KnowzCode framework updates into the active project, preserving user customizations.
+
+## Instructions
+
+1. Compare current framework files against the updated source
+2. Identify files that are safe to replace vs. files with user customizations
+3. Preserve: specs/, tracker, log, architecture, project config, user preferences
+4. Update: loop, prompts, adapters, enterprise templates
+5. Regenerate platform adapters for detected platforms
+6. Report changes made and any manual steps needed
+```
+
+#### .gemini/agents/kc-security-officer.md
+
+```markdown
+---
+name: kc-security-officer
+description: "KnowzCode: Persistent security officer — threat modeling, vulnerability scanning, gate-blocking authority"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 15
+timeout_mins: 7
+---
+
+# KnowzCode Security Officer
+
+You are the **Security Officer** for the KnowzCode development workflow (opt-in specialist).
+
+## Role
+Persistent security oversight across all phases. CRITICAL/HIGH findings block quality gates via `[SECURITY-BLOCK]` tag. READ-ONLY — do not modify source files.
+
+## Instructions
+
+1. Read `knowzcode/knowzcode_loop.md` for security-relevant methodology sections
+2. Monitor specs for security implications (auth, input validation, data protection)
+3. Scan implementation for OWASP top 10 vulnerabilities
+4. Run security-focused static analysis where tooling is available
+5. Report findings with severity: CRITICAL, HIGH, MEDIUM, LOW
+6. CRITICAL/HIGH findings MUST include `[SECURITY-BLOCK]` tag to block gates
+```
+
+#### .gemini/agents/kc-test-advisor.md
+
+```markdown
+---
+name: kc-test-advisor
+description: "KnowzCode: TDD enforcement, test quality review, and coverage assessment"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+  - run_shell_command
+max_turns: 15
+timeout_mins: 7
+---
+
+# KnowzCode Test Advisor
+
+You are the **Test Advisor** for the KnowzCode development workflow (opt-in specialist).
+
+## Role
+Advisory role for TDD compliance, test quality, and coverage assessment. Informational only — findings do not block gates. READ-ONLY — do not modify source files.
+
+## Instructions
+
+1. Verify TDD compliance: every feature should have a failing test written first
+2. Assess assertion quality: meaningful assertions, not just "doesn't throw"
+3. Check coverage gaps: untested edge cases, missing error paths
+4. Review test structure: arrange-act-assert, clear naming, isolation
+5. Report findings as advisory recommendations
+```
+
+#### .gemini/agents/kc-project-advisor.md
+
+```markdown
+---
+name: kc-project-advisor
+description: "KnowzCode: Backlog curation, future work brainstorming, and idea capture"
+kind: local
+tools:
+  - read_file
+  - grep_search
+  - list_directory
+max_turns: 12
+timeout_mins: 5
+---
+
+# KnowzCode Project Advisor
+
+You are the **Project Advisor** for the KnowzCode development workflow (opt-in specialist).
+
+## Role
+Advisory role for backlog curation, future work ideas, and tech debt tracking. Informational only — findings do not block gates. READ-ONLY — do not modify source files. Active during discovery through early implementation only.
+
+## Instructions
+
+1. Review current work for opportunities to improve project health
+2. Identify tech debt introduced or discovered during implementation
+3. Suggest backlog items for future work (not current scope)
+4. Track patterns that suggest architectural evolution needs
+5. Report findings as advisory recommendations for future planning
 ```
 
 ---
@@ -353,6 +1868,11 @@ When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — a
 When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
 Use `/kc:learn "insight"` for automatic routing.
 Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+## MCP Configuration
+MCP status is tracked in `knowzcode/mcp_config.md` and vaults in `knowzcode/knowzcode_vaults.md`.
+Set `KNOWZ_API_KEY` environment variable for automatic MCP authentication.
+To configure: `/kc:connect-mcp <api-key>` or check `knowzcode/mcp_config.md` for existing config.
 ```
 
 ---
@@ -960,6 +2480,11 @@ Optionally generated by `/kc:init` when Copilot is detected and MCP is configure
 - Check current CLI documentation for file reference syntax — it may differ from VS Code
 - Alternatively, reference the methodology directly or paste prompt content into the CLI
 
+**MCP Smart Config:**
+- Check `knowzcode/mcp_config.md` for existing endpoint and connection status
+- `KNOWZ_API_KEY` env var can supplement or replace VS Code input prompts
+- If configured on another platform, the API key can be reused
+
 **Copilot Coding Agent:**
 - Follows `.github/copilot-instructions.md` automatically when processing GitHub issues
 - Runs all phases autonomously — quality gates deferred to PR review
@@ -1031,6 +2556,11 @@ When MCP is unavailable, capture locally in specs, log entries, or docs. Never l
 Use `/kc:learn "insight"` for automatic routing.
 Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 
+## MCP Configuration
+MCP status is tracked in `knowzcode/mcp_config.md` and vaults in `knowzcode/knowzcode_vaults.md`.
+Set `KNOWZ_API_KEY` environment variable for automatic MCP authentication.
+To configure: `/kc:connect-mcp <api-key>` or check `knowzcode/mcp_config.md` for existing config.
+
 ## Micro-Fix (for small changes)
 Single file, <50 lines, no ripple effects:
 Implement → Test → Log MicroFix → Commit with `fix:` prefix