https://github.com/knowz-io/knowzcode
**KnowzCode** - Structured development methodology for AI coding assistants. TDD workflows, quality gates, specs, and tracking that work across Claude Code, Gemini, Cursor, Copilot, Codex, and Windsurf.
https://github.com/knowz-io/knowzcode
agentic-ai agentic-rag claude claude-code codex gemini knowz
Last synced: 4 days ago
JSON representation
**KnowzCode** - Structured development methodology for AI coding assistants. TDD workflows, quality gates, specs, and tracking that work across Claude Code, Gemini, Cursor, Copilot, Codex, and Windsurf.
- Host: GitHub
- URL: https://github.com/knowz-io/knowzcode
- Owner: knowz-io
- License: other
- Created: 2026-02-07T02:20:38.000Z (13 days ago)
- Default Branch: main
- Last Pushed: 2026-02-12T20:35:46.000Z (7 days ago)
- Last Synced: 2026-02-12T23:49:24.967Z (7 days ago)
- Topics: agentic-ai, agentic-rag, claude, claude-code, codex, gemini, knowz
- Language: JavaScript
- Homepage: https://www.knowzai.com
- Size: 492 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# KnowzCode
**A structured development methodology for AI coding assistants.**
[](LICENSE)
[](https://github.com/knowz-io/knowzcode)
[](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)
---
## 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`.
Supported Platforms (6)
| 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 |
### 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 ` | Start feature workflow |
| `/kc:plan ` | Research before implementing |
| `/kc:audit [type]` | Run quality audits |
| `/kc:fix ` | 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 |
Agent Teams Setup & Roster (14 agents)
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 |
Opt-in Specialist Agents
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.
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.
---
**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)