@boopkit/cli 0.6.12 → 0.6.13

package/dist/lib/scaffold.d.ts

@@ -1,9 +1,9 @@
 import { CapabilityHook } from './config';
 export interface TemplateVariables {
     projectName: string;
-    port: number;
-    scripts: Record<string, string>;
-    nodeVersion: string;
+    port?: number;
+    scripts?: Record<string, string>;
+    nodeVersion?: string;
     hookImports?: string;
     hookInit?: string;
     hookPreRoutes?: string;
@@ -21,11 +21,22 @@ export interface TemplateVariables {
  */
 export declare function renderTemplate(templateContent: string, variables: TemplateVariables): string;
 /**
- * Copy and render all kernel templates into a target directory.
- * Creates directories as needed. Does not overwrite existing files
- * unless overwrite is true.
+ * Resolve the template directory `boop init` renders for a profile.
+ *
+ * A profile that ships its own `profiles/<name>/templates/` folder gets that
+ * folder, which must be complete on its own — nothing is merged from the kernel.
+ * Every other profile falls back to `src/templates/kernel/`. The fallback is
+ * what keeps `web-app`, which ships no templates/ folder, scaffolding exactly
+ * what it always has.
+ */
+export declare function getTemplatesDir(profileName: string): string;
+export declare function profileHasTemplates(profileName: string): boolean;
+/**
+ * Copy and render every file in a templates directory (the kernel templates
+ * by default) into a target directory. Creates directories as needed. Does
+ * not overwrite existing files unless overwrite is true.
  */
-export declare function scaffoldKernel(targetDir: string, variables: TemplateVariables, overwrite?: boolean): string[];
+export declare function scaffoldKernel(targetDir: string, variables: TemplateVariables, overwrite?: boolean, templatesDir?: string): string[];
 /**
  * Compute SHA-256 hash of a file's content.
  */

package/dist/lib/scaffold.js

@@ -37,6 +37,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderTemplate = renderTemplate;
+exports.getTemplatesDir = getTemplatesDir;
+exports.profileHasTemplates = profileHasTemplates;
 exports.scaffoldKernel = scaffoldKernel;
 exports.hashFile = hashFile;
 exports.copyCapabilityFiles = copyCapabilityFiles;
@@ -68,19 +70,33 @@ function renderTemplate(templateContent, variables) {
     const compiled = handlebars_1.default.compile(templateContent, { noEscape: true });
     return compiled(variables);
 }
+function getKernelTemplatesDir() {
+    return path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'kernel');
+}
 /**
- * Get the path to the kernel templates directory.
+ * Resolve the template directory `boop init` renders for a profile.
+ *
+ * A profile that ships its own `profiles/<name>/templates/` folder gets that
+ * folder, which must be complete on its own — nothing is merged from the kernel.
+ * Every other profile falls back to `src/templates/kernel/`. The fallback is
+ * what keeps `web-app`, which ships no templates/ folder, scaffolding exactly
+ * what it always has.
  */
-function getTemplatesDir() {
-    return path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'kernel');
+function getTemplatesDir(profileName) {
+    return profileHasTemplates(profileName) ? getProfileTemplatesDir(profileName) : getKernelTemplatesDir();
+}
+function profileHasTemplates(profileName) {
+    return fs.existsSync(getProfileTemplatesDir(profileName));
+}
+function getProfileTemplatesDir(profileName) {
+    return path.join((0, config_1.getBoopRoot)(), 'profiles', profileName, 'templates');
 }
 /**
- * Copy and render all kernel templates into a target directory.
- * Creates directories as needed. Does not overwrite existing files
- * unless overwrite is true.
+ * Copy and render every file in a templates directory (the kernel templates
+ * by default) into a target directory. Creates directories as needed. Does
+ * not overwrite existing files unless overwrite is true.
  */
-function scaffoldKernel(targetDir, variables, overwrite = false) {
-    const templatesDir = getTemplatesDir();
+function scaffoldKernel(targetDir, variables, overwrite = false, templatesDir = getKernelTemplatesDir()) {
     const written = [];
     function processDir(srcDir, destDir) {
         if (!fs.existsSync(destDir)) {
@@ -101,12 +117,13 @@ function scaffoldKernel(targetDir, variables, overwrite = false) {
                 if (!overwrite && fs.existsSync(destPath)) {
                     continue;
                 }
-                const content = fs.readFileSync(srcPath, 'utf-8');
-                // Only render .hbs files through Handlebars
-                const rendered = entry.name.endsWith('.hbs')
-                    ? renderTemplate(content, variables)
-                    : content;
-                fs.writeFileSync(destPath, rendered, 'utf-8');
+                // Only .hbs files are text by contract; anything else may be binary, so copy its bytes untouched
+                if (entry.name.endsWith('.hbs')) {
+                    fs.writeFileSync(destPath, renderTemplate(fs.readFileSync(srcPath, 'utf-8'), variables), 'utf-8');
+                }
+                else {
+                    fs.copyFileSync(srcPath, destPath);
+                }
                 written.push(path.relative(targetDir, destPath));
             }
         }

package/docs/init.md

@@ -1,6 +1,8 @@
 # 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.
+`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/config.json` manifest, and, unless you opt out, installs npm dependencies and sets up the project's beads issue tracker.
+The goal is simple: get you to a local project you can work in, extend, and keep clean as both humans and agents start contributing.
 
 ## Synopsis
 
@@ -10,9 +12,15 @@ boop init <name> --profile <profile>
 
 If you omit `--profile`, Boop uses `web-app`.
 
+`<name>` can be a plain name or a path such as `~/work/aws-setup`.
+Either way, the project is named after its folder, `aws-setup` in that example:
+that is the name in `package.json`, `.boop/config.json` and the README heading, and the beads issue prefix.
+
 ## 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.
+The `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.
+The `base` profile names no runtime, so it has no version to check.
 
 ## Available Profiles
 
@@ -27,110 +35,154 @@ Current output:
 ```text
 Available profiles:
 
+  base
+    Planning, writing and issue tracking for a project that isn't an application
+    capabilities:
+      Development: project-mgmt, product-design, skills
+
+  development
+    Development skills only — for a project with no application domain (a CLI, a library, a data pipeline)
+    capabilities:
+      Development: coding, testing, project-mgmt, product-design, skills, workflows
+
   web-app
-    Full-stack web application (Express + Handlebars + Tailwind + Postgres)
-    capabilities: web, api, database
+    Full-stack web application (Express + Handlebars + Tailwind)
     runtime: node | deploy: heroku | port: 3000
+    capabilities:
+      Application: web, api, services, database
+      Development: coding, testing, project-mgmt, product-design, skills, workflows
+      Demo: hello
 ```
 
-`web-app` is the only profile `boop init` can scaffold from.
-The other built-in profile, `development`, carries development capabilities and no application domain,
-so it has no runtime, port or deploy target to scaffold with —
-`boop init --profile development` is refused with a pointer to the two ways it is meant to be used:
+`boop init` can scaffold from two of these.
+`web-app` carries a kernel, the configuration for a running application, and renders an Express server from it.
+`base` has no kernel, but it ships templates of its own,
+so it renders a project for planning, writing and tracking work instead:
+agent instructions, a README in each of `specs/`, `reference/` and `docs/`,
+and the planning and writing skills, with no application code at all.
+
+The third profile, `development`, carries development capabilities and no application domain.
+It has neither a kernel nor templates, so there is nothing for `boop init` to write,
+and `boop init --profile development` is refused with a pointer to the two ways it is meant to be used:
 naming it as the `profile` in an existing project's `.boop/config.json`,
 or `boop add` for the capabilities you want.
 
 ## What It Creates
 
-Running `boop init my-saas --profile web-app --no-install` creates a project like this:
+Running `boop init my-saas --profile web-app --no-install --no-beads` creates a project like this, shown to two levels:
 
 ```text
 my-saas/
-  .boop.json
+  .boop/
+    config.json
+  .env
+  .env.example
+  .github/
+    copilot-instructions.md
   .gitignore
+  AGENTS.md
+  CLAUDE.md
   Procfile
   README.md
+  jest.config.js
   package.json
+  prisma/
+    schema/
+  public/
+    css/
+    favicon.svg
   reference/
-    architecture.ref.md
-    message-queue-patterns.ref.md
+    (architecture, database, REST API, service layer and web UI pages, among others)
   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
+    (40 skill folders from the installed capabilities)
+  specs/
+    README.md
   src/
+    app.ts
+    controllers/
+    db.ts
     lib/
-      .gitkeep
+    middleware/
+    routes/
+    scripts/
     server.ts
+    services/
+  styles/
+  tailwind.config.ts
+  tests/
   tsconfig.json
+  tsconfig.test.json
+  views/
 ```
 
 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`
+- Kernel files, rendered from boop's kernel templates: `.github/copilot-instructions.md`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `Procfile`, `README.md`, `package.json`, `tsconfig.json`, `src/app.ts`, `src/server.ts`, `src/lib/.gitkeep`, `specs/README.md` and `reference/boop-guide.ref.md`
 - 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`
+- Capability files: each capability's skills are copied into `skills/`, and its scaffold files (`src/`, `views/`, `styles/`, `prisma/`, `tests/` and so on) into the project
+- Project manifest: `.boop/config.json` records the project name, profile, boop version, installed capabilities, the hashes of the files each capability wrote, and the creation timestamp
+- Capability install effects: default capability dependencies and scripts are merged into `package.json`, and any environment variables a capability needs are written to `.env` and `.env.example`
 
 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.
+- Application: `web`, `api`, `services`, `database`
+- Development: `coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`
+- Demo: `hello`
 
 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.
 
+The `base` profile makes a much smaller project.
+Running `boop init notes --profile base --no-install --no-beads` creates this:
+
+```text
+notes/
+  .boop/
+    config.json
+  .github/
+    copilot-instructions.md
+  .gitignore
+  AGENTS.md
+  CLAUDE.md
+  README.md
+  docs/
+    README.md
+  package.json
+  reference/
+    README.md
+  skills/
+    (16 skill folders from project-mgmt, product-design and skills)
+  specs/
+    README.md
+```
+
+There is no `src/`, no test setup and no server to start.
+The `package.json` holds only the capability packages, the `bd` dependency and two `bd:` scripts;
+it is there because it is how boop records the capabilities and refreshes their skills with `boop update`.
+Without `--no-beads`, the project also has a `.beads/` folder and a git repository with two commits, as described under `--no-beads` below.
+
 ## 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.
+- `--no-beads`: skip the beads setup.
+  By default, when the profile installs `project-mgmt` (as `web-app` and `base` both do), Boop's last step is `bd init --non-interactive --server -p <name>`,
+  where the issue prefix is the project folder's name even when you pass a path such as `~/work/aws-setup`.
+  That creates the project's beads issue database in Dolt server mode and starts its Dolt server,
+  so `bd create` works straight away and `boop loop` can run in the project without first migrating it to server mode.
+  Pass `--no-beads` for a throwaway scaffold or a CI run; the command is printed under "Next steps" so you can run it later.
+  If `bd` is not installed, or `bd init` fails, init still succeeds and prints the same command.
+
+  Just before `bd init`, Boop creates a git repository in the new project and commits the scaffold, so the project starts with two commits (the scaffold, then beads) and a clean `git status`.
+  With `--no-beads`, Boop leaves git alone.
+  If git has no `user.name` and `user.email` configured, Boop skips its commit and tells you; it never sets an identity for you.
+  If the new project is inside another git repository, Boop skips both the commit and `bd init` and tells you why, because `bd init` would commit into that repository and redirect its git hooks.
 
 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
+## Example: Initialize Without Installing or Setting Up Beads
 
 ```bash
-boop init my-saas --profile web-app --no-install
+boop init my-saas --profile web-app --no-install --no-beads
 ```
 
 Expected output:
@@ -138,43 +190,37 @@ 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/
+  13 kernel files · 11 capabilities · 68 capability files · 13 scripts
+    Application: web, api, services, database
+    Development: coding, testing, project-mgmt, product-design, skills, workflows
+    Demo: hello
 
 Next steps:
   cd my-saas
   npm install
-  npm run dev
+  bd init --non-interactive --server -p my-saas
+  boop status          ← check what needs configuration
+  npm run dev          ← start development server
 ```
 
+The counts change as capabilities grow.
+A `base` project's summary counts template files rather than kernel files,
+and its next steps stop at `boop status`, because there is no development server to start.
+
 ## What To Do After Init
 
-If you used `--no-install`, run:
+Run the commands under "Next steps".
+If you used `--no-install` and `--no-beads`, that is:
 
 ```bash
 cd my-saas
 npm install
+bd init --non-interactive --server -p my-saas
+boop status
 npm run dev
 ```
 
-If you let Boop install dependencies for you, the shorter version is:
+If you let Boop install dependencies and set up beads for you, the shorter version is:
 
 ```bash
 cd my-saas

package/docs/loop.md

@@ -122,6 +122,21 @@ Session logs are written to `labs/claude-runs/` in the project directory. Each i
 - **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
+- **A failed queue read is never a clean finish** — if the loop cannot read the ready queue it says so and stops with exit code 1, rather than reporting "No more ready issues" and exiting 0. See [Reading the ready queue](#reading-the-ready-queue).
+
+## Reading the ready queue
+
+The loop reads claimable work with `bd ready --json -n 0`, projected through `jq` to the only three fields its filters use: `id`, `issue_type` and `parent`.
+
+The projection matters because `bd ready --json` returns every ready issue *with its full description*. In a repo with 112 ready issues that is 274,529 bytes, roughly 70% of it description the loop never looks at; projected, the same read is 5,941 bytes. Node captures at most 1 MiB from a subprocess by default and fails past it, so an unprojected read on a mature backlog dies — and a dead read used to be indistinguishable from an empty queue, which is how a loop could stop early with work still ready.
+
+**`jq` is recommended but not required.** It ships with neither stock macOS nor stock Debian, so when it is missing the loop warns once and falls back to the unprojected read. That stays safe because every `bd` read is capped at 256 MiB rather than the 1 MiB default. Install `jq` to keep the read small:
+
+```bash
+brew install jq
+```
+
+If the ready queue cannot be read at all, the loop says which command failed and stops with exit code 1 rather than reporting a clean finish. Under `--poll` it logs the failure and retries on the next interval.
 
 ## Planning Mode
 
@@ -167,6 +182,7 @@ The prefix is included in the planning prompt as a suggestion for naming the fea
 - **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.
+- **Ready-queue read failure** — If `bd ready` cannot be read, the loop reports the failing command and stops with exit code 1; it never reports a clean finish on a read it could not make.
 
 Planning session logs are written to `labs/claude-runs/` with the prefix `_planning_`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "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": [
@@ -21,7 +21,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && node tools/generate-version-manifest.js",
+    "build": "npm run build:caps && tsc && node tools/generate-version-manifest.js",
+    "build:cli": "tsc && node tools/generate-version-manifest.js",
     "typecheck": "tsc -p tsconfig.test.json",
     "skills:index": "node tools/generate-skills-index.js",
     "skills:layout": "tsx tools/generate-installed-layout.ts",

package/profiles/base/profile.md

@@ -0,0 +1,105 @@
+---
+name: base
+description: Planning, writing and issue tracking for a project that isn't an application
+defaultCapabilities:
+  - project-mgmt
+  - product-design
+  - skills
+---
+
+# Base Profile
+
+The part of boop that was never about web apps:
+the folder conventions, the agent instructions, the issue tracker,
+and the planning and writing skills.
+
+Some projects produce decisions, documents and tracked work rather than code.
+Setting up an AWS environment is one; a research project or a migration plan is another.
+They still need somewhere to write down what is intended,
+somewhere to record what now exists,
+and a list of what comes next.
+This profile gives them that and nothing else.
+
+It is not a web app with the app removed.
+A project made from it should read as a place to think and to track work,
+with `specs/` for what we intend, `reference/` for what exists, and issues for what comes next.
+Nothing in it assumes there is code to build, test or deploy,
+and if a file only makes sense for an application, it does not belong here.
+
+## What You Get
+
+Three capabilities, all of them `type: development`,
+whose skills apply to work that isn't code without any edits:
+
+- **project-mgmt** — beads issue tracking and planning skills
+- **product-design** — requirements, design, documentation and writing skills
+- **skills** — skill authoring, discovery and maintenance
+
+The profile also ships its own `templates/` folder,
+which `boop init` renders in place of the web-app kernel templates:
+an `AGENTS.md` that describes a project whose output is documents and tracked work,
+a `README.md`, a `CLAUDE.md` pointer, a `.github/copilot-instructions.md` pointer, a `.gitignore`,
+a README in each of `specs/`, `reference/` and `docs/` saying what belongs there,
+and a minimal `package.json`.
+Because `project-mgmt` is installed, `boop init` then commits the scaffold
+and sets up the project's beads issue tracker in Dolt server mode,
+so work can be filed as issues from the first minute.
+
+The `package.json` has no scripts or dependencies of its own.
+It exists because it is how boop delivers capability skills and refreshes them:
+without one, the capability packages would never be recorded
+and `boop update` would have nothing to update.
+
+## Three Deliberate Omissions
+
+The development capabilities that every other profile carries —
+`coding`, `testing` and `workflows` —
+are left out on purpose.
+An agent takes the skills and files in a project as a hint about what kind of work happens there,
+so every code-shaped thing in the scaffold is an invitation to do code-shaped work.
+
+### No testing
+
+`testing` installs Jest, `ts-jest`, a `tsconfig.test.json` and a `tests/` folder.
+A project with nothing to test would carry a test runner nobody runs,
+and an agent that finds one will reasonably suggest writing tests for it.
+
+### No workflows
+
+Seven of the ten `workflows` skills are for code:
+feature development, refactoring, test audits, website work and so on.
+An agent asked to "set up the network" could reasonably pick one of them up
+and start a feature branch for something that has no code in it.
+The three that suit any project — issue sweeps, knowledge backfill and stray disposition —
+can join this profile once `workflows` is split (tracked in `boop-4n87`).
+
+### No coding
+
+`coding` is mostly about application code:
+development conventions, code style, debugging.
+When a project grows code of its own, such as Terraform for an infrastructure project,
+`boop add coding` brings those skills in.
+Leaving the capability out costs nothing until then.
+
+## No Kernel, and Templates Instead
+
+### No kernel
+
+`web-app` carries a `kernel` block:
+a node runtime, a deploy target, a port, an Express dependency set and the scripts that start a server.
+This profile scaffolds no application, so it has none of those to name.
+
+Unlike `development`, which has no kernel either and is refused by `boop init`,
+this profile ships `templates/`,
+and a profile with templates is one `boop init` can scaffold.
+The steps that only mean something for an application —
+the Node version check, merging kernel dependencies
+and the `npm run dev` next step —
+are skipped.
+
+### No reference/
+
+The folder READMEs live under `templates/`, not in a `profiles/base/reference/` folder.
+Boop mirrors every profile's `reference/` pages into its own `reference/` folder as symlinks,
+so a README placed there would land in boop's own tree
+rather than in the projects made from this profile.

package/profiles/base/templates/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+Read the [AGENTS.md](../AGENTS.md) file and follow those instructions.
+
+Before starting work, run `boop status` to see what capabilities are configured and what needs setup.

package/profiles/base/templates/.gitignore.hbs

@@ -0,0 +1,6 @@
+node_modules/
+.env
+*.log
+.DS_Store
+.boop/*
+!.boop/config.json

package/profiles/base/templates/AGENTS.md.hbs

@@ -0,0 +1,50 @@
+# {{projectName}}
+
+This is a **boop**-managed project. Use boop commands — don't reinvent what boop already provides.
+
+## 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.
+
+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.
+
+## What this project is for
+
+This project produces decisions, documents and tracked work rather than an application.
+There is no code to build, test or deploy,
+so don't set up a test suite, a build step or a feature branch unless you are asked to.
+
+## How to work in this project
+
+1. **Prefer project skills over general knowledge.**
+   When a skill matches your task — writing a spec, planning work, filing issues, documenting something, writing a proposal — follow its `SKILL.md` instead of working from memory.
+   Skills live in `skills/` (each is a folder with a `SKILL.md`) and are also exposed at `.claude/skills/` for tooling that auto-discovers there.
+   If your tooling does not auto-surface skills, list `skills/` and read each `SKILL.md`'s frontmatter (`name`, `description`) to find a match.
+2. **Track work in beads.**
+   Every piece of work that outlives the current conversation is an issue in `bd`, not a markdown to-do list.
+   Run `bd ready` to see what is unblocked, and `bd create` to file something new.
+3. **Check project status.**
+   Run `boop status` to see which capabilities are installed and whether anything needs attention.
+4. **Use boop for capabilities.**
+   Run `boop caps` to see what is available.
+   If the project grows code of its own — infrastructure as code, a script worth keeping — run `boop add <capability>` (for example `boop add coding`) rather than installing and wiring things by hand.
+5. **Run `boop --help`** for the full command list.
+
+## Project layout
+- `specs/` — what we intend: proposals, designs and plans ("future state")
+- `reference/` — what exists now, kept true as things are finished or change ("current state")
+- `docs/` — guides for the people who use what this project produces
+- `skills/` — process skills for agents (each skill is a folder with a `SKILL.md`); also linked from `.claude/skills/` for Claude Code's built-in skill discovery
+- `.beads/` — the issue tracker's database (managed by `bd`)
+- `.boop/` — project manifest (managed by boop)
+
+## The working cycle
+
+1. **A spec describes the intent.**
+   Before a significant piece of work starts, write down in `specs/` what is wanted and why.
+2. **Issues carry the work.**
+   Once the spec is agreed, break it into issues in beads, one per step someone can pick up and finish.
+3. **`reference/` records the result.**
+   When a step is finished, or something that already exists changes, update `reference/` so it describes what is true now.
+
+Specs stay as the record of what was intended.
+`reference/` is what a newcomer reads to learn how things actually are, so it has to be kept current.

package/profiles/base/templates/CLAUDE.md.hbs

@@ -0,0 +1,3 @@
+# {{projectName}}
+
+Read [AGENTS.md](AGENTS.md) and follow all instructions there.

package/profiles/base/templates/README.md.hbs

@@ -0,0 +1,15 @@
+# {{projectName}}
+
+A project scaffolded with [boop](https://github.com/boop),
+for planning, writing and tracking work rather than building an application.
+
+## How it is organized
+
+- `specs/` — what we intend: proposals, designs and plans
+- `reference/` — what exists now, kept true as things change
+- `docs/` — guides for the people who use what this project produces
+- `skills/` — the process skills agents follow when working here
+- `.beads/` — the issue tracker; run `bd ready` to see what is next
+
+`AGENTS.md` explains how an agent should work in this project,
+and `boop status` shows which capabilities are installed.