@biffo/cli 0.109.1 → 0.109.3

package/_skeletons/plugin-template/.github/workflows/ci.yml

@@ -8,9 +8,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [dev]
   pull_request:
-    branches: [main]
+    branches: [dev]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

package/_skeletons/plugin-template/AGENTS.md

@@ -0,0 +1,73 @@
+# Rules of Engagement for AI Agents
+
+These rules are **binding for every automated coding agent** working in this
+repository — Claude Code, Codex, Cursor, or any other. They are tool-agnostic:
+express everything as plain `git` / `gh` / `pnpm` / `uv` commands. Tool-specific
+guidance belongs in that tool's own file (e.g. `CLAUDE.md`), which imports this
+one rather than restating it.
+
+This is a **Biffo satellite repo** (a plugin or sibling app), separate from the
+core project it extends. It follows the same engagement rules as every Biffo
+repo; only its product differs.
+
+## 1. One integration branch: `dev`
+
+- **`dev` is the integration branch** — you branch from it and open every PR back
+  into it; `gh repo view --json defaultBranchRef` confirms it. If it reports
+  anything other than `dev`, flag it rather than working around it. (A sibling app
+  also carries `staging` and a reserved `main`/production branch as promotion
+  targets — production not built yet; a plugin repo has `dev` only. Either way you
+  work off `dev`.)
+- **All changes land via PR.** No direct commits to `dev`, no force-pushes to it.
+  Branch protection stays on.
+- Never leave the primary checkout parked on a feature branch or let it fall
+  behind — keep it on `dev`, no more than a `git fetch` behind, and do the work
+  in worktrees (§2).
+
+## 2. Work in an isolated worktree
+
+- **Always start from a freshly-fetched `dev`:** `git fetch origin`, then
+  `git worktree add .worktrees/<name> -b <type>/<slug> origin/dev`. Never branch
+  from a stale local ref.
+- **Install dependencies in the new worktree before working** — `uv sync` and/or
+  `pnpm install`, so the local gates (pre-push checks, lint-staged) run against
+  fresh deps, not a stale `.venv`/`node_modules`.
+- **One worktree per unit of work**, under the git-ignored `.worktrees/`.
+- **Clean up when the PR merges:** `git worktree remove .worktrees/<name>`, then
+  let the branch be deleted. Keep `git worktree list` short and every entry live.
+
+## 3. Commits
+
+- **Conventional Commits** (`feat`, `fix`, `chore`, `docs`, `test`, `infra`,
+  `security`, `refactor`, `perf`, `ci`), enforced by commitlint.
+- Tag your commits with your agent's own `Co-Authored-By:` trailer.
+- Keep commits and PRs **scoped to one concern**.
+
+## 4. Pull requests
+
+- Link the issue the PR resolves (`Closes #N`) and describe what changed and why.
+- Mark a PR **ready** (not draft) when it is meant to merge.
+- Behavior changes ship **with tests**. Don't reduce coverage to make CI pass.
+
+## 5. Merging — never merge red
+
+- Get CI green and confirm it: `gh pr checks <N>`. A green local run is not
+  sufficient — verify the actual PR checks.
+- **Squash-merge, delete the branch, remove the worktree:**
+  `gh pr merge <N> --squash --delete-branch`.
+
+## 6. Push honestly, and verify the remote has your commit
+
+- **Push with the exit status visible:** `git push origin HEAD; echo $?`. A pipe
+  (`git push | tail`) reports the pipe's status, not git's — a rejected push then
+  reads as success and the commit is silently lost. Never trust a "pushed"
+  message printed unconditionally after a pipe.
+- **Confirm the remote actually has the commit before relying on it,** especially
+  before merge: `git log origin/<branch> -1`. A green PR page is not proof your
+  latest local commit reached it.
+
+## 7. Security
+
+- **Never commit secrets** (keys, tokens, credentials, `.env` values).
+- **Never silently disable a security gate.** If one must be loosened, do it in
+  the open and raise a tracking issue to restore it.

package/_skeletons/plugin-template/CLAUDE.md

@@ -0,0 +1,15 @@
+# AI Assistant Context
+
+The tool-agnostic rules of engagement for **all** automated agents (integration
+branch, worktrees, commits, PRs, merging, honest pushes, security) live in
+[`AGENTS.md`](AGENTS.md) and are imported below. They are binding for any change
+in this repo; `AGENTS.md` is the single source of truth.
+
+@AGENTS.md
+
+## What this repo is
+
+A **Biffo plugin** — code that extends a core Biffo project, distributed and
+mounted by it. See the core project's ADR-0003 (plugin system) and ADR-0021
+(shared plugin hosting) for how a plugin is installed and run. This repo carries
+the plugin's own manifest (`biffo.plugin.json`), source, and tests.

package/_skeletons/sibling-template/.github/workflows/ci.yml

@@ -12,9 +12,9 @@ name: CI
 
 on:
   push:
-    branches: [main, dev, staging]
+    branches: [dev, staging, main]
   pull_request:
-    branches: [main, dev, staging]
+    branches: [dev, staging, main]
   # Manual re-run, matching the core project's CI. Without this there is no way
   # to trigger CI on a protected branch without pushing to it — and a sibling
   # repo has the same branch protection, so the same recovery gap. See #293.

package/_skeletons/sibling-template/.github/workflows/codeql.yml

@@ -2,9 +2,9 @@ name: 'CodeQL'
 
 on:
   push:
-    branches: [main, dev, staging]
+    branches: [dev, staging, main]
   pull_request:
-    branches: [main, dev, staging]
+    branches: [dev, staging, main]
   schedule:
     # Weekly catch-up scan (Tuesday 05:17 UTC) for issues that land outside
     # PR review (e.g. direct merges onto a branch).

package/_skeletons/sibling-template/AGENTS.md

@@ -0,0 +1,73 @@
+# Rules of Engagement for AI Agents
+
+These rules are **binding for every automated coding agent** working in this
+repository — Claude Code, Codex, Cursor, or any other. They are tool-agnostic:
+express everything as plain `git` / `gh` / `pnpm` / `uv` commands. Tool-specific
+guidance belongs in that tool's own file (e.g. `CLAUDE.md`), which imports this
+one rather than restating it.
+
+This is a **Biffo satellite repo** (a plugin or sibling app), separate from the
+core project it extends. It follows the same engagement rules as every Biffo
+repo; only its product differs.
+
+## 1. One integration branch: `dev`
+
+- **`dev` is the integration branch** — you branch from it and open every PR back
+  into it; `gh repo view --json defaultBranchRef` confirms it. If it reports
+  anything other than `dev`, flag it rather than working around it. (A sibling app
+  also carries `staging` and a reserved `main`/production branch as promotion
+  targets — production not built yet; a plugin repo has `dev` only. Either way you
+  work off `dev`.)
+- **All changes land via PR.** No direct commits to `dev`, no force-pushes to it.
+  Branch protection stays on.
+- Never leave the primary checkout parked on a feature branch or let it fall
+  behind — keep it on `dev`, no more than a `git fetch` behind, and do the work
+  in worktrees (§2).
+
+## 2. Work in an isolated worktree
+
+- **Always start from a freshly-fetched `dev`:** `git fetch origin`, then
+  `git worktree add .worktrees/<name> -b <type>/<slug> origin/dev`. Never branch
+  from a stale local ref.
+- **Install dependencies in the new worktree before working** — `uv sync` and/or
+  `pnpm install`, so the local gates (pre-push checks, lint-staged) run against
+  fresh deps, not a stale `.venv`/`node_modules`.
+- **One worktree per unit of work**, under the git-ignored `.worktrees/`.
+- **Clean up when the PR merges:** `git worktree remove .worktrees/<name>`, then
+  let the branch be deleted. Keep `git worktree list` short and every entry live.
+
+## 3. Commits
+
+- **Conventional Commits** (`feat`, `fix`, `chore`, `docs`, `test`, `infra`,
+  `security`, `refactor`, `perf`, `ci`), enforced by commitlint.
+- Tag your commits with your agent's own `Co-Authored-By:` trailer.
+- Keep commits and PRs **scoped to one concern**.
+
+## 4. Pull requests
+
+- Link the issue the PR resolves (`Closes #N`) and describe what changed and why.
+- Mark a PR **ready** (not draft) when it is meant to merge.
+- Behavior changes ship **with tests**. Don't reduce coverage to make CI pass.
+
+## 5. Merging — never merge red
+
+- Get CI green and confirm it: `gh pr checks <N>`. A green local run is not
+  sufficient — verify the actual PR checks.
+- **Squash-merge, delete the branch, remove the worktree:**
+  `gh pr merge <N> --squash --delete-branch`.
+
+## 6. Push honestly, and verify the remote has your commit
+
+- **Push with the exit status visible:** `git push origin HEAD; echo $?`. A pipe
+  (`git push | tail`) reports the pipe's status, not git's — a rejected push then
+  reads as success and the commit is silently lost. Never trust a "pushed"
+  message printed unconditionally after a pipe.
+- **Confirm the remote actually has the commit before relying on it,** especially
+  before merge: `git log origin/<branch> -1`. A green PR page is not proof your
+  latest local commit reached it.
+
+## 7. Security
+
+- **Never commit secrets** (keys, tokens, credentials, `.env` values).
+- **Never silently disable a security gate.** If one must be loosened, do it in
+  the open and raise a tracking issue to restore it.

package/_skeletons/sibling-template/CLAUDE.md

@@ -0,0 +1,16 @@
+# AI Assistant Context
+
+The tool-agnostic rules of engagement for **all** automated agents (integration
+branch, worktrees, commits, PRs, merging, honest pushes, security) live in
+[`AGENTS.md`](AGENTS.md) and are imported below. They are binding for any change
+in this repo; `AGENTS.md` is the single source of truth.
+
+@AGENTS.md
+
+## What this repo is
+
+A **Biffo sibling app** (ADR-0007) — an independently-deployed microservice that
+shares the core project's login and domain (`baseurl.com/<name>`) but has its own
+repo, CI/CD, and AWS resources. It never touches the core database directly — it
+only ever calls the core project's own API. Its own identity lives in
+`biffo.sibling.json`.

package/dist/index.js

@@ -515,10 +515,11 @@ var GitAdapter = class {
    *
    * Sets the initial branch name explicitly (`-b`) rather than relying on
    * the running machine's `init.defaultBranch` git config, which isn't
-   * guaranteed to be "main" (or even consistent between a dev's laptop and
-   * a CI runner).
+   * guaranteed to be "dev" (or even consistent between a dev's laptop and
+   * a CI runner). Defaults to `dev`, the single integration branch every Biffo
+   * repo uses (#559).
    */
-  async init(cwd, initialBranch = "main") {
+  async init(cwd, initialBranch = "dev") {
     await execa("git", ["init", "-b", initialBranch], { cwd });
   }
   /** Adds a remote. Fails if a remote with this name already exists. */
@@ -531,7 +532,7 @@ var GitAdapter = class {
   async commit(cwd, message) {
     await execa("git", ["commit", "-m", message], { cwd });
   }
-  /** The current branch name (e.g. "main"). */
+  /** The current branch name (e.g. "dev"). */
   async currentBranch(cwd) {
     const { stdout } = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
     return stdout.trim();
@@ -644,7 +645,7 @@ var GitHubAdapter = class {
    * The repo's default branch — the integration branch a PR should target.
    *
    * Asked of GitHub rather than inferred from the local checkout: it differs per
-   * repo (biffo-template uses `main`, instances use `dev`), and the local
+   * repo (every Biffo repo uses `dev` (#559)), and the local
    * current branch is whatever the caller happens to be on, which under the
    * worktree-per-change workflow is never it.
    */
@@ -840,7 +841,7 @@ var GitHubAdapter = class {
       `Ref "${ref}" not found in ${org}/${repo} after ${timeoutMs / 1e3}s \u2014 GitHub template generation may have stalled. Check the repository and re-run biffo init.`
     );
   }
-  async createBranch(org, repo, branch, from = "main", waitTimeoutMs = 12e4, waitIntervalMs = 3e3) {
+  async createBranch(org, repo, branch, from = "dev", waitTimeoutMs = 12e4, waitIntervalMs = 3e3) {
     try {
       await this.octokit.repos.getBranch({ owner: org, repo, branch });
       log.info(`Branch ${branch} already exists \u2014 skipping`);
@@ -1269,7 +1270,7 @@ var GitHubAdapter = class {
       }
     }
   }
-  async triggerWorkflow(org, repo, workflowId, inputs = {}, ref = "main", timeoutMs = 6e4, intervalMs = 5e3) {
+  async triggerWorkflow(org, repo, workflowId, inputs = {}, ref = "dev", timeoutMs = 6e4, intervalMs = 5e3) {
     const deadline = Date.now() + timeoutMs;
     while (true) {
       try {
@@ -1288,7 +1289,7 @@ var GitHubAdapter = class {
       }
     }
   }
-  async waitForWorkflowRun(org, repo, workflowId, baselineRunId, timeoutMs = 36e5, intervalMs = 3e4, branch = "main") {
+  async waitForWorkflowRun(org, repo, workflowId, baselineRunId, timeoutMs = 36e5, intervalMs = 3e4, branch = "dev") {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       const { data } = await this.octokit.actions.listWorkflowRuns({
@@ -1977,7 +1978,7 @@ function breakingChangesBetween(from, to, entries) {
 }
 
 // src/lib/global-workflows.ts
-var GLOBAL_DISPATCH_REF = "main";
+var GLOBAL_DISPATCH_REF = "dev";
 var GLOBAL_DISPATCH_WORKFLOW_PATHS = [
   ".github/workflows/deploy-global.yml"
 ];
@@ -5300,11 +5301,11 @@ async function pushSkeleton(git, skeletonRoot, cloneUrl, config, coreConfig, git
       // `template_version` field doc on `SiblingMarker` (lib/sibling-teardown.ts).
       templateVersion: getLatestCoreVersion()
     });
-    await git.init(workDir, "main");
+    await git.init(workDir, "dev");
     await git.addRemote(workDir, "origin", cloneUrl);
     await git.add(workDir, ["."]);
     await git.commit(workDir, `feat: scaffold ${config.project.name} sibling app (ADR-0007)`);
-    await git.push(workDir, "main", { token: githubToken });
+    await git.push(workDir, "dev", { token: githubToken });
   } finally {
     git.cleanup(workDir);
   }
@@ -5345,8 +5346,8 @@ function writeSiblingTemplate(templateRoot, targetDir, config, context) {
 }
 async function configureSiblingGithub(github, config, coreConfig, session, coreIdentity) {
   const { org, repo } = githubRepo(config);
-  await github.createBranch(org, repo, "dev", "main");
-  await github.createBranch(org, repo, "staging", "main");
+  await github.createBranch(org, repo, "staging", "dev");
+  await github.createBranch(org, repo, "main", "dev");
   await github.setDefaultBranch(org, repo, "dev");
   await github.configureBranchProtection(config);
   await github.createEnvironments(config);
@@ -5694,9 +5695,9 @@ async function runInit(github, aws, config, session, appSibling) {
   }
   const { org, repo } = config.source_control.config;
   if (!hasCompleted(session, "github_branches")) {
-    log.step(5, totalSteps, "Creating dev and staging branches...");
-    await github.createBranch(org, repo, "dev", "main");
-    await github.createBranch(org, repo, "staging", "main");
+    log.step(5, totalSteps, "Creating the staging and main branches...");
+    await github.createBranch(org, repo, "staging", "dev");
+    await github.createBranch(org, repo, "main", "dev");
     markStepComplete(session, "github_branches");
   } else {
     log.step(5, totalSteps, "Branches already created \u2014 skipping");
@@ -5833,8 +5834,8 @@ function appSiblingRegistryFiles(config) {
   }));
 }
 var INSTANCE_CONFIG_FILE = "biffo.config.json";
-var INSTANCE_FILE_BASE_BRANCH = "main";
-var INSTANCE_FILE_FOLLOWER_BRANCHES = ["dev", "staging"];
+var INSTANCE_FILE_BASE_BRANCH = "dev";
+var INSTANCE_FILE_FOLLOWER_BRANCHES = ["staging", "main"];
 var INSTANCE_FILE_BRANCHES = [
   INSTANCE_FILE_BASE_BRANCH,
   ...INSTANCE_FILE_FOLLOWER_BRANCHES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.109.1",
+  "version": "0.109.3",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",