@boopkit/cli 0.1.15 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # boop
 
-CLI tool to scaffold new projects from reusable profiles and capabilities. Get a running web app with proven architecture, conventions, and AI agent skills — in one command.
+Boop is a bootstrap platform for AI-first builders — founders, small teams, and anyone chasing product-market fit without sliding into a vibe-coded swamp. One command gives you a running project with the capabilities you pick: web server, APIs, database, and the design and coding skills your agents need to keep the code clean as it grows. Code plus expertise, already in the box.
 
 ## Install
 
@@ -8,78 +8,180 @@ CLI tool to scaffold new projects from reusable profiles and capabilities. Get a
 npm install -g @boopkit/cli@beta
 ```
 
-Or use directly:
+Or run directly with `npx`:
 
 ```bash
-npx @boopkit/cli@beta init myapp
+npx @boopkit/cli@beta init my-app
 ```
 
 ## Quick Start
 
-```bash
-# go to your projects directory
-cd ~/projects
-
-# install the boop CLI globally 
-npm install -g @boopkit/cli@beta
+Six commands from nothing to a running local app with agent-ready skills already in place.
 
-# scaffold a new app from the default profile (web-app)
+```bash
+# Scaffold a new project from the default profile (web-app)
 boop init my-app
 cd my-app
-boop status # have your agent follow instructions to finish setup
+```
 
-# start your web server
-npm run dev 
+`boop init` creates the project directory, applies the `web-app` profile, installs capability packages from npm, and scaffolds files into your project — including a `.boop.json` manifest that records what profile and capabilities are installed.
 
-# stop the server...
+```bash
+# See what was installed, what's configured, and what to do next
+boop status
+```
 
-# see available capabilities to add new features
-npm caps 
+`boop status` prints post-install instructions from every capability — environment variables to set, services to start, migrations to run. Hand it to your AI agent as a checklist.
 
-# add user authentication and account management features
-# have your agent follow instructions to finish setup
-boop add users-and-accounts 
+```bash
+# Start the dev server
+npm run dev
+```
 
+You now have an Express + Handlebars + Tailwind app running on port 3000, backed by PostgreSQL via Prisma.
+
+```bash
+# Browse available capabilities and add one
+boop caps
+boop add users-and-accounts
 ```
 
+`boop add` resolves transitive dependencies, installs packages, merges scaffold files, wires middleware hooks into your server, and installs agent skills — all declaratively driven by each capability's `capability.json`.
+
+## The Capability Model
+
+Start simple, grow deliberately. That's the shape of a boop project: a strong starting point you can extend without collecting scaffolding debt.
+
+A **profile** is a named starting point. It defines the kernel (TypeScript config, `package.json`, `src/server.ts`, deployment setup) and a set of default capabilities.
+
+A **capability** is a composable feature bundle. Each capability package ships:
+
+- **Scaffold files** — code, configs, templates copied into your project
+- **npm dependencies** — merged into your `package.json`
+- **Middleware hooks** — lines wired into `src/server.ts` at the right phase (imports, pre-routes, routes, error-handling)
+- **Scripts** — added to `package.json` (e.g. `db:migrate`, `tailwind:build`)
+- **Post-install steps** — human/agent-readable instructions printed by `boop status`
+- **Agent skills** — `.skill.md` files that teach AI agents the conventions this capability uses
+
+Capabilities can declare `requires` relationships (e.g. `users-and-accounts` requires `database`, `services`, and `web`). `boop add` resolves the dependency graph and installs everything needed.
+
+## Profiles
+
+A profile is where a project starts. Today there's one; more will follow as the common shapes of AI-first products become clearer.
+
+### `web-app`
+
+Full-stack web application — Express + Handlebars + Tailwind CSS + PostgreSQL via Prisma, deployable to Heroku.
+
+Ships with application capabilities (`web`, `api`, `services`, `database`), development skills (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`), and the `hello` demo capability.
+
+List profiles with `boop list profiles`.
+
+## Available Capabilities
+
+Pick what the product needs. `boop add <name>` handles the wiring — npm dependencies, scaffold files, middleware hooks, and the agent skills that go with the feature.
+
+### Application
+
+| Name | What it adds | Requires |
+|------|--------------|----------|
+| `web` | Handlebars view engine, Tailwind CSS, static asset serving, request logging | — |
+| `api` | Express API middleware — error handling, request ID, 404 handler, health checks | — |
+| `services` | Service-layer pattern — controllers, auto-discovered `*.service.ts` files, factory-based data access | — |
+| `database` | PostgreSQL via Prisma — schema, migrations, transaction helper, health check | — |
+| `users-and-accounts` | User accounts, identities, properties, and session-based authentication | `database`, `services`, `web` |
+| `email` | Transactional email via SendGrid with Handlebars templates | `services` |
+| `background-jobs` | Background job processing with RabbitMQ (CloudAMQP) | `services` |
+| `cloud-storage` | File and asset storage via AWS S3 | `services` |
+| `noticeboard` | Reference demo feature showing the full service-layer pattern end-to-end | — |
+
+### Development (skills-only — no runtime code)
+
+| Name | What it adds |
+|------|--------------|
+| `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 |
+
+### Demo
+
+| Name | What it adds |
+|------|--------------|
+| `hello` | Minimal capability used to validate the install pipeline |
+
 ## Commands
 
+Most days you'll use `init`, `add`, and `status`. The rest are there when you need them.
+
 | Command | Description |
 |---------|-------------|
+| `boop init <name>` | Create a new project from a profile (default: `web-app`) |
 | `boop list profiles` | List available profiles |
-| `boop init <name>` | Create a new project from a profile (default profile is `web-app`) |
-| `boop status` | Show current project status |
-| `boop caps` | List available capabilities (alias for `boop list capabilities`) |
-| `boop add <capability>` | Add a capability to an existing project |
+| `boop list capabilities` | List available capabilities |
+| `boop caps` | Shortcut for `list capabilities` |
+| `boop status` | Show installed capabilities and pending post-install steps |
+| `boop add <capability>` | Install a capability into an existing project |
+| `boop update [capability]` | Re-scaffold files from installed capability packages |
+| `boop adopt <capability>` | Copy a capability's source into your project for full ownership |
+| `boop loop` | (Advanced) A hands-off spec-to-code workflow. Continuously process ready beads issues through Claude Code sessions. |
 
-## What You Get
+Flags:
 
-`boop init` scaffolds a full-stack web application with:
+- `boop init --no-install` / `boop add --no-install` — skip `npm install`
+- `boop add --dry-run` — preview changes without writing
+- `boop update --force` — overwrite locally modified scaffold files (creates `.bak` backups)
+- `boop update --prune` — remove scaffold files no longer shipped by the capability
 
-- **Express** server with Handlebars views and Tailwind CSS
-- **REST API** with controllers, routes, and middleware
-- **TypeScript** with strict mode and path aliases
-- **Jest** testing setup with TDD workflow
-- **Multi-process architecture** (web, worker, scheduler)
-- **Heroku deployment** via Procfile
-- **AI agent skills** for development, testing, design, and project management
+## Working with AI Agents
 
-Capabilities are additive. Start simple, add complexity when you need it:
+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:
 
-```bash
-boop add users-and-accounts # Adds user authentication and account management features
-boop add email # Adds email sending capabilities with templates 
-```
+- **Skills** — every capability installs `.skill.md` files into `skills/`. These are focused, task-specific instructions (e.g. `design.rest-api-design.skill.md`, `test.tdd-light.skill.md`) that tell an agent the conventions this project uses.
+- **`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).
+
+The workflow is designed so a human sets direction, an agent does the implementation, and boop provides the rails.
+
+## Post-Init: What to Do Next
+
+After `boop init`, `boop status` will list the specific steps for the capabilities you installed. Typical setup for a `web-app` project:
+
+1. **Set environment variables** — `.env` values for `DATABASE_URL`, and anything capabilities you added need (`SENDGRID_API_KEY`, `CLOUDAMQP_URL`, `AWS_ACCESS_KEY_ID`, etc.)
+2. **Start Postgres** — e.g. `brew services start postgresql` or a Docker container
+3. **Run migrations** — `npm run db:migrate`
+4. **Build CSS** — `npm run tailwind:build`
+5. **Start the dev server** — `npm run dev`
 
-## Development
+Add more capabilities as you need them:
 
 ```bash
-npm install
-npm run build
-npm run test
-npm run dev -- init test-project   # Run from source
+boop add email              # transactional email
+boop add background-jobs    # async job processing
+boop add cloud-storage      # S3 file uploads
 ```
 
+## Requirements
+
+Boop itself is light — Node and npm. The other requirements come from whichever capabilities you install, so you're not signing up for them until you opt in.
+
+- **Node.js 24+** (the `web-app` profile enforces this)
+- **npm** (or any package manager that respects workspaces)
+- **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
+
+- **[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
+
 ## License
 
-Private
+ISC

package/dist/capability-catalog.json

@@ -4,7 +4,9 @@
     "description": "REST API with Express",
     "type": "application",
     "package": "@boopkit/cap-api",
-    "requires": []
+    "requires": [
+      "web"
+    ]
   },
   {
     "name": "background-jobs",
@@ -59,7 +61,9 @@
     "description": "Notice board demo — data service, business service, handler set, and router factory",
     "type": "demo",
     "package": "@boopkit/cap-noticeboard",
-    "requires": []
+    "requires": [
+      "web"
+    ]
   },
   {
     "name": "product-design",

package/dist/capability-versions.json

@@ -1,18 +1,18 @@
 {
-  "@boopkit/cap-api": "0.1.0",
-  "@boopkit/cap-background-jobs": "0.2.0",
-  "@boopkit/cap-cloud-storage": "0.1.0",
-  "@boopkit/cap-coding": "0.1.0",
-  "@boopkit/cap-database": "0.1.3",
-  "@boopkit/cap-email": "0.1.0",
-  "@boopkit/cap-hello": "0.1.0",
-  "@boopkit/cap-noticeboard": "0.1.1",
-  "@boopkit/cap-product-design": "0.1.0",
-  "@boopkit/cap-project-mgmt": "0.1.0",
-  "@boopkit/cap-services": "0.1.0",
-  "@boopkit/cap-skills": "0.1.0",
-  "@boopkit/cap-testing": "0.1.0",
-  "@boopkit/cap-users": "0.1.0",
-  "@boopkit/cap-web": "0.1.1",
-  "@boopkit/logger": "0.1.0"
+  "@boopkit/cap-api": "0.3.0",
+  "@boopkit/cap-background-jobs": "0.3.0",
+  "@boopkit/cap-cloud-storage": "0.3.0",
+  "@boopkit/cap-coding": "0.3.0",
+  "@boopkit/cap-database": "0.3.0",
+  "@boopkit/cap-email": "0.3.0",
+  "@boopkit/cap-hello": "0.3.0",
+  "@boopkit/cap-noticeboard": "0.3.0",
+  "@boopkit/cap-product-design": "0.3.0",
+  "@boopkit/cap-project-mgmt": "0.3.0",
+  "@boopkit/cap-services": "0.3.0",
+  "@boopkit/cap-skills": "0.3.0",
+  "@boopkit/cap-testing": "0.3.0",
+  "@boopkit/cap-users": "0.3.0",
+  "@boopkit/cap-web": "0.3.0",
+  "@boopkit/logger": "0.3.0"
 }

package/dist/commands/list.js

@@ -61,7 +61,7 @@ function listProfilesCommand() {
  * Reused by both `boop list capabilities` and `boop add` (no arg).
  */
 function printGroupedCapabilities() {
-    const capabilities = (0, capability_1.listCapabilities)().filter(c => !c.name.startsWith('_'));
+    const capabilities = (0, capability_1.listCapabilities)();
     if (capabilities.length === 0) {
         console.log('No capabilities found.');
         return;

package/dist/lib/capability.d.ts

@@ -16,7 +16,9 @@ export declare function getCatalogEntry(name: string): (CapabilityMetadata & {
  * List all capabilities by scanning package directory and capabilities/ source tree (test fixtures only).
  * Package resolution takes priority. Returns metadata for each valid capability.
  */
-export declare function listCapabilities(): CapabilityMetadata[];
+export declare function listCapabilities(opts?: {
+    includeTest?: boolean;
+}): CapabilityMetadata[];
 /**
  * Get a single capability's metadata by name.
  * Tries package resolution first, falls back to source tree.

package/dist/lib/capability.js

@@ -140,13 +140,14 @@ function getCatalogEntry(name) {
  * List all capabilities by scanning package directory and capabilities/ source tree (test fixtures only).
  * Package resolution takes priority. Returns metadata for each valid capability.
  */
-function listCapabilities() {
+function listCapabilities(opts) {
+    const includeTest = opts?.includeTest ?? false;
     const seen = new Set();
     const capabilities = [];
     // Primary source: baked-in catalog (always available in published CLI)
     const catalog = loadCatalog();
     for (const cap of catalog) {
-        if (cap.name.startsWith('_'))
+        if (!includeTest && cap.name.startsWith('_'))
             continue;
         seen.add(cap.name);
         // Also track the package short name (e.g. "users" from "@boopkit/cap-users")
@@ -174,6 +175,8 @@ function listCapabilities() {
             if ((!entry.isDirectory() && !entry.isSymbolicLink()) || !entry.name.startsWith('cap-'))
                 continue;
             const capName = entry.name.replace(/^cap-/, '');
+            if (!includeTest && capName.startsWith('_'))
+                continue;
             if (seen.has(capName))
                 continue;
             const cap = getCapabilityFromPackage(capName, [process.cwd()]);
@@ -190,6 +193,8 @@ function listCapabilities() {
         for (const entry of entries) {
             if (!entry.isDirectory())
                 continue;
+            if (!includeTest && entry.name.startsWith('_'))
+                continue;
             if (seen.has(entry.name))
                 continue;
             const cap = getCapabilityFromSourceTree(entry.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.1.15",
+  "version": "0.3.0",
   "description": "CLI tool to scaffold new projects from boop profiles and capabilities",
   "main": "dist/cli.js",
   "workspaces": [
@@ -19,6 +19,9 @@
   },
   "scripts": {
     "build": "tsc && node tools/generate-version-manifest.js",
+    "build:caps": "./tools/build-caps.sh",
+    "publish" : "./tools/publish-caps.sh",
+    "release" : "./tools/publish-caps.sh --release",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "test": "jest"

package/src/templates/kernel/AGENTS.md.hbs

@@ -2,17 +2,17 @@
 
 This is a **boop**-managed project. Use boop commands — don't reinvent what boop already provides.
 
-## Getting Started
+## Conversational style
+When the user asks a question, it is for informational purpose and not a veiled request for action. Unless the user says a colloquially phrased command like "can you write a test for X" or "can you add a database", you should not take any action.  If the user wants you to do something, they will ask you to do it directly.
 
-1. Run `boop status` to see what needs configuration
-2. Follow the setup hints to configure your environment
-3. Run `npm run dev` to start the development server
+Don't confirm a hypothesis (or take action) without observation - logs, tests, and other data are your friends. If you don't have the information you need to answer a question, find it (eg. run db queries, look at logs, add more logging, etc.) or ask for it instead of guessing.
 
 ## How to work in this project
 
-1. **Check skills first.** Before coding, reviewing, testing, or designing, check [skills/index.md](skills/index.md) for a matching skill and follow its process. Do not rely on general knowledge when a project skill exists.
-2. **Use boop for capabilities.** To add features like database, auth, or other infrastructure, run `boop add <capability>` — don't install or wire things manually. Run `boop caps` to see what's available.
-3. **Check project status.** Run `boop status` to see what's configured and what needs attention.
+0. **Read the skills index now.** Open [skills/index.md](skills/index.md) before doing anything else in this session. You need to know what skills exist before you can apply rule 1.
+1. **Check skills first.** Before coding, reviewing, testing, designing, debugging, filing issues, or proposing any non-trivial change, check [skills/index.md](skills/index.md) for a matching skill and follow its process. Do not rely on general knowledge when a project skill exists.
+2. **Use boop for capabilities.** Run `boop caps` to see what's available. To add features like database, auth, or other services and infrastructure, run `boop add <capability>` — don't install or wire things manually.
+3. **Check project status.** If the system isn't working or new capabilities need to be added run `boop status` to see what's configured and what needs attention.
 4. **Run `boop --help`** for the full command list.
 
 ## Boop extension model