Install, Update & Adopt

Overview

Scaffold ships as one tool with two install surfaces: the scaffold CLI (distributed on npm as @zigrivers/scaffold and via Homebrew) and an optional Claude Code plugin that auto-activates the runner and pipeline-reference skills. The CLI is the core; the plugin only adds interactive guidance on top of it. The published npm package exposes the single scaffold binary (package.json:37) and bundles the compiled CLI plus the pipeline content, knowledge entries, and skills (package.json:27).

This guide is for users installing, updating, and bootstrapping projects. Maintainers releasing Scaffold itself follow a separate flow in docs/architecture/operations-runbook.md docs/architecture/operations-runbook.md:326.

Prerequisite — Node.js 18.17+. The CLI requires Node.js >=18.17.0 (package.json:34). The Homebrew formula installs and manages Node as a dependency, so you don't install Node separately; the npm install uses your system Node.

Installing

Pick one of the three surfaces below. The npm and Homebrew tabs install the CLI; the plugin tab adds the optional Claude Code skills on top.

npm install -g @zigrivers/scaffold

Verify with scaffold version. This is the recommended path — it uses your system Node and updates with npm update -g.

brew tap zigrivers/scaffold
brew install scaffold

The formula installs and manages Node as a dependency, so no separate Node install is needed. Verify with scaffold version.

Inside a Claude Code session:

/plugin marketplace add zigrivers/scaffold
/plugin install scaffold@zigrivers-scaffold

This is optional and complements the CLI — it auto-activates the Scaffold Runner and pipeline-reference skills for interactive guidance. Everything the plugin does is also reachable via scaffold run <step>. CLI-only users don't need it: scaffold init installs the skills automatically and later CLI commands keep them current.

Keeping current

Check what you have and whether a newer release exists with scaffold version (or scaffold update --check-only); both query the npm registry for the latest @zigrivers/scaffold (src/cli/commands/version.ts:93). scaffold update detects how you installed and prints the right upgrade command rather than running the install for you — Homebrew installs map to brew upgrade scaffold (src/cli/commands/update.ts:47), npm-global installs to npm update -g @zigrivers/scaffold (src/cli/commands/update.ts:51), and anything else falls back to npx @zigrivers/scaffold@latest (src/cli/commands/update.ts:55).

The Homebrew command it prints is exactly brew upgrade scaffold — it does not include the brew update prefix. Homebrew users must prepend it themselves and run brew update && brew upgrade scaffold, or the upgrade can silently no-op against a stale tap cache (see the danger callout below).

Run the upgrade for your channel:

npm update -g @zigrivers/scaffold

brew update && brew upgrade scaffold

/plugin marketplace update zigrivers-scaffold

Homebrew: run brew update before brew upgrade. brew outdated and brew upgrade both read from the local tap cache. Without a preceding brew update, the cache stays stale and a freshly-published release reports "already installed" / nothing-outdated even though a newer formula is live on GitHub. Always upgrade with brew update && brew upgrade scaffold docs/architecture/operations-runbook.md:326.

After upgrading the CLI, run scaffold status inside any existing project. The state manager auto-migrates old step keys, drops retired steps, and normalizes artifact paths — no manual editing of .scaffold/state.json is needed.

Starting fresh vs. adopting

Both scaffold init and scaffold adopt operate on the current project directory. Use init to set up a project from scratch and adopt to bootstrap pipeline state from documentation you already have.

#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#666;stroke:#666;}#my-svg .marker.cross{stroke:#666;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#000000;color:#000000;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#eee;stroke:#999;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#666;stroke-width:1px;}#my-svg .flowchart-link{stroke:#666;fill:none;}#my-svg .edgeLabel{background-color:white;text-align:center;}#my-svg .edgeLabel p{background-color:white;}#my-svg .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#my-svg .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#my-svg .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:white;text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:white;padding:2px;}#my-svg .icon-shape .label rect,#my-svg .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg .node .neo-node{stroke:#999;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node path{stroke:url(#my-svg-gradient);stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#my-svg [data-look="neo"].node circle{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}No / brand newYes, already writtenNew or existing projectHave matching docsPRD, tech-stack, etc.?scaffold initwizard + config + skillsscaffold init, thenscaffold adoptRun the pipeline

scaffold init

scaffold init initializes Scaffold for the current project (src/cli/commands/init.ts:152): it runs a wizard, writes .scaffold/ config and state, and installs the skills. The wizard detects whether the directory is brand new or already has code and suggests a methodology preset (mvp, deep, or custom) accordingly. To re-initialize a project that already has a .scaffold/ directory, pass --force — it backs up the existing state before reinitializing (src/cli/commands/init.ts:157).

scaffold adopt

scaffold adopt adopts an existing project into Scaffold (src/cli/commands/adopt.ts:168). It classifies the project as greenfield, brownfield, or v1-migration (src/project/adopt.ts:72), discovers which pipeline outputs (PRD, tech-stack, coding-standards, etc.) you already have on disk, and marks the corresponding steps complete so you don't re-run work you've already done. Preview the changes first with --dry-run, which reports what it would do without writing anything (src/cli/commands/adopt.ts:173).

The usual sequence for an existing codebase: scaffold init (create the config and state), then scaffold adopt (backfill state from existing docs), then pick up the pipeline at the first incomplete step.

Troubleshooting

scaffold: command not found after npm install. Your global npm bin directory isn't on PATH. Find it with echo "$(npm prefix -g)/bin" (the binaries live in the bin subdirectory of npm prefix -g) and add that directory to your shell PATH, or reinstall with a prefix that's already on PATH.

See also