knowzcode 0.2.1 → 0.3.3

package/agents/test-advisor.md

@@ -0,0 +1,162 @@
+---
+name: test-advisor
+description: "KnowzCode: TDD enforcement, test quality review, and coverage assessment"
+tools: Read, Glob, Grep, Bash
+model: sonnet
+permissionMode: default
+maxTurns: 15
+---
+
+# Test Advisor
+
+You are the **Test Advisor** in a KnowzCode development workflow.
+Your expertise: TDD compliance verification, test quality assessment, coverage analysis, assertion quality.
+
+## Your Job
+
+Enforce TDD rigor. Review test quality. Assess coverage. The builder writes tests; you verify they're good tests.
+
+**Informational only — does not block gates.** Your findings are advisory. The lead includes them in gate presentations for transparency but they do not pause autonomous mode.
+
+**This is a READ-ONLY role.** You MUST NOT modify, create, or delete any files. Bash usage is limited to read-only operations: coverage reports, `git log` inspection for TDD compliance verification. Implementation is the builder's responsibility.
+
+## Stage 0: Coverage Baseline
+
+1. Glob for test files to establish baseline:
+   - `Glob: "**/*.test.*"` — JS/TS test files
+   - `Glob: "**/*.spec.*"` — spec-style test files
+   - `Glob: "**/test_*"` — Python test files
+   - `Glob: "**/tests/**"` — test directories
+   - `Glob: "**/*_test.go"` — Go test files
+   - `Glob: "**/*Test.java"` — Java test files
+2. Run coverage command if available (read-only — do NOT modify state):
+   - Check for `package.json` scripts: `"test:coverage"`, `"coverage"`
+   - Check for `pytest --cov`, `go test -cover`, `cargo tarpaulin`
+   - Run coverage report command via Bash (read-only)
+3. Map existing coverage to the goal's affected areas
+4. Broadcast baseline: `"Test coverage baseline for {goal}"`
+
+## Stage 1: Test Strategy
+
+After the analyst delivers the Change Set:
+
+1. Recommend test types per NodeID:
+   - **Unit tests**: Pure logic, transformations, utilities
+   - **Integration tests**: API endpoints, database operations, cross-component
+   - **E2E tests**: User flows, critical paths
+2. Flag NodeIDs needing special test infrastructure (mocking, fixtures, test databases)
+3. DM architect if VERIFY criteria aren't testable as written:
+   > "VERIFY criteria for NodeID-X aren't testable as written — {specific issue, suggestion}"
+4. DM lead with test strategy for Gate #1
+
+## Stage 1: Spec Testability Review (post-spec)
+
+After specs are drafted, review VERIFY criteria for testability:
+- Can each VERIFY statement be verified with an automated test?
+- Are expected values specific enough? (e.g., "returns 200" vs "returns success")
+- Do VERIFY statements cover error paths, not just happy paths?
+- Flag vague VERIFY criteria that would lead to weak assertions
+
+## Stage 2: Test Quality Review
+
+For each completed NodeID, review test files for:
+
+### TDD Compliance
+Check git log to verify tests were committed before (or with) implementation:
+```bash
+git log --oneline -- {test-file}
+git log --oneline -- {impl-file}
+```
+Compare timestamps — tests should appear at or before implementation commits.
+
+### Assertion Quality
+- Are assertions specific? (`expect(result).toEqual({id: 1, name: "test"})` vs `expect(result).toBeTruthy()`)
+- Do assertions test behavior, not implementation details?
+- Are error messages descriptive?
+- No `expect(true).toBe(true)` or similar vacuous assertions
+
+### Edge Case Coverage
+- **Happy path**: Core functionality tested
+- **Error paths**: Invalid inputs, network failures, timeouts
+- **Boundary conditions**: Empty arrays, null values, max/min values, off-by-one
+- **Concurrency**: Race conditions, parallel execution (if applicable)
+
+### Test Isolation
+- Proper mocking — no real network calls, database writes, or file system changes in unit tests
+- No test interdependence — tests pass in any order
+- Proper setup/teardown — no leaking state between tests
+- No shared mutable state between test cases
+
+### Naming Conventions
+- Tests describe behavior: `"should return 404 when user not found"` not `"test1"`
+- Test file names match source files: `auth.ts` → `auth.test.ts`
+- Describe/context blocks organize by feature or scenario
+
+## Finding Report Format
+
+Report findings to the lead using this structured format:
+
+```markdown
+### Test Advisor Report
+
+**Coverage Baseline**: {X}% overall, {Y}% in affected areas
+**TDD Compliance**: {X}/{N} NodeIDs had tests before implementation
+
+| NodeID | Test File | TDD | Edge Cases | Quality | Issues |
+|--------|-----------|-----|------------|---------|--------|
+| Auth | auth.test.ts | Yes | Covered | Good | — |
+| UserProfile | profile.test.ts | No | Missing error path | Adequate | Weak assertions on line 45 |
+| DataExport | export.test.ts | Yes | Missing boundary | Poor | No isolation, shared DB state |
+
+**Recommendations**:
+- {specific improvement suggestions}
+```
+
+## Builder Communication
+
+DM builders with specific test improvement feedback:
+> "Test for NodeID-X misses error path — add test for {scenario}"
+> "Assertions on line 45 are too weak — test specific return values, not truthiness"
+
+**Discipline**: Max 2 DMs to any individual builder. Consolidate findings — no per-file noise.
+
+## Inter-Specialist Communication
+
+- **DM security-officer** if a test gap is in a security-critical path (max 2 inter-specialist DMs):
+  > "Auth flow has no test for token expiry — flagging for security review"
+- Respond to security-officer DMs about test coverage for security scenarios
+
+## Enterprise Compliance (Optional)
+
+If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`:
+
+1. Read the manifest's Active Guidelines table — load guidelines where `Active: true`
+2. Read active guidelines and extract all `ARC Verification` criteria (e.g., `ARC_SEC_AUTH_01a`, `ARC_CQ_PATTERN_01a`)
+3. **Stage 2**: For each enterprise ARC criterion in scope, check if a corresponding test exists:
+   - Search test files for references to the ARC ID or the behavior it describes
+   - Flag ARC criteria that have no test coverage
+4. **Finding Report**: Add `Enterprise ARC Coverage` subsection when enterprise compliance is active:
+   ```
+   **Enterprise ARC Coverage**: {X}/{N} criteria have test coverage
+   | ARC Criterion | Guideline | Test File | Covered | Notes |
+   ```
+5. Check `knowzcode/enterprise/guidelines/code-quality.md` section 5 ("Testing Standards") for enterprise-specific testing requirements — incorporate into test quality assessment if populated.
+
+## Bash Usage
+
+Read-only only. Permitted commands:
+- `git log --oneline -- tests/` — TDD compliance verification
+- `git log --oneline -- {file}` — commit history for test-before-code check
+- Coverage report commands (e.g., `npx jest --coverage --reporter=text`, `pytest --cov --cov-report=term`)
+- `git diff --stat {ref}` — change scope assessment
+
+**NOT permitted**: Running tests that modify state, executing build commands, writing files.
+
+## Exit Expectations
+
+- Coverage baseline broadcast during Stage 0
+- Test strategy per NodeID delivered for Gate #1
+- Spec testability review delivered for Gate #2
+- Test quality report delivered for Gate #3
+- All findings consolidated — no per-file noise
+- Available for follow-up until shut down by lead (after Gate #3)

package/commands/audit.md

@@ -33,6 +33,22 @@ Read:
 - `knowzcode/knowzcode_tracker.md`
 - `knowzcode/knowzcode_architecture.md`
 - `knowzcode/knowzcode_project.md`
+- `knowzcode/knowzcode_orchestration.md` (if exists)
+
+## Step 1.1: Parse Orchestration Config (Optional)
+
+If `knowzcode/knowzcode_orchestration.md` exists, parse its YAML blocks:
+
+1. `SCOUT_MODE` = `scout_mode` value (default: "full")
+2. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
+3. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
+
+Apply flag overrides (flags win over config):
+- `--no-scouts` in `$ARGUMENTS` → override `SCOUT_MODE = "none"`
+- `--no-specialists` in `$ARGUMENTS` → override `DEFAULT_SPECIALISTS = []`
+- `--no-mcp` in `$ARGUMENTS` → override `MCP_AGENTS_ENABLED = false`
+
+If the file doesn't exist, use hardcoded defaults (current behavior).
 
 ## Step 2: Set Up Execution Mode
 
@@ -155,11 +171,55 @@ Spawn reviewers with their task IDs:
    > **Audit scope**: Enterprise compliance ONLY.
    > Check against guidelines in `knowzcode/enterprise/compliance_manifest.md`.
 
-4. If `VAULTS_CONFIGURED = true`, spawn `knowz-scout` for standards lookup in parallel with reviewers:
+4. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, spawn `knowz-scout` for standards lookup in parallel with reviewers:
    > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
    > Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type. Query for team standards: `ask_question({vault matching "ecosystem" type}, "standards for {project_type}", researchMode=true)`
 
-Wait for all to complete. Synthesize results in Step 4.
+Wait for all to complete.
+
+#### Specialist Integration (Optional)
+
+Initialize `AUDIT_SPECIALISTS = DEFAULT_SPECIALISTS` (from orchestration config, default: []).
+
+If `$ARGUMENTS` contains `--specialists` (or `--specialists=security`, `--specialists=test`, `--specialists=security,test`):
+- `--specialists` → enable all applicable: `[security-officer, test-advisor]`
+- `--specialists=csv` → enable specified subset
+- `--no-specialists` → clear to `[]` (overrides config defaults)
+
+If neither `--specialists` nor `--no-specialists` is present, use `DEFAULT_SPECIALISTS` from config.
+
+Parse which specialists to enable. Then spawn alongside reviewers:
+
+1. **security-officer** (if enabled) — spawn alongside `reviewer-sec-int` for deeper security scanning:
+   - `TaskCreate("Security officer: deep security audit")` → `TaskUpdate(owner: "security-officer")`
+   - Spawn `security-officer` teammate:
+     > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+     > You are the **security-officer** running a deep security audit.
+     > Read `agents/security-officer.md` for your role definition.
+     > Read `knowzcode/claude_code_execution.md` for team conventions.
+     >
+     > **Audit scope**: Full codebase security scan — vulnerability patterns, hardcoded secrets, injection vectors, auth bypass, SSRF, path traversal.
+     > **Context files**: knowzcode_tracker.md, knowzcode_architecture.md, knowzcode_project.md
+     > **Specs directory**: knowzcode/specs/
+     >
+     > Deliverable: Security finding report with severity ratings. Tag CRITICAL/HIGH findings with `[SECURITY-BLOCK]`.
+     > If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`, also cross-reference findings with enterprise guideline IDs.
+
+2. **test-advisor** (if enabled) — spawn alongside reviewers for test quality assessment:
+   - `TaskCreate("Test advisor: test quality audit")` → `TaskUpdate(owner: "test-advisor")`
+   - Spawn `test-advisor` teammate:
+     > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+     > You are the **test-advisor** running a test quality audit.
+     > Read `agents/test-advisor.md` for your role definition.
+     > Read `knowzcode/claude_code_execution.md` for team conventions.
+     >
+     > **Audit scope**: Test coverage, TDD compliance, assertion quality, edge case coverage, test isolation.
+     > **Context files**: knowzcode_tracker.md, knowzcode_project.md
+     >
+     > Deliverable: Test quality report with coverage metrics, TDD compliance, and improvement recommendations.
+     > If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`, also check enterprise ARC criteria for test coverage.
+
+Wait for all reviewers and specialists to complete. Synthesize results in Step 4.
 
 ### Subagent Mode
 
@@ -167,12 +227,15 @@ Wait for all to complete. Synthesize results in Step 4.
 
 Launch scouts + reviewer in parallel via `Task()`:
 
-1. **context-scout** — Local context (3 parallel instances):
-   - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
-   - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for related audit findings. Max 10 tool calls. Write findings to a concise summary.")`
-   - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md — scan for active WIP, prior audit results, architecture health. Max 10 tool calls. Write findings to a concise summary.")`
+1. **context-scout** — Local context (if `SCOUT_MODE != "none"`):
+   - `SCOUT_MODE = "full"` (default): 3 parallel instances:
+     - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for related audit findings. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research audit scope: {audit_type}. Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md — scan for active WIP, prior audit results, architecture health. Max 10 tool calls. Write findings to a concise summary.")`
+   - `SCOUT_MODE = "minimal"`: 1 combined instance:
+     - `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research audit scope: {audit_type}. Focus: ALL local context — knowzcode/specs/*.md, knowzcode/workgroups/*.md, knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md. Max 10 tool calls. Write findings to a concise summary.")`
 
-2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true`):
+2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
    - `Task(subagent_type="knowz-scout", description="Scout: vault standards", prompt="Research audit scope: {audit_type}. Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query for team standards, conventions, and past audit decisions. Max 10 tool calls. Write findings to a concise summary.")`
 
 3. **reviewer** — The audit itself:
@@ -191,12 +254,15 @@ All launched in parallel. Synthesize scout findings alongside reviewer results.
 
 Launch scouts + parallel reviewers via `Task()`:
 
-1. **context-scout** — Local context (3 parallel instances):
-   - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research for comprehensive audit. Focus: knowzcode/specs/*.md — scan all specifications for quality, completeness, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
-   - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research for comprehensive audit. Focus: knowzcode/workgroups/*.md — scan all WorkGroups for patterns, recurring issues, audit history. Max 10 tool calls. Write findings to a concise summary.")`
-   - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research for comprehensive audit. Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md — scan for WIP status, prior audit results, architecture health. Max 10 tool calls. Write findings to a concise summary.")`
+1. **context-scout** — Local context (if `SCOUT_MODE != "none"`):
+   - `SCOUT_MODE = "full"` (default): 3 parallel instances:
+     - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research for comprehensive audit. Focus: knowzcode/specs/*.md — scan all specifications for quality, completeness, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research for comprehensive audit. Focus: knowzcode/workgroups/*.md — scan all WorkGroups for patterns, recurring issues, audit history. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research for comprehensive audit. Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md — scan for WIP status, prior audit results, architecture health. Max 10 tool calls. Write findings to a concise summary.")`
+   - `SCOUT_MODE = "minimal"`: 1 combined instance:
+     - `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research for comprehensive audit. Focus: ALL local context — knowzcode/specs/*.md, knowzcode/workgroups/*.md, knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md. Max 10 tool calls. Write findings to a concise summary.")`
 
-2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true`):
+2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
    - `Task(subagent_type="knowz-scout", description="Scout: vault standards", prompt="Research for comprehensive audit. Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query for team standards, conventions, security policies, and compliance requirements. Max 10 tool calls. Write findings to a concise summary.")`
 
 3. **Parallel reviewers**:
@@ -206,6 +272,25 @@ Launch scouts + parallel reviewers via `Task()`:
 
 Synthesize scout context alongside reviewer results.
 
+#### Specialist Integration (Subagent Mode — Optional)
+
+Initialize `AUDIT_SPECIALISTS = DEFAULT_SPECIALISTS` (from orchestration config, default: []).
+
+If `$ARGUMENTS` contains `--specialists` (or `--specialists=security`, `--specialists=test`, `--specialists=security,test`):
+- `--specialists` → enable all applicable
+- `--specialists=csv` → enable specified subset
+- `--no-specialists` → clear to `[]`
+
+If `AUDIT_SPECIALISTS` is non-empty, launch specialist `Task()` calls in parallel with reviewers:
+
+1. **security-officer** (if enabled):
+   - `Task(subagent_type="security-officer", description="Security officer: deep security audit", prompt="Audit scope: Full codebase security scan. Context files: knowzcode_tracker.md, knowzcode_architecture.md. Specs: knowzcode/specs/. Deliverable: Security finding report with severity ratings. Tag CRITICAL/HIGH with [SECURITY-BLOCK]. If knowzcode/enterprise/compliance_manifest.md exists and compliance_enabled: true, also cross-reference findings with enterprise guideline IDs.")`
+
+2. **test-advisor** (if enabled):
+   - `Task(subagent_type="test-advisor", description="Test advisor: test quality audit", prompt="Audit scope: Test coverage, TDD compliance, assertion quality, edge cases. Context files: knowzcode_tracker.md. Deliverable: Test quality report with coverage metrics and recommendations. If knowzcode/enterprise/compliance_manifest.md exists and compliance_enabled: true, also check enterprise ARC criteria for test coverage.")`
+
+Synthesize specialist findings alongside reviewer results.
+
 ## Step 4: Present Results
 
 ```markdown
@@ -227,6 +312,10 @@ Synthesize scout context alongside reviewer results.
 
 ### Recommendations
 {prioritized action items}
+
+### Specialist Reports                    [only when --specialists active]
+**Security Officer**: {finding count, severity breakdown, SECURITY-BLOCK tags}
+**Test Advisor**: {coverage %, TDD compliance, quality assessment}
 ```
 
 ## Step 5: Log Audit

package/commands/connect-mcp.md

@@ -280,6 +280,30 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
    You can edit knowzcode/knowzcode_vaults.md to update descriptions or routing rules.
    ```
 
+   **Step 6f: Update CLAUDE.md with vault targeting guidance**
+
+   Ensure agents always know to pass `vaultId` by adding a reference section to the project's CLAUDE.md:
+
+   1. Read the project's `CLAUDE.md`
+   2. Search for an existing `### Vault Targeting` or `### Knowz MCP` section
+   3. **If found:** Replace the existing section with the updated content below
+   4. **If NOT found:** Append the section after the `# KnowzCode Integration` block (or at the end if not found)
+   5. Insert a vault targeting reference section that points to the central config:
+
+   ```markdown
+   ### Vault Targeting (MCP Writes)
+   **Always pass `vaultId`** when calling `create_knowledge` or `update_knowledge`.
+   Omitting it saves to the tenant default vault — NOT the project vault.
+
+   Vault IDs and routing rules: `knowzcode/knowzcode_vaults.md`
+   If vault IDs are already in context from a previous read, do not re-read the file.
+   For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
+   ```
+
+   6. Confirm: `"Updated CLAUDE.md with vault targeting guidance (vault IDs managed in knowzcode/knowzcode_vaults.md)."`
+
+   **Idempotent:** Replaces existing `### Vault Targeting` section rather than duplicating.
+
 7. **Add MCP server using CLI**
    ```bash
    claude mcp add --transport http \

package/commands/init.md

@@ -33,6 +33,7 @@ knowzcode/
 ├── knowzcode_log.md
 ├── knowzcode_architecture.md
 ├── knowzcode_loop.md
+├── knowzcode_orchestration.md
 ├── platform_adapters.md
 ├── environment_context.md
 ├── user_preferences.md (if configured)
@@ -59,6 +60,20 @@ Use the embedded templates below.
 - If yes: prompt for testing frameworks, code style, quality priorities
 - Create `knowzcode/user_preferences.md`
 
+### 5.5. Configure orchestration defaults (optional)
+
+Ask: "Would you like to configure agent orchestration defaults? (optional — can be changed later in knowzcode/knowzcode_orchestration.md)"
+
+If yes: prompt for:
+- Max concurrent builders (1-5, default: 5)
+- Scout mode (full/minimal/none, default: full)
+- Default specialists (checkboxes: security-officer, test-advisor, project-advisor)
+- MCP agents enabled (yes/no, default: yes)
+
+If no: generate with all defaults.
+
+Generate `knowzcode/knowzcode_orchestration.md` from the template (always — it's part of the standard file set).
+
 ### 6. Create .gitignore
 
 Protect environment-specific files from git:
@@ -80,7 +95,7 @@ CHECK for existing files:
   - AGENTS.md or AGENTS.override.md → offer to generate Codex adapter
   - GEMINI.md or ~/.gemini/GEMINI.md → offer to generate Gemini adapter
   - .cursor/rules/ or .cursorrules (deprecated) → offer Cursor adapter (.cursor/rules/knowzcode.mdc)
-  - .github/copilot-instructions.md → offer Copilot adapter
+  - .github/copilot-instructions.md OR .github/ directory → offer Copilot adapter (full prompt files)
   - .windsurf/rules/ or .windsurfrules (deprecated) → offer Windsurf adapter (.windsurf/rules/knowzcode.md)
 ```
 
@@ -119,6 +134,53 @@ After generation, verify each adapter:
 
 Adapter templates are in `knowzcode/platform_adapters.md`. Copy the relevant sections into the appropriate files.
 
+**Step 7e: Copilot-specific generation**
+
+When Copilot is selected, generate the full prompt file suite in addition to the instructions file:
+
+```
+1. Create .github/ directory if it doesn't exist
+2. Create .github/copilot-instructions.md from platform_adapters.md template Section A
+3. Create .github/prompts/ directory
+4. Generate all 9 prompt files from platform_adapters.md template Section B:
+   - .github/prompts/kc-work.prompt.md
+   - .github/prompts/kc-analyze.prompt.md
+   - .github/prompts/kc-specify.prompt.md
+   - .github/prompts/kc-implement.prompt.md
+   - .github/prompts/kc-audit.prompt.md
+   - .github/prompts/kc-finalize.prompt.md
+   - .github/prompts/kc-fix.prompt.md
+   - .github/prompts/kc-plan.prompt.md
+   - .github/prompts/kc-continue.prompt.md
+5. Replace "vX.Y.Z" in generated files with the current KnowzCode version
+6. Optionally create .vscode/mcp.json skeleton from template Section C
+   (ask user: "Would you like to generate MCP configuration for VS Code?")
+```
+
+**Skip Agent Teams enablement for Copilot** — Copilot uses single-agent sequential execution.
+
+**Copilot success message:**
+```
+GitHub Copilot adapter generated:
+  .github/copilot-instructions.md     (repository-level instructions)
+  .github/prompts/kc-work.prompt.md   (start workflow: #prompt:kc-work)
+  .github/prompts/kc-analyze.prompt.md
+  .github/prompts/kc-specify.prompt.md
+  .github/prompts/kc-implement.prompt.md
+  .github/prompts/kc-audit.prompt.md
+  .github/prompts/kc-finalize.prompt.md
+  .github/prompts/kc-fix.prompt.md    (quick fix: #prompt:kc-fix)
+  .github/prompts/kc-plan.prompt.md   (research: #prompt:kc-plan)
+  .github/prompts/kc-continue.prompt.md (resume: #prompt:kc-continue)
+
+Usage in VS Code:
+  #prompt:kc-work "Build user authentication"  — Start a feature
+  #prompt:kc-fix "Fix login redirect bug"      — Quick fix
+  #prompt:kc-continue                          — Resume where you left off
+
+See knowzcode/copilot_execution.md for the full execution guide.
+```
+
 ### 7.5. Enable Agent Teams (Claude Code only)
 
 If the user is on Claude Code, **actively offer** to enable Agent Teams:
@@ -192,6 +254,7 @@ Created:
   knowzcode/knowzcode_log.md
   knowzcode/knowzcode_architecture.md
   knowzcode/knowzcode_loop.md
+  knowzcode/knowzcode_orchestration.md
   knowzcode/platform_adapters.md
   knowzcode/.gitignore
   knowzcode/specs/
@@ -311,6 +374,58 @@ Next steps:
 **Test Runner:** [Auto-detected]
 ```
 
+### knowzcode_orchestration.md
+```markdown
+# 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
+max_builders: 5
+```
+
+---
+
+## Scout Configuration
+
+```yaml
+scout_mode: full
+```
+
+---
+
+## Specialist Defaults
+
+```yaml
+default_specialists: []
+```
+
+---
+
+## MCP Agent Configuration
+
+```yaml
+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.
+```
+
 ---
 
 ## Error Handling

package/commands/plan.md

@@ -40,6 +40,16 @@ Attempt `TeamCreate(team_name="kc-plan-{slug}")` (2-4 word kebab-case from topic
 
 The user MUST see the execution mode announcement before investigation begins.
 
+## Step 3.5: Load Orchestration Config (Optional)
+
+If `knowzcode/knowzcode_orchestration.md` exists, parse:
+1. `SCOUT_MODE` = `scout_mode` value (default: "full")
+2. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
+
+Flag overrides: `--no-scouts` → `SCOUT_MODE = "none"`, `--no-mcp` → `MCP_AGENTS_ENABLED = false`
+
+If file doesn't exist, use defaults. Other config settings (`max_builders`, `default_specialists`) are not applicable to `/kc:plan`.
+
 ## Step 4: Launch Parallel Investigation
 
 ### MCP Probe
@@ -83,15 +93,15 @@ Before spawning agents, determine vault availability:
 
 Create tasks first, pre-assign, then spawn with task IDs:
 
-1. `TaskCreate("Scout: local context for {topic}")` → `TaskUpdate(owner: "context-scout")`
-2. `TaskCreate("Scout: vault knowledge for {topic}")` → `TaskUpdate(owner: "knowz-scout")` (if `VAULTS_CONFIGURED = true`)
+1. If `SCOUT_MODE != "none"`: `TaskCreate("Scout: local context for {topic}")` → `TaskUpdate(owner: "context-scout")`
+2. `TaskCreate("Scout: vault knowledge for {topic}")` → `TaskUpdate(owner: "knowz-scout")` (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`)
 3. `TaskCreate("Research: code exploration")` → `TaskUpdate(owner: "analyst")`
 4. `TaskCreate("Research: architecture")` → `TaskUpdate(owner: "architect")`
 5. `TaskCreate("Research: security + quality")` → `TaskUpdate(owner: "reviewer")`
 
-Spawn up to five teammates with their task IDs:
+Spawn teammates with their task IDs (count depends on SCOUT_MODE and MCP settings):
 
-1. Spawn `context-scout` teammate:
+1. If `SCOUT_MODE != "none"`, spawn `context-scout` teammate:
    > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
    > You are researching "{topic}" from a **knowzcode history** angle.
    > Read `agents/context-scout.md` for your role definition.
@@ -99,7 +109,7 @@ Spawn up to five teammates with their task IDs:
    > Find: existing specs, prior WorkGroups, tracker entries relevant to this topic.
    > Broadcast findings to all teammates.
 
-2. If `VAULTS_CONFIGURED = true`, spawn `knowz-scout` teammate:
+2. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, spawn `knowz-scout` teammate:
    > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
    > You are researching "{topic}" from a **vault knowledge** angle.
    > Read `agents/knowz-scout.md` for your role definition.
@@ -138,12 +148,15 @@ Wait for all to complete, then synthesize in Step 5.
 
 Delegate to up to five agents in parallel via `Task()`:
 
-1. **context-scout** — Local context (3 parallel instances):
-   - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research \"{topic}\". Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
-   - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research \"{topic}\". Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for similar goals, what was tried, what succeeded/failed. Max 10 tool calls. Write findings to a concise summary.")`
-   - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research \"{topic}\". Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md, knowzcode/knowzcode_project.md — scan for active WIP, REFACTOR tasks, architecture summary, recent log patterns. Max 10 tool calls. Write findings to a concise summary.")`
+1. **context-scout** — Local context (if `SCOUT_MODE != "none"`):
+   - `SCOUT_MODE = "full"` (default): 3 parallel instances:
+     - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research \"{topic}\". Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research \"{topic}\". Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for similar goals, what was tried, what succeeded/failed. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research \"{topic}\". Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md, knowzcode/knowzcode_project.md — scan for active WIP, REFACTOR tasks, architecture summary, recent log patterns. Max 10 tool calls. Write findings to a concise summary.")`
+   - `SCOUT_MODE = "minimal"`: 1 combined instance:
+     - `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research \"{topic}\". Focus: ALL local context — knowzcode/specs/*.md, knowzcode/workgroups/*.md, knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md, knowzcode/knowzcode_project.md. Max 10 tool calls. Write findings to a concise summary.")`
 
-2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true`):
+2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
    - `Task(subagent_type="knowz-scout", description="Scout: vault knowledge", prompt="Research \"{topic}\". Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query each for relevant knowledge: team conventions, past decisions, similar implementations. Max 10 tool calls. Write findings to a concise summary.")`
 
 3. **analyst** — Code exploration: