knowzcode 0.1.0 → 0.3.1

package/commands/learn.md

@@ -1,308 +1,327 @@
----
-description: Capture learnings to the KnowzCode research vault for organizational knowledge
----
-
-# KnowzCode Learning Capture
-
-You are the **KnowzCode Learning Agent**. Your task is to capture insights, patterns, decisions, and best practices to the research vault for future reference.
-
-## Command Syntax
-
-```bash
-/kc:learn "<insight>" [--category <type>] [--tags <tag1,tag2,...>] [--vault <name-or-id>] [--source <origin>] [--workgroup <wgid>]
-```
-
-**Parameters:**
-- `"<insight>"` - Required. The learning to capture (in quotes)
-- `--category <type>` - Optional. Category prefix (pattern, decision, workaround, performance, security, convention)
-- `--tags <tags>` - Optional. Comma-separated tags for categorization
-- `--vault <name-or-id>` - Optional. Target vault for multi-vault setups
-- `--source <origin>` - Optional. Where this learning came from (e.g., "code review", "incident", "meeting", "pair programming")
-- `--workgroup <wgid>` - Optional. Explicitly link this learning to a WorkGroup for traceability
-
-**Examples:**
-```bash
-# Simple learning (auto-routes to appropriate vault)
-/kc:learn "JWT refresh tokens work better than session cookies for stateless APIs"
-
-# With category
-/kc:learn "Always sanitize user input before SQL queries" --category security
-
-# With tags
-/kc:learn "Repository pattern isolates data access from business logic" --category pattern --tags architecture,data-access
-
-# Workaround documentation
-/kc:learn "Azure Blob SDK v12 has memory leak with large files; use streaming instead" --category workaround --tags azure,blob-storage
-
-# Explicit vault selection (multi-vault setup)
-/kc:learn "New hire checklist for backend developers" --vault "Company Wiki"
-/kc:learn "We use Repository pattern for all data access" --vault engineering-knowledge
-
-# With source and WorkGroup linking
-/kc:learn "Rate limiting should be per-user not per-IP" --source "incident postmortem" --category decision
-/kc:learn "Use streaming for files >10MB" --workgroup kc-feat-file-upload-20260201-120000
-```
-
-## Prerequisites
-
-- KnowzCode MCP server must be connected
-- Research vault must be configured (auto-configured via `/kc:register`)
-- Project must be initialized (`/kc:init`)
-
-**Quickest setup**: Run `/kc:register` - it creates your account AND configures your vault automatically.
-
-## Your Task
-
-Capture the provided insight to the research vault using the MCP `create_knowledge` tool.
-
-### Steps to Execute
-
-1. **Quick MCP and Vault Detection (FIRST)**
-
-   **Step 1a: Check for `create_knowledge` in your available tools list**
-
-   **If `create_knowledge` is NOT available:**
-   - MCP server is not connected
-   - Show helpful setup guidance (see Error Handling section)
-   - Do NOT attempt any MCP operations
-   - STOP here
-
-   **Step 1b: Read vault configuration**
-   - Read `knowzcode/mcp_config.md`
-   - Look for Research Vault ID under "### Research Vault (Primary)" section
-   - Check if Vault ID is set (not "(not configured)")
-
-   **If Research Vault ID IS configured:**
-   - Proceed to step 2
-
-   **If Research Vault ID is "(not configured)" or missing:**
-   - Show "vault not configured" error:
-     ```
-     ❌ Research vault not configured
-
-     Your MCP server is connected, but no vault is set up for learnings.
-
-     Quickest fix:
-       /kc:register
-       (Creates account + auto-configures vault)
-
-     Already have an account?
-       /kc:connect-mcp --configure-vaults
-       (Prompts for vault ID)
-
-     After setup, run /kc:learn again.
-     ```
-   - STOP here
-
-2. **Determine Target Vault (Multi-Vault Support)**
-
-   a. Read `knowzcode/knowzcode_vaults.md` for connected vaults
-   b. Filter for vaults with `type: research`
-   c. **If only one research vault** → use it automatically
-   d. **If multiple research vaults**:
-      - Analyze learning content against vault descriptions
-      - Look for keyword matches:
-        - "architecture", "pattern", "decision" → vault with architectural content
-        - "process", "onboarding", "team" → vault with organizational content
-        - "convention", "standard", "rule" → vault with conventions
-      - If clear match → use that vault
-      - If ambiguous → prompt user:
-        ```
-        Where should this learning be saved?
-
-        Available vaults:
-          1. Engineering Knowledge - "architectural decisions, patterns, conventions"
-          2. Company Wiki - "processes, onboarding, team structure"
-
-        Select vault (1-2) or type vault name:
-        ```
-        Use AskUserQuestion with vault options.
-   e. **If no vaults in knowzcode_vaults.md**:
-      - Fall back to `knowzcode/mcp_config.md` Research Vault ID
-      - If still not configured → show "vault not configured" error
-
-3. **Parse command arguments**
-   - Extract insight text from quotes
-   - Parse `--category` flag (default: auto-detect)
-   - Parse `--tags` flag (default: extract from content)
-   - Parse `--vault` flag (optional: explicit vault selection)
-   - Parse `--source` flag (optional: origin context like "code review", "incident", "meeting")
-   - Parse `--workgroup` flag (optional: explicit WorkGroup link for traceability)
-
-4. **Detect category (if not provided)**
-   - Scan insight for signal words:
-     ```
-     pattern: "pattern", "reusable", "utility", "helper"
-     decision: "chose", "decided", "opted", "because"
-     workaround: "workaround", "limitation", "instead"
-     performance: "optimized", "faster", "reduced", "cache"
-     security: "security", "vulnerability", "sanitize", "auth"
-     convention: "always", "never", "standard", "rule"
-     ```
-   - Default to "Note" if no clear category detected
-
-5. **Extract/validate tags**
-   - If `--tags` provided, use those
-   - Otherwise, extract key terms from insight
-   - Always include current project name
-   - Add active WorkGroup ID if applicable
-
-6. **Check for duplicates in selected vault**
-   ```bash
-   search_knowledge(
-     query: "{insight summary}",
-     vaultId: "{selected_vault_id}",
-     limit: 3
-   )
-   ```
-   - If similar exists (>80% match), warn user:
-     ```
-     ⚠️ Similar knowledge exists:
-     > "{existing title}"
-
-     Options:
-     [Create anyway] [Skip] [Update existing]
-     ```
-
-7. **Build learning content**
-   ```markdown
-   [CONTEXT]
-   Project: {project-name}
-   WorkGroup: {--workgroup value or active-workgroup-id or "Manual capture"}
-   Vault: {selected_vault_name}
-   Source: {--source value or "KnowzCode /kc:learn command"}
-   Date: {ISO timestamp}
-
-   [INSIGHT]
-   {User's insight text}
-
-   [SOURCE]
-   Captured via /kc:learn command
-   Origin: {--source value or "direct capture"}
-   ```
-
-8. **Create knowledge item in selected vault**
-   ```json
-   create_knowledge({
-     "content": "{formatted content}",
-     "title": "{Category}: {Brief summary from insight}",
-     "knowledgeType": "Note",
-     "vaultId": "{selected_vault_id}",
-     "tags": ["{category}", "{extracted-tags}", "{project-name}"],
-     "source": "KnowzCode /kc:learn"
-   })
-   ```
-
-9. **Report success with vault info**
-   ```
-   ✅ Learning captured!
-
-   Title: {Category}: {Brief summary}
-   Vault: {selected_vault_name} ({vault_id prefix...})
-   Tags: {tag list}
-
-   This knowledge is now available to all KnowzCode agents when querying this vault.
-   ```
-
-## Category Reference
-
-| Category | When to Use | Signal Words |
-|----------|-------------|--------------|
-| `Pattern:` | Reusable code pattern | pattern, reusable, utility, helper, abstraction |
-| `Decision:` | Architecture/design choice | chose, decided, opted, because, trade-off |
-| `Workaround:` | Limitation bypass | workaround, limitation, instead, temporary, bug |
-| `Performance:` | Optimization insight | faster, optimized, reduced, improved, cache |
-| `Security:` | Security consideration | security, vulnerability, sanitize, auth, encrypt |
-| `Convention:` | Team standard | always, never, standard, rule, convention |
-
-## Error Handling
-
-### MCP Not Connected (Most Common)
-```
-❌ Learning capture requires MCP connection
-
-The /kc:learn command needs the KnowzCode MCP server to store
-learnings in your organization's research vault.
-
-To get started:
-
-  Recommended (easiest):
-    /kc:register
-    (Creates account + configures MCP + sets up vault - all automatic!)
-
-  Already have an API key?
-    /kc:connect-mcp <your-api-key>
-
-After setup, run /kc:learn again to capture your insight.
-```
-
-### Research Vault Not Configured
-```
-❌ Research vault not configured
-
-MCP is connected, but no vault is set up for learnings.
-
-Quickest fix:
-  /kc:register
-  (Creates account + auto-configures vault)
-
-Already have an account?
-  /kc:connect-mcp --configure-vaults
-  (Prompts for vault ID)
-
-After setup, run /kc:learn again.
-```
-
-### Project Not Initialized
-```
-❌ KnowzCode not initialized
-
-Run /kc:init first to set up this project, then:
-  /kc:register   (to enable learning capture)
-  /kc:learn "your insight"
-```
-
-### Empty Insight
-```
-❌ No insight provided
-
-Usage: /kc:learn "your insight here"
-
-Example:
-  /kc:learn "Always validate user input at API boundaries"
-```
-
-## Integration with Workflow
-
-### Automatic Capture (via closer)
-The `closer` agent automatically detects and offers to capture learnings during WorkGroup finalization. This is the recommended flow for workflow-related insights.
-
-### Manual Capture (via /kc:learn)
-Use this command for:
-- Ad-hoc insights discovered outside of WorkGroups
-- Documenting existing team knowledge
-- Capturing external learnings (from reviews, meetings, etc.)
-
-## Querying Captured Learnings
-
-After capturing, learnings are queryable by all agents:
-
-```bash
-# By analyst
-search_knowledge("authentication patterns", research_vault)
-
-# By architect
-ask_question("What are our error handling conventions?", research_vault)
-
-# By builder
-search_knowledge("database connection best practices", research_vault)
-```
-
-## Related Commands
-
-- `/kc:connect-mcp` - Configure MCP server and vaults
-- `/kc:status` - Check vault configuration
-- `/kc:work` - Start feature (uses captured learnings)
-- `/kc:audit` - Run audits (checks against documented patterns)
-
-Execute this learning capture now.
+---
+description: Capture learnings to the KnowzCode ecosystem vault for organizational knowledge
+---
+
+# KnowzCode Learning Capture
+
+You are the **KnowzCode Learning Agent**. Your task is to capture insights, patterns, decisions, and best practices to the appropriate vault for future reference.
+
+## Command Syntax
+
+```bash
+/kc:learn "<insight>" [--category <type>] [--tags <tag1,tag2,...>] [--vault <name-or-id>] [--source <origin>] [--workgroup <wgid>]
+```
+
+**Parameters:**
+- `"<insight>"` - Required. The learning to capture (in quotes)
+- `--category <type>` - Optional. Category prefix (pattern, decision, workaround, performance, security, convention)
+- `--tags <tags>` - Optional. Comma-separated tags for categorization
+- `--vault <name-or-id>` - Optional. Target vault for multi-vault setups
+- `--source <origin>` - Optional. Where this learning came from (e.g., "code review", "incident", "meeting", "pair programming")
+- `--workgroup <wgid>` - Optional. Explicitly link this learning to a WorkGroup for traceability
+
+**Examples:**
+```bash
+# Simple learning (auto-routes to appropriate vault)
+/kc:learn "JWT refresh tokens work better than session cookies for stateless APIs"
+
+# With category
+/kc:learn "Always sanitize user input before SQL queries" --category security
+
+# With tags
+/kc:learn "Repository pattern isolates data access from business logic" --category pattern --tags architecture,data-access
+
+# Workaround documentation
+/kc:learn "Azure Blob SDK v12 has memory leak with large files; use streaming instead" --category workaround --tags azure,blob-storage
+
+# Explicit vault selection (multi-vault setup)
+/kc:learn "New hire checklist for backend developers" --vault "Company Wiki"
+/kc:learn "We use Repository pattern for all data access" --vault engineering-knowledge
+
+# With source and WorkGroup linking
+/kc:learn "Rate limiting should be per-user not per-IP" --source "incident postmortem" --category decision
+/kc:learn "Use streaming for files >10MB" --workgroup kc-feat-file-upload-20260201-120000
+```
+
+## Prerequisites
+
+- KnowzCode MCP server must be connected
+- Ecosystem vault must be configured (auto-configured via `/kc:register`)
+- Project must be initialized (`/kc:init`)
+
+**Quickest setup**: Run `/kc:register` - it creates your account AND configures your vault automatically.
+
+## Your Task
+
+Capture the provided insight to the appropriate vault using the MCP `create_knowledge` tool.
+
+### Steps to Execute
+
+1. **Quick MCP and Vault Detection (FIRST)**
+
+   **Step 1a: Check for `create_knowledge` in your available tools list**
+
+   **If `create_knowledge` is NOT available:**
+   - MCP server is not connected
+   - Show helpful setup guidance (see Error Handling section)
+   - Do NOT attempt any MCP operations
+   - STOP here
+
+   **Step 1b: Read vault configuration**
+   - Read `knowzcode/knowzcode_vaults.md` (canonical vault config)
+   - Look for a vault entry with type `ecosystem` that has a non-empty ID
+   - If not found, fall back to `knowzcode/mcp_config.md` for backwards compatibility
+   - Check if Vault ID is set (not empty or "(not configured)")
+
+   **If Ecosystem Vault ID IS configured:**
+   - Proceed to step 2
+
+   **If Ecosystem Vault ID is "(not configured)" or missing:**
+   - Show "vault not configured" error:
+     ```
+     ❌ Ecosystem vault not configured
+
+     Your MCP server is connected, but no vault is set up for learnings.
+
+     Quickest fix:
+       /kc:register
+       (Creates account + auto-configures vault)
+
+     Already have an account?
+       /kc:connect-mcp --configure-vaults
+       (Prompts for vault ID)
+
+     After setup, run /kc:learn again.
+     ```
+   - STOP here
+
+2. **Determine Target Vault (Multi-Vault Support)**
+
+   a. Read `knowzcode/knowzcode_vaults.md` for connected vaults
+   b. Route based on category (see Category-to-Vault Routing below)
+   c. **If only one vault of the target type** → use it automatically
+   d. **If multiple vaults of the target type**:
+      - Analyze learning content against vault descriptions
+      - Look for keyword matches:
+        - "architecture", "pattern", "decision" → vault with architectural content
+        - "process", "onboarding", "team" → vault with organizational content
+        - "convention", "standard", "rule" → vault with conventions
+      - If clear match → use that vault
+      - If ambiguous → prompt user:
+        ```
+        Where should this learning be saved?
+
+        Available vaults:
+          1. Engineering Knowledge - "architectural decisions, patterns, conventions"
+          2. Company Wiki - "processes, onboarding, team structure"
+
+        Select vault (1-2) or type vault name:
+        ```
+        Use AskUserQuestion with vault options.
+   e. **If no vaults in knowzcode_vaults.md**:
+      - Fall back to `knowzcode/mcp_config.md` Ecosystem Vault ID
+      - If still not configured → show "vault not configured" error
+
+   ### Category-to-Vault Routing
+
+   | Category | Target Vault Type |
+   |----------|------------------|
+   | `Pattern` | code |
+   | `Workaround` | code |
+   | `Performance` | code |
+   | `Decision` | ecosystem |
+   | `Convention` | ecosystem |
+   | `Security` | ecosystem |
+   | `Integration` | ecosystem |
+   | *(completion records)* | finalizations |
+   | *(no category / Note)* | ecosystem (default) |
+
+   If a `finalizations` vault is configured, completion-specific context (e.g., learnings tagged with `--workgroup` or about completed sessions) may be routed there.
+
+3. **Parse command arguments**
+   - Extract insight text from quotes
+   - Parse `--category` flag (default: auto-detect)
+   - Parse `--tags` flag (default: extract from content)
+   - Parse `--vault` flag (optional: explicit vault selection)
+   - Parse `--source` flag (optional: origin context like "code review", "incident", "meeting")
+   - Parse `--workgroup` flag (optional: explicit WorkGroup link for traceability)
+
+4. **Detect category (if not provided)**
+   - Scan insight for signal words:
+     ```
+     pattern: "pattern", "reusable", "utility", "helper"
+     decision: "chose", "decided", "opted", "because"
+     workaround: "workaround", "limitation", "instead"
+     performance: "optimized", "faster", "reduced", "cache"
+     security: "security", "vulnerability", "sanitize", "auth"
+     convention: "always", "never", "standard", "rule"
+     ```
+   - Default to "Note" if no clear category detected
+
+5. **Extract/validate tags**
+   - If `--tags` provided, use those
+   - Otherwise, extract key terms from insight
+   - Always include current project name
+   - Add active WorkGroup ID if applicable
+
+6. **Check for duplicates in selected vault**
+   ```bash
+   search_knowledge(
+     query: "{insight summary}",
+     vaultId: "{selected_vault_id}",
+     limit: 3
+   )
+   ```
+   - If similar exists (>80% match), warn user:
+     ```
+     ⚠️ Similar knowledge exists:
+     > "{existing title}"
+
+     Options:
+     [Create anyway] [Skip] [Update existing]
+     ```
+
+7. **Build learning content**
+   ```markdown
+   [CONTEXT]
+   Project: {project-name}
+   WorkGroup: {--workgroup value or active-workgroup-id or "Manual capture"}
+   Vault: {selected_vault_name}
+   Source: {--source value or "KnowzCode /kc:learn command"}
+   Date: {ISO timestamp}
+
+   [INSIGHT]
+   {User's insight text}
+
+   [SOURCE]
+   Captured via /kc:learn command
+   Origin: {--source value or "direct capture"}
+   ```
+
+8. **Create knowledge item in selected vault**
+   ```json
+   create_knowledge({
+     "content": "{formatted content}",
+     "title": "{Category}: {Brief summary from insight}",
+     "knowledgeType": "Note",
+     "vaultId": "{selected_vault_id}",
+     "tags": ["{category}", "{extracted-tags}", "{project-name}"],
+     "source": "KnowzCode /kc:learn"
+   })
+   ```
+
+9. **Report success with vault info**
+   ```
+   ✅ Learning captured!
+
+   Title: {Category}: {Brief summary}
+   Vault: {selected_vault_name} ({vault_id prefix...})
+   Tags: {tag list}
+
+   This knowledge is now available to all KnowzCode agents when querying this vault.
+   ```
+
+## Category Reference
+
+| Category | When to Use | Signal Words |
+|----------|-------------|--------------|
+| `Pattern:` | Reusable code pattern | pattern, reusable, utility, helper, abstraction |
+| `Decision:` | Architecture/design choice | chose, decided, opted, because, trade-off |
+| `Workaround:` | Limitation bypass | workaround, limitation, instead, temporary, bug |
+| `Performance:` | Optimization insight | faster, optimized, reduced, improved, cache |
+| `Security:` | Security consideration | security, vulnerability, sanitize, auth, encrypt |
+| `Convention:` | Team standard | always, never, standard, rule, convention |
+
+## Error Handling
+
+### MCP Not Connected (Most Common)
+```
+❌ Learning capture requires MCP connection
+
+The /kc:learn command needs the KnowzCode MCP server to store
+learnings in your organization's knowledge vault.
+
+To get started:
+
+  Recommended (easiest):
+    /kc:register
+    (Creates account + configures MCP + sets up vault - all automatic!)
+
+  Already have an API key?
+    /kc:connect-mcp <your-api-key>
+
+After setup, run /kc:learn again to capture your insight.
+```
+
+### Ecosystem Vault Not Configured
+```
+❌ Ecosystem vault not configured
+
+MCP is connected, but no vault is set up for learnings.
+
+Quickest fix:
+  /kc:register
+  (Creates account + auto-configures vault)
+
+Already have an account?
+  /kc:connect-mcp --configure-vaults
+  (Prompts for vault ID)
+
+After setup, run /kc:learn again.
+```
+
+### Project Not Initialized
+```
+❌ KnowzCode not initialized
+
+Run /kc:init first to set up this project, then:
+  /kc:register   (to enable learning capture)
+  /kc:learn "your insight"
+```
+
+### Empty Insight
+```
+❌ No insight provided
+
+Usage: /kc:learn "your insight here"
+
+Example:
+  /kc:learn "Always validate user input at API boundaries"
+```
+
+## Integration with Workflow
+
+### Automatic Capture (via closer)
+The `closer` agent automatically detects and offers to capture learnings during WorkGroup finalization. This is the recommended flow for workflow-related insights.
+
+### Manual Capture (via /kc:learn)
+Use this command for:
+- Ad-hoc insights discovered outside of WorkGroups
+- Documenting existing team knowledge
+- Capturing external learnings (from reviews, meetings, etc.)
+
+## Querying Captured Learnings
+
+After capturing, learnings are queryable by all agents:
+
+```bash
+# Resolve vault IDs from knowzcode/knowzcode_vaults.md first, then query by type:
+
+# By analyst
+search_knowledge("authentication patterns", {vault matching "ecosystem" type})
+
+# By architect
+ask_question("What are our error handling conventions?", {vault matching "ecosystem" type})
+
+# By builder
+search_knowledge("database connection best practices", {vault matching "ecosystem" type})
+```
+
+## Related Commands
+
+- `/kc:connect-mcp` - Configure MCP server and vaults
+- `/kc:status` - Check vault configuration
+- `/kc:work` - Start feature (uses captured learnings)
+- `/kc:audit` - Run audits (checks against documented patterns)
+
+Execute this learning capture now.