# 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:knowzcode-*` 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:knowzcode-work "goal"
  → Creates WorkGroup, classifies tier, Phase 1A analysis, proposes Change Set
  → STOP — await user approval

#prompt:knowzcode-specify
  → Reads WorkGroup, drafts specs for approved Change Set
  → STOP — await user approval, then commits specs

#prompt:knowzcode-implement
  → Reads WorkGroup + specs, TDD Red-Green-Refactor
  → STOP — report implementation results

#prompt:knowzcode-audit
  → READ-ONLY audit against VERIFY statements
  → STOP — report gaps, await user decision

#prompt:knowzcode-finalize
  → Updates specs to as-built, tracker, log, architecture check, commits
```

### Shortcut Workflows

| Prompt | Use Case |
|--------|----------|
| `#prompt:knowzcode-fix "description"` | Single-file, <50 line fixes — skip the full loop |
| `#prompt:knowzcode-explore "topic"` | Research, investigation, or planning before implementing |
| `#prompt:knowzcode-continue` | Resume interrupted work or advance to next phase |
| `#prompt:knowzcode-analyze` | Re-run Phase 1A on an existing WorkGroup |

### Prompt File Location

All prompt files live in `.github/prompts/` and are generated by `/knowzcode:setup` (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:knowzcode-work` to invoke the workflow prompt
2. Add your goal as the chat message: `#prompt:knowzcode-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:knowzcode-*` | 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 liaison/vault 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:knowzcode-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:knowzcode-*` 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:knowzcode-specify` |
| Phase 1B complete, no approval recorded | Present specs for approval |
| Phase 1B approved, no implementation started | Advise: `#prompt:knowzcode-implement` |
| Phase 2A complete | Advise: `#prompt:knowzcode-audit` |
| Phase 2B complete, gaps found | Advise: fix gaps then `#prompt:knowzcode-implement`, or `#prompt:knowzcode-finalize` to accept |
| Phase 2B complete, no gaps | Advise: `#prompt:knowzcode-finalize` |
| No active WorkGroup | Inform user, suggest `#prompt:knowzcode-work` |