@boopkit/cli 0.6.1 → 0.6.8

package/README.md

@@ -73,7 +73,7 @@ A profile is where a project starts. Today there's one; more will follow as the
 
 Full-stack web application — Express + Handlebars + Tailwind CSS + PostgreSQL via Prisma, deployable to Heroku.
 
-Ships with application capabilities (`web`, `api`, `services`, `database`), development skills (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`), and the `hello` demo capability.
+Ships with application capabilities (`web`, `api`, `services`, `database`), development skills (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`), and the `hello` demo capability.
 
 List profiles with `boop list profiles`.
 
@@ -105,8 +105,38 @@ Pick what the product needs. `boop add <name>` handles the wiring — npm depend
 | `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 |
 | `skills` | Skill-authoring and skill-discovery guidance for extending the skill library |
+| `workflows` | Reusable end-to-end dev/writing workflows — feature, light, refactor, test-audit, architecture-audit, issue-sweep, website, design-handoff, knowledge-backfill |
 
-> For the full list of the skills each capability ships — with a one-line description of what each covers — see **`docs/skills.md`**, bundled in the package (run `npm view @boopkit/cli` or open it in your `node_modules/@boopkit/cli/docs/` after install).
+### Skills each capability ships
+
+Adding a capability installs its skills into your project's `skills/` directory. Here's the full set, grouped by capability (one-line descriptions for each are in the bundled `docs/skills.md`):
+
+<!-- SKILLS-INDEX:START -->
+<!-- Generated by `npm run skills:index`. Do not edit by hand. -->
+
+**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
+- **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning
+- **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what
+- **`testing`** — boop-testing-tdd-light, boop-testing-testing-express-web, boop-testing-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
+
+**Application capabilities**
+
+- **`api`** — boop-api-rest-api-design
+- **`background-jobs`** — boop-background-jobs-background-jobs-design
+- **`cloud-storage`** — boop-cloud-storage-cloud-storage
+- **`database`** — boop-database-prisma, boop-database-data-model
+- **`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
+
+_One-line description of each skill: see the bundled `docs/skills.md`._
+<!-- SKILLS-INDEX:END -->
 
 ### Demo
 
@@ -173,6 +203,7 @@ Boop itself is light — Node and npm. The other requirements come from whicheve
 
 - **Node.js 24+** (the `web-app` profile enforces this)
 - **npm** (or any package manager that respects workspaces)
+- **beads (`bd`) 1.1.2+** — if you use the agent workflows or `boop loop`. The tree-building workflows depend on `bd gate` and `bd epic close-eligible` (1.1.x) and on 1.1.2 dependency semantics (plain `blocks` edges; `waits-for` is not used), and `boop loop` needs beads in Dolt server mode. See [beads](https://github.com/gastownhall/beads).
 - **PostgreSQL** — if the `database` capability is installed
 - **RabbitMQ / CloudAMQP account** — if `background-jobs` is installed
 - **SendGrid account** — if `email` is installed

package/dist/capability-catalog.json

@@ -124,5 +124,12 @@
     "type": "application",
     "package": "@boopkit/cap-web",
     "requires": []
+  },
+  {
+    "name": "workflows",
+    "description": "Reusable end-to-end development and writing workflows",
+    "type": "development",
+    "package": "@boopkit/cap-workflows",
+    "requires": []
   }
 ]

package/dist/capability-versions.json

@@ -1,19 +1,20 @@
 {
   "@boopkit/cap-api": "0.4.2",
-  "@boopkit/cap-background-jobs": "0.4.1",
+  "@boopkit/cap-background-jobs": "0.4.2",
   "@boopkit/cap-cloud-storage": "0.4.0",
   "@boopkit/cap-coding": "0.4.2",
   "@boopkit/cap-database": "0.4.3",
-  "@boopkit/cap-email": "0.4.1",
+  "@boopkit/cap-email": "0.4.2",
   "@boopkit/cap-hello": "0.4.0",
   "@boopkit/cap-noticeboard": "0.4.0",
-  "@boopkit/cap-product-design": "0.6.3",
-  "@boopkit/cap-project-mgmt": "0.4.3",
+  "@boopkit/cap-product-design": "0.6.5",
+  "@boopkit/cap-project-mgmt": "0.4.4",
   "@boopkit/cap-services": "0.4.2",
-  "@boopkit/cap-skills": "0.5.1",
-  "@boopkit/cap-testing": "0.5.1",
+  "@boopkit/cap-skills": "0.5.2",
+  "@boopkit/cap-testing": "0.5.2",
   "@boopkit/cap-users": "0.4.3",
-  "@boopkit/cap-ux": "0.2.1",
-  "@boopkit/cap-web": "0.5.1",
+  "@boopkit/cap-ux": "0.2.2",
+  "@boopkit/cap-web": "0.5.2",
+  "@boopkit/cap-workflows": "0.1.0",
   "@boopkit/logger": "0.4.0"
 }

package/dist/cli.js

@@ -119,11 +119,12 @@ program
     .option('--run', 'actually execute (dry-run by default)')
     .option('--max <n>', 'stop after N issues')
     .option('--budget <amount>', `budget cap per issue in USD (default: ${loop_1.DEFAULT_BUDGET_USD})`)
-    .option('--model <model>', 'Claude model to use, applied to every spawned session and nested loop (falls back to $ANTHROPIC_MODEL, then claude-opus-4-8). Sub-agents keep their own declared model unless they opt into model: inherit.')
+    .option('--model <model>', 'Claude model to use, applied to every spawned session and nested loop (falls back to $ANTHROPIC_MODEL, then claude-opus-5). Sub-agents keep their own declared model unless they opt into model: inherit.')
     .option('--poll', 'keep polling when no ready issues found')
     .option('--poll-interval <seconds>', 'seconds between polls (default: 60)')
     .option('--resume-limit <n>', 'max resume attempts per issue (default: 3)')
     .option('--per-issue-branch', 'create a separate branch per issue')
+    .option('--reuse-session', 'issue-driven only: reuse one Claude session across a coherent --prefix run instead of a fresh one per issue, rotating to a fresh session when its context fills. Asserts the scope is coherent enough for carried context to help. Not valid with --work/--flow; mutually exclusive with --per-issue-branch')
     .option('--no-branch', 'skip branch/worktree creation; run in place on the current branch')
     .option('--no-skip-perms', 'do not skip permission prompts')
     .option('--bare', 'force API key auth; skip OAuth/keychain, use ANTHROPIC_API_KEY strictly')
@@ -133,11 +134,13 @@ program
     'Examples:',
     '  boop loop --work specs/feature.spec.md --flow skills/my-flow/SKILL.md --run',
     '  boop loop --prefix boop-abc --run --features',
+    '  boop loop --prefix boop-abc --run --reuse-session   # drain a coherent cluster on one session',
     '  boop loop --merge --run --watch',
     '',
     'Notes:',
     '  • Dry-run by default; add --run to execute.',
     '  • --work and --flow must be used together; --features and --watch only apply to their own mode.',
+    '  • --reuse-session is issue-driven (--prefix) only and cannot combine with --per-issue-branch; the loop rotates to a fresh session on its own when context fills, so issues are never split. Off by default (a fresh session per issue).',
     '  • Merge mode rebases ready work/<id> branches onto main, runs tests, ff-merges, and cleans up worktrees.',
 ].join('\n'))
     .action((options) => (options.merge ? (0, loop_merge_1.runMerge)(options) : (0, loop_1.runLoop)(options)));

package/dist/commands/loop.d.ts

@@ -17,10 +17,15 @@ export interface LoopOptions {
     json?: boolean;
     merge?: boolean | string;
     watch?: boolean;
+    reuseSession?: boolean;
 }
 interface ClaudeRunResult {
     exitCode: number;
     limitHit: boolean;
+    /** Peak context-window occupancy observed on this run, in tokens. */
+    peakContext?: number;
+    /** The model's context window (tokens), from the result's modelUsage. */
+    contextWindow?: number;
 }
 export interface PlanResult {
     featureId: string | null;
@@ -67,6 +72,15 @@ export declare function discoverDoltServer(projectDir: string, deps?: {
  * branch, reuse it (and skip install if node_modules is present); if the path is
  * occupied by something else, throw a clear error rather than silently suffixing.
  */
+/**
+ * Best-effort resolution of the repo's default branch, used to move a launch dir
+ * off a loop feature branch it should never have been parked on (boop-6iw).
+ * Prefers `origin/HEAD`, then a local `main`/`master`, then `main`.
+ */
+export declare function resolveDefaultBranch(execSyncFn: (cmd: string, opts: {
+    encoding: string;
+    cwd?: string;
+}) => string, cwd: string): string;
 export declare function createWorktree(scope: string, mode: WorktreeMode, projectDir: string, deps?: {
     execSyncFn?: (cmd: string, opts: {
         encoding: string;
@@ -136,7 +150,7 @@ export declare function isStandaloneUsageLimitMessage(text: string): boolean;
  * the `ANTHROPIC_MODEL` environment variable, then the built-in default. The env
  * fallback is what lets a nested `boop loop` (spawned by a Claude session that
  * the parent loop launched with ANTHROPIC_MODEL set) inherit the same model
- * instead of silently dropping to the default. Keep the default (claude-opus-4-8)
+ * instead of silently dropping to the default. Keep the default (claude-opus-5)
  * in sync with the `--model` help text in cli.ts.
  */
 export declare function resolveModel(optionModel: string | undefined, env?: NodeJS.ProcessEnv): string;
@@ -202,5 +216,11 @@ export declare const DEFAULT_BUDGET_USD = "25.00";
  * — this clause is the belt-and-suspenders for a block raised mid-resume.
  */
 export declare const RESUME_PROMPT = "The previous session ended without closing this issue. Reload the state and continue.\n\nIMPORTANT: If the previous session marked this issue blocked with a diagnostic, the block stands. Do not re-open it or work around it. Read the issue's notes and the previous session's commits, confirm the block is still appropriate, and stop without taking further action.\n\nOtherwise, complete the workflow:\n- Finish any remaining implementation\n- Run tests to verify\n- Commit changes referencing the issue ID\n- Close the issue with bd close\n- Push with: git pull --rebase && git push\n\nDo not pause for review of completed work. Complete everything now.";
+/**
+ * Decide whether a reused session should rotate before taking the next issue.
+ * Rotates once peak observed occupancy reaches ROTATE_FRACTION of the window.
+ * Pure so it is unit-testable without a running loop.
+ */
+export declare function shouldRotateSession(peakContext: number, contextWindow: number, fraction?: number): boolean;
 export declare function runLoop(options: LoopOptions): Promise<void>;
 export {};

package/dist/commands/loop.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESUME_PROMPT = exports.DEFAULT_BUDGET_USD = void 0;
 exports.assertDoltServerMode = assertDoltServerMode;
 exports.discoverDoltServer = discoverDoltServer;
+exports.resolveDefaultBranch = resolveDefaultBranch;
 exports.createWorktree = createWorktree;
 exports.writeWorktreeMetadata = writeWorktreeMetadata;
 exports.buildPlanningPrompt = buildPlanningPrompt;
@@ -50,6 +51,7 @@ exports.isIssueInScope = isIssueInScope;
 exports.isClaimableReadyIssue = isClaimableReadyIssue;
 exports.shouldCloseFeatureRoot = shouldCloseFeatureRoot;
 exports.getMatchingReadyIssues = getMatchingReadyIssues;
+exports.shouldRotateSession = shouldRotateSession;
 exports.runLoop = runLoop;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
@@ -130,6 +132,31 @@ function discoverDoltServer(projectDir, deps) {
  * branch, reuse it (and skip install if node_modules is present); if the path is
  * occupied by something else, throw a clear error rather than silently suffixing.
  */
+/**
+ * Best-effort resolution of the repo's default branch, used to move a launch dir
+ * off a loop feature branch it should never have been parked on (boop-6iw).
+ * Prefers `origin/HEAD`, then a local `main`/`master`, then `main`.
+ */
+function resolveDefaultBranch(execSyncFn, cwd) {
+    try {
+        const ref = execSyncFn('git symbolic-ref --short refs/remotes/origin/HEAD', { encoding: 'utf8', cwd }).trim();
+        if (ref)
+            return ref.replace(/^origin\//, '');
+    }
+    catch {
+        // origin/HEAD not set — fall through to local candidates.
+    }
+    for (const cand of ['main', 'master']) {
+        try {
+            execSyncFn(`git rev-parse --verify --quiet refs/heads/${cand}`, { encoding: 'utf8', cwd });
+            return cand;
+        }
+        catch {
+            // not present — try next
+        }
+    }
+    return 'main';
+}
 function createWorktree(scope, mode, projectDir, deps) {
     const execSyncFn = deps?.execSyncFn ||
         ((cmd, o) => (0, child_process_1.execSync)(cmd, o));
@@ -281,6 +308,32 @@ function createWorktree(scope, mode, projectDir, deps) {
         branchExists = false;
     }
     if (branchExists) {
+        // Guard (boop-6iw): if the loop branch is checked out in the launch dir — e.g. a
+        // planning phase that ran `git checkout -b work/<id>` in place before the worktree
+        // existed — then `git worktree add <path> <branch>` fails with "already checked
+        // out at <launch-dir>". It also leaves the launch dir parked on the feature branch,
+        // so a concurrent session's next commit lands on the wrong branch. Move the launch
+        // dir back to its default branch first: it both unblocks the worktree add and undoes
+        // the mis-parking. (Flows should not create the branch during planning — see the
+        // light-dev-workflow skill — but this makes any that slip through non-fatal.)
+        let launchBranch = '';
+        try {
+            launchBranch = execSyncFn('git branch --show-current', { encoding: 'utf8', cwd: projectDir }).trim();
+        }
+        catch {
+            // Detached HEAD or no git — nothing of ours is parked; proceed.
+        }
+        if (launchBranch === branch) {
+            const defaultBranch = resolveDefaultBranch(execSyncFn, projectDir);
+            try {
+                execSyncFn(`git checkout ${defaultBranch}`, { encoding: 'utf8', cwd: projectDir });
+            }
+            catch {
+                throw new Error(`Loop branch "${branch}" is checked out in the launch directory (${projectDir}), which blocks ` +
+                    `creating its worktree. Moving the launch dir to "${defaultBranch}" failed — likely uncommitted ` +
+                    `changes there. Commit or stash them (or run \`git checkout ${defaultBranch}\`) and retry.`);
+            }
+        }
         execSyncFn(`git worktree add ${worktreePath} ${branch}`, { encoding: 'utf8', cwd: projectDir });
     }
     else {
@@ -539,11 +592,11 @@ function findClaudeBinary() {
  * the `ANTHROPIC_MODEL` environment variable, then the built-in default. The env
  * fallback is what lets a nested `boop loop` (spawned by a Claude session that
  * the parent loop launched with ANTHROPIC_MODEL set) inherit the same model
- * instead of silently dropping to the default. Keep the default (claude-opus-4-8)
+ * instead of silently dropping to the default. Keep the default (claude-opus-5)
  * in sync with the `--model` help text in cli.ts.
  */
 function resolveModel(optionModel, env = process.env) {
-    return optionModel || env.ANTHROPIC_MODEL || 'claude-opus-4-8';
+    return optionModel || env.ANTHROPIC_MODEL || 'claude-opus-5';
 }
 /**
  * Whether the loop should resume an issue that a session left open. A `blocked`
@@ -793,6 +846,33 @@ Otherwise, complete the workflow:
 - Push with: git pull --rebase && git push
 
 Do not pause for review of completed work. Complete everything now.`;
+/**
+ * Fraction of the context window at which a reused session is rotated for a fresh
+ * one. Deliberately well below Claude Code's auto-compaction point — compaction
+ * silently discards the context the reuse exists to keep, so we rotate first.
+ * The one knob a trial run should tune (specs/loop-session-reuse.spec.md).
+ */
+const ROTATE_FRACTION = 0.55;
+/** Fallback context window (tokens) before the stream has reported a real one. */
+const DEFAULT_CONTEXT_WINDOW = 1000000;
+/**
+ * Live context-window occupancy for one turn, from a stream-json `usage` object:
+ * everything the model had to read this turn (fresh input + cached prompt).
+ */
+function contextOccupancy(usage) {
+    if (!usage)
+        return 0;
+    return (usage.input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
+}
+/**
+ * Decide whether a reused session should rotate before taking the next issue.
+ * Rotates once peak observed occupancy reaches ROTATE_FRACTION of the window.
+ * Pure so it is unit-testable without a running loop.
+ */
+function shouldRotateSession(peakContext, contextWindow, fraction = ROTATE_FRACTION) {
+    const window = contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
+    return peakContext >= fraction * window;
+}
 function runClaude(prompt, opts, logFile, readableLogFile) {
     return new Promise((resolve) => {
         const args = [
@@ -837,6 +917,11 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
             : process.env;
         const child = (0, child_process_1.spawn)(claudeBin, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'], env: childEnv });
         let limitHit = false;
+        // Track context-window pressure from outside the agent (spec: the loop reads
+        // the stream it already parses; the agent is never told). Peak occupancy over
+        // the run drives session rotation; contextWindow comes from the result.
+        let peakContext = 0;
+        let contextWindow;
         child.stdin.write(prompt);
         child.stdin.end();
         child.stdout.on('data', (chunk) => {
@@ -846,6 +931,10 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
                 try {
                     const msg = JSON.parse(line);
                     if (msg.type === 'assistant') {
+                        // Live context occupancy for this turn (read from outside the agent).
+                        const occ = contextOccupancy(msg.message?.usage);
+                        if (occ > peakContext)
+                            peakContext = occ;
                         const texts = (msg.message?.content || [])
                             .filter((c) => c.type === 'text')
                             .map((c) => c.text);
@@ -875,6 +964,16 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
                         if ((msg.is_error || msg.subtype === 'error') && isUsageLimitText(resultText)) {
                             limitHit = true;
                         }
+                        // The result reports the model's context window under modelUsage.<model>.
+                        const mu = msg.modelUsage;
+                        if (mu) {
+                            for (const m of Object.values(mu)) {
+                                if (typeof m?.contextWindow === 'number' && m.contextWindow > 0) {
+                                    contextWindow = m.contextWindow;
+                                    break;
+                                }
+                            }
+                        }
                         const cost = msg.total_cost_usd || '?';
                         const dur = Math.round((msg.duration_ms || 0) / 1000);
                         const turns = msg.num_turns || '?';
@@ -901,12 +1000,12 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
             logStream.end();
             if (readableStream)
                 readableStream.end();
-            resolve({ exitCode: code ?? 1, limitHit });
+            resolve({ exitCode: code ?? 1, limitHit, peakContext, contextWindow });
         });
     });
 }
 async function processIssue(issue, opts) {
-    const sessionId = (0, crypto_1.randomUUID)();
+    const sessionId = opts.session?.id ?? (0, crypto_1.randomUUID)();
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
     const logFile = path.join(opts.logDir, `${issue.id}_${timestamp}.log`);
     const readableLogFile = path.join(opts.logDir, `${issue.id}_${timestamp}.readable.log`);
@@ -944,9 +1043,13 @@ async function processIssue(issue, opts) {
         skipPerms: opts.skipPerms,
         bare: opts.bare,
         sessionId,
+        // Continue a carried session for this new issue (its normal prompt via --resume).
+        resume: opts.session?.resume,
         cwd: opts.cwd,
     }, logFile, readableLogFile);
     let anyLimitHit = initialRun.limitHit;
+    let peakContext = initialRun.peakContext ?? 0;
+    let contextWindow = initialRun.contextWindow;
     if (initialRun.limitHit) {
         console.error('\x1b[31m[bd-loop]\x1b[0m   Claude usage limit reached; stopping retries for this issue');
     }
@@ -977,6 +1080,10 @@ async function processIssue(issue, opts) {
             resume: true,
             cwd: opts.cwd,
         }, logFile, readableLogFile);
+        if (resumeRun.peakContext && resumeRun.peakContext > peakContext)
+            peakContext = resumeRun.peakContext;
+        if (resumeRun.contextWindow)
+            contextWindow = resumeRun.contextWindow;
         if (resumeRun.limitHit) {
             anyLimitHit = true;
             console.error('\x1b[31m[bd-loop]\x1b[0m   Claude usage limit reached during resume; stopping retries for this issue');
@@ -999,7 +1106,7 @@ async function processIssue(issue, opts) {
             // Best effort
         }
     }
-    return { issueId: issue.id, closed, resumes: resumeCount, logFile, limitHit: anyLimitHit };
+    return { issueId: issue.id, closed, resumes: resumeCount, logFile, limitHit: anyLimitHit, sessionId, peakContext, contextWindow };
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -1062,6 +1169,19 @@ async function runLoop(options) {
     const skipPerms = options.skipPerms !== false; // default true
     const bare = options.bare || false;
     const poll = options.poll || false;
+    const reuseSession = options.reuseSession || false;
+    // --reuse-session is a --prefix-mode knob, mutually exclusive with the two things
+    // that imply one-session-per-issue. Errors are plain, not silent winners.
+    if (reuseSession && (work || flow)) {
+        console.error('\x1b[31mERR\x1b[0m --reuse-session is only for --prefix runs, not --work/--flow (spec-driven children are already session-sized)');
+        process.exitCode = 1;
+        return;
+    }
+    if (reuseSession && perIssueBranch) {
+        console.error('\x1b[31mERR\x1b[0m --reuse-session and --per-issue-branch are mutually exclusive (a branch per issue implies a session per issue)');
+        process.exitCode = 1;
+        return;
+    }
     const projectDir = process.cwd();
     const logDir = path.join(projectDir, 'labs', 'claude-runs');
     fs.mkdirSync(logDir, { recursive: true });
@@ -1171,6 +1291,14 @@ async function runLoop(options) {
     let totalProcessed = 0;
     let totalClosed = 0;
     const results = [];
+    // --reuse-session state: a healthy session survives to the next issue; a fresh
+    // one is minted only on rotation (context full) or death. Off → activeSession
+    // stays null and every issue mints its own, exactly as before.
+    let activeSession = null;
+    let sessionCount = 0;
+    // Issue id at each session START (the first entry is the initial session, not a
+    // rotation). Actual rotations are everything after the first — see the summary.
+    const sessionStarts = [];
     while (true) {
         const nextId = prefix ? findNextIssue(prefix, includeFeatures) : null;
         if (!nextId) {
@@ -1238,6 +1366,24 @@ async function runLoop(options) {
             console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to get issue details for ${nextId}`);
             continue;
         }
+        // Decide the session this issue runs under. Reuse a healthy carried session;
+        // otherwise (first issue, or the last one filled up) mint a fresh one. The
+        // decision lands here, between issues, so rotation can never split an issue.
+        let session;
+        if (reuseSession) {
+            if (activeSession && !shouldRotateSession(activeSession.peakContext, activeSession.contextWindow)) {
+                session = { id: activeSession.id, resume: true };
+            }
+            else {
+                if (activeSession) {
+                    console.log(`\x1b[36m[bd-loop]\x1b[0m Session context full (${Math.round(activeSession.peakContext / 1000)}k/${Math.round(activeSession.contextWindow / 1000)}k) — rotating to a fresh session at ${issue.id}`);
+                }
+                session = { id: (0, crypto_1.randomUUID)(), resume: false };
+                activeSession = { id: session.id, peakContext: 0, contextWindow: DEFAULT_CONTEXT_WINDOW };
+                sessionCount++;
+                sessionStarts.push(issue.id);
+            }
+        }
         const result = await processIssue(issue, {
             budget,
             model,
@@ -1248,10 +1394,22 @@ async function runLoop(options) {
             noBranch,
             logDir,
             cwd: loopCwd,
+            session,
         });
         results.push(result);
         if (result.closed)
             totalClosed++;
+        // Fold this issue's observed context back into the carried session so the next
+        // iteration's rotation decision is current. A limit/death drops the session so
+        // the next issue starts clean (recovery lands between issues, same as rotation).
+        if (reuseSession && activeSession) {
+            if (result.peakContext)
+                activeSession.peakContext = Math.max(activeSession.peakContext, result.peakContext);
+            if (result.contextWindow)
+                activeSession.contextWindow = result.contextWindow;
+            if (result.limitHit)
+                activeSession = null;
+        }
         if (result.limitHit) {
             console.error('\x1b[31m[bd-loop]\x1b[0m   Credit/usage limit hit — stopping loop');
             break;
@@ -1270,6 +1428,14 @@ async function runLoop(options) {
         if (totalProcessed > totalClosed) {
             console.log(`\x1b[33m[bd-loop]\x1b[0m   Not closed: ${totalProcessed - totalClosed}`);
         }
+        if (reuseSession) {
+            console.log(`\x1b[32m[bd-loop]\x1b[0m   Sessions:  ${sessionCount} (--reuse-session)`);
+            // The first session start is not a rotation; only entries after it are.
+            const rotatedAt = sessionStarts.slice(1);
+            if (rotatedAt.length > 0) {
+                console.log(`\x1b[32m[bd-loop]\x1b[0m   Rotated at: ${rotatedAt.join(', ')}`);
+            }
+        }
     }
     console.log(`\x1b[32m[bd-loop]\x1b[0m   Logs: ${logDir}/`);
     if (worktreeCtx) {
@@ -1283,6 +1449,7 @@ async function runLoop(options) {
             totalClosed,
             results,
             worktree: worktreeCtx ? { path: worktreeCtx.path, branch: worktreeCtx.branch, mode: worktreeCtx.mode } : null,
+            sessions: reuseSession ? { count: sessionCount, rotatedAt: sessionStarts.slice(1) } : null,
         }, null, 2));
     }
 }

package/docs/loop.md

@@ -52,8 +52,9 @@ If `--prefix` is also provided, it is passed to the planning session as a naming
 | `--resume-limit <n>` | `3` | Maximum resume attempts if issue isn't closed |
 | `--poll` | off | Keep polling when no ready issues found |
 | `--poll-interval <s>` | `60` | Seconds between polls |
-| `--model <model>` | `claude-opus-4-6` | Claude model to use |
+| `--model <model>` | `claude-opus-5` | Claude model to use (falls back to `$ANTHROPIC_MODEL`, then this default) |
 | `--per-issue-branch` | off | Create a `fix/<issue-id>` branch per issue (nested inside the worktree) |
+| `--reuse-session` | off | (`--prefix` only) Reuse one Claude session across a coherent run of issues, rotating to a fresh session when its context fills. Mutually exclusive with `--per-issue-branch` |
 | `--no-branch` | off | Opt out of worktree isolation; run in-place on the current branch |
 | `--features` | off | Include feature-type issues (auto-enabled in planning mode) |
 | `--no-skip-perms` | off | Don't skip Claude permission prompts |

package/docs/skills.md

@@ -21,7 +21,8 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-product-design-feature-requirements** — When you need to write a feature spec, draft a spec document, or turn a brief or vague directive into requirements — i.e. define what a feature should accomplish before designing how to build it. This fires even when you frame the task to yourself as just 'writing a spec' or 'matching the house spec format': reading an existing spec to imitate its shape is not a substitute for the method, and the more competent you feel at the raw task the more this applies. Start with the user's jobs to be done, in frequency order; take and defend a stance; then derive goals, non-goals, and success metrics.
 - **boop-product-design-reference-integration** — When you need to integrate new knowledge into the project's `reference/` directory after completing a feature, fixing a bug that changes behavior, or adding a capability.
 - **boop-product-design-thought-partnership** — When the user wants to think out loud through a design — a feature, a capability, a strategic direction — be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, and keep software-shaped concerns downstream of the user's lived problems.
-- **boop-writing-technical-prose** — When writing chat responses, bd issue bodies, or any artifact a fresh reader will pick up cold, write grammatical conversational English. Avoid the agent-shorthand patterns that compress meaning at the cost of legibility.
+- **boop-writing-technical-prose** — When writing chat responses, summaries, bd issue bodies, specifications, specs, or any artifact a fresh reader will pick up cold, write grammatical conversational English. Avoid the agent-shorthand patterns that compress meaning at the cost of legibility.
+- **boop-writing-documents** — When you need to write a document someone will read cold and act on — a proposal, strategy memo, analysis, recommendation, or status write-up — and want the discipline of the Amazon six-pager: narrative prose, a declared length budget, claims that carry their evidence, and the hard questions answered inside the document.
 
 ### `project-mgmt` — Project management with beads
 
@@ -33,6 +34,8 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-skill-authoring** — When you need to add or update an agent skill in this project, follow this format and checklist.
 - **boop-skills-discovery** — When you pick up a non-trivial task, sweep the available skills for ones relevant to the work before you start, as a backstop for an issue that missed a breadcrumb.
 - **boop-skills-agent-surface-design** — When you design or audit tool surfaces (tools, schemas, APIs, conventions) that LLM agents will reach for, decide where to put the friction — adapt the system to the agent, or make the existing thing more discoverable. Last resort: prompt-engineer.
+- **boop-get-smart** — When there is a recurring fault in your own behaviour during a chat, run the five whys to find its root cause, and agree a change with the operator that makes it less likely.
+- **boop-so-what** — When the operator asks for the so-what, or says some version of 'thanks for the essay', compress what you just produced into three sentences about what they should care about.
 
 ### `testing` — Jest testing setup
 
@@ -47,6 +50,18 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-ux-eval-and-refine-workflow** — When you are tasked with iteratively evaluating and improving an existing rendered page (discovery, not delivery), follow this workflow. Inner loop: capture → eval → recommend → implement → re-capture. Outer: knowledge integration.
 - **boop-ux-app-ui-dev-workflow** — When you are tasked with improving an existing app-side page (app UX, not marketing) end-to-end and the input is a target page rather than a written spec, follow this beads-issue-per-step workflow. Sibling to feature-dev-workflow but stripped of backend phases. The judgement lenses are the planning input.
 
+### `workflows` — Reusable end-to-end development and writing workflows
+
+- **boop-feature-dev-workflow** — When you are tasked with building a feature end-to-end, follow this guidance.
+- **boop-light-dev-workflow** — When you are extending an existing system (front-end, back-end, or full-stack) toward a goal — wiring something new from data and patterns that already exist, not building greenfield — follow this grounded flow: goal → investigate the real system → design → critique → decompose into one scoped epic + child issues → run them → close out. Loop-drivable via boop loop --work --flow; lighter than feature-dev-workflow.
+- **boop-refactor-dev-workflow** — When you need to change a contract, cardinality, or shape that existing code already depends on — usually to make a feature buildable — follow this workflow instead of the feature workflow.
+- **boop-test-audit-workflow** — Use when a set of tests is not testing the purpose of the code: mocks that verify data the test itself fed in, tests that exercise the platform rather than our code, or a stubbed seam where the integration is the actual risk. Also use when tests are so coupled to the shape of the implementation that they check a label, an exact string, or a call sequence rather than a behaviour. This workflow removes tests that cannot go red for a real reason, rewrites the ones that check a real goal at the wrong level, merges duplicates, and does not lose coverage. It explicitly does not target good tests merely because a coming change will make them need updating. The sibling of light-dev-workflow for reworking tests rather than building features.
+- **boop-architecture-audit-workflow** — When you need to judge whether an area of shipped code is structurally healthy and decide what is worth fixing — undesired coupling, concerns bleeding across layers or domain boundaries, interfaces that are not composable because they are use-case specific or unparameterized — follow this process: scope one area and name the properties it should uphold → check the tests can catch you → measure before reading → grade every property and classify every finding against a named change → critique → operator gate → decompose → execute via refactor-dev-workflow. The sibling of test-audit-workflow for production code rather than tests. Not for finding bugs, and not for executing a structural change you have already decided on.
+- **boop-issue-sweep-workflow** — When the bd queue has accumulated a noisy backlog of lingering P1/P2 items — paper-cuts, small refactors, dead code, cosmetic bugs, taxonomy drift — and you want to clear them autonomously in a sequence that supports the week's goals, follow this process: inventory → cluster by theme → pick a cluster with the operator → run autonomously in one sweep worktree → hand off for a single UAT pass → log. The work lands in a worktree for one operator review rather than on main; it arrives with no decisions left in it.
+- **boop-website-dev-workflow** — When you are tasked with implementing website changes end-to-end (new pages, page rewrites, IA changes, content/CTA updates), follow this guidance.
+- **boop-design-handoff-workflow** — When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run.
+- **boop-knowledge-backfill** — When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established.
+
 ## Application capabilities
 
 ### `api` — REST API with Express
@@ -85,4 +100,4 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 
 ---
 
-Standalone workflow skills (e.g. `boop-feature-dev-workflow`, `boop-light-dev-workflow`, `boop-issue-sweep-workflow`, `boop-design-handoff-workflow`) live in the repo's top-level `skills/` directory rather than in a capability package, so they are not listed above.
+Boop-maintainer skills (e.g. `boop-capability-development`, `boop-downstream-harvest`, `boop-loop-conductor`, `boop-dolt-recovery`) live in the repo's top-level `skills/` directory rather than in a capability package, so they do not ship and are not listed above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.1",
+  "version": "0.6.8",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [

package/profiles/web-app/profile.md

@@ -13,6 +13,7 @@ defaultCapabilities:
   - project-mgmt
   - product-design
   - skills
+  - workflows
   # Demo
   - hello
 kernel: