{"id":44410071,"url":"https://github.com/knowz-io/knowzcode","last_synced_at":"2026-02-15T20:11:54.732Z","repository":{"id":338049763,"uuid":"1151868202","full_name":"knowz-io/knowzcode","owner":"knowz-io","description":"**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.","archived":false,"fork":false,"pushed_at":"2026-02-12T20:35:46.000Z","size":504,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T23:49:24.967Z","etag":null,"topics":["agentic-ai","agentic-rag","claude","claude-code","codex","gemini","knowz"],"latest_commit_sha":null,"homepage":"https://www.knowzai.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knowz-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T02:20:38.000Z","updated_at":"2026-02-12T20:35:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/knowz-io/knowzcode","commit_stats":null,"previous_names":["knowz-io/knowzcode"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/knowz-io/knowzcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowz-io%2Fknowzcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowz-io%2Fknowzcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowz-io%2Fknowzcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowz-io%2Fknowzcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knowz-io","download_url":"https://codeload.github.com/knowz-io/knowzcode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knowz-io%2Fknowzcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29487396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T15:33:17.885Z","status":"ssl_error","status_checked_at":"2026-02-15T15:32:53.698Z","response_time":118,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-rag","claude","claude-code","codex","gemini","knowz"],"created_at":"2026-02-12T07:08:03.926Z","updated_at":"2026-02-15T20:11:54.726Z","avatar_url":"https://github.com/knowz-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KnowzCode\n\n\u003cdiv align=\"center\"\u003e\n\n**A structured development methodology for AI coding assistants.**\n\n[![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT_+_Commons_Clause-yellow.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowzcode)\n[![Version](https://img.shields.io/badge/version-0.3.4-blue)](https://github.com/knowz-io/knowzcode/releases)\n\n[Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)\n\n\u003c/div\u003e\n\n---\n\n## The Problem\n\nAI coding assistants lack structure. Without it, they:\n- Forget context between sessions\n- Make changes without considering impact\n- Declare \"done\" without verifying anything works\n- Let documentation drift from reality immediately\n\n## What KnowzCode Does\n\nKnowzCode is a **platform-agnostic development methodology** that lives in your project's `knowzcode/` directory.\n\n- **Adaptive Development Loop** — Scales from quick fixes to full 5-phase TDD workflows with quality gates at each phase\n- **Quality Gates** — Automated verification at each phase prevents broken code from advancing\n- **Living Documentation** — Architecture diagrams and specs auto-update as code changes\n- **Session Memory** — WorkGroups track complete context so nothing is lost between sessions\n- **Interruption Recovery** — Say \"continue\" to resume exactly where you left off\n- **Multi-Platform** — Works with Claude Code, Codex, Gemini, Cursor, Copilot, and Windsurf\n\n## When to Use KnowzCode\n\nKnowzCode 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:\n\n**Your agent's native mode is fine for:**\n- Single-file changes, bug fixes, small refactors\n- Tasks where \"good enough\" is good enough\n- Anything you can verify at a glance\n\n**Reach for KnowzCode when:**\n- **Outcomes aren't meeting expectations** — the agent keeps missing edge cases, breaking things, or delivering incomplete work\n- **Multi-component changes** — features that touch multiple layers (API + DB + UI + tests) benefit from impact analysis and phased execution\n- **Architecture and security matter** — quality gates catch issues before they compound\n- **You need documentation that stays current** — specs and architecture docs update as part of the workflow, not as an afterthought\n- **Enforcing standards** — personal conventions, team guidelines, or enterprise compliance rules baked into every phase\n- **Resumability** — long-running work that spans sessions, where losing context means starting over\n- **Autonomous execution** — approve specs upfront, then let the agent run; verification loops and quality gates keep output on track without constant oversight\n\nThe overhead pays for itself when the cost of getting it wrong exceeds the cost of being thorough.\n\n## How It Works\n\nEvery feature follows a structured loop with quality gates between phases:\n\n```\n  ┌──────────────────── THE KNOWZCODE LOOP ────────────────────┐\n  │                                                             │\n  │  Goal → Analyze → ✓ → Design → ✓ → Build → Audit → ✓ → Ship  │\n  │         Impact        Specs        (TDD)    Quality         │\n  │          1A            1B           2A       2B        3    │\n  │                                                             │\n  │  ✓ = approval gate (you decide whether to proceed)         │\n  └─────────────────────────────────────────────────────────────┘\n```\n\nKnowzCode automatically classifies tasks by complexity:\n- **Micro** — single-file fixes skip the loop entirely (`/kc:fix`)\n- **Light** — small changes (≤3 files) use a streamlined 2-phase path\n- **Full** — complex features get the complete 5-phase workflow above\n\nEach gate requires your approval before proceeding. See the [Workflow Reference](./docs/workflow-reference.md) for details.\n\n## Installation\n\n### Claude Code (Recommended)\n\n```bash\n/plugin marketplace add knowz-io/knowzcode\n/plugin install kc@knowzcode\ncd your-project/\n/kc:init\n/kc:work \"Build user authentication\"\n```\n\n### Alternative: Script Install\n\n```bash\nnpx knowzcode                                    # Interactive setup\nnpx knowzcode install --platforms claude,cursor   # Specific platforms\nnpx knowzcode install --platforms all             # All 6 platforms\n```\n\nCommands available as `/work`, `/plan`, `/fix` (without `kc:` prefix).\nFor `/kc:` prefix, also run: `/plugin install kc@knowzcode`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSupported Platforms (6)\u003c/strong\u003e\u003c/summary\u003e\n\n| Platform | Instruction File | Support Level |\n|----------|-----------------|---------------|\n| Claude Code | `CLAUDE.md` | Full support (plugin + agents + commands) |\n| Gemini CLI | `GEMINI.md` + `.gemini/commands/kc/*.toml` | Native `/kc:` commands + instruction file |\n| OpenAI Codex | `AGENTS.md` | Instruction file + SKILL.md format |\n| Cursor | `.cursor/rules/*.mdc` + `.cursor/commands/*.md` | Rules + commands (beta) |\n| GitHub Copilot | `.github/copilot-instructions.md` + `.github/prompts/kc-*.prompt.md` | Full support (instructions + 9 prompt files + MCP) |\n| Windsurf | `.windsurf/rules/*.md` + `.windsurf/workflows/*.md` | Rules + workflows |\n\n\u003c/details\u003e\n\n### Manual (No Node.js)\n\n```bash\ngit clone https://github.com/knowz-io/knowzcode.git\ncd KnowzCode\n./install.sh --target /path/to/your/project       # Linux/macOS\n.\\install.ps1 -Target C:\\path\\to\\your\\project     # Windows\n```\n\n### Cloud Features (Optional)\n\nConnect to KnowzCode Cloud for vector-powered semantic search, AI Q\u0026A, and learning capture via MCP. See the [Getting Started Guide](./docs/knowzcode_getting_started.md#mcp-integration-cloud-features) for setup.\n\n## Quick Start\n\n### Start a Feature\n\n```bash\n/kc:work \"Build user authentication with email and password\"\n```\n\nRuns the full loop: impact analysis → specs → TDD → audit → finalize, with approval gates between each phase.\n\n### Research First\n\n```bash\n/kc:plan \"how is authentication implemented?\"\n```\n\nExplores your codebase first. Say \"implement\" to transition into `/kc:work` with findings pre-loaded.\n\n### Quick Fix\n\n```bash\n/kc:fix \"Fix typo in login button text\"\n```\n\nTargeted fixes that skip the full loop — for typos, small bugs, and CSS tweaks.\n\n## Commands\n\n| Command | Description |\n|:--------|:------------|\n| `/kc:init` | Initialize KnowzCode in project |\n| `/kc:work \u003cgoal\u003e` | Start feature workflow |\n| `/kc:plan \u003ctopic\u003e` | Research before implementing |\n| `/kc:audit [type]` | Run quality audits |\n| `/kc:fix \u003ctarget\u003e` | Quick targeted fix |\n| `/kc:connect-mcp` | Configure MCP server |\n| `/kc:register` | Register and configure MCP |\n| `/kc:status` | Check MCP connection |\n| `/kc:learn` | Capture learnings to vault |\n| `/kc:telemetry` | Investigate production telemetry |\n| `/kc:telemetry-setup` | Configure telemetry sources |\n\n## Architecture\n\n```\nLayer 4: Platform Enhancements (optional, best experience)\n         Claude Code agents | Codex Agents SDK | Gemini Skills\n         ──────────────────────────────────────────────────────\nLayer 3: Platform Adapters (thin instruction files)\n         CLAUDE.md | AGENTS.md | GEMINI.md | .cursor/rules/*.mdc\n         ──────────────────────────────────────────────────────\nLayer 2: MCP Integration (cross-platform knowledge layer)\n         KnowzCode MCP server → vaults, search, learning capture\n         ──────────────────────────────────────────────────────\nLayer 1: Core Methodology (platform-agnostic, the actual product)\n         knowzcode/ directory → loop, specs, tracker, architecture\n```\n\nThe real product is Layer 1 — the `knowzcode/` directory. Everything else enhances it.\nOn Claude Code, Layer 4 provides 14 specialized agents (11 core + 3 opt-in specialists) with parallel orchestration.\nOn other platforms, the AI follows the same methodology directly.\nSee [Understanding KnowzCode](./docs/understanding-knowzcode.md) for a deep dive.\n\n## Execution Modes\n\n### Claude Code\n\nWhen using Claude Code, `/kc:work` automatically selects an execution strategy based on task complexity and available features:\n\n| Mode | When Used | How It Works |\n|------|-----------|-------------|\n| **Parallel Teams** | Complex features (default for \u003e3 files) | Multiple agents work concurrently — scouts gather context, builders implement in parallel, reviewer audits incrementally |\n| **Sequential Teams** | Lighter features or `--sequential` flag | One agent per phase with persistent team context |\n| **Subagent Delegation** | Agent Teams not enabled | One agent spawned per phase via fallback — works on all Claude Code instances |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAgent Teams Setup \u0026 Roster (14 agents)\u003c/strong\u003e\u003c/summary\u003e\n\nParallel 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`:\n\n```json\n{ \"env\": { \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\" } }\n```\n\nOr ask Claude Code: _\"Enable Agent Teams in my settings.\"_ Then restart. Without it, subagent delegation is used automatically.\n\n| Agent | Role | Phase |\n|-------|------|-------|\n| `context-scout` | Local context research (specs, tracker, history) | Discovery |\n| `knowz-scout` | MCP vault research (conventions, decisions) | Discovery |\n| `knowz-scribe` | MCP vault writes (learning capture, audit trails) | All phases |\n| `analyst` | Impact analysis, Change Set proposals | 1A |\n| `architect` | Specification drafting, architecture review | 1B |\n| `builder` | TDD implementation, verification loops | 2A |\n| `reviewer` | Quality audit, security review | 2B |\n| `closer` | Finalization, learning capture | 3 |\n| `security-officer` | Threat modeling, vulnerability scanning (opt-in) | All phases |\n| `test-advisor` | TDD enforcement, test quality review (opt-in) | All phases |\n| `project-advisor` | Backlog curation, future work ideas (opt-in) | Discovery–2A |\n| `microfix-specialist` | Quick targeted fixes | Utility |\n| `knowledge-migrator` | Knowledge migration between vaults | Utility |\n| `update-coordinator` | Plugin update coordination | Utility |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpt-in Specialist Agents\u003c/strong\u003e\u003c/summary\u003e\n\nActivate specialists with `--specialists` in `/kc:work` or `/kc:audit`:\n\n```bash\n/kc:work \"Build auth system\" --specialists              # All 3 specialists\n/kc:work \"Build auth system\" --specialists=security     # Security officer only\n/kc:audit --specialists                                 # Deep audit with specialists\n```\n\n- **security-officer**: Officer authority — CRITICAL/HIGH findings block gates\n- **test-advisor**: Advisory — TDD compliance, assertion quality, coverage gaps\n- **project-advisor**: Advisory — backlog ideas, tech debt tracking (shuts down mid-implementation)\n\nSpecialists communicate directly with builders (max 2 DMs each) and report findings at quality gates. Supported in Parallel Teams and Subagent modes only.\n\n\u003c/details\u003e\n\nSee the [Workflow Reference](./docs/workflow-reference.md) for detailed orchestration flows.\n\n### GitHub Copilot\n\nCopilot users invoke phases via prompt files in VS Code Copilot Chat:\n\n```bash\n#prompt:kc-work \"Build JWT authentication\"  # Start feature workflow\n#prompt:kc-specify                          # Draft specs (after Change Set approved)\n#prompt:kc-implement                        # TDD implementation\n#prompt:kc-audit                            # READ-ONLY audit\n#prompt:kc-finalize                         # Finalize and commit\n#prompt:kc-continue                         # Resume where you left off\n```\n\nGenerated by `/kc:init` into `.github/prompts/`. See `knowzcode/copilot_execution.md` for details.\n\n### Other Platforms\n\nGemini, 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.\n\n## Project Structure\n\n```\nyour-project/\n└── knowzcode/\n    ├── knowzcode_loop.md          # The methodology (TDD, quality gates, phases)\n    ├── knowzcode_project.md       # Project goals, tech stack, standards\n    ├── knowzcode_architecture.md  # Auto-maintained architecture docs\n    ├── knowzcode_tracker.md       # WorkGroup status tracking\n    ├── knowzcode_log.md           # Session history\n    ├── specs/                     # Component specifications\n    ├── prompts/                   # Phase prompt templates (works with any AI)\n    ├── workgroups/                # Session data (gitignored)\n    └── enterprise/                # Optional compliance config (gitignored, experimental)\n```\n\n## Documentation\n\n| Guide | Description |\n|:------|:------------|\n| [Getting Started](./docs/knowzcode_getting_started.md) | Walkthrough, MCP setup, file structure |\n| [Understanding KnowzCode](./docs/understanding-knowzcode.md) | Concepts and architecture deep dive |\n| [Workflow Reference](./docs/workflow-reference.md) | Phase details, execution modes, parallel orchestration |\n| [Prompts Guide](./docs/knowzcode_prompts_guide.md) | Prompt templates and command reference |\n\n## Contributing\n\nFork → branch → PR. See **[CLAUDE.md](CLAUDE.md)** for developer docs.\n\n## Acknowledgments\n\nKnowzCode 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.\n\n## License\n\nMIT License with Commons Clause — See [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**A structured development methodology for AI coding assistants.**\n\n[Get Started](#installation) · [Read the Docs](#documentation) · [Contribute](#contributing)\n\nBuilt by [Knowz](https://github.com/knowz-io)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowz-io%2Fknowzcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknowz-io%2Fknowzcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowz-io%2Fknowzcode/lists"}