Skip to content
purlshq projects

TASKS-v0.10.0-setup-guide.md

TASKS-v0.10.0-setup-guide.md

Section titled “TASKS-v0.10.0-setup-guide.md”

Setup guide fixes identified during work machine setup session — 2026-03-16. All issues target the v0.10.0 milestone.

Pre-work

Section titled “Pre-work”

Create GitHub issues for each task below before starting any work:

gh issue create --title "bug: WSL2 installed via Windows Store defaults to root user" \
  --label "bug,setup-guide" --milestone "v0.10.0" \
  --body "When Ubuntu is installed via Windows Store, first-run setup sometimes skips username creation and drops the user into root. The setup guide needs a step early in Section 4 to detect this (whoami) and create a proper user if needed, before any other steps run."


gh issue create --title "feat: ask if environment already exists before setup begins" \
  --label "enhancement,setup-guide" --milestone "v0.10.0" \
  --body "The setup guide assumes a clean machine. It should ask upfront: 'Have you already set up a working environment on this or another user account on this machine?' If yes, branch to a discovery flow — check what's already installed, what folders exist, what's already cloned — and skip or adjust steps accordingly. Never assume, never overwrite."


gh issue create --title "feat: replace hardcoded D: drive with dynamic path discovery" \
  --label "enhancement,setup-guide" --milestone "v0.10.0" \
  --body "The guide hardcodes D: as the external drive. Instead it should ask where the user wants to work, then verify that path exists before running any mkdir commands. Should also handle the case where the target folder already exists from a previous setup on another account or machine."


gh issue create --title "feat: detect if scaffolder is already cloned before install step" \
  --label "enhancement,setup-guide" --milestone "v0.10.0" \
  --body "The guide runs gh repo clone and npm install unconditionally. It should first check if the scaffolder folder already exists at the expected path. If it does, skip cloning and go straight to npm install && npm run build && npm link."


gh issue create --title "feat: add Claude login step to setup guide" \
  --label "enhancement,setup-guide" --milestone "v0.10.0" \
  --body "The setup guide has no step for logging into Claude. User must authenticate Claude Code with their Anthropic account after installation. Add a dedicated section after Claude Code install: run claude, follow the browser auth flow, confirm logged in."

Task 1 — WSL2 root user detection

Section titled “Task 1 — WSL2 root user detection”

Branch: fix/setup-guide-root-user Label: bug, setup-guide Milestone: v0.10.0

What to build

Section titled “What to build”

Add a detection step to Section 4 of SETUP-GUIDE.md. Before any user creation instructions, have the user run:

Terminal window
whoami

If output is root:

  • Explain what happened (Windows Store WSL2 skips user creation)
  • Walk through adduser, usermod -aG sudo, and ubuntu config --default-user
  • Have user close and reopen Ubuntu before continuing
  • Verify with whoami again before proceeding

If output is anything else:

  • They already have a user, skip to next section

Definition of done:

  • Section 4 includes whoami check
  • Root detection path is clearly documented
  • Normal user path skips gracefully
  • Tested: fresh WSL2 install via Windows Store

Task 2 — Existing environment detection

Section titled “Task 2 — Existing environment detection”

Branch: feat/setup-guide-env-detection Label: enhancement, setup-guide Milestone: v0.10.0

What to build

Section titled “What to build”

Add a “Before you start” decision section at the very top of the setup flow (before Section 1). Ask:

“Have you already set up a Claude development environment on this machine or another user account on this machine?”

If no: Continue with standard setup flow as normal.

If yes: Branch to an environment discovery checklist:

  • What user account was it set up under?
  • Is that account accessible from this one?
  • Run: ls /mnt/d/Claude (or equivalent path) — does the folder exist?
  • Run: node --version, gh auth status, claude --version — what’s already installed?
  • Based on results, skip sections that are already complete

Definition of done:

  • Decision branch exists at top of guide
  • Discovery checklist covers: user, folders, installed tools
  • Each section has a “skip if” condition based on discovery results
  • Guide never overwrites existing work without explicit confirmation

Task 3 — Dynamic path discovery

Section titled “Task 3 — Dynamic path discovery”

Branch: feat/setup-guide-path-discovery Label: enhancement, setup-guide Milestone: v0.10.0

What to build

Section titled “What to build”

Replace all hardcoded D: / /mnt/d references in SETUP-GUIDE.md with a dynamic path decision section. Early in the guide (before Section 5), ask:

“Where do you want to store your projects?”

  • External drive — what drive letter? (check with ls /mnt in Ubuntu)
  • Local folder on C: (default: C:\Dev\Claude)

Then:

  • Have user verify the path exists: ls /mnt/[letter]
  • Check if Claude folder already exists: ls /mnt/[letter]/Claude
  • If exists: show contents, ask “Is this your existing environment?”
  • If not exists: proceed with mkdir

Replace all subsequent path references in the guide with [YOUR_PATH] placeholder with a reminder of what they chose.

Definition of done:

  • No hardcoded drive letters anywhere in SETUP-GUIDE.md
  • Path decision captured early and referenced consistently throughout
  • Existing folder detected and handled gracefully
  • Tested with both external drive and local C: scenarios

Task 4 — Scaffolder clone detection

Section titled “Task 4 — Scaffolder clone detection”

Branch: feat/setup-guide-clone-detection Label: enhancement, setup-guide Milestone: v0.10.0

What to build

Section titled “What to build”

Before the scaffolder install step (Section 11), add a detection check:

Terminal window
ls [YOUR_PATH]/projects/scaffolder

If folder exists:

  • Skip cloning
  • Go straight to: cd [YOUR_PATH]/projects/scaffolder && npm install && npm run build && npm link
  • Verify with sc --version

If folder does not exist:

  • Proceed with gh repo clone purlshq/scaffolder as normal
  • Then run install/build/link

Definition of done:

  • Section 11 includes existence check before clone
  • Both paths (exists / not exists) are documented
  • Tested with pre-existing scaffolder folder

Task 5 — Claude login step

Section titled “Task 5 — Claude login step”

Branch: feat/setup-guide-claude-login Label: enhancement, setup-guide Milestone: v0.10.0

What to build

Section titled “What to build”

Add a new section after Claude Code install (after current Section 9) for Claude authentication:

Section 9b — Log into Claude

Terminal window
claude

This opens Claude Code and triggers the browser authentication flow on first run. Steps:

  1. Run claude in terminal
  2. Browser opens — log in with your Anthropic account
  3. Authorize Claude Code
  4. Return to terminal — confirmed when you see the Claude Code prompt
  5. Type /exit to close for now

Add a note: “You must have an active Claude Pro or Max subscription to use Claude Code.”

Definition of done:

  • New section exists between Claude Code install and folder structure setup
  • Auth flow is clearly documented step by step
  • Subscription requirement noted
  • Tested on fresh install

Release notes

Section titled “Release notes”

These are all SETUP-GUIDE.md changes only — no scaffolder code changes. All changes go in templates/SETUP-GUIDE.md in the scaffolder repo. Once all tasks are merged to dev, test the full guide end-to-end on a fresh WSL2 instance before releasing.