knowzcode 0.2.1 → 0.3.1

package/knowzcode/copilot_execution.md

@@ -0,0 +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` |

package/knowzcode/enterprise/compliance_manifest.md

@@ -112,6 +112,9 @@ When `mcp_compliance_enabled: true`:
 | analyst | create_knowledge | After 1A approval | Scope decisions, risk assessment |
 | reviewer | create_knowledge | After 2B audit | Audit findings, security posture |
 | closer | create_knowledge | After Phase 3 | Completion record, architecture changes |
+| security-officer | search_knowledge | Stage 0, Stage 2 | Organization security standards, past security findings |
+| test-advisor | (read-only) | Stage 2 | Enterprise ARC criteria for test coverage check |
+| project-advisor | (read-only) | Stage 0 | Compliance config gaps for backlog proposals |
 
 ---
 

package/knowzcode/knowzcode_loop.md

@@ -446,7 +446,9 @@ Both broadcast findings to inform analyst and architect work.
 
 ### Sequential Execution Protocol (for platforms without orchestration)
 
-For platforms like Cursor, Copilot, or Windsurf where there is no agent orchestration:
+For platforms like Cursor, Copilot, or Windsurf where there is no agent orchestration.
+
+**Copilot users:** Instead of manually reading phase prompts, use `#prompt:kc-*` prompt files in VS Code Copilot Chat (e.g., `#prompt:kc-work`, `#prompt:kc-specify`). These prompt files encode the sequential protocol below with `#file:` references for context. See `knowzcode/copilot_execution.md` for the full Copilot execution guide.
 
 ```
 FOR each phase in [1A, 1B, 2A, 2B, 3]:

package/knowzcode/knowzcode_orchestration.md

@@ -0,0 +1,66 @@
+# KnowzCode Orchestration Configuration
+
+**Purpose:** Project-level defaults for team sizing and agent orchestration. Read by `/kc:work` and `/kc:audit` at startup. Per-invocation flags override these settings.
+
+---
+
+## Builder Configuration
+
+```yaml
+# Maximum concurrent builders in Parallel Teams mode (default: 5, range: 1-5)
+# Lower values reduce token usage and complexity; higher values increase parallelism.
+# If the dependency map produces fewer partitions, fewer builders spawn regardless.
+max_builders: 5
+```
+
+---
+
+## Scout Configuration
+
+```yaml
+# Scout mode controls context-scout spawning at Stage 0 (default: full)
+#   full    — 3 scouts: specs, workgroups, backlog (default)
+#   minimal — 1 scout: combined scan of all local context
+#   none    — skip scouts entirely (lead loads context inline)
+scout_mode: full
+```
+
+---
+
+## Specialist Defaults
+
+```yaml
+# Specialists enabled by default for this project (default: none)
+# These activate without needing --specialists on every invocation.
+# Per-invocation --no-specialists overrides this setting.
+# Values: security-officer, test-advisor, project-advisor
+default_specialists: []
+
+# Examples:
+# default_specialists: [security-officer]
+# default_specialists: [security-officer, test-advisor]
+# default_specialists: [security-officer, test-advisor, project-advisor]
+```
+
+---
+
+## MCP Agent Configuration
+
+```yaml
+# Enable MCP agents (knowz-scout, knowz-scribe) when vaults are configured (default: true)
+# Set to false to skip vault agents even when vaults exist — reduces agent count.
+mcp_agents_enabled: true
+```
+
+---
+
+## Override Precedence
+
+| Setting | Config Default | Flag Override |
+|---------|---------------|--------------|
+| max_builders | `max_builders:` | `--max-builders=N` |
+| scout_mode | `scout_mode:` | `--no-scouts` |
+| default_specialists | `default_specialists:` | `--specialists`, `--no-specialists` |
+| mcp_agents_enabled | `mcp_agents_enabled:` | `--no-mcp` |
+
+Per-invocation flags always win. `--specialists` adds to defaults; `--no-specialists` clears all.