@boopkit/cli 0.6.0 → 0.6.7

package/README.md

@@ -102,8 +102,39 @@ Pick what the product needs. `boop add <name>` handles the wiring — npm depend
 | `coding` | Development conventions and coding skills for AI agents |
 | `testing` | Jest setup and testing skills (TDD workflow, Express testing patterns) |
 | `project-mgmt` | Beads issue-tracking and planning skills |
-| `product-design` | Feature-requirements and product-design skills |
-| `skills` | Skill-authoring guidance for extending the skill library |
+| `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 |
+
+### 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
+- **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning
+- **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design
+- **`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
+
+**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
 
@@ -138,11 +169,11 @@ Flags:
 
 Boop is built for agent-assisted work — the skills and conventions ship with the code so your agent has real guidance, not just a blank repo. Every scaffolded project includes:
 
-- **Skills** — every capability installs skill folders into `skills/`. These are focused, task-specific instructions (each folder contains a `SKILL.md`, e.g. `skills/rest-api-design/SKILL.md`, `skills/tdd-light/SKILL.md`) that tell an agent the conventions this project uses.
+- **Skills** — every capability installs skill folders into `skills/`. These are focused, task-specific instructions (each folder contains a `SKILL.md`, e.g. `skills/boop-api-rest-api-design/SKILL.md`, `skills/boop-testing-tdd-light/SKILL.md`) that tell an agent the conventions this project uses. See the bundled **`docs/skills.md`** for the full index of what each capability ships.
 - **`boop status`** — after `boop init` or `boop add`, run `boop status`. It prints every capability's post-install steps. Hand this to your agent and say "finish setup."
 - **`boop loop`** — Uses Claude for 'unattended work', building working code and UI from your specifications. 
-  - `prefix` mode: Plan work as a tree of issues, then `boop loop --prefix <id>` processes them one at a time, each in its own Claude Code session. Dry-run by default; budget-capped; resumes unfinished work. See [docs/loop.md](docs/loop.md).
-  - `workflow` mode: Provide your spec and the bundled `feature-dev-workflow` skill to `boop loop --work <spec> --flow <skill>`. It processes the spec requirements into a technical design, a set of linked tasks and then continuously processes issues until the work is complete. See [docs/loop.md](docs/loop.md#workflow-mode).
+  - `prefix` mode: Plan work as a tree of issues, then `boop loop --prefix <id>` processes them one at a time, each in its own Claude Code session. Dry-run by default; budget-capped; resumes unfinished work. See the bundled `docs/loop.md`.
+  - `workflow` mode: Provide your spec and the bundled `feature-dev-workflow` skill to `boop loop --work <spec> --flow <skill>`. It processes the spec requirements into a technical design, a set of linked tasks and then continuously processes issues until the work is complete. See the bundled `docs/loop.md`.
 
 The workflow is designed so a human sets direction, an agent does the implementation, and boop provides the rails.
 
@@ -170,17 +201,19 @@ 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
 - **AWS S3 bucket** — if `cloud-storage` is installed
 
-## Links
+## Bundled docs
+
+These ship inside the package (under `docs/`) — open them after install in `node_modules/@boopkit/cli/docs/`:
 
-- **[docs/init.md](docs/init.md)** — detailed `boop init` walkthrough
-- **[docs/loop.md](docs/loop.md)** — automated agent workflow
-- **[GitHub repo](https://github.com/boop-labs/boop)** — source and issues
-- **[Contributing](https://github.com/boop-labs/boop/blob/main/CONTRIBUTING.md)** — dev setup, architecture, how to add a capability
+- **`docs/init.md`** — detailed `boop init` walkthrough
+- **`docs/loop.md`** — automated agent workflow
+- **`docs/skills.md`** — index of every capability's agent skills
 
 ## License
 

package/dist/capability-versions.json

@@ -1,19 +1,19 @@
 {
-  "@boopkit/cap-api": "0.4.1",
-  "@boopkit/cap-background-jobs": "0.4.0",
+  "@boopkit/cap-api": "0.4.2",
+  "@boopkit/cap-background-jobs": "0.4.2",
   "@boopkit/cap-cloud-storage": "0.4.0",
-  "@boopkit/cap-coding": "0.4.1",
+  "@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.1",
-  "@boopkit/cap-project-mgmt": "0.4.1",
+  "@boopkit/cap-product-design": "0.6.4",
+  "@boopkit/cap-project-mgmt": "0.4.4",
   "@boopkit/cap-services": "0.4.2",
   "@boopkit/cap-skills": "0.5.1",
-  "@boopkit/cap-testing": "0.5.0",
-  "@boopkit/cap-users": "0.4.2",
-  "@boopkit/cap-ux": "0.2.0",
-  "@boopkit/cap-web": "0.5.0",
+  "@boopkit/cap-testing": "0.5.1",
+  "@boopkit/cap-users": "0.4.3",
+  "@boopkit/cap-ux": "0.2.2",
+  "@boopkit/cap-web": "0.5.2",
   "@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;
@@ -168,12 +182,13 @@ export declare function isClaimableReadyIssue(issue: {
     issue_type: string;
 }, hasChildren: (id: string) => boolean): boolean;
 /**
- * Decide whether the loop should close a feature root itself, as a safety net,
+ * Decide whether the loop should close a container root itself, as a safety net,
  * when its workflow chain has completed. The intended owner of this close is the
- * closeout child task (see boop-feature-dev-workflow SKILL step 6), but if that
- * task never closed the root — or no closeout task exists — the feature would be
- * orphaned open forever once filtered from claimable work. Only close when the
- * feature is still open and every child is closed.
+ * closeout child task (see the flow SKILL's closeout step), but if that task never
+ * closed the root — or no closeout task exists — the container would be orphaned
+ * open forever once filtered from claimable work. Applies to both container types
+ * the loop supports: a `feature` (feature-dev flow) or an `epic` (light-dev flow).
+ * Only close when the container is still open and every child is closed.
  */
 export declare function shouldCloseFeatureRoot(feature: {
     status: string;
@@ -201,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 {
@@ -355,19 +408,18 @@ ${workContent}
 ${flowContent}
 
 ## Instructions
-1. Read the work specification carefully
-2. Create a feature issue: \`bd create "<title>" -t feature -d "<description>"\`
-   - Derive the title from the work specification
-   - Include breadcrumbs in the description (links to the work file, relevant specs, skills, and code)
-3. Follow the workflow process to create child issues under this feature
-   (use \`--parent <feature-id>\` so they are children of the feature)
-4. Review all created issues: ensure each has breadcrumbs, then set
-   appropriate priorities and blocking deps between tasks
+1. Read the work specification carefully.
+2. Follow the Workflow Process above to set up the work. The Workflow Process
+   governs the stages, the container issue (its type and title), and the child
+   issues created under it — use \`--parent <container-id>\` so they are its children.
+3. The setup MUST produce a single container issue with its child issues, each
+   carrying breadcrumbs (links to the work file, relevant specs, skills, and code),
+   with appropriate priorities and blocking deps.
 
-When finished, output exactly one line:
-FEATURE_ID=<the-feature-issue-id>`;
+When finished, output exactly one line with the id of the container issue you created:
+FEATURE_ID=<the-container-issue-id>`;
     if (prefix) {
-        prompt += `\n\nNaming hint: Use \`${prefix}\` as a naming hint for the feature title.`;
+        prompt += `\n\nNaming hint: Use \`${prefix}\` as a naming hint for the container title.`;
     }
     return prompt;
 }
@@ -540,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`
@@ -604,15 +656,16 @@ function isClaimableReadyIssue(issue, hasChildren) {
     return true;
 }
 /**
- * Decide whether the loop should close a feature root itself, as a safety net,
+ * Decide whether the loop should close a container root itself, as a safety net,
  * when its workflow chain has completed. The intended owner of this close is the
- * closeout child task (see boop-feature-dev-workflow SKILL step 6), but if that
- * task never closed the root — or no closeout task exists — the feature would be
- * orphaned open forever once filtered from claimable work. Only close when the
- * feature is still open and every child is closed.
+ * closeout child task (see the flow SKILL's closeout step), but if that task never
+ * closed the root — or no closeout task exists — the container would be orphaned
+ * open forever once filtered from claimable work. Applies to both container types
+ * the loop supports: a `feature` (feature-dev flow) or an `epic` (light-dev flow).
+ * Only close when the container is still open and every child is closed.
  */
 function shouldCloseFeatureRoot(feature, children) {
-    if (!feature || feature.issue_type !== 'feature') {
+    if (!feature || (feature.issue_type !== 'feature' && feature.issue_type !== 'epic')) {
         return false;
     }
     if (feature.status === 'closed') {
@@ -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/init.md

@@ -0,0 +1,179 @@
+# boop init
+
+`boop init` is the command you run when you want a real starting point quickly. It creates a new project directory, applies a boop profile, writes a `.boop.json` manifest, and, unless you opt out, installs npm dependencies. The goal is simple: get you to a local project you can run, extend, and keep clean as both humans and agents start contributing.
+
+## Synopsis
+
+```bash
+boop init <name> --profile <profile>
+```
+
+If you omit `--profile`, Boop uses `web-app`.
+
+## Before You Run It
+
+The current `web-app` profile requires Node 24 or newer. If your Node version is too old, `boop init` exits before creating the directory and prints an upgrade hint.
+
+## Available Profiles
+
+List the profiles Boop knows about with:
+
+```bash
+boop list profiles
+```
+
+Current output:
+
+```text
+Available profiles:
+
+  web-app
+    Full-stack web application (Express + Handlebars + Tailwind + Postgres)
+    capabilities: web, api, database
+    runtime: node | deploy: heroku | port: 3000
+```
+
+Right now the built-in profile is `web-app`.
+
+## What It Creates
+
+Running `boop init my-saas --profile web-app --no-install` creates a project like this:
+
+```text
+my-saas/
+  .boop.json
+  .gitignore
+  Procfile
+  README.md
+  package.json
+  reference/
+    architecture.ref.md
+    message-queue-patterns.ref.md
+  skills/
+    boop-api-rest-api-design/
+      SKILL.md
+    boop-coding-beads-flow/
+      SKILL.md
+    boop-coding-commit-changes/
+      SKILL.md
+    boop-coding-development/
+      SKILL.md
+    boop-coding-review-changes/
+      SKILL.md
+    boop-database-data-model/
+      SKILL.md
+    boop-database-prisma/
+      SKILL.md
+    boop-product-design-engineering-design/
+      SKILL.md
+    boop-product-design-feature-documentation/
+      SKILL.md
+    boop-product-design-feature-requirements/
+      SKILL.md
+    boop-product-design-reference-integration/
+      SKILL.md
+    boop-project-mgmt-beads-planning/
+      SKILL.md
+    boop-project-mgmt-engineering-planning/
+      SKILL.md
+    boop-services-controllers/
+      SKILL.md
+    boop-services-services/
+      SKILL.md
+    boop-skill-authoring/
+      SKILL.md
+    boop-testing-tdd-light/
+      SKILL.md
+    boop-testing-testing/
+      SKILL.md
+    boop-testing-testing-express-web/
+      SKILL.md
+    boop-web-web-ui-design/
+      SKILL.md
+  src/
+    lib/
+      .gitkeep
+    server.ts
+  tsconfig.json
+```
+
+That scaffold breaks down into a few parts:
+
+- Kernel files: `.gitignore`, `Procfile`, `README.md`, `package.json`, `tsconfig.json`, `src/server.ts`, and `src/lib/.gitkeep`
+- Profile reference docs: copied into `reference/`
+- Profile and capability skills: copied into `skills/`
+- Project manifest: `.boop.json` records the project name, profile, boop version, installed capabilities, and creation timestamp
+- Capability install effects: default capability dependencies and scripts are merged into `package.json`, and the installed capability names are recorded in `.boop.json`
+
+For the `web-app` profile, the default capabilities are:
+
+- `web`
+- `api`
+- `database`
+
+At the moment, those capabilities show up most clearly in `package.json`, `skills/`, and `.boop.json`. The initial source tree is still small: the kernel server entry point plus the copied reference and skill material.
+
+Beyond the defaults, optional capabilities are available to add later with `boop add <capability>`. For example, `users-and-accounts` adds user management and authentication, and `noticeboard` provides a fuller service-layer reference demo. See the profile documentation for the complete list.
+
+## Options
+
+- `--profile <profile>`: choose which profile to initialize. Defaults to `web-app`.
+- `--no-install`: skip `npm install`. This is useful if you want to inspect or adjust the scaffold before installing dependencies.
+
+If you do not pass `--no-install`, Boop runs `npm install` after scaffolding and then prints the same next-step summary.
+
+## Example: Initialize Without Installing
+
+```bash
+boop init my-saas --profile web-app --no-install
+```
+
+Expected output:
+
+```text
+Created project "my-saas" with profile "web-app"
+
+Kernel files:
+  .gitignore
+  Procfile
+  README.md
+  package.json
+  src/lib/.gitkeep
+  src/server.ts
+  tsconfig.json
+
+Capabilities: web, api, database
+
+Scripts added:
+  tailwind:build: npx @tailwindcss/cli -i src/public/css/input.css -o src/public/css/style.css --minify
+  tailwind:watch: npx @tailwindcss/cli -i src/public/css/input.css -o src/public/css/style.css --watch
+  db:migrate: prisma migrate dev --schema=prisma/schema/
+  db:deploy: prisma migrate deploy --schema=prisma/schema/
+  db:seed: prisma db seed --schema=prisma/schema/
+  db:generate: prisma generate --schema=prisma/schema/
+  db:studio: prisma studio --schema=prisma/schema/
+
+Next steps:
+  cd my-saas
+  npm install
+  npm run dev
+```
+
+## What To Do After Init
+
+If you used `--no-install`, run:
+
+```bash
+cd my-saas
+npm install
+npm run dev
+```
+
+If you let Boop install dependencies for you, the shorter version is:
+
+```bash
+cd my-saas
+npm run dev
+```
+
+That gets you to a local project quickly, with the reference material and agentic skills already in place so the next changes do not have to start from scratch.

package/docs/loop.md

@@ -0,0 +1,205 @@
+# boop loop
+
+`boop loop` continuously processes ready beads issues through Claude Code sessions. It finds issues matching a prefix, launches Claude to work each one, and resumes if the issue isn't closed — all with dry-run safety by default. By default each loop runs inside its own git worktree (see [Worktree Isolation](#worktree-isolation-default)) so several loops can run concurrently without colliding.
+
+It also supports a **planning mode** via `--work` and `--flow` flags, which bootstraps a feature issue tree from a spec file before looping through the created tasks.
+
+## Synopsis
+
+```bash
+# Process existing issues by prefix
+boop loop --prefix <prefix> [--run] [--max N] [--budget N.NN]
+
+# Plan-then-execute: create a feature tree from a spec, then process tasks
+boop loop --work <spec-file> --flow <workflow-file> [--run] [--prefix <hint>]
+```
+
+Without `--run`, the command shows what it would do without executing anything.
+
+## How It Works
+
+### Standard mode (`--prefix`)
+
+1. Queries `bd ready` for leaf tasks in `--prefix` scope. Scope is two-layer: an issue matches if its ID starts with the prefix string, **or** if any ancestor in its parent chain has an ID that does — so issues re-parented under a matching epic or feature are processed even when their own IDs are unrelated. To run a group of related issues that don't share a prefix, create an epic, `bd update <id> --parent <epic-id>` each one, and pass the epic's ID as `--prefix`. Always pass a complete issue ID: matching is raw `startsWith`, so a truncated prefix like `boop-4` also matches `boop-45j`. Epics themselves and feature issues that own children are never claimed as work.
+2. Picks the first ready issue and launches a Claude Code session
+3. When Claude exits, checks if the issue was closed
+4. If not closed, resumes the session with a continuation prompt (up to `--resume-limit` times)
+5. Moves to the next ready issue and repeats
+6. Exits when no more ready issues exist (or keeps polling with `--poll`)
+
+Each Claude session gets a full prompt with issue details and instructions to work autonomously through the complete workflow: claim, implement, test, commit, close, and push.
+
+### Planning mode (`--work` + `--flow`)
+
+When `--work` and `--flow` are provided, boop loop runs a **plan-then-execute pipeline**:
+
+1. **Planning phase** — Reads the spec file (`--work`) and workflow file (`--flow`), builds a planning prompt, and launches a Claude session that creates a feature issue with child tasks in beads.
+2. **Feature ID extraction** — Parses the planning session output for `FEATURE_ID=<id>`. If not found, falls back to querying `bd list` for recently created features matching the spec's title.
+3. **Loop phase** — Uses the extracted feature ID as the prefix and processes all child tasks through the standard loop, with `--features` automatically enabled.
+
+If `--prefix` is also provided, it is passed to the planning session as a naming hint for the feature title (e.g., `--prefix boop-abc` suggests the feature should use that prefix).
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--prefix <prefix>` | — | Issue ID prefix to filter. Required unless `--work`/`--flow` are used |
+| `--work <path>` | — | Spec file for planning phase. Must be used with `--flow` |
+| `--flow <path>` | — | Workflow file for planning phase. Must be used with `--work` |
+| `--run` | off | Actually execute. Without this flag, dry-run mode shows what would happen |
+| `--max <n>` | unlimited | Stop after processing N issues |
+| `--budget <amount>` | `5.00` | Budget cap in USD, applied to both planning and per-issue phases |
+| `--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-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 |
+| `--json` | off | Output summary as JSON |
+
+## Worktree Isolation (default)
+
+By default, `boop loop` runs **inside its own git worktree** so that N loops can run concurrently without colliding. On start (with `--run`) the loop:
+
+1. Creates a worktree at `../boop-<scope>` on a new branch `work/<scope>`, where `<scope>` is the feature ID (planning mode) or the `--prefix` value.
+2. Runs `npm install --prefer-offline` in the worktree to pre-warm dependencies (so the agent doesn't spend budget on a deterministic step).
+3. Writes `.boop-worktree.json` into the worktree root recording the beads scope, branch, and provenance (read by future integration tooling).
+4. Runs the whole loop — every Claude session, commit, and `git push` — with its working directory set to the worktree.
+
+**Your main working tree is never checked out or mutated by the loop.** When the loop finishes it **leaves the worktree and branch in place** for integration. Use `boop loop --merge` (see [Merging completed work](#merging-completed-work-boop-loop---merge)) for automated, test-gated integration, or merge by hand:
+
+```bash
+git -C <main-repo> merge work/<scope>     # or open a PR from the branch
+git worktree remove ../boop-<scope>       # clean up when done
+```
+
+If you re-run a loop for the same scope, an existing worktree on the matching `work/<scope>` branch is reused; a path occupied by something else is reported as an error rather than silently renamed.
+
+### Dolt server-mode requirement
+
+Concurrent worktrees share **one** beads issue database over a TCP Dolt server. The loop therefore requires beads to be in **Dolt server mode**:
+
+- It reads `.beads/metadata.json` and refuses to start unless `dolt_mode` is `"server"`, pointing you to `skills/boop-dolt-recovery` otherwise.
+- It discovers the running server's port from `.beads/dolt-server.port` (it never starts a server itself) and copies the `dolt-server.port`/`dolt-server.pid` discovery files into the new worktree's `.beads/` so `bd` inside the worktree connects to the shared server instead of auto-starting a rogue one.
+
+Start the shared server with `bd dolt start` before running the loop.
+
+### Branching alternatives
+
+- **`--no-branch`** — Opts out of worktree isolation entirely and runs **in-place on the current branch** (the original single-tenant behavior). Use this when you've already set up the branch/tree you want and are running only one loop.
+- **`--per-issue-branch`** — Creates a separate `fix/<issue-id>` branch for each issue. Under worktree isolation these branches are created **inside** the loop's worktree (nested under `work/<scope>`), keeping main untouched. Combine with `--no-branch` to get the old in-place per-issue behavior.
+
+## Merging completed work (`boop loop --merge`)
+
+Once feature loops finish, `boop loop --merge` integrates their branches back into `main` sequentially. No individual loop merges its own branch — this dedicated integrator does it, so failures in one feature never block others.
+
+```bash
+boop loop --merge            # dry-run: list branches ready to merge
+boop loop --merge --run      # integrate every ready branch
+boop loop --merge work/<scope> --run   # merge one named branch, skipping the readiness check
+boop loop --merge --run --watch        # poll and merge branches as they become ready
+```
+
+For each ready branch (one at a time, with `main` as the integration branch):
+
+1. **Readiness** — a branch is ready when every beads issue in its scope is closed (scope is read from the worktree's `.boop-worktree.json`). `bd ready` is insufficient here — it only lists *unblocked* issues — so `--merge` lists by status and filters by scope. An explicit `boop loop --merge work/<scope>` skips this check.
+2. **Rebase onto main** inside the worktree. Only **`package.json` dependency conflicts** are auto-resolved (union of dependencies; same-key version conflicts take the higher semver). Any other conflict aborts the rebase, files a beads bug, and skips to the next branch.
+3. **Run `npm test`** in the worktree. On failure the branch is reset to its pre-rebase commit, a beads bug is filed, and the branch is skipped.
+4. **Fast-forward merge** into `main`, then remove the worktree and delete the merged branch.
+
+**Safety contract:** `main` is never left dirty. The integration tree must be on a clean `main` before merging; a rebase conflict aborts cleanly, and a post-rebase test failure resets the feature branch. Every merge runs the test suite before completing, so no merge lands untested.
+
+## Logs
+
+Session logs are written to `labs/claude-runs/` in the project directory. Each issue produces a log file named `<issue-id>_<timestamp>.log` containing the full Claude stream-json output.
+
+## Safety
+
+- **Dry-run by default** — nothing executes without `--run`
+- **Budget caps** — each issue is capped at `--budget` USD
+- **Resume limits** — prevents infinite retry loops (default: 3 attempts)
+- **Permission skipping** — enabled by default for unattended operation; use `--no-skip-perms` to require approval for each tool call
+
+## Planning Mode
+
+### Dry-run
+
+Without `--run`, planning mode shows the prompt that would be sent to Claude and exits:
+
+```bash
+boop loop --work specs/foo.spec.md --flow skills/bar.skill.md
+```
+
+Output:
+```
+[bd-loop] PLANNING MODE (dry-run)
+[bd-loop]   Work file: specs/foo.spec.md
+[bd-loop]   Flow file: skills/bar.skill.md
+[bd-loop]   Planning prompt that would be sent:
+---
+<planning prompt content>
+---
+[bd-loop] After planning, loop would process tasks under the created feature.
+```
+
+### Full run
+
+```bash
+boop loop --work specs/foo.spec.md --flow skills/bar.skill.md --run
+```
+
+This launches a Claude session to create the feature tree, extracts the feature ID, then loops through all child tasks.
+
+### Using `--prefix` as a naming hint
+
+```bash
+boop loop --work specs/foo.spec.md --flow skills/bar.skill.md --prefix boop-foo --run
+```
+
+The prefix is included in the planning prompt as a suggestion for naming the feature. After planning, the prefix is overridden with the actual feature ID for the loop phase.
+
+### Error handling
+
+- **Missing files** — If the `--work` or `--flow` file doesn't exist, the command exits with an error before launching any session.
+- **Flags used separately** — `--work` without `--flow` (or vice versa) prints an error. They must be used together.
+- **Feature ID not found** — If the planning session doesn't output `FEATURE_ID=<id>` and the fallback query finds no matching recent feature, the command exits with an error and points to the session log for debugging.
+- **Planning session limit hit** — If the Claude session hits a usage limit, the command exits without proceeding to the loop phase.
+
+Planning session logs are written to `labs/claude-runs/` with the prefix `_planning_`.
+
+### Budget and planning
+
+The `--budget` value is a **per-session cap**, applied identically to the planning phase and to each task in the loop phase. A complex spec can consume a large portion of the budget during planning, leaving the same cap for each task — but if tasks are simpler than the plan, this is usually fine since each task gets its own independent budget allowance.
+
+However, be aware:
+- A spec that requires extensive decomposition (many tasks, deep dependency trees) may use most of the budget during planning.
+- If the planning session hits the budget limit, it exits without creating the full task tree and the loop phase does not start.
+- At runtime, boop loop warns if the planning phase consumes more than 50% of the budget.
+
+To mitigate, increase `--budget` when using complex specs, or break large specs into smaller ones.
+
+### Interaction with other flags
+
+- **`--budget`** — The same budget value is used for both the planning phase and each task in the loop phase.
+- **`--features`** — Automatically enabled after planning, so the feature issue itself is included in the loop queue.
+- **`--model`**, **`--no-skip-perms`** — Applied to both planning and task sessions.
+- **`--poll`**, **`--max`**, **`--resume-limit`** — Apply only to the loop phase (not planning).
+
+## Workflow Integration
+
+`boop loop` works with the beads issue tracker. Typical workflows:
+
+### Manual issue setup
+1. Plan work with `bd create` and set up dependencies
+2. Run `boop loop --prefix <prefix>` to preview the queue
+3. Run `boop loop --prefix <prefix> --run` to execute
+4. After completion, integrate with `boop loop --merge --run` (or review the `work/<prefix>` branch in the `../boop-<prefix>` worktree and merge it by hand)
+
+### Automated planning
+1. Write a spec in `specs/` and choose a workflow skill from `skills/`
+2. Preview: `boop loop --work specs/my-feature.spec.md --flow skills/dev-workflow.skill.md`
+3. Execute: `boop loop --work specs/my-feature.spec.md --flow skills/dev-workflow.skill.md --run`
+4. The planning phase creates the feature tree, then the loop processes each task

package/docs/skills.md

@@ -0,0 +1,88 @@
+# boop skills index
+
+> Generated by `tools/generate-skills-index.js` (`npm run skills:index`). Do not edit by hand.
+
+Every capability ships **agent skills** — focused `SKILL.md` guides that `boop add` installs into your project's `skills/` directory. This index lists them by capability so you can see what guidance each one brings before installing it.
+
+## Development capabilities (skills only — no runtime code)
+
+### `coding` — Development tools and conventions
+
+- **boop-coding-beads-flow** — When you need to work through the beads issue lifecycle from claiming work to pushing final code.
+- **boop-coding-development** — When you need to build features or implement changes, follow these core development principles and workflows.
+- **boop-coding-commit-changes** — When you need to commit code changes, use **Conventional Commits** to write clear, machine-readable commit messages that communicate the nature of each change.
+- **boop-coding-review-changes** — When you need to review uncommitted code changes, use this skill to perform a judgment-level code review using git diffs.
+- **boop-coding-debugging** — When you need to diagnose a bug, crash, or failing test, debug from the data and the observation — not from the first familiar mechanism.
+
+### `product-design` — Product design skills
+
+- **boop-product-design-engineering-design** — When you need to design a feature or system and communicate the technical decisions — including when you frame the task as writing a design doc, drafting the technical or engineering section of a spec, deciding the architecture, or choosing how to build something. Reaching for an existing design to imitate its structure is not a substitute for the method. For UI features, includes a per-affordance interaction-shapes pass that derives page/surface count from job-anchored mechanism choices rather than asserting it up front.
+- **boop-product-design-feature-documentation** — When you need to document a complex feature, function, or system — including when you frame the task as 'write the docs', 'write a README', 'write up how X works', or 'explain this for the next reader who picks it up cold'.
+- **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, 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.
+
+### `project-mgmt` — Project management with beads
+
+- **boop-project-mgmt-beads-planning** — When you need to write and organize beads issues so that any fresh agent can pick up work.
+- **boop-project-mgmt-engineering-planning** — When you need to decompose a design into an executable plan of work — including when you frame the task as 'make a plan', 'break this into tasks or steps', 'figure out the order of work', or planning a build before you start writing issues. Order the work by uncertainty reduction, not just demonstrable value.
+
+### `skills` — Skill authoring
+
+- **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.
+
+### `testing` — Jest testing setup
+
+- **boop-testing-tdd-light** — When you need to build features, implement changes, or fix bugs, follow the Light TDD Flow. This includes bug fixes found during UAT — write the failing test *before* applying the fix.
+- **boop-testing-testing-express-web** — When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes.
+- **boop-testing-testing** — When you need to write, run, or reason about tests in this project.
+
+### `ux` — UX design judgement and the discovery/delivery workflows that operate it
+
+- **boop-ux-purpose-judgement** — When you are evaluating a rendered page and need to judge whether each thing on it belongs there, in the right shape, for the right job. Asks the structural question that the visual lens does not — is this affordance the right idea, not just rendered well. Pairs with ux-visual-judgement (the question of how things look and scan).
+- **boop-ux-visual-judgement** — When you are evaluating a rendered page and need to form a principled judgement about how it looks and scans. Visual lens only — eye-path, register, anatomy, scan-line, gestalt, density, voice. Pairs with ux-purpose-judgement (the question of whether each element belongs at all) and with the CSS skill (the grammar of how things are rendered).
+- **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.
+
+## Application capabilities
+
+### `api` — REST API with Express
+
+- **boop-api-rest-api-design** — When you need to design or implement REST-style HTTP APIs — including when you frame the task as 'add an endpoint', 'add a route', 'build the API', or 'decide the request and response shape' — follow these principles.
+
+### `background-jobs` — Background job processing with RabbitMQ via CloudAMQP
+
+- **boop-background-jobs-background-jobs-design** — When you need to add a background job consumer, publish messages, or work with the message queue infrastructure, follow these principles.
+
+### `cloud-storage` — Cloud storage service for files and assets (AWS S3)
+
+- **boop-cloud-storage-cloud-storage** — When you need to work with cloud storage for files and assets in a boop project (using AWS S3).
+
+### `database` — Postgres via Prisma ORM
+
+- **boop-database-prisma** — When you need to design, modify, or migrate the app database schema.
+- **boop-database-data-model** — When you need to design data models for new features or extend existing entities.
+
+### `email` — Transactional email via Sendgrid with Handlebars templates
+
+- **boop-email-email-design** — When you need to design, implement, or work with transactional email, follow these guidelines.
+
+### `services` — Service layer with controllers and business logic
+
+- **boop-services-controllers** — When you need to design, implement, or review a controller, follow these principles.
+- **boop-services-services** — When you need to design, implement, or review a service, follow these principles.
+
+### `users-and-accounts` — Users, identities, properties, and authentication via Prisma
+
+- **boop-users-user-data-modeling** — When you need to add, store, or query a field related to users, identities, or accounts in a boop project, decide *where* the field belongs before writing the schema or service.
+
+### `web` — Web UI with Handlebars + Tailwind
+
+- **boop-web-web-ui-design** — When you need to design and implement user interfaces — including when you frame the task as 'build a page', 'add a component', 'style this surface', or 'wire up the UI' — following established patterns and philosophy.
+
+---
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.0",
+  "version": "0.6.7",
   "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": [
@@ -11,6 +11,9 @@
   },
   "files": [
     "dist/",
+    "docs/init.md",
+    "docs/loop.md",
+    "docs/skills.md",
     "profiles/",
     "src/templates/"
   ],
@@ -19,6 +22,7 @@
   },
   "scripts": {
     "build": "tsc && node tools/generate-version-manifest.js",
+    "skills:index": "node tools/generate-skills-index.js",
     "build:caps": "./tools/build-caps.sh",
     "publish": "./tools/publish-caps.sh",
     "release": "./tools/publish-caps.sh --release",