z2w-starter-kit

Version: 0.2.1 | Framework: 2.13.0

Node CLI to scaffold new Z2W projects from canonical Templates + AGENTS.md.

Brand: Zero2Webmaster

Overview

z2w-starter-kit is a command-line scaffolder for Zero2Webmaster projects. It reads canonical content from the master Templates folder (AGENTS_WP_v3.1.0.md, AGENTS_v2.13.0.md, Resources/*), parses a pasted project brief OR walks an 8-question fallback wizard, applies brand presets, layers the current Z2W standards block (portable-stack, Fathom analytics, Uptime Kuma, Neon-careful, Agent Coordination, SEO baseline, email-service, text-size), substitutes placeholders, and writes a complete project skeleton atomically into the target path.

It is the Node/npm sibling of the instantiate-z2w-project Claude Code skill — the same orchestration logic, packaged so any developer can run it without Claude Code installed. When standards drift, both must be updated together.

npx @zero2webmaster/starter-kit init

Quick start

# Run without installing
npx @zero2webmaster/starter-kit init

# Or install globally
npm install -g @zero2webmaster/starter-kit
z2w-starter-kit init

# Or run from a local clone during development
git clone https://github.com/zero2webmaster/z2w-starter-kit
cd z2w-starter-kit
npm install
npm run build
node dist/cli.js init

The CLI's primary surface is brief-first: paste a project-instantiation brief, the CLI parses it deterministically, shows a numbered confirmation screen with per-line edit, then scaffolds. Type skip at the brief prompt or pass --wizard to fall back to the 8-question sequential wizard.

Project types supported: wp-plugin, cf-worker, cf-pages, nextjs, python-service, library, protocol-repo.

Brand presets: save-the-frogs, bansuri-bliss, zero2webmaster, custom.

CLI flags

| Flag | Purpose | |---|---| | --wizard | Skip brief-first mode; go straight to the 8-question fallback wizard | | --input <source> | Non-interactive mode. --input <path> reads ScaffoldInputs JSON from a file; --input - reads from stdin. Bypasses brief / confirm / wizard entirely. For CI use | | --dry-run | Print the file list + contents that would be written, without touching disk | | --target-path <path> | Override the target path from inputs | | --templates-path <path> | Point at a Templates folder other than ~/Desktop/Zero2Webmaster/AI/Templates/. Strict — when set, the hosted-mirror fallback is bypassed | | --refresh-templates | Force-bypass the local ~/.cache/z2w-templates/ cache and re-fetch from the hosted mirror at https://templates.z2w.us. Use after a Templates upstream change | | --promote-standards | Run the interactive (a) inline / (b) promote-into-Templates dialog per applicable standard. Promoted standards are captured in STANDARDS_PROMOTIONS.md alongside the scaffold (the Templates-folder write itself is a v0.3.x concern) | | --allow-non-empty | Write into a non-empty target directory. Off by default — the CLI refuses to scaffold over existing content unless explicitly opted in | | --no-color | Suppress ANSI color in the final summary output. Honored regardless of terminal capability, per POSIX NO_COLOR convention |

Architecture

This is a pure CLI tool. No web UI, no database, no scheduled jobs, no deployment target. Side-effectful commands (git init, gh repo create, npm install, composer install, symlink setup) are surfaced as next-actions in the final summary block — the CLI does NOT run them on the user's behalf in v0.1.x.

• Layer 1 (Directive): SOPs in directives/ (system architecture, scaffolder contracts, brand presets)
• Layer 2 (Orchestration): Node CLI (src/cli.ts) parses args, parses the brief or runs the wizard, decides what to write
• Layer 3 (Execution): Filesystem operations via fs-extra (atomic per-file writes via .tmp + rename); git/gh shell-outs run by the user post-scaffold, not by this CLI

For non-WP web apps (nextjs, cf-pages with hasWebUi), the CLI emits the full 7-item SEO baseline at instantiation: SSR/SSG via the framework's Metadata API, per-page metadata, one <h1> + semantic HTML, sitemap + robots with preview-noindex gating, OG image placeholder, Organization JSON-LD, Fathom Analytics wiring via the canonical env var (NEXT_PUBLIC_FATHOM_SITE_ID for Next.js, PUBLIC_FATHOM_SITE_ID for Vite/SvelteKit/Astro, inline <script> for cf-pages static), and a SEO-CHECKLIST.md pre-launch audit.

Templates resolution

The CLI resolves canonical template content (AGENTS bodies + Resources/) through a five-step fallback chain. The first source that has the file wins:

1. --templates-path <path> if set — strict use of that exact location; no fallback.
2. Local Templates folder at ~/Desktop/Zero2Webmaster/AI/Templates/ if present.
3. Fresh local cache at ~/.cache/z2w-templates/ (mtime < 24h).
4. Hosted mirror at https://templates.z2w.us — fetched, cached, returned.
5. Stale local cache with a warning (when the mirror is unreachable but a cached copy exists).
6. Hard fail with a clear --templates-path <path> hint.

Pass --refresh-templates to force a fresh fetch from the mirror, skipping step 3. This is the right call after an upstream Templates change you want to pull immediately.

Relationship to the Claude Code skill

The Claude Code skill at ~/.claude/skills/instantiate-z2w-project/SKILL.md and this CLI share a contract: same inputs, same outputs, same brand presets, same standards block. The skill is the in-Claude-Code path; this CLI is the standalone path. The canonical Templates folder remains the source for AGENTS file bodies and Resources/ boilerplate — both the skill and this CLI read Templates files fresh on every run; neither embeds copies.

Status

• v0.2.1 is a buyer-experience polish pass over v0.2.0's free-on-any-machine CLI (hosted Templates mirror at templates.z2w.us). It lands the brief-first hardening slice (secret-safe .gitignore, brief parser fixes, cancel-safe confirm, cd-safe git next-actions) plus: a scannable --dry-run file list (--show-contents for the full dump), Fathom correctly skipped for WordPress plugins, UPPER_SNAKE PHP constants, a scaffolded .env.local/.env, brief planning sections flowing into ROADMAP.md, and a populated README Overview + per-type Quick start.
• v0.2.0 shipped as a fully-free CLI that works on any machine — the hosted Templates mirror makes the CLI usable without a local Templates folder.
• The runtime license-validation Worker and the first paid features (--with-init, Pro SEO baseline) per the project brief are a separate v0.3.x track, gated on a marketing/distribution plan session.

License

Proprietary — © 2026 Dr. Kerry Kriger, Zero2Webmaster. All rights reserved.

A paid subscription is required for production use, redistribution, and any commercial deployment. Free evaluation use for the purpose of assessing whether to purchase a subscription is permitted. See LICENSE for full terms.

Subscriptions: https://zero2webmaster.com. For licensing inquiries: [email protected].

Scaffolded 2026-05-28 via the [[instantiate-z2w-project]] Claude Code skill v1; reconciled against the consolidated skill v1.1.0 (brief-first + Agent Coordination block) on 2026-05-29. Version: 0.2.1 | Last Updated: 2026-06-15