New Research: Supply Chain Attack on Axios Pulls Malicious Dependency from npm.Details →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

knowzcode

Package Overview
Dependencies
Maintainers
1
Versions
18
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

knowzcode - npm Package Compare versions

Comparing version
0.8.4
 to
0.9.0
+1
-1
.claude-plugin/plugin.json
{
"name": "knowzcode",
"description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
"version": "0.8.4",
"version": "0.9.0",
"keywords": ["tdd", "development-methodology", "quality-gates", "agents", "code-review"],

@@ -6,0 +6,0 @@ "author": {

+12
-3
agents/knowledge-liaison.md

@@ -17,3 +17,3 @@ ---

Own all context gathering (local + vault) and vault I/O routing throughout the workflow lifecycle. You are the single point of accountability for context delivery and vault I/O — no other agent dispatches `knowz:writer` or `knowz:reader` directly.
Own context gathering (local + vault) and vault I/O routing throughout the workflow lifecycle. The lead performs baseline vault reads directly (`search_knowledge`) before you are spawned — you coordinate deeper vault research beyond the baseline and all vault writes. No other agent dispatches `knowz:writer` or `knowz:reader` directly.

@@ -38,4 +38,13 @@ **You do NOT have MCP tools.** You delegate all vault I/O by dispatching `knowz:writer` (for writes) and `knowz:reader` (for queries).

2. **Dispatch vault readers** (if vaults configured) — do this IMMEDIATELY so queries run while you read local files.
Dispatch one `knowz:reader` per configured vault (same turn, parallel Task() calls):
2. **Dispatch vault readers for deep research** (if vaults configured) — do this IMMEDIATELY so queries run while you read local files.
**Check your spawn prompt for Lead Vault Baseline.** The lead runs baseline `search_knowledge` queries before spawning you.
**If VAULT_BASELINE is provided** — skip broad baseline queries. Dispatch targeted deep-dive queries based on baseline findings:
- `Task(subagent_type="knowz:reader", description="Deep reader: {vault-name} vault for {goal}")`:
> Vault ID: {id}. The lead already queried for broad context. Baseline results: {VAULT_BASELINE excerpt for this vault}.
> Go deeper: query for specific implementation details, edge cases, failure modes, and follow-up questions from the baseline. Focus on: {specific aspects that need expansion}.
- (One Task per configured vault — typically 2-3 vaults)
**If VAULT_BASELINE is NOT provided** (e.g., MCP was unavailable at probe time but recovered, or lead could not run baseline) — perform full baseline queries:
- `Task(subagent_type="knowz:reader", description="Reader: {vault-name} vault for {goal}")`:

@@ -42,0 +51,0 @@ > Vault ID: {id}. Query for: past decisions, conventions, implementation patterns, known workarounds related to {goal}.

+88
-13
knowzcode/knowzcode_vaults.md

@@ -7,2 +7,6 @@ # KnowzCode Vault Configuration

> **REQUIRED STRUCTURE — DO NOT REMOVE**
>
> Agents parse the fields below (`**Name**:`, `**ID**:`, `**Type**:`, `**Write Conditions**:`, `**Content Filter**:`) by exact format. Removing or restructuring these fields breaks automated knowledge capture at quality gates. Add supplementary guidance in separate sections below the structured fields — never replace them with prose.
## Connected Vaults

@@ -193,16 +197,24 @@

KnowzCode works with a single vault. If only one vault is configured (regardless of its declared type), all reads and writes route to it. This is the recommended starting point:
KnowzCode works with a single vault. If only one vault is configured (regardless of its declared type), all reads and writes route to it. This is the recommended starting point.
```
┌──────────────────────────────────────────────────────┐
│ KnowzCode Vault │
│ │
│ Purpose: All learnings, decisions, patterns, etc. │
│ Read by: knowz:reader, all agents │
│ Written by: knowz:writer, /knowz save │
│ Code search: Uses local grep/glob (no code vault) │
│ │
└──────────────────────────────────────────────────────┘
```
### Ready-to-Use Single Vault Entry
To use a single vault, replace the three default entries in "Connected Vaults" above with this single entry:
````markdown
### (not created)
- **Name**: Project Knowledge
- **ID**:
- **Type**: ecosystem
- **Description**: All project learnings — patterns, decisions, conventions, workarounds, security findings, integration details, and completion records. Single vault for all knowledge capture.
- **Write Conditions**:
- After Phase 1A: scope decisions, risk assessment
- After Phase 2A: implementation patterns, workarounds, performance insights
- After Phase 2B: security findings, quality decisions, audit results
- After Phase 3: all learnings — architectural discoveries, conventions, consolidation decisions, completion record
- **Content Filter**: Pattern:, Workaround:, Performance:, Decision:, Convention:, Security:, Integration:, Scope:, Completion:
````
> When using a single vault, the Write Routing table still applies for title prefixes and content formatting — agents use the `ecosystem` content filter (`[CONTEXT]/[INSIGHT]/[RATIONALE]/[TAGS]`) for all entries. The `finalizations` content filter (`[GOAL]/[OUTCOME]/[NODES]/[DURATION]/[SUMMARY]/[TAGS]`) is used only for completion records.
**Why start with one vault?**

@@ -236,4 +248,56 @@ - Simpler onboarding — no vault type decisions needed

> **Customization safety**: When adapting this file for your project:
> 1. Never remove `**Write Conditions**:` and `**Content Filter**:` fields — agents parse them by exact label
> 2. Never remove the Write Routing table — it maps learning categories to vault types
> 3. Add supplementary guidance in new sections below, not by replacing structured fields
> 4. For single-vault setups, use the ready-to-use entry in "Single Vault Model" above
---
## Supplementary Capture Guidance
> These sections enrich agent capture behavior. They are supplementary — the required structured fields above (`Write Conditions`, `Content Filter`, Write Routing table) must remain intact for automated captures to function.
### Minimum Capture Requirements
Agents MUST capture these categories at quality gates:
| Category | When | What |
|----------|------|------|
| Scope decisions | Phase 1A gate | What included/excluded, risk reasoning |
| Implementation patterns | Phase 2A | Patterns, workarounds, performance from TDD |
| Security & audit findings | Phase 2B gate | Vulnerabilities, audit gaps, remediation |
| Conventions established | Phase 3 | New conventions with rationale and examples |
| Architecture discoveries | Phase 3 | Structural insights, component relationships |
| Completion record | Phase 3 | Goal, outcome, NodeIDs, duration, learnings |
### Mid-Work Discovery Signals
Agents should watch for these during any phase and queue via knowledge-liaison (`"Consider: {description}"`):
| Signal | Examples |
|--------|----------|
| Corrected assumption | "It turns out...", unexpected behavior |
| Undocumented dependency | Hidden coupling, implicit ordering |
| Workaround applied | Limitation-driven alternatives |
| Configuration gotcha | Non-obvious defaults, env-specific settings |
| Performance finding | Before/after measurements |
| API quirk | Undocumented behavior, version differences |
When detected, capture immediately — do not defer to finalization. Sessions can end unexpectedly.
### Architecture Documentation Depth
When capturing architectural knowledge, include:
1. **Component relationships** — how modules interact, dependency direction, data flow
2. **Design rationale** — why this structure was chosen over alternatives
3. **Boundary definitions** — what belongs in each layer/module, what does not
4. **Integration contracts** — API surfaces, event schemas, shared data structures
5. **Error propagation** — how failures cascade, circuit breaker locations
6. **Configuration surface** — what is configurable, default values, environment differences
Each architectural entry should include file paths, code references, and enough context to be understood without access to the codebase.
---
## Integration with Agents

@@ -243,3 +307,4 @@

|-------|-------------------|---------|
| `knowledge-liaison` | Routes captures and queries to knowz agents | Single point of vault I/O coordination across all phases |
| `lead (skill)` | Direct `search_knowledge` calls | Baseline vault queries — guaranteed minimum vault context before agents spawn |
| `knowledge-liaison` | Routes captures and deep queries to knowz agents | Deeper vault research beyond the baseline and all vault write coordination |
| `knowz:reader` | Read all configured vaults | Find past decisions, conventions, patterns (dispatched by knowledge-liaison) |

@@ -255,2 +320,12 @@ | `knowz:writer` | Write to matching vaults | Route and capture learnings (dispatched by knowledge-liaison) |

### Two-Tier Vault Read Model
Vault reads use a two-tier model to ensure vault context is always available when MCP is connected:
1. **Baseline (lead-direct)**: The lead calls `search_knowledge` directly after the MCP probe, before any agents are spawned. One broad query per configured vault. This provides a guaranteed minimum of vault context for all execution modes — Agent Teams, Subagent Delegation, and Solo Mode.
2. **Deep research (knowledge-liaison)**: When agents are available, the knowledge-liaison dispatches `knowz:reader` subagents for targeted deep-dive queries that build on the baseline. The liaison receives the baseline results in its spawn prompt and focuses on areas the baseline didn't cover.
Vault **writes** remain single-tier — the knowledge-liaison coordinates all writes via `knowz:writer` dispatches.
---

@@ -257,0 +332,0 @@ 

+1
-1
package.json
{
"name": "knowzcode",
"version": "0.8.4",
"version": "0.9.0",
"description": "Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",

@@ -5,0 +5,0 @@ "type": "module",

+23
-1
README.md

@@ -9,3 +9,3 @@ # KnowzCode

[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowz-skills)
[![Version](https://img.shields.io/badge/version-0.8.4-blue)](https://github.com/knowz-io/knowz-skills/releases)
[![Version](https://img.shields.io/badge/version-0.9.0-blue)](https://github.com/knowz-io/knowz-skills/releases)

@@ -363,2 +363,24 @@ [Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)

## Enterprise Configuration
Enterprises that self-host the Knowz platform can customize endpoints and branding by creating an `enterprise.json` file in the plugin root:
```json
{
"brand": "Acme Corp",
"mcp_endpoint": "https://mcp.acme.internal/mcp",
"api_endpoint": "https://api.acme.internal/api/v1"
}
```
All fields are optional. When absent, the plugin defaults to the Knowz cloud platform (`knowz.io`). See `enterprise.example.json` for the template.
When `enterprise.json` is present:
- The CLI installer (`npx knowzcode`) uses the configured endpoints and skips the dev/prod environment selection
- Initialization and platform adapter generation use the configured values
- User-facing messages use the configured brand name
- The `--dev` flag is ignored (enterprise manages its own environments)
Enterprise forks should commit this file so it distributes to all team members via the marketplace.
## Contributing

@@ -365,0 +387,0 @@ 

+56
-7
skills/explore/SKILL.md

@@ -101,2 +101,4 @@ ---

If `MCP_AGENTS_ENABLED = false` (from Step 3.5, e.g. `--no-mcp`), skip the MCP Probe and Step 4.1 entirely. Set `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`, `VAULT_BASELINE = null`.
Before spawning agents, determine vault availability:

@@ -138,4 +140,24 @@ 1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)

> **Vault research is mandatory when available.** If `VAULTS_CONFIGURED = true` and `MCP_AGENTS_ENABLED = true`, the knowledge-liaison MUST dispatch vault reader subagents in both Exploration and Planning modes. Only skip vault queries when MCP is genuinely unavailable (`MCP_ACTIVE = false`).
> **Vault research is mandatory when available.** The lead performs baseline vault queries directly (Step 4.1) whenever `VAULTS_CONFIGURED = true` and `MCP_ACTIVE = true` — this is the guaranteed minimum. When agents are available, the knowledge-liaison performs deeper targeted queries beyond the baseline. Only skip all vault queries when MCP is genuinely unavailable (`MCP_ACTIVE = false`).
### Step 4.1: Baseline Vault Query (Lead-Direct)
If `VAULTS_CONFIGURED = true` AND `MCP_ACTIVE = true`, the lead performs baseline vault queries directly BEFORE spawning any agents. This ensures vault context is available regardless of agent availability.
1. Using vault configuration from the MCP Probe above (already loaded), resolve configured vault IDs and types.
2. For each configured vault, call `search_knowledge({vault_id}, "past decisions, conventions, patterns related to {topic}")`.
- For `finalizations`-type vaults: `search_knowledge({vault_id}, "past work related to {topic}")`.
- One broad query per vault — the goal is baseline coverage, not exhaustive research.
3. Store all results as `VAULT_BASELINE`:
```
VAULT_BASELINE:
- {vault_name} ({vault_type}): {summary of results, or "No relevant results found"}
```
4. **Failure handling**: If `search_knowledge` fails for a vault, log the failure and continue with remaining vaults. A partial baseline is better than none. If ALL queries fail, set `VAULT_BASELINE = "Vault queries failed — MCP may be degraded"` and continue.
5. Announce: `**Vault Baseline: {N} vault(s) queried — {M} results found**`
If `VAULTS_CONFIGURED = false` OR `MCP_ACTIVE = false`, set `VAULT_BASELINE = null` and skip this step.
> **This step is non-skippable when MCP is available.** It runs before agent spawning and does not depend on agent availability.
### Agent Teams Mode

@@ -158,3 +180,4 @@

> **Vault config**: `knowzcode/knowzcode_vaults.md`
> **Context gathering**: Read local context directly (specs, workgroups, tracker, architecture) using Read/Glob tools. Dispatch vault reader subagents in parallel for vault knowledge (past decisions, conventions, patterns).
> **Lead Vault Baseline**: {VAULT_BASELINE or "No baseline — MCP not available or no vaults configured"}
> **Context gathering**: Read local context directly (specs, workgroups, tracker, architecture) using Read/Glob tools. If baseline results are provided above, skip broad vault queries and dispatch deeper targeted research instead. If no baseline, perform full vault queries per your startup sequence.
> **Deliverable**: Push Context Briefing to analyst and architect with local + vault findings.

@@ -234,3 +257,3 @@

1. **knowledge-liaison** — Local context + vault knowledge:
- `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & vault research for {topic}", prompt="Read agents/knowledge-liaison.md for your full role definition. Goal: Research \"{topic}\" — gather local context and vault knowledge. Vault config: knowzcode/knowzcode_vaults.md. Read local context files directly (specs, workgroups, tracker, architecture) using Read and Glob tools. Dispatch vault reader subagents in parallel for vault knowledge (past decisions, conventions, patterns). Return consolidated Context Briefing with local + vault findings.")`
- `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & vault research for {topic}", prompt="Read agents/knowledge-liaison.md for your full role definition. Goal: Research \"{topic}\" — gather local context and vault knowledge. Vault config: knowzcode/knowzcode_vaults.md. Lead Vault Baseline: {VAULT_BASELINE or 'No baseline — MCP not available or no vaults configured'}. Read local context files directly (specs, workgroups, tracker, architecture) using Read and Glob tools. If baseline results are provided, skip broad vault queries and dispatch deeper targeted research instead. If no baseline, perform full vault queries per your startup sequence. Return consolidated Context Briefing with local + vault findings.")`

@@ -270,5 +293,29 @@ 2. **analyst** — Code exploration / Impact analysis:

### Solo Mode (No Agents Available)
If BOTH TeamCreate fails AND Task() is unavailable or fails, the lead performs all research directly:
1. Announce: `**Execution Mode: Solo** — Agent Teams and Subagent Delegation not available, lead performing research directly`
2. **Vault knowledge**: Already available from Step 4.1 (`VAULT_BASELINE`). If deeper vault queries are needed for specific aspects:
- Call `search_knowledge({vault_id}, "{specific_aspect_of_topic}")` for targeted follow-ups.
- Call `ask_question({vault_id}, "{question_about_topic}")` for synthesized answers.
3. **Local context** (lead reads directly):
- `Glob("knowzcode/specs/*.md")` — scan for related specs
- `Read("knowzcode/knowzcode_architecture.md")` — architecture context
- `Read("knowzcode/knowzcode_project.md")` — project standards
- `Glob("knowzcode/workgroups/*.md")` — prior WorkGroups
- `Read("knowzcode/knowzcode_tracker.md")` — active WIP, REFACTOR tasks
4. **Codebase exploration** (lead reads directly):
- Grep for topic-related keywords across source files
- Read top affected files to understand patterns and dependencies
- Check test coverage for the topic area
5. Proceed to Step 5 (Synthesis) with `VAULT_BASELINE` + local findings + codebase findings.
### Project Management Analysis (Planning Mode Only)
**After** spawning agents and **before** synthesizing findings, the lead performs project management research directly:
**After** spawning agents (or completing Solo Mode research) and **before** synthesizing findings, the lead performs project management research directly:

@@ -300,6 +347,7 @@ 1. Read `knowzcode/knowzcode_tracker.md` for WIP conflicts (overlapping NodeIDs/files)

### Existing Knowledge (from knowledge-liaison)
### Existing Knowledge
- **Relevant Specs**: {list or "None found"}
- **Prior WorkGroups**: {list or "None found"}
- **Vault Knowledge**: {list or "N/A — MCP not configured"}
- **Vault Knowledge (Baseline)**: {VAULT_BASELINE results or "N/A — MCP not configured"}
- **Vault Knowledge (Deep)**: {knowledge-liaison findings beyond baseline, or "N/A — agents not available" or "N/A — MCP not configured"}

@@ -348,3 +396,4 @@ ### Recommended Approaches

## Prior Knowledge (from vaults)
{relevant past decisions, conventions, patterns, prior failures}
**Baseline** (lead-direct): {VAULT_BASELINE results or "N/A — MCP not configured"}
**Deep research** (knowledge-liaison): {liaison findings beyond baseline, or "N/A — agents not available"}

@@ -351,0 +400,0 @@ ## Impact Analysis

+16
-0
skills/init/SKILL.md

@@ -12,2 +12,18 @@ ---

## Enterprise Configuration
Before using any endpoints or brand names in this skill, check for an `enterprise.json` file in the plugin root directory (the directory containing `.claude-plugin/plugin.json`). Read it once at the start of initialization.
If the file exists, use its values:
- `brand` → replaces "Knowz" in all user-facing messages and generated config
- `mcp_endpoint` → replaces `https://mcp.knowz.io/mcp` in all MCP commands and generated config (e.g., Gemini settings.json)
- `api_endpoint` → replaces `https://api.knowz.io/api/v1` in all API references
If the file is absent or a field is missing, use the defaults:
- brand: `Knowz`
- mcp_endpoint: `https://mcp.knowz.io/mcp`
- api_endpoint: `https://api.knowz.io/api/v1`
When `enterprise.json` is present, ignore the `--dev` flag for endpoint selection.
## What KnowzCode Provides

@@ -14,0 +30,0 @@ 

+9
-56
skills/work/references/parallel-orchestration.md

@@ -11,42 +11,3 @@ # Parallel Teams Orchestration — Work Skill (Tier 3)

2. Read knowzcode context files (lead does initial load for spawn prompts)
3. **MCP Probe** — determine vault availability BEFORE spawning:
a. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
b. Call `list_vaults(includeStats=true)` **always** — regardless of whether any IDs exist in the file
c. If `list_vaults()` fails:
- Check if `knowzcode/knowzcode_vaults.md` has any CONFIGURED entries (non-empty ID)
- **If CONFIGURED entries exist**: Set `MCP_ACTIVE = true`, `VAULTS_CONFIGURED = true` — vault agents will verify connectivity independently via their Startup Verification. Announce `**MCP Status: Lead probe failed — delegating verification to vault agents**`. Proceed to Step 4.
- **If no CONFIGURED entries** (all empty IDs or no file): Set `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`, announce `**MCP Status: Not connected**`. Knowledge-liaison still spawns (Group A, unconditional) but provides local context only.
d. 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. For each uncreated vault, derive the "Written During" column from its Write Conditions field in `knowzcode_vaults.md`. Example rows:
- `| Code Patterns | code | Learnings, gotchas, and architecture insights from the codebase | Phase 2A (implementation patterns), Phase 3 (workarounds, performance) |`
- `| Ecosystem Knowledge | ecosystem | Business rules, conventions, decisions, and cross-system details | Phase 1A (scope decisions), Phase 2B (security, quality), Phase 3 (conventions) |`
- `| Finalizations | finalizations | Final summaries documenting complete execution and outcomes | Phase 3 (completion record) |`
Then present options:
```
Options:
**A) Create all {N} vaults** (recommended)
**B) Select which to create**
**C) Skip** — proceed without vaults (can create later with `/knowz setup`)
```
e. 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 the ID field with the server-returned vault ID and change the H3 heading from `(not created)` to the vault ID. If creation fails for some vaults, update only successful ones, report failures, and let user decide.
- **B**: Ask which vaults to create, then create only selected ones using the same process as A.
- **C**: Log `"Vault creation skipped — knowledge capture disabled."` Continue.
f. 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)**`
3. **MCP & Vault Baseline** — use `MCP_ACTIVE`, `VAULTS_CONFIGURED`, and `VAULT_BASELINE` from Step 3.6 in `work/SKILL.md`. The lead has already completed the MCP probe, vault creation, and baseline vault queries before reaching Stage 0. Do NOT re-run the MCP probe or baseline queries here.
4. **Spawn Group A**:

@@ -66,4 +27,4 @@ Create tasks first, pre-assign, then spawn with task IDs:

Spawn all Group A agents with their `{task-id}` in the spawn prompt (use spawn prompts from [spawn-prompts.md](spawn-prompts.md)).
The knowledge-liaison reads local context directly and dispatches vault reader subagents in parallel — no separate scout agents needed.
5. **Vault status note**: The knowledge-liaison handles vault availability internally. If `VAULTS_CONFIGURED = true`, it dispatches `knowz:reader` for vault research. If `VAULTS_CONFIGURED = false`, it still provides local context (direct reads only). No separate Group B spawn needed.
The knowledge-liaison reads local context directly and dispatches vault reader subagents for deeper targeted research (building on the lead's `VAULT_BASELINE`) — no separate scout agents needed.
5. **Vault status note**: The lead has already performed baseline vault queries (`VAULT_BASELINE`). The knowledge-liaison performs deeper targeted research beyond the baseline. If `VAULTS_CONFIGURED = true`, it dispatches `knowz:reader` for deep-dive queries. If `VAULTS_CONFIGURED = false`, it still provides local context (direct reads only). No separate Group B spawn needed.
6. **Spawn Group C** (specialist agents — same turn as Group A): If `SPECIALISTS_ENABLED` is non-empty:

@@ -300,16 +261,8 @@ Create tasks first, pre-assign, then spawn with task IDs:

### MCP Probe (Sequential/Subagent)
### MCP & Vault Baseline (Sequential/Subagent)
Determine vault availability before Phase 1A:
Use `MCP_ACTIVE`, `VAULTS_CONFIGURED`, and `VAULT_BASELINE` from Step 3.6 in `work/SKILL.md`. The lead has already completed the MCP probe, vault creation, and baseline vault queries before reaching this point. Do NOT re-run the MCP probe or baseline queries here.
1. Read `knowzcode/knowzcode_vaults.md` — check for CONFIGURED entries (non-empty ID)
2. Attempt `list_vaults(includeStats=true)`
3. If succeeds AND UNCREATED entries exist → present the **Vault Creation Prompt** (same as Parallel Teams Step 3d). Handle selection identically.
4. After resolution, announce MCP status to the user:
- `list_vaults()` succeeded: `**MCP Status: Connected — N vault(s) available**`
- `list_vaults()` failed but configured vaults exist: `**MCP Status: Lead probe failed — closer will verify at Phase 3**`
- No configured vaults: `**MCP Status: Not configured**`
The closer agent independently verifies MCP at Phase 3 regardless of the lead's probe result (see `agents/closer.md` — Startup MCP Verification).
The closer agent independently verifies MCP at Phase 3 regardless of this result (see `agents/closer.md` — Startup MCP Verification). This probe is for the user announcement and vault creation opportunity only.
### Pre-Phase: Context & Knowledge Research (Sequential/Subagent)

@@ -319,5 +272,5 @@

1. Dispatch knowledge-liaison:
- *Sequential Teams*: Spawn as first teammate. Create task `"Context & knowledge: research for {goal}"`. Wait for completion.
- *Subagent*: `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & knowledge research", prompt=<liaison spawn prompt from spawn-prompts.md>)`.
1. Dispatch knowledge-liaison (include `VAULT_BASELINE` in spawn/dispatch prompt):
- *Sequential Teams*: Spawn as first teammate. Create task `"Context & knowledge: research for {goal}"`. Wait for completion. Include `VAULT_BASELINE` in the spawn prompt.
- *Subagent*: `Task(subagent_type="knowzcode:knowledge-liaison", description="Context & knowledge research", prompt=<liaison spawn prompt from spawn-prompts.md, with VAULT_BASELINE included>)`.
2. Collect findings from the knowledge-liaison's task summary.

@@ -324,0 +277,0 @@ 3. Inject into the analyst spawn prompt as: `> **Context Briefing**: {liaison findings}`.

+2
-1
skills/work/references/spawn-prompts.md

@@ -62,4 +62,5 @@ # Agent Spawn Prompts — Work Skill

> **Vault config**: `knowzcode/knowzcode_vaults.md`
> **Lead Vault Baseline**: {VAULT_BASELINE or "No baseline — MCP not available or no vaults configured"}
> **Lifecycle**: You persist from Stage 0 through team shutdown. You are the last agent shut down before team cleanup.
> **Context gathering**: At startup, read local context directly and dispatch vault reader subagents in parallel (see `agents/knowledge-liaison.md` Startup). Push Context Briefing to analyst and architect.
> **Context gathering**: At startup, read local context directly and dispatch vault reader subagents in parallel (see `agents/knowledge-liaison.md` Startup). If baseline results are provided above, skip broad vault queries and dispatch deeper targeted research instead. If no baseline, perform full vault queries per your startup sequence. Push Context Briefing to analyst and architect.
> **Ongoing**: Accept capture DMs from the lead (at quality gates) and closer (Phase 3). Accept `"Log: ..."` and `"Consider: ..."` from any agent. Accept `"VaultQuery: ..."` from any agent. Dispatch `knowz:writer` and `knowz:reader` as needed.

@@ -66,0 +67,0 @@ 

+72
-6
skills/work/SKILL.md

@@ -166,2 +166,67 @@ ---

## Step 3.6: MCP Probe + Baseline Vault Query (Non-Skippable)
If `MCP_AGENTS_ENABLED = false` (from Step 2.4, e.g. `--no-mcp`), skip this entire step. Set `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`, `VAULT_BASELINE = null`.
Otherwise:
### MCP Probe
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:
- Check if `knowzcode/knowzcode_vaults.md` has any CONFIGURED entries (non-empty ID).
- **If CONFIGURED entries exist**: Set `MCP_ACTIVE = true`, `VAULTS_CONFIGURED = true`. Announce: `**MCP Status: Lead probe failed — vault agents will verify independently**`
- **If no CONFIGURED entries**: Set `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`. Announce: `**MCP Status: Not connected**`
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 `/knowz setup`)
```
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.
- If BOTH `create_vault()` and name-matching fail: log failure, set `VAULTS_CONFIGURED = false`, continue. Report: `"Vault creation failed — proceeding without knowledge capture. Run /knowz setup to retry."`
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)**`
### Baseline Vault Query
If `VAULTS_CONFIGURED = true` AND `MCP_ACTIVE = true`:
1. For each configured vault, call `search_knowledge({vault_id}, "past decisions, patterns, conventions related to {goal}")`.
- For `finalizations`-type vaults: `search_knowledge({vault_id}, "past work related to {goal}")`.
- One broad query per vault — the goal is baseline coverage, not exhaustive research.
2. Store all results as `VAULT_BASELINE`:
```
VAULT_BASELINE:
- {vault_name} ({vault_type}): {summary of results, or "No relevant results found"}
```
3. **Failure handling**: If `search_knowledge` fails for a vault, log failure and continue with remaining vaults. If ALL queries fail, set `VAULT_BASELINE = "Vault queries failed — MCP may be degraded"` and continue.
4. Announce: `**Vault Baseline: {N} vault(s) queried — {M} results found**`
If `VAULTS_CONFIGURED = false` OR `MCP_ACTIVE = false`, set `VAULT_BASELINE = null` and skip the baseline query.
> **This step runs for ALL tiers (2 and 3) when MCP is available.** It does not depend on agent availability. The baseline provides guaranteed vault context before any phase work begins.
## Step 4: Create WorkGroup File

@@ -242,5 +307,6 @@

1. Quick impact scan: grep for related files, check existing specs
2. Propose a Change Set (typically 1 NodeID)
3. Draft a lightweight spec (or reference existing spec if found) — use the 4-section format from `knowzcode_loop.md` section 3.2. Minimum: 1 Rule, 1 Interface, 2 `VERIFY:` statements.
4. Present combined Change Set + Spec for approval:
2. **Vault context**: Reference `VAULT_BASELINE` from Step 3.6 (already available). If baseline results are relevant to the affected component, factor them into the Change Set. If deeper component-specific queries are needed, call `search_knowledge({vault_id}, "past decisions about {affected_component}")` for targeted follow-up.
3. Propose a Change Set (typically 1 NodeID)
4. Draft a lightweight spec (or reference existing spec if found) — use the 4-section format from `knowzcode_loop.md` section 3.2. Minimum: 1 Rule, 1 Interface, 2 `VERIFY:` statements.
5. Present combined Change Set + Spec for approval:

@@ -263,3 +329,3 @@ ```markdown

5. **Autonomous Mode**: If `AUTONOMOUS_MODE = true`, log `[AUTO-APPROVED] Light mode gate` and proceed directly to implementation.
6. **Autonomous Mode**: If `AUTONOMOUS_MODE = true`, log `[AUTO-APPROVED] Light mode gate` and proceed directly to implementation.
If `AUTONOMOUS_MODE = false`: If rejected — adjust based on feedback and re-present. If approved:

@@ -293,3 +359,3 @@ - Update `knowzcode_tracker.md` with NodeID status `[WIP]`

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`.
6. **Progress capture** (if MCP is configured): Read `knowzcode/knowzcode_vaults.md`, resolve vault IDs. Check for existing entry via `search_by_title_pattern("WorkGroup: {wgid}*")` — update if found, create if not. Then write a WorkGroup completion record to the vault via `create_knowledge` (or `update_knowledge` if entry exists). Also check for duplicates via `search_knowledge` before creating.

@@ -335,3 +401,3 @@ **DONE** — 3 agents skipped (analyst, architect, reviewer, closer).

- **Stage 0**: Create team, MCP probe, spawn knowledge-liaison/analyst/architect/scanner/specialist agents in parallel
- **Stage 0**: Create team, use MCP/vault baseline from Step 3.6, spawn knowledge-liaison/analyst/architect/scanner/specialist agents in parallel
- **Stage 1**: Analyst completes Change Set → Gate #1 → Architect drafts specs → Gate #2

@@ -338,0 +404,0 @@ - **Stage 2**: Parallel builders (1 per independent partition) + paired reviewers + gap loop

bin/knowzcode.mjs

Sorry, the diff of this file is too big to display

knowzcode/platform_adapters.md

Sorry, the diff of this file is too big to display