@boopkit/cli 0.6.12 → 0.6.14

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.

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

@@ -0,0 +1,12 @@
+# Docs
+
+Guides for the people who **use** what this project produces.
+Where `reference/` explains how things are set up for the people who maintain them, `docs/` explains how to use them.
+
+## What belongs here
+
+- How-to guides for a task someone will come here to do, written from their side
+- Getting-started pages for someone meeting the result for the first time
+- Answers to the questions people keep asking
+
+Write for a reader who was not involved in the work and only needs to use its result.

package/profiles/base/templates/package.json.hbs

@@ -0,0 +1,7 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {},
+  "devDependencies": {}
+}

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

@@ -0,0 +1,16 @@
+# Reference
+
+Documents that describe **what exists now** — the current state of whatever this project has set up, decided or produced.
+Where `specs/` records what we intend, `reference/` records what is actually true.
+
+## What belongs here
+
+- A description of each thing that exists: what it is, where it lives, how it is configured, and why it is that way
+- Decisions that are in force, with enough of the reasoning that someone can tell when a decision no longer applies
+- Conventions this project follows, so a newcomer can work the same way
+
+## Keeping it true
+
+A reference page is only useful while it matches reality.
+When a piece of work is finished, or something that already exists changes, update the page that describes it as part of the same piece of work.
+If a page no longer describes anything real, delete it rather than leaving it to mislead.

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

@@ -0,0 +1,12 @@
+# Specs
+
+Design documents and specifications for planned features and changes. Specs describe the **future state** — what we intend to build — in contrast to `reference/` which documents the **current state**.
+
+## Workflow
+
+1. Write a spec for a new feature or significant change
+2. Review and approve the spec
+3. Create implementation tasks (in beads) from the approved spec
+4. After shipping, update `reference/` docs to reflect the new reality
+
+Specs remain as a record of design intent even after implementation.

package/profiles/development/profile.md

@@ -61,7 +61,14 @@ and it would make `boop init --profile development`
 emit an Express `src/app.ts` that imports a dependency the profile never installs.
 
 So `kernel` is absent, and `ProfileMetadata.kernel` is optional to allow it.
-The consequence is deliberate: `boop init --profile development` is refused
+
+Having no kernel does not on its own stop `boop init`.
+A profile that ships a `templates/` folder of its own, as `base` does,
+is scaffolded from those templates instead.
+This profile ships none, because it describes how a project is developed,
+not what files the project starts with.
+With neither a kernel nor templates there is nothing to write,
+and the consequence is deliberate: `boop init --profile development` is refused
 with a message pointing at the two ways this profile is actually meant to be used —
 name it in an existing project's `.boop/config.json`,
 or `boop add` these capabilities one at a time.

package/src/templates/skill-project/PROJECT.md

@@ -0,0 +1,28 @@
+# How this project applies this skill
+
+This file belongs to the project.
+`SKILL.md`, beside it, belongs to boop and is replaced on every `boop update`, so a rule written there is lost.
+boop created this file and never tracks, updates or overwrites it, so write this project's rules here.
+Where this file and `SKILL.md` conflict, this file wins.
+
+Put each rule under the heading that describes it.
+To decide between this file and `SKILL.md`, ask whether the rule would still be true in a brand-new boop project scaffolded tomorrow.
+If it would not, it belongs here.
+If it would, it belongs under "Offered to boop".
+
+## Adds
+
+Rules this project follows that the skill's guidance does not cover.
+
+## Narrows
+
+Where the skill offers a choice, the one this project always makes.
+
+## Overrides
+
+Where this project deliberately contradicts the skill's guidance, and why.
+
+## Offered to boop
+
+Rules that apply here and that this project thinks boop should adopt for every project.
+They stay in effect here until boop ships them.