knowzcode 0.1.0

package/commands/fix.md

@@ -0,0 +1,107 @@
+---
+description: "Execute the KnowzCode micro-fix workflow"
+argument-hint: "<target> <summary>"
+---
+
+# KnowzCode Micro-Fix
+
+Execute a targeted micro-fix within the KnowzCode framework.
+
+**Usage**: `/kc:fix <target> <summary>`
+**Example**: `/kc:fix src/auth/login.ts "Fix null reference in password validation"`
+
+---
+
+## Scope Guard
+
+**This command is for micro-fixes only.** Before proceeding, verify:
+
+| Criteria | Required |
+|----------|----------|
+| Change affects ≤1 file | ✓ |
+| Change is <50 lines | ✓ |
+| No ripple effects to other components | ✓ |
+| No new dependencies introduced | ✓ |
+| Existing tests cover the change area | ✓ |
+
+**If ANY criteria fails**: Stop and suggest `/kc:work` for full orchestration.
+
+---
+
+## Workflow Steps
+
+### 1. Validate Scope
+- Confirm the fix meets micro-fix criteria above
+- If scope exceeds limits, redirect to `/kc:work`
+
+### 2. Load Context
+- Read the target file to understand current implementation
+- Identify existing test coverage for the affected code
+
+### 3. Implement Fix
+- Apply the minimal change required
+- Follow existing code patterns and style
+
+### 4. Verification Loop (MANDATORY)
+
+**⛔ DO NOT skip verification. DO NOT claim "done" without passing tests.**
+
+```
+REPEAT until all checks pass:
+  1. Run relevant tests:
+     - Unit tests covering the changed code
+     - Integration tests if the fix touches boundaries
+     - E2E tests if the fix affects user-facing behavior
+
+  2. If tests FAIL:
+     - Analyze failure
+     - Apply corrective fix
+     - RESTART verification from step 1
+
+  3. If tests PASS:
+     - Run static analysis / linter
+     - If issues found, fix and RESTART from step 1
+
+  4. All checks pass → Exit loop
+```
+
+**Test Selection Guidance:**
+| Fix Type | Required Tests |
+|----------|---------------|
+| Logic bug in function | Unit tests for that function |
+| API endpoint fix | Unit + Integration tests |
+| UI/UX fix | Unit + E2E tests |
+| Configuration fix | Integration tests |
+| Data handling fix | Unit + Integration tests |
+
+### 5. Log and Commit
+- Log MicroFix entry in `knowzcode/knowzcode_log.md`
+- Include verification evidence (which tests passed)
+- Commit with `fix:` prefix
+
+---
+
+## Arguments
+
+- `target` (required): NodeID or file path that requires the micro-fix
+- `summary` (required): One-line description of the requested change
+
+## Example Usage
+
+```
+/kc:fix src/auth/login.ts "Fix null reference in password validation"
+/kc:fix NODE_AUTH_123 "Update error message formatting"
+```
+
+## Execution
+
+Delegate to the **microfix-specialist** agent via `Task()`. Pass the target file/NodeID and fix summary.
+
+The agent validates scope, implements the minimal fix, runs the verification loop, logs the outcome, and commits.
+
+> **Note:** Micro-fixes use subagent delegation only. Agent Teams overhead is not justified for single-file, <50 line fixes.
+
+## Context Files
+
+- knowzcode/automation_manifest.md
+- knowzcode/prompts/Execute_Micro_Fix.md

package/commands/init.md

@@ -0,0 +1,320 @@
+---
+description: Initialize KnowzCode framework in the current project
+---
+
+# KnowzCode Project Initialization
+
+You are the **KnowzCode Initialization Agent**. Set up the KnowzCode framework in the current working directory.
+
+## What KnowzCode Provides
+
+KnowzCode is an AI-powered development methodology that provides:
+- **Structured TDD workflow** with quality gates
+- **Specification-driven development** with living documentation
+- **Comprehensive tracking** of WorkGroups and specifications
+- **Platform-agnostic** — works with Claude Code, Codex, Gemini, Cursor, Copilot, and more
+
+## Steps to Execute
+
+### 1. Check if already initialized
+
+- Look for existing `knowzcode/` directory
+- If exists and has content, ask user:
+  - **Abort** (preserve existing)
+  - **Merge** (add missing files only)
+  - **Overwrite** (reset to templates)
+
+### 2. Create directory structure
+
+```
+knowzcode/
+├── knowzcode_project.md
+├── knowzcode_tracker.md
+├── knowzcode_log.md
+├── knowzcode_architecture.md
+├── knowzcode_loop.md
+├── platform_adapters.md
+├── environment_context.md
+├── user_preferences.md (if configured)
+├── .gitignore
+├── specs/
+├── workgroups/
+├── prompts/
+└── enterprise/ (optional)
+```
+
+### 3. Copy template files
+
+Use the embedded templates below.
+
+### 4. Generate environment context
+
+- Detect project language, framework, tools
+- Populate `environment_context.md`
+- Include package managers, test runners, build tools
+
+### 5. Capture user preferences (optional)
+
+- Ask: "Would you like to configure development preferences? (optional)"
+- If yes: prompt for testing frameworks, code style, quality priorities
+- Create `knowzcode/user_preferences.md`
+
+### 6. Create .gitignore
+
+Protect environment-specific files from git:
+```
+environment_context.md
+workgroups/
+*.local.md
+.scratch/
+```
+
+### 7. Detect AI platforms and generate adapters
+
+Check which AI platforms are present and offer to generate adapter files.
+
+**Step 7a: Detect platforms**
+```
+CHECK for existing files:
+  - CLAUDE.md → offer to append KnowzCode section
+  - AGENTS.md or AGENTS.override.md → offer to generate Codex adapter
+  - GEMINI.md or ~/.gemini/GEMINI.md → offer to generate Gemini adapter
+  - .cursor/rules/ or .cursorrules (deprecated) → offer Cursor adapter (.cursor/rules/knowzcode.mdc)
+  - .github/copilot-instructions.md → offer Copilot adapter
+  - .windsurf/rules/ or .windsurfrules (deprecated) → offer Windsurf adapter (.windsurf/rules/knowzcode.md)
+```
+
+**Step 7b: Present options**
+```
+PRESENT to user:
+  "Which AI platform adapters would you like to generate?"
+  Options:
+  - Detected platforms only
+  - All platforms
+  - Skip (just use knowzcode/ directly)
+```
+
+**Step 7c: Generate project-specific adapters**
+
+When generating adapters, inject detected project info to make them project-specific:
+
+1. From `environment_context.md`, extract:
+   - Test runner command (e.g., `npm test`, `pytest`, `dotnet test`)
+   - Build command (e.g., `npm run build`, `go build`)
+   - Language/framework (e.g., TypeScript/React, Python/FastAPI)
+
+2. Inject into adapter templates where applicable:
+   - Replace generic test/build references with detected commands
+   - Add framework-specific notes (e.g., "Use Composer for multi-file React edits" for Cursor)
+
+3. For Codex: note that `AGENTS.override.md` can be used for user-local overrides
+
+**Step 7d: Validate generated adapters**
+
+After generation, verify each adapter:
+- References correct `knowzcode/` file paths
+- Contains all 5 phase descriptions
+- Mentions TDD enforcement and quality gates
+- Includes PAUSE/STOP instructions at quality gates
+
+Adapter templates are in `knowzcode/platform_adapters.md`. Copy the relevant sections into the appropriate files.
+
+### 7.5. Enable Agent Teams (Claude Code only)
+
+If the user is on Claude Code, **actively offer** to enable Agent Teams:
+
+**Step 7.5a: Ask the user**
+```
+"Would you like to enable Agent Teams? (recommended for Claude Code)
+
+Agent Teams spawns specialized teammates for each workflow phase,
+giving you richer multi-agent coordination.
+
+Without it, KnowzCode uses subagent delegation (works fine, just less interactive)."
+
+Options:
+  - Yes (recommended)
+  - No (use subagent fallback)
+```
+
+**Step 7.5b: If yes, create/update `.claude/settings.local.json`**
+
+Read `.claude/settings.local.json` if it exists. Merge the Agent Teams env var into it:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+If the file already has other keys, preserve them and merge. If it doesn't exist, create it with the content above.
+
+**Step 7.5c: Windows note**
+
+If the platform is Windows (`process.platform === 'win32'` or detected via environment):
+```
+Note: On Windows, Agent Teams runs in "in-process" mode by default
+(split-pane tmux mode is not supported in Windows Terminal).
+This works correctly — no action needed.
+```
+
+**Step 7.5d: If no, proceed normally** — subagent delegation works without any configuration.
+
+### 8. Optional: Set up enterprise compliance
+
+- Ask: "Would you like to set up enterprise compliance features? (optional)"
+- If yes: create `knowzcode/enterprise/` directory with manifest and templates
+- Compliance is disabled by default
+
+### 9. Optional: Configure MCP
+
+Inform user about enhanced features:
+```
+Optional: Connect to KnowzCode Cloud for AI-powered capabilities:
+  New user?     /kc:register
+  Have a key?   /kc:connect-mcp <api-key>
+```
+
+### 10. Report success
+
+```
+KnowzCode initialized successfully!
+
+Created:
+  knowzcode/knowzcode_project.md
+  knowzcode/knowzcode_tracker.md
+  knowzcode/knowzcode_log.md
+  knowzcode/knowzcode_architecture.md
+  knowzcode/knowzcode_loop.md
+  knowzcode/platform_adapters.md
+  knowzcode/.gitignore
+  knowzcode/specs/
+  knowzcode/workgroups/
+  knowzcode/prompts/
+
+Platform adapters: [list generated adapters or "None (skip)"]
+
+Agent Teams: [Enabled (.claude/settings.local.json) | Not enabled (subagent fallback)]
+
+Next steps:
+  1. Review knowzcode/knowzcode_project.md and add project details
+  2. Start your first feature: /kc:work "your feature description"
+  3. Research first: /kc:plan "your question"
+```
+
+---
+
+## Template Files
+
+### knowzcode_project.md
+```markdown
+# KnowzCode Project Overview
+
+**Purpose:** Project context for KnowzCode AI agents.
+
+### 1. Project Goal & Core Problem
+*   **Goal:** [To be filled in during first session]
+*   **Core Problem Solved:** [To be filled in during first session]
+
+### 2. Scope & Key Features
+*   **Key Features (In Scope):**
+    *   [Feature 1]: [Description]
+*   **Out of Scope:**
+    *   [Deferred 1]: [Description]
+
+### 3. Technology Stack
+| Category | Technology | Version | Notes |
+|:---------|:-----------|:--------|:------|
+| Language(s) | [Detected] | [Detected] | [Auto-detected] |
+| Testing | [Detected] | [Detected] | [Auto-detected] |
+
+### Links to Other Artifacts
+* **Loop Protocol:** `knowzcode/knowzcode_loop.md`
+* **Session Log:** `knowzcode/knowzcode_log.md`
+* **Architecture:** `knowzcode/knowzcode_architecture.md`
+* **Tracker:** `knowzcode/knowzcode_tracker.md`
+* **Specifications:** `knowzcode/specs/`
+```
+
+### knowzcode_tracker.md
+```markdown
+# KnowzCode Status Map (WorkGroup Tracker)
+
+**Purpose:** Tracks all active and completed WorkGroups.
+
+## Active WorkGroups
+
+*None yet. Run `/kc:work "your feature description"` to create your first WorkGroup.*
+
+## Completed WorkGroups
+
+*None yet.*
+
+**Next WorkGroup ID:** WG-001
+```
+
+### knowzcode_log.md
+```markdown
+# KnowzCode Operational Record
+
+**Purpose:** Session log and quality criteria reference.
+
+## Recent Sessions
+
+*No sessions yet.*
+
+## Reference Quality Criteria
+
+1. **Reliability:** Robust error handling, graceful degradation
+2. **Maintainability:** Clear code structure, good naming, modularity
+3. **Security:** Input validation, secure authentication, data protection
+4. **Performance:** Efficient algorithms, optimized queries
+5. **Testability:** Comprehensive test coverage, clear test cases
+```
+
+### knowzcode_architecture.md
+```markdown
+# KnowzCode Architecture Documentation
+
+**Purpose:** Living architecture documentation for this project.
+
+## System Architecture
+
+*To be populated during first feature development.*
+
+## Key Components
+
+*To be populated during implementation.*
+
+## Data Flow
+
+*To be populated during implementation.*
+```
+
+### environment_context.md
+```markdown
+# KnowzCode Environment Context
+
+**Purpose:** Environment and tooling information.
+
+## Detected Environment
+
+**Platform:** [Auto-detected]
+**Language:** [Auto-detected]
+**Package Manager:** [Auto-detected]
+**Test Runner:** [Auto-detected]
+```
+
+---
+
+## Error Handling
+
+If initialization fails:
+1. Report which step failed
+2. Show partial progress
+3. Suggest remediation
+4. Offer to clean up
+
+Execute this initialization now.