knowzcode 0.3.7 → 0.5.2

package/commands/init.md

@@ -124,6 +124,183 @@ When generating adapters, inject detected project info to make them project-spec
 
 3. For Codex: note that `AGENTS.override.md` can be used for user-local overrides
 
+**Step 7c-codex: Generate Codex skill files**
+
+When Codex is selected, generate skill files in addition to `AGENTS.md`:
+
+```
+1. Create .agents/skills/ directory
+2. Generate 12 skill files from platform_adapters.md "Codex Skill Files" section:
+   - .agents/skills/kc-work/SKILL.md
+   - .agents/skills/kc-plan/SKILL.md
+   - .agents/skills/kc-fix/SKILL.md
+   - .agents/skills/kc-audit/SKILL.md
+   - .agents/skills/kc-learn/SKILL.md
+   - .agents/skills/kc-continue/SKILL.md
+   - .agents/skills/kc-init/SKILL.md
+   - .agents/skills/kc-status/SKILL.md
+   - .agents/skills/kc-connect-mcp/SKILL.md
+   - .agents/skills/kc-register/SKILL.md
+   - .agents/skills/kc-telemetry/SKILL.md
+   - .agents/skills/kc-telemetry-setup/SKILL.md
+3. Replace "vX.Y.Z" with current KnowzCode version
+```
+
+**Codex success message:**
+```
+OpenAI Codex adapter generated:
+  AGENTS.md                                       (primary instructions)
+  .agents/skills/kc-work/SKILL.md                (/kc:work — start workflow)
+  .agents/skills/kc-plan/SKILL.md                (/kc:plan — research)
+  .agents/skills/kc-fix/SKILL.md                 (/kc:fix — quick fix)
+  .agents/skills/kc-audit/SKILL.md               (/kc:audit — quality audit)
+  .agents/skills/kc-learn/SKILL.md               (/kc:learn — capture learning)
+  .agents/skills/kc-continue/SKILL.md            (/kc:continue — resume workflow)
+  .agents/skills/kc-init/SKILL.md                (/kc:init — initialize project)
+  .agents/skills/kc-status/SKILL.md              (/kc:status — check status)
+  .agents/skills/kc-connect-mcp/SKILL.md         (/kc:connect-mcp — configure MCP)
+  .agents/skills/kc-register/SKILL.md            (/kc:register — register account)
+  .agents/skills/kc-telemetry/SKILL.md           (/kc:telemetry — investigate errors)
+  .agents/skills/kc-telemetry-setup/SKILL.md     (/kc:telemetry-setup — configure sources)
+
+Tip: Run `npx knowzcode install --platforms codex --global` to install
+skills globally to ~/.agents/skills/ (available in all projects).
+```
+
+**Step 7c-gemini-mcp: Offer MCP configuration for Gemini CLI**
+
+After generating GEMINI.md + commands + skills + subagents, run Smart Discovery first:
+1. Check `KNOWZ_API_KEY` environment variable
+2. Check `knowzcode/mcp_config.md` — if `Connected: Yes`, endpoint and key info available
+3. Check `.mcp.json` or `.vscode/mcp.json` for existing API key (extract Bearer token)
+
+If existing config found:
+  "Found existing MCP config (endpoint: {endpoint}, key ending ...{last4}).
+   Configure Gemini using this existing config? [Yes] [No, enter different key] [Skip]"
+  If Yes: write .gemini/settings.json using discovered config (no key prompt needed)
+
+If no existing config found, ask:
+```
+"Would you like to configure MCP for Gemini CLI? (Requires a KnowzCode API key)"
+```
+
+- If **"Yes, I have a key"**: Accept API key →
+  1. Write `.gemini/settings.json` (merge with existing if present):
+     ```json
+     {
+       "mcpServers": {
+         "knowz": {
+           "url": "https://mcp.knowz.io/mcp",
+           "headers": {
+             "Authorization": "Bearer <api-key>",
+             "X-Project-Path": "<project-path>"
+           }
+         }
+       }
+     }
+     ```
+  2. Verify by calling `list_vaults` if possible
+  3. Update `knowzcode/mcp_config.md` with connection status
+- If **"Yes, register first"**: Direct to `/kc:register`
+- If **"No"**: Skip, mention `/kc:connect-mcp` for later setup
+
+**Step 7c-gemini: Generate Gemini TOML commands, skills, and subagents**
+
+When Gemini is selected, generate TOML command files, skill files, and subagent definitions in addition to `GEMINI.md`:
+
+```
+1. Create .gemini/commands/kc/ directory
+2. Generate 12 TOML files from platform_adapters.md "Native Commands" section:
+   - .gemini/commands/kc/work.toml
+   - .gemini/commands/kc/plan.toml
+   - .gemini/commands/kc/fix.toml
+   - .gemini/commands/kc/audit.toml
+   - .gemini/commands/kc/learn.toml
+   - .gemini/commands/kc/status.toml
+   - .gemini/commands/kc/continue.toml
+   - .gemini/commands/kc/init.toml
+   - .gemini/commands/kc/connect-mcp.toml
+   - .gemini/commands/kc/register.toml
+   - .gemini/commands/kc/telemetry.toml
+   - .gemini/commands/kc/telemetry-setup.toml
+3. Create .gemini/skills/ directory
+4. Generate 12 skill files from platform_adapters.md "Gemini Skill Files" section:
+   - .gemini/skills/kc-work/SKILL.md
+   - .gemini/skills/kc-plan/SKILL.md
+   - .gemini/skills/kc-fix/SKILL.md
+   - .gemini/skills/kc-audit/SKILL.md
+   - .gemini/skills/kc-learn/SKILL.md
+   - .gemini/skills/kc-continue/SKILL.md
+   - .gemini/skills/kc-init/SKILL.md
+   - .gemini/skills/kc-status/SKILL.md
+   - .gemini/skills/kc-connect-mcp/SKILL.md
+   - .gemini/skills/kc-register/SKILL.md
+   - .gemini/skills/kc-telemetry/SKILL.md
+   - .gemini/skills/kc-telemetry-setup/SKILL.md
+5. Replace "vX.Y.Z" with current KnowzCode version
+```
+
+**Step 7c-gemini-agents: Generate Gemini subagent files (experimental, opt-in)**
+
+Ask user: "Would you like to generate Gemini subagent definitions? (experimental — requires `experimental.enableAgents: true` in Gemini settings.json)"
+
+If yes:
+```
+1. Create .gemini/agents/ directory
+2. Generate 14 subagent files from platform_adapters.md "Gemini Subagents" section:
+   - .gemini/agents/kc-analyst.md
+   - .gemini/agents/kc-architect.md
+   - .gemini/agents/kc-builder.md
+   - .gemini/agents/kc-reviewer.md
+   - .gemini/agents/kc-closer.md
+   - .gemini/agents/kc-context-scout.md
+   - .gemini/agents/kc-knowz-scout.md
+   - .gemini/agents/kc-knowz-scribe.md
+   - .gemini/agents/kc-microfix.md
+   - .gemini/agents/kc-knowledge-migrator.md
+   - .gemini/agents/kc-update-coordinator.md
+   - .gemini/agents/kc-security-officer.md
+   - .gemini/agents/kc-test-advisor.md
+   - .gemini/agents/kc-project-advisor.md
+3. Replace "vX.Y.Z" with current KnowzCode version
+```
+
+**Gemini success message:**
+```
+Gemini CLI adapter generated:
+  GEMINI.md                                       (primary instructions)
+  .gemini/commands/kc/work.toml                  (/kc:work — start workflow)
+  .gemini/commands/kc/plan.toml                  (/kc:plan — research)
+  .gemini/commands/kc/fix.toml                   (/kc:fix — quick fix)
+  .gemini/commands/kc/audit.toml                 (/kc:audit — quality audit)
+  .gemini/commands/kc/learn.toml                 (/kc:learn — capture learning)
+  .gemini/commands/kc/status.toml                (/kc:status — connection status)
+  .gemini/commands/kc/continue.toml              (/kc:continue — resume workflow)
+  .gemini/commands/kc/init.toml                  (/kc:init — initialize project)
+  .gemini/commands/kc/connect-mcp.toml           (/kc:connect-mcp — configure MCP)
+  .gemini/commands/kc/register.toml              (/kc:register — register account)
+  .gemini/commands/kc/telemetry.toml             (/kc:telemetry — investigate errors)
+  .gemini/commands/kc/telemetry-setup.toml       (/kc:telemetry-setup — configure sources)
+  .gemini/skills/kc-work/SKILL.md                (discoverable skill)
+  .gemini/skills/kc-plan/SKILL.md                (discoverable skill)
+  .gemini/skills/kc-fix/SKILL.md                 (discoverable skill)
+  .gemini/skills/kc-audit/SKILL.md               (discoverable skill)
+  .gemini/skills/kc-learn/SKILL.md               (discoverable skill)
+  .gemini/skills/kc-continue/SKILL.md            (discoverable skill)
+  .gemini/skills/kc-init/SKILL.md                (discoverable skill)
+  .gemini/skills/kc-status/SKILL.md              (discoverable skill)
+  .gemini/skills/kc-connect-mcp/SKILL.md         (discoverable skill)
+  .gemini/skills/kc-register/SKILL.md            (discoverable skill)
+  .gemini/skills/kc-telemetry/SKILL.md           (discoverable skill)
+  .gemini/skills/kc-telemetry-setup/SKILL.md     (discoverable skill)
+  .gemini/agents/kc-*.md (14 subagents)          (experimental — if opted in)
+
+MCP: [Configured (.gemini/settings.json) | Not configured — run /kc:connect-mcp later]
+
+Tip: Run `npx knowzcode install --platforms gemini --global` to install
+skills globally to ~/.gemini/skills/ (available in all projects).
+```
+
 **Step 7d: Validate generated adapters**
 
 After generation, verify each adapter:

package/commands/register.md

@@ -107,6 +107,29 @@ YOU                              USER
 
 ### Steps to Execute
 
+#### Step 0: Smart Discovery
+
+Before starting registration, check if user already has a KnowzCode API key:
+
+1. Check `KNOWZ_API_KEY` environment variable
+2. Check `knowzcode/mcp_config.md` — if `Connected: Yes`, existing config exists
+3. Check cross-platform configs: `.gemini/settings.json`, `.vscode/mcp.json`, `.mcp.json`
+   - Extract Bearer token from Authorization headers if found
+
+If existing API key found:
+```
+You already have a KnowzCode API key configured (ending ...{last4}) from {source}.
+
+Options:
+1. Use existing key — run /kc:connect-mcp to configure this platform
+2. Register a new account anyway
+3. Cancel
+```
+
+If user chooses option 1: advise running `/kc:connect-mcp` with discovered key.
+If user chooses option 2: proceed with registration normally (Step 1).
+If user chooses option 3: stop.
+
 #### Step 1: Check Existing Configuration
 
 1. Check if MCP server already configured:
@@ -363,6 +386,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
    - **Connected**: Yes
    - **Endpoint**: {endpoint}
    - **Last Verified**: {ISO timestamp}
+   - **API Key (last 4)**: {last 4 characters of the API key}
 
    ---
 

package/commands/status.md

@@ -40,12 +40,41 @@ Check Agent Teams status, then check the KnowzCode MCP server status, and report
    Note: Agent Teams availability is no longer checked via settings files. Commands (`/kc:work`, `/kc:plan`, `/kc:audit`) detect availability at runtime by attempting `TeamCreate()` and falling back gracefully. The `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var must still be set at the Claude Code level for Agent Teams to work, but commands do not check for it directly.
 
 2. **Check MCP server configuration**
-   ```bash
-   CLAUDECODE= claude mcp get knowz
-   ```
+
+   Detect the current platform and use the appropriate check:
+   - **Claude Code**: `CLAUDECODE= claude mcp get knowz`
+   - **Gemini CLI**: Read `.gemini/settings.json` for `mcpServers.knowz` entry, or run `gemini mcp list`
+   - **Copilot**: Read `.vscode/mcp.json` for knowz server entry
+   - **Codex**: Read `.mcp.json` for knowz server entry
+   - **Fallback**: Read `knowzcode/mcp_config.md` for connection status
 
    - If configured: Extract scope, endpoint, headers
-   - If not configured: Report and suggest `/kc:connect`
+   - If not configured: Report and suggest `/kc:connect-mcp`
+
+2.5. **Cross-Platform Config Discovery**
+
+   Check all known MCP config locations and report:
+
+   1. `KNOWZ_API_KEY` env var: Set (ending ...{last4}) | Not set
+   2. `knowzcode/mcp_config.md`: Connected / Not configured
+   3. Claude Code (`claude mcp get knowz`): Configured | Not found
+   4. Gemini (`.gemini/settings.json` → `mcpServers.knowz`): Configured | Not found
+   5. Copilot (`.vscode/mcp.json` → `servers.knowz`): Configured | Not found
+   6. Codex (`.mcp.json` → knowz): Configured | Not found
+
+   Include in output:
+   ```
+   Config Sources:
+     - Environment (KNOWZ_API_KEY): {status}
+     - Project config (mcp_config.md): {status}
+     - Claude Code: {status}
+     - Gemini CLI: {status}
+     - VS Code / Copilot: {status}
+     - Codex (.mcp.json): {status}
+   ```
+
+   If configs found on other platforms but not current:
+   "Tip: An API key was found in {source}. Run /kc:connect-mcp to configure for this platform."
 
 3. **Check vault configuration**
    - **Primary**: Read `knowzcode/knowzcode_vaults.md` for multi-vault routing
@@ -275,7 +304,7 @@ Status: https://status.knowz.io
 ### After configuration
 ```bash
 /kc:connect-mcp <api-key>
-# ... restart Claude Code ...
+# ... restart your AI coding assistant ...
 /kc:status  # Verify everything works
 ```
 
@@ -301,7 +330,7 @@ This command is useful:
 
 ## Important Notes
 
-- **Restart required**: After `/kc:connect-mcp`, Claude Code must restart
+- **Restart required**: After `/kc:connect-mcp`, restart your AI coding assistant (Claude Code, Gemini CLI, etc.)
 - **Graceful degradation**: KnowzCode works without MCP (just less powerful)
 - **No credentials shown**: Never display full API keys
 - **Clear guidance**: Always suggest next steps if issues found

package/commands/work.md

@@ -270,6 +270,7 @@ After builder completes successfully:
    ```
 4. Final commit: `git add knowzcode/ <changed files> && git commit -m "feat: {goal} (WorkGroup {wgid})"`
 5. Report completion.
+6. **Progress capture** (if MCP is configured): Read `knowzcode/knowzcode_vaults.md`, resolve vault IDs. Write a brief scope-and-outcome learning to the ecosystem vault via `create_knowledge`. Check for duplicates first via `search_knowledge`.
 
 **DONE** — 3 agents skipped (analyst, architect, reviewer, closer).
 
@@ -878,9 +879,9 @@ Approve this Change Set to proceed to specification?
 **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)
+### Lead Responsibility: Progress Capture
 
-If MCP is configured and knowz-scribe is active, after Change Set approval:
+**Lead responsibility.** After gate approval, the lead triggers progress capture. If knowz-scribe is active (Parallel Teams with vaults configured):
 - Create capture task: `TaskCreate("Scribe: Capture Phase 1A")` → `TaskUpdate(owner: "knowz-scribe")`
 - Send message to **knowz-scribe** with task ID: `"Capture Phase 1A: {wgid}. Your task: #{task-id}"` — 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
@@ -1012,9 +1013,9 @@ git commit -m "KnowzCode: Specs approved for {WorkGroupID}"
 
 When complete, present implementation summary including files changed, tests written, and test results.
 
-### MCP Learning Capture (Optional)
+### Lead Responsibility: Progress Capture
 
-If MCP is configured and knowz-scribe is active, after implementation completes:
+**Lead responsibility.** After gate approval, the lead triggers progress capture. If knowz-scribe is active (Parallel Teams with vaults configured):
 - Create capture task: `TaskCreate("Scribe: Capture Phase 2A")` → `TaskUpdate(owner: "knowz-scribe")`
 - Send message to **knowz-scribe** with task ID: `"Capture Phase 2A: {wgid}. Your task: #{task-id}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
 
@@ -1094,9 +1095,9 @@ If `AUTONOMOUS_MODE = false`: User decides — proceed / fix gaps / modify specs
 
 **Subagent mode**: Launch parallel `Task()` calls — one for gap fix (builder), then one for re-audit (reviewer). Repeat as needed.
 
-### MCP Learning Capture (Optional)
+### Lead Responsibility: Progress Capture
 
-If MCP is configured and knowz-scribe is active, after audit approval:
+**Lead responsibility.** After gate approval, the lead triggers progress capture. If knowz-scribe is active (Parallel Teams with vaults configured):
 - Create capture task: `TaskCreate("Scribe: Capture Phase 2B")` → `TaskUpdate(owner: "knowz-scribe")`
 - Send message to **knowz-scribe** with task ID: `"Capture Phase 2B: {wgid}. Your task: #{task-id}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
 
@@ -1134,6 +1135,7 @@ If MCP is configured and knowz-scribe is active, after audit 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.
 > **Vault writes**: No knowz-scribe — you own all vault writes. Follow the Direct Write Fallback in `agents/closer.md`.
+> **MCP Status**: {MCP_ACTIVE} — Vaults configured: {VAULTS_CONFIGURED}. Vault config: `knowzcode/knowzcode_vaults.md`.
 > **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, write learnings to vaults, and create final commit.
 
 **Dispatch**:

package/knowzcode/claude_code_execution.md

@@ -199,6 +199,7 @@ This section defines conventions specific to Parallel Teams mode in `/kc:work`.
 - 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
+- Lead owns progress documentation — at every quality gate, the lead creates scribe capture tasks and sends capture messages (e.g., "Capture Phase 1A: {wgid}"). No other agent initiates gate captures. If the scribe is unavailable, the lead ensures the closer is briefed to handle vault writes at Phase 3.
 
 ### Task Assignment Protocol
 
@@ -347,6 +348,16 @@ Specialists communicate directly with builders, architect, and each other — no
 
 ---
 
+## Lead Responsibilities (All Execution Modes)
+
+Regardless of execution mode (Parallel Teams, Sequential Teams, Subagent Delegation), the lead/outer orchestrator is responsible for:
+
+1. **Progress documentation via knowz-scribe**: At every quality gate, the lead triggers knowledge capture. In Parallel Teams, this means creating scribe capture tasks and sending DMs. In Sequential/Subagent modes where the scribe is not spawned, the lead passes MCP status and vault config to the closer's spawn prompt so Phase 3 captures are handled via Direct Write Fallback.
+2. **MCP status handoff**: The lead performs the MCP probe and communicates the result downstream — either by spawning vault agents (Parallel) or by including `MCP_ACTIVE` and `VAULTS_CONFIGURED` status in the closer's spawn prompt (Sequential/Subagent).
+3. **Capture completeness verification**: The lead confirms all gate captures completed before shutting down the scribe or proceeding to the next stage.
+
+---
+
 ## Teammate Initialization Protocol
 
 ### Agent Teams Mode (spawned as a teammate)

package/knowzcode/knowzcode_loop.md

@@ -279,6 +279,11 @@ Autonomous mode is per-WorkGroup and does not carry over.
 
 If KnowzCode MCP server is configured (`knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`), agents can leverage vault queries to enhance every phase.
 
+**Cross-platform config**: MCP configuration is stored in `knowzcode/mcp_config.md` and
+`knowzcode/knowzcode_vaults.md` — both platform-agnostic. If MCP was configured on one
+platform, other platforms detect and reuse the existing config. Set `KNOWZ_API_KEY` as an
+environment variable to enable automatic MCP authentication on any platform.
+
 **Before using MCP, read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type.** Use the vault's description to confirm the query is appropriate for that vault. If a single vault covers all types, use it for everything. Never hardcode vault names — always resolve from config.
 
 ### Vault Types
@@ -344,7 +349,7 @@ During finalization, scan the WorkGroup for insight-worthy patterns:
 
 ### Auto-Capture Triggers
 
-Learning candidates are detected at each quality gate. Capture is delegated to the knowz-scribe agent on multi-agent platforms, or handled directly via MCP tools on single-agent platforms.
+Learning candidates are detected at each quality gate. **The lead/outer orchestrator is responsible for triggering capture** — delegating to the knowz-scribe on multi-agent platforms, or ensuring the closer handles it via Direct Write Fallback on single-agent/sequential platforms.
 
 **Multi-agent platforms (knowz-scribe active):**
 

package/knowzcode/mcp_config.md

@@ -4,10 +4,15 @@
 - **Connected**: No
 - **Endpoint**: (not configured)
 - **Last Verified**: (never)
+- **API Key (last 4)**: (not configured)
 
 > **Not configured?** Run `/kc:register` to create an account and set up MCP automatically,
 > or `/kc:connect-mcp <api-key>` if you already have a key.
 
+> **Environment variable**: Set `KNOWZ_API_KEY` in your shell to enable automatic
+> MCP authentication on any platform without interactive prompts.
+> All `/kc:connect-mcp` and `/kc:register` commands check this variable first.
+
 ---
 
 ## Vaults