knowzcode 0.3.7 → 0.4.0

package/README.md

@@ -1,320 +1,354 @@
-# KnowzCode
-
-<div align="center">
-
-**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-0.3.7-blue)](https://github.com/knowz-io/knowzcode/releases)
-
-[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>
-
----
-
-## The Problem
-
-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 your project's `knowzcode/` directory.
-
-- **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 ────────────────────┐
-  │                                                             │
-  │  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 (Recommended)
-
-```bash
-/plugin marketplace add knowz-io/knowzcode
-/plugin install kc@knowzcode
-cd your-project/
-/kc:init
-/kc:work "Build user authentication"
-```
-
-### Alternative: Script Install
-
-```bash
-npx knowzcode                                    # Interactive setup
-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 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)
-
-```bash
-git clone https://github.com/knowz-io/knowzcode.git
-cd KnowzCode
-./install.sh --target /path/to/your/project       # Linux/macOS
-.\install.ps1 -Target C:\path\to\your\project     # Windows
-```
-
-### Cloud Features (Optional)
-
-Connect to KnowzCode Cloud for vector-powered semantic search, AI Q&A, and learning capture via MCP. See the [Getting Started Guide](./docs/knowzcode_getting_started.md#mcp-integration-cloud-features) for setup.
-
-## Quick Start
-
-### Start a Feature
-
-```bash
-/kc:work "Build user authentication with email and password"
-```
-
-Runs the full loop: impact analysis → specs → TDD → audit → finalize, with approval gates between each phase.
-
-### Research First
-
-```bash
-/kc:plan "how is authentication implemented?"
-```
-
-Explores your codebase first. Say "implement" to transition into `/kc:work` with findings pre-loaded.
-
-### Quick Fix
-
-```bash
-/kc:fix "Fix typo in login button text"
-```
-
-Targeted fixes that skip the full loop — for typos, small bugs, and CSS tweaks.
-
-## Commands
-
-| 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
-
-```
-Layer 4: Platform Enhancements (optional, best experience)
-         Claude Code agents | Codex Agents SDK | Gemini Skills
-         ──────────────────────────────────────────────────────
-Layer 3: Platform Adapters (thin instruction files)
-         CLAUDE.md | AGENTS.md | GEMINI.md | .cursor/rules/*.mdc
-         ──────────────────────────────────────────────────────
-Layer 2: MCP Integration (cross-platform knowledge layer)
-         KnowzCode MCP server → vaults, search, learning capture
-         ──────────────────────────────────────────────────────
-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.
-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
-
-```
-your-project/
-└── knowzcode/
-    ├── knowzcode_loop.md          # The methodology (TDD, quality gates, phases)
-    ├── knowzcode_project.md       # Project goals, tech stack, standards
-    ├── knowzcode_architecture.md  # Auto-maintained architecture docs
-    ├── knowzcode_tracker.md       # WorkGroup status tracking
-    ├── knowzcode_log.md           # Session history
-    ├── specs/                     # Component specifications
-    ├── prompts/                   # Phase prompt templates (works with any AI)
-    ├── workgroups/                # Session data (gitignored)
-    └── enterprise/                # Optional compliance config (gitignored, experimental)
-```
-
-## Documentation
-
-| Guide | Description |
-|:------|:------------|
-| [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
-
-Fork → branch → PR. See **[CLAUDE.md](CLAUDE.md)** for developer docs.
-
-## Acknowledgments
-
-KnowzCode is built upon the foundation of the [Noderr project](https://github.com/kaithoughtarchitect/noderr) by [@kaithoughtarchitect](https://github.com/kaithoughtarchitect). We're grateful for their pioneering work in systematic AI-driven development.
-
-## License
-
-MIT License with Commons Clause — See [LICENSE](LICENSE) file for details.
-
----
-
-<div align="center">
-
-**A structured development methodology for AI coding assistants.**
-
-[Get Started](#installation) · [Read the Docs](#documentation) · [Contribute](#contributing)
-
-Built by [Knowz](https://github.com/knowz-io)
-
-</div>
+# KnowzCode
+
+<div align="center">
+
+**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-0.4.0-blue)](https://github.com/knowz-io/knowzcode/releases)
+
+[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>
+
+---
+
+## The Problem
+
+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 your project's `knowzcode/` directory.
+
+- **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 ────────────────────┐
+  │                                                             │
+  │  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 (Recommended)
+
+```bash
+/plugin marketplace add knowz-io/knowzcode
+/plugin install kc@knowzcode
+cd your-project/
+/kc:init
+/kc:work "Build user authentication"
+```
+
+### Alternative: Script Install
+
+```bash
+npx knowzcode                                    # Interactive setup
+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 | Generated Files | Support Level |
+|----------|----------------|---------------|
+| Claude Code | `CLAUDE.md` + `.claude/{agents,commands,skills}/` | Full support (plugin + 14 agents + 11 commands) |
+| Gemini CLI | `GEMINI.md` + `.gemini/commands/kc/*.toml` (7 commands) | Native `/kc:` commands + instruction file |
+| OpenAI Codex | `AGENTS.md` + `.codex/skills/kc/*.md` (6 skills) | Instruction file + discoverable skill files |
+| Cursor | `.cursor/rules/knowzcode.mdc` | Rules file (commands via `.cursor/commands/` beta) |
+| GitHub Copilot | `.github/copilot-instructions.md` + `.github/prompts/kc-*.prompt.md` (9 prompts) + `.vscode/mcp.json` | Full support (instructions + prompt files + MCP) |
+| Windsurf | `.windsurf/rules/knowzcode.md` | Rules file (workflows via `.windsurf/workflows/`) |
+
+</details>
+
+### Manual (Repo Clone)
+
+```bash
+git clone https://github.com/knowz-io/knowzcode.git
+cd KnowzCode
+./install.sh install --target /path/to/your/project   # Linux/macOS
+.\install.ps1 install --target C:\path\to\your\project # Windows
+```
+
+`install.sh` and `install.ps1` are thin wrappers that delegate to the Node.js installer (`bin/knowzcode.mjs`). Node.js 18+ is required.
+
+### Cloud Features (Optional)
+
+Connect to KnowzCode Cloud for vector-powered semantic search, AI Q&A, and learning capture via MCP. See the [Getting Started Guide](./docs/knowzcode_getting_started.md#mcp-integration-cloud-features) for setup.
+
+## Quick Start
+
+### Start a Feature
+
+```bash
+/kc:work "Build user authentication with email and password"
+```
+
+Runs the full loop: impact analysis → specs → TDD → audit → finalize, with approval gates between each phase.
+
+### Research First
+
+```bash
+/kc:plan "how is authentication implemented?"
+```
+
+Explores your codebase first. Say "implement" to transition into `/kc:work` with findings pre-loaded.
+
+### Quick Fix
+
+```bash
+/kc:fix "Fix typo in login button text"
+```
+
+Targeted fixes that skip the full loop — for typos, small bugs, and CSS tweaks.
+
+## Commands
+
+| 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
+
+```
+Layer 4: Platform Enhancements (optional, best experience)
+         Claude Code agents | Codex Agents SDK | Gemini Skills
+         ──────────────────────────────────────────────────────
+Layer 3: Platform Adapters (thin instruction files)
+         CLAUDE.md | AGENTS.md | GEMINI.md | .cursor/rules/*.mdc
+         ──────────────────────────────────────────────────────
+Layer 2: MCP Integration (cross-platform knowledge layer)
+         KnowzCode MCP server → vaults, search, learning capture
+         ──────────────────────────────────────────────────────
+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.
+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.
+
+### Gemini CLI
+
+Gemini users get native `/kc:` commands via TOML files in `.gemini/commands/kc/`:
+
+```bash
+/kc:work "Build JWT authentication"   # Start feature workflow
+/kc:plan "how is auth implemented?"   # Research first
+/kc:fix "Fix login redirect bug"      # Quick fix
+/kc:audit                             # Quality audit
+/kc:continue                          # Resume where you left off
+```
+
+Generated by `npx knowzcode install --platforms gemini` into `.gemini/commands/kc/`.
+
+### OpenAI Codex
+
+Codex users get discoverable `/kc:` skills via `.codex/skills/kc/`:
+
+```bash
+/kc:work "Build user authentication"  # Start feature workflow
+/kc:plan "how is auth implemented?"   # Research first
+/kc:fix "Fix login bug"               # Quick fix
+/kc:audit                             # Quality audit
+```
+
+Generated by `npx knowzcode install --platforms codex` into `.codex/skills/kc/`.
+
+For cross-project availability, install skills globally:
+```bash
+npx knowzcode install --platforms codex --global   # Skills → ~/.codex/skills/kc/
+```
+
+### Other Platforms
+
+Cursor 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
+
+```
+your-project/
+└── knowzcode/
+    ├── knowzcode_loop.md          # The methodology (TDD, quality gates, phases)
+    ├── knowzcode_project.md       # Project goals, tech stack, standards
+    ├── knowzcode_architecture.md  # Auto-maintained architecture docs
+    ├── knowzcode_tracker.md       # WorkGroup status tracking
+    ├── knowzcode_log.md           # Session history
+    ├── specs/                     # Component specifications
+    ├── prompts/                   # Phase prompt templates (works with any AI)
+    ├── workgroups/                # Session data (gitignored)
+    └── enterprise/                # Optional compliance config (gitignored, experimental)
+```
+
+## Documentation
+
+| Guide | Description |
+|:------|:------------|
+| [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
+
+Fork → branch → PR. See **[CLAUDE.md](CLAUDE.md)** for developer docs.
+
+## Acknowledgments
+
+KnowzCode is built upon the foundation of the [Noderr project](https://github.com/kaithoughtarchitect/noderr) by [@kaithoughtarchitect](https://github.com/kaithoughtarchitect). We're grateful for their pioneering work in systematic AI-driven development.
+
+## License
+
+MIT License with Commons Clause — See [LICENSE](LICENSE) file for details.
+
+---
+
+<div align="center">
+
+**A structured development methodology for AI coding assistants.**
+
+[Get Started](#installation) · [Read the Docs](#documentation) · [Contribute](#contributing)
+
+Built by [Knowz](https://github.com/knowz-io)
+
+</div>