zcode-starterkit

Bootstrap package for the ZCode Agent — installs a curated baseline of skills, commands, agents, hooks, and MCP tools as ZCode plugins.

# Install globally from GitHub (requires repository access)
npm install -g github:cong91/zcode-starterkit

Then inside any project: /setup to materialize the .zcode/ overlay.

/init is reserved by ZCode's built-in project initializer. Starterkit project onboarding uses /setup so the full overlay, Beads, Codebase-Memory, wiki, and AGENTS.md workflow is not shadowed by the built-in command.

v-claw providers

The installer registers two providers without setting a global default model:

• vc-cheap — lower-cost v-claw-compatible models: glm-5.2, hy3-preview, kimi-k2.7-code, deepseek-v4-pro, qwen3.7-max, mimo-v2.5-pro, minimax-m3.
• vc-codex — Responses/Codex models: gpt-5.4, gpt-5.4-mini, gpt-5.5, gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, codex-auto-review.

The review and verify agents use vc-codex/codex-auto-review when vc-codex matches the starterkit-managed provider fingerprint. After installing, add the two API keys:

zcode-starterkit setup-vclaw

The command masks interactive input, verifies provider fingerprints before sending credentials, validates both model catalogs, backs up ~/.zcode/v2/config.json, and preserves unrelated config. For non-interactive setup, set VCLAW_API_KEY and VCLAW_CODEX_API_KEY. Use --skip-vclaw-verify only when the v-claw service is temporarily unavailable.

Uninstall removes fingerprint-matching vc-cheap/vc-codex providers, exact ownership-recorded starterkit MCP entries, and the dedicated setup-vclaw backup directory. Same-ID user providers, same-name user MCP servers, and unrelated plugin registrations are preserved; removing the agents-config plugin removes the projected native review/verify profiles.

What you get

Four plugins installed globally under ~/.zcode:

| Plugin | Contents | |---|---| | core | 144 curated skills + 31 commands + project templates + validated workflow recipes | | agents-config | 15 native agent profiles: 14 general workflow roles plus explicit-only reverse + qualified routing registry + eval policy | | mcp-tools | 27 MCP tools (code search, memory + admin + graph, sessions, srcwalk navigation, skill MCP calls/status, swarm coordination) | | hooks | 7 runtime hooks (guard, prompt router, intent→skill mapping, memory capture) |

Workflow Recipes

The core plugin provides validated, read-only recipes for /audit <pattern> and /research <topic> --thorough. Commands remain the execution owners; a project may override a recipe at .zcode/workflows/<recipe>.json. batch-implement, development-lifecycle-workflow, and garbage-collection remain packaged Markdown references and are not executable recipes.

Skills (144)

Covers the full development lifecycle: plan → build → verify → ship.

| Domain | Key skills | |---|---| | Planning | planning-and-task-breakdown, prd, prd-task, spec-driven-development | | Building | incremental-implementation, frontend-design, react-best-practices, api-and-interface-design | | Verifying | debugging-and-error-recovery, code-review-and-quality, verification-gates, testing-anti-patterns | | Shipping | shipping-and-launch, vercel-deploy-claimable, ci-cd-and-automation, gh-fix-ci | | UI/UX | ui-ux-pro-max, mockup-to-code, web-design-guidelines, accessibility-audit, anti-ai-slop | | Research | deep-research, opensrc, source-code-research, agent-reach | | Security | security-and-hardening, skillspector, security-threat-model, defense-in-depth | | Platform | cloudflare, supabase, swift-concurrency, swiftui-expert-skill, v0, v1-run | | Advanced | desktop-commander, pencil, code-cleanup, deep-module-design, development-lifecycle |

Tier 1 Agentic Integrations (v1.6.0)

Three new integrations that extend ZCode with agentic capabilities:

| Skill | What it does | Setup | |---|---|---| | agent-reach | 15-platform web research router (Twitter, Reddit, YouTube, GitHub, etc.) | pipx install from GitHub | | skillspector | NVIDIA security scanner for skills — 68+ vulnerability patterns, 17 categories | uvx auto-bootstrap | | desktop-commander | Terminal, filesystem & process control via MCP — 26 tools | npx auto-bootstrap |

Commands (31)

The prompt auto-router covers 28 workflow commands; curate-wiki, hookify, and mcp-find remain explicit-only. Describe a routed workflow or invoke any command directly: /research, /plan, /create, /ship, /verify, /fix, /review-codebase, /design, /explore, /pr, /audit, /status, /health, /handoff, /curate, /setup, and more.

The canonical tracked-work lifecycle is:

/explore or /research -> /create -> /plan? -> /start -> /ship -> /verify -> /pr -> /compound

Each phase has one owner. Beads stores business task status; .beads/artifacts/<id>/run.json stores workflow phase, suspension, and fingerprinted review/verification evidence; swarm state is used only for multi-agent worker execution. Review scales to 1, 3, or 5 agents by changed-code risk. /loop manages recipes through native ZCode automations instead of storing schedule history in Markdown.

Agents (15 + host compaction)

Plugin-defined native profiles use qualified IDs such as agents-config:verify. Definitions are lazy; only task-relevant instances are spawned. ZCode's host-managed compaction lifecycle remains separate from callable custom profiles.

| Agent | Role | |---|---| | build | Primary developer — full codebase access | | plan | Architecture & decomposition | | explore | Read-only codebase search | | scout | External research (docs, packages, patterns) | | research-lead | Fan-out/fan-in research synthesis and conflict resolution | | review | Read-only diff review & security audit (vc-codex/codex-auto-review) | | verify | Independent goal/acceptance verification (vc-codex/codex-auto-review) | | debugger | Read-only reproduction, hypotheses, and root-cause analysis | | general | Small, well-defined implementation tasks | | runner | Shell/git/filesystem operations | | painter | Image generation & editing | | vision | Visual analysis (UI/UX, accessibility, design) | | prompt-curator | Maintain the prompt-library wiki (dedup, orphans, lint, import, convert) | | god | Authorized security testing orchestration | | reverse | Explicit-only authorized reverse engineering and binary analysis |

Automatic agent routing is intentionally disabled by default. agents-config/evals/ ships the equal-budget evaluation matrix and record schema; enabling routing remains an explicit release decision after the measured gate passes.

How it works

Prompt routing (automatic)

Every user prompt goes through the prompt-leverage hook:

1. Execution framing — adds a 5-step checklist before acting
2. Auto-router — detects intent and injects the matching command runbook
3. Intent→Skill mapping — for free-form prompts, loads the right skills automatically
4. Knowledge routing — non-trivial coding/review/research uses project rules, then a configured wiki, then the bundled pinned offline standards catalog
5. Prompt library — "act as ..." patterns trigger targeted wiki search for playbooks

No configuration needed — it just works.

Hooks (runtime)

| Hook | Trigger | What it does | |---|---|---| | guard | Before bash commands | Blocks dangerous operations (rm -rf, sudo, db:reset) | | rtk | Before bash commands | Rewrites commands for token efficiency | | prompt-leverage | Every user prompt | Execution framing + auto-routing + compact knowledge/skill policy | | memory-inject | Every user prompt | Injects relevant past observations from memory DB | | memory-capture | After tool use | Records tool usage as observations | | session-summary | Stop | Persists session state across turns |

Quick reference

# One command installs the baseline (skills, agents, commands, MCP tools, hooks,
# Codebase-Memory, optional WebClaw health probe, and RTK). No flags needed.
npx "github:cong91/zcode-starterkit"
# Codebase-Memory is the only starterkit-managed native always-on MCP and
# auto-indexes ONLY this cwd when it is a project root. Starterkit also ships
# a pinned Apache-2.0 agent-skills-standard snapshot for offline standards.
# Tilth, WebClaw, and Obsidian spawn only per skill call; /setup stores wiki
# readiness so knowledge-retrieval can use it without an environment variable.

# Or install the CLI globally, then run it anywhere
npm install -g github:cong91/zcode-starterkit
zcode-starterkit

# Sandbox test (doesn't touch real ~/.zcode and doesn't probe or download integrations)
npx "github:cong91/zcode-starterkit" --sandbox --skip-webclaw --skip-rtk

# Inside EACH project — materialize .zcode/ overlay, synthesize AGENTS.md from
# the configured wiki or bundled offline standards, and index THIS project
# with Codebase-Memory (mandatory gate; repairs if missing)
/setup

# Opt out of the optional WebClaw health probe / RTK only
# (Codebase-Memory remains the mandatory native MCP)
npx "github:cong91/zcode-starterkit" --skip-webclaw --skip-rtk

# Configure v-claw keys
zcode-starterkit setup-vclaw

# Uninstall
npx "github:cong91/zcode-starterkit" uninstall

For developers

Rebuild MCP tools

cd baseline/mcp-tools
npm install && npm run build

Cut a release

# 1. Bump version in both files:
#    package.json (version)
#    src/constants.mjs (PLUGIN_VERSION)
# 2. Commit + push
# 3. Tag + push tag
git tag v1.6.0
git push origin v1.6.0

The release GitHub Action runs tests (Linux + Windows), rebuilds MCP tools, and tags the release. The tag must match package.json version. Users install from git (no npm registry).

Design docs

See docs/superpowers/specs/2026-06-24-zcode-starterkit-design.md for architecture details.

See docs/superpowers/specs/2026-07-30-zcode-mcp-lifecycle-policy.md for native, plugin, and skill-scoped MCP lifecycle policy.

See AGENTS.md for the shipped global rules and the full Intent→Skill mapping table.