knowzcode 0.3.6 → 0.4.0

package/knowzcode/platform_adapters.md

@@ -1,1047 +1,1260 @@
-# 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)
-```
-
----
-
-## 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/>"""
-```
-
-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 — 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.