Zest Dev

A lightweight, human-interactive development workflow for AI-assisted coding.

Quick Start

Install the CLI from npm, then initialize the editor-facing commands and skills in your project:

npm install -g zest-dev
zest-dev init

If you prefer not to install globally, run it with npx:

npx zest-dev init

After installation, verify the CLI is available:

zest-dev --version
zest-dev --help

Initialize a Project

From the project where you want to use Zest Dev, run:

zest-dev init

Local Development Setup

When developing this repository locally, install dependencies and link the CLI into your global PATH:

npm install
npm link

npm link makes the global zest-dev command point at this checkout, so local source changes are picked up immediately:

zest-dev --help
zest-dev init

Publishing to npm

Publishing is automated from GitHub Actions after merge to main when package.json contains a new version.

Before publishing, validate the package locally:

npm pack --dry-run --json
pnpm test:local
pnpm test:package

The repository uses npm Trusted Publishing with GitHub Actions OIDC:

• PRs that change package-shipped CLI files automatically receive a patch version bump when needed.
• PRs fail CI if their version is not ahead of main.
• The publish-npm.yml workflow publishes merged versions with npm publish --access public --provenance.
• npm package settings must include a trusted publisher for nettee/zest-dev with workflow filename publish-npm.yml.

Optional repository secret:

• Set AUTO_BUMP_TOKEN to a fine-grained GitHub token with write access to this repository if you want PR auto-bump pushes to be attributed to that token owner instead of github-actions[bot]. This can avoid GitHub's approval gate on follow-up PR runs triggered by the auto-bump commit.

If publishing fails, inspect the Publish npm workflow run on main before retrying.

Usage Workflow

Zest Dev uses a content-contract skill / approach command model:

• the Zest Dev skill owns Spec lifecycle and recording contracts
• Section Guides define Overview, Design, Plan, and Implementation content
• two thin commands choose how a new Spec reaches Designed Status
• the zest-dev CLI manages Spec files and lifecycle state

Design Approaches

Use the lightweight route for straightforward work:

/zest-dev:lightweight "My new feature"

Use grilling when the design needs an intensive, one-question-at-a-time decision process:

/zest-dev:grilling "My complex feature"

Both commands create and activate a new Spec, establish its Overview, and reach the same Designed Status. The grilling route composes the registered grilling and domain-modeling skills. Research is not a separate status or required step; source-backed Research Findings live beside Design Decisions in the Design Record.

New-format Specs progress through new → designed → planned → implemented.

CLI Reference

The zest-dev CLI manages spec files. Use it to inspect and update specs outside of Claude.

Commands

Command	Purpose
zest-dev status	View project status
zest-dev show <spec-id|active>	View spec content
zest-dev create <slug>	Create new spec
zest-dev set-active <spec-id>	Set active change spec
zest-dev unset-active	Unset active change spec
zest-dev update <spec-id|active> <status>	Update spec status
zest-dev create-branch	Create a git branch from the active change spec
zest-dev dump <spec-id|active> [--dry-run]	Archive a spec as an issue representation or GitHub issue
zest-dev load [issue] [--from-file <path>]	Reconstruct a spec from an issue representation or GitHub issue
zest-dev ralph	Convert active Spec Progress items into Ralph tasks

Status Transitions

Valid status values: new, designed, planned, implemented

• Forward-only transitions (skipping is allowed): e.g. new → designed is valid
• Backward transitions fail: e.g. implemented → designed
• Setting the same status again returns an error

Resource Layout

Zest Dev's editor-facing resources are stored in top-level directories:

• commands/ - the lightweight and grilling Design Approach entrypoints
• skills/ - the Zest Dev skill and its Section Guides
• agents/ - reusable subagent definitions

The plugin/ directory is a Claude Code compatibility layer. It keeps plugin metadata under plugin/.claude-plugin/, while plugin/commands, plugin/skills, and plugin/agents are symlinks to the top-level source directories.

Project Structure

project/
├── specs/
│   ├── change/
│       ├── 20260224-init-project/
│       │   ├── spec.md
│       │   ├── design.md
│       │   └── implementation.md
│       ├── 20260225-feature-name/
│       │   ├── spec.md
│       │   ├── design.md
│       │   └── implementation.md
│       └── active -> 20260225-feature-name (symlink)
│   └── current/
│       └── implementation.md

References

• OpenSpec - Inspired by its current-spec methodology, where specs act as the source of truth for how a system currently behaves and changes are managed separately until they are merged back.
• Matt Pocock Skills: to-tickets - References its tracer-bullet vertical-slice planning style for breaking design work into Zest Dev Plan tickets.
• Matt Pocock Skills: tdd - References its test-driven implementation methodology for coding work, separate from Plan ticket slicing.