@boopkit/cli 0.7.1 → 0.8.1

package/README.md

@@ -129,7 +129,8 @@ Pick what the product needs. `boop add <name>` handles the wiring — npm depend
 | Name | What it adds |
 |------|--------------|
 | `coding` | Development conventions and coding skills for AI agents |
-| `testing` | Jest setup and testing skills (TDD workflow, Express testing patterns) |
+| `typescript` | The TypeScript toolchain: Jest with ts-jest, `tsconfig.test.json`, and the `test` and `typecheck` scripts |
+| `testing` | Testing principles and the TDD-Lite workflow skills |
 | `project-mgmt` | Beads issue-tracking and planning skills |
 | `product-design` | Product design skills — feature requirements, engineering design, documentation, design thought-partnership, and technical prose |
 | `ux` | UX judgement (purpose + visual) and the app-UI evaluation and delivery workflows |
@@ -146,12 +147,13 @@ Adding a capability installs its skills into your project's `skills/` directory.
 **Development capabilities (skills only — no runtime code)**
 
 - **`coding`** — boop-coding-beads-flow, boop-coding-development, boop-coding-commit-changes, boop-coding-review-changes, boop-coding-debugging
-- **`product-design`** — boop-product-design-engineering-design, boop-product-design-feature-documentation, boop-product-design-feature-requirements, boop-product-design-reference-integration, boop-product-design-thought-partnership, boop-writing-technical-prose, boop-writing-documents, boop-writing-semantic-line-breaks
-- **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning
+- **`product-design`** — boop-product-design-engineering-design, boop-product-design-feature-documentation, boop-product-design-feature-requirements, boop-product-design-reference-integration, boop-product-design-knowledge-backfill, boop-product-design-thought-partnership, boop-writing-technical-prose, boop-writing-documents, boop-writing-semantic-line-breaks
+- **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning, boop-project-mgmt-issue-sweep-workflow, boop-project-mgmt-stray-disposition
 - **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what, boop-skills-hyperlinking, boop-skills-edit-triage
-- **`testing`** — boop-testing-tdd-light, boop-testing-testing-express-web, boop-testing-testing
+- **`testing`** — boop-testing-tdd-light, boop-testing-testing
+- **`typescript`** — boop-typescript-testing
 - **`ux`** — boop-ux-purpose-judgement, boop-ux-visual-judgement, boop-ux-eval-and-refine-workflow, boop-ux-app-ui-dev-workflow
-- **`workflows`** — boop-feature-dev-workflow, boop-light-dev-workflow, boop-refactor-dev-workflow, boop-test-audit-workflow, boop-architecture-audit-workflow, boop-issue-sweep-workflow, boop-website-dev-workflow, boop-design-handoff-workflow, boop-knowledge-backfill, boop-stray-disposition
+- **`workflows`** — boop-feature-dev-workflow, boop-light-dev-workflow, boop-refactor-dev-workflow, boop-test-audit-workflow, boop-architecture-audit-workflow
 
 **Application capabilities**
 
@@ -162,7 +164,7 @@ Adding a capability installs its skills into your project's `skills/` directory.
 - **`email`** — boop-email-email-design
 - **`services`** — boop-services-controllers, boop-services-services
 - **`users-and-accounts`** — boop-users-user-data-modeling
-- **`web`** — boop-web-web-ui-design
+- **`web`** — boop-web-web-ui-design, boop-web-testing, boop-web-website-dev-workflow, boop-web-design-handoff-workflow
 
 _One-line description of each skill: see the bundled `docs/skills.md`._
 <!-- SKILLS-INDEX:END -->

package/dist/capability-catalog.json

@@ -95,7 +95,7 @@
   },
   {
     "name": "project-mgmt",
-    "description": "Project management with beads",
+    "description": "Project management with beads: planning, issue sweeps and stray disposition",
     "type": "development",
     "package": "@boopkit/cap-project-mgmt",
     "requires": []
@@ -116,11 +116,18 @@
   },
   {
     "name": "testing",
-    "description": "Jest testing setup",
+    "description": "Testing method: the testing principles and the TDD-Lite workflow",
     "type": "development",
     "package": "@boopkit/cap-testing",
     "requires": []
   },
+  {
+    "name": "typescript",
+    "description": "TypeScript toolchain: Jest with ts-jest, and the whole-program type check",
+    "type": "development",
+    "package": "@boopkit/cap-typescript",
+    "requires": []
+  },
   {
     "name": "users-and-accounts",
     "description": "Users, identities, properties, and authentication via Prisma",
@@ -148,7 +155,7 @@
   },
   {
     "name": "workflows",
-    "description": "Reusable end-to-end development and writing workflows",
+    "description": "Reusable end-to-end development and audit workflows for code",
     "type": "development",
     "package": "@boopkit/cap-workflows",
     "requires": []

package/dist/capability-versions.json

@@ -1,22 +1,23 @@
 {
   "@boopkit/cap-api": "0.4.5",
-  "@boopkit/cap-background-jobs": "0.5.0",
+  "@boopkit/cap-background-jobs": "0.5.1",
   "@boopkit/cap-cloud-storage": "0.5.0",
-  "@boopkit/cap-coding": "0.4.7",
-  "@boopkit/cap-database": "0.4.5",
+  "@boopkit/cap-coding": "0.4.8",
+  "@boopkit/cap-database": "0.4.6",
   "@boopkit/cap-email": "0.4.4",
   "@boopkit/cap-hello": "0.4.1",
   "@boopkit/cap-noticeboard": "0.4.1",
   "@boopkit/cap-oauth-client": "0.1.1",
-  "@boopkit/cap-oauth-server": "0.3.1",
-  "@boopkit/cap-product-design": "0.6.11",
-  "@boopkit/cap-project-mgmt": "0.4.12",
+  "@boopkit/cap-oauth-server": "0.3.2",
+  "@boopkit/cap-product-design": "0.6.12",
+  "@boopkit/cap-project-mgmt": "0.4.14",
   "@boopkit/cap-services": "0.4.3",
-  "@boopkit/cap-skills": "0.5.6",
-  "@boopkit/cap-testing": "0.5.8",
+  "@boopkit/cap-skills": "0.5.7",
+  "@boopkit/cap-testing": "0.5.9",
+  "@boopkit/cap-typescript": "0.1.0",
   "@boopkit/cap-users": "0.9.0",
-  "@boopkit/cap-ux": "0.2.3",
-  "@boopkit/cap-web": "0.5.6",
-  "@boopkit/cap-workflows": "0.2.2",
+  "@boopkit/cap-ux": "0.2.4",
+  "@boopkit/cap-web": "0.5.7",
+  "@boopkit/cap-workflows": "0.2.3",
   "@boopkit/logger": "0.4.0"
 }

package/dist/commands/add.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAdd = runAdd;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const preflight_1 = require("../lib/preflight");
 const execute_1 = require("../lib/execute");
@@ -61,33 +62,51 @@ function runAdd(capabilityName, options) {
         return;
     }
     const targetDir = process.cwd();
-    // --- Phase 0: Ensure capability package is available locally ---
+    // --- Phase 0: Make the capability package readable without touching the project ---
     // When the CLI is installed globally, capability packages aren't in
-    // node_modules yet. Install the package so preflight can read its
-    // capability.json, scaffold files, etc.
+    // node_modules yet. Pre-flight needs the package's capability.json and
+    // scaffold files, so install it into a staging folder for pre-flight to read;
+    // the project gets it only once the checks pass.
     // With --tag, install from that dist-tag even when a package is present
     // (the operator asked for that version), and skip npm's cached registry
     // metadata, which can predate a just-published beta.
+    let stagingDir;
+    let installCommand;
     if (options.tag || !(0, capability_1.getPackageDir)(capabilityName, [targetDir])) {
         const catalogEntry = (0, capability_1.getCatalogEntry)(capabilityName);
         if (catalogEntry?.package) {
             const spec = options.tag ? `${catalogEntry.package}@${options.tag}` : catalogEntry.package;
             const flags = options.tag ? ' --prefer-online' : '';
-            console.error(`Installing ${spec}...`);
+            installCommand = `npm install ${spec}${flags}`;
+            stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'boop-add-'));
+            console.error(`Fetching ${spec}...`);
             try {
-                (0, child_process_1.execSync)(`npm install ${spec}${flags}`, { cwd: targetDir, stdio: 'pipe' });
+                (0, child_process_1.execSync)(`${installCommand} --prefix ${JSON.stringify(stagingDir)}`, { cwd: stagingDir, stdio: 'pipe' });
             }
             catch (err) {
                 console.error(`\x1b[31mERR\x1b[0m Failed to install ${spec}: ${err.message}`);
+                fs.rmSync(stagingDir, { recursive: true, force: true });
                 process.exitCode = 1;
                 return;
             }
         }
     }
+    try {
+        addCapability(targetDir, capabilityName, options, stagingDir, installCommand);
+    }
+    finally {
+        if (stagingDir)
+            fs.rmSync(stagingDir, { recursive: true, force: true });
+    }
+}
+function addCapability(targetDir, capabilityName, options, stagingDir, installCommand) {
     // --- Phase 1: Pre-flight (read-only) ---
     let plan;
     try {
-        plan = (0, preflight_1.planAdd)(targetDir, capabilityName);
+        plan = (0, preflight_1.planAdd)(targetDir, capabilityName, {
+            searchPaths: stagingDir ? [targetDir, stagingDir] : [targetDir],
+            installCommand,
+        });
     }
     catch (err) {
         if (err instanceof SyntaxError) {
@@ -107,7 +126,7 @@ function runAdd(capabilityName, options) {
         }
         throw err;
     }
-    const { manifest, cap, projectManifest, filesToCopy, warnings } = plan;
+    const { manifest, cap, projectManifest, filesToCopy, warnings, creates } = plan;
     // Emit any warnings from pre-flight
     for (const w of warnings) {
         console.error(w);
@@ -166,6 +185,7 @@ function runAdd(capabilityName, options) {
         console.log(JSON.stringify({
             capability: capabilityName,
             project: projectManifest.name,
+            created: creates,
             files: fileEntries,
             skills: skillEntries,
             nextSteps,
@@ -190,6 +210,14 @@ function runAdd(capabilityName, options) {
     // Human-readable output
     console.log(`\n${'─'.repeat(40)}`);
     console.log(`Added capability "${capabilityName}" to ${projectManifest.name}\n`);
+    if (creates.includes('package.json')) {
+        console.log('Created package.json — a minimal one, because boop records each capability as an npm package there.');
+    }
+    if (creates.includes('.boop/config.json')) {
+        console.log(`Created .boop/config.json — this project is now a boop project, with profile "${projectManifest.profile}".`);
+    }
+    if (creates.length > 0)
+        console.log('');
     if (fileEntries.length > 0) {
         console.log('Files:');
         for (const f of fileEntries) {

package/dist/commands/adopt.js

@@ -65,7 +65,7 @@ function runAdopt(capabilityName, options) {
         throw err;
     }
     if (!manifest) {
-        console.error('Not a boop project (no .boop/config.json found). Run `boop init` to create one.');
+        console.error('Not a boop project (no .boop/config.json found). Run `boop init` in an empty folder, or `boop add <capability>` in an existing project, to create one.');
         process.exitCode = 1;
         return;
     }

package/dist/commands/loop-merge.d.ts

@@ -80,5 +80,16 @@ export declare function isScopeComplete(scope: string, deps: MergeDeps): boolean
  * are ignored.
  */
 export declare function findMergeCandidates(deps: MergeDeps): MergeCandidate[];
+/**
+ * A readable, bounded issue description for a post-rebase test failure: the
+ * cause, the restored commit, the first failures, the Jest summary, and where
+ * the full output lives.
+ */
+export declare function testFailureDescription(o: {
+    branch: string;
+    origSha: string;
+    output: string;
+    logPath: string | null;
+}): string;
 export declare function runMerge(options: LoopOptions, deps?: MergeDeps): Promise<void>;
 export {};

package/dist/commands/loop-merge.js

@@ -37,6 +37,7 @@ exports.pickHigherVersion = pickHigherVersion;
 exports.mergePackageJsonContents = mergePackageJsonContents;
 exports.isScopeComplete = isScopeComplete;
 exports.findMergeCandidates = findMergeCandidates;
+exports.testFailureDescription = testFailureDescription;
 exports.runMerge = runMerge;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
@@ -212,35 +213,76 @@ function findMergeCandidates(deps) {
 // ── Merge engine ──────────────────────────────────────────────────────────────
 const defaultExec = (cmd, opts) => (0, child_process_1.execSync)(cmd, { encoding: 'utf8', ...opts });
 class MergeError extends Error {
-    constructor(message, detail) {
+    constructor(message, detail, title = 'Merge conflict') {
         super(message);
         this.detail = detail;
+        this.title = title;
     }
 }
-/** True if the integration tree is on `main` with a clean working tree. */
+// Files bd rewrites in the main checkout on every command, including the ones a
+// loop session runs from its own worktree. A change to them is beads bookkeeping,
+// not work in progress, so it does not block a merge on its own.
+const BEADS_EXPORT_FILES = ['.beads/interactions.jsonl', '.beads/issues.jsonl'];
+/**
+ * Throws unless the integration tree is on `main` with no uncommitted changes
+ * beyond beads' export files. Returns the export files that are uncommitted.
+ */
 function assertCleanMain(execSyncFn, projectDir) {
     const exec = execSyncFn;
     const branch = exec('git rev-parse --abbrev-ref HEAD', { cwd: projectDir }).trim();
     if (branch !== 'main') {
         throw new Error(`Integration tree at ${projectDir} is on "${branch}", not "main". Checkout main before merging.`);
     }
-    const status = exec('git status --porcelain', { cwd: projectDir }).trim();
-    if (status) {
-        throw new Error(`Integration tree at ${projectDir} has uncommitted changes; commit or stash before merging.`);
+    // Not trimmed: each porcelain line starts with a two-column status that may be a space.
+    const changed = exec('git status --porcelain', { cwd: projectDir })
+        .split('\n')
+        .filter((l) => l.trim())
+        .map((l) => l.slice(3));
+    const others = changed.filter((f) => !BEADS_EXPORT_FILES.includes(f));
+    if (others.length > 0) {
+        throw new Error(`Integration tree at ${projectDir} has uncommitted changes (${others.join(', ')}); commit or stash before merging.`);
+    }
+    return changed;
+}
+/**
+ * Throws if the branch changes a beads export file that is uncommitted in main,
+ * since the fast-forward would then run over that uncommitted change.
+ */
+function assertBranchAvoids(exec, projectDir, branch, dirty) {
+    if (dirty.length === 0)
+        return;
+    const touched = exec(`git diff --name-only main...${branch}`, { cwd: projectDir })
+        .split('\n')
+        .map((l) => l.trim());
+    const overlap = dirty.filter((f) => touched.includes(f));
+    if (overlap.length > 0) {
+        throw new Error(`${branch} changes ${overlap.join(', ')}, which is uncommitted in the integration tree at ${projectDir}; commit it in main before merging.`);
     }
 }
 /**
  * Rebase the candidate branch onto main inside its worktree, auto-resolving only
  * package.json dependency conflicts. Throws MergeError (rebase aborted) on any
- * other conflict.
+ * other conflict, and on any rebase that does not complete, so the branch is
+ * never tested or merged un-rebased.
  */
 function rebaseOntoMain(exec, wt) {
+    // git refuses to rebase over uncommitted tracked changes (`npm install` can
+    // rewrite package-lock.json); checking first lets the issue name the files.
+    const uncommitted = exec('git status --porcelain --untracked-files=no', { cwd: wt })
+        .split('\n')
+        .filter((l) => l.trim())
+        .map((l) => l.slice(3));
+    if (uncommitted.length > 0) {
+        throw new MergeError(`worktree has uncommitted changes (${uncommitted.join(', ')})`, `Uncommitted files in ${wt}: ${uncommitted.join(', ')}. Commit or discard them in the worktree.`, 'Merge blocked');
+    }
+    let failure = '';
     try {
         exec('git rebase main', { cwd: wt, stdio: 'pipe' });
         return;
     }
-    catch {
+    catch (e) {
         // Conflict (or other failure). Inspect unmerged paths.
+        failure = commandOutput(e);
     }
     // Iteratively resolve package.json-only conflicts and continue.
     for (let guard = 0; guard < 100; guard++) {
@@ -285,29 +327,40 @@ function rebaseOntoMain(exec, wt) {
             exec('GIT_EDITOR=true git rebase --continue', { cwd: wt, stdio: 'pipe' });
             return; // rebase finished
         }
-        catch {
+        catch (e) {
             // More commits ahead may conflict again — loop and re-inspect.
+            failure = commandOutput(e);
         }
     }
+    // No unmerged paths, yet the rebase did not finish: git refused it outright
+    // (e.g. untracked files main would overwrite). Abort any partial rebase.
+    try {
+        exec('git rebase --abort', { cwd: wt, stdio: 'pipe' });
+    }
+    catch {
+        /* no rebase in progress — git refused before starting */
+    }
+    throw new MergeError('rebase did not complete', `git said:\n\n${failure.trim()}`, 'Merge blocked');
 }
 function mergeOne(candidate, deps) {
     const projectDir = deps.projectDir || process.cwd();
     const exec = deps.execSyncFn || defaultExec;
     const createIssue = deps.createIssueFn || defaultCreateIssue(deps);
     const { branch, worktreePath: wt } = candidate;
-    assertCleanMain(exec, projectDir);
+    const dirtyExports = assertCleanMain(exec, projectDir);
+    assertBranchAvoids(exec, projectDir, branch, dirtyExports);
     const origSha = exec('git rev-parse HEAD', { cwd: wt }).trim();
     try {
         rebaseOntoMain(exec, wt);
     }
     catch (e) {
         const err = e;
-        const issueId = createIssue(`Merge conflict: ${branch}`, `Rebasing ${branch} onto main failed: ${err.message}\n\n${err.detail || ''}\n\nResolve by hand, then re-run \`boop loop --merge ${branch}\`.`);
+        const issueId = createIssue(`${err.title}: ${branch}`, `Rebasing ${branch} onto main failed: ${err.message}\n\n${err.detail || ''}\n\nResolve by hand, then re-run \`boop loop --merge ${branch}\`.`);
         return { branch, status: 'skipped', reason: err.message, issueId };
     }
     // Post-rebase test gate. Failure → restore the branch, never touch main.
     try {
-        exec('npm test', { cwd: wt, stdio: 'pipe' });
+        exec('npm test', { cwd: wt, stdio: 'pipe', maxBuffer: TEST_OUTPUT_MAX_BUFFER });
     }
     catch (e) {
         try {
@@ -316,7 +369,9 @@ function mergeOne(candidate, deps) {
         catch {
             /* best-effort restore */
         }
-        const issueId = createIssue(`Merge test failure: ${branch}`, `Tests failed after rebasing ${branch} onto main; branch reset to ${origSha} and main left untouched.\n\n${e.message}`);
+        const output = commandOutput(e);
+        const logPath = writeTestLog(projectDir, branch, output);
+        const issueId = createIssue(`Merge test failure: ${branch}`, testFailureDescription({ branch, origSha, output, logPath }));
         return { branch, status: 'skipped', reason: 'tests failed post-rebase', issueId };
     }
     // Fast-forward into main (guaranteed possible: branch was just rebased onto it).
@@ -341,11 +396,77 @@ function mergeOne(candidate, deps) {
     }
     return { branch, status: 'merged' };
 }
+// A Jest run's stderr can run to hundreds of kilobytes; past the 1 MiB default
+// execSync throws ENOBUFS and the summary at the end is lost.
+const TEST_OUTPUT_MAX_BUFFER = 64 * 1024 * 1024;
+const DESCRIPTION_FAILURES_MAX = 4000;
+const DESCRIPTION_SUMMARY_MAX = 2000;
+/** stdout + stderr of a failed execSync, falling back to the error message. */
+function commandOutput(e) {
+    const err = e;
+    const text = [err.stdout, err.stderr]
+        .map((s) => (s == null ? '' : String(s)))
+        .filter(Boolean)
+        .join('\n');
+    return text || err.message || '';
+}
+/** Save the full test output beside the loop's other run logs. Returns the path, or null. */
+function writeTestLog(projectDir, branch, output) {
+    try {
+        const logDir = path.join(projectDir, 'labs', 'claude-runs');
+        fs.mkdirSync(logDir, { recursive: true });
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const logPath = path.join(logDir, `_merge_${branch.replace(/[^\w.-]+/g, '_')}_${timestamp}.log`);
+        fs.writeFileSync(logPath, output);
+        return logPath;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A readable, bounded issue description for a post-rebase test failure: the
+ * cause, the restored commit, the first failures, the Jest summary, and where
+ * the full output lives.
+ */
+function testFailureDescription(o) {
+    const lines = o.output.split('\n');
+    const summaryAt = lines.map((l) => l.startsWith('Test Suites:')).lastIndexOf(true);
+    const summary = summaryAt >= 0 ? lines.slice(summaryAt).join('\n').trim() : '';
+    const firstFailureAt = lines.findIndex((l) => l.trimStart().startsWith('● '));
+    const failures = firstFailureAt >= 0
+        ? lines.slice(firstFailureAt, summaryAt >= 0 ? summaryAt : undefined).join('\n')
+        : summary
+            ? ''
+            : o.output.slice(-DESCRIPTION_FAILURES_MAX);
+    const parts = [
+        `Tests failed after rebasing ${o.branch} onto main; branch reset to ${o.origSha} and main left untouched.`,
+    ];
+    if (failures)
+        parts.push(`First failures:\n\n${truncate(failures.trim(), DESCRIPTION_FAILURES_MAX)}`);
+    if (summary)
+        parts.push(`Summary:\n\n${truncate(summary, DESCRIPTION_SUMMARY_MAX)}`);
+    parts.push(o.logPath ? `Full test output: ${o.logPath}` : 'The full test output could not be saved.');
+    return parts.join('\n\n');
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}\n… (truncated)`;
+}
+// bd runs from an argument array, not a shell: titles and descriptions carry
+// branch names, error messages and test output, where backticks and `$(...)`
+// would otherwise run as commands. `env` is passed explicitly so a PATH set on
+// this module's process.env (as a test sandbox does) decides which bd runs.
 function defaultCreateIssue(deps) {
-    const exec = deps.execSyncFn || defaultExec;
+    const projectDir = deps.projectDir || process.cwd();
     return (title, description) => {
         try {
-            const raw = exec(`bd create ${JSON.stringify(title)} --description=${JSON.stringify(description)} -t bug -p 1 --json`);
+            const raw = (0, child_process_1.execFileSync)('bd', ['create', title, '--description', description, '-t', 'bug', '-p', '1', '--json'], {
+                cwd: projectDir,
+                env: process.env,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                maxBuffer: loop_1.BD_READ_MAX_BUFFER,
+            });
             return JSON.parse(raw).id || null;
         }
         catch {

package/dist/commands/loop.d.ts

@@ -244,6 +244,17 @@ export declare function getMatchingReadyIssues(prefix: string, includeFeatures:
         maxBuffer?: number;
     }) => string;
 }): ReadyIssue[];
+/** A skill folder in a project's skills/ directory. */
+export interface InstalledSkill {
+    name: string;
+    hasProjectFile: boolean;
+}
+/**
+ * The skills installed in a project folder: each folder under skills/ that holds
+ * a SKILL.md. statSync follows symlinks, which matters because boop's own
+ * skills/ entries are symlinks into each capability package's skills/ folder.
+ */
+export declare function readInstalledSkills(projectDir: string): InstalledSkill[];
 /**
  * The instructions every loop session starts from. A session acts on this text
  * literally and reads it whether or not it opens a skill, so step 5 carries the
@@ -251,8 +262,15 @@ export declare function getMatchingReadyIssues(prefix: string, includeFeatures:
  * when the issue asks) and names no command, because the text is the same in
  * every project and the commands are not. For the same reason it names no
  * project.
+ *
+ * Step 3 lists, as paths, the installed skills the issue names: each SKILL.md,
+ * plus the PROJECT.md beside it where there is one. Sessions open a skill they
+ * only see named about one time in seven, but read a path the prompt spells out.
+ * An issue that names no installed skill is pointed at boop-skills-discovery
+ * instead, and without `installed` (or without discovery installed) step 3 keeps
+ * the general "read relevant skills" wording.
  */
-export declare function buildPrompt(issue: IssueInfo): string;
+export declare function buildPrompt(issue: IssueInfo, installed?: InstalledSkill[]): string;
 /**
  * Default per-issue budget cap in USD. The planning phase and each task each get
  * this cap. Single source of truth — imported by cli.ts for its --budget help

package/dist/commands/loop.js

@@ -52,6 +52,7 @@ exports.isIssueInScope = isIssueInScope;
 exports.isClaimableReadyIssue = isClaimableReadyIssue;
 exports.shouldCloseFeatureRoot = shouldCloseFeatureRoot;
 exports.getMatchingReadyIssues = getMatchingReadyIssues;
+exports.readInstalledSkills = readInstalledSkills;
 exports.buildPrompt = buildPrompt;
 exports.shouldRotateSession = shouldRotateSession;
 exports.sessionDidWork = sessionDidWork;
@@ -883,6 +884,65 @@ function isIssueClosed(id) {
         return false;
     }
 }
+/**
+ * The skills installed in a project folder: each folder under skills/ that holds
+ * a SKILL.md. statSync follows symlinks, which matters because boop's own
+ * skills/ entries are symlinks into each capability package's skills/ folder.
+ */
+function readInstalledSkills(projectDir) {
+    const skillsDir = path.join(projectDir, 'skills');
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const name of entries) {
+        const dir = path.join(skillsDir, name);
+        try {
+            if (!fs.statSync(dir).isDirectory() || !fs.existsSync(path.join(dir, 'SKILL.md')))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        skills.push({ name, hasProjectFile: fs.existsSync(path.join(dir, 'PROJECT.md')) });
+    }
+    return skills;
+}
+/**
+ * The installed skills an issue description names, by bare name or by path, in
+ * the order each is first mentioned. A name only matches whole, so
+ * boop-testing-testing does not match inside boop-testing-testing-integration.
+ */
+function namedSkills(description, installed) {
+    const found = [];
+    for (const skill of installed) {
+        const escaped = skill.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const match = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`).exec(description);
+        if (match)
+            found.push({ skill, at: match.index });
+    }
+    return found.sort((a, b) => a.at - b.at).map((f) => f.skill);
+}
+function skillStep(issue, installed) {
+    const general = '3. Read relevant skills from skills/ (list folders, read each SKILL.md) before making changes';
+    if (!installed)
+        return general;
+    const named = namedSkills(issue.description, installed);
+    if (named.length > 0) {
+        const lines = named.map((s) => s.hasProjectFile
+            ? `   - skills/${s.name}/SKILL.md and skills/${s.name}/PROJECT.md`
+            : `   - skills/${s.name}/SKILL.md`);
+        return `3. Before making changes, read each of these in full, unless you have already read it in this session:\n${lines.join('\n')}`;
+    }
+    if (installed.some((s) => s.name === 'boop-skills-discovery')) {
+        return '3. Follow skills/boop-skills-discovery/SKILL.md to choose the skills relevant to this work, and read those skills before making changes';
+    }
+    return general;
+}
 /**
  * The instructions every loop session starts from. A session acts on this text
  * literally and reads it whether or not it opens a skill, so step 5 carries the
@@ -890,8 +950,15 @@ function isIssueClosed(id) {
  * when the issue asks) and names no command, because the text is the same in
  * every project and the commands are not. For the same reason it names no
  * project.
+ *
+ * Step 3 lists, as paths, the installed skills the issue names: each SKILL.md,
+ * plus the PROJECT.md beside it where there is one. Sessions open a skill they
+ * only see named about one time in seven, but read a path the prompt spells out.
+ * An issue that names no installed skill is pointed at boop-skills-discovery
+ * instead, and without `installed` (or without discovery installed) step 3 keeps
+ * the general "read relevant skills" wording.
  */
-function buildPrompt(issue) {
+function buildPrompt(issue, installed) {
     return `You are working on issue ${issue.id} in this project.
 
 ## Issue: ${issue.title}
@@ -903,7 +970,7 @@ ${issue.description}
 ## Instructions
 1. Read AGENTS.md for project orientation
 2. Claim the issue: bd update ${issue.id} --claim
-3. Read relevant skills from skills/ (list folders, read each SKILL.md) before making changes
+${skillStep(issue, installed)}
 4. Implement the changes following TDD-Lite: observe, implement, verify
 5. Run the tests this issue needs, and no more:
    - If the issue description states which tests to run, run exactly those and skip the rest of this step. The issue's scope replaces the default below; do not run both.
@@ -1201,7 +1268,8 @@ async function processIssue(issue, opts) {
         }
     }
     // Initial run
-    const prompt = buildPrompt(issue);
+    // opts.cwd is the worktree the session runs in, so its skills/ is the one the session sees.
+    const prompt = buildPrompt(issue, readInstalledSkills(opts.cwd ?? process.cwd()));
     console.log(`\x1b[32m[bd-loop]\x1b[0m   🚀 Starting Claude session (budget: $${opts.budget}, session: ${sessionId.substring(0, 8)}...)`);
     const initialRun = await runClaude(prompt, {
         budget: opts.budget,

package/dist/commands/migrate-skill-edits.js

@@ -51,7 +51,7 @@ function runMigrateSkillEdits(deps = {}) {
     const projectDir = process.cwd();
     const manifest = (0, project_1.readProjectManifest)(projectDir);
     if (!manifest) {
-        console.error('\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run `boop init` first.');
+        console.error('\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run `boop init` in an empty folder, or `boop add <capability>` in an existing project, first.');
         process.exitCode = 1;
         return;
     }
@@ -67,7 +67,7 @@ async function runApplySkillEdits(deps = terminalDeps()) {
     const projectDir = process.cwd();
     const manifest = (0, project_1.readProjectManifest)(projectDir);
     if (!manifest) {
-        console.error('\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run `boop init` first.');
+        console.error('\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run `boop init` in an empty folder, or `boop add <capability>` in an existing project, first.');
         process.exitCode = 1;
         return;
     }

package/dist/commands/status.d.ts

@@ -1,4 +1,5 @@
 import { BoopManifest } from '../lib/project';
+import { MoveState } from '../lib/moves';
 export interface CapabilityStatusEnvVar {
     required?: string;
     set: boolean;
@@ -13,6 +14,15 @@ export interface CapabilityStatus {
     reachable?: boolean;
     /** Skills whose SKILL.md this project has edited, which no boop update can improve until the edits move out */
     skillEdits?: SkillEditsStatus;
+    /** Paths leaving this capability for another, which the move pass of `boop update` has not settled */
+    moves?: PendingMove[];
+}
+export interface PendingMove {
+    path: string;
+    toCapability: string;
+    toPath: string;
+    state: MoveState;
+    instruction: string;
 }
 export interface SkillEditsStatus {
     edited: number;