knowzcode 0.1.0 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official KnowzCode plugin marketplace - Platform-agnostic AI development methodology",
-    "version": "0.1.0"
+    "version": "0.3.1"
   },
   "plugins": [
     {
       "name": "kc",
       "source": "./",
       "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-      "version": "0.1.0",
+      "version": "0.3.1",
       "author": {
         "name": "Alex Headscarf"
       },
@@ -42,9 +42,15 @@
         "./agents/builder.md",
         "./agents/reviewer.md",
         "./agents/closer.md",
+        "./agents/context-scout.md",
+        "./agents/knowz-scout.md",
         "./agents/microfix-specialist.md",
         "./agents/knowledge-migrator.md",
-        "./agents/update-coordinator.md"
+        "./agents/update-coordinator.md",
+        "./agents/knowz-scribe.md",
+        "./agents/security-officer.md",
+        "./agents/test-advisor.md",
+        "./agents/project-advisor.md"
       ],
       "skills": [
         "./skills/start-work.md",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kc",
   "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "author": {
     "name": "Alex Headscarf"
   }

package/README.md

@@ -2,13 +2,13 @@
 
 <div align="center">
 
-**Turn any AI coding assistant into a disciplined software engineer.**
+**A structured development methodology for AI coding assistants.**
 
 [![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT_+_Commons_Clause-yellow.svg)](LICENSE)
 [![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowzcode)
-[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/knowz-io/knowzcode/releases)
+[![Version](https://img.shields.io/badge/version-0.3.1-blue)](https://github.com/knowz-io/knowzcode/releases)
 
-[Installation](#installation) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)
+[Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)
 
 </div>
 
@@ -16,62 +16,78 @@
 
 ## The Problem
 
-AI coding assistants are powerful — they can read your entire codebase, write complex code, and understand requirements. But without structure, they forget context between sessions, make random changes without considering impact, declare "done" when they've only written code (not verified it), and let documentation drift from reality immediately.
-
-**KnowzCode fixes this.**
+AI coding assistants lack structure. Without it, they:
+- Forget context between sessions
+- Make changes without considering impact
+- Declare "done" without verifying anything works
+- Let documentation drift from reality immediately
 
 ## What KnowzCode Does
 
-KnowzCode is a **platform-agnostic development methodology** that lives in a `knowzcode/` directory inside your project. It gives any AI assistant a structured TDD workflow with quality gates, specifications, and session tracking — turning chaotic AI coding into systematic, verifiable software engineering.
+KnowzCode is a **platform-agnostic development methodology** that lives in your project's `knowzcode/` directory.
 
-- **5-Phase Development Loop** — Impact analysis → specs → TDD implementation → audit → finalization
+- **Adaptive Development Loop** — Scales from quick fixes to full 5-phase TDD workflows with quality gates at each phase
 - **Quality Gates** — Automated verification at each phase prevents broken code from advancing
 - **Living Documentation** — Architecture diagrams and specs auto-update as code changes
 - **Session Memory** — WorkGroups track complete context so nothing is lost between sessions
 - **Interruption Recovery** — Say "continue" to resume exactly where you left off
 - **Multi-Platform** — Works with Claude Code, Codex, Gemini, Cursor, Copilot, and Windsurf
 
+## When to Use KnowzCode
+
+KnowzCode adds overhead — more time, more tokens, more structure than letting your coding agent plan and execute natively. That's the tradeoff. Here's when it's worth it:
+
+**Your agent's native mode is fine for:**
+- Single-file changes, bug fixes, small refactors
+- Tasks where "good enough" is good enough
+- Anything you can verify at a glance
+
+**Reach for KnowzCode when:**
+- **Outcomes aren't meeting expectations** — the agent keeps missing edge cases, breaking things, or delivering incomplete work
+- **Multi-component changes** — features that touch multiple layers (API + DB + UI + tests) benefit from impact analysis and phased execution
+- **Architecture and security matter** — quality gates catch issues before they compound
+- **You need documentation that stays current** — specs and architecture docs update as part of the workflow, not as an afterthought
+- **Enforcing standards** — personal conventions, team guidelines, or enterprise compliance rules baked into every phase
+- **Resumability** — long-running work that spans sessions, where losing context means starting over
+- **Autonomous execution** — approve specs upfront, then let the agent run; verification loops and quality gates keep output on track without constant oversight
+
+The overhead pays for itself when the cost of getting it wrong exceeds the cost of being thorough.
+
 ## How It Works
 
 Every feature follows a structured loop with quality gates between phases:
 
 ```
- ┌─────────────────────────────────────────────────────────┐
- │                   THE KNOWZCODE LOOP                    │
- │                                                         │
- │  You provide a goal (e.g., "Add user authentication")   │
- │                        ↓                                │
- │  ┌──────────┐   ┌──────────┐   ┌──────────┐            │
- │  │ Phase 1A │──→│ Phase 1B │──→│ Phase 2A │            │
- │  │ Analyze  │   │ Specify  │   │ Build    │            │
- │  │ Impact   │   │ Design   │   │ with TDD │            │
- │  └──────────┘   └──────────┘   └──────────┘            │
- │       ↑              ↑              │                   │
- │   [approve]      [approve]          ↓                   │
- │                          ┌──────────┐   ┌──────────┐   │
- │                          │ Phase 2B │──→│ Phase 3  │   │
- │                          │ Audit    │   │ Finalize │   │
- │                          │ Quality  │   │ & Commit │   │
- │                          └──────────┘   └──────────┘   │
- │                               ↑                         │
- │                           [approve]                     │
- └─────────────────────────────────────────────────────────┘
+  ┌──────────────────── THE KNOWZCODE LOOP ────────────────────┐
+  │                                                             │
+  │  Goal → Analyze → ✓ → Design → ✓ → Build → Audit → ✓ → Ship  │
+  │         Impact        Specs        (TDD)    Quality         │
+  │          1A            1B           2A       2B        3    │
+  │                                                             │
+  │  ✓ = approval gate (you decide whether to proceed)         │
+  └─────────────────────────────────────────────────────────────┘
 ```
 
+KnowzCode automatically classifies tasks by complexity:
+- **Micro** — single-file fixes skip the loop entirely (`/kc:fix`)
+- **Light** — small changes (≤3 files) use a streamlined 2-phase path
+- **Full** — complex features get the complete 5-phase workflow above
+
 Each gate requires your approval before proceeding. See the [Workflow Reference](./docs/workflow-reference.md) for details.
 
 ## Installation
 
-### Claude Code (Plugin)
+### Claude Code (Recommended)
 
 ```bash
-/plugin marketplace add https://github.com/knowz-io/knowzcode
-/plugin install knowzcode
+/plugin marketplace add knowz-io/knowzcode
+/plugin install kc@knowzcode
 cd your-project/
 /kc:init
+/kc:work "Build user authentication"
 ```
 
-### npx (Any Platform)
+### Alternative: Script Install
 
 ```bash
 npx knowzcode                                    # Interactive setup
@@ -79,14 +95,22 @@ npx knowzcode install --platforms claude,cursor   # Specific platforms
 npx knowzcode install --platforms all             # All 6 platforms
 ```
 
+Commands available as `/work`, `/plan`, `/fix` (without `kc:` prefix).
+For `/kc:` prefix, also run: `/plugin install kc@knowzcode`.
+
+<details>
+<summary><strong>Supported Platforms (6)</strong></summary>
+
 | Platform | Instruction File | Support Level |
 |----------|-----------------|---------------|
-| Claude Code | `CLAUDE.md` | Full (agents + commands) |
-| OpenAI Codex | `AGENTS.md` | Adapter template |
-| Gemini CLI | `GEMINI.md` | Adapter template |
-| Cursor | `.cursor/rules/knowzcode.mdc` | Adapter template |
-| GitHub Copilot | `copilot-instructions.md` | Adapter template |
-| Windsurf | `.windsurf/rules/knowzcode.md` | Adapter template |
+| Claude Code | `CLAUDE.md` | Full support (plugin + agents + commands) |
+| Gemini CLI | `GEMINI.md` + `.gemini/commands/kc/*.toml` | Native `/kc:` commands + instruction file |
+| OpenAI Codex | `AGENTS.md` | Instruction file + SKILL.md format |
+| Cursor | `.cursor/rules/*.mdc` + `.cursor/commands/*.md` | Rules + commands (beta) |
+| GitHub Copilot | `.github/copilot-instructions.md` + `.github/prompts/kc-*.prompt.md` | Full support (instructions + 9 prompt files + MCP) |
+| Windsurf | `.windsurf/rules/*.md` + `.windsurf/workflows/*.md` | Rules + workflows |
+
+</details>
 
 ### Manual (No Node.js)
 
@@ -109,7 +133,7 @@ Connect to KnowzCode Cloud for vector-powered semantic search, AI Q&A, and learn
 /kc:work "Build user authentication with email and password"
 ```
 
-KnowzCode analyzes impact, generates specs, guides TDD implementation, verifies quality, and updates documentation — all with approval gates at each phase.
+Runs the full loop: impact analysis → specs → TDD → audit → finalize, with approval gates between each phase.
 
 ### Research First
 
@@ -117,7 +141,7 @@ KnowzCode analyzes impact, generates specs, guides TDD implementation, verifies
 /kc:plan "how is authentication implemented?"
 ```
 
-Spawns parallel research agents to explore your codebase. After investigation, say "implement" to transition into `/kc:work` with findings pre-loaded.
+Explores your codebase first. Say "implement" to transition into `/kc:work` with findings pre-loaded.
 
 ### Quick Fix
 
@@ -129,19 +153,19 @@ Targeted fixes that skip the full loop — for typos, small bugs, and CSS tweaks
 
 ## Commands
 
-| Command | Description | Example |
-|:--------|:------------|:--------|
-| `/kc:init` | Initialize KnowzCode in project | `/kc:init` |
-| `/kc:work <goal>` | Start feature workflow | `/kc:work "Add dark mode"` |
-| `/kc:plan <topic>` | Research before implementing | `/kc:plan "how does auth work?"` |
-| `/kc:audit [type]` | Run quality audits | `/kc:audit security` |
-| `/kc:fix <target>` | Quick targeted fix | `/kc:fix auth.js` |
-| `/kc:connect-mcp` | Configure MCP server | `/kc:connect-mcp <api-key>` |
-| `/kc:register` | Register and configure MCP | `/kc:register` |
-| `/kc:status` | Check MCP connection | `/kc:status` |
-| `/kc:learn` | Capture learnings to vault | `/kc:learn "insight"` |
-| `/kc:telemetry` | Investigate production telemetry | `/kc:telemetry "error 500"` |
-| `/kc:telemetry-setup` | Configure telemetry sources | `/kc:telemetry-setup` |
+| Command | Description |
+|:--------|:------------|
+| `/kc:init` | Initialize KnowzCode in project |
+| `/kc:work <goal>` | Start feature workflow |
+| `/kc:plan <topic>` | Research before implementing |
+| `/kc:audit [type]` | Run quality audits |
+| `/kc:fix <target>` | Quick targeted fix |
+| `/kc:connect-mcp` | Configure MCP server |
+| `/kc:register` | Register and configure MCP |
+| `/kc:status` | Check MCP connection |
+| `/kc:learn` | Capture learnings to vault |
+| `/kc:telemetry` | Investigate production telemetry |
+| `/kc:telemetry-setup` | Configure telemetry sources |
 
 ## Architecture
 
@@ -159,7 +183,92 @@ Layer 1: Core Methodology (platform-agnostic, the actual product)
          knowzcode/ directory → loop, specs, tracker, architecture
 ```
 
-The real product is Layer 1 — the `knowzcode/` directory. Everything else enhances it. See [Understanding KnowzCode](./docs/understanding-knowzcode.md) for a deep dive.
+The real product is Layer 1 — the `knowzcode/` directory. Everything else enhances it.
+On Claude Code, Layer 4 provides 14 specialized agents (11 core + 3 opt-in specialists) with parallel orchestration.
+On other platforms, the AI follows the same methodology directly.
+See [Understanding KnowzCode](./docs/understanding-knowzcode.md) for a deep dive.
+
+## Execution Modes
+
+### Claude Code
+
+When using Claude Code, `/kc:work` automatically selects an execution strategy based on task complexity and available features:
+
+| Mode | When Used | How It Works |
+|------|-----------|-------------|
+| **Parallel Teams** | Complex features (default for >3 files) | Multiple agents work concurrently — scouts gather context, builders implement in parallel, reviewer audits incrementally |
+| **Sequential Teams** | Lighter features or `--sequential` flag | One agent per phase with persistent team context |
+| **Subagent Delegation** | Agent Teams not enabled | One agent spawned per phase via fallback — works on all Claude Code instances |
+
+<details>
+<summary><strong>Agent Teams Setup & Roster (14 agents)</strong></summary>
+
+Parallel and Sequential Teams require [Agent Teams (experimental)](https://code.claude.com/docs/en/agent-teams). Enable by adding the following to your Claude Code `settings.json`:
+
+```json
+{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
+```
+
+Or ask Claude Code: _"Enable Agent Teams in my settings."_ Then restart. Without it, subagent delegation is used automatically.
+
+| Agent | Role | Phase |
+|-------|------|-------|
+| `context-scout` | Local context research (specs, tracker, history) | Discovery |
+| `knowz-scout` | MCP vault research (conventions, decisions) | Discovery |
+| `knowz-scribe` | MCP vault writes (learning capture, audit trails) | All phases |
+| `analyst` | Impact analysis, Change Set proposals | 1A |
+| `architect` | Specification drafting, architecture review | 1B |
+| `builder` | TDD implementation, verification loops | 2A |
+| `reviewer` | Quality audit, security review | 2B |
+| `closer` | Finalization, learning capture | 3 |
+| `security-officer` | Threat modeling, vulnerability scanning (opt-in) | All phases |
+| `test-advisor` | TDD enforcement, test quality review (opt-in) | All phases |
+| `project-advisor` | Backlog curation, future work ideas (opt-in) | Discovery–2A |
+| `microfix-specialist` | Quick targeted fixes | Utility |
+| `knowledge-migrator` | Knowledge migration between vaults | Utility |
+| `update-coordinator` | Plugin update coordination | Utility |
+
+</details>
+
+<details>
+<summary><strong>Opt-in Specialist Agents</strong></summary>
+
+Activate specialists with `--specialists` in `/kc:work` or `/kc:audit`:
+
+```bash
+/kc:work "Build auth system" --specialists              # All 3 specialists
+/kc:work "Build auth system" --specialists=security     # Security officer only
+/kc:audit --specialists                                 # Deep audit with specialists
+```
+
+- **security-officer**: Officer authority — CRITICAL/HIGH findings block gates
+- **test-advisor**: Advisory — TDD compliance, assertion quality, coverage gaps
+- **project-advisor**: Advisory — backlog ideas, tech debt tracking (shuts down mid-implementation)
+
+Specialists communicate directly with builders (max 2 DMs each) and report findings at quality gates. Supported in Parallel Teams and Subagent modes only.
+
+</details>
+
+See the [Workflow Reference](./docs/workflow-reference.md) for detailed orchestration flows.
+
+### GitHub Copilot
+
+Copilot users invoke phases via prompt files in VS Code Copilot Chat:
+
+```bash
+#prompt:kc-work "Build JWT authentication"  # Start feature workflow
+#prompt:kc-specify                          # Draft specs (after Change Set approved)
+#prompt:kc-implement                        # TDD implementation
+#prompt:kc-audit                            # READ-ONLY audit
+#prompt:kc-finalize                         # Finalize and commit
+#prompt:kc-continue                         # Resume where you left off
+```
+
+Generated by `/kc:init` into `.github/prompts/`. See `knowzcode/copilot_execution.md` for details.
+
+### Other Platforms
+
+Gemini, Cursor, Codex, and Windsurf follow the same methodology phases sequentially — the AI reads prompt templates from `knowzcode/prompts/` and follows the same quality gates. No agent orchestration is needed.
 
 ## Project Structure
 
@@ -174,33 +283,21 @@ your-project/
     ├── specs/                     # Component specifications
     ├── prompts/                   # Phase prompt templates (works with any AI)
     ├── workgroups/                # Session data (gitignored)
-    └── enterprise/                # Optional compliance config
+    └── enterprise/                # Optional compliance config (gitignored, experimental)
 ```
 
-**Committed to git:** `knowzcode/*.md`, `knowzcode/specs/`, `knowzcode/prompts/`
-**Gitignored:** `knowzcode/workgroups/`, `knowzcode/environment_context.md`, `knowzcode/*.local.md`
-
 ## Documentation
 
 | Guide | Description |
 |:------|:------------|
-| [Getting Started](./docs/knowzcode_getting_started.md) | Complete walkthrough, MCP setup, migration |
-| [Understanding KnowzCode](./docs/understanding-knowzcode.md) | Deep dive into concepts and architecture |
-| [Workflow Reference](./docs/workflow-reference.md) | Phase details, agent delegation, parallel execution |
-| [Prompts Guide](./docs/knowzcode_prompts_guide.md) | All prompts and command reference |
-| [Visual Guide](./docs/knowzcode_guide.md) | File structure roadmap |
-| [Developer Guide](./CLAUDE.md) | Plugin development documentation |
+| [Getting Started](./docs/knowzcode_getting_started.md) | Walkthrough, MCP setup, file structure |
+| [Understanding KnowzCode](./docs/understanding-knowzcode.md) | Concepts and architecture deep dive |
+| [Workflow Reference](./docs/workflow-reference.md) | Phase details, execution modes, parallel orchestration |
+| [Prompts Guide](./docs/knowzcode_prompts_guide.md) | Prompt templates and command reference |
 
 ## Contributing
 
-We welcome contributions!
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing`
-3. Make changes and test thoroughly
-4. Submit a pull request
-
-See **[CLAUDE.md](CLAUDE.md)** for developer documentation.
+Fork → branch → PR. See **[CLAUDE.md](CLAUDE.md)** for developer docs.
 
 ## Acknowledgments
 
@@ -214,7 +311,7 @@ MIT License with Commons Clause — See [LICENSE](LICENSE) file for details.
 
 <div align="center">
 
-**Turn any AI coding assistant into a disciplined software engineer.**
+**A structured development methodology for AI coding assistants.**
 
 [Get Started](#installation) · [Read the Docs](#documentation) · [Contribute](#contributing)
 

package/agents/analyst.md

@@ -18,28 +18,11 @@ Analyze the codebase to understand what needs to change for the given goal, then
 
 ## NodeID Classification Rules
 
-NodeIDs must be **domain concepts**, not tasks.
+Follow the NodeID naming conventions in `knowzcode_loop.md` section 3.1. Key rules:
 
-### Default: Domain-Area Names (PascalCase)
-
-| Pattern | Examples | Covers |
-|---------|----------|--------|
-| `Authentication` | login form, auth endpoint, token service | All auth components |
-| `FileManagement` | files tab, blob proxy, PDF worker | All file handling |
-| `Checkout` | cart, orders, payment | All purchase flow |
-
-Sub-areas when a domain grows large: `Authentication_OAuth`, `Payments_Stripe`
-
-### Exception: Utility/Config NodeIDs
-
-| Prefix | Examples |
-|--------|----------|
-| `LIB_` | `LIB_DateFormat`, `LIB_Validation` |
-| `CONFIG_` | `CONFIG_FeatureFlags` |
-
-### Invalid NodeIDs (Never Use)
-
-`FIX-001`, `UI-FIX-002`, `TASK-123`, `FEATURE-X` — tasks belong in WorkGroup files, not as NodeIDs.
+- NodeIDs must be **domain concepts** (PascalCase), not tasks
+- Use `LIB_` prefix for isolated utilities, `CONFIG_` for configuration
+- Never use task-oriented names: `FIX-001`, `TASK-X`, `FEATURE-Y`
 
 ## Consolidation-First Mindset
 
@@ -53,31 +36,12 @@ Before proposing ANY new NodeID:
 
 - One NodeID per new capability, not per file modified
 - Files that use/integrate a capability are "affected files" — no NodeID needed
-- Ask: "Is this creating NEW functionality?" If yes, NodeID. If just integrating, affected file.
-
-## Change Set Format
-
-```markdown
-## Change Set for WorkGroup [ID]
-
-### New Capabilities (NodeIDs)
-| NodeID | Description |
-|--------|-------------|
-| LIB_DateTimeFormat | Timezone formatting utility |
-
-### Affected Files (no NodeIDs needed)
-- JobsPage.tsx - integrate formatDateTime
-- IntakeJobsPage.tsx - integrate formatDateTime
-
-**Specs Required**: 1
-```
 
 ## Historical Context
 
 Before analyzing impact:
 1. Scan `knowzcode/workgroups/` for completed WorkGroups touching similar features
-2. Extract implementation patterns, decisions, and lessons learned
-3. Reference relevant context in your Change Set proposal
+2. Reference relevant context in your Change Set proposal
 
 ## Smart Scanning Strategy
 
@@ -88,34 +52,32 @@ Before analyzing impact:
 
 ## MCP Integration (Optional)
 
-If MCP is configured, enhance your analysis with vault queries:
-
-- `search_knowledge(research_vault, "past decisions about {domain}")` — find relevant architectural decisions
-- `search_knowledge(code_vault, "{affected_component} implementation")` — find related code patterns
-- `ask_question(research_vault, "conventions for {domain}?")` — check team conventions
+If MCP is configured:
+- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
+- `search_knowledge({vault matching "ecosystem" type}, "past decisions about {domain}")` — find relevant architectural decisions
+- `search_knowledge({vault matching "code" type}, "{affected_component} implementation")` — find related code patterns
 
-If MCP is not available, use standard grep/glob — works fine. All analysis works without MCP.
-
-## MCP Learning (Optional)
-
-After Change Set is approved, if MCP is configured:
-- `create_knowledge(research_vault, title="Scope: {goal}", tags=["scope", "change-set"])`
-  with NodeIDs, risk assessment, and user-approved boundaries
-- Skip if MCP unavailable — this is enhancement only
+If MCP is not available, use standard grep/glob. All analysis works without MCP.
 
 ## Exit Expectations
 
-- Produce a complete Change Set with NodeIDs and spec status
+- Produce a complete Change Set (format defined in `knowzcode_loop.md` section 3.1)
 - Flag nodes requiring new specs as `[NEEDS_SPEC]`
 - Include risk assessment and historical context
+- Include dependency map (see below) when running in Parallel Teams mode
 - Present to user for approval
 
-## Multi-Agent Coordination
+## Dependency Map (Parallel Teams)
+
+When running in Parallel Teams mode, include a dependency map in your Change Set:
 
-When running in a multi-agent workflow:
-- Your Change Set output feeds into the architect for spec drafting
-- Clarify scope with the architect if NodeIDs overlap with existing specs
-- Answer the builder's questions about affected files and dependencies
-- Answer the reviewer's questions about change scope
+### NodeID Dependencies & Parallelism
+| NodeID | Depends On | Shared Files With | Parallel Group |
+|--------|-----------|-------------------|----------------|
+| {id} | {deps or "none"} | {other NodeIDs sharing files} | {group number} |
 
-For Claude Code Agent Teams behavior, see `knowzcode/claude_code_execution.md`.
+Rules:
+- Two NodeIDs that share ANY affected file must be in the SAME parallel group
+- NodeIDs with no shared files can be in different groups
+- Mark sequential dependencies (NodeID-B requires NodeID-A's output)
+- The lead uses this to partition work across builders

package/agents/architect.md

@@ -33,31 +33,9 @@ Specs are **lean decision records + contracts** — quick reference documents ca
 - Data structure definitions (unless there's a decision to document)
 - Error handling catalogs (capture via `VERIFY:` statements instead)
 
-## The 4-Section Template
+## Spec Format
 
-```markdown
-# {NodeID}: {Human-Readable Name}
-
-**Updated:** {timestamp}
-**Status:** Draft | Approved | As-Built
-
-## Rules & Decisions
-- Decision: chose X over Y because Z
-- Rule: must always validate before persisting
-
-## Interfaces
-- POST /api/users -> { id, email }
-- Depends on: AuthService for token validation
-
-## Verification Criteria
-- VERIFY: when valid credentials, returns JWT token
-- VERIFY: when email exists, returns 409
-
-## Debt & Gaps
-- TODO: add rate limiting
-```
-
-**Minimum valid spec:** 1+ Rules item, 1+ Interface item, 2+ `VERIFY:` statements.
+Use the 4-section template defined in `knowzcode_loop.md` section 3.2. **Minimum valid spec:** 1+ Rules item, 1+ Interface item, 2+ `VERIFY:` statements.
 
 ## Consolidation Mandate
 
@@ -75,47 +53,81 @@ When assessing architectural impact:
 - Flag pattern violations and consistency concerns
 - Verify flowchart alignment with `knowzcode/knowzcode_architecture.md`
 
-### Architecture Assessment Output
+### Architecture Health Report
+
+Provide a structured Architecture Health Report at each quality gate. This is a first-class gate deliverable. When specialists are active, the lead includes your Architecture Health Report in the Specialist Reports section at each gate.
+
+**Gate #1 (Change Set Approval)** — Architecture impact assessment:
+```markdown
+**Architect — Architecture Health Report (Gate #1):**
+- Impact Scope: {layers touched, components affected}
+- Coupling Concerns: {new dependencies, tight coupling risks}
+- Pattern Alignment: {matches existing patterns / introduces new pattern / deviates}
+- Recommendation: {proceed / adjust scope}
+```
 
+**Gate #2 (Specification Approval)** — Spec architecture review:
 ```markdown
-**Architecture Assessment:**
-- Alignment: {HIGH/MEDIUM/LOW}
+**Architect — Architecture Health Report (Gate #2):**
+- Spec-Architecture Alignment: {specs follow documented patterns / drift concerns}
 - Layer Violations: {list or None}
-- Pattern Concerns: {list or None}
-- Drift Detected: {list or None}
+- Consistency: {specs are internally consistent / conflicts between NodeID-X and NodeID-Y}
+- Recommendation: {proceed / revise specs}
 ```
 
+**Gate #3 (Audit Results)** — Implementation architecture audit:
+```markdown
+**Architect — Architecture Health Report (Gate #3):**
+- Drift: {Yes/No — implementation matches spec intent}
+- Pattern Violations: {count} — {list or None}
+- Layer Health: {all layers respected / violations in {list}}
+- Recommendation: {proceed / fix drift}
+```
+
+## During Implementation (Parallel Teams — Consultative Role)
+
+When builders are implementing, you persist as a read-only consultative resource:
+
+### What To Do
+- Respond to builder DMs about spec intent and design decisions
+- Clarify interface contracts and expected behavior
+- Flag architectural concerns if implementation drifts from spec intent
+- Advise on `[SPEC_ISSUE]` flags raised by builders
+
+### What NOT To Do
+- Write code or modify source files
+- Modify specs (spec changes require a new gate approval cycle)
+- Create tasks or assign work
+- Block builders — respond promptly, don't gatekeep
+
+### Proactive Availability
+When notified that builders are spawning, send a brief intro to each builder:
+> I'm the architect for this WorkGroup. DM me if you need clarification on spec intent, interface contracts, or design decisions.
+
 ## Enterprise Compliance (Optional)
 
 If `knowzcode/enterprise/compliance_manifest.md` exists and `compliance_enabled: true`:
 - Merge guideline criteria into Verification Criteria as `VERIFY:` statements
-- Address required concerns in Rules & Decisions
 - Flag blocking vs advisory compliance issues
 
 ## MCP Integration (Optional)
 
-If MCP is configured, enhance your spec drafting with vault queries:
-
-- `ask_question(research_vault, "conventions for {component_type}?")` — check team conventions before drafting
-- `search_knowledge(research_vault, "{NodeID_domain} patterns")` — find related patterns and prior decisions
-- `search_knowledge(code_vault, "{component_type} implementation")` — find implementation examples to inform interfaces
+If MCP is configured:
+- Read `knowzcode/knowzcode_vaults.md` to resolve vault IDs by type
+- `ask_question({vault matching "ecosystem" type}, "conventions for {component_type}?")` — check team conventions
+- `search_knowledge({vault matching "ecosystem" type}, "{NodeID_domain} patterns")` — find related patterns
+- `search_knowledge({vault matching "ecosystem" type}, "{component_type} integration context")` — find integration patterns
 
-If MCP is not available, use grep/glob and read existing specs directly. All spec drafting works without MCP.
+If MCP is not available, use grep/glob. All spec drafting works without MCP.
 
 ## Exit Expectations
 
-- All specs use the 4-section format
-- Each spec has 2+ `VERIFY:` statements
+### After Specification (Gate #2)
+- All specs use the 4-section format with 2+ `VERIFY:` statements
 - Tracker statuses updated
 - Present specs to user for approval
 
-## Multi-Agent Coordination
-
-When running in a multi-agent workflow:
-- Receive the approved Change Set from the analyst
-- Clarify scope with the analyst if NodeIDs need adjustment
-- Answer the builder's questions about spec intent and design decisions
-- Answer the reviewer's questions about expected behavior
-- Notify the closer about spec format and any legacy specs needing migration
-
-For Claude Code Agent Teams behavior, see `knowzcode/claude_code_execution.md`.
+### After Implementation (Gate #3 — Parallel Teams only)
+- All builder spec-clarification questions answered
+- `[SPEC_ISSUE]` flags reviewed and addressed
+- No outstanding architectural concerns from implementation review