knowzcode 0.1.0 → 0.2.1

package/commands/work.md

@@ -30,30 +30,53 @@ If missing: inform user to run `/kc:init` first. STOP.
 - `{slug}`: 2-4 word kebab-case from goal (remove common words: build, add, create, implement, the, a, with, for)
 - Truncate slug to max 25 characters
 
-## Step 2: Detect Execution Mode
+## Step 2: Select Execution Mode
 
-Check if Agent Teams is enabled: you have team management capabilities (spawning teammates, shared task list, messaging) when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set. If these tools are available, use Agent Teams mode. Otherwise, use subagent fallback.
+Determine the execution mode using try-then-fallback:
 
-The user never selects a mode — the phases, quality gates, and interactions are identical in both paths.
+1. Note user preferences from `$ARGUMENTS`:
+   - `--sequential` → prefer Sequential Teams
+   - `--subagent` → force Subagent Delegation (skip team creation attempt)
+
+2. **If `--subagent` NOT specified**, attempt `TeamCreate(team_name="kc-{wgid}")`:
+   - **If TeamCreate succeeds** → Agent Teams is available. Choose mode:
+     - `--sequential` or Tier 2 → **Sequential Teams**: `**Execution Mode: Sequential Teams** — created team kc-{wgid}`
+     - Otherwise → **Parallel Teams** (default for Tier 3): `**Execution Mode: Parallel Teams** — created team kc-{wgid}`
+   - **If TeamCreate fails** (error, unrecognized tool, timeout) → **Subagent Delegation**: `**Execution Mode: Subagent Delegation** — Agent Teams not available, using Task() fallback`
+
+3. **If `--subagent` specified** → **Subagent Delegation** directly (no TeamCreate attempt):
+   - Announce: `**Execution Mode: Subagent Delegation** — per user request`
+
+For all Agent Teams modes (Sequential and Parallel):
+- You are the **team lead** in delegate mode — you coordinate phases, present quality gates, and manage the workflow. You NEVER write code, specs, or project files directly. All work is done by teammates. (Tip: the user can press Shift+Tab to system-enforce delegate mode.)
+- After completion or if the user cancels, shut down all active teammates and clean up the team (see Cleanup section)
+
+For Subagent Delegation:
+- For each phase, delegate via `Task()` with the parameters specified in phase sections below
+
+The user MUST see the execution mode announcement before any phase work begins. The phases, quality gates, and interactions are identical across all paths.
 
 > **Note:** Agent Teams is experimental and the API may change.
 
-### If Agent Teams is available:
+## Step 2.5: Autonomous Mode Detection
+
+Set `AUTONOMOUS_MODE = true` if ANY of these match:
+
+a. **Flags**: `$ARGUMENTS` contains `--autonomous` or `--auto`
 
-1. Read `knowzcode/claude_code_execution.md` for team conventions
-2. You are the **team lead in delegate mode** — you coordinate phases, present quality gates, and manage the workflow. You NEVER write code, specs, or project files directly. All work is done by teammates. (Tip: the user can press Shift+Tab to system-enforce delegate mode.)
-3. For each phase:
-   - Spawn ONE teammate with the spawn prompt defined in that phase section below
-   - Create a task describing the phase work and assign it to the teammate
-   - Wait for the teammate to complete the task
-   - Review the teammate's output
-   - Present results at the quality gate for user approval
-   - Shut down the teammate before spawning the next phase's teammate
-4. After Phase 3 completes or if the user cancels at any point, shut down all active teammates (see Cleanup section)
+b. **Natural language** (case-insensitive match in `$ARGUMENTS` OR the user's preceding conversation message):
+   - Approval intent: "approve all", "pre-approve", "preapprove", "auto-approve"
+   - Mode intent: "autonomous mode", "autonomous", "unattended", "hands off", "hands-off"
+   - Proceed intent: "don't stop to ask", "don't ask me", "no approval needed", "just run through", "run it all", "run straight through", "proceed without asking", "skip the gates", "go all the way through"
+   - Delegation intent: "I trust your judgement", "use your best judgement", "defer to your judgement", "you decide"
 
-### If Agent Teams is NOT available (subagent fallback):
+c. **Contextual** — if the user's message conveys clear intent for the lead to operate without stopping (even if none of the exact phrases above match), interpret that as autonomous mode. The spirit of the instruction matters more than exact phrasing.
 
-Use `Task()` calls to delegate each phase to the named agent. Pass the WorkGroupID, goal, and context file paths. This is the existing behavior — each phase section below includes both paths.
+Default: `AUTONOMOUS_MODE = false`
+
+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 3: Load Context Files (ONCE)
 
@@ -67,7 +90,7 @@ Read these files ONCE (do NOT re-read between phases):
 
 If MCP is configured and enterprise compliance is enabled:
 1. Check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`
-2. If enabled: `ask_question(enterprise_vault, "team standards for {project_type}")`
+2. If enabled: Read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise", then `ask_question({resolved_enterprise_vault_id}, "team standards for {project_type}")`
 3. Merge returned standards into WorkGroup context for quality gate criteria
 
 If MCP is not configured or enterprise is not enabled, skip this step.
@@ -82,6 +105,7 @@ Create `knowzcode/workgroups/{WorkGroupID}.md`:
 **Created**: {timestamp}
 **Status**: Active
 **Current Phase**: 1A - Impact Analysis
+**Autonomous Mode**: Active/Inactive
 
 ## Change Set
 (Populated after Phase 1A)
@@ -104,6 +128,108 @@ Create `knowzcode/workgroups/{WorkGroupID}.md`:
 
 If ambiguous, proceed with implementation.
 
+## Step 5.5: Complexity Classification
+
+Assess the goal against the codebase to determine the appropriate workflow tier.
+
+### Tier 1: Micro → redirect to `/kc:fix`
+- Single file, <50 lines, no ripple effects
+
+### Tier 2: Light (2-phase workflow)
+ALL must be true:
+- ≤3 files touched
+- Single NodeID (1 new capability)
+- No architectural changes
+- No security-sensitive components (auth, payments, PII)
+- No external API integrations
+- Estimated <200 lines of change
+
+### Tier 3: Full (5-phase workflow)
+ANY triggers full:
+- >3 files or >1 NodeID
+- Architectural impact
+- Security-sensitive scope
+- External integrations
+- User explicitly requests: `--tier full`
+
+**Announce the detected tier to the user.** User can override:
+- "use full" or `--tier full` → Tier 3
+- "use light" or `--tier light` → Tier 2
+
+If `$ARGUMENTS` contains `--tier light`, force Tier 2. If `--tier full`, force Tier 3.
+
+---
+
+## Tier 2: Light Workflow (2-phase fast path)
+
+When Tier 2 is selected, execute this streamlined workflow instead of the 5-phase Tier 3 below.
+
+### Light Phase 1 (Inline — lead does this, no agent)
+
+1. Quick impact scan: grep for related files, check existing specs
+2. Propose a Change Set (typically 1 NodeID)
+3. Draft a lightweight spec (or reference existing spec if found) — use the 4-section format from `knowzcode_loop.md` section 3.2. Minimum: 1 Rule, 1 Interface, 2 `VERIFY:` statements.
+4. Present combined Change Set + Spec for approval:
+
+```markdown
+## Light Mode: Change Set + Spec Approval
+
+**WorkGroupID**: {wgid}
+**Tier**: 2 (Light)
+**NodeID**: {NodeID} — {description}
+**Affected Files**: {list}
+
+**Spec Summary**:
+- Rules: {key decisions}
+- Interfaces: {public contracts}
+- VERIFY: {criteria list}
+
+Approve Change Set and spec to proceed to implementation?
+```
+
+5. **Autonomous Mode**: If `AUTONOMOUS_MODE = true`, log `[AUTO-APPROVED] Light mode gate` and proceed directly to implementation.
+   If `AUTONOMOUS_MODE = false`: If rejected — adjust based on feedback and re-present. If approved:
+   - Update `knowzcode_tracker.md` with NodeID status `[WIP]`
+   - Pre-implementation commit: `git add knowzcode/ && git commit -m "KnowzCode: Light spec approved for {wgid}"`
+
+### Light Phase 2A: Implementation (Builder agent)
+
+Spawn the builder using the standard Phase 2A prompt below (same for both tiers).
+
+The builder self-verifies against spec VERIFY criteria — no separate audit phase.
+
+### Light Phase 3 (Inline — lead does this, no agent)
+
+After builder completes successfully:
+1. Update spec to As-Built status
+2. Update `knowzcode_tracker.md`: NodeID status `[WIP]` → `[VERIFIED]`
+3. Write a brief log entry to `knowzcode_log.md`:
+   ```markdown
+   ---
+   **Type:** ARC-Completion
+   **Timestamp:** [timestamp]
+   **WorkGroupID:** [ID]
+   **NodeID(s):** [list]
+   **Logged By:** AI-Agent
+   **Details:** Light mode (Tier 2). {brief summary of implementation}.
+   ---
+   ```
+4. Final commit: `git add knowzcode/ <changed files> && git commit -m "feat: {goal} (WorkGroup {wgid})"`
+5. Report completion.
+
+**DONE** — 3 agents skipped (analyst, architect, reviewer, closer).
+
+---
+
+## Tier 3: Full Workflow (5-phase)
+
+The standard 5-phase workflow. Used when complexity warrants full analysis, specification, audit, and finalization.
+
+Tier 3 supports three execution modes (determined in Step 2):
+- **Parallel Teams** (default) — Stage 0-3 orchestration with concurrent agents
+- **Sequential Teams** (`--sequential`) — one agent per phase, spawned and shut down sequentially
+- **Subagent Delegation** — Task() calls, no persistent agents
+
 ## Step 6: Spec Detection (Optional Optimization)
 
 Check for existing specs covering this work:
@@ -116,33 +242,340 @@ Check for existing specs covering this work:
 
 If no matches found, proceed to Phase 1A.
 
+### Refactor Task Check
+
+Scan `knowzcode/knowzcode_tracker.md` for outstanding `REFACTOR_` tasks that overlap with the current goal's scope. If found, mention them to the user during Phase 1A so the analyst can factor them into the Change Set.
+
 ---
 
-## Phase 1A: Impact Analysis
+## Parallel Teams Orchestration (Tier 3 Default)
+
+When Parallel Teams mode is active, follow these 4 stages instead of spawning one agent per phase sequentially. The same phase spawn prompts (defined in the Phase Reference sections below) are reused — what changes is WHEN agents are spawned and HOW MANY run concurrently.
+
+### Stage 0: Team Creation + Parallel Discovery
+
+1. Create team `kc-{wgid}`
+2. Read knowzcode context files (lead does initial load for spawn prompts)
+3. **MCP Probe** — determine vault availability BEFORE spawning:
+   a. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
+   b. Call `list_vaults(includeStats=true)` **always** — regardless of whether any IDs exist in the file
+   c. If `list_vaults()` fails → set `MCP_ACTIVE = false`, announce `**MCP Status: Not connected**`, skip to Step 4
+   d. 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. For each uncreated vault, derive the "Written During" column from its Write Conditions field in `knowzcode_vaults.md`. Example rows:
+      - `| Code Patterns | code | Learnings, gotchas, and architecture insights from the codebase | Phase 2A (implementation patterns), Phase 3 (workarounds, performance) |`
+      - `| Ecosystem Knowledge | ecosystem | Business rules, conventions, decisions, and cross-system details | Phase 1A (scope decisions), Phase 2B (security, quality), Phase 3 (conventions) |`
+      - `| Finalizations | finalizations | Final summaries documenting complete execution and outcomes | Phase 3 (completion record) |`
+
+      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`)
+      ```
+
+   e. 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 the ID field with the server-returned vault ID and change the H3 heading from `(not created)` to the vault ID. If creation fails for some vaults, update only successful ones, report failures, and let user decide.
+      - **B**: Ask which vaults to create, then create only selected ones using the same process as A.
+      - **C**: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
+   f. 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)**`
+4. **Spawn Group A** (always — 5 agents):
+   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`:
+   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
+
+**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.
+
+### 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:
+   - 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
+   - 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)
+
+### 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
+
+2. Create builder tasks and spawn:
+   - `TaskCreate("Implement NodeIDs [A, B]", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "builder-1")`
+   - `TaskCreate("Implement NodeIDs [C]", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "builder-2")`
+   - `TaskCreate("Implement NodeIDs [D, E]", addBlockedBy: [spec-task-id])` → `TaskUpdate(owner: "builder-3")`
+   Spawn each builder with its `{task-id}` in the spawn prompt.
+   Each builder gets its partition's specs + affected files list.
+   **NO TWO BUILDERS TOUCH THE SAME FILE**
+
+3. Notify architect of builder spawn:
+   - Lead DMs architect: `"Builders spawned for Stage 2. Introduce yourself to: {builder-1, builder-2, ...}"`
+   - Architect sends brief availability message to each builder (see `agents/architect.md` — Proactive Availability)
+
+4. Each builder creates subtasks per NodeID in the task list:
+   - `"TDD: NodeID-A tests"` → `"TDD: NodeID-A implementation"` → `"TDD: NodeID-A verify"`
+   - Builder works through subtasks, marks each complete with summary
+
+5. Create reviewer tasks and spawn — one per builder partition:
+   - `TaskCreate("Audit partition 1: NodeIDs [A, B]", addBlockedBy: [implement-A-task-id])` → `TaskUpdate(owner: "reviewer-1")`
+   - `TaskCreate("Audit partition 2: NodeIDs [C]", addBlockedBy: [implement-C-task-id])` → `TaskUpdate(owner: "reviewer-2")`
+   - `TaskCreate("Audit partition 3: NodeIDs [D, E]", addBlockedBy: [implement-D-task-id])` → `TaskUpdate(owner: "reviewer-3")`
+   Spawn each reviewer with its `{task-id}` + partition's specs + VERIFY criteria.
+   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):
+   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")`
+   c. Lead sends DM to builder with task ID and gap details:
+      > **New Task**: #{fix-task-id} — Fix gaps: NodeID-A
+      > **Gaps**: {file path, VERIFY criterion not met, expected vs actual}
+      > Fix each gap, re-run affected tests, report completion.
+   d. Builder claims fix task, fixes gaps, re-runs tests, marks fix task complete
+   e. Lead creates re-audit task and pre-assigns:
+      `TaskCreate("Re-audit: NodeID-A", addBlockedBy: [gap-fix-task-id])` → `TaskUpdate(owner: "reviewer-N")`
+   f. Lead sends DM to reviewer: `"**New Task**: #{reaudit-task-id} — Re-audit: NodeID-A. {gap list}"`
+   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):
+   - 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:
+   - 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")
+   - builder → reviewer (same partition): Implementation complete notifications (via task system)
+   - 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
+
+### Stage 3: Finalization
+
+1. `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):
+   - Update all specs to FINAL as-built
+   - Update `knowzcode_tracker.md`: all NodeIDs `[WIP]` → `[VERIFIED]`
+   - Write ARC-Completion log entry
+   - Review architecture docs for discrepancies
+   - 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
+
+### WorkGroup File Format (Parallel Mode)
+
+In Parallel Teams mode, the WorkGroup file uses per-NodeID phase tracking instead of a single `Current Phase`:
 
-### Agent Teams Mode
+```markdown
+## Change Set
+| NodeID | Phase | Builder | Status | Timestamp |
+|--------|-------|---------|--------|-----------|
+| Authentication | 2A | builder-1 | Implementing | ... |
+| UserProfile | 2B | builder-1 | Under review | ... |
+| LIB_DateFormat | 2A | builder-2 | Tests passing | ... |
+
+## Autonomous Mode
+Active/Inactive
+
+## Current Stage
+Stage 2: Parallel Implementation + Incremental Review
+```
 
-Spawn a teammate named `analyst` with this prompt:
+### Task Dependency Graph
+
+When creating tasks, model the dependency chain with `addBlockedBy` and pre-assign with `owner`:
+
+| Task | Blocked By | Owner |
+|------|-----------|-------|
+| Scout: specs context | (none) | context-scout-specs |
+| Scout: workgroups context | (none) | context-scout-workgroups |
+| 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 |
+| Implement: NodeID-X | Spec: NodeID-X | builder-N |
+| Audit: NodeID-X | Implement: NodeID-X | reviewer-N |
+| 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 |
+
+---
+
+## Sequential Teams / Subagent Flow (Tier 3 Fallback)
+
+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.
+
+---
 
+## Phase Prompt Reference
+
+The spawn prompts below are shared by all execution modes. In Parallel Teams mode, the lead uses these prompts when spawning agents at the appropriate stage. In Sequential Teams / Subagent mode, agents are spawned one at a time in phase order.
+
+## Stage 0: Context Scouts (3 instances)
+
+**Agent**: `context-scout` (x3) | Read-only local context researchers
+
+Three instances of the same agent, each focused on a different local folder group:
+
+**context-scout-specs spawn prompt**:
+> You are `context-scout-specs` for WorkGroup `{wgid}`.
+> Read `agents/context-scout.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Focus area**: `knowzcode/specs/*.md` — scan existing specifications.
+> **Goal**: {goal}
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast relevant spec findings (NodeIDs, status, VERIFY criteria overlapping with goal).
+
+**context-scout-workgroups spawn prompt**:
+> You are `context-scout-workgroups` for WorkGroup `{wgid}`.
+> Read `agents/context-scout.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Focus area**: `knowzcode/workgroups/*.md` — scan previous WorkGroups for similar goals.
+> **Goal**: {goal}
+> **READ-ONLY.** Do NOT modify any files.
+> **Deliverable**: Broadcast prior WorkGroup context (what was tried, what succeeded/failed, patterns).
+
+**context-scout-backlog spawn prompt**:
+> You are `context-scout-backlog` for WorkGroup `{wgid}`.
+> Read `agents/context-scout.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Focus area**: `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 active WIP, REFACTOR tasks, architecture summary, and recent log patterns relevant to goal.
+
+**Dispatch**:
+- *Parallel Teams*: All 3 context scouts spawned at Stage 0, no blockedBy. Shut down after Gate #2 (specs approved).
+- *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", ...)`
+
+---
+
+## Stage 0: Knowz Scout
+
+**Agent**: `knowz-scout` | MCP vault researcher and knowledge agent
+
+**Spawn prompt**:
+> You are the **knowz-scout** for WorkGroup `{wgid}`.
+> Read `agents/knowz-scout.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **Goal**: {goal}
+> **Step 1**: Read `knowzcode/knowzcode_vaults.md` to discover configured vaults — their IDs, types, descriptions, and what knowledge each contains.
+> **Step 2**: For each configured vault, construct goal-relevant queries using the vault's description to guide what to ask. If a single vault covers all knowledge, consolidate queries there.
+> **Deliverable**: Broadcast vault knowledge findings to all teammates.
+
+**Dispatch**:
+- *Parallel Teams*: **Group B** — spawned at Stage 0 if `VAULTS_CONFIGURED = true`, no blockedBy. Persistent — stays alive through the entire workflow. Shut down after Phase 3 capture is complete.
+- *Sequential Teams*: Not applicable (scouts are Parallel Teams only).
+- *Subagent*: `Task(subagent_type="knowz-scout", description="Query vault for domain knowledge", prompt=<above>)` (only if MCP Probe passes)
+
+---
+
+## Stage 0: Knowz Scribe
+
+**Agent**: `knowz-scribe` | Persistent vault write agent (Haiku)
+
+**Spawn prompt**:
+> You are the **knowz-scribe** for WorkGroup `{wgid}`.
+> Read `agents/knowz-scribe.md` for your full role definition.
+> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Vault config**: Read `knowzcode/knowzcode_vaults.md` to discover configured vaults and resolve vault IDs by type.
+> **You are a message-driven agent.** Wait for capture messages from teammates (e.g., "Capture Phase 1A: {wgid}"). On each message, read the WorkGroup file, extract relevant learnings, and write to the appropriate vault.
+> **Do NOT read or modify source code.** You only read knowzcode/ files and write to MCP vaults.
+
+**Dispatch**:
+- *Parallel Teams*: **Group B** — spawned at Stage 0 if `VAULTS_CONFIGURED = true`, no blockedBy. Persistent — stays alive through the entire workflow. Shut down after Phase 3 capture is complete.
+- *Sequential Teams*: Not applicable (knowz-scribe is Parallel Teams only).
+- *Subagent*: Not applicable — vault writes in subagent mode are handled inline by the lead.
+
+---
+
+## Phase 1A: Impact Analysis
+
+**Agent**: `analyst` | **Loop.md**: Section 3.1
+
+**Spawn prompt**:
 > You are the **analyst** for WorkGroup `{wgid}`.
 > Read `agents/analyst.md` for your full role definition.
-> Read `knowzcode/claude_code_execution.md` for team conventions.
 >
 > **Goal**: {goal}
-> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **Context files**: Read sections 1-2 and 3.1 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
 > **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
 >
-> **Deliverable**: Change Set proposal written to the WorkGroup file. Include NodeIDs, descriptions, affected files, and risk assessment.
-> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
-
-Create task: `Phase 1A: Impact analysis for "{goal}"` and assign to the analyst.
-Wait for task completion, then review the Change Set output.
-
-### Subagent Mode
+> **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.
+> **Deliverable**: Change Set proposal written to the WorkGroup file. Include NodeIDs, descriptions, affected files, risk assessment, and dependency map (for Parallel Teams mode).
 
-Delegate to the **analyst** agent via `Task()`. Pass WorkGroupID, goal, and context file paths.
+**Dispatch**:
+- *Parallel Teams*: Spawned at Stage 0 alongside scouts 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>)`
 
-### Quality Gate #1 (both modes)
+### Quality Gate #1
 
 Present the Change Set for user approval:
 
@@ -153,44 +586,52 @@ Present the Change Set for user approval:
 **Proposed Change Set** ({N} nodes):
 {NodeIDs with descriptions}
 
+**Dependency Map** (Parallel Teams):
+{NodeID parallelism groups}
+
 **Risk Assessment**: {Low/Medium/High}
 
 Approve this Change Set to proceed to specification?
 ```
 
-If rejected: re-run analyst with user feedback. If approved: update tracker, proceed.
+**Autonomous Mode**: If `AUTONOMOUS_MODE = true`, present gate info for transparency, log `[AUTO-APPROVED] Gate #1`, and proceed immediately.
+If `AUTONOMOUS_MODE = false`: If rejected — re-run analyst with user feedback. If approved — update tracker, proceed.
+
+### MCP Learning Capture (Optional)
+
+If MCP is configured and knowz-scribe is active, after Change Set approval:
+- Send message to **knowz-scribe**: `"Capture Phase 1A: {wgid}"` — the scribe reads the WorkGroup file, extracts scope/risk/decision data, and writes to the appropriate vault
+- `search_knowledge({resolved_domain_vault_id}, "patterns for {domain}")` — pull relevant past learnings to inform specification
+- Share any relevant findings with the architect in the Phase 1B prompt
 
 ---
 
 ## Phase 1B: Specification
 
-### Agent Teams Mode
-
-Spawn a teammate named `architect` with this prompt:
+**Agent**: `architect` | **Loop.md**: Section 3.2
 
+**Spawn prompt**:
 > You are the **architect** for WorkGroup `{wgid}`.
 > Read `agents/architect.md` for your full role definition.
-> Read `knowzcode/claude_code_execution.md` for team conventions.
 >
 > **Goal**: {goal}
 > **Approved Change Set**: {NodeIDs from Gate #1}
-> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **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/`
 >
-> **Plan approval enabled**: Present your spec design (structure, VERIFY criteria, test strategy) for lead review BEFORE writing final specs. Wait for approval.
+> **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.
 > **Deliverable**: Finalized specs for all NodeIDs written to `knowzcode/specs/`.
-> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
-
-Create task: `Phase 1B: Draft specifications for {N} NodeIDs` and assign to the architect.
-Wait for the architect to present their plan. Review and approve or request changes.
-After plan approval, wait for task completion.
 
-### Subagent Mode
+**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`.
+- *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.")`
 
-Delegate to the **architect** agent via `Task()`. Pass WorkGroupID, approved Change Set NodeIDs, and context file paths.
+> **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.
 
-### Quality Gate #2 (both modes)
+### Quality Gate #2
 
 Present specs for batch approval:
 
@@ -205,7 +646,8 @@ Present specs for batch approval:
 Review specs and approve to proceed to implementation?
 ```
 
-If rejected: re-run specs needing revision. If approved: pre-implementation commit, proceed.
+**Autonomous Mode**: If `AUTONOMOUS_MODE = true`, present gate info for transparency, log `[AUTO-APPROVED] Gate #2`, and proceed immediately.
+If `AUTONOMOUS_MODE = false`: If rejected — re-run specs needing revision. If approved — pre-implementation commit, proceed.
 
 **Pre-Implementation Commit:**
 ```bash
@@ -217,67 +659,65 @@ git commit -m "KnowzCode: Specs approved for {WorkGroupID}"
 
 ## Phase 2A: Implementation
 
-### Agent Teams Mode
-
-Spawn a teammate named `builder` with this prompt:
+**Agent**: `builder` | **Loop.md**: Section 3.3
 
+**Spawn prompt**:
 > You are the **builder** for WorkGroup `{wgid}`.
 > Read `agents/builder.md` for your full role definition.
-> Read `knowzcode/claude_code_execution.md` for team conventions.
 >
 > **Goal**: {goal}
 > **Approved Change Set**: {NodeIDs}
 > **Specs**: {list of spec file paths from Phase 1B}
-> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`
+> **Context files**: Read sections 1-2 and 3.3 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_project.md`
 > **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
 >
-> **Plan approval enabled**: Present your implementation approach (file changes, test strategy, execution order) for lead review BEFORE writing code. Wait for approval.
+> **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.
 > **TDD mandatory**: Write failing tests first, then implement, then refactor. Every NodeID must have tests.
-> **Deliverable**: All NodeIDs implemented with passing tests. Update WorkGroup file with results.
-> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+> **Blocker protocol**: If you hit a blocker, document it as a Blocker Report in the WorkGroup file (see loop.md Section 11 format) and report to the lead immediately instead of guessing.
+> **Deliverable**: All NodeIDs implemented with passing tests.
 
-Create task: `Phase 2A: Implement {N} NodeIDs with TDD` and assign to the builder.
-Wait for the builder to present their plan. Review and approve or request changes.
-After plan approval, wait for task completion.
+**Dispatch**:
+- *Parallel Teams*: Multiple builders spawned at Stage 2, one per partition from the dependency map. Each builder gets its partition's NodeIDs and specs. Builders create per-NodeID subtasks for visibility. **Plan approval enabled** — add to prompt: `Present your implementation approach for lead review BEFORE writing code. Wait for approval.` If `AUTONOMOUS_MODE = true`: auto-approve `plan_approval_request` immediately. Log `[AUTO-APPROVED] Builder plan`.
+- *Sequential Teams*: Spawn teammate `builder`, create task `Phase 2A: Implement {N} NodeIDs with TDD`. **Plan approval enabled** — add to prompt: `Present your implementation approach for lead review BEFORE writing code. Wait for approval.` Wait for `plan_approval_request`, review, respond. If `AUTONOMOUS_MODE = true`: auto-approve immediately. Log `[AUTO-APPROVED] Builder plan`.
+- *Subagent*: `Task(subagent_type="builder", description="Phase 2A TDD implementation", mode="bypassPermissions", prompt=<above>)`
 
-### Subagent Mode
+### Phase 2A Output
 
-Delegate to the **builder** agent via `Task()`. Pass WorkGroupID, NodeIDs, spec file paths, and context file paths.
+When complete, present implementation summary including files changed, tests written, and test results.
 
-### Phase 2A Output (both modes)
+### MCP Learning Capture (Optional)
 
-When complete, present implementation summary including files changed, tests written, and test results.
+If MCP is configured and knowz-scribe is active, after implementation completes:
+- Send message to **knowz-scribe**: `"Capture Phase 2A: {wgid}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
 
 ---
 
 ## Phase 2B: Completeness Audit
 
-### Agent Teams Mode
-
-Spawn a teammate named `reviewer` with this prompt:
+**Agent**: `reviewer` | **Loop.md**: Section 3.4
 
+**Spawn prompt**:
 > You are the **reviewer** for WorkGroup `{wgid}`.
 > Read `agents/reviewer.md` for your full role definition.
-> Read `knowzcode/claude_code_execution.md` for team conventions.
 >
 > **Goal**: {goal}
 > **Change Set**: {NodeIDs}
 > **Specs**: {list of spec file paths}
-> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **Context files**: Read sections 1-2 and 3.4 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
 > **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
 >
+> **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.
 > **This is a READ-ONLY audit.** Do not modify any source code or test files.
-> **Deliverable**: Audit report with ARC completion %, security posture, and gap list. Write results to WorkGroup file.
-> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+> **Deliverable**: Audit report with ARC completion %, security posture, and gap list.
 
-Create task: `Phase 2B: Completeness audit for {N} NodeIDs` and assign to the reviewer.
-Wait for task completion, then review audit results.
+**Dispatch**:
+- *Parallel Teams*: One reviewer per builder partition, spawned at Stage 2. Each reviewer gets its partition's NodeIDs and specs. Audit tasks use `addBlockedBy` per implementation task. Each reviewer uses structured gap report format (see `agents/reviewer.md`).
+- *Sequential Teams*: Spawn teammate `reviewer`, create task `Phase 2B: Completeness audit for {N} NodeIDs`, wait for completion.
+- *Subagent*: `Task(subagent_type="reviewer", description="Phase 2B completeness audit", prompt=<above>)`
 
-### Subagent Mode
-
-Delegate to the **reviewer** agent via `Task()`. Pass WorkGroupID, NodeIDs, spec file paths, and context file paths.
-
-### Quality Gate #3 (both modes)
+### Quality Gate #3
 
 Present audit results:
 
@@ -293,57 +733,69 @@ Present audit results:
 How would you like to proceed?
 ```
 
-### Gap Loop (when user chooses to fix gaps)
+**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 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.
 
-If the user wants gaps fixed:
+If `AUTONOMOUS_MODE = false`: User decides — proceed / fix gaps / modify specs / cancel.
 
-**Agent Teams Mode**: The previous builder teammate was already shut down. Spawn a NEW `builder` teammate with the same base prompt as Phase 2A, plus these additions:
+### Gap Loop (when user chooses to fix gaps)
 
-> **Gap fix mode**: You are fixing gaps found during audit, not doing fresh implementation.
-> **Gaps to fix**:
-> {gap list from reviewer — file path, criterion not met, expected vs actual}
->
-> Fix each gap, re-run affected tests, and report completion.
+**Parallel Teams mode** (per-partition, persistent agents — no respawning):
+1. Lead reads each reviewer's structured gap report from task summary
+2. Lead creates fix task and pre-assigns:
+   `TaskCreate("Fix gaps: NodeID-X", addBlockedBy: [audit-task-id])` → `TaskUpdate(owner: "builder-N")`
+3. Lead sends DM to builder with task ID and gap details:
+   `"**New Task**: #{fix-task-id} — Fix gaps: NodeID-X. {file path, VERIFY criterion, expected vs actual}"`
+4. Builder claims fix task, fixes gaps, re-runs tests, marks fix task complete
+5. Lead creates re-audit task and pre-assigns:
+   `TaskCreate("Re-audit: NodeID-X", addBlockedBy: [gap-fix-task-id])` → `TaskUpdate(owner: "reviewer-N")`
+6. Lead sends DM to reviewer: `"**New Task**: #{reaudit-task-id} — Re-audit: NodeID-X. {gap list}"`
+7. Each builder-reviewer pair repeats independently until clean — no cross-partition blocking
+8. All builders and reviewers stay alive throughout
+9. **3-iteration cap per partition**: If a partition exceeds 3 gap-fix iterations without resolution, **PAUSE** autonomous mode for that partition (even if `AUTONOMOUS_MODE = true`). Announce: `> **Autonomous Mode Paused** — Partition {N} failed 3 gap-fix iterations. Manual review required.`
+
+**Sequential Teams mode**: Spawn a NEW `builder` with the standard Phase 2A prompt plus gap fix context. Then re-run Phase 2B (spawn a new reviewer). Repeat until user approves at Gate #3.
 
-Create task: `Phase 2A (gap fix): Address {N} audit gaps` and assign to the new builder.
-Wait for completion, then re-run Phase 2B (spawn a new reviewer).
+**Subagent mode**: Launch parallel `Task()` calls — one for gap fix (builder), then one for re-audit (reviewer). Repeat as needed.
 
-**Subagent Mode**: Delegate gap fixes to the **builder** agent via `Task()` with gap details. Then re-delegate audit to the **reviewer** agent.
+### MCP Learning Capture (Optional)
 
-If approved at Gate #3: proceed to finalization.
+If MCP is configured and knowz-scribe is active, after audit approval:
+- Send message to **knowz-scribe**: `"Capture Phase 2B: {wgid}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
 
 ---
 
 ## Phase 3: Finalization
 
-### Agent Teams Mode
-
-Spawn a teammate named `closer` with this prompt:
+**Agent**: `closer` | **Loop.md**: Section 3.5
 
+**Spawn prompt**:
 > You are the **closer** for WorkGroup `{wgid}`.
 > Read `agents/closer.md` for your full role definition.
-> Read `knowzcode/claude_code_execution.md` for team conventions.
 >
 > **Goal**: {goal}
 > **Change Set**: {NodeIDs}
 > **Specs**: {list of spec file paths}
-> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_log.md`
+> **Context files**: Read sections 1-2, 3.5, 6, and 7 of `knowzcode/knowzcode_loop.md` (skip other phases), `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_log.md`
 > **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
 >
-> **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, capture learnings, and create final commit.
-> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+> **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.
+> **Vault writes**: If knowz-scribe is active, send it `"Capture Phase 3: {wgid}"` to delegate learning capture and audit trail writes. Do NOT call `create_knowledge` directly.
+> **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, delegate learning capture to knowz-scribe, and create final commit.
 
-Create task: `Phase 3: Finalize WorkGroup {wgid}` and assign to the closer.
-Wait for task completion.
+**Dispatch**:
+- *Parallel Teams*: Spawned at Stage 3 (`addBlockedBy`: last audit/re-audit task). All other agents shut down before closer starts, except knowz-scout and knowz-scribe (stay alive for Phase 3 capture).
+- *Sequential Teams*: Spawn teammate `closer`, create task `Phase 3: Finalize WorkGroup {wgid}`, wait for completion.
+- *Subagent*: `Task(subagent_type="closer", description="Phase 3 finalization", prompt=<above>)`
 
-### Subagent Mode
+### Phase 3 Output
 
-Delegate to the **closer** agent via `Task()`. Pass WorkGroupID, NodeIDs, spec file paths, and all context file paths.
-
-### Phase 3 Output (both modes)
-
-When complete, push completion record to MCP vault if configured:
-- `create_knowledge` with WorkGroup summary, decisions, and outcomes
+When complete, if MCP is configured and knowz-scribe is active:
+- The closer sends a message to **knowz-scribe**: `"Capture Phase 3: {wgid}"` — the scribe reads the WorkGroup file, extracts learnings, decisions, and outcomes, and writes to the appropriate vaults
 
 Update workgroup to "Closed" and report:
 
@@ -363,27 +815,38 @@ Update workgroup to "Closed" and report:
 
 ## Cleanup
 
-After Phase 3 completes successfully, or if the user cancels the workflow at any point:
+### After Phase 3 Completes
 
-**Agent Teams Mode**: Shut down all active teammates. No teammates should remain running after the workflow ends.
+**Agent Teams Mode** (Parallel or Sequential):
+1. Shut down all active teammates. Wait for each to confirm shutdown.
+2. Once all teammates have shut down, clean up the team (delete the `kc-{wgid}` team).
+   No teammates or team resources should remain after the workflow ends.
 
 **Subagent Mode**: No cleanup needed — `Task()` calls are self-contained.
 
----
+### If User Cancels Mid-Workflow
 
-## Complexity Triage
+Follow the abandonment protocol from `knowzcode_loop.md` Section 12:
 
-Before full orchestration, assess the change:
-- Single file, <50 lines, isolated fix? Consider `/kc:fix` instead
-- Multiple files or architectural impact? Continue with full workflow
+1. **Revert uncommitted changes** — if implementation was in progress, revert source code changes (keep knowzcode files)
+2. **Update tracker** — set all affected NodeIDs back to their pre-WorkGroup status
+3. **Log abandonment** — create a log entry with type `WorkGroup-Abandoned` including the reason and phase at abandonment
+4. **Close WorkGroup file** — mark the WorkGroup as `Abandoned` with timestamp and reason
+5. **Preserve learnings** — if any useful patterns were discovered, capture them before closing
+6. **Team teardown** — (Agent Teams only) shut down all active teammates and delete the team
+7. **Parallel mode**: If cancelled mid-Stage-2, revert uncommitted code changes and mark WorkGroup abandoned
+
+The WorkGroup file remains in `knowzcode/workgroups/` for reference. It can be resumed later with `/kc:work` referencing the same goal.
+
+---
 
 ## Handling Failures
 
 - Phase 1A rejected: re-run analyst with feedback
-- Phase 1B rejected: re-run architect with specific issues
-- Phase 2A max iterations exceeded: pause, report blocker
+- Phase 1B rejected: re-run architect with specific issues (Parallel Teams: architect is already warm)
+- Phase 2A blocker encountered: present Blocker Report (per loop.md Section 11) to user with 5 recovery options: (1) modify spec, (2) change approach, (3) split WorkGroup, (4) accept partial with documented gap, (5) cancel WorkGroup
 - Phase 2B audit shows gaps: return to 2A with gap list (see Gap Loop above)
-- If >3 failures on same phase: PAUSE and ask user for direction
+- If >3 failures on same phase: PAUSE and ask user for direction (applies even when `AUTONOMOUS_MODE = true` — this is a safety exception)
 
 ## KnowzCode: Prefix Enforcement