| name | scaffold-upgrade |
| description | Upgrade harness control-plane files (hooks, scripts, git-hooks, agents) in a previously scaffolded project without wiping project-manifest or state. Dry-run by default. |
| argument-hint | [--apply] [--include-skills] [--profile core|full|brownfield] [--target path] |
Scaffold Upgrade
Refresh the harness machinery in an existing project after a harness release, without re-running full /scaffold or destroying local state.
When to use
- You upgraded the harness monorepo / SKU version and want new gates, hooks, or scripts.
- You do not want to overwrite
project-manifest.json, program.md, settings, or .claude/state/.
Do not use
- Brand-new projects →
/scaffold
- Disposable artifacts only → harness-lite
Procedure
-
Resolve the harness plugin source (the .claude tree of the harness version you want):
- Packaged:
dist/skus/harness-core (or full)
- Contributor clone:
~/claude_harness_eng_v5/.claude
-
Dry-run (default — always run first):
node "<plugin-source>/scripts/scaffold-upgrade.js" --target "<project-root>" --profile core
Review the printed write/skip counts.
- Apply when the plan looks right:
node "<plugin-source>/scripts/scaffold-upgrade.js" --target "<project-root>" --profile core --apply
Optional: --include-skills also refreshes skill prompts (larger surface change).
-
In the target project, review git diff under .claude/hooks, .claude/scripts, .claude/git-hooks, .claude/agents.
-
Run the project's tests / npm run agent-readiness if applicable.
Guarantees
| Never overwrites | Always refreshes (default apply) |
|---|
project-manifest.json (project root) | .claude/hooks/** |
.claude/state/** | .claude/scripts/** |
program.md, settings (skipped) | .claude/git-hooks/**, agents |
Flags
| Flag | Meaning |
|---|
--apply | Perform the copy (omit = dry-run) |
--include-skills | Also refresh .claude/skills/** |
--profile core|full|brownfield | Copy set (default core) |
--target <path> | Project root (default cwd) |
--plugin-source <path> | Harness .claude root |
Related
- Emit SKUs:
npm run package:skus (in harness monorepo)
- Publish process:
docs/marketplace-publish.md
