knowzcode 0.1.0 → 0.2.1

package/agents/reviewer.md

@@ -3,7 +3,7 @@ name: reviewer
 description: "KnowzCode: Quality audit, security review, and compliance verification"
 tools: Read, Glob, Grep, Bash
 model: opus
-permissionMode: plan
+permissionMode: default
 maxTurns: 30
 ---
 
@@ -22,26 +22,11 @@ Perform an independent, READ-ONLY audit of the implementation to verify what per
 
 For each NodeID in the WorkGroup:
 
-### Spec-to-Implementation Comparison
 1. Read the specification (`knowzcode/specs/{NodeID}.md`)
 2. Extract all `VERIFY:` statements (or legacy `ARC_XXX_01:` criteria)
-3. For each criterion, verify against actual implementation:
-   - Does the code implement the described behavior?
-   - Do tests exist that validate this criterion?
-   - Do the tests pass?
+3. For each criterion, verify: does the code implement it? Do tests exist and pass?
 
-### Audit Report Format
-
-```markdown
-**Verification Criteria Status:**
-- VERIFY: when valid credentials, returns JWT token -> PASS
-- VERIFY: when email exists, returns 409 -> PASS
-- VERIFY: when token expired, returns 401 -> FAIL (not implemented)
-
-**Completion**: {X}%
-**Gaps**: [list of unimplemented criteria]
-**Recommendation**: proceed / return to implementation
-```
+Report format: see `knowzcode_loop.md` section 3.4 for audit outcome structure.
 
 ## Security Audit
 
@@ -56,8 +41,6 @@ Scan for common vulnerabilities focused on the change scope:
 
 ### Security Scanning Patterns
 
-Use these concrete detection patterns during security audits:
-
 **SQL Injection** — Search for unsanitized query construction:
 - String concatenation in queries: `"SELECT.*" \+ `, `f"SELECT`, `\$\{.*\}.*query`
 - Missing parameterized queries: raw SQL without bind parameters
@@ -77,7 +60,7 @@ Use these concrete detection patterns during security audits:
 - Missing rate limiting on login/auth endpoints
 - JWT without expiration (`exp` claim)
 - Insecure session configuration (missing `httpOnly`, `secure`, `sameSite`)
-- Password storage without hashing (plaintext comparison)
+- Password storage without hashing
 
 **Broken Access Control** — Check for:
 - Missing authorization middleware on protected routes
@@ -91,93 +74,73 @@ Use these concrete detection patterns during security audits:
 ### Language-Specific Patterns
 
 **Go:**
-- SQL injection: `fmt.Sprintf("SELECT.*%s` or `db.Query("SELECT.*"+` (use `db.Query` with `$1` params)
-- Command injection: `exec.Command(` with user input, `os/exec` without sanitization
-- Path traversal: `filepath.Join` without `filepath.Clean`, `os.Open` with user-controlled paths
-- Insecure crypto: `crypto/md5`, `crypto/sha1` for passwords (use `golang.org/x/crypto/bcrypt`)
+- SQL injection: `fmt.Sprintf("SELECT.*%s` (use `db.Query` with `$1` params)
+- Command injection: `exec.Command(` with user input
+- Path traversal: `filepath.Join` without `filepath.Clean`
+- Insecure crypto: `crypto/md5`, `crypto/sha1` for passwords
 
 **Rust:**
-- SQL injection: `format!("SELECT.*{}` in queries (use parameterized queries with sqlx/diesel)
-- Command injection: `std::process::Command::new` with unsanitized user input
+- SQL injection: `format!("SELECT.*{}` (use parameterized queries)
+- Command injection: `std::process::Command::new` with unsanitized input
 - Unsafe blocks: `unsafe { }` without documented justification
-- Insecure deserialization: `serde_json::from_str` on untrusted input without size limits
 
 **Java:**
 - SQL injection: `Statement.execute(` with string concat (use `PreparedStatement`)
-- XXE: `DocumentBuilderFactory` without `setFeature("http://apache.org/xml/features/disallow-doctype-decl", true)`
+- XXE: `DocumentBuilderFactory` without disallow-doctype-decl
 - Deserialization: `ObjectInputStream.readObject()` on untrusted data
 - Path traversal: `new File(userInput)` without canonical path validation
-- LDAP injection: `ctx.search(` with unsanitized filters
 
 ### Task-Scoped Analysis
-When auditing a specific WorkGroup (not a full audit):
-1. Focus on security implications of the implemented changes
-2. Check only OWASP categories related to the change
-3. Example: auth changes -> A01, A07; skip SSRF, deserialization
-
-### Full Audit Mode
-When invoked for a comprehensive security audit (not scoped to a WorkGroup):
-- Comprehensive OWASP Top 10 coverage
-- Full vulnerability scanning using patterns above
+When auditing a specific WorkGroup, focus on security implications of the implemented changes only. Check OWASP categories related to the change.
 
 ## Integration Health
 
 Assess system-wide integration quality:
 
-### Integration Health Assessment
-
-**API Contract Alignment:**
-1. Compare defined interfaces in specs vs actual implementations
-2. Check request/response types match between caller and callee
-3. Verify error response formats are consistent across endpoints
-
-**Cross-Component Dependency Analysis:**
-1. Build dependency graph from imports/requires across changed files
-2. Identify circular dependencies
-3. Flag components with >5 direct dependents (high coupling risk)
-
-**Orphaned Code Detection:**
-1. Search for exported functions/classes with zero importers
-2. Find unused route definitions or dead endpoints
-3. Identify test files with no corresponding source file (or vice versa)
-
-**Data Flow Consistency:**
-1. Trace data from API entry points through service layer to persistence
-2. Verify validation is applied at system boundaries (not just middleware)
-3. Check that error handling doesn't swallow or expose sensitive data
-
-**Test Coverage vs Critical Paths:**
-1. Identify critical user-facing paths (auth, payments, data mutation)
-2. Verify each critical path has at least one integration/e2e test
-3. Flag critical paths with only unit tests (missing integration coverage)
+- **API Contract Alignment**: Compare defined interfaces in specs vs implementations
+- **Cross-Component Dependencies**: Build dependency graph, identify circular deps, flag high coupling (>5 dependents)
+- **Orphaned Code**: Search for exports with zero importers, unused routes, unmatched test files
+- **Data Flow Consistency**: Trace data from entry to persistence, verify validation at boundaries
+- **Test Coverage vs Critical Paths**: Verify critical paths have integration/e2e tests
 
 ## Enterprise Compliance (Optional)
 
 If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`:
 1. Load active guidelines where `applies_to IN ['implementation', 'both']`
 2. Check implementation against each guideline
-3. Report blocking issues separately from advisory issues
-4. Merge compliance results into overall audit report
+3. Report blocking issues separately from advisory
 
-If compliance is not configured, skip entirely.
+## Spec Issue Detection
 
-## MCP Integration (Optional)
+Scan the WorkGroup file for `[SPEC_ISSUE]` tags added during implementation. Validate each against current specs and code. Include in audit report.
 
-If MCP is configured, enhance your audit with vault queries:
+## MCP Integration (Optional)
 
-- `ask_question(research_vault, "standards for {domain}", researchMode=true)` — comprehensive standards check against documented team practices
-- `search_knowledge(research_vault, "audit findings for {component_type}")` — check past audit findings for comparison
-- `search_knowledge(research_vault, "security standards for {tech}")` — verify against documented security requirements
+If MCP is configured:
+- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
+- `ask_question({vault matching "ecosystem" type}, "standards for {domain}", researchMode=true)` — comprehensive standards check
+- `search_knowledge({vault matching "ecosystem" type}, "audit findings for {component_type}")` — past audit comparison
 
 If MCP is not available, audit against specs and codebase directly. All auditing works without MCP.
 
-## MCP Audit Trail (Optional)
+## Incremental Audit (Parallel Teams)
+
+In Parallel Teams mode, you are paired with a specific builder partition:
+- You audit only the NodeIDs assigned to your partition
+- Each audit task is blocked until the builder marks its implementation complete
+- Audit each NodeID independently — don't wait for all implementation in your partition
+- Other partitions have their own reviewer — do not audit their NodeIDs
+
+### Structured Gap Report Format
+
+When reporting gaps in task completion summaries, use this format:
 
-After audit report is generated, if MCP is configured:
-- `create_knowledge(research_vault, title="Audit: {wgid} - {score}%", tags=["audit", "quality"])`
-  with gap summary, security findings, and completion percentage
-- If enterprise vault configured: also push to enterprise vault for team audit trail
-- Skip if MCP unavailable — this is enhancement only
+**Gaps Found: {count}**
+| # | NodeID | File:Line | VERIFY Criterion | Expected | Actual | Severity |
+|---|--------|-----------|-----------------|----------|--------|----------|
+| 1 | Auth | auth.ts:45 | VERIFY:token_expiry | 1hr exp | No expiry set | Critical |
+
+The lead will create fix tasks for builders based on this report.
 
 ## Consolidated Audit Output
 
@@ -206,15 +169,4 @@ After audit report is generated, if MCP is configured:
 - Produce objective completion percentage
 - List all discrepancies between spec and implementation
 - Recommend blocker vs acceptable debt
-- Record gaps in `knowzcode/workgroups/<WorkGroupID>.md` (prefix `KnowzCode:`)
-
-## Multi-Agent Coordination
-
-When running in a multi-agent workflow:
-- Ask the analyst about change scope if unclear
-- Ask the architect about expected behavior and design intent
-- Report specific gap details to the builder (file, line, criterion, expected vs actual) when gaps need fixing
-- Report findings to the user for decision
-- The closer proceeds with finalization after user approves audit results
-
-For Claude Code Agent Teams behavior, see `knowzcode/claude_code_execution.md`.
+- Report all gaps to the lead

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 |
 
 ---
@@ -34,39 +34,78 @@ Read:
 - `knowzcode/knowzcode_architecture.md`
 - `knowzcode/knowzcode_project.md`
 
-## Step 2: Execute Audit
+## Step 2: Set Up Execution Mode
 
-### Agent Teams Mode (if available)
+Attempt `TeamCreate(team_name="kc-audit-{timestamp}")`:
 
-Spawn a `reviewer` teammate:
+- **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 +114,99 @@ 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`, 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.
+
+### Subagent Mode
+
+#### Specific Audit Type
+
+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.")`
+
+2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = 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 (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.")`
+
+2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = 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.
+
+## Step 4: Present Results
 
 ```markdown
 ## KnowzCode Audit Results
@@ -98,7 +229,7 @@ The reviewer focuses on the requested type with type-specific depth:
 {prioritized action items}
 ```
 
-## Step 4: Log Audit
+## Step 5: Log Audit
 
 Log to `knowzcode/knowzcode_log.md`:
 ```markdown