knowzcode 0.1.0 → 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

@@ -1,5 +1,7 @@
 # Enterprise Compliance Manifest
 
+> **Status: Experimental** — This feature is partially implemented. Security guidelines are functional; code-quality guidelines are templates only. No automated tests exist yet. Use at your own discretion.
+
 **Purpose:** Defines which enterprise guidelines are active and their enforcement level.
 
 ---
@@ -110,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

@@ -24,7 +24,7 @@
 
 ## 3. The Main Operational Loop
 
-### Phase 1A: Impact Analysis
+### 3.1 Phase 1A: Impact Analysis
 
 Receive the goal from the user. Identify the **Change Set** — all components affected by this change.
 
@@ -68,7 +68,7 @@ NodeIDs must be **domain concepts**, not tasks.
 **Historical Context:** Before proposing the Change Set, scan `knowzcode/workgroups/` for completed WorkGroups that touched similar components. Reference relevant context in your proposal.
 
 #### Quality Gate: Change Set Approval
-Present the proposed Change Set to the user. **PAUSE and await user approval.** Do NOT proceed to Phase 1B until the user explicitly approves.
+Present the proposed Change Set to the user. **PAUSE and await user approval.** Do NOT proceed to Phase 1B until the user explicitly approves. In autonomous mode, auto-approve and proceed immediately (see Section 5).
 
 Upon approval, generate a unique WorkGroupID and update `knowzcode_tracker.md` for all nodes to `[WIP]`.
 
@@ -79,7 +79,7 @@ Upon approval, generate a unique WorkGroupID and update `knowzcode_tracker.md` f
 
 ---
 
-### Phase 1B: Specification
+### 3.2 Phase 1B: Specification
 
 Draft or refine `knowzcode/specs/[NodeID].md` for all nodes in the Change Set.
 
@@ -115,13 +115,13 @@ Known limitations and future work.
 **Backward compatibility:** Old numbered-section specs remain valid until naturally touched. When finalizing, rewrite in the new format.
 
 #### Quality Gate: Spec Approval
-Present drafted specs to the user. **PAUSE and await user approval.** Log "SpecApproved" events.
+Present drafted specs to the user. **PAUSE and await user approval.** Log "SpecApproved" events. In autonomous mode, auto-approve and proceed immediately (see Section 5).
 
 **Pre-Implementation Commit:** After specs are approved, commit `knowzcode/` to create a checkpoint before implementation begins.
 
 ---
 
-### Phase 2A: Implementation (TDD MANDATORY)
+### 3.3 Phase 2A: Implementation (TDD MANDATORY)
 
 For each NodeID in the approved Change Set:
 
@@ -160,7 +160,7 @@ Report implementation results including test counts, verification iterations, an
 
 ---
 
-### Phase 2B: Completeness Audit
+### 3.4 Phase 2B: Completeness Audit
 
 An independent, READ-ONLY audit verifying what percentage of specifications were actually implemented.
 
@@ -177,11 +177,11 @@ An independent, READ-ONLY audit verifying what percentage of specifications were
 - Cancel the WorkGroup
 
 #### Quality Gate: Audit Approval
-Present audit results to the user. **PAUSE for decision.** Only proceed to Phase 3 when the user approves.
+Present audit results to the user. **PAUSE for decision.** Only proceed to Phase 3 when the user approves. In autonomous mode, auto-approve and proceed immediately unless safety exceptions apply (see Section 5).
 
 ---
 
-### Phase 3: Atomic Finalization
+### 3.5 Phase 3: Atomic Finalization
 
 Once implementation is verified and approved, execute finalization:
 
@@ -258,28 +258,66 @@ You **MUST** pause and await explicit user approval at:
 * If you encounter a critical, unresolvable issue
 * If an architecture discrepancy is too complex to fix autonomously
 
+### Autonomous Mode Override
+
+When the user conveys intent for autonomous operation — through natural language (e.g., "approve all", "preapprove", "autonomous mode", "just run through", "I trust your judgement") or the `--autonomous` flag — quality gates above are still **presented** for transparency but **auto-approved** without waiting for user input. The workflow runs from start to finalization uninterrupted.
+
+The lead should interpret the **spirit** of the user's instruction, not just exact keyword matches. If the user clearly wants the workflow to proceed without stopping, that constitutes autonomous mode activation.
+
+**Safety exceptions** — ALWAYS pause even in autonomous mode:
+* Critical, unresolvable blockers (Section 11)
+* Security vulnerabilities rated HIGH or CRITICAL
+* >3 failures on the same phase
+* Architecture discrepancies too complex to fix autonomously
+* >3 gap-fix iterations per partition without resolution
+
+Autonomous mode is per-WorkGroup and does not carry over.
+
 ---
 
 ## 6. MCP Integration (Optional but Recommended)
 
 If KnowzCode MCP server is configured (`knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`), agents can leverage vault queries to enhance every phase.
 
+**Before using MCP, read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type.** Use the vault's description to confirm the query is appropriate for that vault. If a single vault covers all types, use it for everything. Never hardcode vault names — always resolve from config.
+
+### Vault Types
+
+| Type | Purpose | Example Queries |
+|------|---------|-----------------|
+| **code** | Reference implementations, code snippets, API patterns | `"authentication middleware pattern"`, `"error handling in {framework}"` |
+| **ecosystem** | Business rules, conventions, decisions, integrations, platform knowledge | `"checkout flow rules"`, `"pricing constraints"`, `"Stripe webhook setup"` |
+| **finalizations** | WorkGroup completion summaries, outcome records | `"past decisions about {component}"`, `"similar WorkGroups"` |
+
+A project may configure one vault covering all types (common for small teams) or multiple specialized vaults. Knowz-scribe (or direct MCP calls) writes to vaults; knowz-scout has read access only. The scribe is the primary capture agent that routes writes to the correct vault based on content type.
+
 ### Phase-Specific Usage
 
 | Phase | MCP Tool | Purpose |
 |-------|----------|---------|
-| **1A (Analysis)** | `search_knowledge(research_vault, "past decisions about {domain}")` | Find prior decisions affecting components |
-| **1B (Spec)** | `ask_question(research_vault, "conventions for {component_type}?")` | Check team conventions before drafting |
-| **2A (Build)** | `search_knowledge(code_vault, "{similar_feature} implementation")` | Find reference implementations |
-| **2B (Audit)** | `ask_question(research_vault, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
-| **3 (Close)** | `create_knowledge(research_vault, ...)` | Capture patterns, decisions, workarounds |
+| **1A (Analysis)** | `search_knowledge({vault matching "ecosystem" type}, "past decisions about {domain}")` | Find prior decisions affecting components |
+| **1B (Spec)** | `ask_question({vault matching "ecosystem" type}, "conventions for {component_type}?")` | Check team conventions before drafting |
+| **2A (Build)** | `search_knowledge({vault matching "code" type}, "{similar_feature} implementation")` | Find reference implementations |
+| **2B (Audit)** | `ask_question({vault matching "ecosystem" type}, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
+| **3 (Close)** | Delegate to knowz-scribe (or `create_knowledge` directly if no scribe) | Capture patterns, decisions, workarounds |
+
+### Knowz-Scribe (Multi-Agent Platforms)
+
+On platforms with multi-agent orchestration (e.g., Claude Code Agent Teams), **knowz-scribe** has full read/write access to MCP vaults, and **knowz-scout** has read access to MCP vaults. Both have read/write access to local knowzcode files:
+
+- Both spawned at workflow start (persistent agents, Stage 0 through Phase 3)
+- **Knowz-scribe** is the primary capture agent — receives capture messages from teammates at each quality gate (e.g., `"Capture Phase 1A: {wgid}"`), reads the WorkGroup file, extracts learnings, and writes to the appropriate vault. Handles deduplication, formatting, and routing to the correct vault by type.
+- **Knowz-scout** is the primary research agent — queries vaults for business context, conventions, and past decisions.
+- Both stay alive through the entire workflow, shut down after Phase 3 capture
+
+On platforms without multi-agent orchestration, the closer handles vault writes directly (see Section 7).
 
 ### Enterprise: Team Standards
 
-At workflow start, if enterprise vault is configured (`knowzcode/enterprise/compliance_manifest.md` has `mcp_compliance_enabled: true`):
+At workflow start, if an enterprise-type vault is configured (read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise", then check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`):
 - Pull team-wide standards and merge into quality gate criteria
-- Push audit results to enterprise vault after Phase 2B
-- Push completion records to enterprise vault after Phase 3
+- Push audit results to the resolved enterprise vault after Phase 2B
+- Push completion records to the resolved enterprise vault after Phase 3
 
 ### Graceful Degradation
 
@@ -301,45 +339,48 @@ During finalization, scan the WorkGroup for insight-worthy patterns:
 
 ### Auto-Capture Triggers
 
-Learning candidates are detected at each quality gate. If MCP is available, write concrete knowledge entries:
+Learning candidates are detected at each quality gate. Capture is delegated to the knowz-scribe agent on multi-agent platforms, or handled directly via MCP tools on single-agent platforms.
 
-**After Phase 1A approval:**
-```
-If MCP available:
-  create_knowledge(research_vault, title="Scope: {goal}",
-    content="[NodeIDs] {list}\n[Risk] {assessment}\n[Decision] {user feedback}",
-    tags=["scope", "change-set"])
-```
+**Multi-agent platforms (knowz-scribe active):**
 
-**After Phase 2A completion:**
-- Capture implementation patterns and workarounds discovered during TDD cycles
+At each quality gate, send a message to the knowz-scribe with the phase identifier:
+- After Phase 1A approval: `"Capture Phase 1A: {wgid}"`
+- After Phase 2A completion: `"Capture Phase 2A: {wgid}"`
+- After Phase 2B audit: `"Capture Phase 2B: {wgid}"`
+- After Phase 3 finalization: `"Capture Phase 3: {wgid}"`
 
-**After Phase 2B audit:**
-```
-If MCP available:
-  create_knowledge(research_vault, title="Audit: {wgid} - {score}%",
-    content="[Findings] {gaps}\n[Security] {issues}\n[Decision] {user choice}",
-    tags=["audit", "quality"])
-If MCP available AND enterprise vault configured:
-  create_knowledge(enterprise_vault, title="Audit: {wgid} - {score}%",
-    content="[Findings] {gaps}\n[Security] {issues}\n[Decision] {user choice}",
-    tags=["audit", "enterprise"])
-```
+The knowz-scribe reads the WorkGroup file, extracts relevant data, checks for duplicates, and writes to the appropriate vault. No other agent should call `create_knowledge` when the scribe is active.
+
+**Single-agent / no scribe (direct MCP writes):**
 
-**After Phase 3 finalization:**
-- Capture architectural learnings and consolidation decisions (handled by closer agent)
+If MCP is available but no knowz-scribe, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
+
+- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {goal}", content="[NodeIDs] {list}\n[Risk] {assessment}", tags=["scope"])`
+- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles
+- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}%", content="[Findings] {gaps}\n[Security] {issues}", tags=["audit"])`
+- After Phase 2B (enterprise): If enterprise vault configured and compliance enabled, push audit results to enterprise vault
+- After Phase 3: Capture architectural learnings and consolidation decisions (handled by closer agent)
 
 ### Capture Protocol
 
-If MCP is available:
-1. Detect learning candidates from WorkGroup file content
-2. Check for duplicates via `search_knowledge` — skip if substantially similar exists
-3. Prompt user for approval before saving
-4. Create learning via `create_knowledge` with appropriate title prefix
+**When knowz-scribe is active (multi-agent platforms):**
+1. Send capture message to knowz-scribe with phase identifier and WorkGroup ID
+2. The scribe handles: vault ID resolution, duplicate checking, user approval prompting, and writing
+3. No other agent should call `create_knowledge` directly
+
+**When no knowz-scribe (single-agent / sequential):**
+1. Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
+2. Detect learning candidates from WorkGroup file content
+3. Check for duplicates via `search_knowledge` — skip if substantially similar exists
+4. Prompt user for approval before saving
+5. Only write if the targeted vault is configured — skip gracefully if not
+6. Create learning via `create_knowledge` with appropriate title prefix
 
 ### Audit Trail (Enterprise)
 
-After Phase 3, if enterprise vault is configured:
+After Phase 3:
+1. Read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise"
+2. Only push if an enterprise vault is configured
 - Push WorkGroup completion record with goal, NodeIDs, audit score, and decisions
 - Push architecture drift findings if any detected during finalization
 
@@ -378,9 +419,36 @@ When a single AI handles all phases sequentially:
 - Pause at each gate for user approval
 - All quality standards apply identically
 
+### Parallel Execution (Multi-Agent Platforms)
+
+On platforms supporting concurrent agents (Claude Code Agent Teams, future multi-agent runtimes):
+
+#### Parallelism Boundaries
+- **Between phases**: Phase 1A must produce Change Set before 1B drafts specs (scope must be approved first)
+- **Within phases**: Independent NodeIDs can be implemented/audited in parallel
+- **Across phases**: Incremental review can start on completed components while other components are still being implemented
+- **Agent persistence**: Agents can stay alive across sub-phases to avoid cold-start overhead (e.g., builder persists through audit gap loop)
+
+#### Dependency Map
+The analyst produces a dependency map alongside the Change Set, identifying:
+- Which NodeIDs share affected files (must be implemented sequentially or by same agent)
+- Which NodeIDs are independent (can be implemented in parallel)
+- Sequential dependencies (NodeID-B requires NodeID-A's output)
+
+#### Incremental Review
+The reviewer can audit completed NodeIDs before all implementation finishes. Gap findings are routed back to the implementer for targeted fixes, then re-audited. Agents persist through this gap loop — no respawning.
+
+#### Context Scouts
+Dedicated context-gathering agents can run in parallel with core analysis:
+- Local context scout: reads project history, specs, workgroups
+- Knowz scout: queries and writes to knowledge management vaults for business context (full read/write access)
+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.