knowzcode 0.2.1 → 0.3.3

package/knowzcode/claude_code_execution.md

@@ -146,7 +146,8 @@ Use mailbox messaging for coordination between teammates:
 | From | To | When |
 |------|-----|------|
 | scout | all | Initial context/vault findings (broadcast) |
-| analyst | architect | Scope clarifications, NodeID overlap with existing specs |
+| scanner | all | Codebase scan findings — affected files, test patterns (broadcast) |
+| analyst | architect | `[PRELIMINARY]` NodeID findings during Stage 0 (max 3 DMs), scope clarifications, NodeID overlap with existing specs |
 | architect | analyst | Scope adjustments needed |
 | architect | builder | Design guidance and spec intent responses |
 | builder | analyst | Affected files and dependency questions |
@@ -159,6 +160,16 @@ Use mailbox messaging for coordination between teammates:
 | closer | knowz-scribe | Phase 3 learning capture (`"Capture Phase 3: {wgid}"`) |
 | closer | analyst | Change scope for log entry accuracy |
 | closer | architect | Spec format and legacy migration |
+| security-officer | lead | Structured finding reports at gates (with `[SECURITY-BLOCK]` for CRITICAL/HIGH) |
+| security-officer | architect | Security VERIFY criteria needs during Phase 1B |
+| security-officer | builder | Security guidance for sensitive partitions (max 2 DMs per builder) |
+| security-officer | test-advisor | Cross-cutting: test gaps in security-critical paths (max 2 inter-specialist DMs) |
+| test-advisor | lead | Test quality reports at gates |
+| test-advisor | architect | VERIFY criteria testability concerns during Phase 1B |
+| test-advisor | builder | Specific test improvement feedback (max 2 DMs per builder) |
+| test-advisor | security-officer | Cross-cutting: security scenarios needing test coverage (max 2 inter-specialist DMs) |
+| project-advisor | lead | Backlog context (Stage 0) and proposals (late Stage 2) |
+| project-advisor | knowz-scribe | Idea captures for vault storage |
 
 ### Gap Communication Flow
 In Parallel Teams mode, gap communication goes through the lead:
@@ -207,12 +218,18 @@ Agents must NOT create new tasks for work already assigned to them via task ID.
 | context-scout-specs | Stage 0 | After Gate #2 | Spec context lookups |
 | context-scout-workgroups | Stage 0 | After Gate #2 | WorkGroup history lookups |
 | context-scout-backlog | Stage 0 | After Gate #2 | Tracker/log/architecture lookups |
+| scanner-direct | Stage 0 (conditional) | After Stage 1 (analyst done) | Source code scanning — broadcasts affected files and code paths |
+| scanner-tests | Stage 0 (conditional) | After Stage 1 (analyst done) | Test discovery — broadcasts test patterns and coverage shape |
 | knowz-scout | Stage 0 | After Phase 3 capture | Vault queries (read-only) throughout workflow |
 | knowz-scribe | Stage 0 | After Phase 3 capture | Vault writes — receives capture messages, handles all `create_knowledge` calls |
 | analyst | Stage 0 | Early Stage 2 | Scope questions from builders |
-| architect | Stage 0 (pre-load) | After Gate #3 | Spec clarifications + design guidance for builders throughout Stage 2 |
+| architect | Stage 0 (pre-load + speculative research) | After Gate #3 | Pre-load → speculative research on `[PRELIMINARY]` NodeIDs → spec drafting (+ parallel coordination for 3+ NodeIDs) → design guidance for builders |
+| spec-drafter(s) | Stage 1 (Path B, 3+ NodeIDs) | After architect consistency review | Draft specs for assigned NodeID partition |
 | builder(s) | Stage 2 | After Gate #3 | Implementation + gap fixes (persistent through gap loop) |
 | reviewer(s) | Stage 2 (1 per builder partition) | After Gate #3 | Incremental audit per partition (persistent through gap loop) |
+| security-officer | Stage 0 (Group C) | After Gate #3 | Threat modeling + vulnerability scanning (officer — can block gates) |
+| test-advisor | Stage 0 (Group C) | After Gate #3 | TDD enforcement + test quality review (advisor — informational) |
+| project-advisor | Stage 0 (Group C) | Mid-Stage 2 | Backlog curation + idea capture (advisor — informational) |
 | closer | Stage 3 | End of workflow | Finalization |
 
 ### Task Dependency Usage
@@ -224,16 +241,31 @@ All tasks in a workflow use `addBlockedBy` to express the dependency chain:
 
 ### Task Graph Patterns
 
-- Stage 0 tasks: scout + knowz-scribe + analysis tasks (no deps)
-- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate)
+- Stage 0 tasks: scout + scanner + knowz-scribe + analysis tasks (no deps)
+- Stage 1 tasks: spec drafting tasks (blocked by gate approval — lead creates after gate). Path B (3+ NodeIDs): spec-drafter tasks + architect consistency review task
 - Stage 2 tasks: implementation subtasks (blocked by spec approval), audit subtasks (blocked by implementation)
 - Stage 3 tasks: finalization (blocked by audit approval)
 
+### Orchestration Configuration
+
+Team sizing defaults are configurable via `knowzcode/knowzcode_orchestration.md`:
+
+| Parameter | Default | Flag Override | Effect |
+|-----------|---------|--------------|--------|
+| `max_builders` | 5 | `--max-builders=N` | Cap concurrent builders (1-5) |
+| `scout_mode` | full | `--no-scouts` | full (3 scouts), minimal (1 scout), none (lead reads context) |
+| `default_specialists` | [] | `--specialists`, `--no-specialists` | Project-level specialist defaults |
+| `mcp_agents_enabled` | true | `--no-mcp` | Toggle vault agents (knowz-scout, knowz-scribe) |
+| `codebase_scanner_enabled` | true | `--no-scanners` | Toggle codebase scanner agents (scanner-direct, scanner-tests) |
+| `parallel_spec_threshold` | 3 | `--no-parallel-specs` | NodeID count threshold for parallel spec drafting (Path B) |
+
+Precedence: hardcoded defaults → orchestration config → per-invocation flags.
+
 ### Builder Partitioning Rules
 
 - No two builders touch the same file
 - Analyst dependency map determines partitions
-- Max 5 concurrent builders
+- Max `MAX_BUILDERS` concurrent builders (default 5, configurable in `knowzcode_orchestration.md`)
 - If all NodeIDs share files → single builder with subtask tracking
 - Builder-to-builder messages for interface changes affecting other partitions
 
@@ -258,11 +290,60 @@ During Stage 2, the architect persists as a read-only consultative resource:
 - Lead notifies architect when builders are spawned — architect sends intro message to each builder
 - Shut down with builders and reviewers after Gate #3
 
-#### Discovery Pre-loading
-During Stage 0, the architect pre-loads context in parallel with analysis:
-- Architect reads architecture docs, existing specs, project config
-- When Gate #1 is approved, architect already has context → specs drafted faster
-- If Gate #1 rejected, architect context is still useful for the revised analysis cycle
+#### Discovery Pre-loading + Speculative Research
+During Stage 0, the architect pre-loads context and conducts speculative research in parallel with analysis:
+- **Pre-load phase**: Architect reads architecture docs, existing specs, project config (3-5 turns)
+- **Speculative research phase**: After pre-load, architect receives `[PRELIMINARY]` NodeID messages from the analyst (max 3). For each, it reads affected files, checks spec consolidation, and analyzes interface patterns — all read-only, no spec writing
+- When Gate #1 is approved, architect already has context + deep research on flagged NodeIDs → specs drafted ~80% faster
+- If Gate #1 rejected, architect context and research are still useful for the revised analysis cycle
+- If no `[PRELIMINARY]` messages arrive (simple 1-NodeID change), architect finishes standard pre-load and waits
+
+#### Parallel Spec Drafting (Path B — 3+ NodeIDs)
+When the approved Change Set contains 3+ NodeIDs (configurable via `PARALLEL_SPEC_THRESHOLD`), spec drafting is parallelized:
+- Architect proposes NodeID partitions (1-2 per partition, max 3 partitions)
+- Lead spawns spec-drafter agents (using `architect` agent definition) for each partition
+- Each drafter receives: its NodeIDs, architect's speculative research findings, cross-NodeID constraints
+- After all drafters complete, architect runs a consistency review: cross-spec alignment, naming, VERIFY coverage
+- Spec-drafters shut down after consistency review, before Gate #2
+- For 1-2 NodeIDs (Path A), architect drafts all specs alone (current behavior, zero overhead)
+
+#### Specialist Agents (Group C — opt-in via `--specialists`)
+
+When specialists are enabled, three additional agents spawn at Stage 0 alongside Groups A and B:
+
+```
+Group A (always):           3 context-scouts + analyst + architect       (5 agents)
+Group A (if scanners):      + scanner-direct + scanner-tests            (+2 agents)
+Group B (if MCP):           knowz-scout + knowz-scribe                  (2 agents)
+Group C (if --specialists): security-officer + test-advisor + project-advisor  (3 agents)
+```
+
+Max Stage 0 concurrent: 5-12 agents depending on orchestration config (scouts, scanners, MCP agents, specialists). Scouts shut down after Gate #2, scanners shut down after Stage 1, so Stage 2 peak is manageable.
+
+##### Officer vs Advisor Authority
+
+| Role | Authority | Gate Impact |
+|------|-----------|-------------|
+| **Officer** (security-officer) | CRITICAL/HIGH findings block gates | `[SECURITY-BLOCK]` tag pauses autonomous mode |
+| **Advisor** (test-advisor, project-advisor) | Informational only | Findings included in gate reports, do not block |
+
+##### Direct DM Protocol
+
+Specialists communicate directly with builders, architect, and each other — no lead bottleneck relay:
+
+- **security-officer → architect**: Security VERIFY criteria needs during Phase 1B
+- **security-officer → builder-N**: Security guidance for sensitive partitions (max 2 DMs per builder)
+- **test-advisor → architect**: VERIFY criteria testability concerns during Phase 1B
+- **test-advisor → builder-N**: Specific test improvement feedback (max 2 DMs per builder)
+- **project-advisor → knowz-scribe**: Idea captures for vault storage
+- **security-officer ↔ test-advisor**: Cross-cutting test gaps in security paths (max 2 inter-specialist DMs total)
+
+##### Communication Discipline
+
+- Max 2 DMs to any individual builder from each specialist
+- Max 2 inter-specialist DMs per workflow
+- Consolidate findings — no per-file noise
+- project-advisor does NOT DM builders or other specialists (observes via task list only)
 
 ---
 

package/knowzcode/copilot_execution.md

@@ -0,0 +1,231 @@
+# Copilot Execution Model
+
+**Purpose:** Defines the execution model for GitHub Copilot users. Copilot operates as a single-agent, sequential platform — users manually transition between phases using prompt files.
+
+Agents on other platforms should ignore this file — see `knowzcode/platform_adapters.md` for platform-specific instructions, or `knowzcode/claude_code_execution.md` for Claude Code Agent Teams.
+
+---
+
+## Execution Model Overview
+
+Copilot uses a **single-agent, user-driven** execution model:
+
+- One AI assistant handles all phases sequentially
+- The user invokes each phase via `#prompt:kc-*` prompt files in VS Code
+- Quality gates are enforced by STOP instructions — the AI pauses and waits for user direction
+- Context carries between phases via WorkGroup files in `knowzcode/workgroups/`
+- No multi-agent orchestration, no inter-agent messaging, no task dependency tracking
+
+This is equivalent to the "Sequential Execution Protocol" described in `knowzcode/knowzcode_loop.md` Section 8.
+
+---
+
+## Prompt File Workflow
+
+### Phase Sequence
+
+```
+#prompt:kc-work "goal"
+  → Creates WorkGroup, classifies tier, Phase 1A analysis, proposes Change Set
+  → STOP — await user approval
+
+#prompt:kc-specify
+  → Reads WorkGroup, drafts specs for approved Change Set
+  → STOP — await user approval, then commits specs
+
+#prompt:kc-implement
+  → Reads WorkGroup + specs, TDD Red-Green-Refactor
+  → STOP — report implementation results
+
+#prompt:kc-audit
+  → READ-ONLY audit against VERIFY statements
+  → STOP — report gaps, await user decision
+
+#prompt:kc-finalize
+  → Updates specs to as-built, tracker, log, architecture check, commits
+```
+
+### Shortcut Workflows
+
+| Prompt | Use Case |
+|--------|----------|
+| `#prompt:kc-fix "description"` | Single-file, <50 line fixes — skip the full loop |
+| `#prompt:kc-plan "topic"` | Research and investigation before implementing |
+| `#prompt:kc-continue` | Resume interrupted work or advance to next phase |
+| `#prompt:kc-analyze` | Re-run Phase 1A on an existing WorkGroup |
+
+### Prompt File Location
+
+All prompt files live in `.github/prompts/` and are generated by `/kc:init` (or `npx knowzcode`). They use YAML frontmatter with `agent: "agent"` for file editing capability.
+
+---
+
+## VS Code Agent Mode
+
+Copilot prompt files with `agent: "agent"` in their frontmatter enable agent mode, which allows:
+
+- File creation and editing
+- Terminal command execution (tests, builds, linting)
+- Multi-file changes in a single session
+
+All KnowzCode prompt files use `agent: "agent"` for TDD implementation, spec writing, and WorkGroup file updates.
+
+### Using Prompt Files
+
+In VS Code Copilot Chat:
+1. Type `#prompt:kc-work` to invoke the workflow prompt
+2. Add your goal as the chat message: `#prompt:kc-work "Build JWT authentication"`
+3. Copilot loads the prompt file, pulls in `#file:` referenced context, and executes
+
+### Adding Extra Context
+
+You can add files to the prompt context manually:
+- Reference files in chat: `#file:src/auth/login.ts`
+- The prompt files already include `#file:` references for core KnowzCode files
+
+---
+
+## Copilot CLI Usage
+
+The Copilot CLI does not support `#prompt:` syntax. Check the current CLI documentation for the exact file reference syntax — it may differ from VS Code's `#file:` references.
+
+Alternatively, paste the goal and reference the methodology directly in the CLI prompt. The CLI provides the same AI capabilities but without the `#prompt:` shorthand.
+
+---
+
+## Copilot Coding Agent Integration
+
+The GitHub Copilot Coding Agent (cloud-based, triggered from GitHub Issues) follows `copilot-instructions.md` automatically when working on repository issues.
+
+### Behavior
+
+When the Coding Agent picks up an issue:
+1. Reads `.github/copilot-instructions.md` for methodology
+2. Follows Phase 1A→3 workflow for non-trivial changes
+3. Includes the Change Set in the PR description
+4. Uses TDD — failing test before implementation code
+5. Self-audits against spec VERIFY statements
+
+### Key Differences from Interactive Use
+
+| Aspect | Interactive (VS Code) | Coding Agent (GitHub) |
+|--------|----------------------|----------------------|
+| Phase transitions | User invokes each `#prompt:kc-*` | Agent runs all phases autonomously |
+| Quality gates | STOP and wait for user | Deferred to PR review |
+| Prompt files | Used via `#prompt:` | Not used — follows `copilot-instructions.md` |
+| Approval | Interactive at each gate | PR reviewers approve |
+
+### PR Description Format
+
+The Coding Agent should structure PR descriptions to reflect the KnowzCode workflow:
+
+```markdown
+## Change Set
+- NodeID: Description
+- Affected files: list
+
+## Specs
+- Link to spec files created/updated
+
+## Verification
+- Test results summary
+- Self-audit completion percentage
+```
+
+---
+
+## MCP Configuration for VS Code
+
+To enable vault access in Copilot, configure `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "knowzcode": {
+      "type": "http",
+      "url": "${input:knowzcode_mcp_url}",
+      "headers": {
+        "x-api-key": "${input:knowzcode_api_key}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "knowzcode_mcp_url",
+      "description": "KnowzCode MCP server URL",
+      "type": "promptString"
+    },
+    {
+      "id": "knowzcode_api_key",
+      "description": "KnowzCode API key",
+      "type": "promptString",
+      "password": true
+    }
+  ]
+}
+```
+
+MCP provides `search_knowledge`, `ask_question`, and `create_knowledge` tools for vault access. All prompt files work without MCP — it enhances context but never blocks.
+
+---
+
+## Model Selection Guidance
+
+| Phase | Recommended Model | Rationale |
+|-------|------------------|-----------|
+| 1A: Analysis | Claude Opus / GPT-4o | Complex reasoning about impact and scope |
+| 1B: Specification | Claude Opus / GPT-4o | Structured spec drafting requires depth |
+| 2A: Implementation | Any capable model | Code generation — Sonnet/GPT-4o sufficient |
+| 2B: Audit | Claude Opus / GPT-4o | Critical evaluation requires strong reasoning |
+| 3: Finalization | Any capable model | Mostly doc updates and formatting |
+| Quick fix | Any model | Simple, scoped changes |
+
+VS Code allows model selection per chat session. For complex features, prefer stronger models for analysis and audit phases.
+
+---
+
+## Limitations and Workarounds
+
+| Limitation | Impact | Workaround |
+|-----------|--------|------------|
+| No multi-agent orchestration | Cannot run parallel analysis/implementation | Sequential phase execution via prompt files |
+| No inter-agent messaging | No scout/scribe delegation | Single agent reads all context directly |
+| No task dependency tracking | No automated phase progression | User manually invokes next prompt |
+| No persistent agents | Context reloaded each prompt invocation | WorkGroup files carry state between invocations |
+| No dynamic agent spawning | Cannot create specialized agents at runtime | Prompt files encode all phase specialization |
+| CLI lacks `#prompt:` support | Cannot use prompt shorthand in CLI | Check CLI docs for file reference syntax, or paste prompt content |
+
+### What Works Well
+
+- Agent mode provides full file editing and terminal access
+- `#file:` references efficiently pull in methodology and context
+- WorkGroup files maintain state across sessions
+- Copilot Coding Agent follows `copilot-instructions.md` for autonomous issue resolution
+- MCP tools integrate natively via `.vscode/mcp.json`
+
+---
+
+## Continue / Resume Workflow
+
+When a user invokes `#prompt:kc-continue`:
+
+1. **Find active WorkGroup**: Read `knowzcode/knowzcode_tracker.md` for `[WIP]` entries
+2. **Determine current phase**: Read the WorkGroup file's Phase History table
+3. **Resume or advance**:
+   - If mid-phase (incomplete todos): Resume the current phase
+   - If at a quality gate (phase complete, awaiting approval): Present results and await decision
+   - If between phases (approved, next not started): Begin the next phase
+4. **Guide user**: Tell the user which `#prompt:kc-*` to invoke next, or proceed directly if the continue prompt can handle it
+
+### Phase Detection Logic
+
+| WorkGroup State | Action |
+|----------------|--------|
+| Phase 1A complete, no approval recorded | Present Change Set for approval |
+| Phase 1A approved, no specs drafted | Advise: `#prompt:kc-specify` |
+| Phase 1B complete, no approval recorded | Present specs for approval |
+| Phase 1B approved, no implementation started | Advise: `#prompt:kc-implement` |
+| Phase 2A complete | Advise: `#prompt:kc-audit` |
+| Phase 2B complete, gaps found | Advise: fix gaps then `#prompt:kc-implement`, or `#prompt:kc-finalize` to accept |
+| Phase 2B complete, no gaps | Advise: `#prompt:kc-finalize` |
+| No active WorkGroup | Inform user, suggest `#prompt:kc-work` |

package/knowzcode/enterprise/compliance_manifest.md

@@ -112,6 +112,9 @@ When `mcp_compliance_enabled: true`:
 | analyst | create_knowledge | After 1A approval | Scope decisions, risk assessment |
 | reviewer | create_knowledge | After 2B audit | Audit findings, security posture |
 | closer | create_knowledge | After Phase 3 | Completion record, architecture changes |
+| security-officer | search_knowledge | Stage 0, Stage 2 | Organization security standards, past security findings |
+| test-advisor | (read-only) | Stage 2 | Enterprise ARC criteria for test coverage check |
+| project-advisor | (read-only) | Stage 0 | Compliance config gaps for backlog proposals |
 
 ---
 

package/knowzcode/knowzcode_loop.md

@@ -446,7 +446,9 @@ Both broadcast findings to inform analyst and architect work.
 
 ### Sequential Execution Protocol (for platforms without orchestration)
 
-For platforms like Cursor, Copilot, or Windsurf where there is no agent orchestration:
+For platforms like Cursor, Copilot, or Windsurf where there is no agent orchestration.
+
+**Copilot users:** Instead of manually reading phase prompts, use `#prompt:kc-*` prompt files in VS Code Copilot Chat (e.g., `#prompt:kc-work`, `#prompt:kc-specify`). These prompt files encode the sequential protocol below with `#file:` references for context. See `knowzcode/copilot_execution.md` for the full Copilot execution guide.
 
 ```
 FOR each phase in [1A, 1B, 2A, 2B, 3]:

package/knowzcode/knowzcode_orchestration.md

@@ -0,0 +1,66 @@
+# KnowzCode Orchestration Configuration
+
+**Purpose:** Project-level defaults for team sizing and agent orchestration. Read by `/kc:work` and `/kc:audit` at startup. Per-invocation flags override these settings.
+
+---
+
+## Builder Configuration
+
+```yaml
+# Maximum concurrent builders in Parallel Teams mode (default: 5, range: 1-5)
+# Lower values reduce token usage and complexity; higher values increase parallelism.
+# If the dependency map produces fewer partitions, fewer builders spawn regardless.
+max_builders: 5
+```
+
+---
+
+## Scout Configuration
+
+```yaml
+# Scout mode controls context-scout spawning at Stage 0 (default: full)
+#   full    — 3 scouts: specs, workgroups, backlog (default)
+#   minimal — 1 scout: combined scan of all local context
+#   none    — skip scouts entirely (lead loads context inline)
+scout_mode: full
+```
+
+---
+
+## Specialist Defaults
+
+```yaml
+# Specialists enabled by default for this project (default: none)
+# These activate without needing --specialists on every invocation.
+# Per-invocation --no-specialists overrides this setting.
+# Values: security-officer, test-advisor, project-advisor
+default_specialists: []
+
+# Examples:
+# default_specialists: [security-officer]
+# default_specialists: [security-officer, test-advisor]
+# default_specialists: [security-officer, test-advisor, project-advisor]
+```
+
+---
+
+## MCP Agent Configuration
+
+```yaml
+# Enable MCP agents (knowz-scout, knowz-scribe) when vaults are configured (default: true)
+# Set to false to skip vault agents even when vaults exist — reduces agent count.
+mcp_agents_enabled: true
+```
+
+---
+
+## Override Precedence
+
+| Setting | Config Default | Flag Override |
+|---------|---------------|--------------|
+| max_builders | `max_builders:` | `--max-builders=N` |
+| scout_mode | `scout_mode:` | `--no-scouts` |
+| default_specialists | `default_specialists:` | `--specialists`, `--no-specialists` |
+| mcp_agents_enabled | `mcp_agents_enabled:` | `--no-mcp` |
+
+Per-invocation flags always win. `--specialists` adds to defaults; `--no-specialists` clears all.