knowzcode 0.2.1 → 0.3.3

package/commands/work.md

@@ -58,6 +58,26 @@ The user MUST see the execution mode announcement before any phase work begins.
 
 > **Note:** Agent Teams is experimental and the API may change.
 
+## Step 2.4: Load Orchestration Config (Optional)
+
+If `knowzcode/knowzcode_orchestration.md` exists, parse its YAML blocks:
+
+1. `MAX_BUILDERS` = `max_builders` value (default: 5, clamp to 1-5)
+2. `SCOUT_MODE` = `scout_mode` value (default: "full")
+3. `DEFAULT_SPECIALISTS` = `default_specialists` value (default: [])
+4. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
+5. `CODEBASE_SCANNER_ENABLED` = `codebase_scanner_enabled` value (default: true)
+6. `PARALLEL_SPEC_THRESHOLD` = `parallel_spec_threshold` value (default: 3, clamp to 2-10)
+
+Apply flag overrides (flags win over config):
+- `--max-builders=N` in `$ARGUMENTS` → override `MAX_BUILDERS`
+- `--no-scouts` in `$ARGUMENTS` → override `SCOUT_MODE = "none"`
+- `--no-mcp` in `$ARGUMENTS` → override `MCP_AGENTS_ENABLED = false`
+- `--no-scanners` in `$ARGUMENTS` → override `CODEBASE_SCANNER_ENABLED = false`
+- `--no-parallel-specs` in `$ARGUMENTS` → override `PARALLEL_SPEC_THRESHOLD = 999` (effectively disabled)
+
+If the file doesn't exist, use hardcoded defaults (current behavior).
+
 ## Step 2.5: Autonomous Mode Detection
 
 Set `AUTONOMOUS_MODE = true` if ANY of these match:
@@ -78,6 +98,37 @@ If `AUTONOMOUS_MODE = true`, announce after the execution mode announcement:
 > **Autonomous Mode: ACTIVE** — Gates presented for transparency but auto-approved.
 > Safety exceptions still pause: critical blockers, HIGH/CRITICAL security findings, >3 same-phase failures, complex architecture discrepancies, >3 gap-fix iterations per partition.
 
+## Step 2.6: Specialist Detection
+
+Set `SPECIALISTS_ENABLED = []` (empty list).
+
+If `DEFAULT_SPECIALISTS` is non-empty (from Step 2.4), initialize:
+`SPECIALISTS_ENABLED = DEFAULT_SPECIALISTS`
+
+Determine which specialists to activate (flags and natural language add to or override the baseline):
+- `--specialists` → enable all 3: `[security-officer, test-advisor, project-advisor]`
+- `--specialists=csv` → enable specific subset (comma-separated, e.g., `--specialists=security,test`):
+  - `security` → `security-officer`
+  - `test` → `test-advisor`
+  - `project` → `project-advisor`
+- `--no-specialists` → explicit opt-out, `SPECIALISTS_ENABLED = []`
+
+**Natural language detection** (case-insensitive match in `$ARGUMENTS` OR the user's preceding conversation message):
+- All specialists: "with specialists", "with officers", "full specialist panel"
+- security-officer: "security review", "threat model", "vulnerability scan", "pentest"
+- test-advisor: "test quality", "TDD enforcement", "test coverage", "test rigor"
+- project-advisor: "backlog", "future work", "brainstorm", "ideas"
+
+**Mode constraints:**
+- Tier 3 Parallel Teams: Full support (Group C)
+- Tier 3 Subagent Delegation: Supported via parallel `Task()` calls
+- Sequential Teams / Tier 2: Not supported — if specialists were detected, announce: `> **Specialists: SKIPPED** — not supported in {Sequential Teams / Tier 2} mode.`
+
+Default: `SPECIALISTS_ENABLED = []` (specialists are opt-in).
+
+If `SPECIALISTS_ENABLED` is non-empty, announce after the autonomous mode announcement (or after the execution mode announcement if autonomous is not active):
+> **Specialists: ACTIVE** — {comma-separated list of enabled specialists}
+
 ## Step 3: Load Context Files (ONCE)
 
 Read these files ONCE (do NOT re-read between phases):
@@ -136,6 +187,9 @@ Assess the goal against the codebase to determine the appropriate workflow tier.
 - Single file, <50 lines, no ripple effects
 
 ### Tier 2: Light (2-phase workflow)
+
+> **Note:** Light mode does not use orchestration config — single builder, no scouts, no specialists.
+
 ALL must be true:
 - ≤3 files touched
 - Single NodeID (1 new capability)
@@ -293,55 +347,99 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
       - `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)**`
-4. **Spawn Group A** (always — 5 agents):
+4. **Spawn Group A**:
    Create tasks first, pre-assign, then spawn with task IDs:
-   - `TaskCreate("Scout: specs context")` → `TaskUpdate(owner: "context-scout-specs")`
-   - `TaskCreate("Scout: workgroups context")` → `TaskUpdate(owner: "context-scout-workgroups")`
-   - `TaskCreate("Scout: backlog context")` → `TaskUpdate(owner: "context-scout-backlog")`
-   - `TaskCreate("Phase 1A: Impact analysis for {goal}")` → `TaskUpdate(owner: "analyst")`
-   - `TaskCreate("Pre-load architecture context")` → `TaskUpdate(owner: "architect")`
-   Spawn all 5 agents with their `{task-id}` in the spawn prompt (use spawn prompts from Phase Prompt Reference below).
-5. **Spawn Group B** (MCP agents — same turn as Group A): If `VAULTS_CONFIGURED = true`:
+   - If `SCOUT_MODE = "full"` (default): spawn 3 context scouts (specs, workgroups, backlog) + analyst + architect (5 agents):
+     - `TaskCreate("Scout: specs context")` → `TaskUpdate(owner: "context-scout-specs")`
+     - `TaskCreate("Scout: workgroups context")` → `TaskUpdate(owner: "context-scout-workgroups")`
+     - `TaskCreate("Scout: backlog context")` → `TaskUpdate(owner: "context-scout-backlog")`
+   - If `SCOUT_MODE = "minimal"`: spawn 1 context-scout (combined scan) + analyst + architect (3 agents):
+     - `TaskCreate("Scout: combined context")` → `TaskUpdate(owner: "context-scout")`
+   - If `SCOUT_MODE = "none"`: spawn analyst + architect only (2 agents). Analyst and architect scan the codebase independently without pre-loaded scout context.
+   - Always:
+     - `TaskCreate("Phase 1A: Impact analysis for {goal}")` → `TaskUpdate(owner: "analyst")`
+     - `TaskCreate("Pre-load architecture context and speculative research")` → `TaskUpdate(owner: "architect")`
+   - If `CODEBASE_SCANNER_ENABLED = true` (default):
+     - Derive two search focuses from the goal:
+       - **Scanner-Direct**: source code search — grep for goal keywords, read affected code paths
+       - **Scanner-Tests**: test discovery — search test directories for tests covering the goal area
+     - `TaskCreate("Scanner: direct codebase scan for {goal}")` → `TaskUpdate(owner: "scanner-direct")`
+     - `TaskCreate("Scanner: test coverage scan for {goal}")` → `TaskUpdate(owner: "scanner-tests")`
+   Spawn all Group A agents with their `{task-id}` in the spawn prompt (use spawn prompts from Phase Prompt Reference below).
+5. **Spawn Group B** (MCP agents — same turn as Group A): If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`:
    Create tasks first, pre-assign, then spawn with task IDs:
    - `TaskCreate("Knowz-scout: vault queries")` → `TaskUpdate(owner: "knowz-scout")`
    - `TaskCreate("Knowz-scribe: listen")` → `TaskUpdate(owner: "knowz-scribe")`
    Spawn both agents with their `{task-id}` in the spawn prompt.
-   If `VAULTS_CONFIGURED = false`, skip Group B and log: `Vault agents skipped — no vaults configured.`
-6. **Roster confirmation** — lead lists every spawned agent by name to the user. If `VAULTS_CONFIGURED` was true but knowz-scout or knowz-scribe is missing from the roster, STOP and re-spawn the missing agent(s) before continuing.
-7. All 5-7 agents work immediately in parallel (3 context scouts are cheap Sonnet read-only agents; knowz-scribe is a cheap Haiku agent)
-8. Scouts broadcast findings → analyst and architect consume as messages
+   If `VAULTS_CONFIGURED = false` or `MCP_AGENTS_ENABLED = false`, skip Group B and log: `Vault agents skipped — no vaults configured` or `Vault agents skipped — MCP agents disabled in orchestration config.`
+6. **Spawn Group C** (specialist agents — same turn as Groups A and B): If `SPECIALISTS_ENABLED` is non-empty:
+   Create tasks first, pre-assign, then spawn with task IDs:
+   - If `security-officer` in list: `TaskCreate("Security officer: initial threat scan")` → `TaskUpdate(owner: "security-officer")`
+   - If `test-advisor` in list: `TaskCreate("Test advisor: coverage baseline")` → `TaskUpdate(owner: "test-advisor")`
+   - If `project-advisor` in list: `TaskCreate("Project advisor: backlog context")` → `TaskUpdate(owner: "project-advisor")`
+   Spawn each enabled specialist with its `{task-id}` in the spawn prompt (use spawn prompts from Specialist Spawn Prompts section below).
+   If `SPECIALISTS_ENABLED` is empty, skip Group C.
+7. **Roster confirmation** — lead lists every spawned agent by name to the user. Include scanners and Group C specialists if active. If `VAULTS_CONFIGURED` was true but knowz-scout or knowz-scribe is missing from the roster, STOP and re-spawn the missing agent(s) before continuing.
+8. All spawned agents work immediately in parallel (context scouts are cheap Sonnet read-only agents; scanners are lightweight general-purpose agents; knowz-scribe is a cheap Haiku agent; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-12 agents at Stage 0.
+9. Scouts broadcast findings → analyst and architect consume as messages. Specialists work independently on their Stage 0 tasks.
 
-**Key**: The analyst does NOT wait for scouts to finish. It starts scanning the codebase immediately. Scout findings arrive as messages and enrich the analyst's work as they arrive.
+**Key**: The analyst does NOT wait for scouts, scanners, or specialists to finish. It starts scanning the codebase immediately. Scout and scanner findings arrive as messages and enrich the analyst's work as they arrive. The analyst also streams `[PRELIMINARY]` NodeID findings to the architect as it discovers them (see Preliminary Findings Protocol). Specialist findings are consumed by the lead at gates.
 
 ### Stage 1: Analysis + Specification
 
 1. Analyst completes Change Set (includes dependency map — see `agents/analyst.md`)
 2. Lead reads analyst's task summary
-3. Lead presents **Quality Gate #1** to user:
+3. Shut down scanners (scanner-direct, scanner-tests) if they were spawned — no longer needed after analysis
+3. **Specialist Change Set reviews** (if `SPECIALISTS_ENABLED` non-empty): Create review tasks blocked on analysis:
+   - If `security-officer` active: `TaskCreate("Security officer: Change Set review", addBlockedBy: [analysis-task-id])` → `TaskUpdate(owner: "security-officer")`. DM security-officer: `"**New Task**: #{task-id} — Review Change Set for security risk. Rate each NodeID."`
+   - If `test-advisor` active: `TaskCreate("Test advisor: Change Set test strategy", addBlockedBy: [analysis-task-id])` → `TaskUpdate(owner: "test-advisor")`. DM test-advisor: `"**New Task**: #{task-id} — Recommend test types per NodeID."`
+4. Lead presents **Quality Gate #1** to user:
    - Change Set with NodeIDs, descriptions, affected files
    - Dependency map showing which NodeIDs can be implemented in parallel
    - Risk assessment
-4. User approves (or rejects → re-run analyst with feedback)
-5. Lead sends DM to architect with the approved Change Set
-6. Lead creates spec-drafting tasks for architect (1 task per NodeID, `addBlockedBy: [analysis-task-id]`):
-   - `TaskCreate("Spec: NodeID-X")` → `TaskUpdate(taskId, owner: "architect")`
-   - DM architect with task IDs: `"**New Tasks**: #{id-1} Spec: NodeID-A, #{id-2} Spec: NodeID-B. Approved Change Set: {summary}"`
-   - Architect is already warm (pre-loaded during Stage 0) → specs drafted FAST
+   - Specialist Reports (if active — see gate template below)
+5. User approves (or rejects → re-run analyst with feedback)
+6. Lead sends DM to architect with the approved Change Set
+7. **Spec Drafting** — choose path based on NodeID count and `PARALLEL_SPEC_THRESHOLD`:
+
+   **Path A: Standard (fewer than PARALLEL_SPEC_THRESHOLD NodeIDs)**
+   - Lead creates spec-drafting tasks for architect (1 task per NodeID, `addBlockedBy: [analysis-task-id]`):
+     - `TaskCreate("Spec: NodeID-X")` → `TaskUpdate(taskId, owner: "architect")`
+     - DM architect with task IDs: `"**New Tasks**: #{id-1} Spec: NodeID-A, #{id-2} Spec: NodeID-B. Approved Change Set: {summary}"`
+   - Architect is already warm (pre-loaded + speculative research during Stage 0) → specs drafted FAST
    - If Gate #1 rejected: shut down architect, re-run analyst with feedback, re-spawn architect after
-7. Architect completes specs
-8. Lead presents **Quality Gate #2** to user:
-   - Spec summaries with VERIFY criteria
-9. User approves (or rejects → architect revises)
-10. Pre-implementation commit: `git add knowzcode/ && git commit -m "KnowzCode: Specs approved for {wgid}"`
-11. Shut down context-scouts (no longer needed after specs approved). Keep knowz-scout alive for vault queries during implementation.
-12. Keep analyst alive briefly (available for scope questions during early implementation)
-13. Keep architect alive through Stage 2 (consultative role — spec clarifications for builders, no code or spec edits)
+
+   **Path B: Parallel Spec Drafting (PARALLEL_SPEC_THRESHOLD or more NodeIDs)**
+   - Lead DMs architect the full approved Change Set and asks for a partition plan (see `agents/architect.md` — Parallel Spec Coordination)
+   - Architect proposes NodeID partitions (1-2 NodeIDs each, max 3 partitions, respecting same-spec and interface constraints)
+   - Lead spawns spec-drafter agents — one per partition:
+     - Spec-drafters use the `architect` agent definition with a scoped spawn prompt
+     - Each drafter gets: its NodeID partition, architect's research findings, cross-NodeID interface constraints, consolidation instructions
+     - `TaskCreate("Spec draft: NodeID-A, NodeID-B")` → `TaskUpdate(owner: "spec-drafter-1")`
+     - Max 3 spec-drafters: `ceil(NodeID_count / 2)`, capped at 3
+   - Spec-drafters draft specs in parallel
+   - After all spec-drafters complete: architect runs consistency review (cross-spec alignment, naming, VERIFY coverage)
+   - Shut down spec-drafters after consistency review
+   - If Gate #1 rejected: shut down architect and any spec-drafters, re-run analyst with feedback, re-spawn architect after
+
+8. Architect completes specs (Path A) or architect completes consistency review (Path B)
+9. **Test-advisor spec review** (if `test-advisor` in `SPECIALISTS_ENABLED`): After specs drafted, create spec testability review task:
+   - `TaskCreate("Test advisor: spec testability review", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "test-advisor")`
+   - DM test-advisor: `"**New Task**: #{task-id} — Review specs for testability. Check VERIFY criteria are automatable."`
+10. Lead presents **Quality Gate #2** to user:
+    - Spec summaries with VERIFY criteria
+    - Specialist Reports (if active — see gate template below)
+11. User approves (or rejects → architect revises)
+12. Pre-implementation commit: `git add knowzcode/ && git commit -m "KnowzCode: Specs approved for {wgid}"`
+13. Shut down context-scouts (no longer needed after specs approved). Keep knowz-scout alive for vault queries during implementation.
+14. Keep analyst alive briefly (available for scope questions during early implementation)
+15. Keep architect alive through Stage 2 (consultative role — spec clarifications for builders, no code or spec edits)
 
 ### Stage 2: Parallel Implementation + Incremental Review
 
 1. Lead examines dependency map from analyst:
    - Group NodeIDs into independent partitions (no shared files between groups)
-   - Determine builder count: 1 builder per independent group, max 5
+   - Determine builder count: 1 builder per independent group, max `MAX_BUILDERS` (default 5, configurable in `knowzcode_orchestration.md`)
 
 2. Create builder tasks and spawn:
    - `TaskCreate("Implement NodeIDs [A, B]", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "builder-1")`
@@ -367,7 +465,20 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    Reviewer stays idle until its paired builder marks first NodeID implementation complete.
    Each reviewer audits incrementally within its partition.
 
-6. Gap flow (per-partition, parallel — persistent agents, DM messaging):
+6. **Specialist implementation reviews** (if `SPECIALISTS_ENABLED` non-empty): Create specialist review tasks alongside reviewer audit tasks, same `addBlockedBy`:
+   - If `security-officer` active — one task per partition (runs parallel to reviewer):
+     `TaskCreate("Security officer: review partition {N}", addBlockedBy: [implement-X-task-id])` → `TaskUpdate(owner: "security-officer")`
+     DM security-officer: `"**New Task**: #{task-id} — Vulnerability scan for partition {N}. NodeIDs: {list}."`
+   - If `test-advisor` active — one task per partition:
+     `TaskCreate("Test advisor: review partition {N} tests", addBlockedBy: [implement-X-task-id])` → `TaskUpdate(owner: "test-advisor")`
+     DM test-advisor: `"**New Task**: #{task-id} — Test quality review for partition {N}. NodeIDs: {list}."`
+   - If `project-advisor` active — one observation task (not per-partition):
+     `TaskCreate("Project advisor: observe implementation")` → `TaskUpdate(owner: "project-advisor")`
+     DM project-advisor: `"**New Task**: #{task-id} — Observe builder progress, note patterns and ideas. Deliver backlog proposals before gap loop."`
+   **Gate #3 is NOT blocked by specialists.** If a specialist hasn't finished, gate shows `[Pending: {specialist}]`. Lead proceeds.
+   **Project-advisor early shutdown**: After project-advisor delivers backlog proposals, shut it down (before the gap loop begins).
+
+7. Gap flow (per-partition, parallel — persistent agents, DM messaging):
    a. Each reviewer marks audit task complete with structured gap report in summary
    b. Lead creates fix task and pre-assigns:
       `TaskCreate("Fix gaps: NodeID-A", addBlockedBy: [audit-task-id])` → `TaskUpdate(owner: "builder-N")`
@@ -382,12 +493,12 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    g. Each builder-reviewer pair repeats independently until clean — no cross-partition blocking
    — All builders and reviewers stay alive through the entire gap loop (no respawning)
 
-7. Enterprise compliance (if enabled):
+8. Enterprise compliance (if enabled):
    - Lead creates parallel compliance task for each reviewer (scoped to their partition)
    - Reviewer checks compliance requirements from knowz-scout findings
    - Runs alongside ARC audits
 
-8. Inter-agent communication during Stage 2:
+9. Inter-agent communication during Stage 2:
    - builder → architect: Spec clarification requests (direct messages)
    - architect → builder: Design guidance and spec intent responses (direct messages)
    - builder ↔ builder: Dependency coordination (direct messages — "I changed the User interface, FYI")
@@ -395,23 +506,31 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - reviewer → lead: Gap reports per partition (structured format via task summaries)
    - lead → builder: Fix tasks (via task creation + DM)
    - lead → reviewer: Re-audit requests (via task creation + DM)
-
-9. After all NodeIDs implemented + audited across all partitions:
-   - Lead consolidates audit results from all reviewers
-   - Lead presents **Quality Gate #3**:
-     - Per-NodeID ARC completion % (from each partition's reviewer)
-     - Combined security posture
-     - Combined integration health
-     - Enterprise compliance (if applicable)
-   - User decides: proceed / fix gaps / modify specs / cancel
-
-10. Shut down analyst, architect, all builders, and all reviewers
+   - security-officer → builder-N: Security guidance for sensitive partitions (max 2 DMs per builder)
+   - test-advisor → builder-N: Test improvement feedback (max 2 DMs per builder)
+   - security-officer ↔ test-advisor: Cross-cutting test gaps in security paths (max 2 inter-specialist DMs)
+   - project-advisor → knowz-scribe: Idea captures for vault storage
+   - project-advisor → lead: Backlog proposals (before gap loop)
+
+10. After all NodeIDs implemented + audited across all partitions:
+    - Lead consolidates audit results from all reviewers
+    - Lead consolidates specialist reports (if `SPECIALISTS_ENABLED` non-empty — include even if some specialist tasks are still pending, noting `[Pending: {specialist}]`)
+    - Lead presents **Quality Gate #3**:
+      - Per-NodeID ARC completion % (from each partition's reviewer)
+      - Combined security posture
+      - Combined integration health
+      - Enterprise compliance (if applicable)
+      - Specialist Reports (if active — see gate template below)
+    - User decides: proceed / fix gaps / modify specs / cancel
+
+11. Shut down analyst, architect, all builders, and all reviewers
 
 ### Stage 3: Finalization
 
-1. `TaskCreate("Phase 3: Finalize {wgid}", addBlockedBy: [last-audit-task-id])` → `TaskUpdate(owner: "closer")`
+1. Shut down remaining specialists (security-officer, test-advisor) if still active. Project-advisor should already be shut down from mid-Stage 2.
+2. `TaskCreate("Phase 3: Finalize {wgid}", addBlockedBy: [last-audit-task-id])` → `TaskUpdate(owner: "closer")`
    Spawn `closer` with `{task-id}` in spawn prompt.
-2. Closer tasks (can be parallel subtasks):
+3. Closer tasks (can be parallel subtasks):
    - Update all specs to FINAL as-built
    - Update `knowzcode_tracker.md`: all NodeIDs `[WIP]` → `[VERIFIED]`
    - Write ARC-Completion log entry
@@ -419,9 +538,9 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - Schedule REFACTOR tasks for tech debt
    - Send learnings to knowz-scribe (if active): `"Capture Phase 3: {wgid}"`. Knowz-scout remains available for vault queries during finalization.
    - Create final atomic commit
-3. Lead presents completion summary
-4. Shut down knowz-scout, knowz-scribe (after Phase 3 capture completes), closer, and all remaining agents
-5. Delete team
+4. Lead presents completion summary
+5. Shut down knowz-scout, knowz-scribe (after Phase 3 capture completes), closer, and all remaining agents
+6. Delete team
 
 ### WorkGroup File Format (Parallel Mode)
 
@@ -453,11 +572,23 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 | Scout: backlog context | (none) | context-scout-backlog |
 | Knowz-scout: vault queries | (none — persistent) | knowz-scout |
 | Knowz-scribe: listen | (none — persistent) | knowz-scribe |
-| Phase 1A analysis | (none — scouts enrich via broadcast) | analyst |
-| Architect pre-load | (none) | architect |
-| Spec: NodeID-X | Phase 1A (gate approval) | architect |
+| Scanner: direct codebase scan | (none) | scanner-direct |
+| Scanner: test coverage scan | (none) | scanner-tests |
+| Phase 1A analysis | (none — scouts + scanners enrich via broadcast) | analyst |
+| Architect pre-load + speculative research | (none — receives [PRELIMINARY] DMs from analyst) | architect |
+| Security officer: initial threat scan | (none — Group C) | security-officer |
+| Test advisor: coverage baseline | (none — Group C) | test-advisor |
+| Project advisor: backlog context | (none — Group C) | project-advisor |
+| Security officer: Change Set review | Phase 1A analysis | security-officer |
+| Test advisor: Change Set test strategy | Phase 1A analysis | test-advisor |
+| Spec: NodeID-X | Phase 1A (gate approval) | architect (Path A) or spec-drafter-N (Path B) |
+| Spec consistency review | All spec drafts complete (Path B only) | architect |
+| Test advisor: spec testability review | Spec: NodeID-X | test-advisor |
 | Implement: NodeID-X | Spec: NodeID-X | builder-N |
 | Audit: NodeID-X | Implement: NodeID-X | reviewer-N |
+| Security officer: review partition N | Implement: NodeID-X | security-officer |
+| Test advisor: review partition N tests | Implement: NodeID-X | test-advisor |
+| Project advisor: observe implementation | (none) | project-advisor |
 | Fix gaps: NodeID-X round N | Audit: NodeID-X (or re-audit N-1) | builder-N |
 | Re-audit: NodeID-X round N | Fix gaps round N | reviewer-N |
 | Phase 3 finalization | All audits approved | closer |
@@ -466,6 +597,8 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 
 ## Sequential Teams / Subagent Flow (Tier 3 Fallback)
 
+> **Note:** Sequential Teams does not use orchestration config settings except `MCP_AGENTS_ENABLED`.
+
 When using Sequential Teams (`--sequential`) or Subagent Delegation, follow the traditional one-agent-per-phase flow. For each phase below: spawn the agent, create a task, wait for completion, present quality gate, shut down agent, proceed to next phase.
 
 ---
@@ -507,10 +640,70 @@ Three instances of the same agent, each focused on a different local folder grou
 > **READ-ONLY.** Do NOT modify any files.
 > **Deliverable**: Broadcast active WIP, REFACTOR tasks, architecture summary, and recent log patterns relevant to goal.
 
+**context-scout (combined) spawn prompt** (used when `SCOUT_MODE = "minimal"`):
+> You are `context-scout` for WorkGroup `{wgid}`.
+> Read `agents/context-scout.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately. Mark completed with summary when done.
+> **Focus area**: 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`
+> **Goal**: {goal}
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast consolidated findings covering specs, prior workgroups, active WIP, REFACTOR tasks, and architecture context.
+
 **Dispatch**:
-- *Parallel Teams*: All 3 context scouts spawned at Stage 0, no blockedBy. Shut down after Gate #2 (specs approved).
+- *Parallel Teams*:
+  - `SCOUT_MODE = "full"`: 3 context scouts spawned at Stage 0. Shut down after Gate #2.
+  - `SCOUT_MODE = "minimal"`: 1 context-scout (combined) spawned at Stage 0. Shut down after Gate #2.
+  - `SCOUT_MODE = "none"`: No scouts spawned.
 - *Sequential Teams*: Not applicable (scouts are Parallel Teams only).
-- *Subagent*: `Task(subagent_type="context-scout", name="context-scout-specs", ...)`, `Task(subagent_type="context-scout", name="context-scout-workgroups", ...)`, `Task(subagent_type="context-scout", name="context-scout-backlog", ...)`
+- *Subagent*:
+  - `SCOUT_MODE = "full"`: 3 parallel `Task()` calls (specs, workgroups, backlog).
+  - `SCOUT_MODE = "minimal"`: 1 `Task()` call with combined prompt.
+  - `SCOUT_MODE = "none"`: Skip scout tasks.
+
+---
+
+## Stage 0: Codebase Scanners (2 instances — conditional)
+
+**Agent**: `general-purpose` (x2) | Lightweight codebase searchers (no agent definition file)
+
+Two temporary agents that scan the codebase in parallel with the analyst, broadcasting findings to accelerate impact analysis. Only spawned when `CODEBASE_SCANNER_ENABLED = true` (default).
+
+**scanner-direct spawn prompt**:
+> You are `scanner-direct` for WorkGroup `{wgid}`.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Focus**: Search source code for goal-related keywords and patterns.
+>
+> **Steps**:
+> 1. Grep for goal keywords across source files (exclude node_modules, dist, build, .git)
+> 2. Read the top 5-8 matching files to understand affected code paths
+> 3. Identify module boundaries and cross-module dependencies
+> 4. Note public APIs and interfaces that may need changes
+>
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast findings to all teammates — affected files, code paths, module boundaries, and interface patterns.
+> **Budget**: Complete within ~12 turns. Focus on breadth over depth.
+
+**scanner-tests spawn prompt**:
+> You are `scanner-tests` for WorkGroup `{wgid}`.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Focus**: Discover tests covering the goal area to understand test patterns and coverage shape.
+>
+> **Steps**:
+> 1. Glob for test files: `**/*.test.*`, `**/*.spec.*`, `**/test_*`, `**/tests/**`
+> 2. Grep test files for goal-related keywords
+> 3. Read 3-5 matching test files to understand testing patterns (test framework, mocking strategy, fixture patterns)
+> 4. Check for integration/e2e tests related to the goal area
+>
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast findings to all teammates — test file locations, testing patterns, coverage gaps, and fixture/mock patterns.
+> **Budget**: Complete within ~12 turns. Focus on breadth over depth.
+
+**Dispatch**:
+- *Parallel Teams*: Spawned at Stage 0 if `CODEBASE_SCANNER_ENABLED = true`. Use `subagent_type: "general-purpose"`, `maxTurns: 12`. Shut down after Stage 1 (analyst completes Change Set).
+- *Sequential Teams*: Not applicable (scanners are Parallel Teams only).
+- *Subagent*: `Task(subagent_type="general-purpose", description="Scan codebase for {focus}", maxTurns=12, prompt=<above>)` if `CODEBASE_SCANNER_ENABLED = true`.
 
 ---
 
@@ -554,6 +747,61 @@ Three instances of the same agent, each focused on a different local folder grou
 
 ---
 
+## Specialist Spawn Prompts (Group C — opt-in via `--specialists`)
+
+The spawn prompts below are used when `SPECIALISTS_ENABLED` is non-empty. Specialists are spawned at Stage 0 alongside Groups A and B.
+
+**Dispatch** (all specialists):
+- *Parallel Teams*: Group C — spawned at Stage 0 if `SPECIALISTS_ENABLED` non-empty, no blockedBy. Security-officer and test-advisor persist through Gate #3. Project-advisor shuts down mid-Stage 2.
+- *Sequential Teams*: Not supported — announce skip reason.
+- *Subagent*: `Task()` calls with spawn prompts below.
+
+### Security Officer
+
+**Agent**: `security-officer` | Officer — CRITICAL/HIGH findings block gates
+
+**Spawn prompt**:
+> You are the **security-officer** for WorkGroup `{wgid}`.
+> Read `agents/security-officer.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **READ-ONLY.** Do NOT modify any files. Bash is for read-only security scanning only.
+> **Stage 0 Deliverable**: Build STRIDE-lite threat model. Scan for auth/PII/crypto/session patterns. Broadcast initial threat assessment.
+> **Authority**: CRITICAL/HIGH findings use `[SECURITY-BLOCK]` tag — lead MUST pause autonomous mode.
+> **Communication**: DM lead at gates. DM architect with security VERIFY criteria needs. DM builders in security-sensitive partitions (max 2 per builder). DM test-advisor for cross-cutting test gaps (max 2).
+> **Enterprise Compliance**: If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`, read active security guidelines and cross-reference findings with enterprise guideline IDs.
+
+### Test Advisor
+
+**Agent**: `test-advisor` | Advisor — informational only
+
+**Spawn prompt**:
+> You are the **test-advisor** for WorkGroup `{wgid}`.
+> Read `agents/test-advisor.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **READ-ONLY.** Do NOT modify any files. Bash is for read-only operations only (git log, coverage reports).
+> **Stage 0 Deliverable**: Establish test coverage baseline. Glob test files, run coverage if available. Broadcast baseline.
+> **Communication**: DM lead at gates. DM architect if VERIFY criteria aren't testable. DM builders with test improvement feedback (max 2 per builder). DM security-officer for cross-cutting security test gaps (max 2).
+> **Enterprise Compliance**: If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`, check enterprise ARC criteria for test coverage gaps.
+
+### Project Advisor
+
+**Agent**: `project-advisor` | Advisor — informational only
+
+**Spawn prompt**:
+> You are the **project-advisor** for WorkGroup `{wgid}`.
+> Read `agents/project-advisor.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **READ-ONLY.** Do NOT modify any files.
+> **Stage 0 Deliverable**: Read tracker for existing REFACTOR tasks and backlog context. DM lead with context summary.
+> **Lifecycle**: You shut down mid-Stage 2 after delivering backlog proposals — before the gap loop.
+> **Communication**: DM lead with backlog context and proposals. DM knowz-scribe with idea captures (if active). Do NOT DM builders or other specialists.
+> **Enterprise Compliance**: If `knowzcode/enterprise/compliance_manifest.md` exists, note compliance configuration gaps in backlog proposals.
+
+---
+
 ## Phase 1A: Impact Analysis
 
 **Agent**: `analyst` | **Loop.md**: Section 3.1
@@ -568,10 +816,12 @@ Three instances of the same agent, each focused on a different local folder grou
 >
 > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
+> **Codebase scanners**: Scanner agents are running in parallel — their findings will arrive as broadcast messages. Incorporate them into your analysis but do NOT wait for them.
+> **Preliminary Findings Protocol**: As you discover high-confidence NodeIDs, DM the architect with `[PRELIMINARY]` messages (max 3 — see `agents/analyst.md` for format). This lets the architect start speculative research early.
 > **Deliverable**: Change Set proposal written to the WorkGroup file. Include NodeIDs, descriptions, affected files, risk assessment, and dependency map (for Parallel Teams mode).
 
 **Dispatch**:
-- *Parallel Teams*: Spawned at Stage 0 alongside scouts and architect. Starts immediately (no blockedBy).
+- *Parallel Teams*: Spawned at Stage 0 alongside scouts, scanners, and architect. Starts immediately (no blockedBy).
 - *Sequential Teams*: Spawn teammate `analyst`, create task `Phase 1A: Impact analysis for "{goal}"`, wait for completion.
 - *Subagent*: `Task(subagent_type="analyst", description="Phase 1A impact analysis", prompt=<above>)`
 
@@ -591,6 +841,11 @@ Present the Change Set for user approval:
 
 **Risk Assessment**: {Low/Medium/High}
 
+### Specialist Reports                    [only when SPECIALISTS_ENABLED non-empty]
+**Security Officer**: {risk assessment per NodeID, attack surface changes, threat model}
+**Architect**: {architecture impact, layer touch points, pattern alignment}
+**Test Advisor**: {coverage baseline, test strategy recommendations per NodeID}
+
 Approve this Change Set to proceed to specification?
 ```
 
@@ -606,11 +861,34 @@ If MCP is configured and knowz-scribe is active, after Change Set approval:
 
 ---
 
+## Stage 0: Architect Pre-load (Parallel Teams)
+
+**Agent**: `architect` | Spawned at Stage 0 for context pre-loading and speculative research
+
+In Parallel Teams mode, the architect is spawned at Stage 0 (not at Phase 1B). It pre-loads architecture context and performs speculative research on `[PRELIMINARY]` NodeIDs from the analyst.
+
+**Stage 0 spawn prompt** (Parallel Teams only):
+> You are the **architect** for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition.
+>
+> **Goal**: {goal}
+> **Context files**: Read sections 1-2 and 3.2 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Stage 0 Role**: Pre-load architecture context, then perform speculative research on any `[PRELIMINARY]` NodeID messages from the analyst (see Speculative Research Protocol in `agents/architect.md`). READ-ONLY research — do NOT write specs yet.
+> **Lifecycle**: You persist through the entire workflow. After Gate #1, you will receive spec-drafting tasks via DM. After Gate #2, you shift to consultative role for builders.
+
+After Gate #1, the lead sends the approved Change Set via DM and creates spec-drafting tasks. For spec-drafting prompts, see Phase 1B below.
+
+---
+
 ## Phase 1B: Specification
 
 **Agent**: `architect` | **Loop.md**: Section 3.2
 
-**Spawn prompt**:
+**Spec-drafting prompt** (sent via DM to already-warm architect in Parallel Teams, or as spawn prompt in Sequential/Subagent):
 > You are the **architect** for WorkGroup `{wgid}`.
 > Read `agents/architect.md` for your full role definition.
 >
@@ -624,12 +902,29 @@ If MCP is configured and knowz-scribe is active, after Change Set approval:
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
 > **Deliverable**: Finalized specs for all NodeIDs written to `knowzcode/specs/`.
 
+**Spec-drafter spawn prompt** (Path B — 3+ NodeIDs, Parallel Teams only):
+> You are `spec-drafter-{N}` for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition — you follow the same Spec Philosophy, Spec Format, and Consolidation Mandate.
+>
+> **Goal**: {goal}
+> **Your NodeIDs**: {partition — 1-2 NodeIDs assigned to this drafter}
+> **Architect Research**: {research findings from architect's speculative research for these NodeIDs}
+> **Cross-NodeID Constraints**: {interface dependencies, shared specs, naming conventions from architect}
+> **Context files**: Read sections 1-2 and 3.2 of `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Deliverable**: Draft specs for your assigned NodeIDs written to `knowzcode/specs/`. The architect will review for consistency after all drafters finish.
+
 **Dispatch**:
-- *Parallel Teams*: Architect is already warm from Stage 0 pre-load. Lead sends DM with approved Change Set, then creates spec-drafting tasks. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Architect plan`.
+- *Parallel Teams*:
+  - **Path A** (< PARALLEL_SPEC_THRESHOLD NodeIDs): Architect is already warm from Stage 0 pre-load + speculative research. Lead sends DM with approved Change Set, then creates spec-drafting tasks. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Architect plan`.
+  - **Path B** (>= PARALLEL_SPEC_THRESHOLD NodeIDs): Lead asks architect for partition plan. Architect proposes partitions. Lead spawns spec-drafters (`subagent_type: "architect"`, `permissionMode: "acceptEdits"`, `maxTurns: 15`) with partition-scoped prompts. After all drafters complete, architect runs consistency review and reports to lead.
 - *Sequential Teams*: Spawn teammate `architect`, create task `Phase 1B: Draft specifications for {N} NodeIDs`. **Plan approval enabled** — add to prompt: `Present your spec design for lead review BEFORE writing final specs. Wait for approval.` Wait for `plan_approval_request`, review, respond with `plan_approval_response`. If `AUTONOMOUS_MODE = true`: auto-approve immediately. Log `[AUTO-APPROVED] Architect plan`.
 - *Subagent*: `Task(subagent_type="architect", description="Phase 1B specification drafting", prompt=<above> + "Present your spec design in your output for lead review.")`
 
-> **Note:** Plan approval (agent pauses for lead review) only works in Agent Teams mode via `permissionMode: plan`. In subagent mode, the architect presents its design in the output for post-hoc review.
+> **Note:** Plan approval (agent pauses for lead review) only works in Agent Teams mode via `permissionMode: plan`. In subagent mode, the architect presents its design in the output for post-hoc review. Spec-drafters (Path B) do NOT use plan approval — they follow the architect's partition briefing directly.
 
 ### Quality Gate #2
 
@@ -643,6 +938,10 @@ Present specs for batch approval:
 |--------|------|---------------------|
 | ... | ... | ... |
 
+### Specialist Reports                    [only when SPECIALISTS_ENABLED non-empty]
+**Architect**: {specs align with component map, drift concerns, pattern consistency}
+**Test Advisor**: {spec testability assessment, recommended test types per NodeID}
+
 Review specs and approve to proceed to implementation?
 ```
 
@@ -728,13 +1027,19 @@ Present audit results:
 **Security Posture**: {status}
 **Gaps Found**: {count}
 
+### Specialist Reports                    [only when SPECIALISTS_ENABLED non-empty]
+**Security Officer**: Findings: {N} | Critical: {N} | High: {N} | {details or [Pending]}
+**Architect**: Drift: {Yes/No} | Pattern Violations: {N} | {details}
+**Test Advisor**: TDD Compliance: {%} | Missing Edge Cases: {N} | Quality: {Good/Adequate/Poor} | {details or [Pending]}
+**Project Advisor**: New REFACTOR tasks: {N} | Ideas captured to vault: {N}
+
 **Recommendation**: {proceed / return to implementation}
 
 How would you like to proceed?
 ```
 
 **Autonomous Mode**: If `AUTONOMOUS_MODE = true`:
-- **Safety check**: If any security finding rated HIGH or CRITICAL → **PAUSE** autonomous mode for this gate. Announce: `> **Autonomous Mode Paused** — HIGH/CRITICAL security finding requires manual review.`
+- **Safety check**: If any security finding rated HIGH or CRITICAL (from reviewer OR security-officer `[SECURITY-BLOCK]`) → **PAUSE** autonomous mode for this gate. Announce: `> **Autonomous Mode Paused** — HIGH/CRITICAL security finding requires manual review.`
 - **Safety check**: If ARC completion < 50% → **PAUSE** autonomous mode for this gate. Announce: `> **Autonomous Mode Paused** — ARC completion below 50% requires manual review.`
 - If safety checks pass and gaps found → log `[AUTO-APPROVED] Gate #3 — proceeding to gap loop`, auto-proceed to gap loop.
 - If safety checks pass and no gaps → log `[AUTO-APPROVED] Gate #3`, auto-proceed to Phase 3.