@boopkit/cli 0.6.0 → 0.6.1

package/README.md

@@ -102,8 +102,11 @@ 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 |
+
+> 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).
 
 ### Demo
 
@@ -138,11 +141,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.
 
@@ -175,12 +178,13 @@ Boop itself is light — Node and npm. The other requirements come from whicheve
 - **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.1",
   "@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-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.3",
+  "@boopkit/cap-project-mgmt": "0.4.3",
   "@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.1",
+  "@boopkit/cap-web": "0.5.1",
   "@boopkit/logger": "0.4.0"
 }

package/dist/commands/loop.d.ts

@@ -168,12 +168,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;

package/dist/commands/loop.js

@@ -355,19 +355,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;
 }
@@ -604,15 +603,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') {

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,204 @@
+# 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-4-6` | Claude model to use |
+| `--per-issue-branch` | off | Create a `fix/<issue-id>` branch per issue (nested inside the worktree) |
+| `--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, 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.
+
+### `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.1",
   "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",