knowzcode 0.4.0 → 0.5.2

package/knowzcode/platform_adapters.md

@@ -1,1260 +1,2577 @@
-# KnowzCode Platform Adapters
-
-This file contains adapter templates for integrating KnowzCode with different AI coding platforms. Each adapter teaches the platform's AI how to follow the KnowzCode methodology with full phase walkthroughs, quality gates, and TDD enforcement.
-
-Generated by `/kc:init`. Adapters should be placed in the project root (or platform-specific location).
-
----
-
-## Claude Code (CLAUDE.md section)
-
-Append to or create `CLAUDE.md` in project root:
-
-```markdown
-# KnowzCode Integration
-
-This project uses KnowzCode for structured TDD development with multi-agent orchestration.
-
-## Required Reading
-- `knowzcode/knowzcode_loop.md` — Development methodology (TDD, quality gates, phases)
-- `knowzcode/knowzcode_project.md` — Project context and tech stack
-- `knowzcode/knowzcode_tracker.md` — Current WorkGroup status
-- `knowzcode/knowzcode_architecture.md` — Architecture documentation
-
-## Workflow Phases
-Follow the phases in `knowzcode_loop.md` for all feature work:
-1. **Phase 1A: Impact Analysis** — Identify affected components, propose Change Set. PAUSE for user approval.
-2. **Phase 1B: Specification** — Draft specs for all NodeIDs. PAUSE for user approval. Commit specs.
-3. **Phase 2A: Implementation** — Strict TDD (Red-Green-Refactor). No production code without a failing test.
-4. **Phase 2B: Completeness Audit** — Independent READ-ONLY audit. PAUSE for user decision on gaps.
-5. **Phase 3: Finalization** — Update specs to as-built, update tracker, log entry, final commit.
-
-## Quality Gates
-Never skip phases. PAUSE for user approval at each gate:
-- After Change Set proposal (1A)
-- After spec drafts (1B)
-- After implementation (2A — awaiting audit)
-- After audit results (2B — user decides on gaps)
-
-## TDD Enforcement
-TDD is mandatory — no production code without a failing test first.
-Red-Green-Refactor cycle for every feature/criterion in the spec.
-
-## Agents
-Specialized agents handle each phase when using Agent Teams or subagent execution:
-- `analyst` (1A), `architect` (1B), `builder` (2A), `reviewer` (2B), `closer` (3)
-- Agent Teams is the preferred execution model when enabled (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var)
-- Subagent fallback for environments without Agent Teams
-
-## Commands
-- `/kc:work "goal"` — Start feature workflow
-- `/kc:plan "topic"` — Research before implementing
-- `/kc:audit [type]` — Run quality audits (spec, architecture, security, integration)
-- `/kc:fix "target" "summary"` — Quick targeted fix
-- `/kc:learn "insight"` — Capture learning to vault
-- `/kc:status` — Check MCP connection and vault status
-
-## MCP Integration
-If configured, agents use `search_knowledge`, `ask_question`, and `create_knowledge` for enhanced context.
-All commands work without MCP — it enhances but never blocks.
-
-### Knowledge Capture (CRITICAL — DO NOT SKIP)
-Every piece of durable knowledge — decisions, patterns, gotchas, workarounds, convention changes —
-**must** be captured. Knowledge lives in two places:
-
-- **MCP vaults** (when connected): `knowzcode/knowzcode_vaults.md` defines vault IDs, routing rules,
-  and write conditions. Always pass `vaultId` when calling `create_knowledge` — omitting it saves
-  to the tenant default vault, NOT the project vault.
-- **Local files** (always available): specs, workgroup files, log entries, architecture docs, and
-  `knowzcode/pending_captures.md` (scribe fallback queue when MCP is unavailable).
-
-If MCP is not connected, knowledge still gets captured locally. Never let insights die in the conversation.
-
-**Vault content detail**: Vault entries are retrieved via semantic search, not read directly like local files. Write detailed, self-contained entries with full reasoning, specific technology names, code examples, and file paths. Terse entries produce poor search results. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
-
-### Knowz-Scribe Delegation
-When knowz-scribe is active (Agent Teams mode), it owns all vault writes — do NOT call `create_knowledge` directly. Send knowledge to the scribe instead:
-
-- **Phase captures**: Handled automatically at quality gates via task-tracked DMs
-- **Explicit**: `"Log: {description}"` — scribe MUST write it; it decides routing (which vault or local file)
-- **Soft**: `"Consider: {description}"` — scribe evaluates whether to capture and where; may skip if not insight-worthy or duplicative
-
-Any agent can send ad-hoc knowledge to the scribe at any time. The scribe handles routing, dedup, and formatting. If MCP is unavailable, the scribe queues captures to `knowzcode/pending_captures.md` for later sync. When no scribe is active, use `/kc:learn "insight"` for automatic routing.
-
-## WorkGroup Files
-- Created in `knowzcode/workgroups/` (gitignored)
-- Every todo must start with `KnowzCode:` prefix
-- Track phase history, Change Set, and outstanding work
-```
-
----
-
-## 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.
-
-```markdown
-# KnowzCode Development Methodology
-
-This project uses KnowzCode for structured TDD development.
-Read `knowzcode/knowzcode_loop.md` before starting any feature work.
-
-## Phase Walkthrough
-
-### Before Starting
-1. Read `knowzcode/knowzcode_tracker.md` — check for active WorkGroups
-2. Read `knowzcode/knowzcode_project.md` — understand project context
-3. Read `knowzcode/knowzcode_architecture.md` — understand current architecture
-
-### Phase 1A: Impact Analysis
-- Analyze what needs to change for the given goal
-- Create NodeIDs for NEW capabilities only (not per-file)
-- Check `knowzcode/specs/` for existing specs in the same domain
-- Propose a Change Set with NodeIDs, affected files, and risk assessment
-- **STOP**: Present Change Set for user approval before continuing
-
-### Phase 1B: Specification
-- Draft specs for each NodeID using the 4-section format:
-  - Rules & Decisions, Interfaces, Verification Criteria, Debt & Gaps
-- Minimum: 1+ Rules, 1+ Interface, 2+ VERIFY statements per spec
-- Save to `knowzcode/specs/{NodeID}.md`
-- **STOP**: Present specs for user approval
-- After approval: `git commit` the specs as a checkpoint
-
-### Phase 2A: Implementation (TDD MANDATORY)
-- For EACH feature/criterion in the spec:
-  1. RED: Write a failing test first
-  2. GREEN: Write minimal code to make the test pass
-  3. REFACTOR: Clean up while keeping tests green
-- Run full test suite + static analysis + build after all features
-- Maximum 10 verification iterations before pausing
-- **STOP**: Report implementation results
-
-### Phase 2B: Completeness Audit
-- READ-ONLY audit — do NOT modify source files
-- Compare implementation against all VERIFY statements in specs
-- Calculate completion percentage
-- Report gaps, security concerns, integration issues
-- **STOP**: Present audit results for user decision
-
-### Phase 3: Finalization
-- Update specs to "As-Built" status
-- Check architecture doc for drift
-- Prepend log entry to `knowzcode/knowzcode_log.md`
-- Update tracker statuses to `[VERIFIED]`
-- Create final commit with all changes
-
-## Key Rules
-- Always propose a Change Set before implementing
-- Get user approval at every quality gate (STOP points above)
-- TDD is mandatory — no production code without failing tests
-- Log all completions in `knowzcode/knowzcode_log.md`
-- Track work in `knowzcode/knowzcode_tracker.md`
-- Every WorkGroup todo must start with `KnowzCode:` prefix
-- Target <20 specs per project — consolidate when domains overlap
-
-## Knowledge Capture (CRITICAL — DO NOT SKIP)
-Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
-When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
-When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
-Use `/kc:learn "insight"` for automatic routing.
-Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
-
-## Quick Fix (Micro-Fix)
-For single-file, <50 line, no-ripple-effect changes:
-1. Implement the fix
-2. Run targeted tests
-3. Log a MicroFix entry
-4. Commit with `fix:` prefix
-
-## Key Files
-- `knowzcode/knowzcode_loop.md` — Complete methodology
-- `knowzcode/knowzcode_project.md` — Project context
-- `knowzcode/knowzcode_architecture.md` — Architecture docs
-- `knowzcode/knowzcode_tracker.md` — WorkGroup tracking
-- `knowzcode/specs/` — Component specifications
-- `knowzcode/workgroups/` — Active session data (gitignored)
-```
-
-### Codex Skill Files (`.codex/skills/kc/`)
-
-Codex (2026) supports `SKILL.md` files for discoverable skills. Place in `.codex/skills/kc/` for automatic `/kc:` command namespacing in the Codex UI.
-
-#### .codex/skills/kc/work.md
-
-```markdown
-<!-- 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.
-```
-
-#### .codex/skills/kc/plan.md
-
-```markdown
-<!-- 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.
-```
-
-#### .codex/skills/kc/fix.md
-
-```markdown
-<!-- 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
-```
-
-#### .codex/skills/kc/audit.md
-
-```markdown
-<!-- 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.
-```
-
-#### .codex/skills/kc/learn.md
-
-```markdown
-<!-- 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.
-```
-
-#### .codex/skills/kc/continue.md
-
-```markdown
-<!-- 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`.
-```
-
----
-
-## 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 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."""
-```
-
-```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."""
-```
-
-```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."""
-```
-
-```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/>"""
-```
-
-```toml
-# .gemini/commands/kc/learn.toml
-description = "Capture a learning to KnowzCode vault"
-prompt = """Read knowzcode/knowzcode_loop.md section on Knowledge Capture.
-Capture the following learning: <ARGS/>
-Route to the appropriate vault per knowzcode/knowzcode_vaults.md.
-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 = """Check the MCP connection status by calling list_vaults.
-Report which vaults are configured in knowzcode/knowzcode_vaults.md.
-Show active WorkGroups from knowzcode/knowzcode_tracker.md."""
-```
-
-```toml
-# .gemini/commands/kc/continue.toml
-description = "Resume interrupted KnowzCode workflow"
-prompt = """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."""
-```
-
-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.
-
-## 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:`
-```
-
----
-
-## Cursor (`.cursor/rules/knowzcode.mdc`)
-
-Create `.cursor/rules/knowzcode.mdc` with YAML frontmatter. Notes: Modern Cursor uses `.cursor/rules/*.mdc` files instead of the deprecated `.cursorrules`. Scoped rules can target specific file patterns using the `globs` frontmatter field. Cursor 1.6+ (2026) also supports `.cursor/commands/*.md` for custom slash commands (beta) and reads `AGENTS.md` for agent instructions.
-
-```markdown
----
-description: KnowzCode TDD development methodology
-alwaysApply: true
----
-
-# KnowzCode Rules
-
-This project uses KnowzCode for structured TDD development.
-
-## Required Reading
-Before any feature work, read:
-- `knowzcode/knowzcode_loop.md` — Complete methodology
-- `knowzcode/knowzcode_project.md` — Project context
-- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
-- `knowzcode/knowzcode_architecture.md` — Architecture docs
-
-## Phase Rules
-
-### Phase 1A: Impact Analysis
-- Identify affected components and propose a Change Set
-- NodeIDs are domain concepts (PascalCase), not tasks
-- Check `knowzcode/specs/` before creating new specs
-- PAUSE for user approval before proceeding
-
-### Phase 1B: Specification
-- Use 4-section format: Rules & Decisions, Interfaces, Verification Criteria, Debt & Gaps
-- Minimum: 2+ VERIFY statements per spec
-- PAUSE for user approval, then commit specs
-
-### Phase 2A: Implementation
-- TDD is mandatory: write failing test FIRST, then minimal code, then refactor
-- Use Composer for multi-file edits when implementing across components
-- Run full test suite before reporting complete
-- PAUSE after implementation
-
-### Phase 2B: Audit
-- READ-ONLY — do not modify source files
-- Compare implementation vs spec VERIFY statements
-- Report completion percentage and gaps
-- PAUSE for user decision
-
-### Phase 3: Finalization
-- Update specs to As-Built status
-- Update tracker and log
-- Check architecture for drift
-- Final commit
-
-## Enforcement
-- Never skip phases or quality gates
-- TDD is mandatory — no production code without a failing test
-- Every WorkGroup todo starts with `KnowzCode:` prefix
-- Consolidate specs when domains overlap >50%
-- Target <20 specs per project
-- Read `knowzcode/knowzcode_tracker.md` for active work
-- Log completions in `knowzcode/knowzcode_log.md`
-
-## 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.
-```
-
----
-
-## GitHub Copilot (.github/copilot-instructions.md + .github/prompts/*.prompt.md)
-
-GitHub Copilot (2026) supports three instruction mechanisms used by KnowzCode:
-
-1. **`.github/copilot-instructions.md`** — Repository-level instructions, always active
-2. **`.github/prompts/*.prompt.md`** — Custom prompts invocable via `#prompt:name` in VS Code
-3. **MCP server tools** (`.vscode/mcp.json`) — Tool access for vault queries
-
-Copilot operates as a **single-agent, sequential** platform — no multi-agent orchestration. Users manually transition between phases using prompt files. See `knowzcode/copilot_execution.md` for the full execution model.
-
-### A. copilot-instructions.md
-
-Create `.github/copilot-instructions.md`:
-
-```markdown
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode Development Methodology
-
-This repository uses KnowzCode for structured TDD development with quality gates.
-
-## Required Reading
-- `knowzcode/knowzcode_loop.md` — Complete methodology (read first)
-- `knowzcode/knowzcode_project.md` — Project context and tech stack
-- `knowzcode/knowzcode_architecture.md` — Architecture documentation
-- `knowzcode/knowzcode_tracker.md` — WorkGroup status tracking
-
-## Workflow Overview
-
-KnowzCode follows a 5-phase development loop with quality gates between each phase.
-Use the prompt files in `.github/prompts/` to invoke each phase:
-
-| Phase | Prompt | Description |
-|-------|--------|-------------|
-| Full workflow | `#prompt:kc-work` | Start a new feature — creates WorkGroup, classifies tier, runs Phase 1A |
-| 1A: Analysis | `#prompt:kc-analyze` | Re-run impact analysis on existing WorkGroup |
-| 1B: Specification | `#prompt:kc-specify` | Draft specs from approved Change Set |
-| 2A: Implementation | `#prompt:kc-implement` | TDD implementation with verification loop |
-| 2B: Audit | `#prompt:kc-audit` | READ-ONLY audit against specs |
-| 3: Finalization | `#prompt:kc-finalize` | Update specs, tracker, log, commit |
-| Quick fix | `#prompt:kc-fix` | Micro-fix for small, scoped changes |
-| Research | `#prompt:kc-plan` | Investigate before implementing |
-| Resume | `#prompt:kc-continue` | Resume or advance to next phase |
-
-### Typical Flow
-
-1. `#prompt:kc-work "Build JWT authentication"` → Creates WorkGroup, proposes Change Set, **STOPs**
-2. Approve Change Set
-3. `#prompt:kc-specify` → Drafts specs, **STOPs**
-4. Approve specs
-5. `#prompt:kc-implement` → TDD Red-Green-Refactor, **STOPs**
-6. `#prompt:kc-audit` → READ-ONLY audit, reports gaps, **STOPs**
-7. `#prompt:kc-finalize` → Updates docs, commits
-
-Use `#prompt:kc-continue` at any point to resume where you left off.
-
-## Quality Gates
-
-STOP and await user approval at each gate:
-- After Change Set proposal (1A)
-- After spec drafts (1B)
-- After implementation complete (2A — awaiting audit)
-- After audit results (2B — user decides on gaps)
-
-## TDD Enforcement
-
-TDD is mandatory — no production code without a failing test first.
-Follow Red-Green-Refactor for every feature/criterion in the spec.
-
-## Key Rules
-- NodeIDs are domain concepts (PascalCase), not tasks
-- Consolidate specs when domains overlap >50%
-- Every WorkGroup todo starts with `KnowzCode:` prefix
-- Target <20 specs per project
-- Log completions in `knowzcode/knowzcode_log.md`
-
-## Key Files
-- `knowzcode/knowzcode_loop.md` — Methodology
-- `knowzcode/knowzcode_project.md` — Project context
-- `knowzcode/knowzcode_architecture.md` — Architecture docs
-- `knowzcode/knowzcode_tracker.md` — WorkGroup tracking
-- `knowzcode/specs/` — Component specifications
-- `knowzcode/workgroups/` — Active session data (gitignored)
-
-## MCP Integration
-
-If configured in `.vscode/mcp.json`, use `search_knowledge` and `ask_question` tools
-for enhanced context from knowledge vaults. All prompts work without MCP.
-
-## Knowledge Capture (CRITICAL — DO NOT SKIP)
-Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
-When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
-When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
-Use `/kc:learn "insight"` for automatic routing.
-Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
-
-## Copilot Coding Agent
-
-When the Copilot Coding Agent works on GitHub issues for this repository:
-- Read `knowzcode/knowzcode_loop.md` and this file for methodology
-- Follow Phase 1A→3 workflow for any non-trivial change
-- Include the Change Set in the PR description
-- Use TDD — failing test before implementation code
-- Self-audit against spec VERIFY statements before marking PR ready
-- Quality gates are deferred to PR review (no interactive approval in async mode)
-
-## Model Selection
-- Complex phases (1A analysis, 1B spec drafting, 2B audit): Use Claude Opus or GPT-4o
-- Implementation (2A): Any capable model with good code generation
-- Quick fixes: Any model
-```
-
-### B. Prompt File Templates (.github/prompts/)
-
-Each prompt file is invocable via `#prompt:kc-*` in VS Code Copilot Chat. All use `agent: "agent"` for file editing capability.
-
-#### kc-work.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Start a new KnowzCode development workflow"
-argument-hint: "Describe the feature or goal to build"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Start Workflow
-
-You are starting a new KnowzCode development workflow. Follow the methodology precisely.
-
-## Context
-
-Read these files for methodology and project context:
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_project.md
-- #file:knowzcode/knowzcode_tracker.md
-- #file:knowzcode/knowzcode_architecture.md
-
-## Instructions
-
-The user's goal is provided in the chat message.
-
-### Step 1: Classify Tier
-
-Based on the goal, classify complexity:
-- **Micro** (single file, <50 lines, no ripple): Redirect to `#prompt:kc-fix`
-- **Light** (≤3 files, straightforward): Streamlined 2-phase path
-- **Full** (>3 files or complex): Complete 5-phase workflow
-
-### Step 2: Create Draft WorkGroup
-
-Generate a WorkGroupID: `kc-{type}-{slug}-YYYYMMDD-HHMMSS`
-Create a draft WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md` to store the analysis output.
-
-### Step 3: Phase 1A — Impact Analysis
-
-Follow Phase 1A from `knowzcode/knowzcode_loop.md`:
-1. Identify the Change Set — all components affected by this change
-2. Create NodeIDs for NEW capabilities only (domain concepts, PascalCase)
-3. Check `knowzcode/specs/` for existing specs with domain overlap
-4. Scan `knowzcode/workgroups/` for completed WorkGroups with relevant context
-5. Propose the Change Set with NodeIDs, affected files, and risk assessment
-
-## STOP
-
-Present the Change Set for user approval. Do NOT proceed until approved.
-
-**After approval:** Update `knowzcode/knowzcode_tracker.md` with new NodeIDs as `[WIP]`, then tell the user to invoke `#prompt:kc-specify` to draft specifications.
-```
-
-#### kc-analyze.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Re-run Phase 1A impact analysis on existing WorkGroup"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Phase 1A — Impact Analysis
-
-You are re-running impact analysis on an existing WorkGroup.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_tracker.md
-
-Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
-Then read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
-
-## Instructions
-
-Follow Phase 1A from `knowzcode/knowzcode_loop.md`:
-1. Re-analyze the goal from the WorkGroup file
-2. Identify all affected components — check for changes since last analysis
-3. Update NodeIDs if scope has changed
-4. Check `knowzcode/specs/` for existing specs with domain overlap
-5. Update the Change Set in the WorkGroup file
-
-## STOP
-
-Present the updated Change Set for user approval.
-
-**Next step after approval:** `#prompt:kc-specify`
-```
-
-#### kc-specify.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Draft specifications from approved Change Set (Phase 1B)"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Phase 1B — Specification
-
-You are drafting specifications for the approved Change Set.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_tracker.md
-
-Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
-If no `[WIP]` entries found, scan `knowzcode/workgroups/` for the most recent draft WorkGroup file.
-Then read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md` for the approved Change Set.
-
-## Instructions
-
-Follow Phase 1B from `knowzcode/knowzcode_loop.md`:
-
-For each NodeID in the approved Change Set:
-1. Draft `knowzcode/specs/{NodeID}.md` using the 4-section format:
-   - **Rules & Decisions** — Key architectural decisions, business rules, constraints
-   - **Interfaces** — Public contracts: inputs, outputs, API signatures, dependencies
-   - **Verification Criteria** — Testable `VERIFY:` assertions (minimum 2 per spec)
-   - **Debt & Gaps** — Known limitations and future work
-2. Minimum valid spec: 1+ Rules, 1+ Interface, 2+ VERIFY statements
-3. Check existing specs — if >50% domain overlap, UPDATE existing spec instead
-4. Update the WorkGroup file with spec status
-
-## STOP
-
-Present all drafted specs for user approval. Do NOT proceed until approved.
-
-**After approval:** Commit the specs as a pre-implementation checkpoint: `git commit -m "specs: draft specs for {WorkGroupID}"`
-
-**Next step:** `#prompt:kc-implement`
-```
-
-#### kc-implement.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "TDD implementation with verification loop (Phase 2A)"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Phase 2A — Implementation
-
-You are implementing the approved specifications using strict TDD.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_tracker.md
-
-Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
-Then read:
-- The WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`
-- All spec files listed in the Change Set from `knowzcode/specs/`
-
-## Instructions
-
-Follow Phase 2A from `knowzcode/knowzcode_loop.md`:
-
-For EACH feature/criterion in the specs:
-1. **RED**: Write a failing test that defines expected behavior. Run test → confirm FAIL
-2. **GREEN**: Write MINIMAL code to make the test pass. Run test → confirm PASS
-3. **REFACTOR**: Clean up while keeping all tests green
-
-### Verification Loop (must pass before reporting complete)
-
-1. Run all tests → if FAIL: fix and restart
-2. Run static analysis → if issues: fix and restart
-3. Run build → if FAIL: fix and restart
-4. Verify all VERIFY: criteria from specs → if unmet: implement and restart
-5. All checks pass → report complete
-
-Maximum 10 iterations. If exceeded, report blocker.
-
-### Spec Issues
-
-If you discover a spec is incorrect during implementation:
-- Tag `[SPEC_ISSUE]` in the WorkGroup file with details
-- Continue with best judgment
-- Report in completion summary
-
-## STOP
-
-Report implementation results: test counts, verification iterations, criteria status.
-
-**Next step:** `#prompt:kc-audit`
-```
-
-#### kc-audit.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "READ-ONLY completeness audit against specs (Phase 2B)"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Phase 2B — Completeness Audit
-
-You are performing an independent, READ-ONLY audit of the implementation.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_tracker.md
-
-Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
-Then read:
-- The WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`
-- All spec files listed in the Change Set from `knowzcode/specs/`
-- The implementation files listed in the Change Set
-
-## Instructions
-
-Follow Phase 2B from `knowzcode/knowzcode_loop.md`:
-
-**CRITICAL: This is a READ-ONLY audit. Do NOT modify any source files.**
-
-1. For each NodeID, compare implementation against every VERIFY statement in its spec
-2. Calculate objective completion percentage per NodeID and overall
-3. Identify gaps: missing features, incomplete criteria, untested paths
-4. Check for security concerns: input validation, authentication, data exposure
-5. Check for orphan code: implementation not covered by any spec
-6. Assess risk for any gaps found
-
-### Standalone Audit Types
-
-If the user specifies an audit type instead of a WorkGroup audit:
-- **spec**: Audit spec quality — completeness, VERIFY statement coverage, format compliance
-- **architecture**: Compare architecture doc against actual codebase structure
-- **security**: Focused security review — OWASP top 10, input validation, auth flows
-- **integration**: Check integration points, API contracts, dependency health
-
-## STOP
-
-Present audit results with completion percentage, gap list, and risk assessment.
-
-**User decides:**
-- Return to `#prompt:kc-implement` to fix gaps
-- Accept and proceed to `#prompt:kc-finalize`
-- Modify specs to match implementation
-- Cancel the WorkGroup
-```
-
-#### kc-finalize.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Finalize WorkGroup — update specs, tracker, log, commit (Phase 3)"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Phase 3 — Finalization
-
-You are finalizing the WorkGroup after approved implementation and audit.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_tracker.md
-- #file:knowzcode/knowzcode_architecture.md
-
-Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
-Then read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
-
-## Instructions
-
-Follow Phase 3 from `knowzcode/knowzcode_loop.md`:
-
-1. **Finalize Specs**: Update each `knowzcode/specs/{NodeID}.md` to as-built state (Status: As-Built)
-2. **Architecture Check**: Compare `knowzcode/knowzcode_architecture.md` against the Change Set. Fix simple discrepancies directly; document complex ones for user review
-3. **Log Entry**: Prepend an `ARC-Completion` entry to `knowzcode/knowzcode_log.md` with WorkGroupID, NodeIDs, verification summary, architectural learnings, and ripple effects
-4. **Update Tracker**: Change NodeID statuses from `[WIP]` to `[VERIFIED]` in `knowzcode/knowzcode_tracker.md`. Create `REFACTOR_` tasks for significant tech debt
-5. **Final Commit**: Stage and commit all changes (source + knowzcode files)
-6. **Close WorkGroup**: Mark the WorkGroup file as closed
-
-## Output
-
-Report completion with summary of what was delivered and any `REFACTOR_` tasks created.
-```
-
-#### kc-fix.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Quick targeted fix using micro-fix protocol"
-argument-hint: "Describe the bug or issue to fix"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Micro-Fix
-
-You are performing a quick, targeted fix using the micro-fix protocol.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-
-## 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, inform the user and suggest `#prompt:kc-work` instead.
-
-## Instructions
-
-Follow the Micro-Fix Protocol from `knowzcode/knowzcode_loop.md` Section 4:
-
-1. **Implement** the fix
-2. **Test** — run targeted tests for the affected code
-3. **Log** — prepend a `MicroFix` entry to `knowzcode/knowzcode_log.md`:
-   - Type: MicroFix
-   - File/NodeID affected
-   - User request, action taken, verification outcome
-4. **Commit** with `fix: {description}` message
-```
-
-#### kc-plan.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Research and investigate before implementing"
-argument-hint: "Describe the topic to research"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Plan / Investigate
-
-You are researching a topic before implementation. This is an investigation workflow, not a build workflow.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_project.md
-- #file:knowzcode/knowzcode_architecture.md
-
-## Instructions
-
-The user's research topic is provided in the chat message.
-
-1. **Explore the codebase** — search for relevant files, patterns, and existing implementations
-2. **Read existing specs** — check `knowzcode/specs/` for related components
-3. **Check history** — scan `knowzcode/workgroups/` for past WorkGroups that touched similar areas
-4. **Analyze architecture** — review `knowzcode/knowzcode_architecture.md` for structural context
-5. **Present findings** with:
-   - Current state of the relevant code
-   - Existing patterns and conventions
-   - Options for implementation (with trade-offs)
-   - Recommended approach
-
-## STOP
-
-Present research findings and recommendations.
-
-**To implement:** Tell the user to invoke `#prompt:kc-work` with their chosen approach.
-```
-
-#### kc-continue.prompt.md
-
-```markdown
----
-agent: "agent"
-description: "Resume interrupted work or advance to next phase"
----
-
-<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
-
-# KnowzCode: Continue / Resume
-
-You are resuming an interrupted KnowzCode workflow or advancing to the next phase.
-
-## Context
-
-- #file:knowzcode/knowzcode_loop.md
-- #file:knowzcode/knowzcode_tracker.md
-
-## Instructions
-
-### Step 1: Find Active WorkGroup
-
-Read `knowzcode/knowzcode_tracker.md` and find entries with `[WIP]` status.
-
-- **One active WorkGroup**: Use it
-- **Multiple active**: Present the list and ask the user which to resume
-- **None active**: Inform the user and suggest `#prompt:kc-work`
-
-### Step 2: Determine Current Phase
-
-Read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
-Check the Phase History table to determine the current state.
-
-### Step 3: Resume or Advance
-
-| WorkGroup State | Action |
-|----------------|--------|
-| Phase 1A in progress | Complete the impact analysis, present Change Set |
-| Phase 1A complete, awaiting approval | Present Change Set for approval |
-| Phase 1A approved, specs not started | Begin Phase 1B — draft specs |
-| Phase 1B in progress | Complete spec drafting |
-| Phase 1B complete, awaiting approval | Present specs for approval |
-| Phase 1B approved, implementation not started | Begin Phase 2A — TDD implementation |
-| Phase 2A in progress | Resume implementation from outstanding todos |
-| Phase 2A complete | Advise: `#prompt:kc-audit` |
-| Phase 2B complete, gaps found | Present options: fix gaps or accept |
-| Phase 2B complete, no gaps | Begin Phase 3 — finalization |
-| Phase 3 in progress | Complete finalization |
-
-### Step 4: Present Status
-
-```
-## Resuming WorkGroup: {WorkGroupID}
-
-**Goal**: {primary goal}
-**Phase**: {current phase}
-**NodeIDs**: {list}
-
-**Outstanding Work**:
-{list from WorkGroup file}
-
-Continuing from where we left off...
-```
-
-Then proceed with the appropriate phase instructions from `knowzcode/knowzcode_loop.md`.
-```
-
-### C. .vscode/mcp.json Template
-
-Optionally generated by `/kc:init` when Copilot is detected and MCP is configured:
-
-```json
-{
-  "servers": {
-    "knowz": {
-      "type": "http",
-      "url": "${input:knowz_mcp_url}",
-      "headers": {
-        "x-api-key": "${input:knowz_api_key}"
-      }
-    }
-  },
-  "inputs": [
-    {
-      "id": "knowz_mcp_url",
-      "description": "KnowzCode MCP server URL",
-      "type": "promptString"
-    },
-    {
-      "id": "knowz_api_key",
-      "description": "KnowzCode API key",
-      "type": "promptString",
-      "password": true
-    }
-  ]
-}
-```
-
-### D. Copilot-Specific Notes
-
-**VS Code usage:**
-- Invoke prompts via `#prompt:kc-work`, `#prompt:kc-specify`, etc. in Copilot Chat
-- Add extra files to context with `#file:path/to/file` in the chat message
-- All prompt files use `agent: "agent"` frontmatter for file editing and terminal access
-- Model can be selected per session — prefer stronger models for analysis/audit phases
-
-**Copilot CLI fallback:**
-- CLI does not support `#prompt:` syntax
-- 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
-
-**Copilot Coding Agent:**
-- Follows `.github/copilot-instructions.md` automatically when processing GitHub issues
-- Runs all phases autonomously — quality gates deferred to PR review
-- Does not use prompt files (uses repository instructions only)
-
-**Execution model:**
-- See `knowzcode/copilot_execution.md` for the full execution guide
-- Single-agent, sequential execution — user manually transitions between phases
-- No multi-agent orchestration (no Parallel Teams, no agent spawning)
-- WorkGroup files carry state between prompt invocations
-
----
-
-## Windsurf (`.windsurf/rules/knowzcode.md`)
-
-Create `.windsurf/rules/knowzcode.md`. Notes: Modern Windsurf uses the `.windsurf/rules/` directory instead of the deprecated `.windsurfrules` file. Cascade multi-file editing works well with KnowzCode's cross-component implementation phases. Windsurf also supports `.windsurf/workflows/*.md` for custom commands invoked as `/workflow-name` — KnowzCode workflows can be defined as individual workflow files for each phase.
-
-```markdown
-# KnowzCode Development Methodology
-
-This project uses KnowzCode for structured TDD development.
-Follow `knowzcode/knowzcode_loop.md` for all feature development.
-
-## Required Reading
-- `knowzcode/knowzcode_loop.md` — Complete methodology
-- `knowzcode/knowzcode_project.md` — Project context
-- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
-- `knowzcode/knowzcode_architecture.md` — Architecture docs
-
-## Phase Walkthrough
-
-### Phase 1A: Impact Analysis
-- Identify affected components, propose Change Set with NodeIDs
-- Check existing specs before creating new ones
-- PAUSE for user approval
-
-### Phase 1B: Specification
-- Draft specs with 4-section format and 2+ VERIFY statements
-- PAUSE for approval, then commit specs
-
-### Phase 2A: Implementation (TDD Mandatory)
-- Write failing test FIRST, then minimal code, then refactor
-- Use Cascade for multi-file edits across components
-- Run full verification loop (tests + linter + build)
-- PAUSE after implementation
-
-### Phase 2B: Audit
-- READ-ONLY audit against spec VERIFY statements
-- Report completion %, gaps, security concerns
-- PAUSE for user decision
-
-### Phase 3: Finalization
-- Update specs to As-Built, tracker, log, architecture
-- Final commit
-
-## Enforcement Rules
-- TDD is mandatory — write failing tests before implementation code
-- Respect quality gates between phases — PAUSE at each gate
-- Update `knowzcode/knowzcode_tracker.md` when completing work
-- Log completions in `knowzcode/knowzcode_log.md`
-- Consolidate specs when domains overlap >50%
-- Target <20 specs per project
-- Every WorkGroup todo starts with `KnowzCode:` prefix
-
-## Knowledge Capture (CRITICAL — DO NOT SKIP)
-Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
-When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
-When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
-Use `/kc:learn "insight"` for automatic routing.
-Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
-
-## Micro-Fix (for small changes)
-Single file, <50 lines, no ripple effects:
-Implement → Test → Log MicroFix → Commit with `fix:` prefix
-```
-
----
-
-## OpenAI Codex Agents SDK (Python)
-
-For teams building custom orchestration with the OpenAI Agents SDK,
-map KnowzCode's 5 phase agents to SDK Agent definitions. The AGENTS.md
-file above provides all instructions each agent needs. See the
-[Agents SDK documentation](https://openai.github.io/openai-agents-python/)
-for implementation details.
+# KnowzCode Platform Adapters
+
+This file contains adapter templates for integrating KnowzCode with different AI coding platforms. Each adapter teaches the platform's AI how to follow the KnowzCode methodology with full phase walkthroughs, quality gates, and TDD enforcement.
+
+Generated by `/kc:init`. Adapters should be placed in the project root (or platform-specific location).
+
+---
+
+## Claude Code (CLAUDE.md section)
+
+Append to or create `CLAUDE.md` in project root:
+
+```markdown
+# KnowzCode Integration
+
+This project uses KnowzCode for structured TDD development with multi-agent orchestration.
+
+## Required Reading
+- `knowzcode/knowzcode_loop.md` — Development methodology (TDD, quality gates, phases)
+- `knowzcode/knowzcode_project.md` — Project context and tech stack
+- `knowzcode/knowzcode_tracker.md` — Current WorkGroup status
+- `knowzcode/knowzcode_architecture.md` — Architecture documentation
+
+## Workflow Phases
+Follow the phases in `knowzcode_loop.md` for all feature work:
+1. **Phase 1A: Impact Analysis** — Identify affected components, propose Change Set. PAUSE for user approval.
+2. **Phase 1B: Specification** — Draft specs for all NodeIDs. PAUSE for user approval. Commit specs.
+3. **Phase 2A: Implementation** — Strict TDD (Red-Green-Refactor). No production code without a failing test.
+4. **Phase 2B: Completeness Audit** — Independent READ-ONLY audit. PAUSE for user decision on gaps.
+5. **Phase 3: Finalization** — Update specs to as-built, update tracker, log entry, final commit.
+
+## Quality Gates
+Never skip phases. PAUSE for user approval at each gate:
+- After Change Set proposal (1A)
+- After spec drafts (1B)
+- After implementation (2A — awaiting audit)
+- After audit results (2B — user decides on gaps)
+
+## TDD Enforcement
+TDD is mandatory — no production code without a failing test first.
+Red-Green-Refactor cycle for every feature/criterion in the spec.
+
+## Agents
+Specialized agents handle each phase when using Agent Teams or subagent execution:
+- `analyst` (1A), `architect` (1B), `builder` (2A), `reviewer` (2B), `closer` (3)
+- Agent Teams is the preferred execution model when enabled (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var)
+- Subagent fallback for environments without Agent Teams
+
+## Commands
+- `/kc:work "goal"` — Start feature workflow
+- `/kc:plan "topic"` — Research before implementing
+- `/kc:audit [type]` — Run quality audits (spec, architecture, security, integration)
+- `/kc:fix "target" "summary"` — Quick targeted fix
+- `/kc:learn "insight"` — Capture learning to vault
+- `/kc:status` — Check MCP connection and vault status
+
+## MCP Integration
+If configured, agents use `search_knowledge`, `ask_question`, and `create_knowledge` for enhanced context.
+All commands work without MCP — it enhances but never blocks.
+
+### Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds, convention changes —
+**must** be captured. Knowledge lives in two places:
+
+- **MCP vaults** (when connected): `knowzcode/knowzcode_vaults.md` defines vault IDs, routing rules,
+  and write conditions. Always pass `vaultId` when calling `create_knowledge` — omitting it saves
+  to the tenant default vault, NOT the project vault.
+- **Local files** (always available): specs, workgroup files, log entries, architecture docs, and
+  `knowzcode/pending_captures.md` (scribe fallback queue when MCP is unavailable).
+
+If MCP is not connected, knowledge still gets captured locally. Never let insights die in the conversation.
+
+**Vault content detail**: Vault entries are retrieved via semantic search, not read directly like local files. Write detailed, self-contained entries with full reasoning, specific technology names, code examples, and file paths. Terse entries produce poor search results. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+### Knowz-Scribe Delegation
+When knowz-scribe is active (Agent Teams mode), it owns all vault writes — do NOT call `create_knowledge` directly. Send knowledge to the scribe instead:
+
+- **Phase captures**: Handled automatically at quality gates via task-tracked DMs
+- **Explicit**: `"Log: {description}"` — scribe MUST write it; it decides routing (which vault or local file)
+- **Soft**: `"Consider: {description}"` — scribe evaluates whether to capture and where; may skip if not insight-worthy or duplicative
+
+Any agent can send ad-hoc knowledge to the scribe at any time. The scribe handles routing, dedup, and formatting. If MCP is unavailable, the scribe queues captures to `knowzcode/pending_captures.md` for later sync. When no scribe is active, use `/kc:learn "insight"` for automatic routing.
+
+## WorkGroup Files
+- Created in `knowzcode/workgroups/` (gitignored)
+- Every todo must start with `KnowzCode:` prefix
+- Track phase history, Change Set, and outstanding work
+```
+
+---
+
+## 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 — 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
+
+This project uses KnowzCode for structured TDD development.
+Read `knowzcode/knowzcode_loop.md` before starting any feature work.
+
+## Phase Walkthrough
+
+### Before Starting
+1. Read `knowzcode/knowzcode_tracker.md` — check for active WorkGroups
+2. Read `knowzcode/knowzcode_project.md` — understand project context
+3. Read `knowzcode/knowzcode_architecture.md` — understand current architecture
+
+### Phase 1A: Impact Analysis
+- Analyze what needs to change for the given goal
+- Create NodeIDs for NEW capabilities only (not per-file)
+- Check `knowzcode/specs/` for existing specs in the same domain
+- Propose a Change Set with NodeIDs, affected files, and risk assessment
+- **STOP**: Present Change Set for user approval before continuing
+
+### Phase 1B: Specification
+- Draft specs for each NodeID using the 4-section format:
+  - Rules & Decisions, Interfaces, Verification Criteria, Debt & Gaps
+- Minimum: 1+ Rules, 1+ Interface, 2+ VERIFY statements per spec
+- Save to `knowzcode/specs/{NodeID}.md`
+- **STOP**: Present specs for user approval
+- After approval: `git commit` the specs as a checkpoint
+
+### Phase 2A: Implementation (TDD MANDATORY)
+- For EACH feature/criterion in the spec:
+  1. RED: Write a failing test first
+  2. GREEN: Write minimal code to make the test pass
+  3. REFACTOR: Clean up while keeping tests green
+- Run full test suite + static analysis + build after all features
+- Maximum 10 verification iterations before pausing
+- **STOP**: Report implementation results
+
+### Phase 2B: Completeness Audit
+- READ-ONLY audit — do NOT modify source files
+- Compare implementation against all VERIFY statements in specs
+- Calculate completion percentage
+- Report gaps, security concerns, integration issues
+- **STOP**: Present audit results for user decision
+
+### Phase 3: Finalization
+- Update specs to "As-Built" status
+- Check architecture doc for drift
+- Prepend log entry to `knowzcode/knowzcode_log.md`
+- Update tracker statuses to `[VERIFIED]`
+- Create final commit with all changes
+
+## Key Rules
+- Always propose a Change Set before implementing
+- Get user approval at every quality gate (STOP points above)
+- TDD is mandatory — no production code without failing tests
+- Log all completions in `knowzcode/knowzcode_log.md`
+- Track work in `knowzcode/knowzcode_tracker.md`
+- Every WorkGroup todo must start with `KnowzCode:` prefix
+- Target <20 specs per project — consolidate when domains overlap
+
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+## Quick Fix (Micro-Fix)
+For single-file, <50 line, no-ripple-effect changes:
+1. Implement the fix
+2. Run targeted tests
+3. Log a MicroFix entry
+4. Commit with `fix:` prefix
+
+## Key Files
+- `knowzcode/knowzcode_loop.md` — Complete methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+- `knowzcode/knowzcode_tracker.md` — WorkGroup tracking
+- `knowzcode/specs/` — Component specifications
+- `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 -->
+
+# /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`.
+```
+
+#### .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.
+```
+
+### 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.
+```
+
+#### .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/agents/kc-builder.md
+
+```markdown
+---
+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
+---
+
+# KnowzCode Builder
+
+You are the **TDD Builder** for the KnowzCode development workflow.
+
+## 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.
+
+## Instructions
+
+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.
+```
+
+#### .gemini/agents/kc-reviewer.md
+
+```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
+---
+
+# KnowzCode Reviewer
+
+You are the **Quality Reviewer** for the KnowzCode development workflow.
+
+## Role
+Perform Phase 2B: Completeness Audit. Conduct a READ-ONLY audit comparing implementation against specs. Do NOT modify source files.
+
+## 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
+```
+
+---
+
+## Cursor (`.cursor/rules/knowzcode.mdc`)
+
+Create `.cursor/rules/knowzcode.mdc` with YAML frontmatter. Notes: Modern Cursor uses `.cursor/rules/*.mdc` files instead of the deprecated `.cursorrules`. Scoped rules can target specific file patterns using the `globs` frontmatter field. Cursor 1.6+ (2026) also supports `.cursor/commands/*.md` for custom slash commands (beta) and reads `AGENTS.md` for agent instructions.
+
+```markdown
+---
+description: KnowzCode TDD development methodology
+alwaysApply: true
+---
+
+# KnowzCode Rules
+
+This project uses KnowzCode for structured TDD development.
+
+## Required Reading
+Before any feature work, read:
+- `knowzcode/knowzcode_loop.md` — Complete methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+
+## Phase Rules
+
+### Phase 1A: Impact Analysis
+- Identify affected components and propose a Change Set
+- NodeIDs are domain concepts (PascalCase), not tasks
+- Check `knowzcode/specs/` before creating new specs
+- PAUSE for user approval before proceeding
+
+### Phase 1B: Specification
+- Use 4-section format: Rules & Decisions, Interfaces, Verification Criteria, Debt & Gaps
+- Minimum: 2+ VERIFY statements per spec
+- PAUSE for user approval, then commit specs
+
+### Phase 2A: Implementation
+- TDD is mandatory: write failing test FIRST, then minimal code, then refactor
+- Use Composer for multi-file edits when implementing across components
+- Run full test suite before reporting complete
+- PAUSE after implementation
+
+### Phase 2B: Audit
+- READ-ONLY — do not modify source files
+- Compare implementation vs spec VERIFY statements
+- Report completion percentage and gaps
+- PAUSE for user decision
+
+### Phase 3: Finalization
+- Update specs to As-Built status
+- Update tracker and log
+- Check architecture for drift
+- Final commit
+
+## Enforcement
+- Never skip phases or quality gates
+- TDD is mandatory — no production code without a failing test
+- Every WorkGroup todo starts with `KnowzCode:` prefix
+- Consolidate specs when domains overlap >50%
+- Target <20 specs per project
+- Read `knowzcode/knowzcode_tracker.md` for active work
+- Log completions in `knowzcode/knowzcode_log.md`
+
+## 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 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.
+```
+
+---
+
+## GitHub Copilot (.github/copilot-instructions.md + .github/prompts/*.prompt.md)
+
+GitHub Copilot (2026) supports three instruction mechanisms used by KnowzCode:
+
+1. **`.github/copilot-instructions.md`** — Repository-level instructions, always active
+2. **`.github/prompts/*.prompt.md`** — Custom prompts invocable via `#prompt:name` in VS Code
+3. **MCP server tools** (`.vscode/mcp.json`) — Tool access for vault queries
+
+Copilot operates as a **single-agent, sequential** platform — no multi-agent orchestration. Users manually transition between phases using prompt files. See `knowzcode/copilot_execution.md` for the full execution model.
+
+### A. copilot-instructions.md
+
+Create `.github/copilot-instructions.md`:
+
+```markdown
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode Development Methodology
+
+This repository uses KnowzCode for structured TDD development with quality gates.
+
+## Required Reading
+- `knowzcode/knowzcode_loop.md` — Complete methodology (read first)
+- `knowzcode/knowzcode_project.md` — Project context and tech stack
+- `knowzcode/knowzcode_architecture.md` — Architecture documentation
+- `knowzcode/knowzcode_tracker.md` — WorkGroup status tracking
+
+## Workflow Overview
+
+KnowzCode follows a 5-phase development loop with quality gates between each phase.
+Use the prompt files in `.github/prompts/` to invoke each phase:
+
+| Phase | Prompt | Description |
+|-------|--------|-------------|
+| Full workflow | `#prompt:kc-work` | Start a new feature — creates WorkGroup, classifies tier, runs Phase 1A |
+| 1A: Analysis | `#prompt:kc-analyze` | Re-run impact analysis on existing WorkGroup |
+| 1B: Specification | `#prompt:kc-specify` | Draft specs from approved Change Set |
+| 2A: Implementation | `#prompt:kc-implement` | TDD implementation with verification loop |
+| 2B: Audit | `#prompt:kc-audit` | READ-ONLY audit against specs |
+| 3: Finalization | `#prompt:kc-finalize` | Update specs, tracker, log, commit |
+| Quick fix | `#prompt:kc-fix` | Micro-fix for small, scoped changes |
+| Research | `#prompt:kc-plan` | Investigate before implementing |
+| Resume | `#prompt:kc-continue` | Resume or advance to next phase |
+
+### Typical Flow
+
+1. `#prompt:kc-work "Build JWT authentication"` → Creates WorkGroup, proposes Change Set, **STOPs**
+2. Approve Change Set
+3. `#prompt:kc-specify` → Drafts specs, **STOPs**
+4. Approve specs
+5. `#prompt:kc-implement` → TDD Red-Green-Refactor, **STOPs**
+6. `#prompt:kc-audit` → READ-ONLY audit, reports gaps, **STOPs**
+7. `#prompt:kc-finalize` → Updates docs, commits
+
+Use `#prompt:kc-continue` at any point to resume where you left off.
+
+## Quality Gates
+
+STOP and await user approval at each gate:
+- After Change Set proposal (1A)
+- After spec drafts (1B)
+- After implementation complete (2A — awaiting audit)
+- After audit results (2B — user decides on gaps)
+
+## TDD Enforcement
+
+TDD is mandatory — no production code without a failing test first.
+Follow Red-Green-Refactor for every feature/criterion in the spec.
+
+## Key Rules
+- NodeIDs are domain concepts (PascalCase), not tasks
+- Consolidate specs when domains overlap >50%
+- Every WorkGroup todo starts with `KnowzCode:` prefix
+- Target <20 specs per project
+- Log completions in `knowzcode/knowzcode_log.md`
+
+## Key Files
+- `knowzcode/knowzcode_loop.md` — Methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+- `knowzcode/knowzcode_tracker.md` — WorkGroup tracking
+- `knowzcode/specs/` — Component specifications
+- `knowzcode/workgroups/` — Active session data (gitignored)
+
+## MCP Integration
+
+If configured in `.vscode/mcp.json`, use `search_knowledge` and `ask_question` tools
+for enhanced context from knowledge vaults. All prompts work without MCP.
+
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+## Copilot Coding Agent
+
+When the Copilot Coding Agent works on GitHub issues for this repository:
+- Read `knowzcode/knowzcode_loop.md` and this file for methodology
+- Follow Phase 1A→3 workflow for any non-trivial change
+- Include the Change Set in the PR description
+- Use TDD — failing test before implementation code
+- Self-audit against spec VERIFY statements before marking PR ready
+- Quality gates are deferred to PR review (no interactive approval in async mode)
+
+## Model Selection
+- Complex phases (1A analysis, 1B spec drafting, 2B audit): Use Claude Opus or GPT-4o
+- Implementation (2A): Any capable model with good code generation
+- Quick fixes: Any model
+```
+
+### B. Prompt File Templates (.github/prompts/)
+
+Each prompt file is invocable via `#prompt:kc-*` in VS Code Copilot Chat. All use `agent: "agent"` for file editing capability.
+
+#### kc-work.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Start a new KnowzCode development workflow"
+argument-hint: "Describe the feature or goal to build"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Start Workflow
+
+You are starting a new KnowzCode development workflow. Follow the methodology precisely.
+
+## Context
+
+Read these files for methodology and project context:
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_project.md
+- #file:knowzcode/knowzcode_tracker.md
+- #file:knowzcode/knowzcode_architecture.md
+
+## Instructions
+
+The user's goal is provided in the chat message.
+
+### Step 1: Classify Tier
+
+Based on the goal, classify complexity:
+- **Micro** (single file, <50 lines, no ripple): Redirect to `#prompt:kc-fix`
+- **Light** (≤3 files, straightforward): Streamlined 2-phase path
+- **Full** (>3 files or complex): Complete 5-phase workflow
+
+### Step 2: Create Draft WorkGroup
+
+Generate a WorkGroupID: `kc-{type}-{slug}-YYYYMMDD-HHMMSS`
+Create a draft WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md` to store the analysis output.
+
+### Step 3: Phase 1A — Impact Analysis
+
+Follow Phase 1A from `knowzcode/knowzcode_loop.md`:
+1. Identify the Change Set — all components affected by this change
+2. Create NodeIDs for NEW capabilities only (domain concepts, PascalCase)
+3. Check `knowzcode/specs/` for existing specs with domain overlap
+4. Scan `knowzcode/workgroups/` for completed WorkGroups with relevant context
+5. Propose the Change Set with NodeIDs, affected files, and risk assessment
+
+## STOP
+
+Present the Change Set for user approval. Do NOT proceed until approved.
+
+**After approval:** Update `knowzcode/knowzcode_tracker.md` with new NodeIDs as `[WIP]`, then tell the user to invoke `#prompt:kc-specify` to draft specifications.
+```
+
+#### kc-analyze.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Re-run Phase 1A impact analysis on existing WorkGroup"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Phase 1A — Impact Analysis
+
+You are re-running impact analysis on an existing WorkGroup.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_tracker.md
+
+Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
+Then read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
+
+## Instructions
+
+Follow Phase 1A from `knowzcode/knowzcode_loop.md`:
+1. Re-analyze the goal from the WorkGroup file
+2. Identify all affected components — check for changes since last analysis
+3. Update NodeIDs if scope has changed
+4. Check `knowzcode/specs/` for existing specs with domain overlap
+5. Update the Change Set in the WorkGroup file
+
+## STOP
+
+Present the updated Change Set for user approval.
+
+**Next step after approval:** `#prompt:kc-specify`
+```
+
+#### kc-specify.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Draft specifications from approved Change Set (Phase 1B)"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Phase 1B — Specification
+
+You are drafting specifications for the approved Change Set.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_tracker.md
+
+Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
+If no `[WIP]` entries found, scan `knowzcode/workgroups/` for the most recent draft WorkGroup file.
+Then read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md` for the approved Change Set.
+
+## Instructions
+
+Follow Phase 1B from `knowzcode/knowzcode_loop.md`:
+
+For each NodeID in the approved Change Set:
+1. Draft `knowzcode/specs/{NodeID}.md` using the 4-section format:
+   - **Rules & Decisions** — Key architectural decisions, business rules, constraints
+   - **Interfaces** — Public contracts: inputs, outputs, API signatures, dependencies
+   - **Verification Criteria** — Testable `VERIFY:` assertions (minimum 2 per spec)
+   - **Debt & Gaps** — Known limitations and future work
+2. Minimum valid spec: 1+ Rules, 1+ Interface, 2+ VERIFY statements
+3. Check existing specs — if >50% domain overlap, UPDATE existing spec instead
+4. Update the WorkGroup file with spec status
+
+## STOP
+
+Present all drafted specs for user approval. Do NOT proceed until approved.
+
+**After approval:** Commit the specs as a pre-implementation checkpoint: `git commit -m "specs: draft specs for {WorkGroupID}"`
+
+**Next step:** `#prompt:kc-implement`
+```
+
+#### kc-implement.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "TDD implementation with verification loop (Phase 2A)"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Phase 2A — Implementation
+
+You are implementing the approved specifications using strict TDD.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_tracker.md
+
+Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
+Then read:
+- The WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`
+- All spec files listed in the Change Set from `knowzcode/specs/`
+
+## Instructions
+
+Follow Phase 2A from `knowzcode/knowzcode_loop.md`:
+
+For EACH feature/criterion in the specs:
+1. **RED**: Write a failing test that defines expected behavior. Run test → confirm FAIL
+2. **GREEN**: Write MINIMAL code to make the test pass. Run test → confirm PASS
+3. **REFACTOR**: Clean up while keeping all tests green
+
+### Verification Loop (must pass before reporting complete)
+
+1. Run all tests → if FAIL: fix and restart
+2. Run static analysis → if issues: fix and restart
+3. Run build → if FAIL: fix and restart
+4. Verify all VERIFY: criteria from specs → if unmet: implement and restart
+5. All checks pass → report complete
+
+Maximum 10 iterations. If exceeded, report blocker.
+
+### Spec Issues
+
+If you discover a spec is incorrect during implementation:
+- Tag `[SPEC_ISSUE]` in the WorkGroup file with details
+- Continue with best judgment
+- Report in completion summary
+
+## STOP
+
+Report implementation results: test counts, verification iterations, criteria status.
+
+**Next step:** `#prompt:kc-audit`
+```
+
+#### kc-audit.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "READ-ONLY completeness audit against specs (Phase 2B)"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Phase 2B — Completeness Audit
+
+You are performing an independent, READ-ONLY audit of the implementation.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_tracker.md
+
+Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
+Then read:
+- The WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`
+- All spec files listed in the Change Set from `knowzcode/specs/`
+- The implementation files listed in the Change Set
+
+## Instructions
+
+Follow Phase 2B from `knowzcode/knowzcode_loop.md`:
+
+**CRITICAL: This is a READ-ONLY audit. Do NOT modify any source files.**
+
+1. For each NodeID, compare implementation against every VERIFY statement in its spec
+2. Calculate objective completion percentage per NodeID and overall
+3. Identify gaps: missing features, incomplete criteria, untested paths
+4. Check for security concerns: input validation, authentication, data exposure
+5. Check for orphan code: implementation not covered by any spec
+6. Assess risk for any gaps found
+
+### Standalone Audit Types
+
+If the user specifies an audit type instead of a WorkGroup audit:
+- **spec**: Audit spec quality — completeness, VERIFY statement coverage, format compliance
+- **architecture**: Compare architecture doc against actual codebase structure
+- **security**: Focused security review — OWASP top 10, input validation, auth flows
+- **integration**: Check integration points, API contracts, dependency health
+
+## STOP
+
+Present audit results with completion percentage, gap list, and risk assessment.
+
+**User decides:**
+- Return to `#prompt:kc-implement` to fix gaps
+- Accept and proceed to `#prompt:kc-finalize`
+- Modify specs to match implementation
+- Cancel the WorkGroup
+```
+
+#### kc-finalize.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Finalize WorkGroup — update specs, tracker, log, commit (Phase 3)"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Phase 3 — Finalization
+
+You are finalizing the WorkGroup after approved implementation and audit.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_tracker.md
+- #file:knowzcode/knowzcode_architecture.md
+
+Read `knowzcode/knowzcode_tracker.md` to find the active `[WIP]` WorkGroup.
+Then read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
+
+## Instructions
+
+Follow Phase 3 from `knowzcode/knowzcode_loop.md`:
+
+1. **Finalize Specs**: Update each `knowzcode/specs/{NodeID}.md` to as-built state (Status: As-Built)
+2. **Architecture Check**: Compare `knowzcode/knowzcode_architecture.md` against the Change Set. Fix simple discrepancies directly; document complex ones for user review
+3. **Log Entry**: Prepend an `ARC-Completion` entry to `knowzcode/knowzcode_log.md` with WorkGroupID, NodeIDs, verification summary, architectural learnings, and ripple effects
+4. **Update Tracker**: Change NodeID statuses from `[WIP]` to `[VERIFIED]` in `knowzcode/knowzcode_tracker.md`. Create `REFACTOR_` tasks for significant tech debt
+5. **Final Commit**: Stage and commit all changes (source + knowzcode files)
+6. **Close WorkGroup**: Mark the WorkGroup file as closed
+
+## Output
+
+Report completion with summary of what was delivered and any `REFACTOR_` tasks created.
+```
+
+#### kc-fix.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Quick targeted fix using micro-fix protocol"
+argument-hint: "Describe the bug or issue to fix"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Micro-Fix
+
+You are performing a quick, targeted fix using the micro-fix protocol.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+
+## 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, inform the user and suggest `#prompt:kc-work` instead.
+
+## Instructions
+
+Follow the Micro-Fix Protocol from `knowzcode/knowzcode_loop.md` Section 4:
+
+1. **Implement** the fix
+2. **Test** — run targeted tests for the affected code
+3. **Log** — prepend a `MicroFix` entry to `knowzcode/knowzcode_log.md`:
+   - Type: MicroFix
+   - File/NodeID affected
+   - User request, action taken, verification outcome
+4. **Commit** with `fix: {description}` message
+```
+
+#### kc-plan.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Research and investigate before implementing"
+argument-hint: "Describe the topic to research"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Plan / Investigate
+
+You are researching a topic before implementation. This is an investigation workflow, not a build workflow.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_project.md
+- #file:knowzcode/knowzcode_architecture.md
+
+## Instructions
+
+The user's research topic is provided in the chat message.
+
+1. **Explore the codebase** — search for relevant files, patterns, and existing implementations
+2. **Read existing specs** — check `knowzcode/specs/` for related components
+3. **Check history** — scan `knowzcode/workgroups/` for past WorkGroups that touched similar areas
+4. **Analyze architecture** — review `knowzcode/knowzcode_architecture.md` for structural context
+5. **Present findings** with:
+   - Current state of the relevant code
+   - Existing patterns and conventions
+   - Options for implementation (with trade-offs)
+   - Recommended approach
+
+## STOP
+
+Present research findings and recommendations.
+
+**To implement:** Tell the user to invoke `#prompt:kc-work` with their chosen approach.
+```
+
+#### kc-continue.prompt.md
+
+```markdown
+---
+agent: "agent"
+description: "Resume interrupted work or advance to next phase"
+---
+
+<!-- Generated by KnowzCode vX.Y.Z /kc:init -->
+
+# KnowzCode: Continue / Resume
+
+You are resuming an interrupted KnowzCode workflow or advancing to the next phase.
+
+## Context
+
+- #file:knowzcode/knowzcode_loop.md
+- #file:knowzcode/knowzcode_tracker.md
+
+## Instructions
+
+### Step 1: Find Active WorkGroup
+
+Read `knowzcode/knowzcode_tracker.md` and find entries with `[WIP]` status.
+
+- **One active WorkGroup**: Use it
+- **Multiple active**: Present the list and ask the user which to resume
+- **None active**: Inform the user and suggest `#prompt:kc-work`
+
+### Step 2: Determine Current Phase
+
+Read the WorkGroup file at `knowzcode/workgroups/{WorkGroupID}.md`.
+Check the Phase History table to determine the current state.
+
+### Step 3: Resume or Advance
+
+| WorkGroup State | Action |
+|----------------|--------|
+| Phase 1A in progress | Complete the impact analysis, present Change Set |
+| Phase 1A complete, awaiting approval | Present Change Set for approval |
+| Phase 1A approved, specs not started | Begin Phase 1B — draft specs |
+| Phase 1B in progress | Complete spec drafting |
+| Phase 1B complete, awaiting approval | Present specs for approval |
+| Phase 1B approved, implementation not started | Begin Phase 2A — TDD implementation |
+| Phase 2A in progress | Resume implementation from outstanding todos |
+| Phase 2A complete | Advise: `#prompt:kc-audit` |
+| Phase 2B complete, gaps found | Present options: fix gaps or accept |
+| Phase 2B complete, no gaps | Begin Phase 3 — finalization |
+| Phase 3 in progress | Complete finalization |
+
+### Step 4: Present Status
+
+```
+## Resuming WorkGroup: {WorkGroupID}
+
+**Goal**: {primary goal}
+**Phase**: {current phase}
+**NodeIDs**: {list}
+
+**Outstanding Work**:
+{list from WorkGroup file}
+
+Continuing from where we left off...
+```
+
+Then proceed with the appropriate phase instructions from `knowzcode/knowzcode_loop.md`.
+```
+
+### C. .vscode/mcp.json Template
+
+Optionally generated by `/kc:init` when Copilot is detected and MCP is configured:
+
+```json
+{
+  "servers": {
+    "knowz": {
+      "type": "http",
+      "url": "${input:knowz_mcp_url}",
+      "headers": {
+        "x-api-key": "${input:knowz_api_key}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "knowz_mcp_url",
+      "description": "KnowzCode MCP server URL",
+      "type": "promptString"
+    },
+    {
+      "id": "knowz_api_key",
+      "description": "KnowzCode API key",
+      "type": "promptString",
+      "password": true
+    }
+  ]
+}
+```
+
+### D. Copilot-Specific Notes
+
+**VS Code usage:**
+- Invoke prompts via `#prompt:kc-work`, `#prompt:kc-specify`, etc. in Copilot Chat
+- Add extra files to context with `#file:path/to/file` in the chat message
+- All prompt files use `agent: "agent"` frontmatter for file editing and terminal access
+- Model can be selected per session — prefer stronger models for analysis/audit phases
+
+**Copilot CLI fallback:**
+- CLI does not support `#prompt:` syntax
+- 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
+- Does not use prompt files (uses repository instructions only)
+
+**Execution model:**
+- See `knowzcode/copilot_execution.md` for the full execution guide
+- Single-agent, sequential execution — user manually transitions between phases
+- No multi-agent orchestration (no Parallel Teams, no agent spawning)
+- WorkGroup files carry state between prompt invocations
+
+---
+
+## Windsurf (`.windsurf/rules/knowzcode.md`)
+
+Create `.windsurf/rules/knowzcode.md`. Notes: Modern Windsurf uses the `.windsurf/rules/` directory instead of the deprecated `.windsurfrules` file. Cascade multi-file editing works well with KnowzCode's cross-component implementation phases. Windsurf also supports `.windsurf/workflows/*.md` for custom commands invoked as `/workflow-name` — KnowzCode workflows can be defined as individual workflow files for each phase.
+
+```markdown
+# KnowzCode Development Methodology
+
+This project uses KnowzCode for structured TDD development.
+Follow `knowzcode/knowzcode_loop.md` for all feature development.
+
+## Required Reading
+- `knowzcode/knowzcode_loop.md` — Complete methodology
+- `knowzcode/knowzcode_project.md` — Project context
+- `knowzcode/knowzcode_tracker.md` — Active WorkGroups
+- `knowzcode/knowzcode_architecture.md` — Architecture docs
+
+## Phase Walkthrough
+
+### Phase 1A: Impact Analysis
+- Identify affected components, propose Change Set with NodeIDs
+- Check existing specs before creating new ones
+- PAUSE for user approval
+
+### Phase 1B: Specification
+- Draft specs with 4-section format and 2+ VERIFY statements
+- PAUSE for approval, then commit specs
+
+### Phase 2A: Implementation (TDD Mandatory)
+- Write failing test FIRST, then minimal code, then refactor
+- Use Cascade for multi-file edits across components
+- Run full verification loop (tests + linter + build)
+- PAUSE after implementation
+
+### Phase 2B: Audit
+- READ-ONLY audit against spec VERIFY statements
+- Report completion %, gaps, security concerns
+- PAUSE for user decision
+
+### Phase 3: Finalization
+- Update specs to As-Built, tracker, log, architecture
+- Final commit
+
+## Enforcement Rules
+- TDD is mandatory — write failing tests before implementation code
+- Respect quality gates between phases — PAUSE at each gate
+- Update `knowzcode/knowzcode_tracker.md` when completing work
+- Log completions in `knowzcode/knowzcode_log.md`
+- Consolidate specs when domains overlap >50%
+- Target <20 specs per project
+- Every WorkGroup todo starts with `KnowzCode:` prefix
+
+## 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 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
+```
+
+---
+
+## OpenAI Codex Agents SDK (Python)
+
+For teams building custom orchestration with the OpenAI Agents SDK,
+map KnowzCode's 5 phase agents to SDK Agent definitions. The AGENTS.md
+file above provides all instructions each agent needs. See the
+[Agents SDK documentation](https://openai.github.io/openai-agents-python/)
+for implementation details.