KnowzCode

View saved version →

---
name: continue
description: "Resume an interrupted KnowzCode workflow. Use when the user wants to continue an active WorkGroup, load the latest local handoff, or advance the next pending phase."
---

# /knowzcode:continue — Resume workflow

Resume the most relevant active KnowzCode WorkGroup from local files. Knowz MCP is optional and never blocks resume.

## Instructions

1. Check `knowzcode/handoffs/*.md`.
   - If the user supplied a handoff path or slug, load that handoff.
   - If no explicit path was supplied, find the newest handoff by filename timestamp.
   - Handoffs are local operational state. Do not search Knowz vaults for workflow handoffs.
2. Read `knowzcode/knowzcode_tracker.md` and locate active `[WIP]` work.
3. If multiple active WorkGroups exist, ask the user which one to resume unless the selected handoff clearly names a WorkGroup.
4. Read the selected WorkGroup file.
5. If a handoff was loaded, parse `## Goal`, `## Current State`, `## Next Step`, `## References`, and `## Durable Learning Candidates`. Use the handoff as the freshest local state. Do not run `cmd:` references automatically.
6. Resume at the next ordinary step:
   - unfinished Change Set
   - spec drafting or approval
   - implementation
   - read-only audit
   - finalization
7. Keep the workflow aligned with `knowzcode/knowzcode_loop.md` and do not skip quality gates unless the user explicitly asked for autonomous execution.
8. Hand off execution to the same contract as `/knowzcode:work` for the current phase.

View saved version →

---
name: explore
description: "Research a codebase area before implementation. Use when the user wants investigation, architectural context, prior art, or options before changing code."
---

# /knowzcode:explore — Research before implementing

Investigate a topic and stop with findings and recommendations. Knowz MCP is optional and never blocks exploration.

## Instructions

1. Classify the exploration question and resolve any selected WorkGroup, capsule, reusable specification, and current phase **before vault retrieval, parallel delegation, or file writes**. Record the exact unresolved question and relevant subsystem boundaries.
2. Load context progressively. Start with that selected WorkGroup/capsule and goal-relevant spec headings/`VERIFY:` criteria. If neither exists, search the topic first; read only the relevant project, architecture, spec, or prior-WorkGroup sections needed to answer the recorded question.
3. Search the codebase for relevant files and patterns using targeted reads.
4. If the topic spans 2 or more independently useful subsystems, parallelize read-only explorers within the active runtime's capacity. Do not create overlapping scopes and do not implement code in this mode.
5. If the local evidence leaves a named prior-decision or convention question **and** Knowz MCP is available, use a targeted `mcp__knowz__search_knowledge` or `mcp__knowz__ask_question` call. Do not issue a broad baseline vault query. If tools are missing, continue with local evidence only.
6. Produce the **Exploration Deliverable** in chat. Write it to `knowzcode/explore/<topic-slug>/summary.md` only when writes are authorized and durable exploration output is requested or materially useful for recovery.
7. Do not implement changes unless the user explicitly asks to move into `/knowzcode:work` or `/knowzcode:fix`.

## Parallel explorer dispatch

Each explorer must:

- Receive exactly one subsystem boundary. No two explorers share files.
- Stay read-only — do not edit or implement code.
- Default to `ephemeral` output (bounded findings in chat). Use `durable` files only when writes are authorized and recovery needs them.

Skip parallel dispatch when the topic touches a single subsystem.

## Exploration Deliverable

```markdown
# Exploration: {topic}

## Current State
{what exists today, with file:line citations}

## Constraints
{rules, conventions, dependencies that must hold}

## Options
1. {option name} — {one-paragraph description}
2. {option name} — {one-paragraph description}

## Risks
{risk → mitigation, one per bullet}

## Recommendation
{one option from the list above, with rationale}

## Suggested Next Skill
{`/knowzcode:work` for full build or `/knowzcode:fix` for a single-file change — pick one}
```

The `<topic-slug>` is the topic in 2-4 word kebab-case.

View saved version →

---
name: fix
description: "Apply a quick, targeted KnowzCode micro-fix. Use when the requested change is small, localized, and does not need the full multi-phase workflow."
---

# /knowzcode:fix — Micro-fix

Use the KnowzCode micro-fix path for small, contained changes. Knowz MCP is optional and never blocks a fix.

## Instructions

1. Confirm the change is narrow in scope: typically one file, low ripple, under roughly 50 lines.
2. Read the micro-fix guidance in `knowzcode/knowzcode_loop.md` if available.
3. Implement the fix.
4. Run the smallest meaningful verification set for the touched behavior.
5. Prepend a `MicroFix` entry to `knowzcode/knowzcode_log.md` describing the request, action, and verification outcome.
6. If the work grows beyond micro-fix scope, stop and move to `/knowzcode:work`.

View saved version →

---
name: regroup
description: "Create a local KnowzCode handoff before clearing context. Use when the user wants to pause, wrap up, step away, clear context, or resume an active WorkGroup later without losing workflow state."
---

# /knowzcode:regroup — Local workflow handoff

**Purpose**: Preserve local workflow continuity before the user clears context. Regroup writes operational state to KnowzCode local files. It does not store session handoffs in Knowz vaults.

Knowz MCP is optional and never blocks regroup.

## Ownership boundary

- KnowzCode owns workflow state: active WorkGroup, phase, branch, dirty files, blockers, next steps, autonomy mode, and resume instructions.
- Knowz owns durable knowledge: decisions, patterns, workarounds, conventions, architecture findings, audit findings, and completion records.
- Do not write the handoff itself to Knowz. If durable learnings are discovered, list them as extraction candidates or route them through `/knowz-save`.

## Instructions

### Step 1: Prerequisite check

1. Check that `knowzcode/` exists.
2. Check for `knowzcode/knowzcode_tracker.md`.
3. If missing, stop and suggest `/knowzcode:setup`.

### Step 2: Resolve WorkGroup

1. If the user supplied a WorkGroup ID or path, use it.
2. Else read `knowzcode/knowzcode_tracker.md` for active `[WIP]` entries.
3. If one active WorkGroup exists, use it.
4. If multiple active WorkGroups exist, choose the one clearly referenced by the current session; otherwise ask the user to choose.
5. If none exist, create a standalone handoff with `WorkGroupID: none` and point the user toward `/knowzcode:work` after resume.

Read the selected WorkGroup file when available: `knowzcode/workgroups/{WorkGroupID}.md`.

### Step 3: Collect local resume state

Keep it dense and actionable:

- Goal and current phase
- Completed work or findings
- Current blockers and unresolved questions
- Next step from the user's argument, if supplied
- Active autonomy mode: `Active` | `Inactive` | `Unspecified`
- Important files, commands, and references
- Current branch, commit, and dirty-file summary from `git branch --show-current`, `git rev-parse --short HEAD`, and `git status --short`

Do not paste raw transcript text.

### Step 4: Write handoff file

Create `knowzcode/handoffs/` if it does not exist. Write:

```text
knowzcode/handoffs/{YYYYMMDD-HHMM}-{slug}.md
```

Use a 2-5 word kebab-case slug from the goal or WorkGroup. If a file already exists, append `-2`, `-3`, etc.

```markdown
# KnowzCode Handoff: {short goal}

**Created:** {ISO timestamp}
**WorkGroupID:** {id or none}
**WorkGroup File:** {path or none}
**Current Phase:** {phase or unknown}
**Autonomous Mode:** {Active|Inactive|Unspecified}
**Branch:** {branch}
**Commit:** {short sha}
**Status:** Active

## Goal
{exact goal to resume}

## Session Summary
{<=100 words}

## Current State
{completed work, current status, blockers; <=180 words}

## Next Step
{immediate next actions; <=80 words}

## Dirty Files
{git status --short summary; omit generated noise unless relevant}

## References
- file:{path} | {why useful}
- cmd:{command} | {why useful}
- kz:{knowledge-id} | {title} | {why useful}
- url:{href} | {why useful}

## Durable Learning Candidates
{Only decisions, patterns, workarounds, conventions, architecture findings, audit findings, or completion records that may belong in Knowz. Use "None" if there are no durable learnings.}

## Fresh Context Prompt
Resume this KnowzCode work.

Read:
- {handoff path}
- {WorkGroup file or "no active WorkGroup"}
- knowzcode/knowzcode_loop.md

Goal: {goal}
Continue from the saved state. Preserve Autonomous Mode only if the user confirms it in the new session.
```

### Step 5: Link from WorkGroup

If an active WorkGroup file exists, append or update a `## Handoffs` section with:

```markdown
- {timestamp}: `knowzcode/handoffs/{file}.md` - {next step summary}
```

### Step 6: Durable knowledge extraction

Do not save the whole handoff to Knowz.

For `## Durable Learning Candidates`:

- Include only durable learnings that should survive outside this local workflow.
- If no capture path is active, leave candidates in the handoff for Phase 3 capture or explicit `/knowz-save`.
- If MCP is unavailable, do not block regroup. The local handoff is the primary artifact.

### Step 7: Report

```markdown
KnowzCode handoff saved.

Path: {handoff path}
WorkGroup: {id or none}
Next: {next step}
Autonomous Mode: {Active|Inactive|Unspecified}
```

Then provide the `Fresh Context Prompt` from the file for copy/paste.

## Related skills

- `/knowzcode:continue` — Load the latest handoff or active WorkGroup and resume
- `/knowzcode:work` — Start a WorkGroup if there is no active workflow
- `/knowz-save` — Capture durable learnings, not workflow handoffs (requires the Knowz plugin)

View saved version →

---
name: regroup-trigger
description: "Detect pause, wrap-up, handoff, or clear-context intent and offer a KnowzCode regroup handoff. Triggers when the user says they need to stop, step away, clear context, start fresh, hand off, or resume later."
---

# KnowzCode Regroup Trigger — Intent router

Use this as a lightweight router into `/knowzcode:regroup`. It never writes handoffs directly.

## Instructions

1. Trigger only when the user's message clearly signals pause, wrap-up, handoff, or context clearing:
   - "wrap up", "pause here", "stop here"
   - "I need to step away", "take a break"
   - "clear context", "new context", "fresh session", "start a new chat"
   - "handoff", "resume later", "continue later", "pick this back up"
   - "context is getting long", "summarize so we can continue later"
2. Do not trigger for normal questions or active implementation requests.
3. Do not trigger during explicit `/knowzcode:*` or `/knowz` command execution.
4. Check that `knowzcode/` exists. If not, do nothing.
5. Read `knowzcode/knowzcode_tracker.md` when available to detect active WorkGroups, but do not block if the read fails and the user's handoff intent is explicit.
6. Offer exactly once:
   ```text
   This looks like a good checkpoint. Want me to run `/knowzcode:regroup` with the current goal and next step so you can resume cleanly after clearing context?
   ```
7. If the user agrees, hand off to the same workflow as `/knowzcode:regroup`, passing any explicit next-step hint.
8. If the user declines or ignores the offer, do nothing.
9. Never auto-regroup, never save workflow state to Knowz, and never write the handoff directly from this trigger.

View saved version →

---
name: setup
description: "Initialize KnowzCode in a repository for Grok Bot and Cursor: framework files, project personalization, and the Cursor rule. Knowz MCP is optional and never blocks setup."
---

# /knowzcode:setup — Initialize KnowzCode

Initialize the KnowzCode framework in the current project. Grok Bot Plugins and Cursor Marketplace are the same catalog — do not treat this as Cursor-IDE-only.

Knowz MCP is **optional**. Never block setup, personalization, or success reporting on missing Knowz tools.

## Instructions

1. Resolve the repository root as an absolute path and check whether `knowzcode/` already exists there.
   - If it does, ask whether to merge, refresh, or stop.
2. Bootstrap through the published CLI rather than assuming this skill can find a plugin-relative framework directory:
   - Fresh repository: `npx --yes knowzcode install --target "{absolute-repository-root}" --platforms cursor --force`
   - Approved refresh: `npx --yes knowzcode upgrade --target "{absolute-repository-root}" --force`
   - Adapter-only merge: `npx --yes knowzcode add-platforms --target "{absolute-repository-root}" --platforms cursor --force`
   Never substitute the current home/global skill directory for the repository target. Verify the CLI exits successfully and that `knowzcode/knowzcode_loop.md` exists before personalization.
3. Preserve user-authored project files. The CLI's ownership marker and manifest control which Cursor surfaces it may update (including `.cursor/rules/knowzcode.mdc`).
4. Detect the project stack and write the Stack table in `knowzcode/knowzcode_project.md` with the concrete language, framework, test runner, and build details. Probe for `package.json` (Node/TS), `pyproject.toml` / `requirements.txt` (Python), `*.csproj` / `*.sln` (.NET), `go.mod` (Go), `Cargo.toml` (Rust), `Gemfile` (Ruby). Leave table cells empty if detection fails — do not write `[Detected]` placeholders.
5. Run three personalization gates. Each is skippable; when declined, write `Not configured during init — edit this file or re-run /knowzcode:setup to fill.` into the relevant section instead of leaving the template's bracketed placeholders.
   - **Gate A (`knowzcode_project.md`):** Ask for (1) project name + one-sentence goal, (2) core problem, (3) architecture style. Rewrite the `## Goal` and `## Architecture` sections with the answers. Leave the Stack table alone — step 4 handles it.
   - **Gate B (`knowzcode_architecture.md`):** Do not generate a diagram. The file ships with an empty Mermaid stub — leave it and tell the user "Architecture will be populated on first /knowzcode:work or when you ask for a sketch."
   - **Gate C (`user_preferences.md`):** Ask for (1) testing framework + coverage target, (2) code style / formatter, (3) top-3 quality priorities ranked, (4) non-negotiable project conventions (optional). Rewrite the file with real answers; strip the `*Examples:*` blocks from the filled copy; update `Last Updated` to the current ISO timestamp.
6. Confirm `.cursor/rules/knowzcode.mdc` exists after install. This plugin also ships `rules/knowzcode.mdc` so Grok Bot and Cursor agents get the same methodology without a local copy.
7. If the user also wants team memory, mention the **Knowz** plugin as a **separate** install (do not merge it into this workflow): Grok Bot Plugins or Cursor Marketplace → search **Knowz** → **Add** → **Authorize**. Do not run `/knowz register` on an existing account. Do not paste API keys.
8. End by suggesting `/knowzcode:work`, `/knowzcode:explore`, and `/knowzcode:fix`. Setup succeeds even when Knowz MCP is absent.

View saved version →

---
name: start-work
description: "Route implementation intent into KnowzCode workflow mode. Use for 'start building', 'go ahead', 'implement this plan', or 'build this now' requests."
---

# KnowzCode Start Work — Intent router

Use this as a lightweight router into `/knowzcode:work`.

## Instructions

1. Trigger only when the user's message clearly expresses implementation intent such as "implement this plan", "go ahead", "start work", "build this now".
2. Do not trigger for questions, hypotheticals, or pure discussion.
3. Recover the best available goal from:
   - the user's current message
   - a recently discussed plan or investigation in the thread
   - an active WorkGroup in `knowzcode/workgroups/`
4. Summarize the goal in one sentence and hand off to `/knowzcode:work` using the contract below.
5. If there is not enough context to identify the goal safely, ask the user what should be implemented.

## Handoff payload

When invoking `/knowzcode:work`, pass a structured payload so the workflow can skip re-discovery:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `goal` | string | yes | One-sentence imperative summary of what to build |
| `source_path` | string | no | Path to the plan or investigation file the goal came from |
| `tier` | `"micro" \| "light" \| "full"` | no | Pre-classified scope hint; `/knowzcode:work` may override |
| `flags` | string | no | Pass-through flags such as `--autonomous` or `--tier full` |
| `prior_findings_summary` | string | no | 2-3 sentences summarizing key constraints/decisions from the source |

Always include `goal`. Include `source_path` whenever a plan/investigation was the trigger.

View saved version →

---
name: status
description: "Check KnowzCode project health, active work, and pending captures. Use for status, setup verification, or troubleshooting. Knowz MCP is optional."
---

# /knowzcode:status — Project status

Report local KnowzCode health without starting or resuming work. Knowz MCP is optional and never blocks this report.

## Instructions

1. Check whether `knowzcode/` exists and whether the core files are present.
2. Inspect `knowzcode/knowzcode_tracker.md` for `[WIP]`, `[VERIFIED]`, and planned work.
3. Count active and completed WorkGroups in `knowzcode/workgroups/` if that directory exists.
4. Count queued items in the project-root `knowz-pending.md` when present. If legacy `knowzcode/pending_captures.md` exists, report it separately as migration input; do not count it as a second active queue.
5. If Knowz MCP is available, call `mcp__knowz__list_vaults` with `includeStats: true` and report vault availability. If not, report that Knowz enhancement is unavailable and the local workflow still works. Do not tell the user to paste an API key or run `/knowz setup <api-key>`.
6. End with one practical action: initialize, continue work, flush captures, or (only if they want vaults) open Grok Bot Plugins / Cursor Marketplace → search **Knowz** → **Add** → **Authorize**.

## Output format

```text
## KnowzCode Status

Framework: {Initialized | Not initialized}
  Core files: {N}/4 present (loop, tracker, project, architecture)
Tracker: {W} WIP, {V} verified, {P} planned
WorkGroups: {A} active, {C} completed
Pending captures: {Q} queued
MCP & vaults: {Connected — N vault(s) | Not connected (optional — workflow still works)}

Next: {one concrete suggested action}
```

Omit non-applicable lines. Keep secrets out of the report.

View saved version →

---
name: work
description: "Start a structured KnowzCode workflow for feature work, multi-file changes, or meaningful refactors with TDD and quality gates. For single-file changes under ~50 lines use /knowzcode:fix; for read-only research use /knowzcode:explore."
---

# /knowzcode:work — Structured workflow

Run the KnowzCode methodology from the current Grok Bot or Cursor agent. Knowz MCP is optional and **never blocks** this workflow.

## Instructions

1. Verify the project is initialized by checking for, but do not eagerly read:
   - `knowzcode/knowzcode_loop.md`
   - `knowzcode/knowzcode_project.md`
   - `knowzcode/knowzcode_tracker.md`
   - `knowzcode/knowzcode_architecture.md`
   If missing, suggest `/knowzcode:setup` and stop unless the user wants a one-off micro-fix (`/knowzcode:fix`).
2. Classify the request **before any vault retrieval, worker delegation, WorkGroup write, or other side effect**:
   - Micro fix → use `/knowzcode:fix`.
   - Light change → streamlined change set, reusable or focused spec, implementation, verification.
   - Full change → Phase 1A, 1B, 2A, 2B, 3.
   - Inspect only the selected active WorkGroup/capsule, the tracker slice needed to select one, and goal-relevant spec headings/`VERIFY:` criteria.
3. Load context progressively:
   - Start with an explicitly selected active WorkGroup or compact context capsule and the current phase contract.
   - If no WorkGroup is selected, inspect the tracker only far enough to resolve active work, then read the project/architecture file only for a concrete planning question.
   - Read only assigned specs, `VERIFY:` criteria, and relevant source paths for the current phase.
4. Discover applicable enterprise guidance after classification (local files first):
   - Read `knowzcode/enterprise/compliance_manifest.md` if present.
   - Do compliance work only when `compliance_enabled: true` (default false).
   - The vault flow additionally requires `mcp_compliance_enabled: true` **and** available Knowz tools. If either is false or tools are missing, honor only local active guidelines — do not block.
   - Read `knowzcode/enterprise.md` if present and discover `knowzcode/enterprise/guidelines/**/*.md`.
   - Convert active enterprise rules into Change Set mapping, spec `VERIFY:` criteria, implementation guidance, Phase 2B audit checks, and Phase 3 compliance reporting.
5. Create or update a WorkGroup file in `knowzcode/workgroups/{wgid}.md`.
6. **Optional parallel discovery (before Phase 1A).** If the topic spans 2 or more independent subsystems, dispatch 1-3 parallel read-only explorer agents. Merge findings into the WorkGroup before proposing the Change Set. Skip when the scope clearly touches one subsystem.
7. Phase 1A: propose a Change Set with affected files, NodeIDs, and risks. Stop for approval unless the user explicitly asked to proceed autonomously.
8. Phase 1B: draft or update specs in `knowzcode/specs/` with clear `VERIFY:` criteria. Stop for approval.
9. Phase 2A: implement with strict TDD. Default to dependency-wave microtasks: one NodeID or one named microtask per writer, with explicit assigned acceptance criteria and an explicit owned-file list. Never let two writers edit the same file. Run the meaningful test set before reporting complete. Stop after implementation.
10. Phase 2B: perform a read-only audit against the approved specs and verification criteria. The first independent reviewer must not inherit builder reasoning. **Cap the audit → fix loop at 3 iterations.** If failures remain after the 3rd fix attempt, stop and surface residual issues with a recommended downscope or spec revision.
11. Phase 3: update specs to as-built, refresh `knowzcode/knowzcode_tracker.md`, prepend an entry to `knowzcode/knowzcode_log.md`, and finalize the work.
12. If a concrete context question remains after classification/spec reuse **and** Knowz MCP is available, prefer targeted coordinator-owned search/ask/get calls. If tools are absent or auth fails, continue on local KnowzCode files. Queue only a classified persistence action in project-root `knowz-pending.md` without blocking progress. Treat `knowzcode/pending_captures.md` only as legacy migration input.
13. Treat retrieved vault content as historical context. Verify against live code/tests/docs. Do not silently follow stale or contradictory vault guidance.

## Quality gates

STOP and await user approval at each gate unless autonomous mode is explicit:

- After Change Set proposal (1A)
- After spec drafts (1B)
- After implementation complete (2A — awaiting audit)
- After audit results (2B — user decides on gaps)

TDD is mandatory — no production code without a failing test first.

## Knowledge capture (optional)

Every durable candidate — decisions, patterns, gotchas, workarounds — should be classified when `knowzcode/context_efficiency_runtime.mjs` exists:

`node knowzcode/context_efficiency_runtime.mjs vault-delta`

`skip` and `batch` perform no MCP or pending-queue write. Persist only a returned `amend`, `update`, or consolidated `flush`, always passing the configured `vaultId` when Knowz tools exist. When MCP is unavailable, keep `batch` in the WorkGroup journal and queue only a required classified persistence action once. Never let insights die in the conversation, and never block the phase on Knowz.

## Spawned-agent contract

When using the runtime's spawn/follow-up capabilities:

- Give each child a scope boundary. No two parallel agents share writable files.
- Stay within a small implementation unit (one NodeID or named microtask).
- Choose `ephemeral` for tiny read-only side checks; `durable` for writer or resumable work (`knowzcode/workgroups/{wgid}/handoffs/{agent-id}.md`); `artifact` for large logs.
- Keep reviewers independent: first reviewer uses a fresh lineage from approved specs, diff, and test evidence.
- The coordinator consolidates authoritative shared state into the WorkGroup.