knowzcode 0.1.0 → 0.3.1

package/knowzcode/automation_manifest.md

@@ -1,59 +1,59 @@
-# KnowzCode Automation Manifest
-
-This manifest describes the resources that support the KnowzCode workflow.
-
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `/kc:work` | Start feature workflow with TDD, quality gates, and structured phases |
-| `/kc:plan` | Research and investigate using parallel agents before implementing |
-| `/kc:audit` | Run quality audits (spec, architecture, security, integration) |
-| `/kc:fix` | Execute targeted micro-fix workflow |
-| `/kc:init` | Initialize KnowzCode in current project + generate platform adapters |
-| `/kc:telemetry` | Investigate production telemetry |
-| `/kc:telemetry-setup` | Configure telemetry sources |
-| `/kc:connect-mcp` | Configure MCP server connection |
-| `/kc:learn` | Capture learning to vault |
-| `/kc:register` | Register and configure MCP |
-| `/kc:status` | Check MCP and vault status |
-
-## Agents
-
-| Agent | Phase | Description |
-| --- | --- | --- |
-| `analyst` | 1A | Impact analysis and Change Set proposals |
-| `architect` | 1B | Specification drafting and architecture review |
-| `builder` | 2A | TDD implementation and verification loops |
-| `reviewer` | 2B | Quality audit, security review, compliance |
-| `closer` | 3 | Finalization — specs, tracker, log, architecture |
-| `microfix-specialist` | - | Scope-gated quick fixes |
-| `knowledge-migrator` | - | External knowledge import |
-| `update-coordinator` | - | Framework self-update |
-
-## Skills
-
-| Skill | Purpose |
-| --- | --- |
-| `start-work` | Detect implementation intent and redirect to /kc:work |
-| `continue` | Detect continuation intent and resume active WorkGroup |
-| `load-core-context` | Load project overview, architecture, tracker into memory |
-| `generate-workgroup-id` | Produce WorkGroupID timestamps |
-| `tracker-update` | Apply validated updates to tracker |
-| `spec-template` | Seed specs with 4-section template |
-| `spec-quality-check` | Verify spec completeness |
-| `log-entry-builder` | Structure log entries |
-| `architecture-diff` | Highlight differences between specs and architecture docs |
-| `environment-guard` | Confirm environment context is complete |
-| `tracker-scan` | Extract current status and WorkGroup assignments |
-| `alias-resolver` | Convert natural language to canonical KnowzCode values |
-| `spec-validator` | Validate individual spec quality |
-
-## State Files
-
-The authoritative state:
-- `knowzcode/knowzcode_tracker.md` — backlog and node status
-- `knowzcode/knowzcode_log.md` — operational history
-- `knowzcode/specs/` — NodeID specifications
-- `knowzcode/workgroups/` — session todo queues
-- `knowzcode/knowzcode_architecture.md` — architecture documentation
+# KnowzCode Automation Manifest
+
+This manifest describes the resources that support the KnowzCode workflow.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/kc:work` | Start feature workflow with TDD, quality gates, and structured phases |
+| `/kc:plan` | Research and investigate using parallel agents before implementing |
+| `/kc:audit` | Run quality audits (spec, architecture, security, integration) |
+| `/kc:fix` | Execute targeted micro-fix workflow |
+| `/kc:init` | Initialize KnowzCode in current project + generate platform adapters |
+| `/kc:telemetry` | Investigate production telemetry |
+| `/kc:telemetry-setup` | Configure telemetry sources |
+| `/kc:connect-mcp` | Configure MCP server connection |
+| `/kc:learn` | Capture learning to vault |
+| `/kc:register` | Register and configure MCP |
+| `/kc:status` | Check MCP and vault status |
+
+## Agents
+
+| Agent | Phase | Description |
+| --- | --- | --- |
+| `analyst` | 1A | Impact analysis and Change Set proposals |
+| `architect` | 1B | Specification drafting and architecture review |
+| `builder` | 2A | TDD implementation and verification loops |
+| `reviewer` | 2B | Quality audit, security review, compliance |
+| `closer` | 3 | Finalization — specs, tracker, log, architecture |
+| `microfix-specialist` | - | Scope-gated quick fixes |
+| `knowledge-migrator` | - | External knowledge import |
+| `update-coordinator` | - | Framework self-update |
+
+## Skills
+
+| Skill | Purpose |
+| --- | --- |
+| `start-work` | Detect implementation intent and redirect to /kc:work |
+| `continue` | Detect continuation intent and resume active WorkGroup |
+| `load-core-context` | Load project overview, architecture, tracker into memory |
+| `generate-workgroup-id` | Produce WorkGroupID timestamps |
+| `tracker-update` | Apply validated updates to tracker |
+| `spec-template` | Seed specs with 4-section template |
+| `spec-quality-check` | Verify spec completeness |
+| `log-entry-builder` | Structure log entries |
+| `architecture-diff` | Highlight differences between specs and architecture docs |
+| `environment-guard` | Confirm environment context is complete |
+| `tracker-scan` | Extract current status and WorkGroup assignments |
+| `alias-resolver` | Convert natural language to canonical KnowzCode values |
+| `spec-validator` | Validate individual spec quality |
+
+## State Files
+
+The authoritative state:
+- `knowzcode/knowzcode_tracker.md` — backlog and node status
+- `knowzcode/knowzcode_log.md` — operational history
+- `knowzcode/specs/` — NodeID specifications
+- `knowzcode/workgroups/` — session todo queues
+- `knowzcode/knowzcode_architecture.md` — architecture documentation

package/knowzcode/claude_code_execution.md

@@ -8,15 +8,15 @@ Agents on other platforms should ignore this file — see `knowzcode/platform_ad
 
 ## Agent Teams Overview
 
-Agent Teams is an **experimental** Claude Code feature for multi-agent coordination. It requires the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to be enabled.
+Agent Teams is an **experimental** Claude Code feature for multi-agent coordination. It requires the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to be set in the Claude Code environment.
 
 > **Status:** Experimental. The API may change in future releases.
 
 ### Prerequisites
 
 - Claude Code with Agent Teams support
-- Environment variable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
-- Agent Teams is the preferred execution model when enabled; subagent fallback is used otherwise
+- Environment variable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (set in `~/.claude/settings.json` env block or shell environment)
+- Commands detect Agent Teams at runtime via try-then-fallback: they attempt `TeamCreate()` and fall back to Subagent Delegation if it fails. No manual detection logic is needed in command files.
 
 > **Windows note:** Split-pane mode (`tmux`) is not supported on Windows Terminal. Agent Teams automatically uses `in-process` mode on Windows (the default `auto` mode handles this correctly). No manual configuration is needed.
 
@@ -54,11 +54,69 @@ Agent Teams supports event-driven coordination via hooks:
 - **`TeammateIdle`**: Fires when a teammate finishes its current task — can auto-assign next work
 - **`TaskCompleted`**: Fires when a task is marked complete — can trigger dependent tasks
 
+### Plan Approval Handshake (Agent Teams Only)
+
+When the lead enables plan approval in the spawn prompt (or a teammate has `permissionMode: plan`):
+
+1. **Teammate** presents their plan by calling `ExitPlanMode`
+2. **Lead** receives a `plan_approval_request` message with a `request_id`
+3. **Lead** reviews the plan and responds with `SendMessage` type `plan_approval_response`:
+   - `approve: true` → teammate exits plan mode and proceeds with execution
+   - `approve: false` + `content: "feedback"` → teammate revises their plan and re-presents
+4. **Teammate** receives the response and acts accordingly
+
+The lead MUST respond to every `plan_approval_request` — ignoring it will leave the teammate blocked indefinitely.
+
+#### Autonomous Mode and Plan Approval
+
+When `AUTONOMOUS_MODE = true`, the lead auto-approves all `plan_approval_request` messages immediately. The plan content is still logged for transparency, but no pause for review occurs.
+
+**Exception**: Plans that touch >10 files or propose disabling security measures → pause for manual review even in autonomous mode.
+
+### Handling Shutdown Requests
+
+When you receive a `shutdown_request` from the lead:
+
+1. Complete or save any in-progress work (update the WorkGroup file if needed)
+2. Mark your current task as `completed` (or leave as `in_progress` if unfinished)
+3. Respond with `SendMessage` type `shutdown_response`:
+   - `approve: true` → confirms shutdown, your process will terminate
+   - `approve: false` + `content: "reason"` → if you are mid-critical-operation (e.g., "Completing task, will be ready in a moment")
+4. After approving shutdown, do not take any further actions
+
 ### Limitations
 
 - Experimental feature — API may change
 - Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var
 - Not available in all Claude Code environments
+- No nested teams — teammates never create teams themselves
+
+---
+
+## Team Lifecycle
+
+The team lead manages the full lifecycle of a team. Teammates never create or clean up teams.
+
+### Creation
+
+At the start of a workflow (`/kc:work`, `/kc:plan`, `/kc:audit`), the lead creates a team before spawning any teammates:
+
+- **`/kc:work`**: Team name `kc-{wgid}` (matches the WorkGroup ID)
+- **`/kc:plan`**: Team name `kc-plan-{slug}` (from the research topic)
+- **`/kc:audit`**: Team name `kc-audit-{timestamp}`
+
+Creating a team establishes:
+- A shared task list for structured work tracking
+- A team config that teammates can read to discover each other
+- A coordination namespace for mailbox messaging
+
+### Cleanup
+
+After the workflow completes (or if cancelled), the lead:
+1. Shuts down all active teammates — waits for each to confirm shutdown
+2. Deletes the team — removes team config and task list
+
+No teammates or team resources should remain after a workflow ends.
 
 ---
 
@@ -67,11 +125,13 @@ Agent Teams supports event-driven coordination via hooks:
 When running as teammates in a Claude Code Agent Teams workflow, all agents follow these conventions:
 
 ### Task Lifecycle
-- Receive a task from the team lead with subject and description
+- Your spawn prompt or DM includes your assigned task ID (e.g., `**Your Task**: #5`)
+- Claim immediately: `TaskUpdate(taskId, status: "in_progress")`
 - Read context files listed in task description independently (do not duplicate context across agents)
 - Report progress by updating task status
-- When complete: mark task completed with a summary
+- When complete: `TaskUpdate(taskId, status: "completed")` with a summary
 - If blocked: keep task in_progress with blocker description
+- Do NOT create new tasks for work already assigned to you — use the provided task ID
 
 ### Plan Approval (architect, builder only)
 - **Architect**: Present spec drafts as a plan for lead review before finalizing. Wait for lead approval before writing final specs
@@ -79,42 +139,221 @@ When running as teammates in a Claude Code Agent Teams workflow, all agents foll
 
 ### Inter-Agent Communication
 
-> **Note:** In the default sequential workflow (`/kc:work`), teammates are spawned one at a time and shut down between phases. The messaging patterns below apply when teammates coexist — for example, during `/kc:plan` (3 parallel researchers) or if you keep the builder alive during Phase 2B review for direct gap communication. In sequential mode, inter-phase communication goes through the lead.
+> **Note:** In `/kc:work` Parallel Teams mode, teammates coexist within stages: scouts run alongside analysts, builders and reviewers persist through the gap loop. The messaging patterns below are actively used. In Sequential Teams mode (`--sequential`), teammates are spawned one at a time — inter-phase communication goes through the lead via WorkGroup files.
 
 Use mailbox messaging for coordination between teammates:
 
 | From | To | When |
 |------|-----|------|
+| scout | all | Initial context/vault findings (broadcast) |
 | analyst | architect | Scope clarifications, NodeID overlap with existing specs |
 | architect | analyst | Scope adjustments needed |
-| architect | builder | Spec intent and design decisions |
+| architect | builder | Design guidance and spec intent responses |
 | builder | analyst | Affected files and dependency questions |
-| builder | architect | Spec intent and design decisions |
-| reviewer | builder | Gap details (file, line, criterion, expected vs actual) |
+| builder | architect | Spec clarification requests |
+| builder | builder | Shared interface changes, dependency coordination |
+| reviewer | lead | Gap reports per partition (structured format via task summaries) |
+| lead | builder | Gap fix assignments with context (task creation + DM) |
+| lead | reviewer | Re-audit requests after gap fixes (task creation + DM) |
+| lead | knowz-scribe | Capture messages at quality gates (`"Capture Phase 1A: {wgid}"`, etc.) |
+| 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:
+1. Reviewer reports gaps in task completion summary (structured format)
+2. Lead creates fix task and pre-assigns to builder:
+   `TaskCreate("Fix gaps: NodeID-X")` → `TaskUpdate(taskId, 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, marks fix task complete
+5. Lead creates re-audit task and pre-assigns to reviewer:
+   `TaskCreate("Re-audit: NodeID-X")` → `TaskUpdate(taskId, owner: "reviewer-N")`
+6. Lead sends DM to reviewer with task ID:
+   `"**New Task**: #{reaudit-task-id} — Re-audit: NodeID-X. {gap list}"`
+
+In Sequential Teams mode, the lead spawns a new builder with gap context, then a new reviewer for re-audit.
+
+---
+
+## Parallel Teams Orchestration
+
+This section defines conventions specific to Parallel Teams mode in `/kc:work`. For the full orchestration flow, see `commands/work.md`.
+
+### Lead Responsibilities in Parallel Mode
+
+- Lead is the **sole WorkGroup file writer** — agents report via task completion summaries, lead consolidates
+- Lead manages all agent lifecycles (spawn, shutdown) — agents never self-shutdown
+- Lead creates the task graph progressively (not all upfront) based on dependency map
+- Lead mediates gap flow: reviewer → lead → builder (not direct reviewer → builder for actionable gaps)
+- Lead uses DM messages alongside task creation to provide context and coordinate
+
+### Task Assignment Protocol
+
+When creating a task for a specific agent, the lead MUST thread the task ID:
+1. `TaskCreate(subject, description)` → capture returned `{task-id}`
+2. `TaskUpdate(taskId: "{task-id}", owner: "{agent-name}")` — pre-assign
+3. Include the task ID in the agent's context:
+   - **Spawn prompt** (new agent): Add `**Your Task**: #{task-id}` line
+   - **DM** (existing agent): Include `**New Task**: #{task-id} — "{subject}"`
+
+Agents must NOT create new tasks for work already assigned to them via task ID.
+
+### Agent Lifecycle
+
+| Agent | Spawn At | Shut Down At | Purpose While Alive |
+|-------|----------|-------------|---------------------|
+| context-scout-specs | Stage 0 | After Gate #2 | Spec context lookups |
+| context-scout-workgroups | Stage 0 | After Gate #2 | WorkGroup history lookups |
+| context-scout-backlog | Stage 0 | After Gate #2 | Tracker/log/architecture lookups |
+| knowz-scout | Stage 0 | After Phase 3 capture | Vault queries (read-only) throughout workflow |
+| knowz-scribe | Stage 0 | After Phase 3 capture | Vault writes — receives capture messages, handles all `create_knowledge` calls |
+| analyst | Stage 0 | Early Stage 2 | Scope questions from builders |
+| 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
+
+All tasks in a workflow use `addBlockedBy` to express the dependency chain:
+1. **Visibility**: `TaskList` shows the workflow graph at any point
+2. **Future automation**: Hooks (`TeammateIdle`, `TaskCompleted`) can auto-assign when dependencies resolve
+3. **Progressive creation**: Lead creates tasks stage-by-stage, not all upfront
+
+### Task Graph Patterns
+
+- Stage 0 tasks: scout + knowz-scribe + analysis tasks (no deps)
+- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate)
+- Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
+- Stage 3 tasks: finalization (blocked by audit approval)
 
-### Gap Communication (reviewer -> builder)
-When the reviewer finds gaps during Phase 2B audit, message the builder with specific details:
-- File path and line number
-- Criterion not met (the VERIFY: statement)
-- Expected behavior vs actual behavior
+### Orchestration Configuration
 
-The builder addresses these gaps and re-verifies before reporting completion.
+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 `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
+
+### Persistent Agent Patterns
+
+In `/kc:work` Parallel Teams mode, agents persist across sub-phases for efficiency:
+
+#### Build + Audit Loop
+During Stage 2, each builder is paired with a dedicated reviewer for its partition:
+- One reviewer per builder partition (e.g., builder-1 ↔ reviewer-1, builder-2 ↔ reviewer-2)
+- Each reviewer audits only the NodeIDs in its paired builder's partition
+- Gap loops run independently per partition — partition A's gap loop does not block partition B's audit
+- If gaps found: lead creates fix task for the partition's builder + re-audit task for the partition's reviewer
+- All builders and reviewers stay alive through the entire gap loop — shut down only after Gate #3
+
+This eliminates both cold-start overhead (no respawning) and the sequential bottleneck (no single reviewer processing all partitions).
+
+#### Architect Consultative Persistence
+During Stage 2, the architect persists as a read-only consultative resource:
+- Responds to builder DMs about spec intent, interface contracts, and design decisions
+- Does NOT write code, modify specs, or create tasks
+- Lead notifies architect when builders are spawned — architect sends intro message to each builder
+- Shut down with builders and reviewers after Gate #3
+
+#### Discovery Pre-loading
+During Stage 0, the architect pre-loads context in parallel with analysis:
+- Architect reads architecture docs, existing specs, project config
+- 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
 
+### Agent Teams Mode (spawned as a teammate)
+
 When spawned as a teammate in an Agent Teams workflow, follow this sequence:
 
-1. Read your agent definition file (referenced in your spawn prompt, e.g. `agents/analyst.md`)
-2. Read this file (`knowzcode/claude_code_execution.md`) for team conventions
-3. Read the WorkGroup file for current state, Change Set, and context
-4. Read context files listed in your task description
-5. Begin your phase work as defined by your role
-6. Update the WorkGroup file with results — prefix all todo entries with `KnowzCode:`
-7. Mark your task as complete with a summary of what was delivered
+1. Read your agent definition file (referenced in your spawn prompt)
+2. Claim your assigned task: `TaskUpdate(taskId: "{task-id from spawn prompt}", status: "in_progress")`
+3. Read this file (`knowzcode/claude_code_execution.md`) for team conventions
+4. Read the WorkGroup file for current state, Change Set, and context
+5. Read context files listed in your task description
+6. Begin your phase work as defined by your role
+7. Update the WorkGroup file with results — prefix all todo entries with `KnowzCode:`
+8. Mark your task as complete with a summary of what was delivered
+
+### Subagent Mode (spawned via Task())
+
+When spawned as a custom subagent type (e.g. `subagent_type: "analyst"`), your agent definition from `agents/*.md` is **auto-loaded as your system prompt**. This means:
+
+- Step 1 above is already done — your role definition, tools, and constraints are pre-loaded
+- Your `tools`, `model`, `permissionMode`, and `maxTurns` from the YAML frontmatter are enforced automatically
+- You only need to read the task-specific context provided in the spawn prompt (WorkGroup file, specs, context files)
+- Begin your phase work directly
+
+### For Both Modes
 
 If you encounter a blocker, keep the task in `in_progress` status with a description of what is blocking you. Do not mark the task as complete until the work is done.
 
@@ -131,3 +370,33 @@ Agents may reference these Claude Code commands as escalation paths:
 | `/kc:audit spec` | knowledge-migrator | Post-migration validation |
 
 On other platforms, these commands translate to running the corresponding phase prompts manually.
+
+---
+
+## Verification & Troubleshooting
+
+### How to verify Agent Teams is working
+
+1. Run `/kc:status` — check the Agent Teams section for "Enabled" status and agent definitions
+2. Run `/kc:work` — confirm a mode announcement appears before Phase 1A (either "Agent Teams" or "Subagent Delegation")
+3. In-process mode: press Shift+Down to see spawned teammates in the panel
+4. Check the WorkGroup file — should show phase transitions with timestamps in the Phase History table
+
+### Common issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No mode announcement | Command didn't run setup step | Verify commands are updated (Step 2 should announce mode) |
+| "Subagent Delegation" when expecting Agent Teams | Env var not set or Claude Code not restarted | Add `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to settings.json `env` block. **Restart Claude Code** — env vars are only loaded on startup. |
+| Agents seem generic / no specialization | Agent definitions not loaded | Check `agents/` directory exists with `.md` files for each role |
+| No quality gates appearing | Command instructions not followed | Re-run `/kc:work` with an explicit goal description |
+| Teammates not visible in panel | Using tmux mode on Windows | Windows uses in-process mode — teammates won't appear in a split pane |
+
+### Verifying after a workflow
+
+Check the WorkGroup file at `knowzcode/workgroups/{wgid}.md`:
+
+- **Phase History table** should show all phases with timestamps and statuses
+- **Change Set** should be populated (Phase 1A output) with NodeIDs and descriptions
+- **Todos** should all start with the `KnowzCode:` prefix
+- **Status** should show "Closed" after Phase 3 completes