knowzcode 0.1.0 → 0.3.1

package/commands/plan.md

@@ -26,54 +26,165 @@ If no argument provided, ask: "What would you like me to research?"
 
 If `knowzcode/` doesn't exist, inform user to run `/kc:init` first. STOP.
 
-## Step 3: Launch Parallel Investigation
+## Step 3: Set Up Execution Mode
 
-### Agent Teams Mode (if available)
+Attempt `TeamCreate(team_name="kc-plan-{slug}")` (2-4 word kebab-case from topic):
 
-Spawn three teammates to investigate simultaneously:
+- **If TeamCreate succeeds** → Agent Teams mode:
+  1. Announce: `**Execution Mode: Agent Teams** — created team kc-plan-{slug}`
+  2. Read `knowzcode/claude_code_execution.md` for team conventions.
+  3. You are the **team lead** — coordinate research, synthesize findings.
 
-1. Spawn `analyst` teammate:
+- **If TeamCreate fails** (error, unrecognized tool, timeout) → Subagent Delegation:
+  - Announce: `**Execution Mode: Subagent Delegation** — Agent Teams not available, using Task() fallback`
+
+The user MUST see the execution mode announcement before investigation begins.
+
+## Step 3.5: Load Orchestration Config (Optional)
+
+If `knowzcode/knowzcode_orchestration.md` exists, parse:
+1. `SCOUT_MODE` = `scout_mode` value (default: "full")
+2. `MCP_AGENTS_ENABLED` = `mcp_agents_enabled` value (default: true)
+
+Flag overrides: `--no-scouts` → `SCOUT_MODE = "none"`, `--no-mcp` → `MCP_AGENTS_ENABLED = false`
+
+If file doesn't exist, use defaults. Other config settings (`max_builders`, `default_specialists`) are not applicable to `/kc:plan`.
+
+## Step 4: Launch Parallel Investigation
+
+### MCP Probe
+
+Before spawning agents, determine vault availability:
+1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
+2. Call `list_vaults(includeStats=true)` **always** — regardless of whether any IDs exist in the file
+3. If `list_vaults()` fails → set `MCP_ACTIVE = false`, announce `**MCP Status: Not connected**`, skip vault setup
+4. If `list_vaults()` succeeds AND UNCREATED list is non-empty → present the **Vault Creation Prompt**:
+
+   ```markdown
+   ## Vault Setup
+
+   Your Knowz API key is valid and MCP is connected, but {N} default vault(s) haven't been created yet.
+   Creating vaults enables knowledge capture throughout the workflow:
+
+   | Vault | Type | Description | Written During |
+   |-------|------|-------------|----------------|
+   ```
+
+   Build table rows dynamically from the UNCREATED entries only. Derive "Written During" from each vault's Write Conditions field in `knowzcode_vaults.md`.
+
+   Then present options:
+   ```
+   Options:
+     **A) Create all {N} vaults** (recommended)
+     **B) Select which to create**
+     **C) Skip** — proceed without vaults (can create later with `/kc:connect-mcp --configure-vaults`)
+   ```
+
+5. Handle user selection:
+   - **A**: For each UNCREATED entry, call MCP `create_vault(name, description)`. If `create_vault` is not available, fall back to matching by name against `list_vaults()` results. Update `knowzcode_vaults.md`: fill ID field, change H3 heading from `(not created)` to vault ID. Report any failures.
+   - **B**: Ask which vaults to create, then create only selected ones.
+   - **C**: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
+6. After resolution, set:
+   - `MCP_ACTIVE = true` (MCP works regardless of vault creation outcome)
+   - `VAULTS_CONFIGURED = true` if at least 1 vault now has a valid ID, else `false`
+   - Announce: `**MCP Status: Connected — N vault(s) available**` or `**MCP Status: Connected — no vaults configured (knowledge capture disabled)**`
+
+### Agent Teams Mode (with scouts)
+
+Create tasks first, pre-assign, then spawn with task IDs:
+
+1. If `SCOUT_MODE != "none"`: `TaskCreate("Scout: local context for {topic}")` → `TaskUpdate(owner: "context-scout")`
+2. `TaskCreate("Scout: vault knowledge for {topic}")` → `TaskUpdate(owner: "knowz-scout")` (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`)
+3. `TaskCreate("Research: code exploration")` → `TaskUpdate(owner: "analyst")`
+4. `TaskCreate("Research: architecture")` → `TaskUpdate(owner: "architect")`
+5. `TaskCreate("Research: security + quality")` → `TaskUpdate(owner: "reviewer")`
+
+Spawn teammates with their task IDs (count depends on SCOUT_MODE and MCP settings):
+
+1. If `SCOUT_MODE != "none"`, spawn `context-scout` teammate:
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+   > You are researching "{topic}" from a **knowzcode history** angle.
+   > Read `agents/context-scout.md` for your role definition.
+   > Read `knowzcode/claude_code_execution.md` for team conventions.
+   > Find: existing specs, prior WorkGroups, tracker entries relevant to this topic.
+   > Broadcast findings to all teammates.
+
+2. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, spawn `knowz-scout` teammate:
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
+   > You are researching "{topic}" from a **vault knowledge** angle.
+   > Read `agents/knowz-scout.md` for your role definition.
+   > Read `knowzcode/claude_code_execution.md` for team conventions.
+   > Query: team conventions, past decisions, similar implementations.
+   > Broadcast findings to all teammates.
+
+3. Spawn `analyst` teammate:
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
    > You are researching "{topic}" from a **code exploration** angle.
    > Read `agents/analyst.md` for your role definition.
    > Read `knowzcode/claude_code_execution.md` for team conventions.
    > Investigate: affected files, dependencies, existing patterns.
    > Max 10 tool calls. Write findings to a concise summary.
 
-2. Spawn `architect` teammate:
+4. Spawn `architect` teammate:
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
    > You are researching "{topic}" from an **architecture** angle.
    > Read `agents/architect.md` for your role definition.
    > Read `knowzcode/claude_code_execution.md` for team conventions.
    > Investigate: layer analysis, design implications, pattern fit.
    > Max 10 tool calls. Write findings to a concise summary.
 
-3. Spawn `reviewer` teammate:
+5. Spawn `reviewer` teammate:
+   > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
    > You are researching "{topic}" from a **security and quality** angle.
    > Read `agents/reviewer.md` for your role definition.
    > Read `knowzcode/claude_code_execution.md` for team conventions.
    > Investigate: risks, performance concerns, quality gaps.
    > Max 10 tool calls. Write findings to a concise summary.
 
-Create three tasks (no dependencies — all run in parallel).
-Wait for all three to complete, then synthesize in Step 5.
-
-### Subagent Mode (fallback)
-
-Delegate to three agents in parallel via `Task()`:
-- **analyst**: Code exploration — affected files, dependencies, existing patterns
-- **architect**: Architecture assessment — layer analysis, design implications, pattern fit
-- **reviewer**: Security and quality — risks, performance concerns, quality gaps
+Scouts broadcast findings; all three core researchers consume them.
+Wait for all to complete, then synthesize in Step 5.
+
+### Subagent Mode
+
+Delegate to up to five agents in parallel via `Task()`:
+
+1. **context-scout** — Local context (if `SCOUT_MODE != "none"`):
+   - `SCOUT_MODE = "full"` (default): 3 parallel instances:
+     - `Task(subagent_type="context-scout", name="context-scout-specs", description="Scout: specs context", prompt="Research \"{topic}\". Focus: knowzcode/specs/*.md — scan existing specifications for relevant NodeIDs, status, VERIFY criteria. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-workgroups", description="Scout: workgroups context", prompt="Research \"{topic}\". Focus: knowzcode/workgroups/*.md — scan previous WorkGroups for similar goals, what was tried, what succeeded/failed. Max 10 tool calls. Write findings to a concise summary.")`
+     - `Task(subagent_type="context-scout", name="context-scout-backlog", description="Scout: backlog context", prompt="Research \"{topic}\". Focus: knowzcode/knowzcode_tracker.md, knowzcode/knowzcode_log.md, knowzcode/knowzcode_architecture.md, knowzcode/knowzcode_project.md — scan for active WIP, REFACTOR tasks, architecture summary, recent log patterns. Max 10 tool calls. Write findings to a concise summary.")`
+   - `SCOUT_MODE = "minimal"`: 1 combined instance:
+     - `Task(subagent_type="context-scout", name="context-scout", description="Scout: combined context", prompt="Research \"{topic}\". Focus: 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. Max 10 tool calls. Write findings to a concise summary.")`
+
+2. **knowz-scout** — MCP knowledge (if `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`):
+   - `Task(subagent_type="knowz-scout", description="Scout: vault knowledge", prompt="Research \"{topic}\". Read knowzcode/knowzcode_vaults.md to discover configured vaults. Query each for relevant knowledge: team conventions, past decisions, similar implementations. Max 10 tool calls. Write findings to a concise summary.")`
+
+3. **analyst** — Code exploration:
+   - `subagent_type`: `"analyst"`
+   - `prompt`: Task-specific context only (role definition is auto-loaded from `agents/analyst.md`):
+     > Research "{topic}" from a **code exploration** angle.
+     > Investigate: affected files, dependencies, existing patterns.
+     > Max 10 tool calls. Write findings to a concise summary.
+   - `description`: `"Plan research: code exploration"`
+
+4. **architect** — Architecture assessment:
+   - `subagent_type`: `"architect"`
+   - `prompt`: Task-specific context only (role definition is auto-loaded from `agents/architect.md`):
+     > Research "{topic}" from an **architecture** angle.
+     > Investigate: layer analysis, design implications, pattern fit.
+     > Max 10 tool calls. Write findings to a concise summary.
+   - `description`: `"Plan research: architecture"`
+
+5. **reviewer** — Security and quality:
+   - `subagent_type`: `"reviewer"`
+   - `prompt`: Task-specific context only (role definition is auto-loaded from `agents/reviewer.md`):
+     > Research "{topic}" from a **security and quality** angle.
+     > Investigate: risks, performance concerns, quality gaps.
+     > Max 10 tool calls. Write findings to a concise summary.
+   - `description`: `"Plan research: security and quality"`
 
 Each uses focused, efficient scoping (max 10 tool calls).
 
-## Step 4: Check Existing Knowledge (in parallel)
-
-While agents investigate, also check:
-- `knowzcode/specs/*.md` for relevant specifications
-- `knowzcode/knowzcode_tracker.md` for related WorkGroups
-- `knowzcode/workgroups/*.md` for prior related work
-
-If MCP is configured: `search_knowledge(research_vault, "{topic}")` for past decisions.
-
 ## Step 5: Synthesize Findings
 
 ```markdown
@@ -88,9 +199,10 @@ If MCP is configured: `search_knowledge(research_vault, "{topic}")` for past dec
 ### Security & Quality
 {summarized findings from reviewer}
 
-### Existing Knowledge
+### Existing Knowledge (from scouts)
 - **Relevant Specs**: {list or "None found"}
 - **Prior WorkGroups**: {list or "None found"}
+- **Vault Knowledge**: {list or "N/A — MCP not configured"}
 
 ### Recommended Approaches
 
@@ -105,6 +217,19 @@ If MCP is configured: `search_knowledge(research_vault, "{topic}")` for past dec
 ### Risks & Considerations
 {synthesized risks}
 
+### Complexity Assessment
+- **Files identified**: {count} — {file list}
+- **Potential NodeIDs**: {count} — {brief descriptions}
+- **Architectural impact**: Yes/No — {reason if yes}
+- **Security-sensitive**: Yes/No — {reason if yes}
+- **External integrations**: Yes/No — {list if yes}
+- **Estimated scope**: ~{N} lines across {M} files
+- **Recommended tier**: Tier 2 (Light) / Tier 3 (Full)
+
+Tier recommendation follows work.md's classification rules:
+- **Tier 3** if ANY: >3 files, >1 NodeID, architectural impact, security-sensitive, external integrations
+- **Tier 2** if ALL: ≤3 files, single NodeID, no arch changes, no security, no external APIs
+
 ---
 
 **Ready to implement?** Say "implement", "do option 1", or "go ahead" to start `/kc:work` with this context.
@@ -114,7 +239,29 @@ If MCP is configured: `search_knowledge(research_vault, "{topic}")` for past dec
 
 Watch for: "implement", "do it", "go ahead", "option N", "start work", "build this"
 
-When triggered, invoke `/kc:work "{original_topic}"` with investigation context.
+When triggered, invoke `/kc:work "{original_topic}" --tier {recommended_tier}` and include
+a summary of investigation findings:
+
+> **Plan investigation context:**
+> - Files: {file list from complexity assessment}
+> - Potential NodeIDs: {list}
+> - Key risks: {top risks}
+> - Recommended approach: {selected option or top recommendation}
+
+This context gives work's analyst a head start and ensures correct tier classification.
+
+---
+
+## Cleanup
+
+After synthesis is complete (or if the user cancels):
+
+**Agent Teams Mode**:
+1. Shut down all active teammates. Wait for each to confirm shutdown.
+2. Once all teammates have shut down, clean up the team.
+   No teammates or team resources should remain after the research ends.
+
+**Subagent Mode**: No cleanup needed — `Task()` calls are self-contained.
 
 ---
 

package/commands/register.md

@@ -368,23 +368,29 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
 
    ## Vaults
 
-   ### Research Vault (Primary)
+   ### Ecosystem Vault (Primary)
    - **Vault ID**: {vault_id from registration}
    - **Vault Name**: {vault_name from registration}
-   - **Purpose**: Learnings, conventions, decisions, patterns
+   - **Purpose**: Decisions, conventions, security, integrations, business rules
    - **Auto-configured**: Yes (via /kc:register)
 
    ### Code Vault (Optional)
    - **Vault ID**: (not configured)
-   - **Purpose**: Indexed source code for semantic search
+   - **Purpose**: Implementation patterns, workarounds, performance
    - **Note**: Code search uses local grep/glob by default.
             Configure code vault for large codebases with /kc:connect-mcp --configure-vaults
+
+   ### Finalizations Vault (Optional)
+   - **Vault ID**: (not configured)
+   - **Purpose**: WorkGroup completion summaries, outcome records
+   - **Note**: Finalizations vault tracks completed work.
+            Configure for teams that want searchable completion history.
    ```
 
    **Edge case - existing vault config**:
-   If `knowzcode/mcp_config.md` already has a Research Vault ID configured:
+   If `knowzcode/mcp_config.md` already has an Ecosystem Vault ID configured:
    - Use AskUserQuestion: "You already have a vault configured. Replace with new vault from registration? [Yes/No/Keep both]"
-   - If "Yes": Replace Research Vault ID
+   - If "Yes": Replace Ecosystem Vault ID
    - If "No": Keep existing vault config
    - If "Keep both": Add new vault as secondary
 
@@ -488,9 +494,9 @@ After MCP is configured and before showing the final success message, offer vaul
    ┌────┬──────────────────────┬──────────────────┬───────────┐
    │ #  │ Name                 │ Type             │ Documents │
    ├────┼──────────────────────┼──────────────────┼───────────┤
-   │ 1  │ KnowzCode (default)  │ research         │ 0         │
+   │ 1  │ KnowzCode (default)  │ ecosystem        │ 0         │
    │ 2  │ my-project-code      │ code             │ 1,234     │
-   │ 3  │ engineering-wiki     │ research         │ 89        │
+   │ 3  │ engineering-wiki     │ ecosystem        │ 89        │
    └────┴──────────────────────┴──────────────────┴───────────┘
    ```
 
@@ -545,13 +551,13 @@ After MCP is configured and before showing the final success message, offer vaul
    ### {vault_id_1}
    - **Name**: {vault_name}
    - **ID**: {vault_id}
-   - **Type**: {code | research}
+   - **Type**: {code | ecosystem | finalizations}
    - **Description**: {user_provided_description}
 
    ### {vault_id_2}
    - **Name**: {vault_name}
    - **ID**: {vault_id}
-   - **Type**: {code | research}
+   - **Type**: {code | ecosystem | finalizations}
    - **Description**: {user_provided_description}
 
    ---
@@ -559,10 +565,13 @@ After MCP is configured and before showing the final success message, offer vaul
    ## Vault Routing Rules
 
    - **Code questions** (implementations, files, structure) → {first code vault}
-   - **Convention questions** (patterns, decisions, best practices) → {first research vault}
-   - **Learning capture** → {default research vault}
+   - **Convention questions** (patterns, decisions, best practices) → {first ecosystem vault}
+   - **Completion records** → {first finalizations vault}
+   - **Learning capture** → {default ecosystem vault}
    ```
 
+   **Null GUID detection**: After writing vault configuration to `knowzcode_vaults.md`, check for entries with empty **ID** fields. If found, prompt: "Found {N} default vault(s) not yet created. Create them now?" On confirmation, create each vault via MCP and update the ID fields.
+
 5. **Show vault configuration summary**
 
    After writing configuration:
@@ -570,7 +579,7 @@ After MCP is configured and before showing the final success message, offer vaul
    Vault configuration saved to knowzcode/knowzcode_vaults.md
 
    Connected Vaults:
-     • KnowzCode (research) - "Team learnings and conventions"
+     • KnowzCode (ecosystem) - "Team learnings and conventions"
      • my-code (code) - "Source code for API project"
 
    Queries will be automatically routed based on your descriptions.