knowzcode 0.1.0 → 0.3.1

package/knowzcode/platform_adapters.md

@@ -68,7 +68,7 @@ All commands work without MCP — it enhances but never blocks.
 
 ## 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).
+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
@@ -152,6 +152,45 @@ For single-file, <50 line, no-ripple-effect changes:
 
 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
 
@@ -212,7 +251,7 @@ Single file, <50 lines, no ripple effects:
 
 ## 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.
+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
 ---
@@ -274,56 +313,618 @@ Before any feature work, read:
 
 ---
 
-## GitHub Copilot (.github/copilot-instructions.md)
+## 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` for repository-level instructions. Notes: GitHub Copilot also supports scoped instructions via `*.instructions.md` files with `applyTo` YAML frontmatter (e.g., `knowzcode.instructions.md` with `applyTo: "knowzcode/**"` to scope KnowzCode methodology to the framework directory).
+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.
+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 |
 
-## Key Constraint: TDD is Mandatory
-- Write failing tests BEFORE implementation code
-- Follow Red-Green-Refactor cycle for every feature
-- No production code without corresponding test coverage
+### Typical Flow
 
-## Workflow
-Reference `knowzcode/knowzcode_loop.md` for the complete development workflow.
-Follow these phases for all feature work:
+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
 
-1. **Impact Analysis** — Propose a Change Set, get user approval
-2. **Specification** — Draft specs with VERIFY statements, get user approval
-3. **Implementation** — Strict TDD, verification loop
-4. **Audit** — READ-ONLY comparison against specs
-5. **Finalization** — Update docs, tracker, log, commit
+Use `#prompt:kc-continue` at any point to resume where you left off.
 
 ## Quality Gates
-STOP and get user approval:
-- After Change Set proposal
-- After spec drafts
-- After implementation (awaiting audit)
-- After audit results (user decides on gaps)
+
+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 (read first)
+- `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)
 
-## Rules
-- NodeIDs are domain concepts (PascalCase), not tasks
-- Consolidate specs when domains overlap >50%
-- Every WorkGroup todo starts with `KnowzCode:` prefix
-- Log completions in `knowzcode/knowzcode_log.md`
+## MCP Integration (Optional)
+
+If configured in `.vscode/mcp.json`, use `search_knowledge` and `ask_question` tools
+for enhanced context from knowledge vaults. All prompts work without MCP.
+
+## 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": {
+    "knowzcode": {
+      "type": "http",
+      "url": "${input:knowzcode_mcp_url}",
+      "headers": {
+        "x-api-key": "${input:knowzcode_api_key}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "knowzcode_mcp_url",
+      "description": "KnowzCode MCP server URL",
+      "type": "promptString"
+    },
+    {
+      "id": "knowzcode_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.
+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