knowzcode 0.1.0

package/commands/telemetry.md

@@ -0,0 +1,188 @@
+---
+description: "Investigate telemetry data from Sentry, App Insights, and other sources"
+argument-hint: "<natural language description>"
+---
+
+# KnowzCode Telemetry Investigation
+
+Investigate production telemetry to diagnose errors, trace issues, and identify root causes.
+
+**Usage**: `/kc:telemetry "<natural language description>"`
+
+Describe everything in plain English - environment, timeframe, and error context will be extracted automatically.
+
+**Examples**:
+```
+/kc:telemetry "in staging in the last 20 min, error 500"
+/kc:telemetry "NullReferenceException in production over the past hour"
+/kc:telemetry "checkout failures in dev since this morning"
+/kc:telemetry "slow API responses in user service today"
+```
+
+---
+
+## Parameter
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `description` | Yes | Natural language query describing what to investigate, including any context about environment, timeframe, etc. |
+
+---
+
+## Workflow
+
+### Step 1: Parse Natural Language Query
+
+Extract from the user's description:
+- **Environment**: staging/production/dev (from phrases like "in staging", "in prod")
+- **Timeframe**: How far back to search (from phrases like "last 20 min", "past 4 hours")
+- **Search query**: The error/symptom to investigate (everything else)
+
+### Step 2: Load Configuration and Detect Sources
+
+Before investigation, load configuration and verify sources are available AND authenticated.
+
+#### 2.1 Load Telemetry Configuration
+
+Read `knowzcode/telemetry_config.md` to get environment-to-resource mappings.
+
+**Parse the config** to extract:
+- **Sentry**: Enabled status, **method** (cli or mcp), organization, environment-to-project mappings
+- **App Insights**: Enabled status, subscription, environment-to-app ID mappings
+
+#### 2.2 Detect Tool Installation
+
+```bash
+# Check Sentry CLI installation
+which sentry-cli 2>/dev/null && echo "SENTRY_CLI_INSTALLED" || echo "NO_SENTRY_CLI"
+
+# Check Azure CLI + App Insights extension
+which az 2>/dev/null && az extension list --query "[?name=='application-insights'].name" -o tsv 2>/dev/null && echo "APPINSIGHTS_INSTALLED" || echo "NO_APPINSIGHTS"
+```
+
+#### 2.3 Verify Authentication
+
+For each installed tool, verify it's authenticated:
+
+```bash
+# Sentry: Check authentication (quick check)
+sentry-cli info 2>&1 | grep -q "Organization" && echo "SENTRY_AUTHENTICATED" || echo "SENTRY_NOT_AUTHENTICATED"
+
+# Azure: Check authentication
+az account show --query "name" -o tsv 2>/dev/null && echo "AZURE_AUTHENTICATED" || echo "AZURE_NOT_AUTHENTICATED"
+```
+
+#### 2.4 Handle Configuration Issues
+
+**If config doesn't exist or sources not configured:**
+
+```markdown
+Telemetry not configured.
+
+Run `/kc:telemetry-setup` to:
+1. Detect available telemetry tools
+2. Verify authentication
+3. Auto-discover projects/resources
+4. Configure environment mappings
+
+After setup, re-run your telemetry query.
+```
+
+**If tools not authenticated:**
+
+```markdown
+Telemetry tools detected but not authenticated.
+
+Sentry: {status}
+App Insights: {status}
+
+Run `/kc:telemetry-setup` to verify authentication and configure sources.
+```
+
+### Step 3: Investigate Telemetry
+
+Spawn the **reviewer** agent to perform the telemetry investigation:
+
+```
+Task(reviewer):
+  Investigate telemetry for the following issue.
+
+  Natural Language Query: {user's full natural language description}
+  Available Sources: {detected sources that are installed AND authenticated}
+
+  Telemetry Configuration:
+  - Sentry: {enabled, method, org, environment mappings}
+  - App Insights: {enabled, subscription, environment mappings}
+
+  Instructions:
+  1. Parse the natural language query to extract environment, timeframe, and search terms
+  2. Use the environment to look up the correct project/app ID from config
+  3. Query available sources using CLI tools (sentry-cli, az monitor)
+  4. Synthesize into unified timeline
+  5. Generate root cause hypothesis
+  6. Return structured findings
+```
+
+### Step 4: Present Findings
+
+Display the synthesized telemetry investigation results:
+
+```markdown
+## KnowzCode Telemetry Investigation
+
+**Original Query**: {user's natural language description}
+**Extracted**:
+  - Environment: {extracted env}
+  - Timeframe: {extracted timeframe}
+  - Search: {extracted search terms}
+**Sources Queried**: {list of sources}
+
+### Event Timeline (merged)
+| Timestamp | Source | Type | Summary |
+|-----------|--------|------|---------|
+| ... | ... | ... | ... |
+
+### Root Cause Hypothesis
+**Most Likely**: {hypothesis}
+**Evidence**: {supporting evidence}
+**Confidence**: HIGH/MEDIUM/LOW
+
+### Recommendations
+1. {quick fix recommendation}
+2. {proper fix recommendation}
+
+---
+
+**Next Steps:**
+- `/kc:fix {target}` - Apply a micro-fix
+- `/kc:work "Fix {issue}"` - Full implementation workflow
+```
+
+---
+
+## Integration with Other Commands
+
+| Command | Relationship |
+|---------|--------------|
+| `/kc:fix` | Hand off quick fixes discovered |
+| `/kc:work` | Hand off larger remediation tasks |
+| `builder` | Can invoke telemetry investigation during debugging |
+| `microfix-specialist` | Can invoke telemetry investigation for verification |
+
+---
+
+## Logging
+
+After investigation, log to `knowzcode/knowzcode_log.md`:
+
+```markdown
+---
+**Type:** Telemetry Investigation
+**Timestamp:** {timestamp}
+**Query:** {original natural language query}
+**Extracted**: env={env}, timeframe={timeframe}
+**Sources:** {sources queried}
+**Finding:** {one-line root cause summary}
+**Status:** Complete
+---
+```

package/commands/work.md

@@ -0,0 +1,390 @@
+---
+description: "Start a new KnowzCode development workflow with TDD, quality gates, and structured phases"
+argument-hint: "[feature_description]"
+---
+
+# Work on New Feature
+
+Start a new KnowzCode development workflow session.
+
+**Usage**: `/kc:work "feature description"`
+**Example**: `/kc:work "Build user authentication with JWT"`
+
+**Primary Goal**: $ARGUMENTS
+
+---
+
+## Step 0: Prerequisite Check
+
+Verify KnowzCode is initialized:
+1. Check if `knowzcode/` directory exists
+2. Check required files exist: `knowzcode_loop.md`, `knowzcode_tracker.md`, `knowzcode_project.md`, `knowzcode_architecture.md`
+
+If missing: inform user to run `/kc:init` first. STOP.
+
+## Step 1: Generate WorkGroup ID
+
+**Format**: `kc-{type}-{slug}-YYYYMMDD-HHMMSS`
+
+- `{type}`: feat, fix, refactor, or issue
+- `{slug}`: 2-4 word kebab-case from goal (remove common words: build, add, create, implement, the, a, with, for)
+- Truncate slug to max 25 characters
+
+## Step 2: Detect Execution Mode
+
+Check if Agent Teams is enabled: you have team management capabilities (spawning teammates, shared task list, messaging) when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set. If these tools are available, use Agent Teams mode. Otherwise, use subagent fallback.
+
+The user never selects a mode — the phases, quality gates, and interactions are identical in both paths.
+
+> **Note:** Agent Teams is experimental and the API may change.
+
+### If Agent Teams is available:
+
+1. Read `knowzcode/claude_code_execution.md` for team conventions
+2. 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.)
+3. For each phase:
+   - Spawn ONE teammate with the spawn prompt defined in that phase section below
+   - Create a task describing the phase work and assign it to the teammate
+   - Wait for the teammate to complete the task
+   - Review the teammate's output
+   - Present results at the quality gate for user approval
+   - Shut down the teammate before spawning the next phase's teammate
+4. After Phase 3 completes or if the user cancels at any point, shut down all active teammates (see Cleanup section)
+
+### If Agent Teams is NOT available (subagent fallback):
+
+Use `Task()` calls to delegate each phase to the named agent. Pass the WorkGroupID, goal, and context file paths. This is the existing behavior — each phase section below includes both paths.
+
+## Step 3: Load Context Files (ONCE)
+
+Read these files ONCE (do NOT re-read between phases):
+- `knowzcode/knowzcode_loop.md`
+- `knowzcode/knowzcode_tracker.md`
+- `knowzcode/knowzcode_project.md`
+- `knowzcode/knowzcode_architecture.md`
+
+## Step 3.5: Pull Team Standards (MCP — Optional)
+
+If MCP is configured and enterprise compliance is enabled:
+1. Check `knowzcode/enterprise/compliance_manifest.md` for `mcp_compliance_enabled: true`
+2. If enabled: `ask_question(enterprise_vault, "team standards for {project_type}")`
+3. Merge returned standards into WorkGroup context for quality gate criteria
+
+If MCP is not configured or enterprise is not enabled, skip this step.
+
+## Step 4: Create WorkGroup File
+
+Create `knowzcode/workgroups/{WorkGroupID}.md`:
+```markdown
+# WorkGroup: {WorkGroupID}
+
+**Primary Goal**: {$ARGUMENTS}
+**Created**: {timestamp}
+**Status**: Active
+**Current Phase**: 1A - Impact Analysis
+
+## Change Set
+(Populated after Phase 1A)
+
+## Todos
+- KnowzCode: Initialize WorkGroup
+- KnowzCode: Complete Phase 1A impact analysis
+
+## Phase History
+| Phase | Status | Timestamp |
+|-------|--------|-----------|
+| 1A | In Progress | {timestamp} |
+```
+
+## Step 5: Input Classification
+
+**Question indicators** (suggest `/kc:plan` instead): starts with is/does/how/why/what/should, contains `?`, phrased as inquiry.
+
+**Implementation indicators** (proceed): starts with build/add/create/implement/fix/refactor, action-oriented verbs.
+
+If ambiguous, proceed with implementation.
+
+## Step 6: Spec Detection (Optional Optimization)
+
+Check for existing specs covering this work:
+1. Extract key terms from goal
+2. Search `knowzcode/specs/*.md` for matching specs
+3. If comprehensive matching specs found, offer:
+   - **A) Quick Path** — skip discovery, use existing specs
+   - **B) Validation Path** (recommended) — quick check specs match codebase
+   - **C) Full Workflow** — complete Phase 1A discovery
+
+If no matches found, proceed to Phase 1A.
+
+---
+
+## Phase 1A: Impact Analysis
+
+### Agent Teams Mode
+
+Spawn a teammate named `analyst` with this prompt:
+
+> You are the **analyst** for WorkGroup `{wgid}`.
+> Read `agents/analyst.md` for your full role definition.
+> Read `knowzcode/claude_code_execution.md` for team conventions.
+>
+> **Goal**: {goal}
+> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+>
+> **Deliverable**: Change Set proposal written to the WorkGroup file. Include NodeIDs, descriptions, affected files, and risk assessment.
+> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+
+Create task: `Phase 1A: Impact analysis for "{goal}"` and assign to the analyst.
+Wait for task completion, then review the Change Set output.
+
+### Subagent Mode
+
+Delegate to the **analyst** agent via `Task()`. Pass WorkGroupID, goal, and context file paths.
+
+### Quality Gate #1 (both modes)
+
+Present the Change Set for user approval:
+
+```markdown
+## Approval Gate #1: Change Set
+
+**WorkGroupID**: {wgid}
+**Proposed Change Set** ({N} nodes):
+{NodeIDs with descriptions}
+
+**Risk Assessment**: {Low/Medium/High}
+
+Approve this Change Set to proceed to specification?
+```
+
+If rejected: re-run analyst with user feedback. If approved: update tracker, proceed.
+
+---
+
+## Phase 1B: Specification
+
+### Agent Teams Mode
+
+Spawn a teammate named `architect` with this prompt:
+
+> You are the **architect** for WorkGroup `{wgid}`.
+> Read `agents/architect.md` for your full role definition.
+> Read `knowzcode/claude_code_execution.md` for team conventions.
+>
+> **Goal**: {goal}
+> **Approved Change Set**: {NodeIDs from Gate #1}
+> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+> **Specs directory**: `knowzcode/specs/`
+>
+> **Plan approval enabled**: Present your spec design (structure, VERIFY criteria, test strategy) for lead review BEFORE writing final specs. Wait for approval.
+> **Deliverable**: Finalized specs for all NodeIDs written to `knowzcode/specs/`.
+> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+
+Create task: `Phase 1B: Draft specifications for {N} NodeIDs` and assign to the architect.
+Wait for the architect to present their plan. Review and approve or request changes.
+After plan approval, wait for task completion.
+
+### Subagent Mode
+
+Delegate to the **architect** agent via `Task()`. Pass WorkGroupID, approved Change Set NodeIDs, and context file paths.
+
+### Quality Gate #2 (both modes)
+
+Present specs for batch approval:
+
+```markdown
+## Approval Gate #2: Specifications
+
+**Specs Drafted**: {count}
+| NodeID | File | Key VERIFY Criteria |
+|--------|------|---------------------|
+| ... | ... | ... |
+
+Review specs and approve to proceed to implementation?
+```
+
+If rejected: re-run specs needing revision. If approved: pre-implementation commit, proceed.
+
+**Pre-Implementation Commit:**
+```bash
+git add knowzcode/
+git commit -m "KnowzCode: Specs approved for {WorkGroupID}"
+```
+
+---
+
+## Phase 2A: Implementation
+
+### Agent Teams Mode
+
+Spawn a teammate named `builder` with this prompt:
+
+> You are the **builder** for WorkGroup `{wgid}`.
+> Read `agents/builder.md` for your full role definition.
+> Read `knowzcode/claude_code_execution.md` for team conventions.
+>
+> **Goal**: {goal}
+> **Approved Change Set**: {NodeIDs}
+> **Specs**: {list of spec file paths from Phase 1B}
+> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+>
+> **Plan approval enabled**: Present your implementation approach (file changes, test strategy, execution order) for lead review BEFORE writing code. Wait for approval.
+> **TDD mandatory**: Write failing tests first, then implement, then refactor. Every NodeID must have tests.
+> **Deliverable**: All NodeIDs implemented with passing tests. Update WorkGroup file with results.
+> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+
+Create task: `Phase 2A: Implement {N} NodeIDs with TDD` and assign to the builder.
+Wait for the builder to present their plan. Review and approve or request changes.
+After plan approval, wait for task completion.
+
+### Subagent Mode
+
+Delegate to the **builder** agent via `Task()`. Pass WorkGroupID, NodeIDs, spec file paths, and context file paths.
+
+### Phase 2A Output (both modes)
+
+When complete, present implementation summary including files changed, tests written, and test results.
+
+---
+
+## Phase 2B: Completeness Audit
+
+### Agent Teams Mode
+
+Spawn a teammate named `reviewer` with this prompt:
+
+> You are the **reviewer** for WorkGroup `{wgid}`.
+> Read `agents/reviewer.md` for your full role definition.
+> Read `knowzcode/claude_code_execution.md` for team conventions.
+>
+> **Goal**: {goal}
+> **Change Set**: {NodeIDs}
+> **Specs**: {list of spec file paths}
+> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+>
+> **This is a READ-ONLY audit.** Do not modify any source code or test files.
+> **Deliverable**: Audit report with ARC completion %, security posture, and gap list. Write results to WorkGroup file.
+> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+
+Create task: `Phase 2B: Completeness audit for {N} NodeIDs` and assign to the reviewer.
+Wait for task completion, then review audit results.
+
+### Subagent Mode
+
+Delegate to the **reviewer** agent via `Task()`. Pass WorkGroupID, NodeIDs, spec file paths, and context file paths.
+
+### Quality Gate #3 (both modes)
+
+Present audit results:
+
+```markdown
+## Approval Gate #3: Audit Results
+
+**ARC Completion**: {X}%
+**Security Posture**: {status}
+**Gaps Found**: {count}
+
+**Recommendation**: {proceed / return to implementation}
+
+How would you like to proceed?
+```
+
+### Gap Loop (when user chooses to fix gaps)
+
+If the user wants gaps fixed:
+
+**Agent Teams Mode**: The previous builder teammate was already shut down. Spawn a NEW `builder` teammate with the same base prompt as Phase 2A, plus these additions:
+
+> **Gap fix mode**: You are fixing gaps found during audit, not doing fresh implementation.
+> **Gaps to fix**:
+> {gap list from reviewer — file path, criterion not met, expected vs actual}
+>
+> Fix each gap, re-run affected tests, and report completion.
+
+Create task: `Phase 2A (gap fix): Address {N} audit gaps` and assign to the new builder.
+Wait for completion, then re-run Phase 2B (spawn a new reviewer).
+
+**Subagent Mode**: Delegate gap fixes to the **builder** agent via `Task()` with gap details. Then re-delegate audit to the **reviewer** agent.
+
+If approved at Gate #3: proceed to finalization.
+
+---
+
+## Phase 3: Finalization
+
+### Agent Teams Mode
+
+Spawn a teammate named `closer` with this prompt:
+
+> You are the **closer** for WorkGroup `{wgid}`.
+> Read `agents/closer.md` for your full role definition.
+> Read `knowzcode/claude_code_execution.md` for team conventions.
+>
+> **Goal**: {goal}
+> **Change Set**: {NodeIDs}
+> **Specs**: {list of spec file paths}
+> **Context files**: `knowzcode/knowzcode_loop.md`, `knowzcode/knowzcode_tracker.md`, `knowzcode/knowzcode_project.md`, `knowzcode/knowzcode_architecture.md`, `knowzcode/knowzcode_log.md`
+> **WorkGroup file**: `knowzcode/workgroups/{wgid}.md`
+>
+> **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, capture learnings, and create final commit.
+> **Prefix rule**: All todo entries MUST start with `KnowzCode:`.
+
+Create task: `Phase 3: Finalize WorkGroup {wgid}` and assign to the closer.
+Wait for task completion.
+
+### Subagent Mode
+
+Delegate to the **closer** agent via `Task()`. Pass WorkGroupID, NodeIDs, spec file paths, and all context file paths.
+
+### Phase 3 Output (both modes)
+
+When complete, push completion record to MCP vault if configured:
+- `create_knowledge` with WorkGroup summary, decisions, and outcomes
+
+Update workgroup to "Closed" and report:
+
+```markdown
+## Workflow Complete
+
+**WorkGroupID**: {wgid}
+**Primary Goal**: {$ARGUMENTS}
+**Status**: VERIFIED and CLOSED
+
+- NodeIDs completed: {list}
+- Specs finalized: {count}
+- Tech debt scheduled: {count REFACTOR_ tasks}
+```
+
+---
+
+## Cleanup
+
+After Phase 3 completes successfully, or if the user cancels the workflow at any point:
+
+**Agent Teams Mode**: Shut down all active teammates. No teammates should remain running after the workflow ends.
+
+**Subagent Mode**: No cleanup needed — `Task()` calls are self-contained.
+
+---
+
+## Complexity Triage
+
+Before full orchestration, assess the change:
+- Single file, <50 lines, isolated fix? Consider `/kc:fix` instead
+- Multiple files or architectural impact? Continue with full workflow
+
+## Handling Failures
+
+- Phase 1A rejected: re-run analyst with feedback
+- Phase 1B rejected: re-run architect with specific issues
+- Phase 2A max iterations exceeded: pause, report blocker
+- Phase 2B audit shows gaps: return to 2A with gap list (see Gap Loop above)
+- If >3 failures on same phase: PAUSE and ask user for direction
+
+## KnowzCode: Prefix Enforcement
+
+Every todo in workgroup files MUST start with `KnowzCode:`. Pass this to all agents.

package/knowzcode/automation_manifest.md

@@ -0,0 +1,59 @@
+# KnowzCode Automation Manifest
+
+This manifest describes the resources that support the KnowzCode workflow.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/kc:work` | Start feature workflow with TDD, quality gates, and structured phases |
+| `/kc:plan` | Research and investigate using parallel agents before implementing |
+| `/kc:audit` | Run quality audits (spec, architecture, security, integration) |
+| `/kc:fix` | Execute targeted micro-fix workflow |
+| `/kc:init` | Initialize KnowzCode in current project + generate platform adapters |
+| `/kc:telemetry` | Investigate production telemetry |
+| `/kc:telemetry-setup` | Configure telemetry sources |
+| `/kc:connect-mcp` | Configure MCP server connection |
+| `/kc:learn` | Capture learning to vault |
+| `/kc:register` | Register and configure MCP |
+| `/kc:status` | Check MCP and vault status |
+
+## Agents
+
+| Agent | Phase | Description |
+| --- | --- | --- |
+| `analyst` | 1A | Impact analysis and Change Set proposals |
+| `architect` | 1B | Specification drafting and architecture review |
+| `builder` | 2A | TDD implementation and verification loops |
+| `reviewer` | 2B | Quality audit, security review, compliance |
+| `closer` | 3 | Finalization — specs, tracker, log, architecture |
+| `microfix-specialist` | - | Scope-gated quick fixes |
+| `knowledge-migrator` | - | External knowledge import |
+| `update-coordinator` | - | Framework self-update |
+
+## Skills
+
+| Skill | Purpose |
+| --- | --- |
+| `start-work` | Detect implementation intent and redirect to /kc:work |
+| `continue` | Detect continuation intent and resume active WorkGroup |
+| `load-core-context` | Load project overview, architecture, tracker into memory |
+| `generate-workgroup-id` | Produce WorkGroupID timestamps |
+| `tracker-update` | Apply validated updates to tracker |
+| `spec-template` | Seed specs with 4-section template |
+| `spec-quality-check` | Verify spec completeness |
+| `log-entry-builder` | Structure log entries |
+| `architecture-diff` | Highlight differences between specs and architecture docs |
+| `environment-guard` | Confirm environment context is complete |
+| `tracker-scan` | Extract current status and WorkGroup assignments |
+| `alias-resolver` | Convert natural language to canonical KnowzCode values |
+| `spec-validator` | Validate individual spec quality |
+
+## State Files
+
+The authoritative state:
+- `knowzcode/knowzcode_tracker.md` — backlog and node status
+- `knowzcode/knowzcode_log.md` — operational history
+- `knowzcode/specs/` — NodeID specifications
+- `knowzcode/workgroups/` — session todo queues
+- `knowzcode/knowzcode_architecture.md` — architecture documentation