knowzcode 0.1.0 → 0.3.1

package/agents/update-coordinator.md

@@ -173,7 +173,6 @@ Before any changes:
 
 ```markdown
 1. Create timestamped backup:
-   .claude.backup.{timestamp}/
    knowzcode.backup.{timestamp}/
 
 2. Store backup manifest:
@@ -237,7 +236,6 @@ Create `knowzcode/update_manifest.md`:
 ✅ Project metadata: Preserved
 
 ### Backup Location
-`.claude.backup.20250104_200000/`
 `knowzcode.backup.20250104_200000/`
 
 ### Version Update
@@ -276,7 +274,7 @@ After update completion:
 
 ## Update Instructions
 
-When invoked via `/kc-update [source_path]`:
+When invoked (see "How to Invoke" below), provide the source path as context:
 
 ```markdown
 1. Validate inputs:
@@ -286,7 +284,6 @@ When invoked via `/kc-update [source_path]`:
    - No active WorkGroups blocking update
 
 2. Create backups:
-   - Backup .claude/ directory
    - Backup knowzcode/ directory
    - Create backup manifest
 
@@ -368,27 +365,19 @@ After successful update:
 
 3. Recommend next steps:
    - Review any .new files
-   - Test orchestration: /kc-step 1A (dry run)
+   - Test orchestration: run /kc:work on a small task to verify
    - Check for deprecated features
    - Read changelog if provided
 ```
 
-## Usage Examples
+## How to Invoke
 
-**Basic Update**:
-```
-/kc-update /path/to/newer/knowzcode
-```
+This agent is invoked manually by name (e.g., spawned as a teammate or via `Task()` with `subagent_type: "update-coordinator"`). There is no dedicated slash command yet — a `/kc:update` command may be added in a future release.
 
-**Update with Conflict Strategy**:
-```
-/kc-update /path/to/newer/knowzcode strategy=preserve-custom
-```
+**Provide the source path in the spawn prompt:**
+> Update KnowzCode from `/path/to/newer/knowzcode`. Use conflict strategy: preserve-custom.
 
-**Update with Dry Run**:
-```
-/kc-update /path/to/newer/knowzcode --dry-run
-```
+**Dry run** — add `--dry-run` to the prompt to preview changes without writing files.
 
 ## Critical Safety Rules
 

package/bin/knowzcode.mjs

@@ -195,6 +195,65 @@ function listFilesRecursive(dir, base = dir) {
   return files;
 }
 
+// ─── Marketplace Config ──────────────────────────────────────────────────────
+
+function setMarketplaceConfig(claudeDir) {
+  ensureDir(claudeDir);
+  const settingsFile = join(claudeDir, 'settings.json');
+  let settings = {};
+
+  if (existsSync(settingsFile)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.extraKnownMarketplaces) settings.extraKnownMarketplaces = {};
+  settings.extraKnownMarketplaces.knowzcode = {
+    source: { source: 'github', repo: 'knowz-io/knowzcode' },
+  };
+
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+}
+
+function removeMarketplaceConfig(claudeDir) {
+  const settingsFile = join(claudeDir, 'settings.json');
+  if (!existsSync(settingsFile)) return;
+
+  try {
+    const settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+    if (settings.extraKnownMarketplaces && settings.extraKnownMarketplaces.knowzcode) {
+      delete settings.extraKnownMarketplaces.knowzcode;
+      writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+    }
+  } catch {
+    // Ignore parse errors
+  }
+}
+
+// ─── Stale File Cleanup ─────────────────────────────────────────────────────
+
+function removeStaleFiles(sourceDir, targetDir) {
+  if (!existsSync(targetDir) || !existsSync(sourceDir)) return;
+
+  const sourceFiles = new Set(
+    readdirSync(sourceDir)
+      .filter((f) => f.endsWith('.md'))
+  );
+
+  for (const entry of readdirSync(targetDir)) {
+    if (entry.endsWith('.md') && !sourceFiles.has(entry)) {
+      const stale = join(targetDir, entry);
+      if (existsSync(stale) && statSync(stale).isFile()) {
+        log.info(`Removing stale file: ${stale}`);
+        rmSync(stale, { force: true });
+      }
+    }
+  }
+}
+
 // ─── Tracker & Log Initializers ──────────────────────────────────────────────
 
 function initTracker(filePath) {
@@ -311,10 +370,9 @@ async function promptConfirm(message) {
 
 // ─── Agent Teams Enablement ──────────────────────────────────────────────────
 
-function enableAgentTeams(dir) {
-  const claudeDir = join(dir, '.claude');
+function enableAgentTeams(claudeDir, isGlobal) {
   ensureDir(claudeDir);
-  const settingsFile = join(claudeDir, 'settings.local.json');
+  const settingsFile = join(claudeDir, isGlobal ? 'settings.json' : 'settings.local.json');
 
   let settings = {};
   if (existsSync(settingsFile)) {
@@ -329,7 +387,7 @@ function enableAgentTeams(dir) {
   settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
 
   writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
-  log.ok('Agent Teams enabled in .claude/settings.local.json');
+  log.ok(`Agent Teams enabled in ${settingsFile}`);
 }
 
 // ─── Commands ────────────────────────────────────────────────────────────────
@@ -475,9 +533,21 @@ async function cmdInstall(opts) {
       const claudeDir = opts.global ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude') : join(dir, '.claude');
 
       log.info(`Installing Claude Code components to ${claudeDir}/`);
+
+      // Remove stale files before copying on --force
+      if (opts.force) {
+        removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+        removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+        removeStaleFiles(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+      }
+
       copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
       copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
       copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+
+      // Pre-register marketplace in settings.json
+      setMarketplaceConfig(claudeDir);
+
       adapterFiles.push(claudeDir + '/commands/', claudeDir + '/agents/', claudeDir + '/skills/');
     } else {
       // Other platforms: extract template and write adapter file
@@ -496,9 +566,12 @@ async function cmdInstall(opts) {
   }
 
   // 4. Agent Teams enablement
+  const agentTeamsClaudeDir = opts.global
+    ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude')
+    : join(dir, '.claude');
   let agentTeamsEnabled = false;
   if (opts.agentTeams) {
-    enableAgentTeams(dir);
+    enableAgentTeams(agentTeamsClaudeDir, opts.global);
     agentTeamsEnabled = true;
   } else if (selectedPlatforms.includes('claude') && !opts.force) {
     // Interactive prompt for Claude Code users
@@ -507,7 +580,7 @@ async function cmdInstall(opts) {
     console.log(`teammates handle each workflow phase. ${c.dim}(experimental)${c.reset}`);
     const wantTeams = await promptConfirm('Enable Agent Teams? (recommended for Claude Code)');
     if (wantTeams) {
-      enableAgentTeams(dir);
+      enableAgentTeams(agentTeamsClaudeDir, opts.global);
       agentTeamsEnabled = true;
     }
   }
@@ -531,7 +604,12 @@ async function cmdInstall(opts) {
   console.log('  1. Edit knowzcode/knowzcode_project.md — set project name, stack, standards');
   console.log('  2. Edit knowzcode/environment_context.md — configure build/test commands');
   if (selectedPlatforms.includes('claude')) {
-    console.log('  3. Start building: /kc:work "Your first feature"');
+    console.log('  3. Install the KnowzCode plugin (recommended):');
+    console.log('     /plugin install kc@knowzcode');
+    console.log('  4. Start building:');
+    console.log('     /kc:work "Your first feature"');
+    console.log('');
+    console.log('  Note: Commands also work without plugin as /work, /plan, /fix, etc.');
   } else {
     console.log('  3. Start building: use knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md');
   }
@@ -624,6 +702,9 @@ async function cmdUninstall(opts) {
     }
   }
 
+  // Clean up marketplace config from settings.json
+  removeMarketplaceConfig(claudeDir);
+
   console.log('');
   log.ok('Uninstall complete');
   console.log('  Removed:');
@@ -716,9 +797,15 @@ async function cmdUpgrade(opts) {
   const claudeDir = join(dir, '.claude');
   if (existsSync(join(claudeDir, 'commands')) || existsSync(join(claudeDir, 'agents'))) {
     log.info('Updating Claude Code components...');
+    // Remove stale files before copying
+    removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
+    removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
+    removeStaleFiles(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
     copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
     copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
     copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
+    // Ensure marketplace config is up to date
+    setMarketplaceConfig(claudeDir);
   }
 
   // Regenerate adapters for detected platforms

package/commands/audit.md

@@ -22,7 +22,7 @@ Run specialized audit workflows.
 | **architecture** | Architecture health and drift |
 | **security** | OWASP vulnerability scanning |
 | **integration** | Cross-component consistency |
-| **compliance** | Enterprise guideline compliance (if configured) |
+| **compliance** | Enterprise guideline compliance (if configured, experimental) |
 | *(no argument)* | Full parallel audit of all types |
 
 ---
@@ -33,40 +33,95 @@ Read:
 - `knowzcode/knowzcode_tracker.md`
 - `knowzcode/knowzcode_architecture.md`
 - `knowzcode/knowzcode_project.md`
+- `knowzcode/knowzcode_orchestration.md` (if exists)
 
-## Step 2: Execute Audit
+## Step 1.1: Parse Orchestration Config (Optional)
 
-### Agent Teams Mode (if available)
+If `knowzcode/knowzcode_orchestration.md` exists, parse its YAML blocks:
 
-Spawn a `reviewer` teammate:
+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
+
+Attempt `TeamCreate(team_name="kc-audit-{timestamp}")`:
+
+- **If TeamCreate succeeds** → Agent Teams mode:
+  1. Announce: `**Execution Mode: Agent Teams** — created team kc-audit-{timestamp}`
+  2. Read `knowzcode/claude_code_execution.md` for team conventions.
+  3. You are the **team lead** — coordinate the audit and present results.
+
+- **If TeamCreate fails** (error, unrecognized tool, timeout) → Subagent Delegation:
+  - Announce: `**Execution Mode: Subagent Delegation** — Agent Teams not available, using Task() fallback`
+
+The user MUST see the execution mode announcement before audit work begins.
+
+## Step 3: Execute Audit
+
+### MCP Probe
+
+Before spawning agents, determine vault availability:
+1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
+2. Call `list_vaults(includeStats=true)` **always** — regardless of whether any IDs exist in the file
+3. If `list_vaults()` fails → set `MCP_ACTIVE = false`, announce `**MCP Status: Not connected**`, skip vault setup
+4. If `list_vaults()` succeeds AND UNCREATED list is non-empty → present the **Vault Creation Prompt**:
+
+   ```markdown
+   ## Vault Setup
+
+   Your Knowz API key is valid and MCP is connected, but {N} default vault(s) haven't been created yet.
+   Creating vaults enables knowledge capture throughout the workflow:
+
+   | Vault | Type | Description | Written During |
+   |-------|------|-------------|----------------|
+   ```
+
+   Build table rows dynamically from the UNCREATED entries only. Derive "Written During" from each vault's Write Conditions field in `knowzcode_vaults.md`.
+
+   Then present options:
+   ```
+   Options:
+     **A) Create all {N} vaults** (recommended)
+     **B) Select which to create**
+     **C) Skip** — proceed without vaults (can create later with `/kc:connect-mcp --configure-vaults`)
+   ```
+
+5. Handle user selection:
+   - **A**: For each UNCREATED entry, call MCP `create_vault(name, description)`. If `create_vault` is not available, fall back to matching by name against `list_vaults()` results. Update `knowzcode_vaults.md`: fill ID field, change H3 heading from `(not created)` to vault ID. Report any failures.
+   - **B**: Ask which vaults to create, then create only selected ones.
+   - **C**: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
+6. After resolution, set:
+   - `MCP_ACTIVE = true` (MCP works regardless of vault creation outcome)
+   - `VAULTS_CONFIGURED = true` if at least 1 vault now has a valid ID, else `false`
+   - Announce: `**MCP Status: Connected — N vault(s) available**` or `**MCP Status: Connected — no vaults configured (knowledge capture disabled)**`
+
+### Agent Teams Mode
+
+#### Specific Audit Type (argument provided)
+
+`TaskCreate("Audit: {audit_type}")` → `TaskUpdate(owner: "reviewer")`.
+
+Spawn a single `reviewer` teammate:
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
 > You are the **reviewer** running a {audit_type} audit.
 > Read `agents/reviewer.md` for your role definition.
 > Read `knowzcode/claude_code_execution.md` for team conventions.
 >
-> **Audit scope**: {audit_type or "comprehensive — all types"}
+> **Audit scope**: {audit_type}
 > **Context files**: knowzcode_tracker.md, knowzcode_architecture.md, knowzcode_project.md
 > **Specs directory**: knowzcode/specs/
 >
 > Deliverable: Audit report with health scores, critical issues, recommendations.
 
-Create task and assign. Wait for completion. Shut down teammate.
-
-### Subagent Mode (fallback)
-
-Delegate to the **reviewer** agent via `Task()`. Pass the audit type and context file paths.
-
-### Full Audit (no argument — DEFAULT)
-
-The reviewer performs a comprehensive quality audit covering:
-- Specification quality (all specs in `knowzcode/specs/`)
-- Architecture health (`knowzcode/knowzcode_architecture.md`)
-- Security vulnerability scan (OWASP Top 10)
-- Integration consistency (cross-component patterns)
-- Enterprise compliance (if `knowzcode/enterprise/` configured)
-
-If MCP is configured: `ask_question(research_vault, "standards for {project_type}", researchMode=true)` to check against documented team standards.
-
-### Specific Audit Type
+Wait for completion. Shut down teammate. Clean up the team.
 
 The reviewer focuses on the requested type with type-specific depth:
 - **spec**: Validates 4-section format, VERIFY statement count, consolidation opportunities
@@ -75,7 +130,168 @@ The reviewer focuses on the requested type with type-specific depth:
 - **integration**: API contracts, dependency graph, orphaned code, data flow
 - **compliance**: Enterprise guideline enforcement levels
 
-## Step 3: Present Results
+#### Full Audit (no argument — DEFAULT)
+
+Create tasks first, pre-assign, then spawn with task IDs:
+- `TaskCreate("Audit: spec + architecture")` → `TaskUpdate(owner: "reviewer-spec-arch")`
+- `TaskCreate("Audit: security + integration")` → `TaskUpdate(owner: "reviewer-sec-int")`
+- (Optional) `TaskCreate("Audit: compliance")` → `TaskUpdate(owner: "reviewer-compliance")` (if enterprise configured)
+- `TaskCreate("Scout: vault standards")` → `TaskUpdate(owner: "knowz-scout")` (if `VAULTS_CONFIGURED = true`)
+
+Spawn reviewers with their task IDs:
+
+1. Spawn `reviewer` teammate (name: `reviewer-spec-arch`):
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+   > You are the **reviewer** running a targeted audit.
+   > Read `agents/reviewer.md` for your role definition.
+   > Read `knowzcode/claude_code_execution.md` for team conventions.
+   >
+   > **Audit scope**: Specification quality AND architecture health ONLY.
+   > Do NOT audit security or integration — another reviewer handles those.
+   > **Context files**: knowzcode_tracker.md, knowzcode_architecture.md, knowzcode_project.md
+   > **Specs directory**: knowzcode/specs/
+   >
+   > Deliverable: Audit report with spec quality scores, architecture health, critical issues.
+
+2. Spawn `reviewer` teammate (name: `reviewer-sec-int`):
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+   > You are the **reviewer** running a targeted audit.
+   > Read `agents/reviewer.md` for your role definition.
+   > Read `knowzcode/claude_code_execution.md` for team conventions.
+   >
+   > **Audit scope**: Security vulnerability scan AND integration consistency ONLY.
+   > Do NOT audit specs or architecture — another reviewer handles those.
+   > **Context files**: knowzcode_tracker.md, knowzcode_architecture.md, knowzcode_project.md
+   > **Specs directory**: knowzcode/specs/
+   >
+   > Deliverable: Audit report with security posture, integration health, critical issues.
+
+3. (Optional) If enterprise compliance configured, spawn `reviewer` (name: `reviewer-compliance`):
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+   > **Audit scope**: Enterprise compliance ONLY.
+   > Check against guidelines in `knowzcode/enterprise/compliance_manifest.md`.
+
+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.
+
+#### 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
+
+#### Specific Audit Type
+
+Launch scouts + reviewer in parallel via `Task()`:
+
+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` 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:
+   - `subagent_type`: `"reviewer"`
+   - `prompt`: Task-specific context only (role definition is auto-loaded from `agents/reviewer.md`):
+     > **Audit scope**: {audit_type}
+     > **Context files**: knowzcode_tracker.md, knowzcode_architecture.md, knowzcode_project.md
+     > **Specs directory**: knowzcode/specs/
+     >
+     > Deliverable: Audit report with health scores, critical issues, recommendations.
+   - `description`: `"Audit: {audit_type}"`
+
+All launched in parallel. Synthesize scout findings alongside reviewer results.
+
+#### Full Audit
+
+Launch scouts + parallel reviewers via `Task()`:
+
+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` 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**:
+   - `Task(subagent_type="reviewer", description="Audit: spec + architecture", prompt="Audit scope: Specification quality AND architecture health ONLY. ...")`
+   - `Task(subagent_type="reviewer", description="Audit: security + integration", prompt="Audit scope: Security vulnerability scan AND integration consistency ONLY. ...")`
+   - `Task(subagent_type="reviewer", description="Audit: compliance", prompt="Audit scope: Enterprise compliance ONLY. ...")` (if enterprise configured)
+
+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
 ## KnowzCode Audit Results
@@ -96,9 +312,13 @@ The reviewer focuses on the requested type with type-specific depth:
 
 ### 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 4: Log Audit
+## Step 5: Log Audit
 
 Log to `knowzcode/knowzcode_log.md`:
 ```markdown