GITHUB-ISSUES-2026-03-21-engine-migration.md

Engine migration — D:\Claude → D:\scaffolder-engine

Run top to bottom. One operation at a time. Confirm each result before proceeding.

Backup at: D:\backups-scaffolder-engine\claude-full-backup-2026-03-21.zip

CONTEXT

Completing the Plan-0002 engine/project split. The folder has been renamed from D:\Claude to D:\scaffolder-engine by the operator. The git repo (.git/) currently lives inside projects/scaffolder/. We are moving it and all engine files up to the engine root so D:\scaffolder-engine IS the repo root.

WSL path: /mnt/d/scaffolder-engine

Working directory for ALL operations: /mnt/d/scaffolder-engine

PHASE 0 — TRIAGE CLOSES

Run the triage close file FIRST. This file is at: projects/scaffolder/docs/issues/GITHUB-ISSUES-2026-03-21-triage-close.md

Execute all three batches in that file, confirm results, then return here.

PHASE 1 — MOVE .git/ AND ENGINE FILES TO ROOT

BEFORE YOU START

cd /mnt/d/scaffolder-engine
Confirm current state: ls -la projects/scaffolder/.git ls projects/scaffolder/src ls projects/scaffolder/templates

Report before proceeding.

OPERATION 1.1 — Move .git/ to engine root

mv projects/scaffolder/.git .
git status

Git will show a ton of deletions (because tracked files are now in projects/scaffolder/ relative to the new .git location). This is expected. Report git status summary.

OPERATION 1.2 — Move engine source files to root

Move one at a time, confirm each:

mv projects/scaffolder/src .
mv projects/scaffolder/templates .
mv projects/scaffolder/dist .
mv projects/scaffolder/node_modules .
mv projects/scaffolder/package.json .
mv projects/scaffolder/package-lock.json .
mv projects/scaffolder/tsconfig.json .
mv projects/scaffolder/versions.json .
mv projects/scaffolder/.env.example .
mv projects/scaffolder/CHANGELOG.md .
mv projects/scaffolder/README.md .
mv projects/scaffolder/LICENSE .
mv projects/scaffolder/CODE_OF_CONDUCT.md .
mv projects/scaffolder/CONTRIBUTING.md .
mv projects/scaffolder/SECURITY.md .

If .github/ exists in projects/scaffolder/:

mv projects/scaffolder/.github .

Confirm: ls the engine root. Should now have src/, templates/, dist/, node_modules/, package.json, and all root files.

OPERATION 1.3 — Merge .claude/ directories

Engine root already has .claude/ with some content. Project has its own .claude/. We need to merge — engine root .claude/ becomes the canonical one.

# Copy project skills that engine doesn't have
cp -rn projects/scaffolder/.claude/skills/session-start .claude/skills/ 2>/dev/null
cp -rn projects/scaffolder/.claude/skills/session-end .claude/skills/ 2>/dev/null
cp -rn projects/scaffolder/.claude/skills/plan-mode-reminder .claude/skills/ 2>/dev/null

# Copy settings if engine doesn't have it
cp -n projects/scaffolder/.claude/settings.local.json .claude/ 2>/dev/null

# List what we have now
ls -la .claude/skills/
ls -la .claude/commands/

Report what’s in .claude/ now.

OPERATION 1.4 — Move scaffolder project’s .gitignore to root

mv projects/scaffolder/.gitignore .

We’ll rewrite it in the next phase.

OPERATION 1.5 — Clean up projects/scaffolder/

Remove engine files that were already moved. Keep ONLY project artifacts:

# Remove the now-empty .claude from project (engine owns it)
rm -rf projects/scaffolder/.claude

# Remove any stale engine files left behind
rm -f projects/scaffolder/.env.example
rm -f projects/scaffolder/versions.json
rm -f projects/scaffolder/tsconfig.json

# Verify what remains in projects/scaffolder/
ls -la projects/scaffolder/

Expected remaining in projects/scaffolder/:

ai-sessions/ (CURRENT-CHAT.md, CURRENT-CODE.md, logs/)
docs/ (decisions/, features/, issues/, plans/, tasks/, and doc files)
CLAUDE.md (project-specific rules — keep)
STANDARDS.md (if present — keep)

Remove anything else that’s engine-level, not project-level. Report what’s left before proceeding.

PHASE 2 — REWRITE .gitignore

Overwrite .gitignore at engine root with:

# Dependencies
node_modules/
dist/

# Environment
.env
.env.local

# OS
.DS_Store
Thumbs.db

# Projects — user saves, never pushed with engine
projects/

# Operator files — local only
_system/
_ideas/
_review/
INSTALLED-MCP.md
TECH-STACK.md

# IDE
.vscode/
.idea/

Confirm by reading the file back.

PHASE 3 — REWRITE ENGINE CLAUDE.md

Overwrite the CLAUDE.md at engine root. This is the global Harley rules file. It applies to ALL projects via Claude Code’s hierarchical inheritance.

Write this content:

# CLAUDE.md — Scaffolder Engine

Standing instructions for all projects. Read this before doing anything.

## Who does what
- Chat AI (Joker) — planning, specs, architecture, documentation
- Code AI (Harley) — execution only, builds against docs

## Session protocol
1. Read this file
2. cd into the project: `cd projects/[project-name]`
3. Read that project's CLAUDE.md
4. Read ai-sessions/CURRENT-CODE.md for project state
5. Ask: "Ready to start. What are we working on this session?"
6. Wait for operator confirmation before doing any work

## Branch strategy
- main — production, stable only
- staging — pre-production review
- dev — integration branch
- feature/[name], fix/[name] — branched from dev
- hotfix/[name] — branched from main only
- Always work on a feature or fix branch unless explicitly told otherwise

Flow: feature → dev (PR) → staging (PR) → main (PR)

## Global rules
1. Never modify engine files (src/, templates/, package.json) without explicit instruction
2. Never modify main or dev directly
3. Never stage files from projects/ — they are gitignored
4. Follow Conventional Commits format
5. Merge any open chore or changelog branches into the feature branch before PR
6. Ask before making any decision not covered in docs

## GitHub
- Username: purlshq
- All repos are private by default

## Tech stack
- Language: TypeScript
- Runtime: Node.js
- Environment: WSL2 on Windows 11

## Key paths
- Engine root: /mnt/d/scaffolder-engine/
- All projects: /mnt/d/scaffolder-engine/projects/
- System files: /mnt/d/scaffolder-engine/_system/

Confirm by reading the file back.

PHASE 4 — UPDATE PROJECTS/SCAFFOLDER/CLAUDE.md

This file stays as project-specific rules. Update it to reflect the new structure. The key changes: remove anything that’s now in the engine CLAUDE.md (branch strategy, global rules, tech stack, GitHub info). Keep only scaffolder-specific content.

Replace the entire file with:

# CLAUDE.md — scaffolder project

Project-specific rules. Engine rules in parent CLAUDE.md apply automatically.

## Project state
Read `ai-sessions/CURRENT-CODE.md` before starting any work.

## Folder structure (this project)
projects/scaffolder/
├── ai-sessions/             ← AI working state
│   ├── CURRENT-CHAT.md
│   ├── CURRENT-CODE.md
│   └── logs/
├── docs/
│   ├── decisions/
│   ├── features/
│   ├── issues/              ← Joker-to-Harley instruction files
│   ├── plans/
│   └── tasks/
├── CLAUDE.md                ← this file
└── STANDARDS.md

## Engine files (at repo root — not here)
src/, templates/, .claude/, package.json, etc. live at the engine root.
Do not duplicate engine files in this project folder.

## Skills and commands
Engine-level — in .claude/ at repo root. Work across all projects.

**Skills** (automatic):
- session-start, session-end — session management
- plan-mode-reminder — suggests plan mode for complex tasks
- sc-session-start, sc-session-end — Joker session management

**Commands** (manual — /command):
- /sc-start, /sc-done — session lifecycle
- /sc-status, /sc-queue — project info
- /sc-create, /sc-config, /sc-help, /sc-ruleset — utilities

Confirm by reading the file back.

PHASE 5 — BUILD AND VERIFY

cd /mnt/d/scaffolder-engine
npm run build

Must be clean — zero errors.

If build succeeds:

npm link
sc --version

Then:

sc create --dry-run "migration-test"

Report the dry-run output. Confirm it shows the correct project structure.

PHASE 6 — COMMIT AND PUSH

cd /mnt/d/scaffolder-engine
git add -A
git status

Review carefully. Expected:

Lots of renames (git detects moves as rename)
New/modified: CLAUDE.md, .gitignore, projects/scaffolder/CLAUDE.md
Deleted: old locations of moved files

If anything looks wrong, STOP and report.

git checkout -b feature/engine-migration
git commit -m "feat: complete engine migration — repo root is now engine root

- Move .git/, src/, templates/, package.json to engine root
- D:\Claude renamed to D:\scaffolder-engine
- Engine CLAUDE.md now contains global Harley rules
- projects/scaffolder/ retains only project artifacts (docs/, ai-sessions/)
- .gitignore updated: projects/, _system/, _ideas/, _review/ excluded
- Merge .claude/ skills and commands at engine level
- Project CLAUDE.md trimmed to project-specific rules only"

git push origin feature/engine-migration

Then open PR to dev:

gh pr create --base dev --title "feat: complete engine migration to repo root" --body "Completes Plan-0002. Engine root is now the git repo root. projects/ is gitignored. All engine files (src/, templates/, .claude/) live at root. Project artifacts stay in projects/scaffolder/. Rename: D:\Claude → D:\scaffolder-engine."

Report: PR URL, git status, sc —version, dry-run output.

DONE

Do not merge the PR. Operator reviews first.