knowzcode 0.1.0

package/commands/learn.md

@@ -0,0 +1,308 @@
+---
+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.

package/commands/plan.md

@@ -0,0 +1,125 @@
+---
+description: "Research and investigate before implementing"
+argument-hint: "<topic or question>"
+---
+
+# KnowzCode Plan
+
+Research a topic, feature, or question using parallel investigation before committing to implementation.
+
+**Usage**: `/kc:plan <topic or question>`
+
+**Examples**:
+```
+/kc:plan "is the API using proper error handling?"
+/kc:plan "add user authentication with JWT"
+/kc:plan "how does caching work in this codebase?"
+```
+
+---
+
+## Step 1: Validate Input
+
+If no argument provided, ask: "What would you like me to research?"
+
+## Step 2: Check Initialization
+
+If `knowzcode/` doesn't exist, inform user to run `/kc:init` first. STOP.
+
+## Step 3: Launch Parallel Investigation
+
+### Agent Teams Mode (if available)
+
+Spawn three teammates to investigate simultaneously:
+
+1. Spawn `analyst` teammate:
+   > 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:
+   > 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:
+   > 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
+
+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
+## Investigation: {topic}
+
+### Code Analysis
+{summarized findings from analyst}
+
+### Architecture Assessment
+{summarized findings from architect}
+
+### Security & Quality
+{summarized findings from reviewer}
+
+### Existing Knowledge
+- **Relevant Specs**: {list or "None found"}
+- **Prior WorkGroups**: {list or "None found"}
+
+### Recommended Approaches
+
+**Option 1**: {approach}
+- Pros: ...
+- Cons: ...
+
+**Option 2**: {approach}
+- Pros: ...
+- Cons: ...
+
+### Risks & Considerations
+{synthesized risks}
+
+---
+
+**Ready to implement?** Say "implement", "do option 1", or "go ahead" to start `/kc:work` with this context.
+```
+
+## Step 6: Listen for Implementation Intent
+
+Watch for: "implement", "do it", "go ahead", "option N", "start work", "build this"
+
+When triggered, invoke `/kc:work "{original_topic}"` with investigation context.
+
+---
+
+## Notes
+
+- Research agents use focused, efficient scoping (max 10 tool calls each)
+- Investigation context is preserved when transitioning to `/kc:work`
+- This replaces the old planning types (strategy, ideas, pre-flight, etc.)