@boopkit/cli 0.4.1 → 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-catalog.json

@@ -111,6 +111,13 @@
       "web"
     ]
   },
+  {
+    "name": "ux",
+    "description": "UX design judgement and the discovery/delivery workflows that operate it",
+    "type": "development",
+    "package": "@boopkit/cap-ux",
+    "requires": []
+  },
   {
     "name": "web",
     "description": "Web UI with Handlebars + Tailwind",

package/dist/capability-versions.json

@@ -1,18 +1,19 @@
 {
-  "@boopkit/cap-api": "0.4.0",
-  "@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.0",
-  "@boopkit/cap-database": "0.4.0",
+  "@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.4.0",
-  "@boopkit/cap-project-mgmt": "0.4.0",
-  "@boopkit/cap-services": "0.4.0",
-  "@boopkit/cap-skills": "0.4.0",
-  "@boopkit/cap-testing": "0.4.0",
-  "@boopkit/cap-users": "0.4.1",
-  "@boopkit/cap-web": "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.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/cli.js

@@ -44,6 +44,7 @@ const add_1 = require("./commands/add");
 const adopt_1 = require("./commands/adopt");
 const update_1 = require("./commands/update");
 const loop_1 = require("./commands/loop");
+const loop_merge_1 = require("./commands/loop-merge");
 const pkgJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new commander_1.Command();
 program
@@ -101,23 +102,43 @@ program
     .action(adopt_1.runAdopt);
 program
     .command('loop')
-    .description('Continuously process ready beads issues via Claude Code sessions')
-    .option('--prefix <prefix>', 'Issue ID prefix to filter by')
-    .option('--work <path>', 'Spec file for planning phase')
-    .option('--flow <path>', 'Workflow file for planning phase')
-    .option('--run', 'Actually execute (dry-run by default)')
-    .option('--max <n>', 'Stop after N issues')
-    .option('--budget <amount>', 'Budget cap per issue in USD (default: 5.00)')
-    .option('--resume-limit <n>', 'Max resume attempts per issue (default: 3)')
-    .option('--poll', 'Keep polling when no ready issues found')
-    .option('--poll-interval <seconds>', 'Seconds between polls (default: 60)')
-    .option('--model <model>', 'Claude model to use (default: claude-opus-4-6)')
-    .option('--per-issue-branch', 'Create a separate branch per issue')
-    .option('--no-branch', 'Skip branch creation entirely')
-    .option('--features', 'Include feature-type issues (excluded by default)')
-    .option('--no-skip-perms', 'Do not skip permission prompts')
-    .option('--bare', 'Force API key auth (--bare mode); skips OAuth/keychain, uses ANTHROPIC_API_KEY strictly')
-    .option('--json', 'Output summary as JSON')
-    .addHelpText('after', '\nBy default runs in dry-run mode. Add --run to execute.')
-    .action(loop_1.runLoop);
+    .summary('Drive Claude Code sessions to build work autonomously')
+    .description('Drive Claude Code sessions to build work autonomously, in one of three modes:\n' +
+    '  spec-driven   --work <spec> --flow <flow>  plan a feature tree from a spec, then build every task\n' +
+    '  issue-driven  --prefix <issue-id>          process ready beads issues in scope: ID starts with the prefix, or any parent-chain ancestor ID does\n' +
+    '  merge         --merge [branch]             integrate completed feature worktrees into main')
+    // — Mode selection (pick exactly one mode) —
+    .option('--work <path>', 'spec-driven: spec/work file to plan from (requires --flow)')
+    .option('--flow <path>', 'spec-driven: workflow file or skill dir that drives planning (requires --work)')
+    .option('--prefix <prefix>', 'issue-driven: scope of issues to process — in scope if the issue ID starts with this prefix OR any ancestor (parent chain) ID does, so issues re-parented under a matching epic/feature are included even with unrelated IDs. Pass a full issue ID; a truncated one over-matches (boop-4 also matches boop-45j)')
+    .option('--merge [branch]', 'merge: integrate completed feature worktrees into main (optional single branch skips readiness)')
+    // — Mode-specific options —
+    .option('--features', 'issue-driven only: also process leaf feature-type issues (excluded by default; always on in spec-driven mode). Feature roots that own child tasks are never claimed directly — they are containers, not work.')
+    .option('--watch', 'merge only: poll for ready branches and merge them as they land')
+    // — Shared execution options —
+    .option('--run', 'actually execute (dry-run by default)')
+    .option('--max <n>', 'stop after N issues')
+    .option('--budget <amount>', `budget cap per issue in USD (default: ${loop_1.DEFAULT_BUDGET_USD})`)
+    .option('--model <model>', 'Claude model to use, applied to every spawned session and nested loop (falls back to $ANTHROPIC_MODEL, then claude-opus-4-8). Sub-agents keep their own declared model unless they opt into model: inherit.')
+    .option('--poll', 'keep polling when no ready issues found')
+    .option('--poll-interval <seconds>', 'seconds between polls (default: 60)')
+    .option('--resume-limit <n>', 'max resume attempts per issue (default: 3)')
+    .option('--per-issue-branch', 'create a separate branch per issue')
+    .option('--no-branch', 'skip branch/worktree creation; run in place on the current branch')
+    .option('--no-skip-perms', 'do not skip permission prompts')
+    .option('--bare', 'force API key auth; skip OAuth/keychain, use ANTHROPIC_API_KEY strictly')
+    .option('--json', 'output summary as JSON')
+    .addHelpText('after', [
+    '',
+    'Examples:',
+    '  boop loop --work specs/feature.spec.md --flow skills/my-flow/SKILL.md --run',
+    '  boop loop --prefix boop-abc --run --features',
+    '  boop loop --merge --run --watch',
+    '',
+    'Notes:',
+    '  • Dry-run by default; add --run to execute.',
+    '  • --work and --flow must be used together; --features and --watch only apply to their own mode.',
+    '  • Merge mode rebases ready work/<id> branches onto main, runs tests, ff-merges, and cleans up worktrees.',
+].join('\n'))
+    .action((options) => (options.merge ? (0, loop_merge_1.runMerge)(options) : (0, loop_1.runLoop)(options)));
 program.parse(process.argv);

package/dist/commands/loop-merge.d.ts

@@ -0,0 +1,83 @@
+import { LoopOptions, WorktreeMode } from './loop';
+/**
+ * Slice 2 — `boop loop --merge`.
+ *
+ * Sequential integration of completed feature worktrees back into main. No
+ * individual loop merges its own branch; this is the dedicated integrator.
+ *
+ * For each ready branch (sequential, failure-isolated):
+ *   record orig sha → rebase work/<id> onto main → npm test → ff-merge into main
+ *   → remove worktree + branch.
+ *
+ * Safety contract: main is NEVER left dirty. A rebase conflict aborts the rebase;
+ * a post-rebase test failure resets the branch to its original sha; either way we
+ * file a beads issue and skip to the next branch. Only `package.json` dependency
+ * additions are auto-resolved (the one documented known-safe pattern); every other
+ * conflict punts to a human via a beads issue.
+ */
+export interface WorktreeMeta {
+    version: number;
+    mode: WorktreeMode;
+    scope: string;
+    branch: string;
+    worktreePath: string;
+}
+export interface MergeCandidate {
+    branch: string;
+    worktreePath: string;
+    scope: string;
+    mode: WorktreeMode;
+    ready: boolean;
+}
+interface ScopeIssue {
+    id: string;
+    parent?: string;
+    status?: string;
+}
+export interface MergeDeps {
+    projectDir?: string;
+    execSyncFn?: (cmd: string, opts?: {
+        cwd?: string;
+        stdio?: unknown;
+    }) => string;
+    existsSyncFn?: (p: string) => boolean;
+    readFileFn?: (p: string) => string;
+    /** Returns beads issues at the given status (`bd list --status=<s> --json`). */
+    bdListFn?: (status: 'open' | 'closed') => ScopeIssue[];
+    /** Parent-id lookup for ancestors not present in the listed set. */
+    getParentFn?: (id: string) => string | null;
+    /** File a beads issue on merge failure. Returns the created issue id (or null). */
+    createIssueFn?: (title: string, description: string) => string | null;
+    /** Best-effort sleep between watch polls. */
+    sleepFn?: (ms: number) => Promise<void>;
+    /** Dolt server-mode guard (defaults to the real `assertDoltServerMode`). */
+    assertServerModeFn?: (projectDir: string) => void;
+}
+/**
+ * Pick the higher of two version specifiers for the same dependency key. Ties and
+ * unparseable specifiers prefer `ours` (the integration/main side) for stability.
+ */
+export declare function pickHigherVersion(ours: string, theirs: string): string;
+/**
+ * Union-merge two package.json sides that conflicted during a rebase. Dependency
+ * maps are unioned (same-key version conflict → higher semver). Every other
+ * top-level key must already agree between the two sides; if any non-dependency
+ * key differs, the conflict is NOT known-safe and this throws so the caller punts
+ * to a human. Returns the merged JSON text (2-space indent, trailing newline).
+ */
+export declare function mergePackageJsonContents(oursText: string, theirsText: string): string;
+/**
+ * A worktree is ready to merge when every beads issue in its scope is closed.
+ * That means: at least one closed in-scope issue exists AND zero open in-scope
+ * issues remain. `bd ready` is insufficient (it only returns *unblocked* issues),
+ * so we list by status and filter with the same scope rule the loop uses.
+ */
+export declare function isScopeComplete(scope: string, deps: MergeDeps): boolean;
+/**
+ * Enumerate registered git worktrees, read each `.boop-worktree.json`, and decide
+ * which are ready to merge. Worktrees without metadata (e.g. unrelated worktrees)
+ * are ignored.
+ */
+export declare function findMergeCandidates(deps: MergeDeps): MergeCandidate[];
+export declare function runMerge(options: LoopOptions, deps?: MergeDeps): Promise<void>;
+export {};