KnowzCode

A structured development methodology for AI coding assistants.

Installation · Quick Start · When to Use It · How It Works · Commands · Docs

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 for details.

Installation

Claude Code (Recommended)

/plugin marketplace add knowz-io/knowzcode
/plugin install kc@knowzcode
cd your-project/
/kc:init
/kc:work "Build user authentication"

Alternative: Script Install

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.

| 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)

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 for setup.

Quick Start

Start a Feature

/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

/kc:plan "how is authentication implemented?"

Explores your codebase first. Say "implement" to transition into /kc:work with findings pre-loaded.

Quick Fix

/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 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 |

Parallel and Sequential Teams require Agent Teams (experimental). Enable by adding the following to your Claude Code settings.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 |

Activate specialists with --specialists in /kc:work or /kc:audit:

/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 for detailed orchestration flows.

GitHub Copilot

Copilot users invoke phases via prompt files in VS Code Copilot Chat:

#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 | Walkthrough, MCP setup, file structure | | Understanding KnowzCode | Concepts and architecture deep dive | | Workflow Reference | Phase details, execution modes, parallel orchestration | | Prompts Guide | Prompt templates and command reference |

Contributing

Fork → branch → PR. See CLAUDE.md for developer docs.

Acknowledgments

KnowzCode is built upon the foundation of the Noderr project by @kaithoughtarchitect. We're grateful for their pioneering work in systematic AI-driven development.

License

MIT License with Commons Clause — See LICENSE file for details.

A structured development methodology for AI coding assistants.

Get Started · Read the Docs · Contribute

Built by Knowz