GITHUB-ISSUES-2026-03-19-engine-structure-build.md

Engine structure build — Phase 1

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

Reference: docs/plans/plan-0002-folder-structure.md

Reference: D:\Claude_review\structure-review-3\ (working example)

CONTEXT

This session builds the Plan-0002 engine structure. The goal is to reorganise the scaffolder project’s files so they match the accepted architecture.

NO source code changes this session. NO cleanup of stale commands. Structure only.

Working directory for this session: /mnt/d/Claude/projects/scaffolder

The engine root (D:\Claude) already has:

CLAUDE.md (created this session — do not touch)
projects/ (existing — do not touch)
_system/ (operator files — do not touch)

BEFORE YOU START

Confirm you are on the dev branch: git status
Create a feature branch: git checkout -b feature/engine-structure-build
Confirm the branch: git status

Report branch name before proceeding.

OPERATION 1 — Create D:\Claude.claude\ engine directory

Plan-0002 says skills and commands live at the engine root (.claude/) and apply to all projects via Claude Code’s directory traversal. They currently live only inside the scaffolder project. This operation creates the engine-level .claude/ and copies the Joker-specific skills (sc-session-start, sc-session-end) up to it.

The project-level skills (session-start, session-end, plan-mode-reminder) and all commands stay in the project .claude/ for now — they move in a later session when source code is updated to stop stamping them into projects.

Steps:

1a. Create engine .claude/ directory structure: mkdir -p /mnt/d/Claude/.claude/commands mkdir -p /mnt/d/Claude/.claude/skills mkdir -p /mnt/d/Claude/.claude/rules

1b. Copy sc-session-start skill to engine level: cp -r .claude/skills/sc-session-start /mnt/d/Claude/.claude/skills/

1c. Copy sc-session-end skill to engine level: cp -r .claude/skills/sc-session-end /mnt/d/Claude/.claude/skills/

1d. Copy all commands to engine level: cp .claude/commands/*.md /mnt/d/Claude/.claude/commands/

1e. Copy settings.local.json to engine level: cp .claude/settings.local.json /mnt/d/Claude/.claude/settings.local.json

1f. Verify engine .claude/ contents: ls -la /mnt/d/Claude/.claude/ ls -la /mnt/d/Claude/.claude/skills/ ls -la /mnt/d/Claude/.claude/commands/

Report what you see before proceeding.

OPERATION 2 — Restructure templates/ to match Plan-0002

Current templates/ is a flat folder with files dumped at root level. Plan-0002 requires three subfolders: project-root/, github/, docs/ Each subfolder name maps directly to its destination in a generated project.

Reference structure (from structure-review-3): templates/ ├── project-root/ <- root files stamped into project by sc create │ ├── ai-sessions/ │ │ ├── CURRENT-CHAT.md │ │ └── CURRENT-CODE.md │ ├── .gitattributes │ ├── .nvmrc │ ├── CHANGELOG.md │ ├── CLAUDE.md │ ├── NAMING-CONVENTIONS.md │ ├── PROJECT-INSTRUCTIONS.md │ ├── README.md │ ├── STANDARDS.md │ └── versions.json ├── github/ │ └── workflows/ │ ├── ci.yml │ └── claude-review.yml.disabled └── docs/ <- Joker reads only, never stamped into projects ├── API.md ├── decisions/ │ └── decision-template.md ├── features/ │ ├── ARCHITECTURE.md │ ├── SCHEMA.md │ ├── SPEC.md │ ├── TASKS.md │ └── TESTING.md ├── issues/ │ └── issues-template.md └── plans/ └── plan-template.md

Steps:

2a. Create the new subfolder structure: mkdir -p templates/project-root/ai-sessions mkdir -p templates/github/workflows mkdir -p templates/docs/decisions mkdir -p templates/docs/features mkdir -p templates/docs/issues mkdir -p templates/docs/plans

2b. Move project-root files: mv templates/CHANGELOG.md templates/project-root/ mv templates/CLAUDE.md templates/project-root/ mv templates/NAMING-CONVENTIONS.md templates/project-root/ mv templates/PROJECT-INSTRUCTIONS.md templates/project-root/ mv templates/README.md templates/project-root/ mv templates/STANDARDS.md templates/project-root/ mv templates/.gitattributes templates/project-root/ mv templates/.nvmrc templates/project-root/ mv templates/versions.json templates/project-root/ 2>/dev/null || echo “versions.json not in templates root — skip”

2c. Move ai-sessions templates: mv templates/CURRENT-CHAT.md templates/project-root/ai-sessions/ mv templates/CURRENT-CODE.md templates/project-root/ai-sessions/

2d. Move github workflow files: mv templates/ci.yml templates/github/workflows/ mv templates/claude-review.yml.disabled templates/github/workflows/

2e. Move docs templates — rename files per Plan-0002 naming: mv templates/API.md templates/docs/ mv templates/adr-template.md templates/docs/decisions/decision-template.md mv templates/GITHUB-ISSUES.md templates/docs/issues/issues-template.md mv templates/rfc-template.md templates/docs/plans/plan-template.md

2f. Move feature doc templates: mv templates/ARCHITECTURE.md templates/docs/features/ mv templates/SCHEMA.md templates/docs/features/ mv templates/SPEC.md templates/docs/features/ mv templates/TESTING.md templates/docs/features/

Note: TASKS.md — check if it exists in templates root:
ls templates/TASKS.md 2>/dev/null && mv templates/TASKS.md templates/docs/features/ || echo "No TASKS.md in templates root — skip"

2g. Remove files that Plan-0002 explicitly deletes from templates: rm -f templates/STATUS.md rm -f templates/START-HERE.md rm -f templates/RETRO.md rm -f templates/SETUP-GUIDE.md rm -f templates/CHAT-REFERENCE.md

Note: Check for any remaining unexpected files at templates root:
ls templates/

2h. Handle claude-skills and claude-commands: These folders stay in templates/ for now — source code still references them. Do NOT move or delete them this session.

2i. Verify final templates/ structure: find templates/ -type f | sort

Report the full file list before proceeding.

OPERATION 3 — Rename sessions/ to ai-sessions/ in scaffolder project

Plan-0002 renames sessions/ to ai-sessions/ in all projects. The scaffolder project is the first to get this treatment.

Steps:

3a. Rename the folder: mv sessions/ ai-sessions/

3b. Verify contents survived: ls -la ai-sessions/ ls -la ai-sessions/logs/

3c. Verify CURRENT-CHAT.md and CURRENT-CODE.md are present: ls ai-sessions/CURRENT-CHAT.md ai-sessions/CURRENT-CODE.md

Report what you see before proceeding.

OPERATION 4 — Update scaffolder project CLAUDE.md

The scaffolder project CLAUDE.md has stale paths. Update it to reflect:

sessions/ -> ai-sessions/
docs/rfcs/ -> docs/plans/
Remove references to removed files (STATUS.md, START-HERE.md, TIME-LOG.md)
Remove stale slash commands (sc-end, sc-exit, sc-history, sc-log)
Update folder structure diagram

Steps:

4a. Read current CLAUDE.md: cat CLAUDE.md

4b. Make the following targeted edits:

Replace in folder structure diagram:
- sessions/                <- all session state
- sessions/CURRENT.md      <- single source of truth
->
- ai-sessions/             <- AI working state (gitignored)
- ai-sessions/CURRENT-CODE.md
- ai-sessions/CURRENT-CHAT.md

Replace in folder structure:
- docs/rfcs/               <- RFC proposals
->
- docs/plans/              <- project plans, numbered

Remove these lines from folder structure:
- START-HERE.md
- STATUS.md
- TIME-LOG.md

Replace in Rules section:
- Read sessions/CURRENT.md
->
- Read ai-sessions/CURRENT-CODE.md

Replace in Slash commands section — remove stale commands:
Remove: /sc-end, /sc-exit, /sc-history, /sc-log
Keep: /sc-start, /sc-done, /sc-status, /sc-queue, /sc-create, /sc-config, /sc-help

4c. Verify the file looks correct: cat CLAUDE.md

Report the full file contents before proceeding.

OPERATION 5 — Update .gitignore

The scaffolder project .gitignore needs ai-sessions/ added (replacing sessions/).

Steps:

5a. Read current .gitignore: cat .gitignore

5b. Replace sessions/ entry with ai-sessions/: (edit the file — find the sessions/ line and replace with ai-sessions/)

5c. Verify: cat .gitignore | grep ai-sessions

Report the result.

OPERATION 6 — Commit

6a. Stage all changes: git add -A

6b. Review what is staged: git status

6c. Confirm nothing unexpected is staged. If anything looks wrong, stop and report.

6d. Commit: git commit -m “feat: restructure templates/ and rename sessions/ to ai-sessions/ per Plan-0002”

6e. Report final git status and confirm the branch: git status git log —oneline -3

DONE

Report:

Branch name
Commit hash
Any files that could not be moved or were not where expected
Anything that looked wrong during the build

Do not push. Do not open a PR. Operator will review locally first.

Paste, save, then hand it to Harley:

cd /mnt/d/Claude/projects/scaffolder && claude