Folder Structure and Architecture

Plan-0002: Folder Structure and Architecture

Summary

A complete restructure of scaffolder’s folder layout based on the Minecraft .minecraft model — scaffolder is the engine, projects are the saves. The engine root contains only engine files. All user projects live inside scaffolder/projects/ which is gitignored. Engine templates mirror the project folder structure exactly so the mapping from template to destination is always obvious. Skills and commands are engine-level and one-time install — never duplicated per project. Session state is renamed ai-sessions/ and lives at project root, gitignored.

Motivation

The current structure has drifted badly. Files live in the wrong places, naming is inconsistent, templates contain files that were never implemented, and the relationship between scaffolder and the projects it creates is unclear to users. The operator cannot tell what belongs to the engine and what belongs to their project. New users have no intuitive mental model for where anything lives.

The root cause is that no explicit architecture decision was ever made about the engine/project boundary. Everything accumulated organically. This plan establishes that boundary once and for all and defines where every file lives and why.

The target audience is developers who use AI to build software and may not have deep systems knowledge. The structure must be self-explanatory without requiring documentation or tribal knowledge.

Scope

In scope:

Engine root folder structure and what lives there
Project folder structure and what sc create produces
Engine templates/ organization and naming
Gitignore rules for both engine and projects
Renaming of docs/rfcs/ to docs/plans/
Renaming of sessions/ to ai-sessions/
Removal of dead/unimplemented files from templates/
Skills and commands as engine-level, one-time install
No templates/ folder in projects
No COMMANDS.md or INSTALL.md in projects — engine only
projects/ living inside scaffolder as gitignored saves
Naming conventions (UPPER at root, kebab inside folders)
File retention config for ai-sessions/logs/ and docs/tasks/

Out of scope:

Plan-0001 smart session start implementation
Source code changes beyond path updates
Migration of existing projects to new structure
Changes to sc command behavior beyond path resolution
sc create project-type prompt (separate session)
_system/ operator personal files (handled per operator)

Proposed approach

Mental model: the Minecraft analogy

Scaffolder is the .minecraft folder. The engine (src/, templates/, .claude/) is the game itself. User projects are the saves — they live inside the engine folder, not alongside it. Users think of scaffolder/ as their home base. They would never delete it because their projects are inside it.

Installation

Scaffolder installs at D:\Claude (or operator-chosen root). The existing D:\Claude\projects\ folder becomes scaffolder/projects/ — no migration needed for existing projects. Backup of D:\Claude taken before any engine files are created.

Build sequence:

Backup D:\Claude entirely
Build engine files at D:\Claude root
Operator sanity checks
Update scaffolder project files (inside projects/)

Engine root — engine files only

The engine root contains only what someone cloning from GitHub needs to see and use. No operator files, no planning docs, no session state.

scaffolder/
├── .claude/              <- engine skills and commands (one-time install)
├── projects/             <- all user projects live here (gitignored)
├── src/                  <- engine source code
├── templates/            <- files used by sc create
├── CHANGELOG.md          <- engine version history
├── CLAUDE.md             <- global Harley rules for all projects
├── COMMANDS.md           <- command reference (visible on GitHub, engine only)
├── INSTALL.md            <- installation guide (visible on GitHub, engine only)
├── LICENSE
├── README.md
├── package.json
├── tsconfig.json
└── versions.json         <- hook sentinel + migration registry

projects/ — the saves

All user projects live inside scaffolder/projects/. This folder is gitignored entirely so user work is never pushed with the engine. The operator’s own scaffolder development work lives here too, as a project like any other.

scaffolder/projects/
├── _archive/             <- completed or paused projects
├── my-app/               <- output of sc create
└── my-other-app/

engine CLAUDE.md — global rules

The CLAUDE.md at engine root applies to all projects inside scaffolder/ due to Claude Code’s hierarchical CLAUDE.md inheritance. It contains global rules that apply everywhere: do not modify engine files, your project is in projects/[name]/, branch strategy, Conventional Commits format. Each project has its own CLAUDE.md that adds project-specific rules on top.

.claude/ — engine skills and commands

Skills and commands are installed once at the engine level and work across all projects. Never copied into individual projects. Users who want custom skills or commands create their own independently.

scaffolder/.claude/
├── commands/             <- sc commands (work across all projects)
│   ├── sc-build.md
│   ├── sc-config.md
│   ├── sc-create.md
│   ├── sc-done.md
│   ├── sc-help.md
│   ├── sc-queue.md
│   ├── sc-ruleset.md
│   ├── sc-start.md
│   └── sc-status.md
├── rules/
├── settings.local.json
└── skills/
    ├── sc-session-start/   <- ENGINE: Joker session start
    ├── sc-session-end/     <- ENGINE: Joker session end
    ├── session-start/      <- PROJECT: Harley session start (all projects)
    ├── session-end/        <- PROJECT: Harley session end (all projects)
    └── plan-mode-reminder/ <- PROJECT: plan mode reminder (all projects)

templates/ — mirrors project structure

Engine templates are organized to mirror exactly where each file lands in the project. The folder name tells you the destination. No exceptions.

scaffolder/templates/
├── project-root/         <- copied to project root by sc create
│   ├── ai-sessions/      <- copied to project ai-sessions/
│   │   ├── CURRENT-CHAT.md
│   │   └── CURRENT-CODE.md
│   ├── CLAUDE.md
│   ├── CHANGELOG.md
│   ├── NAMING-CONVENTIONS.md
│   ├── PROJECT-INSTRUCTIONS.md
│   ├── README.md
│   ├── STANDARDS.md
│   ├── .gitattributes
│   ├── .nvmrc
│   └── versions.json
├── github/               <- copied to project .github/ by sc create
│   └── workflows/        <- copied to project .github/workflows/
│       ├── ci.yml
│       └── claude-review.yml.disabled
└── docs/                 <- Joker reads only, never copied by sc create
    ├── API.md            <- produced on request, project-wide API reference
    ├── decisions/
    │   └── decision-template.md
    ├── features/
    │   ├── ARCHITECTURE.md
    │   ├── SCHEMA.md
    │   ├── SPEC.md
    │   ├── TASKS.md
    │   └── TESTING.md
    ├── issues/
    │   └── issues-template.md
    └── plans/
        └── plan-template.md

Project structure — output of sc create

No templates/ folder. No per-project skills or commands. No COMMANDS.md or INSTALL.md — those are engine-level only.

my-app/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── claude-review.yml.disabled
├── ai-sessions/          <- gitignored, AI working state only
│   ├── CURRENT-CHAT.md   <- Joker session state
│   ├── CURRENT-CODE.md   <- Harley session state
│   └── logs/             <- immutable session logs, retained forever by default
├── docs/                 <- committed to git (except tasks/)
│   ├── decisions/        <- architectural decisions, numbered, immutable
│   ├── features/         <- per-module build docs
│   │   └── [module]/
│   │       ├── ARCHITECTURE.md
│   │       ├── SCHEMA.md
│   │       ├── SPEC.md
│   │       ├── TASKS.md
│   │       └── TESTING.md
│   ├── issues/           <- dated issue operation files, Joker writes
│   ├── plans/            <- project plans, numbered
│   └── tasks/            <- gitignored, retained forever by default
├── src/                  <- project source code
├── CHANGELOG.md
├── CLAUDE.md             <- project-specific rules, inherits engine CLAUDE.md
├── LICENSE
├── NAMING-CONVENTIONS.md
├── PROJECT-INSTRUCTIONS.md
├── README.md
├── STANDARDS.md
├── package.json
├── tsconfig.json
└── versions.json         <- hook sentinel

Naming conventions

UPPER_CASE.md — root-level human-readable files (README.md, CLAUDE.md, CHANGELOG.md, STANDARDS.md, CURRENT-CHAT.md). “Look at me” files.
kebab-case.md — files inside folders (plan-template.md, decision-template.md, issues-template.md). “Find me when you need me” files.

Gitignore rules

Gitignored (local only, never pushed):

ai-sessions/ <- AI working state
docs/tasks/ <- planning scratch
projects/ <- engine only, user projects never pushed with engine

Committed to git:

docs/plans/
docs/decisions/
docs/features/
docs/issues/
All root UPPER files
src/, templates/, .claude/

File retention config

ai-sessions/logs/ and docs/tasks/ are retained forever by default. Config allows operators to set a maximum count per project if they want to prune. Not hardcoded. Losing history by accident is worse than keeping too much.

Files removed

STATUS.md — never kept current, CURRENT-CODE.md covers active state
START-HERE.md — manual upload steps obsolete with MCP
RETRO.md — never filled in, Joker produces on request if needed
COMMANDS.md and INSTALL.md — removed from project templates, engine only
bug_report.md, chore.md, feature_request.md — unimplemented feature, removed
SPEC.md, ARCHITECTURE.md, SCHEMA.md, TESTING.md (old root templates/) — move to templates/docs/features/ as engine-only templates
rfc-template.md — renamed plan-template.md, moves to templates/docs/plans/
adr-template.md — renamed decision-template.md, moves to templates/docs/decisions/
GITHUB-ISSUES.md — renamed issues-template.md, moves to templates/docs/issues/
API.md (old root location) — moves to templates/docs/ as engine-only template

Files renamed

docs/rfcs/ -> docs/plans/ (all projects and engine)
sessions/ -> ai-sessions/ (all projects)
Plan-0001 filename updated to match new naming convention

Dependencies

Plan-0001 smart session start references session file locations — ai-sessions/ path must be reflected in Plan-0001 when it is accepted
All src/ path resolution must derive from new projects/ location inside engine
CLAUDE.md hierarchical inheritance must be verified in Claude Code before build
sc create must write into projects/ and mirror new template structure exactly

Database impact

None.

API impact

None.

UI impact

None — terminal and chat interface only.

Risks and edge cases

Existing projects at old paths break until migrated. Mitigation: staged build sequence — engine first, operator sanity check, then project update.
Engine CLAUDE.md hierarchical inheritance must be verified before build begins. If Claude Code does not merge parent CLAUDE.md files, global rules will not apply. Mitigation: Harley verifies behavior in a test project before full build.
projects/ gitignore must be airtight. Mitigation: gitignore entry plus CLAUDE.md guardrail warning Harley never to stage files in projects/.
Renaming sessions/ to ai-sessions/ and docs/rfcs/ to docs/plans/ requires updating all references across CLAUDE.md, CHAT-REFERENCE.md, skills, and src/.
D:\Claude backup must be taken and verified before any engine files are created.

Acceptance criteria

Engine root contains only: .claude/, projects/, src/, templates/, and root files. No docs/, no sessions/, no operator files.
sc create produces the exact project structure defined in this plan. No extra files or folders.
COMMANDS.md and INSTALL.md do not appear in any project produced by sc create.
projects/ is gitignored and verified — git status never shows project files.
Engine CLAUDE.md hierarchical inheritance verified in Harley before build.
Skills and commands work across all projects without per-project copies.
ai-sessions/ is gitignored in every project.
docs/tasks/ is gitignored in every project.
File retention is config-driven with forever-by-default behavior.
templates/ structure mirrors project structure exactly, including workflows/.
All removed files gone from templates/ with no remaining references.
All renamed files and folders updated across src/, skills, CLAUDE.md, CHAT-REFERENCE.md, and any other references.
D:\Claude backup exists and verified before build begins.
Existing scaffolder project updated to new structure without data loss.

Open questions

Does sc create need a project-type prompt to conditionally stamp files? Deferred to separate session — out of scope for this plan.

ADRs produced

Decisions identified during discovery — to be drafted as proposed ADRs after this plan is accepted:

Projects live inside scaffolder/projects/ — not alongside the engine
Engine root contains only engine files — no operator or planning artifacts
Engine CLAUDE.md as global rules for all projects via hierarchical inheritance
Skills and commands are engine-level, one-time install, never per-project
No templates/ folder in projects — teams customize root files directly
COMMANDS.md and INSTALL.md are engine-only — never stamped into projects
ai-sessions/ replaces sessions/ — self-explanatory to non-developers
Engine templates/ mirrors project folder structure exactly including subfolders
docs/plans/ replaces docs/rfcs/ — plain English for target audience
Naming convention: UPPER at root, kebab inside folders
File retention is config-driven, forever by default, pruning is opt-in
Gitignore boundary: projects/, ai-sessions/, docs/tasks/ always local