knowzcode 0.4.0 → 0.5.2

package/knowzcode/copilot_execution.md

@@ -1,231 +1,231 @@
-# Copilot Execution Model
-
-**Purpose:** Defines the execution model for GitHub Copilot users. Copilot operates as a single-agent, sequential platform — users manually transition between phases using prompt files.
-
-Agents on other platforms should ignore this file — see `knowzcode/platform_adapters.md` for platform-specific instructions, or `knowzcode/claude_code_execution.md` for Claude Code Agent Teams.
-
----
-
-## Execution Model Overview
-
-Copilot uses a **single-agent, user-driven** execution model:
-
-- One AI assistant handles all phases sequentially
-- The user invokes each phase via `#prompt:kc-*` prompt files in VS Code
-- Quality gates are enforced by STOP instructions — the AI pauses and waits for user direction
-- Context carries between phases via WorkGroup files in `knowzcode/workgroups/`
-- No multi-agent orchestration, no inter-agent messaging, no task dependency tracking
-
-This is equivalent to the "Sequential Execution Protocol" described in `knowzcode/knowzcode_loop.md` Section 8.
-
----
-
-## Prompt File Workflow
-
-### Phase Sequence
-
-```
-#prompt:kc-work "goal"
-  → Creates WorkGroup, classifies tier, Phase 1A analysis, proposes Change Set
-  → STOP — await user approval
-
-#prompt:kc-specify
-  → Reads WorkGroup, drafts specs for approved Change Set
-  → STOP — await user approval, then commits specs
-
-#prompt:kc-implement
-  → Reads WorkGroup + specs, TDD Red-Green-Refactor
-  → STOP — report implementation results
-
-#prompt:kc-audit
-  → READ-ONLY audit against VERIFY statements
-  → STOP — report gaps, await user decision
-
-#prompt:kc-finalize
-  → Updates specs to as-built, tracker, log, architecture check, commits
-```
-
-### Shortcut Workflows
-
-| Prompt | Use Case |
-|--------|----------|
-| `#prompt:kc-fix "description"` | Single-file, <50 line fixes — skip the full loop |
-| `#prompt:kc-plan "topic"` | Research and investigation before implementing |
-| `#prompt:kc-continue` | Resume interrupted work or advance to next phase |
-| `#prompt:kc-analyze` | Re-run Phase 1A on an existing WorkGroup |
-
-### Prompt File Location
-
-All prompt files live in `.github/prompts/` and are generated by `/kc:init` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.
-
----
-
-## VS Code Agent Mode
-
-Copilot prompt files with `agent: "agent"` in their frontmatter enable agent mode, which allows:
-
-- File creation and editing
-- Terminal command execution (tests, builds, linting)
-- Multi-file changes in a single session
-
-All KnowzCode prompt files use `agent: "agent"` for TDD implementation, spec writing, and WorkGroup file updates.
-
-### Using Prompt Files
-
-In VS Code Copilot Chat:
-1. Type `#prompt:kc-work` to invoke the workflow prompt
-2. Add your goal as the chat message: `#prompt:kc-work "Build JWT authentication"`
-3. Copilot loads the prompt file, pulls in `#file:` referenced context, and executes
-
-### Adding Extra Context
-
-You can add files to the prompt context manually:
-- Reference files in chat: `#file:src/auth/login.ts`
-- The prompt files already include `#file:` references for core KnowzCode files
-
----
-
-## Copilot CLI Usage
-
-The Copilot CLI does not support `#prompt:` syntax. Check the current CLI documentation for the exact file reference syntax — it may differ from VS Code's `#file:` references.
-
-Alternatively, paste the goal and reference the methodology directly in the CLI prompt. The CLI provides the same AI capabilities but without the `#prompt:` shorthand.
-
----
-
-## Copilot Coding Agent Integration
-
-The GitHub Copilot Coding Agent (cloud-based, triggered from GitHub Issues) follows `copilot-instructions.md` automatically when working on repository issues.
-
-### Behavior
-
-When the Coding Agent picks up an issue:
-1. Reads `.github/copilot-instructions.md` for methodology
-2. Follows Phase 1A→3 workflow for non-trivial changes
-3. Includes the Change Set in the PR description
-4. Uses TDD — failing test before implementation code
-5. Self-audits against spec VERIFY statements
-
-### Key Differences from Interactive Use
-
-| Aspect | Interactive (VS Code) | Coding Agent (GitHub) |
-|--------|----------------------|----------------------|
-| Phase transitions | User invokes each `#prompt:kc-*` | Agent runs all phases autonomously |
-| Quality gates | STOP and wait for user | Deferred to PR review |
-| Prompt files | Used via `#prompt:` | Not used — follows `copilot-instructions.md` |
-| Approval | Interactive at each gate | PR reviewers approve |
-
-### PR Description Format
-
-The Coding Agent should structure PR descriptions to reflect the KnowzCode workflow:
-
-```markdown
-## Change Set
-- NodeID: Description
-- Affected files: list
-
-## Specs
-- Link to spec files created/updated
-
-## Verification
-- Test results summary
-- Self-audit completion percentage
-```
-
----
-
-## MCP Configuration for VS Code
-
-To enable vault access in Copilot, configure `.vscode/mcp.json`:
-
-```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
-    }
-  ]
-}
-```
-
-MCP provides `search_knowledge`, `ask_question`, and `create_knowledge` tools for vault access. All prompt files work without MCP — it enhances context but never blocks.
-
----
-
-## Model Selection Guidance
-
-| Phase | Recommended Model | Rationale |
-|-------|------------------|-----------|
-| 1A: Analysis | Claude Opus / GPT-4o | Complex reasoning about impact and scope |
-| 1B: Specification | Claude Opus / GPT-4o | Structured spec drafting requires depth |
-| 2A: Implementation | Any capable model | Code generation — Sonnet/GPT-4o sufficient |
-| 2B: Audit | Claude Opus / GPT-4o | Critical evaluation requires strong reasoning |
-| 3: Finalization | Any capable model | Mostly doc updates and formatting |
-| Quick fix | Any model | Simple, scoped changes |
-
-VS Code allows model selection per chat session. For complex features, prefer stronger models for analysis and audit phases.
-
----
-
-## Limitations and Workarounds
-
-| Limitation | Impact | Workaround |
-|-----------|--------|------------|
-| No multi-agent orchestration | Cannot run parallel analysis/implementation | Sequential phase execution via prompt files |
-| No inter-agent messaging | No scout/scribe delegation | Single agent reads all context directly |
-| No task dependency tracking | No automated phase progression | User manually invokes next prompt |
-| No persistent agents | Context reloaded each prompt invocation | WorkGroup files carry state between invocations |
-| No dynamic agent spawning | Cannot create specialized agents at runtime | Prompt files encode all phase specialization |
-| CLI lacks `#prompt:` support | Cannot use prompt shorthand in CLI | Check CLI docs for file reference syntax, or paste prompt content |
-
-### What Works Well
-
-- Agent mode provides full file editing and terminal access
-- `#file:` references efficiently pull in methodology and context
-- WorkGroup files maintain state across sessions
-- Copilot Coding Agent follows `copilot-instructions.md` for autonomous issue resolution
-- MCP tools integrate natively via `.vscode/mcp.json`
-
----
-
-## Continue / Resume Workflow
-
-When a user invokes `#prompt:kc-continue`:
-
-1. **Find active WorkGroup**: Read `knowzcode/knowzcode_tracker.md` for `[WIP]` entries
-2. **Determine current phase**: Read the WorkGroup file's Phase History table
-3. **Resume or advance**:
-   - If mid-phase (incomplete todos): Resume the current phase
-   - If at a quality gate (phase complete, awaiting approval): Present results and await decision
-   - If between phases (approved, next not started): Begin the next phase
-4. **Guide user**: Tell the user which `#prompt:kc-*` to invoke next, or proceed directly if the continue prompt can handle it
-
-### Phase Detection Logic
-
-| WorkGroup State | Action |
-|----------------|--------|
-| Phase 1A complete, no approval recorded | Present Change Set for approval |
-| Phase 1A approved, no specs drafted | Advise: `#prompt:kc-specify` |
-| Phase 1B complete, no approval recorded | Present specs for approval |
-| Phase 1B approved, no implementation started | Advise: `#prompt:kc-implement` |
-| Phase 2A complete | Advise: `#prompt:kc-audit` |
-| Phase 2B complete, gaps found | Advise: fix gaps then `#prompt:kc-implement`, or `#prompt:kc-finalize` to accept |
-| Phase 2B complete, no gaps | Advise: `#prompt:kc-finalize` |
-| No active WorkGroup | Inform user, suggest `#prompt:kc-work` |
+# Copilot Execution Model
+
+**Purpose:** Defines the execution model for GitHub Copilot users. Copilot operates as a single-agent, sequential platform — users manually transition between phases using prompt files.
+
+Agents on other platforms should ignore this file — see `knowzcode/platform_adapters.md` for platform-specific instructions, or `knowzcode/claude_code_execution.md` for Claude Code Agent Teams.
+
+---
+
+## Execution Model Overview
+
+Copilot uses a **single-agent, user-driven** execution model:
+
+- One AI assistant handles all phases sequentially
+- The user invokes each phase via `#prompt:kc-*` prompt files in VS Code
+- Quality gates are enforced by STOP instructions — the AI pauses and waits for user direction
+- Context carries between phases via WorkGroup files in `knowzcode/workgroups/`
+- No multi-agent orchestration, no inter-agent messaging, no task dependency tracking
+
+This is equivalent to the "Sequential Execution Protocol" described in `knowzcode/knowzcode_loop.md` Section 8.
+
+---
+
+## Prompt File Workflow
+
+### Phase Sequence
+
+```
+#prompt:kc-work "goal"
+  → Creates WorkGroup, classifies tier, Phase 1A analysis, proposes Change Set
+  → STOP — await user approval
+
+#prompt:kc-specify
+  → Reads WorkGroup, drafts specs for approved Change Set
+  → STOP — await user approval, then commits specs
+
+#prompt:kc-implement
+  → Reads WorkGroup + specs, TDD Red-Green-Refactor
+  → STOP — report implementation results
+
+#prompt:kc-audit
+  → READ-ONLY audit against VERIFY statements
+  → STOP — report gaps, await user decision
+
+#prompt:kc-finalize
+  → Updates specs to as-built, tracker, log, architecture check, commits
+```
+
+### Shortcut Workflows
+
+| Prompt | Use Case |
+|--------|----------|
+| `#prompt:kc-fix "description"` | Single-file, <50 line fixes — skip the full loop |
+| `#prompt:kc-plan "topic"` | Research and investigation before implementing |
+| `#prompt:kc-continue` | Resume interrupted work or advance to next phase |
+| `#prompt:kc-analyze` | Re-run Phase 1A on an existing WorkGroup |
+
+### Prompt File Location
+
+All prompt files live in `.github/prompts/` and are generated by `/kc:init` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.
+
+---
+
+## VS Code Agent Mode
+
+Copilot prompt files with `agent: "agent"` in their frontmatter enable agent mode, which allows:
+
+- File creation and editing
+- Terminal command execution (tests, builds, linting)
+- Multi-file changes in a single session
+
+All KnowzCode prompt files use `agent: "agent"` for TDD implementation, spec writing, and WorkGroup file updates.
+
+### Using Prompt Files
+
+In VS Code Copilot Chat:
+1. Type `#prompt:kc-work` to invoke the workflow prompt
+2. Add your goal as the chat message: `#prompt:kc-work "Build JWT authentication"`
+3. Copilot loads the prompt file, pulls in `#file:` referenced context, and executes
+
+### Adding Extra Context
+
+You can add files to the prompt context manually:
+- Reference files in chat: `#file:src/auth/login.ts`
+- The prompt files already include `#file:` references for core KnowzCode files
+
+---
+
+## Copilot CLI Usage
+
+The Copilot CLI does not support `#prompt:` syntax. Check the current CLI documentation for the exact file reference syntax — it may differ from VS Code's `#file:` references.
+
+Alternatively, paste the goal and reference the methodology directly in the CLI prompt. The CLI provides the same AI capabilities but without the `#prompt:` shorthand.
+
+---
+
+## Copilot Coding Agent Integration
+
+The GitHub Copilot Coding Agent (cloud-based, triggered from GitHub Issues) follows `copilot-instructions.md` automatically when working on repository issues.
+
+### Behavior
+
+When the Coding Agent picks up an issue:
+1. Reads `.github/copilot-instructions.md` for methodology
+2. Follows Phase 1A→3 workflow for non-trivial changes
+3. Includes the Change Set in the PR description
+4. Uses TDD — failing test before implementation code
+5. Self-audits against spec VERIFY statements
+
+### Key Differences from Interactive Use
+
+| Aspect | Interactive (VS Code) | Coding Agent (GitHub) |
+|--------|----------------------|----------------------|
+| Phase transitions | User invokes each `#prompt:kc-*` | Agent runs all phases autonomously |
+| Quality gates | STOP and wait for user | Deferred to PR review |
+| Prompt files | Used via `#prompt:` | Not used — follows `copilot-instructions.md` |
+| Approval | Interactive at each gate | PR reviewers approve |
+
+### PR Description Format
+
+The Coding Agent should structure PR descriptions to reflect the KnowzCode workflow:
+
+```markdown
+## Change Set
+- NodeID: Description
+- Affected files: list
+
+## Specs
+- Link to spec files created/updated
+
+## Verification
+- Test results summary
+- Self-audit completion percentage
+```
+
+---
+
+## MCP Configuration for VS Code
+
+To enable vault access in Copilot, configure `.vscode/mcp.json`:
+
+```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
+    }
+  ]
+}
+```
+
+MCP provides `search_knowledge`, `ask_question`, and `create_knowledge` tools for vault access. All prompt files work without MCP — it enhances context but never blocks.
+
+---
+
+## Model Selection Guidance
+
+| Phase | Recommended Model | Rationale |
+|-------|------------------|-----------|
+| 1A: Analysis | Claude Opus / GPT-4o | Complex reasoning about impact and scope |
+| 1B: Specification | Claude Opus / GPT-4o | Structured spec drafting requires depth |
+| 2A: Implementation | Any capable model | Code generation — Sonnet/GPT-4o sufficient |
+| 2B: Audit | Claude Opus / GPT-4o | Critical evaluation requires strong reasoning |
+| 3: Finalization | Any capable model | Mostly doc updates and formatting |
+| Quick fix | Any model | Simple, scoped changes |
+
+VS Code allows model selection per chat session. For complex features, prefer stronger models for analysis and audit phases.
+
+---
+
+## Limitations and Workarounds
+
+| Limitation | Impact | Workaround |
+|-----------|--------|------------|
+| No multi-agent orchestration | Cannot run parallel analysis/implementation | Sequential phase execution via prompt files |
+| No inter-agent messaging | No scout/scribe delegation | Single agent reads all context directly |
+| No task dependency tracking | No automated phase progression | User manually invokes next prompt |
+| No persistent agents | Context reloaded each prompt invocation | WorkGroup files carry state between invocations |
+| No dynamic agent spawning | Cannot create specialized agents at runtime | Prompt files encode all phase specialization |
+| CLI lacks `#prompt:` support | Cannot use prompt shorthand in CLI | Check CLI docs for file reference syntax, or paste prompt content |
+
+### What Works Well
+
+- Agent mode provides full file editing and terminal access
+- `#file:` references efficiently pull in methodology and context
+- WorkGroup files maintain state across sessions
+- Copilot Coding Agent follows `copilot-instructions.md` for autonomous issue resolution
+- MCP tools integrate natively via `.vscode/mcp.json`
+
+---
+
+## Continue / Resume Workflow
+
+When a user invokes `#prompt:kc-continue`:
+
+1. **Find active WorkGroup**: Read `knowzcode/knowzcode_tracker.md` for `[WIP]` entries
+2. **Determine current phase**: Read the WorkGroup file's Phase History table
+3. **Resume or advance**:
+   - If mid-phase (incomplete todos): Resume the current phase
+   - If at a quality gate (phase complete, awaiting approval): Present results and await decision
+   - If between phases (approved, next not started): Begin the next phase
+4. **Guide user**: Tell the user which `#prompt:kc-*` to invoke next, or proceed directly if the continue prompt can handle it
+
+### Phase Detection Logic
+
+| WorkGroup State | Action |
+|----------------|--------|
+| Phase 1A complete, no approval recorded | Present Change Set for approval |
+| Phase 1A approved, no specs drafted | Advise: `#prompt:kc-specify` |
+| Phase 1B complete, no approval recorded | Present specs for approval |
+| Phase 1B approved, no implementation started | Advise: `#prompt:kc-implement` |
+| Phase 2A complete | Advise: `#prompt:kc-audit` |
+| Phase 2B complete, gaps found | Advise: fix gaps then `#prompt:kc-implement`, or `#prompt:kc-finalize` to accept |
+| Phase 2B complete, no gaps | Advise: `#prompt:kc-finalize` |
+| No active WorkGroup | Inform user, suggest `#prompt:kc-work` |