Skip to content
purlshq projects

TASKS.md — scaffolder v0.7.0 file structure migration

TASKS.md — scaffolder v0.7.0 file structure migration

Section titled “TASKS.md — scaffolder v0.7.0 file structure migration”

Rules for Code

Section titled “Rules for Code”
  • Always work on a feature branch, never directly on dev or main
  • Read BUILDER-INSTRUCTIONS.md and STANDARDS.md before starting any work
  • Complete each task fully before moving to the next
  • Do not add features not listed here
  • Follow Conventional Commits format on every commit
  • Update SESSION-NOTES.md at the end of every session
  • This is a BREAKING CHANGE release — file structure changes, placeholder names change

Branch

Section titled “Branch”

Create one branch for all tasks: feature/v0.7.0-file-restructure All tasks committed to that branch. Final PR: feature/v0.7.0-file-restructure → dev → main

Version target

Section titled “Version target”

v0.7.0

Context

Section titled “Context”

This release migrates the scaffolder’s project file structure to support the new session-based workflow. Key changes:

  • New sessions/ folder consolidates all session state
  • BUILDER-INSTRUCTIONS.md → CLAUDE.md (native Claude Code loading)
  • CONTEXT.md + SESSION-NOTES.md → sessions/CURRENT.md (single source of truth)
  • CHAT-LOG.md removed (replaced by session logs)
  • docs/handoffs/ removed (replaced by session logs)
  • Placeholder names change: [ARCHITECT_NAME]/[BUILDER_NAME] → [CHAT_AI_NAME]/[CODE_AI_NAME]
  • Always-nested docs/ with docs/features/ subfolder
  • .claude/rules/ added for modular rules
  • Optional GitHub Action for PR review as .disabled file

Reference: MASTER-PLAN-v0.7.0-2026-03-15.md in docs/ for full architectural context.

Definition of done

Section titled “Definition of done”

A task is only complete when:

  • File edited or created correctly
  • No hardcoded personal values in any template
  • All placeholder names use new format ([CHAT_AI_NAME]/[CODE_AI_NAME])
  • npm run build passes
  • Committed with correct message format
  • No unintended changes to other files

Release checklist (before dev → main PR)

Section titled “Release checklist (before dev → main PR)”
  • All tasks below complete and committed
  • CHANGELOG.md updated for v0.7.0
  • Version bumped in package.json
  • versions.json updated (latest: “0.7.0”, new version entry, breaking: true)
  • README.md badge updated to v0.7.0
  • npm run build passes clean
  • Dry run output (create --dry-run "test") matches new structure

Build order

Section titled “Build order”

Task 1 — Create new template files

Section titled “Task 1 — Create new template files”

Branch: feature/v0.7.0-file-restructure Commit: feat: add sessions/CURRENT.md and CLAUDE.md templates

Create templates/CURRENT.md:

# CURRENT.md — [project-name]


## Current state
_What is the current state of the project in plain English?_


## Version
v0.0.0


## Active branch
dev


## What was done last session
_Summary of what was completed, by whom (chat or code), and when._


## What is in progress
_What is actively being worked on?_


## What is not started
_What is queued but not yet begun?_


## What is working
_What is stable and complete?_


## What is not working
_What is broken or incomplete?_


## Decisions made
_Key decisions from recent sessions._


## Next steps
_What should happen next?_


## Watch out for
_Any gotchas, risks, or things to be careful about._

Create templates/CLAUDE.md:

# CLAUDE.md — Standing instructions for [CODE_AI_NAME]


This file is read automatically by Claude Code at the start of every session.
Do not rename this file.


## Who does what
- [CHAT_AI_NAME] — planning, specs, architecture decisions, documentation
- [CODE_AI_NAME] — execution only, builds against the docs in this repo


## Project state
Read `sessions/CURRENT.md` before starting any work. It contains the current
project state, what was done last session, and what to do next.


## Planning rules
- For any task touching 3+ files or adding new functionality: suggest plan mode
  first, produce a plan, get operator approval before coding
- For single-file bug fixes or minor changes: proceed directly
- When in doubt: plan first


## Folder structure
[project-name]/
├── docs/                    ← planning artifacts
│   ├── features/            ← feature-specific docs
│   ├── DISCOVERY.md
│   ├── SPEC.md
│   ├── ARCHITECTURE.md
│   ├── SCHEMA.md
│   ├── TASKS.md
│   ├── PLANNING.md
│   ├── DECISIONS.md
│   ├── TESTING.md
│   ├── API.md
│   ├── NAMING-CONVENTIONS.md
│   └── RETRO.md
├── sessions/                ← all session state
│   ├── CURRENT.md           ← single source of truth for project state
│   └── logs/                ← immutable session records
├── src/                     ← all code
├── .claude/
│   ├── settings.local.json
│   └── rules/               ← modular path-scoped rules
├── .github/
├── CLAUDE.md                ← this file (you are reading it)
├── STANDARDS.md
├── START-HERE.md
├── STATUS.md
├── TIME-LOG.md
├── README.md
└── CHANGELOG.md


## Branch strategy
- main — stable, production-ready only
- dev — integration branch, all features merge here first
- feature/[name] — one per feature, branched from dev, deleted after merge
- fix/[name] — for bug fixes, branched from dev
- hotfix/[name] — critical fixes, branched from main only
- [CODE_AI_NAME] always works on a feature or fix branch unless explicitly told otherwise


## Rules for [CODE_AI_NAME]
1. Read this file before starting any work
2. Read STANDARDS.md for commit, PR, and versioning rules
3. Read sessions/CURRENT.md for project state
4. Read all docs in docs/ before writing any code
5. Always create a feature branch before starting a task
6. Never modify main or dev directly
7. Never add features not listed in docs/TASKS.md
8. Never improvise folder structure or architecture
9. Ask before making any decision not covered in the docs
10. Follow Conventional Commits format (see STANDARDS.md)


## Session management
At the end of every session, [CODE_AI_NAME] must:
1. Ensure all work is committed on the current branch
2. Update sessions/CURRENT.md with: what was completed, what is in progress,
   decisions made, next steps, and current branch/status
3. Report current branch and status to operator


## GitHub
- Username: [github-username]
- All repos are private by default


## Tech stack
Defined per project in docs/DISCOVERY.md — never assume defaults.


## [CHAT_AI_NAME] handoff checklist
Before [CODE_AI_NAME] starts any project, confirm:
- [ ] docs/DISCOVERY.md complete and confirmed
- [ ] docs/SPEC.md complete with user stories and acceptance criteria
- [ ] docs/ARCHITECTURE.md complete
- [ ] docs/TASKS.md complete with definition of done per task
- [ ] docs/TESTING.md complete
- [ ] docs/DECISIONS.md present
- [ ] docs/SCHEMA.md complete (if database required)
- [ ] .scaffolder metadata file present
- [ ] GitHub repo created and accessible


## Mid-project check-in
After every 3 tasks completed, [CODE_AI_NAME] must:
1. Report progress to operator
2. Confirm next 3 tasks before continuing
3. Flag any decisions that [CHAT_AI_NAME] should know about


## Definition of complete planning
Planning is complete when ALL of the following exist and are confirmed:
- docs/DISCOVERY.md
- docs/SPEC.md (with user stories and acceptance criteria)
- docs/ARCHITECTURE.md
- docs/TASKS.md
- docs/TESTING.md
- docs/DECISIONS.md
- docs/SCHEMA.md (if database required)
- CLAUDE.md (this file)
- SCAFFOLDER-ANSWERS.md

Definition of done: Both template files created. Content matches the above exactly. No personal values.

Task 2 — Update createFolders.ts for new directory structure

Section titled “Task 2 — Update createFolders.ts for new directory structure”

Branch: feature/v0.7.0-file-restructure Commit: feat: add sessions/, docs/features/, .claude/rules/ to project structure

File: src/createFolders.ts

Add these directories to the dirs array:

path.join(projectPath, "sessions"),
path.join(projectPath, "sessions", "logs"),
path.join(projectPath, "docs", "features"),
path.join(projectPath, ".claude", "rules"),

Remove this directory from the dirs array:

path.join(projectPath, "docs", "handoffs"),

Definition of done: New directories created. docs/handoffs/ no longer created. Build passes.

Task 3 — Update createDocs.ts for new file structure

Section titled “Task 3 — Update createDocs.ts for new file structure”

Branch: feature/v0.7.0-file-restructure Commit: refactor: migrate to new file structure in createDocs

File: src/createDocs.ts

This is the largest task. Make these changes carefully:

1. Update the replaceAiNames function: Change placeholder names from [ARCHITECT_NAME]/[BUILDER_NAME] to [CHAT_AI_NAME]/[CODE_AI_NAME]:

function replaceAiNames(content: string): string {
  const globalConfig = getConfig();
  const chatAiName = globalConfig.chatAiName || "Chat";
  const codeAiName = globalConfig.codeAiName || "Code";
  content = content.replace(/\[CHAT_AI_NAME\]/g, chatAiName);
  content = content.replace(/\[CODE_AI_NAME\]/g, codeAiName);
  // Keep backward compatibility during transition
  content = content.replace(/\[ARCHITECT_NAME\]/g, chatAiName);
  content = content.replace(/\[BUILDER_NAME\]/g, codeAiName);
  return content;
}

2. Replace BUILDER-INSTRUCTIONS.md with CLAUDE.md: Find the block that copies BUILDER-INSTRUCTIONS.md to project root (around line 28-33). Change:

  • Read from templates/CLAUDE.md instead of templates/BUILDER-INSTRUCTIONS.md
  • Write to path.join(projectPath, "CLAUDE.md") instead of BUILDER-INSTRUCTIONS.md

Remove the line that also copies BUILDER-INSTRUCTIONS.md to docs/. (The dual-copy to docs/ is eliminated.)

3. Remove ARCHITECT-REFERENCE.md copy: Find and remove the entire block that copies ARCHITECT-REFERENCE.md to docs/ AND project root (around line 35-42). This file no longer lives per-project.

4. Replace CONTEXT.md and SESSION-NOTES.md with sessions/CURRENT.md: Find and remove the block that writes CONTEXT.md to project root. Find and remove the block that generates SESSION-NOTES.md to project root. Find and remove the block that copies CHAT-LOG.md to project root.

Add new block to write sessions/CURRENT.md:

// Copy CURRENT.md template to sessions/
const currentTemplatePath = path.join(TEMPLATES_DIR, "CURRENT.md");
let currentContent = fs.readFileSync(currentTemplatePath, "utf-8");
currentContent = currentContent.replace(/\[project-name\]/g, projectName);
currentContent = replaceAiNames(currentContent);
fs.writeFileSync(path.join(projectPath, "sessions", "CURRENT.md"), currentContent);

5. Remove PROJECT-INSTRUCTIONS.md from per-project output: Find and remove the block that copies PROJECT-INSTRUCTIONS.md to project root (around line 130-136). This file stays in _system/ only — not per-project.

6. Update BUILDER-INSTRUCTIONS.md from TEMPLATE_FILES array: The TEMPLATE_FILES array at the top of the file lists files copied to docs/. Remove "BUILDER-INSTRUCTIONS.md" from this array.

7. Keep STANDARDS.md copy from templates/ (already fixed in v0.6.4). No change needed — just verify it reads from TEMPLATES_DIR.

Definition of done: createDocs.ts generates the new file structure. No CONTEXT.md, SESSION-NOTES.md, CHAT-LOG.md, ARCHITECT-REFERENCE.md, or PROJECT-INSTRUCTIONS.md at project root. CLAUDE.md replaces BUILDER-INSTRUCTIONS.md at root. sessions/CURRENT.md created. Build passes.

Task 4 — Update all templates to use new placeholder names

Section titled “Task 4 — Update all templates to use new placeholder names”

Branch: feature/v0.7.0-file-restructure Commit: refactor: replace ARCHITECT_NAME/BUILDER_NAME with CHAT_AI_NAME/CODE_AI_NAME in all templates

Files: Every file in templates/ that contains [ARCHITECT_NAME] or [BUILDER_NAME]

Run a search across all templates:

Terminal window
grep -rl "ARCHITECT_NAME\|BUILDER_NAME" templates/

For every match, replace:

  • [ARCHITECT_NAME] → [CHAT_AI_NAME]
  • [BUILDER_NAME] → [CODE_AI_NAME]

Also check and update templates/STANDARDS.md — it references these names in session handoff, decision log, and escalation sections.

Do NOT edit:

  • templates/CLAUDE.md (created in Task 1, already uses new names)
  • templates/CURRENT.md (created in Task 1, no AI name references)

Definition of done: Zero occurrences of [ARCHITECT_NAME] or [BUILDER_NAME] in any template file. All replaced with [CHAT_AI_NAME] / [CODE_AI_NAME].

Task 5 — Rewrite templates/START-HERE.md

Section titled “Task 5 — Rewrite templates/START-HERE.md”

Branch: feature/v0.7.0-file-restructure Commit: docs: rewrite START-HERE.md for simplified session flow

File: templates/START-HERE.md

Replace entire contents with:

# START-HERE.md — [project-name]


## Starting a Chat session
1. Open your Claude Chat project
2. Upload `sessions/CURRENT.md` to Project Files (replace the old one if present)
3. Start a new conversation:


Hey [CHAT_AI_NAME]. Picking up [project-name].
Goal today: [what are we doing]


## Starting a Code session
1. Open terminal
2. Run:

/sc build [project-name]

3. Code reads CLAUDE.md and sessions/CURRENT.md automatically — no paste needed


## After running /sc create "[project-name]"
Copy your planning docs from Downloads:

cp /mnt/c/Users/[WINDOWS_USERNAME]/Downloads/[project-name]/*.md [DEFAULT_DRIVE]/projects/[project-name]/docs/

If you have a prototype:

cp /mnt/c/Users/[WINDOWS_USERNAME]/Downloads/[project-name]/*.html [DEFAULT_DRIVE]/projects/[project-name]/docs/

## End of session


### Code session
Run `/sc end` — this automatically:
- Updates sessions/CURRENT.md
- Writes a session log to sessions/logs/
- Commits and pushes


### Chat session
Chat produces a session log file. Download it and run:

cp ~/Downloads/[log-filename].md [DEFAULT_DRIVE]/projects/[project-name]/sessions/logs/

Then re-upload the updated sessions/CURRENT.md to your Chat Project Files.


## Running a QA session
1. Test against acceptance criteria in docs/SPEC.md
2. Log every bug as a GitHub issue:

gh issue create —title “bug: description” —label “bug,high” —milestone “v0.1.0”

3. Update STATUS.md with open issue count
4. No PR to main until QA checklist in docs/TESTING.md passes


## GitHub Issues quick reference

gh issue create —title “bug: description” —label “bug” —milestone “v0.1.0” gh issue create —title “chore: description” —label “chore” —milestone “v0.1.0” gh issue list gh issue close [number]

## Deployment checklist
- [ ] All env vars added to hosting platform
- [ ] .env.example up to date
- [ ] Tests passing
- [ ] PR merged to main and tagged
- [ ] Verify app works after deployment

Definition of done: START-HERE.md reflects the new simplified flow. No boot sequence paste. References sessions/CURRENT.md and CLAUDE.md. Uses new placeholder names.

Task 6 — Create GitHub Action PR review template

Section titled “Task 6 — Create GitHub Action PR review template”

Branch: feature/v0.7.0-file-restructure Commit: feat: add optional GitHub Action for Claude PR review

Create templates/claude-review.yml.disabled:

# OPTIONAL: Automated PR review with Claude Code
#
# To enable:
#   1. Add your ANTHROPIC_API_KEY to GitHub repo secrets
#   2. Run /install-github-app in Claude Code
#   3. Rename this file to claude-review.yml (remove .disabled)
#
# Cost: Usage is billed per API call. Review current pricing at:
#   https://www.anthropic.com/pricing
#
# name: Claude PR Review
# on:
#   pull_request:
#     types: [opened, synchronize]
#   issue_comment:
#     types: [created]
#
# permissions:
#   contents: read
#   pull-requests: write
#   issues: write
#
# jobs:
#   review:
#     if: |
#       github.event_name == 'pull_request' ||
#       (github.event_name == 'issue_comment' &&
#        github.event.issue.pull_request &&
#        contains(github.event.comment.body, '@claude'))
#     runs-on: ubuntu-latest
#     steps:
#       - uses: anthropics/claude-code-action@v1
#         with:
#           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Update src/createDocs.ts: Add a block to copy this file to .github/workflows/:

// Copy optional Claude PR review workflow (disabled by default)
const reviewTemplatePath = path.join(TEMPLATES_DIR, "claude-review.yml.disabled");
if (fs.existsSync(reviewTemplatePath)) {
  const reviewContent = fs.readFileSync(reviewTemplatePath, "utf-8");
  fs.writeFileSync(path.join(projectPath, ".github", "workflows", "claude-review.yml.disabled"), reviewContent);
}

Definition of done: Template created. Copied to .github/workflows/ on project create. Entirely commented out. Links to Anthropic pricing, no hardcoded dollar amount.

Task 7 — Remove deprecated template files

Section titled “Task 7 — Remove deprecated template files”

Branch: feature/v0.7.0-file-restructure Commit: refactor: remove deprecated template files replaced by new structure

Delete these files from templates/:

  • templates/CONTEXT.md (replaced by templates/CURRENT.md)
  • templates/CHAT-LOG.md (replaced by session logs)
  • templates/HANDOFF.md (replaced by session logs)

Do NOT delete:

  • templates/BUILDER-INSTRUCTIONS.md — keep this file for now. It’s still referenced by the migration system and existing projects may need it for the v0.6.4→v0.7.0 migration path. Add a comment at the top:
<!-- DEPRECATED: This file is kept for migration compatibility only. New projects use CLAUDE.md instead. -->

Definition of done: Three files deleted. BUILDER-INSTRUCTIONS.md marked deprecated but retained. No references to deleted files remain in createDocs.ts (verify against Task 3).

Task 8 — Update printDryRun() for new structure

Section titled “Task 8 — Update printDryRun() for new structure”

Branch: feature/v0.7.0-file-restructure Commit: refactor: update dry run output to reflect v0.7.0 structure

File: src/index.ts

Find the printDryRun function and replace the entire output tree with:

function printDryRun(name: string): void {
  const config = getConfig();
  const baseDir = config.defaultDrive ? `${config.defaultDrive}/projects` : "/mnt/d/Claude/projects";
  const githubUser = config.githubUsername || config.defaultGitHub || "purlshq";


  console.log(`\nDry run — here's what would be created:\n`);
  console.log(`Project folder: ${baseDir}/${name}/`);
  console.log(`├── .claude/`);
  console.log(`│   ├── rules/`);
  console.log(`│   └── settings.local.json`);
  console.log(`├── .github/`);
  console.log(`│   ├── ISSUE_TEMPLATE/`);
  console.log(`│   │   ├── bug_report.md`);
  console.log(`│   │   ├── feature_request.md`);
  console.log(`│   │   └── chore.md`);
  console.log(`│   └── workflows/`);
  console.log(`│       ├── ci.yml`);
  console.log(`│       └── claude-review.yml.disabled`);
  console.log(`├── docs/`);
  console.log(`│   ├── features/`);
  console.log(`│   ├── SPEC.md`);
  console.log(`│   ├── ARCHITECTURE.md`);
  console.log(`│   ├── SCHEMA.md`);
  console.log(`│   ├── TASKS.md`);
  console.log(`│   ├── PLANNING.md`);
  console.log(`│   ├── DECISIONS.md`);
  console.log(`│   ├── DISCOVERY.md`);
  console.log(`│   ├── TESTING.md`);
  console.log(`│   ├── API.md`);
  console.log(`│   ├── NAMING-CONVENTIONS.md`);
  console.log(`│   └── RETRO.md`);
  console.log(`├── sessions/`);
  console.log(`│   ├── logs/`);
  console.log(`│   └── CURRENT.md`);
  console.log(`├── src/`);
  console.log(`├── .env.example`);
  console.log(`├── .gitattributes`);
  console.log(`├── .gitignore`);
  console.log(`├── .nvmrc`);
  console.log(`├── .scaffolder`);
  console.log(`├── CHANGELOG.md`);
  console.log(`├── CLAUDE.md`);
  console.log(`├── README.md`);
  console.log(`├── STANDARDS.md`);
  console.log(`├── START-HERE.md`);
  console.log(`├── STATUS.md`);
  console.log(`└── TIME-LOG.md`);
  console.log(`\nGitHub repo: ${githubUser}/${name} (private)`);
  console.log(`\nRun /sc create "${name}" to create this project.`);
}

Note: Dry run now uses config-derived paths and usernames. Also updated the final message to use /sc create (future command name — doesn’t break anything to show it now).

Definition of done: Dry run output matches v0.7.0 structure exactly. No hardcoded paths or usernames.

Task 9 — Update sc.ts handleDone() for new session log location

Section titled “Task 9 — Update sc.ts handleDone() for new session log location”

Branch: feature/v0.7.0-file-restructure Commit: refactor: update handleDone to write session logs to sessions/logs/

File: src/sc.ts

Find the handleDone function. Update the handoff file generation:

1. Change the output path from docs/handoffs/ to sessions/logs/: Replace:

const handoffDir = path.join(basePath, sessionProject, "docs", "handoffs");

With:

const handoffDir = path.join(basePath, sessionProject, "sessions", "logs");

2. Change the filename format to use the new log naming convention: Replace the handoffName construction with:

const config = getConfig();
const operator = config.operatorAlias || config.yourName?.substring(0, 5).toLowerCase() || "user";
const version = getProjectVersion(basePath, sessionProject);
const timestamp = new Date().toISOString().replace(/[-:]/g, "").substring(0, 13).replace("T", "-");
const logName = `${version}-${date}-${timestamp.split("-")[1]}-code-${operator}.md`;

Add a helper function before handleDone:

function getProjectVersion(basePath: string, project: string): string {
  const metaPath = path.join(basePath, project, ".scaffolder");
  try {
    const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
    const v = meta.scaffolderVersion || "0.0.0";
    const parts = v.split(".");
    return `v${parts[0].padStart(2, "0")}.${parts[1].padStart(2, "0")}.${parts[2].padStart(2, "0")}`;
  } catch {
    return "v00.00.00";
  }
}

3. Update the copy command output to reference the new location:

console.log(`  cp /mnt/c/Users/${winUser}/Downloads/${logName} ${basePath}/${sessionProject}/sessions/logs/`);

4. Update the content template — replace the HANDOFF format with a session log format:

const logContent = `---
version: ${version}
date: ${date}
time: ${new Date().toISOString().split("T")[1].substring(0, 5)}
type: code
operator: ${operator}
duration: ${duration}
project: ${sessionProject}
---


# Code session — ${sessionProject} — ${date}


## What was completed
_Key work done this session._


## Decisions made
_Any decisions that Chat needs to know about._


## Current state
_Where things stand right now._


## Next steps
_What should happen next._
`;

Definition of done: /sc done writes to sessions/logs/ with the new naming convention and log format. Build passes.

Task 10 — Update sc.ts handleEnd() to update sessions/CURRENT.md

Section titled “Task 10 — Update sc.ts handleEnd() to update sessions/CURRENT.md”

Branch: feature/v0.7.0-file-restructure Commit: feat: auto-update sessions/CURRENT.md on /sc end

File: src/sc.ts

Find the handleEnd function. After logging time, add a block to update sessions/CURRENT.md:

// Update sessions/CURRENT.md
const config = getConfig();
const basePath = config.defaultDrive ? `${config.defaultDrive}/projects` : "/mnt/d/Claude/projects";
const currentPath = path.join(basePath, result.session.project, "sessions", "CURRENT.md");


if (fs.existsSync(currentPath)) {
  let current = fs.readFileSync(currentPath, "utf-8");
  const date = new Date().toISOString().split("T")[0];


  // Update "What was done last session" section
  const lastSessionMarker = "## What was done last session";
  if (current.includes(lastSessionMarker)) {
    const nextSection = current.indexOf("\n## ", current.indexOf(lastSessionMarker) + lastSessionMarker.length);
    const before = current.substring(0, current.indexOf(lastSessionMarker) + lastSessionMarker.length);
    const after = nextSection > -1 ? current.substring(nextSection) : "";
    current = `${before}\n${capitalize(result.session.type)} session completed on ${date}. Duration: ${result.formattedDuration}.\n${after}`;
  }


  fs.writeFileSync(currentPath, current);
  console.log(`Updated sessions/CURRENT.md`);
}

Note: This is a minimal auto-update. Code should also manually update CURRENT.md with more detail as part of session closing. This just ensures the timestamp and duration are always captured.

Definition of done: /sc end writes a session summary line to sessions/CURRENT.md. Graceful if file doesn’t exist. Build passes.

Task 11 — Add migration definition for v0.6.4 → v0.7.0

Section titled “Task 11 — Add migration definition for v0.6.4 → v0.7.0”

Branch: feature/v0.7.0-file-restructure Commit: feat: add v0.6.4 to v0.7.0 migration definition

Create src/migrations/v0.6.4-to-v0.7.0.ts:

export const migration = {
  fromVersion: "0.6.4",
  toVersion: "0.7.0",
  breaking: true,
  filesAdded: [
    "CLAUDE.md",
    "sessions/CURRENT.md",
    ".github/workflows/claude-review.yml.disabled",
  ],
  filesChanged: [
    "START-HERE.md",
    "STANDARDS.md",
    ".gitignore",
  ],
  filesRemoved: [
    "BUILDER-INSTRUCTIONS.md",
    "ARCHITECT-REFERENCE.md",
    "CONTEXT.md",
    "SESSION-NOTES.md",
    "CHAT-LOG.md",
    "PROJECT-INSTRUCTIONS.md",
    "docs/BUILDER-INSTRUCTIONS.md",
    "docs/ARCHITECT-REFERENCE.md",
  ],
  instructions: "BREAKING: File structure changed. BUILDER-INSTRUCTIONS.md → CLAUDE.md. CONTEXT.md + SESSION-NOTES.md → sessions/CURRENT.md. CHAT-LOG.md removed. Run /sc init to update config with operatorAlias field.",
};

Update src/migrations/index.ts: Add import and register the new migration in the array.

Definition of done: Migration chain is complete from v0.6.4 → v0.7.0. Breaking flag is true.

Task 12 — Update scaffolder’s own project files

Section titled “Task 12 — Update scaffolder’s own project files”

Branch: feature/v0.7.0-file-restructure Commit: docs: update scaffolder project files for v0.7.0

The scaffolder itself needs its structure updated to match what it generates.

  1. Create sessions/ directory and sessions/logs/ in the scaffolder project root
  2. Create sessions/CURRENT.md by combining content from current CONTEXT.md and SESSION-NOTES.md
  3. Create docs/features/ directory (empty)
  4. Create .claude/rules/ directory (empty)
  5. Rename BUILDER-INSTRUCTIONS.md at scaffolder root → CLAUDE.md
  6. Update docs/ARCHITECTURE.md to reflect new file structure

Do NOT delete the old files yet — they’ll be cleaned up after the release is tagged and confirmed working.

Definition of done: Scaffolder’s own structure includes sessions/, docs/features/, .claude/rules/, and CLAUDE.md at root.

Task 13 — Rename _system/ARCHITECT-REFERENCE.md

Section titled “Task 13 — Rename _system/ARCHITECT-REFERENCE.md”

Branch: feature/v0.7.0-file-restructure Commit: refactor: rename ARCHITECT-REFERENCE.md to CHAT-REFERENCE.md in _system

File: /mnt/d/Claude/_system/ARCHITECT-REFERENCE.md

Rename to: /mnt/d/Claude/_system/CHAT-REFERENCE.md

Update the header inside the file:

# CHAT-REFERENCE.md — Full reference for [CHAT_AI_NAME]

Replace all [ARCHITECT_NAME] with [CHAT_AI_NAME] and [BUILDER_NAME] with [CODE_AI_NAME] throughout.

Note: This file is outside the git repo. It’s the operator’s personal system file. This is a filesystem operation, not a committed change. Code should do this and confirm.

Definition of done: File renamed. All placeholder names updated. Old filename no longer exists.

Task 14 — Version bump, CHANGELOG, and PR

Section titled “Task 14 — Version bump, CHANGELOG, and PR”

Branch: feature/v0.7.0-file-restructure Commit: chore: bump version to 0.7.0 Commit: docs: update CHANGELOG for v0.7.0

  1. Bump version in package.json to 0.7.0

  2. Update versions.json:

    • Set "latest": "0.7.0"
    • Add entry:
    "0.7.0": { "breaking": true, "changes": ["BREAKING: File structure migration — sessions/ folder, CLAUDE.md replaces BUILDER-INSTRUCTIONS.md, CURRENT.md replaces CONTEXT.md + SESSION-NOTES.md, CHAT-LOG.md removed, docs/handoffs/ removed, placeholder names changed to CHAT_AI_NAME/CODE_AI_NAME, always-nested docs/ with features/ subfolder, .claude/rules/ added, optional GitHub Action PR review template"] }

  3. Update CHANGELOG.md:

## [0.7.0] — 2026-03-15
### Added
- feat: sessions/ folder with CURRENT.md and logs/ for all session state
- feat: CLAUDE.md template — native Claude Code loading, replaces BUILDER-INSTRUCTIONS.md
- feat: docs/features/ subfolder for feature-specific docs
- feat: .claude/rules/ for modular path-scoped rules
- feat: optional GitHub Action PR review template (claude-review.yml.disabled)
- feat: auto-update sessions/CURRENT.md on /sc end
- feat: session log naming convention with version, date, type, and operator


### Changed
- BREAKING: BUILDER-INSTRUCTIONS.md → CLAUDE.md at project root
- BREAKING: CONTEXT.md + SESSION-NOTES.md → sessions/CURRENT.md
- BREAKING: placeholder names [ARCHITECT_NAME]/[BUILDER_NAME] → [CHAT_AI_NAME]/[CODE_AI_NAME]
- refactor: START-HERE.md rewritten for simplified session flow
- refactor: /sc done writes to sessions/logs/ instead of docs/handoffs/
- refactor: _system/ARCHITECT-REFERENCE.md renamed to CHAT-REFERENCE.md


### Removed
- CHAT-LOG.md (replaced by session logs)
- docs/handoffs/ (replaced by sessions/logs/)
- PROJECT-INSTRUCTIONS.md from per-project output (system doc only)
- ARCHITECT-REFERENCE.md from per-project output (system doc only)
- Dual-copy of BUILDER-INSTRUCTIONS.md to docs/ (CLAUDE.md at root only)

  1. Update README.md badge to v0.7.0

  2. Open PR: feature/v0.7.0-file-restructure → dev

  3. Merge to dev

  4. Verify: npm run build passes, create --dry-run "test" shows correct structure

  5. Open PR: dev → main

  6. Report PR URL to operator for review and merge

  7. After merge: tag v0.7.0

  8. Update sessions/CURRENT.md (using the new file!)

  9. Push all changes

Definition of done: v0.7.0 tagged on main. New file structure in place. All templates use new placeholder names. Dry run output matches. Build passes clean.