knowzcode 0.2.1 → 0.3.1

package/commands/work.md

@@ -58,6 +58,22 @@ 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)
+
+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`
+
+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 +94,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 +183,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 +343,75 @@ 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")` → `TaskUpdate(owner: "architect")`
+   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 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; knowz-scribe is a cheap Haiku agent; specialists are Sonnet read-only agents). Agent count depends on orchestration config: 2-10 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 or specialists to finish. It starts scanning the codebase immediately. Scout findings arrive as messages and enrich the analyst's work as they arrive. 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. **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]`):
+   - 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. 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
    - 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)
+8. Architect completes specs
+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 +437,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 +465,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 +478,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 +510,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)
 
@@ -455,9 +546,18 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 | Knowz-scribe: listen | (none — persistent) | knowz-scribe |
 | Phase 1A analysis | (none — scouts enrich via broadcast) | analyst |
 | Architect pre-load | (none) | 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 |
+| 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 +566,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 +609,25 @@ 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.
 
 ---
 
@@ -554,6 +671,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
@@ -591,6 +763,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?
 ```
 
@@ -643,6 +820,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 +909,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.

package/knowzcode/claude_code_execution.md

@@ -159,6 +159,16 @@ Use mailbox messaging for coordination between teammates:
 | closer | knowz-scribe | Phase 3 learning capture (`"Capture Phase 3: {wgid}"`) |
 | closer | analyst | Change scope for log entry accuracy |
 | closer | architect | Spec format and legacy migration |
+| security-officer | lead | Structured finding reports at gates (with `[SECURITY-BLOCK]` for CRITICAL/HIGH) |
+| security-officer | architect | Security VERIFY criteria needs during Phase 1B |
+| security-officer | builder | Security guidance for sensitive partitions (max 2 DMs per builder) |
+| security-officer | test-advisor | Cross-cutting: test gaps in security-critical paths (max 2 inter-specialist DMs) |
+| test-advisor | lead | Test quality reports at gates |
+| test-advisor | architect | VERIFY criteria testability concerns during Phase 1B |
+| test-advisor | builder | Specific test improvement feedback (max 2 DMs per builder) |
+| test-advisor | security-officer | Cross-cutting: security scenarios needing test coverage (max 2 inter-specialist DMs) |
+| project-advisor | lead | Backlog context (Stage 0) and proposals (late Stage 2) |
+| project-advisor | knowz-scribe | Idea captures for vault storage |
 
 ### Gap Communication Flow
 In Parallel Teams mode, gap communication goes through the lead:
@@ -213,6 +223,9 @@ Agents must NOT create new tasks for work already assigned to them via task ID.
 | architect | Stage 0 (pre-load) | After Gate #3 | Spec clarifications + design guidance for builders throughout Stage 2 |
 | builder(s) | Stage 2 | After Gate #3 | Implementation + gap fixes (persistent through gap loop) |
 | reviewer(s) | Stage 2 (1 per builder partition) | After Gate #3 | Incremental audit per partition (persistent through gap loop) |
+| security-officer | Stage 0 (Group C) | After Gate #3 | Threat modeling + vulnerability scanning (officer — can block gates) |
+| test-advisor | Stage 0 (Group C) | After Gate #3 | TDD enforcement + test quality review (advisor — informational) |
+| project-advisor | Stage 0 (Group C) | Mid-Stage 2 | Backlog curation + idea capture (advisor — informational) |
 | closer | Stage 3 | End of workflow | Finalization |
 
 ### Task Dependency Usage
@@ -229,11 +242,24 @@ All tasks in a workflow use `addBlockedBy` to express the dependency chain:
 - Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
 - Stage 3 tasks: finalization (blocked by audit approval)
 
+### Orchestration Configuration
+
+Team sizing defaults are configurable via `knowzcode/knowzcode_orchestration.md`:
+
+| Parameter | Default | Flag Override | Effect |
+|-----------|---------|--------------|--------|
+| `max_builders` | 5 | `--max-builders=N` | Cap concurrent builders (1-5) |
+| `scout_mode` | full | `--no-scouts` | full (3 scouts), minimal (1 scout), none (lead reads context) |
+| `default_specialists` | [] | `--specialists`, `--no-specialists` | Project-level specialist defaults |
+| `mcp_agents_enabled` | true | `--no-mcp` | Toggle vault agents (knowz-scout, knowz-scribe) |
+
+Precedence: hardcoded defaults → orchestration config → per-invocation flags.
+
 ### Builder Partitioning Rules
 
 - No two builders touch the same file
 - Analyst dependency map determines partitions
-- Max 5 concurrent builders
+- Max `MAX_BUILDERS` concurrent builders (default 5, configurable in `knowzcode_orchestration.md`)
 - If all NodeIDs share files → single builder with subtask tracking
 - Builder-to-builder messages for interface changes affecting other partitions
 
@@ -264,6 +290,43 @@ During Stage 0, the architect pre-loads context in parallel with analysis:
 - When Gate #1 is approved, architect already has context → specs drafted faster
 - If Gate #1 rejected, architect context is still useful for the revised analysis cycle
 
+#### Specialist Agents (Group C — opt-in via `--specialists`)
+
+When specialists are enabled, three additional agents spawn at Stage 0 alongside Groups A and B:
+
+```
+Group A (always):           3 context-scouts + analyst + architect       (5 agents)
+Group B (if MCP):           knowz-scout + knowz-scribe                  (2 agents)
+Group C (if --specialists): security-officer + test-advisor + project-advisor  (3 agents)
+```
+
+Max Stage 0 concurrent: 5-10 agents depending on orchestration config (scouts, MCP agents, specialists). Scouts shut down after Gate #2, so Stage 2 peak is manageable.
+
+##### Officer vs Advisor Authority
+
+| Role | Authority | Gate Impact |
+|------|-----------|-------------|
+| **Officer** (security-officer) | CRITICAL/HIGH findings block gates | `[SECURITY-BLOCK]` tag pauses autonomous mode |
+| **Advisor** (test-advisor, project-advisor) | Informational only | Findings included in gate reports, do not block |
+
+##### Direct DM Protocol
+
+Specialists communicate directly with builders, architect, and each other — no lead bottleneck relay:
+
+- **security-officer → architect**: Security VERIFY criteria needs during Phase 1B
+- **security-officer → builder-N**: Security guidance for sensitive partitions (max 2 DMs per builder)
+- **test-advisor → architect**: VERIFY criteria testability concerns during Phase 1B
+- **test-advisor → builder-N**: Specific test improvement feedback (max 2 DMs per builder)
+- **project-advisor → knowz-scribe**: Idea captures for vault storage
+- **security-officer ↔ test-advisor**: Cross-cutting test gaps in security paths (max 2 inter-specialist DMs total)
+
+##### Communication Discipline
+
+- Max 2 DMs to any individual builder from each specialist
+- Max 2 inter-specialist DMs per workflow
+- Consolidate findings — no per-file noise
+- project-advisor does NOT DM builders or other specialists (observes via task list only)
+
 ---
 
 ## Teammate Initialization Protocol