KnowzCode

Structured AI Development.

What You Get · How It Works · Install · Quick Start · Platforms · Privacy

AI coding assistants lack structure. Without it, they forget context between sessions, skip tests, make changes without considering impact, and declare "done" without verifying anything works.

KnowzCode brings discipline to AI-assisted development — quality gates, test-driven workflows, and session continuity that keeps complex projects on track.

What You Get

• Quality gates that catch issues before they compound
• Tests written before code, verified against requirements
• Living documentation that updates as code changes
• Session continuity — pick up exactly where you left off, even days later
• Complexity-aware — quick fixes skip ceremony, complex features get full rigor
• Works on 6 AI platforms — not locked to any single tool
• Connected to your knowledge base — past decisions inform future work (optional)
• Autonomous mode — approve the plan upfront, then let the AI run with safety guardrails

When to Use It

KnowzCode adds overhead. Here's when it's worth it:

Your agent's native mode is fine for: single-file changes, small refactors, anything you can verify at a glance.

Reach for KnowzCode when:

• Outcomes aren't meeting expectations — the agent keeps missing edge cases or delivering incomplete work
• Multi-component changes — features that touch API + database + UI + tests
• Architecture and security matter
• You need documentation that stays current
• Long-running work that spans sessions

The overhead pays for itself when the cost of getting it wrong exceeds the cost of being thorough.

How It Works

  Goal → Analyze → ✓ → Design → ✓ → Build & Test → Audit → ✓ → Ship

  ✓ = approval gate (you decide whether to proceed)

| Step | What Happens | |------|-------------| | Analyze | Scans your codebase for impact — what files change, what could break, what patterns to follow | | Design | Drafts specifications with requirements and test criteria. You review before any code is written | | Build & Test | Tests first, then code. Verification loops catch regressions | | Audit | Quality review covering code quality, security, test coverage, and adherence to your standards | | Ship | Commits, updates documentation, and captures learnings |

KnowzCode automatically classifies tasks by complexity:

| Tier | When | What Happens | |------|------|-------------| | Quick Fix | Single file, small bug | Skips the loop. Fix, verify, done | | Light | 3 files or fewer | Streamlined two-step path | | Full | Complex features | Complete loop with all gates |

Execution Profiles (advisor / teams / classic / frontier)

KnowzCode on Claude Code supports four execution profiles that trade cost, quality, and parallelism. frontier is the default (Fable plans/specs/reviews, Opus builds). The choice is yours and asked exactly once: /knowzcode:setup asks during setup, and if no profile: is configured, the first /knowzcode:work asks and saves your answer to knowzcode/knowzcode_orchestration.md — no run ever re-asks. Set profile: teams (or --profile=teams) any time to opt out of frontier's Fable cost.

| Profile | When to Use | Mode | Requires | |---------|-------------|------|----------| | frontier (default) | Fable plans/specs/reviews every change; Opus executes. The most capable planning, at higher cost; auto-falls back to Opus if Fable is unavailable. | Parallel / Sequential / Subagent (your choice) | Direct Anthropic API (or Claude Platform on AWS) for Fable | | teams | Opt OUT of frontier's Fable cost — all agents use their frontmatter defaults (mostly Opus). No external dependencies. | Parallel / Sequential / Subagent (your choice) | Any Claude Code version, any provider | | advisor | Cost-sensitive work where Sonnet + advisor-tool is acceptable quality. ~12% cheaper on coding tasks (per Anthropic benchmarks). | Parallel Teams (forced) | Claude Code v2.1.100+, direct Anthropic API | | classic | Agent Teams unavailable, or you want deterministic single-threaded execution. | Subagent Delegation (forced) | — |

How the advisor profile works

Claude Code's advisor tool lets a Sonnet-based agent consult Opus mid-generation within a single API call. Under advisor profile, the agents listed below switch to Sonnet and get an advisor-guidance block in their spawn prompt:

| Agent | advisor | teams | classic | |-------|-----------|---------|-----------| | architect, analyst, security-officer, enterprise-enforcer | opus | opus | opus | | builder, reviewer, closer, smoke-tester, microfix-specialist, frontend-designer | sonnet | opus | opus | | knowledge-liaison, test-advisor, project-advisor | sonnet | sonnet | sonnet | | knowledge-migrator, update-coordinator (utility) | opus | opus | opus |

Strategic agents (architect, analyst, security-officer, enterprise-enforcer) stay on Opus — the advisor tool adds no value where the whole task is reasoning.

How the frontier profile works

frontier routes the reasoning-heavy phases to Fable and the build to Opus:

| Agent | frontier | |-------|-----------| | analyst, architect, reviewer, security-officer, test-advisor, project-advisor, enterprise-enforcer | fable | | builder, closer, smoke-tester, frontend-designer, microfix-specialist, knowledge-migrator, update-coordinator | opus | | knowledge-liaison | sonnet |

The idea: Fable produces an exhaustive, per-change specification (every change enumerated, each with a dedicated VERIFY criterion), then Opus — itself state-of-the-art at agentic execution — implements against it. You get frontier judgment on both ends (Fable writes the spec at Gate #2 and audits the build as reviewer at Gate #3) without paying Fable's premium on the highest-token phase, building. /knowzcode:explore also runs its research agents on Fable under this profile.

For the rare job where the implementation itself needs frontier reasoning, add --fable-execution (or set execute_on_fable: true) to run the execution agents on Fable too.

Configure

In knowzcode/knowzcode_orchestration.md:

profile: frontier    # default; or: teams, advisor, classic

Or override per-invocation:

/knowzcode:work "build X" --profile=advisor
/knowzcode:work "build critical auth flow" --profile=frontier
/knowzcode:audit --profile=teams

Graceful fallback

When profile: advisor is set but the environment can't support the advisor tool (e.g., CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, or ANTHROPIC_BASE_URL pointing to Bedrock/Vertex/custom endpoints), /work and /audit automatically fall back to teams with a clear message. Your workflow proceeds — you just don't get the cost savings.

Similarly, profile: frontier requires Fable, which runs on the direct Anthropic API (or Claude Platform on AWS) and needs 30-day data retention. If Fable is unavailable (e.g. ANTHROPIC_BASE_URL pointing at Bedrock/Vertex/Foundry), the planning/review agents fall back to Opus with a clear message and the run proceeds as an all-Opus flow.

Conflicts

--profile=advisor with --sequential or --subagent is an error: the advisor profile requires Parallel Teams. Remove the conflicting flag, or choose --profile=teams if you want sequential/subagent execution.

Roll back

Delete the profile: line from knowzcode/knowzcode_orchestration.md (or omit --profile on the CLI) to use the default (frontier). To restore the pre-0.19 all-Opus behavior, set profile: teams. No migration needed.

Cross-Agent Relay (experimental)

Let the current host plan, specify, review, and finalize while the other coding agent implements. From Claude Code the default external target is the OpenAI Codex CLI; from Codex the default external target is the Claude Code CLI. The target completes Phase 2A headlessly, the host reviews the checkpoint diff at Gate #3, the target resumes for bounded fix rounds, and the host takes over any remaining fixes after the configured cap.

Target resolution is deterministic: explicit --relay= flag → unambiguous natural language → project relay: configuration → /knowzcode:relay defaults to other. Ordinary /knowzcode:work remains native when none of those enable relay. auto and other select the opposite supported host; an explicitly named same-host target is an error and is never silently reversed.

Requirements: the selected target CLI must be installed and authenticated. For a Codex target, install Codex and run codex login. For a Claude target, install Claude Code and run claude auth login. Missing automatic/configured targets visibly fall back to native Phase 2A; explicitly named unavailable targets and authentication failures stop with remediation.

Enable it with flags, natural language, or portable project configuration:

/knowzcode:relay Add rate limiting to the API      # targets the other agent
/knowzcode:work --relay=other <goal>               # portable explicit selection
/knowzcode:work --relay=claude <goal>              # literal Claude target
/knowzcode:work --relay=codex <goal>               # literal Codex target (v0.20 compatible)
/knowzcode:work have Claude implement the approved plan
# or set `relay: other` in knowzcode/knowzcode_orchestration.md

Tuning uses generic per-invocation --relay-model=, --relay-effort=, and --relay-max-fix-rounds=N overrides plus provider-specific config (relay_codex_*, relay_claude_*) and shared relay_transport, relay_max_fix_rounds, and relay_timeout_minutes. Existing v0.20 relay_model/relay_effort/relay_fix_effort/relay_sandbox keys remain Codex-target fallbacks.

Transports: Codex targets use the synchronous codex mcp-server transport when registered, otherwise codex exec. Claude targets use claude -p with streaming JSONL and explicit --resume; claude mcp serve is not an agent-delegation transport. Both exec adapters poll inside the active orchestrator turn—never a background wake-up—and persist the provider session ID as soon as it appears.

Safety model: relay runs on a dedicated kc-relay/{wgid} branch, never the default branch, with a clean C0 baseline. The target never commits; the host checkpoints each completed leg. Codex uses workspace-write with approvals disabled. Claude uses dontAsk, a bounded implementation tool set, strict Bash sandboxing, strict MCP configuration, and never defaults to bypassing permissions. Schema-2 state records host, target, role state, and session ID in knowzcode/workgroups/{wgid}-relay/state.md; /knowzcode:continue also reads legacy v0.20 Codex state.

Constraints: Tier 3 workflows only; incompatible with --profile advisor; supported hosts are Claude Code and Codex. Gemini remains native-only because “other” is ambiguous there. Full protocol: knowzcode/skills/work/references/relay-execution.md.

Enterprise Compliance & Custom Guidelines

Beta. Wire your organization's own guidelines — security rules, API conventions, code-quality patterns, accessibility/design standards — into the workflow so they're enforced at the same quality gates you already approve.

You author guidelines as markdown, register them in a manifest, and a persistent enterprise-enforcer officer injects the required checks into specs and blocks the audit gate on violations of anything you mark blocking.

knowzcode/enterprise/
├── compliance_manifest.md     # master switch + which guidelines are active
├── guidelines/
│   ├── security.md            # ships with real rules
│   └── custom/                # your org's guidelines go here
└── templates/guideline-template.md

Three steps to turn it on:

1. Author a guideline from templates/guideline-template.md (or edit security.md).
2. Register it in the manifest's Active Guidelines table with Active: true.
3. Set compliance_enabled: true, then run /knowzcode:audit compliance to verify.

Guidelines are blocking (violations stop the workflow) or advisory (reported only). It's opt-in and off by default. Full guide: docs/enterprise-compliance.md.

Note: the white-label enterprise.json (brand + MCP/API endpoints) is a separate feature, unrelated to compliance guidelines.

Install

# Claude Code (recommended)
/plugin marketplace add knowz-io/knowz-skills
/plugin install knowzcode@knowz-skills
cd your-project/
/knowzcode:setup

# All platforms
npx knowzcode                                    # Interactive setup
npx knowzcode install --platforms claude,gemini   # Specific platforms
npx knowzcode install --platforms all             # All 6 platforms

Quick Start

# Build a feature (full loop)
/knowzcode:work "Build user authentication with email and password"

# Research first, build later
/knowzcode:explore "how is authentication implemented?"

# Quick fix (skips the loop)
/knowzcode:fix "Fix typo in login button text"

# Save local resume state before clearing context
/knowzcode:regroup "Continue from the active WorkGroup after context clear"

# Resume where you left off — just say "continue"

KnowzCode can also offer regroup automatically when you say things like "wrap up", "clear context", "step away", or "resume this later". The trigger only asks; it never writes a handoff without approval.

Commands

| Command | Description | |---------|-------------| | /knowzcode:work <goal> | Start a feature workflow | | /knowzcode:explore <topic> | Research before implementing | | /knowzcode:fix <target> | Quick targeted fix | | /knowzcode:relay <goal> | Cross-agent relay: the host plans/reviews while the resolved external agent implements | | /knowzcode:regroup [next step] | Save a local handoff for clearing context | | /knowzcode:regroup-trigger | (Trigger) Detects pause/wrap-up intent and offers regroup | | /knowzcode:start-work | (Trigger) Detects "implement the plan" intent and invokes /knowzcode:work | | /knowzcode:audit [type] | Run quality audits (spec, architecture, security, integration, compliance) | | /knowzcode:setup | Initialize in your project | | /knowzcode:status | Check project status | | /knowzcode:telemetry | Investigate production errors | | /knowzcode:telemetry-setup | Configure telemetry sources (Sentry, App Insights) |

Platform Support

Full support:

| Platform | Install | |----------|---------| | Claude Code | /plugin install knowzcode@knowz-skills | | OpenAI Codex | npx knowzcode install --platforms codex | | Gemini CLI | npx knowzcode install --platforms gemini |

Experimental:

| Platform | Install | |----------|---------| | GitHub Copilot | npx knowzcode install --platforms copilot | | Cursor | npx knowzcode install --platforms cursor | | Windsurf | npx knowzcode install --platforms windsurf |

Connected to Knowz

KnowzCode optionally connects to Knowz for persistent knowledge across projects:

• Past decisions are searchable — "Why did we choose JWT over sessions?" gets a real answer
• Learnings captured automatically as you work
• Conventions from one project inform work on another

Works fully without Knowz. The connection adds memory, not dependency.

Privacy & Support

KnowzCode stores workflow state in local project files by default. It only sends data to Knowz when the user has configured Knowz and chooses a workflow that queries or writes vault knowledge. Telemetry workflows only connect to user-configured telemetry providers.

• Privacy policy: ../PRIVACY.md and https://knowz.io/privacy
• Support contact: [email protected]
• Security reports: ../SECURITY.md
• Status: https://status.knowz.io

Acknowledgments

KnowzCode builds upon ideas from the Noderr project by @kaithoughtarchitect.

License

MIT License — See LICENSE for details.

Full capabilities · Documentation · knowz.io