knowzcode 0.1.0

package/knowzcode/claude_code_execution.md

@@ -0,0 +1,133 @@
+# Claude Code Execution Model
+
+**Purpose:** Defines Agent Teams behavior and inter-agent communication patterns specific to Claude Code. This file supplements the platform-agnostic agent definitions in `agents/`.
+
+Agents on other platforms should ignore this file — see `knowzcode/platform_adapters.md` for platform-specific execution instructions.
+
+---
+
+## Agent Teams Overview
+
+Agent Teams is an **experimental** Claude Code feature for multi-agent coordination. It requires the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to be enabled.
+
+> **Status:** Experimental. The API may change in future releases.
+
+### Prerequisites
+
+- Claude Code with Agent Teams support
+- Environment variable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+- Agent Teams is the preferred execution model when enabled; subagent fallback is used otherwise
+
+> **Windows note:** Split-pane mode (`tmux`) is not supported on Windows Terminal. Agent Teams automatically uses `in-process` mode on Windows (the default `auto` mode handles this correctly). No manual configuration is needed.
+
+### Architecture
+
+Agent Teams uses a **team lead + teammates** model:
+
+- **Team Lead**: Coordinates workflow, delegates tasks, never codes directly (delegate mode)
+- **Teammates**: Specialized agents that receive tasks and report results
+- **Shared Task List**: Structured work tracking with dependencies
+- **Mailbox**: Ad-hoc inter-agent messaging for coordination
+
+### Task Mechanics
+
+Tasks follow a lifecycle: `pending` -> `in_progress` -> `completed`
+
+- Tasks can have **dependencies** (task B blocked by task A)
+- Tasks can have **blockers** (external impediments)
+- The lead creates tasks and assigns to teammates
+- Teammates update status and report results
+
+### Communication Primitives
+
+Agent Teams provides two communication mechanisms:
+
+| Mechanism | Purpose | When to Use |
+|-----------|---------|-------------|
+| **Task List** | Structured work with status, dependencies, blockers | Phase delegation, quality gates, handoffs |
+| **Mailbox** | Ad-hoc coordination between teammates | Clarifications, gap details, scope questions |
+
+### Hooks
+
+Agent Teams supports event-driven coordination via hooks:
+
+- **`TeammateIdle`**: Fires when a teammate finishes its current task — can auto-assign next work
+- **`TaskCompleted`**: Fires when a task is marked complete — can trigger dependent tasks
+
+### Limitations
+
+- Experimental feature — API may change
+- Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var
+- Not available in all Claude Code environments
+
+---
+
+## KnowzCode Agent Teams Behavior
+
+When running as teammates in a Claude Code Agent Teams workflow, all agents follow these conventions:
+
+### Task Lifecycle
+- Receive a task from the team lead with subject and description
+- Read context files listed in task description independently (do not duplicate context across agents)
+- Report progress by updating task status
+- When complete: mark task completed with a summary
+- If blocked: keep task in_progress with blocker description
+
+### Plan Approval (architect, builder only)
+- **Architect**: Present spec drafts as a plan for lead review before finalizing. Wait for lead approval before writing final specs
+- **Builder**: Present implementation plan (approach, file changes, test strategy) for lead review before coding. Wait for lead approval before writing code
+
+### Inter-Agent Communication
+
+> **Note:** In the default sequential workflow (`/kc:work`), teammates are spawned one at a time and shut down between phases. The messaging patterns below apply when teammates coexist — for example, during `/kc:plan` (3 parallel researchers) or if you keep the builder alive during Phase 2B review for direct gap communication. In sequential mode, inter-phase communication goes through the lead.
+
+Use mailbox messaging for coordination between teammates:
+
+| From | To | When |
+|------|-----|------|
+| analyst | architect | Scope clarifications, NodeID overlap with existing specs |
+| architect | analyst | Scope adjustments needed |
+| architect | builder | Spec intent and design decisions |
+| builder | analyst | Affected files and dependency questions |
+| builder | architect | Spec intent and design decisions |
+| reviewer | builder | Gap details (file, line, criterion, expected vs actual) |
+| closer | analyst | Change scope for log entry accuracy |
+| closer | architect | Spec format and legacy migration |
+
+### Gap Communication (reviewer -> builder)
+When the reviewer finds gaps during Phase 2B audit, message the builder with specific details:
+- File path and line number
+- Criterion not met (the VERIFY: statement)
+- Expected behavior vs actual behavior
+
+The builder addresses these gaps and re-verifies before reporting completion.
+
+---
+
+## Teammate Initialization Protocol
+
+When spawned as a teammate in an Agent Teams workflow, follow this sequence:
+
+1. Read your agent definition file (referenced in your spawn prompt, e.g. `agents/analyst.md`)
+2. Read this file (`knowzcode/claude_code_execution.md`) for team conventions
+3. Read the WorkGroup file for current state, Change Set, and context
+4. Read context files listed in your task description
+5. Begin your phase work as defined by your role
+6. Update the WorkGroup file with results — prefix all todo entries with `KnowzCode:`
+7. Mark your task as complete with a summary of what was delivered
+
+If you encounter a blocker, keep the task in `in_progress` status with a description of what is blocking you. Do not mark the task as complete until the work is done.
+
+---
+
+## Command References
+
+Agents may reference these Claude Code commands as escalation paths:
+
+| Command | Used By | Context |
+|---------|---------|---------|
+| `/kc:work` | microfix-specialist | Redirect when fix exceeds scope gate |
+| `/kc:audit security` | reviewer | Full security audit mode |
+| `/kc:audit spec` | knowledge-migrator | Post-migration validation |
+
+On other platforms, these commands translate to running the corresponding phase prompts manually.

package/knowzcode/enterprise/compliance_manifest.md

@@ -0,0 +1,132 @@
+# Enterprise Compliance Manifest
+
+**Purpose:** Defines which enterprise guidelines are active and their enforcement level.
+
+---
+
+## Active Guidelines
+
+| Guideline File | Enforcement | Applies To | Active |
+|:---------------|:------------|:-----------|:-------|
+| security.md | blocking | both | false |
+| code-quality.md | advisory | implementation | false |
+
+> **Note:** Set `Active` to `true` to enable a guideline. Guidelines with empty content are skipped.
+
+---
+
+## Enforcement Levels
+
+| Level | Behavior |
+|:------|:---------|
+| **blocking** | Violations STOP workflow progression. Must be resolved before proceeding. |
+| **advisory** | Violations are REPORTED but workflow can continue with documented acceptance. |
+
+---
+
+## Applies-To Scope
+
+| Scope | When Checked | What Is Validated |
+|:------|:-------------|:------------------|
+| **spec** | Phase 1B (Specification) | Specs address required concerns, ARC criteria included |
+| **implementation** | Phase 2B (Verification) | Code meets requirements, patterns compliant |
+| **both** | Phase 1B AND Phase 2B | Full coverage at both stages |
+
+---
+
+## Custom Guidelines
+
+Add custom guidelines to `knowzcode/enterprise/guidelines/custom/` following the template in `templates/guideline-template.md`.
+
+To activate a custom guideline, add it to the Active Guidelines table above.
+
+---
+
+## Configuration
+
+```yaml
+# Enable/disable compliance checking globally (default: false)
+compliance_enabled: false
+
+# Auto-run compliance during /kc:audit when enabled
+include_in_audit: true
+
+# Require compliance sign-off before Phase 3 finalization
+require_signoff_for_finalization: false
+
+# Show advisory issues in workflow output
+show_advisory_issues: true
+
+# Skip guidelines with empty content (default: true)
+skip_empty_guidelines: true
+```
+
+---
+
+## MCP-Based Compliance (Optional)
+
+When MCP is configured with an enterprise vault, compliance can be enhanced with vault-based standards and audit trails.
+
+```yaml
+# Enable MCP-based compliance features (default: false)
+mcp_compliance_enabled: false
+
+# Enterprise vault ID for standards and audit trails
+compliance_vault_id: ""
+
+# Audit trail vault ID (can be same as compliance vault)
+audit_trail_vault_id: ""
+
+# Pull team-wide standards from enterprise vault at workflow start
+pull_standards_at_start: true
+
+# Push audit results to enterprise vault after Phase 2B
+push_audit_results: true
+
+# Push WorkGroup completion records to enterprise vault after Phase 3
+push_completion_records: true
+```
+
+### How It Works
+
+When `mcp_compliance_enabled: true`:
+
+**At workflow start (before Phase 1A):**
+- Query enterprise vault for team-wide standards: `ask_question(compliance_vault, "team standards for {project_type}")`
+- Merge returned standards into quality gate criteria for the WorkGroup
+
+**After Phase 2B audit:**
+- Push audit results to enterprise vault: `create_knowledge(audit_trail_vault, "Audit: {wgid} - {score}%")`
+- Include security findings, compliance status, and gap summary
+
+**After Phase 3 finalization:**
+- Push completion record: `create_knowledge(audit_trail_vault, "Completion: {wgid}")`
+- Include goal, NodeIDs, audit score, key decisions, and architecture changes
+
+### Agent-to-Enterprise-Vault Operations
+
+| Agent | Operation | When | Content |
+|-------|-----------|------|---------|
+| 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 |
+
+---
+
+## Usage
+
+### Check Compliance Status
+```bash
+/kc:audit compliance           # Full review (spec + implementation)
+/kc:audit compliance spec      # Review specs only
+/kc:audit compliance impl      # Review implementation only
+```
+
+---
+
+## Adding New Guidelines
+
+1. Create guideline file in `guidelines/` or `guidelines/custom/`
+2. Use `templates/guideline-template.md` as starting point
+3. Add entry to Active Guidelines table above
+4. Run `/kc:audit compliance` to verify guideline loads correctly

package/knowzcode/enterprise/compliance_status.md

@@ -0,0 +1,30 @@
+# Enterprise Compliance Status
+
+**Purpose:** Track compliance review status per WorkGroup.
+
+---
+
+## Current WorkGroup
+
+**WorkGroupID:** (none active)
+**Last Review:** N/A
+**Status:** N/A
+
+---
+
+## Review History
+
+| Timestamp | WorkGroupID | Scope | Guidelines | Blocking | Advisory | Result |
+|:----------|:------------|:------|:-----------|:---------|:---------|:-------|
+| | | | | | | |
+
+---
+
+## Notes
+
+This file is automatically updated by the reviewer agent during:
+- Phase 1B spec compliance checks
+- Phase 2B implementation compliance audits
+- Standalone `/kc:audit compliance` reviews
+
+Review history entries are appended chronologically with most recent at top.

package/knowzcode/enterprise/guidelines/code-quality.md

@@ -0,0 +1,67 @@
+---
+guideline_id: CQ-001
+name: Code Quality Guidelines
+enforcement: advisory
+applies_to: implementation
+priority: high
+---
+
+# Code Quality Guidelines
+
+**Purpose:** Ensure code meets enterprise quality standards and design patterns.
+
+> **Note:** This is a template. Add your organization's code quality requirements below.
+> Empty sections are skipped during compliance review.
+
+---
+
+## 1. Design Patterns
+
+<!-- Add required design patterns here -->
+<!-- Example:
+### CQ-PATTERN-01: Repository Pattern for Data Access
+
+**Requirement:** All database access SHOULD use the Repository pattern.
+
+**Applies To:** implementation
+
+**Severity:** medium
+
+**ARC Verification:**
+- ARC_CQ_PATTERN_01a: Verify data access is encapsulated in repository classes
+- ARC_CQ_PATTERN_01b: Verify controllers do not directly access database
+-->
+
+---
+
+## 2. Error Handling
+
+<!-- Add error handling standards here -->
+
+---
+
+## 3. Naming Conventions
+
+<!-- Add naming convention requirements here -->
+
+---
+
+## 4. Code Structure
+
+<!-- Add code structure requirements here -->
+
+---
+
+## 5. Testing Standards
+
+<!-- Add testing requirements here -->
+
+---
+
+## Compliance Summary
+
+| ID | Requirement | Severity | Scope |
+|:---|:------------|:---------|:------|
+<!-- Add your requirements summary here -->
+
+---