# Scaffold Upgrade

> 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.

- Skill: `cwijayasundara/scaffold-upgrade` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cwijayasundara/scaffold-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cwijayasundara/scaffold-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cwijayasundara (https://skillmd.com/u/cwijayasundara)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cwijayasundara/scaffold-upgrade

---


# 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

1. 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`

2. **Dry-run** (default — always run first):

```bash
node "<plugin-source>/scripts/scaffold-upgrade.js" --target "<project-root>" --profile core
```

Review the printed write/skip counts.

3. **Apply** when the plan looks right:

```bash
node "<plugin-source>/scripts/scaffold-upgrade.js" --target "<project-root>" --profile core --apply
```

Optional: `--include-skills` also refreshes skill prompts (larger surface change).

4. In the target project, review `git diff` under `.claude/hooks`, `.claude/scripts`, `.claude/git-hooks`, `.claude/agents`.

5. 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`