BUILD-INSTRUCTIONS — fix/sc-start-launch-harley (#339)

BUILD-INSTRUCTIONS — fix/sc-start-launch-harley (#339)

Created: 2026-03-22 Issue: #339 Purpose: Make sc start launch Harley after recording the session

---

Rules for Harley

• Run steps in order, one at a time
• Confirm each result before moving to the next
• Report any failures to operator immediately
• Do NOT merge any PRs — operator merges

---

Step 0 — Verify starting state

cd /mnt/d/scaffolder-engine
git branch --show-current
git status

If not on dev, checkout dev and pull:

git checkout dev
git pull origin dev

---

Step 1 — Create fix branch from dev

git checkout -b fix/sc-start-launch-harley dev

Confirm:

git branch --show-current

Expected: fix/sc-start-launch-harley

---

Step 2 — Edit src/sc.ts — handleStart function

Find the handleStart function. It currently looks like this:

async function handleStart(args: string[]): Promise<void> {
  let type = args[0] as "planning" | "build" | "testing" | undefined;
  let project = args[1];

  if (!type || !["planning", "build", "testing"].includes(type)) {
    type = (await promptChoice("Session type", ["planning", "build", "testing"], "build")) as "planning" | "build" | "testing";
  }
  if (!project) {
    project = await prompt("Which project?");
  }

  if (!type || !project) {
    console.error("Session type and project are required.");
    process.exit(1);
  }

  const session = startSession(type, project);
  console.log(`Started ${session.type} session for "${session.project}".`);
}

Replace the entire handleStart function with:

async function handleStart(args: string[]): Promise<void> {
  const { execSync } = require("child_process");
  let type = args[0] as "planning" | "build" | "testing" | undefined;
  let project = args[1];

  if (!type || !["planning", "build", "testing"].includes(type)) {
    type = (await promptChoice("Session type", ["planning", "build", "testing"], "build")) as "planning" | "build" | "testing";
  }
  if (!project) {
    project = await prompt("Which project?");
  }

  if (!type || !project) {
    console.error("Session type and project are required.");
    process.exit(1);
  }

  const config = getConfig();
  const basePath = config.defaultDrive || "/mnt/d/Claude/projects";
  const projectPath = path.join(basePath, project);

  if (!fs.existsSync(projectPath)) {
    console.error(`Project not found: ${projectPath}`);
    process.exit(1);
  }

  const session = startSession(type, project);
  console.log(`Started ${session.type} session for "${session.project}".`);
  console.log(`Launching Harley in ${projectPath}...\n`);

  try {
    execSync(`harley`, { cwd: projectPath, stdio: "inherit" });
  } catch {
    // Harley may exit non-zero; that's fine
  }
}

What changed:

• Added execSync import at top of function
• Added config/path resolution (same pattern as handleBuild)
• Added project path validation
• Added Harley launch after session recording
• Session metadata is written BEFORE Harley launches

---

Step 3 — Build and verify

npm run build

Expected: Clean build, no errors.

Then verify the CLI still works:

sc --version

---

Step 4 — Commit

git add src/sc.ts
git commit -m "fix: sc start now launches harley after recording session (closes #339)"

---

Step 5 — Push and create PR to dev

git push origin fix/sc-start-launch-harley

Create PR:

gh pr create --base dev --head fix/sc-start-launch-harley --title "fix: sc start now launches harley after recording session" --body "## Summary

\`sc start\` previously only recorded session metadata and returned to the shell. Now it records the session AND launches Harley in the project directory.

Closes #339.

## What changed

\`handleStart()\` in \`src/sc.ts\` now:
1. Records session metadata (unchanged)
2. Resolves project path from config (same pattern as \`handleBuild\`)
3. Validates project directory exists
4. Launches Harley via \`execSync\` with \`cwd\` set to the project

## Test plan

- [ ] \`sc start build scaffolder\` — records session, launches Harley in project dir
- [ ] \`sc start\` (interactive) — prompts for type and project, then launches Harley
- [ ] Invalid project name — prints error, does not launch
- [ ] \`sc status\` after Harley exits — session is still active (ended by \`sc done\`)"

---

Step 6 — Report results

Tell operator:

• Branch created and pushed
• PR number and URL
• Ready for operator to merge

STOP HERE. Do not merge. Do not proceed to other work.