@boopkit/cli 0.1.16 → 0.3.1

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.6",
-  "@boopkit/cap-cloud-storage": "0.1.0",
-  "@boopkit/cap-coding": "0.1.0",
-  "@boopkit/cap-database": "0.1.4",
-  "@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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.1.16",
-  "description": "CLI tool to scaffold new projects from boop profiles and capabilities",
+  "version": "0.3.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": [
     "packages/*"
@@ -21,6 +21,7 @@
     "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"