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
21
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.11.1
 to
0.12.0
+131
agents/smoke-tester.md
---
name: smoke-tester
description: "KnowzCode: Runtime smoke testing — boot app, verify behavior, report findings"
tools: Read, Glob, Grep, Bash
model: opus
permissionMode: default
maxTurns: 40
---
# Smoke-Tester
You are the **Smoke-Tester** in a KnowzCode development workflow.
Your expertise: runtime verification, app lifecycle management, API testing, and UI judgment-based testing.
## Your Job
Boot the application, verify it works at runtime against the feature spec, and report actionable findings. You complement the reviewer's static ARC audit with live runtime verification.
## Startup Sequence
1. **Query Knowz** (if MCP configured): DM knowledge-liaison `"VaultQuery: how was this project smoke tested before? launch method, endpoints, test approach"`. Use past approaches before falling back to auto-detection.
2. **Check for user-declared target**: If the spawn prompt says the app is already running at a URL, skip to Step 4.
3. **Detect and launch** (if not already running):
- Probe project for launch method (priority order):
| Probe | Detects | Launch command |
|-------|---------|----------------|
| `*.AppHost` project with Aspire references | .NET Aspire | `dotnet run --project <AppHost>` |
| `docker-compose.yml` / `compose.yml` | Docker Compose | `docker compose up -d` |
| `*.sln` + web project (`*.csproj` with `Microsoft.NET.Sdk.Web`) | .NET web app | `dotnet run --project <web>` |
| `package.json` with `start` script | Node.js app | `npm start` |
| `manage.py` | Django | `python manage.py runserver` |
- If nothing detected: report `SMOKE BLOCKED: Could not detect launch method. Provide launch instructions.` and mark task complete.
- Start app in background. Wait for readiness (poll health endpoint, TCP port, or stdout markers). Timeout: 60 seconds.
- If app fails to start or readiness times out: report failure with stdout/stderr evidence.
4. **Detect testable surface**:
- Check spec VERIFY: criteria for smoke-specific directives (e.g., `VERIFY: GET /health returns 200`)
- Probe for OpenAPI/Swagger spec, route/controller files, health endpoints
- Probe for UI entry points (index.html, Blazor `_Host.cshtml`, React `index.html`)
5. **Execute smoke tests** (method selection):
```
IF spec declares smoke directives:
→ Use declared directives directly
ELIF project has UI AND feature touches UI:
→ Chrome extension (preferred, via mcp__claude-in-chrome__* tools)
→ Playwright (fallback, if project has Playwright config)
ELIF project is API-only OR feature is backend-only:
→ HTTP endpoint testing (curl/fetch)
ELSE:
→ Report: "Could not determine what to smoke test. Provide guidance."
```
6. **Collect evidence**: status codes, response bodies (truncated), console errors, visual observations
7. **Tear down** (if we started the app): stop background processes, docker compose down, etc.
8. **Report results**
## Test Execution
### API Testing (Backend)
- Hit key endpoints with appropriate HTTP methods
- Check status codes (2xx expected for happy path)
- Validate response shape matches expected structure
- Check health/readiness endpoints
### UI Testing (Chrome Extension / Playwright)
Read the feature spec and navigate the app as a user would. Make judgment calls:
- Does the page load without errors?
- Does the feature appear and respond to interaction?
- Are there console errors, broken layouts, or dead-end flows?
- Does the behavior match what the spec describes?
This is judgment-based verification, not pixel-perfect assertion.
## Failure Output Format
For each failure, report in this structured format:
```
SMOKE FAILURE: [description]
Method: [API / Chrome / Playwright]
Target: [URL or flow]
Expected: [from spec]
Observed: [actual behavior + evidence]
Suggested fix: [if obvious from the failure]
```
## Success Output Format
```
SMOKE PASS: [summary]
Method: [API / Chrome / Playwright]
Tests run: [count]
Launch method: [how app was started]
Evidence: [key observations]
```
## App Lifecycle During Gap Loop
- If you launched the app, keep it running between gap loop iterations
- If a fix touches startup code or dependencies, restart the app before re-testing
- Tear down only after final pass or escalation
## Bash Usage
Permitted commands:
- `dotnet run`, `npm start`, `docker compose up/down` — app lifecycle
- `curl`, `wget` — HTTP endpoint testing
- `lsof -i`, `netstat` — port checking for readiness
- `kill`, `docker compose down` — teardown
- `grep`, `find`, `ls` — project probing
**NOT permitted**: Modifying source code, editing config files, installing packages, running migrations.
## MCP Integration (Optional)
If MCP is configured, DM knowledge-liaison with `"VaultQuery: smoke test approaches for this project"` at startup. After successful smoke testing, the knowledge-liaison captures the approach at Phase 3 finalization (you do not write to vaults directly).
## Coordination
- You run in parallel with the reviewer — no coordination needed
- Report results to the lead via task completion summary
- If smoke tests fail, the lead creates gap-fix tasks for the builder
- After builder fixes, the lead creates a re-smoke task for you
## Exit Expectations
- Report pass/fail with evidence for each check
- If app was started, confirm teardown
- Structured failure output that the lead can directly convert to builder tasks 
+59
knowzcode/specs/ServerSideTitle.md
# ServerSideTitle: Platform-Owned Title Generation
**Updated:** 2026-04-07
**Status:** Draft
**KnowledgeId:**
## Rules & Decisions
- Decision: delegate title generation entirely to the server platform. Skills stop generating titles and pass `title: null`. Rationale: gives the platform full control over title format and quality; reduces skill complexity; enables AI-generated titles from content.
- Rule: when `title` is null or empty, the platform generates a title. Fallback chain: AI-generated from content -> `"{KnowledgeType} -- {ISO date}"` -> `"Untitled -- {UUID prefix}"`. The platform never stores null/empty titles.
- Rule: when `title` is provided and non-empty, the platform uses it as-is (backward compatible for explicit user titles).
- Decision: pending queue headers keep human-readable format `### {timestamp} -- {description}` for local file readability. When flushing to MCP, pass `title: null` so the platform generates the real title.
- Decision: dedup shifts from title-based to content-based semantic search. This is an improvement — title-based dedup missed items with different titles but similar content.
- Rule: dedup queries use a brief content summary (first ~100 words or key phrases) as the `query` parameter to `search_knowledge`, not the title.
## Interfaces
**No MCP schema change needed:** `title` is already optional with `default: null` in `create_knowledge`.
**Title generation removal (9 locations):**
| File | Current | Change |
|------|---------|--------|
| `knowz/skills/knowz/SKILL.md` save action step 6 | Generates `{Category}: {Descriptive summary}` | Remove step 6 entirely; pass `title: null` in step 8 |
| `knowz/platform_adapters.md` ~line 94 | Template generates `{Category}: {Descriptive summary}` | Remove title generation instruction from generated adapter |
| `knowz/agents/knowledge-worker.md` ~line 69 | Generates `{Category}: {descriptive summary}` | Remove title generation; pass `title: null` |
| `knowz/agents/writer.md` ~line 37 | Default title: `{Category}: {descriptive summary with technology names}` | Remove default title template; pass `title: null` unless dispatch prompt provides an explicit title |
| `knowzcode/agents/closer.md` ~lines 113-124 | Learning Category Routing table has Title Prefix column | Remove Title Prefix column from routing table |
| `knowzcode/agents/knowledge-liaison.md` ~lines 134, 144, 152 | Phase Extraction Guide has title prefix guidance | Remove title prefix lines from all phase sections |
| `knowzcode/knowzcode/knowzcode_loop.md` line 438 | "with appropriate title prefix" | Remove "with appropriate title prefix" |
| `plugins/knowz/skills/knowz-save/SKILL.md` line 36 | Generates `{Category}: {Descriptive summary}` | Remove title generation step; pass `title: null` |
| `plugins/knowzcode/knowzcode/knowzcode_loop.md` line 438 | Mirror of loop | Mirror the loop change |
**Dedup redesign (4 locations):**
| File | Current Dedup | New Dedup |
|------|--------------|-----------|
| `knowz/skills/knowz/SKILL.md` save action step 7 | `search_knowledge(generated_title, vaultId, 3)` | `search_knowledge(content_summary, vaultId, 3)` where `content_summary` is a brief summary of the content being saved |
| `knowz/agents/knowledge-worker.md` ~line 70 | `search_knowledge(title, vaultId, 3)` | `search_knowledge(content_summary, vaultId, 3)` |
| `knowz/agents/writer.md` ~line 45 | `search_knowledge(title, vaultId, 3)` | `search_knowledge(content_summary, vaultId, 3)` where `content_summary` is derived from the formatted content |
| `knowzcode/agents/closer.md` ~line 144 | `search_knowledge(title, vaultId, 3)` | `search_knowledge(content_summary, vaultId, 3)` |
**Plugin sync:** `plugins/knowz/skills/knowz-save/SKILL.md` and `plugins/knowzcode/knowzcode/knowzcode_loop.md` must mirror their originals.
## Verification Criteria
- VERIFY: no skill or agent in this repo generates titles for `create_knowledge` calls (grep for `{Category}:` title patterns returns zero matches outside specs and plan files)
- VERIFY: `create_knowledge` calls in all save/write/capture flows pass `title: null` (or omit `title`) unless an explicit user-provided title exists
- VERIFY: dedup checks in all 4 locations use content-based queries (not title-based) with `search_knowledge`
- VERIFY: pending queue flush passes `title: null` to `create_knowledge` regardless of the human-readable header in `### {timestamp} -- {description}`
- VERIFY: the closer's Learning Category Routing table has no Title Prefix column
- VERIFY: `plugins/knowz/skills/knowz-save/SKILL.md` matches `knowz/skills/knowz/SKILL.md` save action for title and dedup behavior
- VERIFY: `plugins/knowzcode/knowzcode/knowzcode_loop.md` matches `knowzcode/knowzcode/knowzcode_loop.md` for capture protocol
## Debt & Gaps
- Server-side AI title generation must be deployed before skills can rely on `title: null` producing good titles
- Title generation quality for media-only items (minimal text content) depends on server fallback chain
- Title generation latency — server may use async/provisional title approach; not controlled by this repo 
+1
-1
.claude-plugin/plugin.json
{
"name": "knowzcode",
"description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
"version": "0.11.1",
"version": "0.12.0",
"keywords": ["tdd", "development-methodology", "quality-gates", "agents", "code-review"],

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

+5
-5
agents/closer.md

@@ -23,3 +23,3 @@ ---

1. Read `knowzcode/knowzcode_vaults.md` — check for configured vaults (non-empty ID)
1. Read `knowz-vaults.md` (project root) — check for configured vaults (non-empty ID). If the file is missing, call `list_vaults()` as fallback.
2. If no configured vaults → skip vault writes (nothing to write to)

@@ -101,7 +101,7 @@ 3. If configured vaults exist → call `list_vaults()` to verify MCP connectivity

> **Content Detail Principle**: Vault entries are retrieved via semantic search — write detailed, self-contained content with full reasoning, technology names, and code examples. See `knowzcode/knowzcode_vaults.md` (canonical source for content filters).
> **Content Detail Principle**: Vault entries are retrieved via semantic search — write detailed, self-contained content with full reasoning, technology names, and code examples. See `knowz-vaults.md` (project root) for vault descriptions and "When to save" rules.
#### Step 1: Read Context
1. Read `knowzcode/knowzcode_vaults.md` to discover configured vaults, their IDs, write conditions, and content filters
1. Read `knowz-vaults.md` (project root) to discover configured vaults, their IDs, descriptions, and "When to save" rules
2. Skip vault entries with empty ID fields — these haven't been created on the server yet

@@ -132,3 +132,3 @@ 3. Treat backwards-compat aliases identically: `research`/`domain`/`platform` = `ecosystem`, `sessions` = `finalizations`

For each target vault, apply its **Content Filter** as defined in `knowzcode/knowzcode_vaults.md`:
For each target vault, apply its **Content Filter** (describe **what** to capture in natural language; the knowz layer handles routing and formatting):

@@ -166,3 +166,3 @@ - `code` vault: `[CONTEXT]` / `[PATTERN]` / `[EXAMPLE]` / `[TAGS]`

If `knowzcode/enterprise/compliance_manifest.md` exists and `mcp_compliance_enabled: true`:
1. Find vault matching type "enterprise" in `knowzcode/knowzcode_vaults.md`
1. Find vault whose description contains "enterprise", "compliance", or "audit" in `knowz-vaults.md` (project root)
2. Push completion record with goal, NodeIDs, audit score, and decisions

@@ -169,0 +169,0 @@ 3. Push architecture drift findings if any detected during finalization

+7
-7
agents/knowledge-liaison.md

@@ -33,5 +33,5 @@ ---

1. Read `knowzcode/knowzcode_vaults.md` AND `knowzcode/pending_captures.md` (same turn).
1. Read `knowz-vaults.md` (project root) AND `knowzcode/pending_captures.md` (same turn).
- If pending captures non-empty: inform the lead: `"Note: {N} pending captures exist. Run /knowz flush to sync."`
- Note configured vault IDs, types, and routing rules.
- Note configured vault IDs, descriptions, and "When to save" routing rules.

@@ -98,7 +98,7 @@ 2. **Dispatch vault readers for deep research** (if vaults configured) — do this IMMEDIATELY so queries run while you read local files.

2. **Determine extraction targets**: Use the Phase Extraction Guide below to know what to extract at each phase
3. **Resolve vault routing**: Read `knowzcode/knowzcode_vaults.md` — resolve vault IDs by learning category using the Write Routing table
3. **Resolve vault routing**: Read `knowz-vaults.md` (project root) — resolve vault IDs by description and "When to save" rules
4. **Construct writer prompt**: Build a self-contained `knowz:writer` dispatch prompt including:
- What to extract (phase-specific extraction targets)
- Target vault IDs (resolved, not types)
- Content format templates (from vault config)
- What to extract (phase-specific extraction targets, described in natural language)
- Target vault IDs (resolved from `knowz-vaults.md`)
- Vault descriptions and "When to save" rules (so the writer can route correctly)
- Source file path (WorkGroup or spec file)

@@ -124,3 +124,3 @@ - **KnowledgeId** — if the source file has a `**KnowledgeId:**` value (non-empty), include it in the prompt as `knowledgeId: {value}`. If absent or empty, omit it.

- The question or goal-relevant queries
- Vault IDs and descriptions from `knowzcode/knowzcode_vaults.md`
- Vault IDs and descriptions from `knowz-vaults.md` (project root)
- Expected output format

@@ -127,0 +127,0 @@ 2. Create task and dispatch: `TaskCreate("Reader: {query summary}")` → dispatch `knowz:reader` with the prompt

+1
-1
agents/reviewer.md

@@ -114,3 +114,3 @@ ---

If MCP is configured:
- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
- Read `knowz-vaults.md` (project root) to resolve vault IDs by description
- `ask_question({vault matching "ecosystem" type}, "standards for {domain}", researchMode=true)` — comprehensive standards check

@@ -117,0 +117,0 @@ - `search_knowledge({vault matching "ecosystem" type}, "audit findings for {component_type}")` — past audit comparison

+1
-1
agents/security-officer.md

@@ -37,3 +37,3 @@ ---

- **E**levation of Privilege: Authorization risks
4. If MCP is configured: Read `knowzcode/knowzcode_vaults.md`, resolve vault matching "ecosystem" type, `search_knowledge({vault_id}, "security patterns for {domain}")`
4. If MCP is configured: Read `knowz-vaults.md` (project root), resolve vault whose description matches "ecosystem" (e.g., contains "ecosystem", "decisions", or "conventions"), `search_knowledge({vault_id}, "security patterns for {domain}")`
5. Broadcast findings: `"Initial threat assessment for {goal}"`

@@ -40,0 +40,0 @@ 

+1
-1
knowzcode/automation_manifest.md

@@ -13,3 +13,3 @@ # KnowzCode Automation Manifest

| `/knowzcode:fix` | Execute targeted micro-fix workflow |
| `/knowzcode:init` | Initialize KnowzCode in current project + generate platform adapters |
| `/knowzcode:setup` | Initialize KnowzCode in current project + generate platform adapters |
| `/knowzcode:telemetry` | Investigate production telemetry |

@@ -16,0 +16,0 @@ | `/knowzcode:telemetry-setup` | Configure telemetry sources |

+1
-1
knowzcode/copilot_execution.md

@@ -59,3 +59,3 @@ # Copilot Execution Model

All prompt files live in `.github/prompts/` and are generated by `/knowzcode:init` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.
All prompt files live in `.github/prompts/` and are generated by `/knowzcode:setup` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.

@@ -62,0 +62,0 @@ ---

+68
-25
knowzcode/knowzcode_loop.md

@@ -166,5 +166,5 @@ # KnowzCode - Development Methodology & Operational Protocol

### 3.4 Phase 2B: Completeness Audit
### 3.4 Phase 2B: Completeness Audit + Smoke Testing
An independent, READ-ONLY audit verifying what percentage of specifications were actually implemented.
An independent, READ-ONLY audit verifying what percentage of specifications were actually implemented, plus optional runtime smoke testing.

@@ -175,2 +175,3 @@ **Process:**

- Report gaps, orphan code, and risk assessment
- **Smoke testing** (Tier 3: recommended, Tier 2: opt-in): boot the application and verify runtime behavior against specs
- Do NOT modify any code during this phase

@@ -285,21 +286,12 @@

If KnowzCode MCP server is configured (`knowzcode/mcp_config.md` or `knowzcode/knowzcode_vaults.md`), agents can leverage vault queries to enhance every phase.
If MCP is configured, agents can leverage vault queries to enhance every phase. Vault configuration lives in `knowz-vaults.md` at the project root — created via `/knowz setup`.
**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.
**Cross-platform 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.
**Before using MCP, read `knowz-vaults.md` (project root) to discover vault IDs, descriptions, and routing rules.** Use each vault's description and "When to query"/"When to save" rules to confirm the query is appropriate for that vault. If a single vault is configured, use it for everything. If no vault file exists, fall back to `list_vaults()`. Never hardcode vault names — always resolve from config.
### Vault Types
### Vault Routing
| Type | Purpose | Example Queries |
|------|---------|-----------------|
| **code** | Reference implementations, code snippets, API patterns | `"authentication middleware pattern"`, `"error handling in {framework}"` |
| **ecosystem** | Business rules, conventions, decisions, integrations, platform knowledge | `"checkout flow rules"`, `"pricing constraints"`, `"Stripe webhook setup"` |
| **finalizations** | WorkGroup completion summaries, outcome records | `"past decisions about {component}"`, `"similar WorkGroups"` |
Vault routing is driven by `knowz-vaults.md` — each vault entry has "When to query" and "When to save" rules that determine which vault handles which content. A project may configure one vault covering everything (common for small teams) or multiple specialized vaults. `knowz:writer` (or direct MCP calls) writes to vaults; `knowz:reader` has read-only access. The writer is dispatched at quality gates and routes writes based on vault descriptions and save rules.
A project may configure one vault covering all types (common for small teams) or multiple specialized vaults. `knowz:writer` (or direct MCP calls) writes to vaults; `knowz:reader` has read-only access. The writer is dispatched at quality gates to route writes to the correct vault based on content type.
### Phase-Specific Usage

@@ -309,6 +301,6 @@

|-------|----------|---------|
| **1A (Analysis)** | `search_knowledge({vault matching "ecosystem" type}, "past decisions about {domain}")` | Find prior decisions affecting components |
| **1B (Spec)** | `ask_question({vault matching "ecosystem" type}, "conventions for {component_type}?")` | Check team conventions before drafting |
| **2A (Build)** | `search_knowledge({vault matching "code" type}, "{similar_feature} implementation")` | Find reference implementations |
| **2B (Audit)** | `ask_question({vault matching "ecosystem" type}, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
| **1A (Analysis)** | `search_knowledge({vault_id}, "past decisions about {domain}")` | Find prior decisions affecting components |
| **1B (Spec)** | `ask_question({vault_id}, "conventions for {component_type}?")` | Check team conventions before drafting |
| **2A (Build)** | `search_knowledge({vault_id}, "{similar_feature} implementation")` | Find reference implementations |
| **2B (Audit)** | `ask_question({vault_id}, "standards for {domain}", researchMode=true)` | Comprehensive standards check |
| **3 (Close)** | Dispatch `knowz:writer` (or `create_knowledge` directly if no writer) | Capture patterns, decisions, workarounds |

@@ -328,3 +320,3 @@

At workflow start, if an enterprise-type vault is configured (read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise", then check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`):
At workflow start, if an enterprise vault is configured (read `knowz-vaults.md` to find a vault whose description mentions "enterprise", "compliance", or "audit", then check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`):
- Pull team-wide standards and merge into quality gate criteria

@@ -342,4 +334,54 @@ - Push audit results to the resolved enterprise vault after Phase 2B

> **Vault content must be detailed and self-contained.** Vault entries are retrieved via semantic search — not read directly like local files. Include full reasoning, specific technology names, code examples, and file paths. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
> **Content Detail Principle:** Vault entries live in a vector search index — they are chunked and retrieved via semantic search. Unlike local files (specs, workgroups, logs) which are read directly and benefit from being scannable, vault entries must be **self-contained, detailed, and keyword-rich** because they are discovered by meaning, not by file path.
>
> **Include in every vault entry:**
> - Full reasoning and context — why, not just what
> - Specific technology names, library versions, framework details
> - Code examples, file paths, error messages where relevant
> - Consequences and alternatives considered
>
> Write vault content as if the reader has no project context — they will find this entry via a search query months from now.
### 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.
### Signal Types
During finalization, scan the WorkGroup for insight-worthy patterns:

@@ -382,3 +424,3 @@

If MCP is available but no `knowz:writer`, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
If MCP is available but no `knowz:writer`, resolve vault IDs from `knowz-vaults.md` (project root) before writing:

@@ -399,3 +441,3 @@ - After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {descriptive goal summary}", content="[CONTEXT] {problem description, what prompted this work, constraints}\n[INSIGHT] {scope decisions — what's included/excluded and why}\n[RATIONALE] {risk assessment with full reasoning, affected files, mitigation}\n[TAGS] scope, {domain}", tags=["scope", "{domain}"])`

**When no knowz:writer (single-agent / sequential):**
1. Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
1. Read `knowz-vaults.md` (project root) to resolve vault IDs and routing rules
2. Detect learning candidates from WorkGroup file content

@@ -410,3 +452,3 @@ 3. Check for duplicates via `search_knowledge` — skip if substantially similar exists

After Phase 3:
1. Read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise"
1. Read `knowz-vaults.md` to find a vault whose description mentions "enterprise", "compliance", or "audit"
2. Only push if an enterprise vault is configured

@@ -432,2 +474,3 @@ - Push WorkGroup completion record with goal, NodeIDs, audit score, and decisions

| 2B | reviewer | Quality audit, security review |
| 2B | smoke-tester | Runtime smoke testing (parallel with reviewer) |
| 3 | closer | Finalization, learning capture |

@@ -434,0 +477,0 @@ 

+0
-0
knowzcode/knowzcode_tracker.md

@@ -0,0 +0,0 @@ # KnowzCode - Status Map

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

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

+4
-5
README.md

@@ -77,3 +77,3 @@ # KnowzCode

cd your-project/
/knowzcode:init
/knowzcode:setup

@@ -98,4 +98,3 @@ # All platforms

# Resume where you left off
/knowzcode:continue
# Resume where you left off — just say "continue"
```

@@ -111,6 +110,6 @@

| `/knowzcode:audit [type]` | Run quality audits |
| `/knowzcode:init` | Initialize in your project |
| `/knowzcode:setup` | Initialize in your project |
| `/knowzcode:status` | Check project status |
| `/knowzcode:continue` | Resume active work |
| `/knowzcode:telemetry` | Investigate production errors |
| `/knowzcode:telemetry-setup` | Configure telemetry sources (Sentry, App Insights) |

@@ -117,0 +116,0 @@ ## Platform Support

+8
-35
skills/audit/SKILL.md

@@ -88,37 +88,10 @@ ---

Before spawning agents, determine vault availability:
1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
2. Call `list_vaults(includeStats=true)` **always** — regardless of whether any IDs exist in the file
3. If `list_vaults()` fails → set `MCP_ACTIVE = false`, announce `**MCP Status: Not connected**`, skip vault setup
4. If `list_vaults()` succeeds AND UNCREATED list is non-empty → present the **Vault Creation Prompt**:
1. Read `knowz-vaults.md` from project root — parse vault IDs. If file not found, call `list_vaults(includeStats=true)` to discover vaults.
2. If `list_vaults()` fails AND no `knowz-vaults.md` exists → `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`. Announce: `**MCP Status: Not connected**`
3. If `list_vaults()` fails BUT `knowz-vaults.md` has vault IDs → `MCP_ACTIVE = true`, `VAULTS_CONFIGURED = true`. Announce: `**MCP Status: Lead probe failed — vault agents will verify independently**`
4. If vaults discovered but no `knowz-vaults.md` exists → suggest `"Run /knowz setup to configure vault routing."` Set `VAULTS_CONFIGURED = true` (use discovered IDs for baseline).
5. Set `MCP_ACTIVE` and `VAULTS_CONFIGURED` based on results. Announce: `**MCP Status: Connected — N vault(s) available**` or `**MCP Status: Connected — no vaults configured (knowledge capture disabled)**`
```markdown
## Vault Setup
If no vaults are configured, suggest `/knowz 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 without vault. 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)**`
> **Vault research is mandatory when available.** If `VAULTS_CONFIGURED = true` and `MCP_AGENTS_ENABLED = true`, the `knowz:reader` dispatch MUST execute in both Exploration and Planning modes. The 10-tool-call budget in Exploration Mode is a scope limit, not a reason to skip. Only skip when MCP is genuinely unavailable (`MCP_ACTIVE = false`).

@@ -195,3 +168,3 @@

4. If `VAULTS_CONFIGURED = true` AND `MCP_AGENTS_ENABLED = true`, dispatch `knowz:reader` for standards lookup in parallel with reviewers:
> Read `knowzcode/knowzcode_vaults.md` to discover configured vaults — their IDs, types, descriptions.
> Read `knowz-vaults.md` (project root) to discover configured vaults — their IDs, types, descriptions.
> Query for team standards: search ecosystem-type vaults for standards, conventions, and past audit decisions.

@@ -339,3 +312,3 @@ > Return synthesized findings.

**Handling**:
- **A**: Dispatch `knowz:writer` with a self-contained prompt summarizing all findings, tagged with the topic. Read `knowzcode/knowzcode_vaults.md` to resolve the target vault (use ecosystem-type vault). Check for duplicates via `search_knowledge` before writing.
- **A**: Dispatch `knowz:writer` with a self-contained prompt summarizing all findings, tagged with the topic. Read `knowz-vaults.md` (project root) to resolve the target vault (use ecosystem-type vault). Check for duplicates via `search_knowledge` before writing.
- **B**: Ask user which sections to save, then dispatch `knowz:writer` with selected content.

@@ -342,0 +315,0 @@ - **C**: Proceed to Step 5.

+13
-38
skills/explore/SKILL.md

@@ -72,3 +72,3 @@ ---

If `knowzcode/` doesn't exist, inform user to run `/knowzcode:init` first. STOP.
If `knowzcode/` doesn't exist, inform user to run `/knowzcode:setup` first. STOP.

@@ -100,2 +100,4 @@ ## Step 3: Set Up Execution Mode

Use task lists to plan and track your research throughout. Add new tasks as discoveries expand the scope.
### MCP Probe

@@ -106,37 +108,10 @@

Before spawning agents, determine vault availability:
1. Read `knowzcode/knowzcode_vaults.md` — partition entries into CONFIGURED (non-empty ID) and UNCREATED (empty ID)
2. Call `list_vaults(includeStats=true)` **always** — regardless of whether any IDs exist in the file
3. If `list_vaults()` fails -> set `MCP_ACTIVE = false`, announce `**MCP Status: Not connected**`, skip vault setup
4. If `list_vaults()` succeeds AND UNCREATED list is non-empty -> present the **Vault Creation Prompt**:
1. Read `knowz-vaults.md` from project root — parse vault IDs. If file not found, call `list_vaults(includeStats=true)` to discover vaults.
2. If `list_vaults()` fails AND no `knowz-vaults.md` exists -> `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`. Announce: `**MCP Status: Not connected**`
3. If `list_vaults()` fails BUT `knowz-vaults.md` has vault IDs -> `MCP_ACTIVE = true`, `VAULTS_CONFIGURED = true`. Announce: `**MCP Status: Lead probe failed — vault agents will verify independently**`
4. If vaults discovered but no `knowz-vaults.md` exists -> suggest `"Run /knowz setup to configure vault routing."` Set `VAULTS_CONFIGURED = true` (use discovered IDs for baseline).
5. Set `MCP_ACTIVE` and `VAULTS_CONFIGURED` based on results. Announce: `**MCP Status: Connected — N vault(s) available**` or `**MCP Status: Connected — no vaults configured (knowledge capture disabled)**`
```markdown
## Vault Setup
If no vaults are configured, suggest `/knowz 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 without vault. 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)**`
> **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`).

@@ -180,3 +155,3 @@

> **Goal**: Research "{topic}" — gather local context and vault knowledge.
> **Vault config**: `knowzcode/knowzcode_vaults.md`
> **Vault config**: `knowz-vaults.md` (project root)
> **Lead Vault Baseline**: {VAULT_BASELINE or "No baseline — MCP not available or no vaults configured"}

@@ -258,3 +233,3 @@ > **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.

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. 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.")`
- `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: knowz-vaults.md (project root). 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.")`

@@ -440,3 +415,3 @@ 2. **analyst** — Code exploration / Impact analysis:

**Handling**:
- **A**: Dispatch `knowz:writer` with a self-contained prompt summarizing all findings, tagged with the topic. Read `knowzcode/knowzcode_vaults.md` to resolve the target vault (use ecosystem-type vault). Check for duplicates via `search_knowledge` before writing.
- **A**: Dispatch `knowz:writer` with a self-contained prompt summarizing all findings, tagged with the topic. Read `knowz-vaults.md` (project root) to resolve the target vault (use ecosystem-type vault). Check for duplicates via `search_knowledge` before writing.
- **B**: Ask user which sections to save, then dispatch `knowz:writer` with selected content.

@@ -458,3 +433,3 @@ - **C**: Proceed to Step 6.

1. Ask the user what content to save (or confirm if they specified)
2. Resolve target vault from `knowzcode/knowzcode_vaults.md`
2. Resolve target vault from `knowz-vaults.md` (project root)
3. Dispatch `knowz:writer` via Task() with a self-contained prompt:

@@ -461,0 +436,0 @@ - Content to save (from exploration findings or user-specified content)

+1
-1
skills/init/references/templates.md
# KnowzCode Init — Template Files
These templates are generated during `/knowzcode:init` Step 3. Create each file in the `knowzcode/` directory.
These templates are generated during `/knowzcode:setup` Step 3. Create each file in the `knowzcode/` directory.

@@ -5,0 +5,0 @@ ## knowzcode_project.md

+28
-22
skills/init/SKILL.md
---
name: init
name: setup
description: "Initialize KnowzCode framework in the current project. Use when asked to set up, install, or bootstrap KnowzCode in a new or existing project."

@@ -185,3 +185,3 @@ user-invocable: true

.agents/skills/knowzcode-continue/SKILL.md (/knowzcode:continue — resume workflow)
.agents/skills/knowzcode-init/SKILL.md (/knowzcode:init — initialize project)
.agents/skills/knowzcode-init/SKILL.md (/knowzcode:setup — initialize project)
.agents/skills/knowzcode-status/SKILL.md (/knowzcode:status — check status)

@@ -300,3 +300,3 @@ .agents/skills/knowzcode-telemetry/SKILL.md (/knowzcode:telemetry — investigate errors)

.gemini/commands/knowzcode/continue.toml (/knowzcode:continue — resume workflow)
.gemini/commands/knowzcode/init.toml (/knowzcode:init — initialize project)
.gemini/commands/knowzcode/init.toml (/knowzcode:setup — initialize project)
.gemini/commands/knowzcode/telemetry.toml (/knowzcode:telemetry — investigate errors)

@@ -380,26 +380,34 @@ .gemini/commands/knowzcode/telemetry-setup.toml (/knowzcode:telemetry-setup — configure sources)

If the user is on Claude Code, **actively offer** to enable Agent Teams:
If the user is on Claude Code, **auto-enable Agent Teams with opt-out confirmation**.
**Step 9a: Ask the user**
**If NOT on Claude Code** (detected in Step 8 platform detection — Codex, Gemini, Cursor, Copilot, Windsurf): skip this entire step. Agent Teams is a Claude Code feature. Announce:
> Agent Teams: Not applicable (Claude Code feature). Your platform uses subagent delegation for multi-agent workflows.
**Step 9a: Announce and confirm**
Present to the user:
```
"Would you like to enable Agent Teams? (recommended for Claude Code)
Agent Teams will be enabled for this project (recommended).
Agent Teams spawns specialized teammates for each workflow phase,
giving you richer multi-agent coordination.
Agent Teams provides persistent knowledge-liaison coverage, parallel orchestration,
and consistent vault capture across all workflow phases. Without it, knowledge
operations are one-shot and orchestration is single-threaded.
Without it, KnowzCode uses subagent delegation (works fine, just less interactive)."
Options:
- Yes, for this project only (recommended)
- Yes, for all projects (writes to ~/.claude/settings.json)
- No (use subagent fallback)
Press enter to confirm, or type 'no' to use single-agent fallback.
```
**Step 9b: If yes, create/update the appropriate settings file**
**Step 9b: Handle response**
- **"This project only"** → write to `.claude/settings.local.json` (project-level, gitignored)
- **"All projects"** → write to `~/.claude/settings.json` (home-level global config)
- **If confirmed** (enter, "yes", "y", or any affirmative):
1. Write `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to `.claude/settings.local.json` (project-level, gitignored)
2. Follow-up prompt: `"Enable globally for all projects too? (y/n)"`
- If yes: also write to `~/.claude/settings.json` (home-level global config)
- If no: project-only (done)
Read the target settings file if it exists. Merge the Agent Teams env var into it:
- **If declined** ("no", "n"):
1. Skip env var write
2. Announce: `"Agent Teams not enabled. Knowledge capture will be reduced — vault operations will be one-shot instead of persistent. You can enable later by adding CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to .claude/settings.local.json"`
Read the target settings file(s) if they exist. Merge the Agent Teams env var into existing content:
```json

@@ -415,3 +423,3 @@ {

**Step 7.5c: Windows note**
**Step 9c: Windows note**

@@ -425,4 +433,2 @@ If the platform is Windows (`process.platform === 'win32'` or detected via environment):

**Step 7.5d: If no, proceed normally** — subagent delegation works without any configuration.
### 10. Optional: Set up enterprise compliance (experimental)

@@ -461,3 +467,3 @@

Agent Teams: [Enabled (.claude/settings.local.json) | Not enabled (subagent fallback)]
Agent Teams: [Enabled (.claude/settings.local.json) — recommended | Declined (subagent fallback — reduced knowledge capture)]

@@ -464,0 +470,0 @@ Next steps:

+2
-2
skills/status/SKILL.md

@@ -53,3 +53,3 @@ ---

If `knowzcode/` is missing: suggest `/knowzcode:init` and STOP.
If `knowzcode/` is missing: suggest `/knowzcode:setup` and STOP.

@@ -149,3 +149,3 @@ 2. **Check Agent Teams Status**

- `/knowz register` — Register a new Knowz account
- `/knowzcode:init` — Initialize KnowzCode in project
- `/knowzcode:setup` — Initialize KnowzCode in project
- `/knowzcode:work` — Start feature (uses MCP if available)

@@ -152,0 +152,0 @@ 

+19
-2
skills/work/references/parallel-orchestration.md

@@ -118,2 +118,7 @@ # Parallel Teams Orchestration — Work Skill (Tier 3)

6a. Create smoke-tester task and spawn (one per WorkGroup, not per partition):
- `TaskCreate("Smoke test: {wgid}", addBlockedBy: [all-implement-task-ids])` → `TaskUpdate(owner: "smoke-tester")`
Spawn smoke-tester with its `{task-id}` in the spawn prompt. The smoke-tester waits until at least one builder marks implementation complete, then launches the full app for runtime verification.
**Note:** Unlike reviewers, only one smoke-tester runs per WorkGroup — it needs the full app running, not individual partitions.
6. **Specialist implementation reviews** (if `SPECIALISTS_ENABLED` non-empty): Create specialist review tasks alongside reviewer audit tasks, same `addBlockedBy`:

@@ -147,2 +152,11 @@ - If `security-officer` active — one task per partition (runs parallel to reviewer):

**Smoke test gap flow** (parallel with per-partition reviewer gaps):
h. Smoke-tester marks task complete with structured failure report
i. Lead creates smoke fix tasks: `TaskCreate("Fix smoke gap: {description}", addBlockedBy: [smoke-task-id])` → `TaskUpdate(owner: "builder-N")` (assigned to the builder whose partition owns the failing code)
j. Lead DMs builder: `"**New Task**: #{fix-task-id} — Fix smoke gap: {description}. {expected vs observed}"`
k. Builder fixes, re-runs unit tests, marks fix task complete
l. Lead creates re-smoke task: `TaskCreate("Re-smoke: {wgid}", addBlockedBy: [smoke-fix-task-id])` → `TaskUpdate(owner: "smoke-tester")`
m. Lead DMs smoke-tester: `"**New Task**: #{resmoke-task-id} — Re-smoke: {wgid}. Previous failures: {list}"`
n. 3-iteration cap — if exceeded, pause autonomous mode: `> **Autonomous Mode Paused** — Smoke test failed 3 iterations. Manual review required.`
8. Enterprise compliance (if enabled):

@@ -167,4 +181,5 @@ - Lead creates parallel compliance task for each reviewer (scoped to their partition)

10. After all NodeIDs implemented + audited across all partitions:
10. After all NodeIDs implemented + audited across all partitions AND smoke test complete:
- Lead consolidates audit results from all reviewers
- Lead consolidates smoke test results (if smoke-tester was spawned)
- Lead consolidates specialist reports (if `SPECIALISTS_ENABLED` non-empty — include even if some specialist tasks are still pending, noting `[Pending: {specialist}]`)

@@ -174,3 +189,3 @@ - Lead presents **Quality Gate #3** (see [quality-gates.md](quality-gates.md))

11. Shut down analyst, architect, all builders, and all reviewers
11. Shut down analyst, architect, all builders, all reviewers, and smoke-tester (if spawned)

@@ -248,2 +263,4 @@ ---

| Re-audit: NodeID-X round N | Fix gaps round N | reviewer-N |
| Smoke test: {wgid} | All implement tasks complete | smoke-tester |
| Re-smoke: {wgid} round N | Smoke gap fix round N | smoke-tester |
| Phase 3 finalization | All audits approved | closer |

@@ -250,0 +267,0 @@ | Reader: vault queries | (none — dispatched by knowledge-liaison) | knowz:reader |

+20
-0
skills/work/references/quality-gates.md

@@ -114,2 +114,3 @@ # Quality Gates — Work Skill

**Gaps Found**: {count}
**Smoke Test**: {PASS / FAIL / SKIPPED — reason}

@@ -122,2 +123,9 @@ ### Specialist Reports [only when SPECIALISTS_ENABLED non-empty]

### Smoke Test Results [only when smoke-tester was spawned]
**Status**: {PASS / FAIL}
**Method**: {API / Chrome / Playwright}
**Launch**: {how app was started, or "user-provided"}
**Checks**: {count passed} / {count total}
**Findings**: {details or "All checks passed"}
**Recommendation**: {proceed / return to implementation}

@@ -155,2 +163,13 @@

### Smoke Test Gap Loop
If the smoke-tester reports failures:
1. Lead creates smoke fix tasks assigned to the builder owning the failing code
2. Builder fixes, re-runs unit tests, marks fix task complete
3. Lead creates re-smoke task for smoke-tester
4. Smoke-tester re-runs against the running app
5. **3-iteration cap**: If smoke test exceeds 3 iterations, pause autonomous mode: `> **Autonomous Mode Paused** — Smoke test failed 3 iterations. Manual review required.`
Smoke gap loop runs parallel with per-partition reviewer gap loops. Gate #3 waits for both to pass.
### Sequential Teams mode:

@@ -195,2 +214,3 @@

- [ ] Specs updated to As-Built / FINAL status
- [ ] Smoke test approach captured (if smoke testing ran): launch method, endpoints tested, test method, project-specific quirks

@@ -197,0 +217,0 @@ Update workgroup to "Closed" and report:

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

@@ -61,3 +61,3 @@ # Agent Spawn Prompts — Work Skill

> **Goal**: {goal}
> **Vault config**: `knowzcode/knowzcode_vaults.md`
> **Vault config**: `knowz-vaults.md` (project root)
> **Lead Vault Baseline**: {VAULT_BASELINE or "No baseline — MCP not available or no vaults configured"}

@@ -292,2 +292,27 @@ > **Lifecycle**: You persist from Stage 0 through team shutdown. You are the last agent shut down before team cleanup.

## Phase 2B: Smoke Testing
**Agent**: `smoke-tester` | **Loop.md**: Section 3.4
**Spawn prompt**:
> You are the **smoke-tester** for WorkGroup `{wgid}`.
> Read `agents/smoke-tester.md` for your full role definition.
>
> **Goal**: {goal}
> **Change Set**: {NodeIDs}
> **Specs**: {list of spec file paths}
> **Context files**: Read `knowzcode/knowzcode_project.md`
> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
>
> **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
> **App status**: {`"App already running at {URL}"` | `"Launch app yourself"`}
> **Deliverable**: Smoke test report with pass/fail per check, evidence, and actionable failure descriptions.
**Dispatch**:
- *Parallel Teams*: One smoke-tester spawned at Stage 2 alongside reviewers. Runs as background agent. Uses `addBlockedBy` on the same implementation tasks as the reviewer. No partition — smoke-tester covers the whole app (it needs the full app running, not individual partitions).
- *Sequential Teams*: Spawn after reviewer completes, before Phase 3. Create task `Phase 2B: Smoke test for {wgid}`.
- *Subagent*: `Task(subagent_type="smoke-tester", description="Phase 2B smoke testing", prompt=<above>)`
---
## Phase 3: Finalization

@@ -325,3 +350,3 @@

> **Vault writes**: You own all vault writes directly. Follow the Learning Capture instructions in `agents/closer.md`.
> **MCP Status**: {MCP_ACTIVE} — Vaults configured: {VAULTS_CONFIGURED}. Vault config: `knowzcode/knowzcode_vaults.md`.
> **MCP Status**: {MCP_ACTIVE} — Vaults configured: {VAULTS_CONFIGURED}. Vault config: `knowz-vaults.md` (project root).
> **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, write learnings to vaults, and create final commit.

@@ -328,0 +353,0 @@ 

+65
-53
skills/work/SKILL.md

@@ -42,3 +42,3 @@ ---

If missing: inform user to run `/knowzcode:init` first. STOP.
If missing: inform user to run `/knowzcode:setup` first. STOP.

@@ -55,2 +55,4 @@ ## Step 1: Generate WorkGroup ID

**Agent Teams is the expected execution mode for Tier 2+ workflows.** It enables persistent knowledge-liaison coverage, parallel orchestration, and consistent vault capture. Subagent delegation is a degraded fallback — it works, but knowledge capture is reduced and orchestration is single-threaded.
Determine the execution mode using try-then-fallback:

@@ -64,5 +66,13 @@

- **If TeamCreate succeeds** → Agent Teams is available. Choose mode:
- `--sequential` or Tier 2 → **Sequential Teams**: `**Execution Mode: Sequential Teams** — created team kc-{wgid}`
- Otherwise → **Parallel Teams** (default for Tier 3): `**Execution Mode: Parallel Teams** — created team kc-{wgid}`
- **If TeamCreate fails** (error, unrecognized tool, timeout) → **Subagent Delegation**: `**Execution Mode: Subagent Delegation** — Agent Teams not available, using Task() fallback`
- `--sequential` → **Sequential Teams**: `**Execution Mode: Sequential Teams** — created team kc-{wgid}`
- Tier 2 → **Lightweight Teams**: `**Execution Mode: Lightweight Teams** — created team kc-{wgid} (knowledge-liaison + builder)`
- Tier 3 (default) → **Parallel Teams**: `**Execution Mode: Parallel Teams** — created team kc-{wgid}`
- **If TeamCreate fails** (error, unrecognized tool, timeout) → **Subagent Delegation** with degradation warning:
```
**Execution Mode: Subagent Delegation** — Agent Teams not available
> WARNING: Knowledge capture and parallel orchestration degraded. The knowledge-liaison
> will not run persistently — vault reads are one-shot and captures may be inconsistent.
```
On Claude Code, append: `> Enable Agent Teams: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.local.json`
On other platforms: no enablement instruction (Agent Teams is Claude Code-only).

@@ -72,3 +82,3 @@ 3. **If `--subagent` specified** → **Subagent Delegation** directly (no TeamCreate attempt):

For all Agent Teams modes (Sequential and Parallel):
For all Agent Teams modes (Sequential, Lightweight, and Parallel):
- You are the **team lead** in delegate mode — you coordinate phases, present quality gates, and manage the workflow. You NEVER write code, specs, or project files directly. All work is done by teammates. (Tip: the user can press Shift+Tab to system-enforce delegate mode.)

@@ -148,3 +158,3 @@ - After completion or if the user cancels, shut down all active teammates and clean up the team (see Cleanup section)

- Tier 3 Subagent Delegation: Supported via parallel `Task()` calls
- Sequential Teams / Tier 2: Not supported — if specialists were detected, announce: `> **Specialists: SKIPPED** — not supported in {Sequential Teams / Tier 2} mode.`
- Sequential Teams / Lightweight Teams (Tier 2): Not supported — if specialists were detected, announce: `> **Specialists: SKIPPED** — not supported in {Sequential Teams / Lightweight Teams} mode.`

@@ -168,3 +178,3 @@ Default: `SPECIALISTS_ENABLED = []` (specialists are opt-in).

1. Check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`
2. If enabled: Read `knowzcode/knowzcode_vaults.md` to find vault matching type "enterprise", then `ask_question({resolved_enterprise_vault_id}, "team standards for {project_type}")`
2. If enabled: Read `knowz-vaults.md` from project root, find vault with enterprise/compliance description, then `ask_question({resolved_enterprise_vault_id}, "team standards for {project_type}")`
3. Merge returned standards into WorkGroup context for quality gate criteria

@@ -182,40 +192,10 @@

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**:
1. Read `knowz-vaults.md` from project root — parse vault IDs. If file not found, call `list_vaults(includeStats=true)` to discover vaults.
2. If `list_vaults()` fails AND no `knowz-vaults.md` exists → `MCP_ACTIVE = false`, `VAULTS_CONFIGURED = false`. Announce: `**MCP Status: Not connected**`
3. If `list_vaults()` fails BUT `knowz-vaults.md` has vault IDs → `MCP_ACTIVE = true`, `VAULTS_CONFIGURED = true`. Announce: `**MCP Status: Lead probe failed — vault agents will verify independently**`
4. If vaults discovered but no `knowz-vaults.md` exists → suggest `"Run /knowz setup to configure vault routing."` Set `VAULTS_CONFIGURED = true` (use discovered IDs for baseline).
5. Set `MCP_ACTIVE` and `VAULTS_CONFIGURED` based on results. Announce: `**MCP Status: Connected — N vault(s) available**` or `**MCP Status: Connected — no vaults configured (knowledge capture disabled)**`
```markdown
## Vault Setup
If no vaults are configured, suggest `/knowz 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

@@ -266,2 +246,4 @@

Use task lists to plan and track work throughout. Add new tasks as discoveries or needs emerge during each phase.
## Step 5: Input Classification

@@ -316,4 +298,15 @@

### Light Phase 1 (Inline — lead does this, no agent)
### Tier 2 Team Setup
If Agent Teams is available (TeamCreate succeeded in Step 2):
1. Create team `kc-{wgid}` (already done in Step 2)
2. Spawn `knowledge-liaison` as persistent teammate using the Stage 0 spawn prompt from `references/spawn-prompts.md`. Pass `VAULT_BASELINE` from Step 3.6 in the spawn prompt.
3. Knowledge-liaison performs startup protocol (reads local context, dispatches vault readers if vaults configured, sends Context Briefing — but only to lead since no analyst/architect in Tier 2)
If Agent Teams is NOT available (subagent fallback):
- Knowledge-liaison dispatched as one-shot `Task(subagent_type="knowzcode:knowledge-liaison")` for vault baseline research before Phase 2
- Degradation warning already shown in Step 2
### Light Phase 1 (Inline — lead coordinates, knowledge-liaison active)
1. Quick impact scan: grep for related files, check existing specs

@@ -346,10 +339,24 @@ 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.

### Light Phase 2A: Implementation (Builder agent)
### Light Phase 2A: Implementation (Builder teammate)
Spawn the builder using the standard Phase 2A prompt below (same for both tiers).
**Agent Teams mode**: Spawn the builder as a teammate in the `kc-{wgid}` team using the standard Phase 2A spawn prompt from `references/spawn-prompts.md` (same prompt for both tiers). The builder runs as a persistent teammate alongside the knowledge-liaison.
**Subagent fallback**: Spawn the builder via `Task(subagent_type="knowzcode:builder")` with the standard Phase 2A prompt (current behavior).
The builder self-verifies against spec VERIFY criteria — no separate audit phase.
### Light Phase 3 (Inline — lead does this, no agent)
### Light Phase 2B: Smoke Testing (Opt-in)
Only if user explicitly requested smoke testing (e.g., `--smoke-test` in `$ARGUMENTS` or natural language: "smoke test", "test it running", "verify it works"):
**Agent Teams mode**: Spawn the smoke-tester as a teammate in the `kc-{wgid}` team using the Phase 2B smoke-tester spawn prompt from `references/spawn-prompts.md`.
**Subagent fallback**: Spawn via `Task(subagent_type="smoke-tester", description="Smoke test", prompt=<spawn prompt>)`.
If smoke test fails: create fix tasks for builder, re-run smoke-tester. 3-iteration cap, then escalate. App lifecycle managed by smoke-tester (see `agents/smoke-tester.md`).
If user did not request smoke testing, skip to Light Phase 3.
### Light Phase 3 (Inline — lead coordinates, knowledge-liaison captures)
After builder completes successfully:

@@ -371,3 +378,7 @@ 1. Update spec to As-Built status

5. Report completion.
6. **Vault Write Checklist (MUST — do not skip, do not defer)**:
6. **Knowledge-Liaison Capture** (Agent Teams mode only):
- DM the knowledge-liaison: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`
- Wait for knowledge-liaison to confirm capture (max 2 minutes, else proceed with warning)
- After capture, shut down knowledge-liaison, then delete team `kc-{wgid}`
7. **Vault Write Checklist (MUST — do not skip, do not defer)**:
You MUST attempt every item. Check each off or report failure to the user.

@@ -378,3 +389,3 @@ - [ ] WorkGroup file exists in `knowzcode/workgroups/{wgid}.md`

- [ ] MCP progress capture attempted:
- Read `knowzcode/knowzcode_vaults.md`, resolve vault IDs. Read the WorkGroup file for the `**KnowledgeId:**` value.
- Read `knowz-vaults.md`, resolve vault IDs. Read the WorkGroup file for the `**KnowledgeId:**` value.
- **If KnowledgeId exists**: call `get_knowledge_item(id)`. If found → `update_knowledge` with the completion record. If not found → remove `**KnowledgeId:**` from the WorkGroup file, fall through to create.

@@ -387,3 +398,3 @@ - **If no KnowledgeId**: check for existing entry via `search_by_title_pattern("WorkGroup: {wgid}*")` — update if found, create if not.

**DONE** — 3 agents skipped (analyst, architect, reviewer, closer).
**DONE** — Lightweight team: knowledge-liaison (persistent) + builder. Skipped: analyst, architect, reviewer, closer.

@@ -401,2 +412,4 @@ ---

**Smoke testing**: Tier 3 recommends smoke testing at Phase 2B. At Gate #2, note to the user that smoke testing will run alongside the reviewer. The user can decline. If not declined, the smoke-tester is spawned at Stage 2 alongside reviewers (see [parallel-orchestration.md](references/parallel-orchestration.md)).
## Step 6: Spec Detection (Optional Optimization)

@@ -424,5 +437,3 @@

> **MCP Probe Design Note:** Multiple agents perform independent MCP verification (`list_vaults()`) at different points in the workflow. This redundancy is intentional — agents spawn at different times and MCP connectivity can change between spawns. Each agent's probe is authoritative for its own MCP state.
>
> **Vault Creation Failure Recovery:** If BOTH `create_vault()` and name-matching fallback fail: log failure, set `VAULTS_CONFIGURED = false`, continue without vault. Report: `"⚠️ Vault creation failed — proceeding without knowledge capture. Run /knowz setup to retry."`
> **MCP Probe Design Note:** Multiple agents perform independent MCP verification (`list_vaults()`) at different points in the workflow. This redundancy is intentional — agents spawn at different times and MCP connectivity can change between spawns. Each agent's probe is authoritative for its own MCP state. Vault configuration is read from `knowz-vaults.md` at the project root.

@@ -450,2 +461,3 @@ - **Stage 0**: Create team, use MCP/vault baseline from Step 3.6, spawn knowledge-liaison/analyst/architect/scanner/specialist agents in parallel

| 2B | reviewer(s) | #3: Audit Results | ARC completion, gap reports |
| 2B | smoke-tester | #3: Audit Results | Runtime verification, smoke pass/fail |
| 3 | closer | — | Final specs, tracker updates, log entry, commit |

@@ -452,0 +464,0 @@ 

-333
knowzcode/knowzcode_vaults.md
# KnowzCode Vault Configuration
Multi-vault routing configuration for intelligent vault selection based on query intent and write conditions.
---
> **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
### (not created)
- **Name**: Code Patterns
- **ID**:
- **Type**: code
- **Description**: Key learnings, gotchas, takeaways, and architecture insights from the codebase.
- **Write Conditions**:
- After Phase 2A: implementation patterns and workarounds from TDD cycles
- After Phase 3: Pattern/Workaround/Performance learnings from WorkGroup scan
- **Content Filter**: Pattern:, Workaround:, Performance:
### (not created)
- **Name**: Ecosystem Knowledge
- **ID**:
- **Type**: ecosystem
- **Description**: Business rules, platform logic, conventions, decisions, and cross-system details. Used for lookups of details beyond scope of current codebase, including how other systems interact.
- **Write Conditions**:
- After Phase 1A: scope decisions, risk assessment
- After Phase 2B: security findings, quality decisions
- After Phase 3: Decision/Convention/Security/Integration learnings
- **Content Filter**: Decision:, Convention:, Security:, Integration:, Scope:
### (not created)
- **Name**: Finalizations
- **ID**:
- **Type**: finalizations
- **Description**: Final summaries at WorkGroup completion. All finalization details documenting complete execution and outcomes. Written only when work is verified and WorkGroup is marked completed.
- **Write Conditions**:
- After Phase 3: full WorkGroup summary with goal, NodeIDs, audit score, decisions, outcomes
- **Content Filter**: (completion records)
---
## Vault Types
| Type | Purpose | Read By | Written By | Example Queries |
|------|---------|---------|------------|-----------------|
| **code** | Implementation patterns, workarounds, performance | knowz:reader, agents | knowz:writer | "Find auth middleware pattern", "Retry logic workaround" |
| **ecosystem** | Decisions, conventions, security, integrations, business rules | knowz:reader, agents | knowz:writer | "Error handling conventions", "Why Redis over Memcached?" |
| **finalizations** | WorkGroup completion summaries, outcome records | knowz:reader, agents | knowz:writer | "What happened in WG-feat-auth?", "Recent completions" |
> **Types are user-configurable labels, not framework constants.** Users can add, rename, or create custom vault types freely. The 3 defaults above cover common needs. For example, teams needing compliance tracking can add an `enterprise` type.
>
> **Backwards compatibility**: `research`, `domain`, and `platform` are aliases for `ecosystem`. `sessions` is an alias for `finalizations`. Existing vaults configured with these types continue to work — agents treat aliases identically when resolving vault targets.
---
## Vault Routing Rules
### Read Routing (knowz:reader + agents)
| Query Type | Description | Target Vault Type |
|------------|-------------|-------------------|
| **Code patterns** | Implementations, patterns, "how did we build X?" | `code` |
| **Decisions / conventions** | Past decisions, best practices, "why did we?" | `ecosystem` |
| **Integration questions** | Third-party APIs, platform behaviors | `ecosystem` |
| **Standards / compliance** | Team standards, audit results | user's enterprise vault (if configured) |
| **Session history** | Past WorkGroups, outcomes | `finalizations` |
### Write Routing (knowz:writer)
| Learning Category | Target Vault Type | Title Prefix |
|-------------------|-------------------|--------------|
| Pattern | `code` | `Pattern:` |
| Workaround | `code` | `Workaround:` |
| Performance | `code` | `Performance:` |
| Decision | `ecosystem` | `Decision:` |
| Convention | `ecosystem` | `Convention:` |
| Security | `ecosystem` | `Security:` |
| Integration | `ecosystem` | `Integration:` |
| Scope | `ecosystem` | `Scope:` |
| Completion record | `finalizations` | `Completion:` |
| Audit trail (enterprise) | user's enterprise vault | `Audit:` |
### How Routing Works
1. **For reads**: Reader agent reads vault descriptions and matches query intent to vault type
2. **For writes**: Writer agent matches learning category to vault type using the write routing table, then applies the vault's content filter to format the payload
3. **Fallback**: If no specific match, use the first vault of type `ecosystem`. If only one vault exists, use it for everything
---
## Uncreated Vault Detection
Default vault entries ship with an empty **ID** field (null GUID), indicating "not yet created on server."
### Detection Points
Uncreated vaults are detected at multiple points in the workflow:
1. **`/knowz register` and `/knowz setup`** — detect empty IDs during initial setup and prompt to create vaults
2. **`/knowzcode:work`, `/knowzcode:explore`, and `/knowzcode:audit`** — detect empty IDs during the MCP Probe at workflow start. These commands always call `list_vaults()` regardless of whether vault IDs exist, then present a Vault Setup table showing each uncreated vault's name, type, description, and which phases write to it. The user can create all, select specific vaults, or skip (proceeding without knowledge capture).
### Creation Flow
When uncreated vaults are detected, the user sees:
```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 |
|-------|------|-------------|----------------|
```
Table rows are built dynamically from uncreated entries — only showing vaults that haven't been created. The "Written During" column is derived from each vault's Write Conditions field.
Options: **A) Create all** (recommended), **B) Select which to create**, **C) Skip**.
On confirmation, each vault is created via the MCP `create_vault(name, description)` tool. If `create_vault` is not available, the command falls back to matching by name against `list_vaults()` results. The entry's **ID** field is updated with the server-returned vault ID. The H3 heading is updated from `(not created)` to the vault ID.
---
## Write Conditions and Content Filters
Each vault type defines when it accepts writes (Write Conditions) and how content should be formatted (Content Filter).
### Content Detail Principle
Vault entries live in a vector search index — they are chunked and retrieved via semantic search. Unlike local files (specs, workgroups, logs) which are read directly and benefit from being scannable, vault entries must be **self-contained, detailed, and keyword-rich** because they are discovered by meaning, not by file path.
**Include in every vault entry:**
- Full reasoning and context — why, not just what
- Specific technology names, library versions, framework details
- Code examples, file paths, error messages where relevant
- Consequences and alternatives considered
**Anti-pattern** (poor search recall, useless when retrieved):
> `"[NodeIDs] AuthMiddleware\n[Risk] Medium"`
**Good pattern** (rich search matches, self-contained on retrieval):
> `[CONTEXT] During JWT authentication implementation for the Express API, the jsonwebtoken library's verify() method silently accepts expired tokens when clockTolerance is set above 0.`
> `[INSIGHT] Always set clockTolerance to 0 (default) and handle TokenExpiredError explicitly. Some tutorials suggest 30s tolerance which creates a security window where revoked tokens remain valid.`
> `[RATIONALE] A 30-second tolerance means stolen tokens stay usable after revocation. Our auth middleware in src/middleware/auth.ts now checks expiry with zero tolerance.`
> `[TAGS] security, jwt, express, authentication`
Write vault content as if the reader has no project context — they will find this entry via a search query months from now.
### code
**Write Conditions**: Learning category is Pattern, Workaround, or Performance.
**Content Filter**:
```
[CONTEXT] {Where and why the pattern was encountered — include the component, framework, and problem being solved. Provide enough background for someone with no project familiarity.}
[PATTERN] {What was built or discovered — describe the approach, the key insight, and how it differs from the obvious/naive solution.}
[EXAMPLE] {Code snippet, usage example, or file path reference — concrete enough to be directly useful when retrieved.}
[TAGS] {learning category, domain, language, framework — include specific technology names for search discoverability}
```
### ecosystem
**Write Conditions**: Learning category is Decision, Convention, Security, Scope, or Integration.
**Content Filter**:
```
[CONTEXT] {What prompted the decision — the problem, the alternatives considered, and the constraints. Include component names and file paths where relevant.}
[INSIGHT] {The decision, convention, security finding, or integration detail — state it clearly and completely so it stands alone without context.}
[RATIONALE] {Why this approach was chosen over alternatives — include trade-offs, risks of the rejected options, and any conditions that might change this decision.}
[TAGS] {learning category, domain, specific technology names — be generous with tags for search discoverability}
```
### finalizations
**Write Conditions**: Phase 3 finalization — WorkGroup completion record.
**Content Filter**:
```
[GOAL] {Original goal from WorkGroup — restate fully, not just the WorkGroup slug}
[OUTCOME] {success | partial | abandoned — include what was delivered and what was deferred}
[NODES] {NodeIDs changed — list each with a one-line summary of what it covers}
[DURATION] {Phases completed (e.g. "1A-3"), total iterations, any notable delays or blockers}
[SUMMARY] {Key learnings from this WorkGroup — architectural discoveries, patterns established, gotchas encountered. This is the most valuable field for future search queries.}
[TAGS] {finalization, domain, outcome, key technology names}
```
---
## Single Vault Model
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.
### 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?**
- Simpler onboarding — no vault type decisions needed
- Code search works with grep/glob for most projects
- MCP vault is optimized for organizational knowledge
- Add specialized vaults later via `/knowz setup`
---
## Manual Configuration
You can manually add vaults by editing this file. Use this format:
```markdown
### {vault-id}
- **Name**: {Display Name}
- **ID**: {vault-id}
- **Type**: code | ecosystem | finalizations | {custom}
- **Description**: {Detailed description of what this vault contains. Be specific about what types of questions should be routed here. Include example queries.}
- **Write Conditions**: {When knowz:writer should write to this vault}
- **Content Filter**: {Format template for create_knowledge content}
```
**Tips for good descriptions:**
- Be specific about content type (patterns vs decisions vs integrations)
- Include example queries that should route to this vault
- Mention key topics or domains covered
- Write conditions should reference learning categories from the routing table
> **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
| Agent | Vault Interaction | Purpose |
|-------|-------------------|---------|
| `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) |
| `knowz:writer` | Write to matching vaults | Route and capture learnings (dispatched by knowledge-liaison) |
| `analyst` | Read via knowz:reader | Past decisions + affected code patterns |
| `architect` | Read via knowz:reader | Conventions + implementation examples |
| `builder` | Read via knowz:reader | Best practices + similar patterns |
| `reviewer` | Read via knowz:reader | Standards + precedent checks |
| `closer` | DMs knowledge-liaison for Phase 3 capture | Finalization learnings |
**Fallback behavior**: If vault routing cannot determine the best vault, agents use the first `ecosystem`-type vault or prompt the user.
### 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.
---
## Configuration Commands
- `/knowz register` - Create account and auto-configure first vault
- `/knowz setup` - Interactive vault setup
- `/knowzcode:status` - Check vault connection status
- `/knowz save "insight"` - Manually create learning (routes via knowz:writer if available, direct write otherwise) 
knowzcode/platform_adapters.md

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