bearings 0.5.1 → 0.5.3

package/dist/{chunk-5D5YO3E3.js → chunk-WYXKSCUW.js}

@@ -16,6 +16,9 @@ var SKILLS = STARTER_SKILL_NAMES;
 var MANUAL_TESTPLAN_FILES = [
   "SKILL.md"
 ];
+var ORCHESTRATE_FILES = [
+  "SKILL.md"
+];
 var FORGE_A_SKILL_FILES = [
   "SKILL.md",
   "templates/guardrail.md",
@@ -63,6 +66,11 @@ var SCAFFOLD = [
     target: `.agents/skills/manual-testplan/${file}`,
     owner: "bearings"
   })),
+  ...ORCHESTRATE_FILES.map((file) => ({
+    template: `agents/skills/orchestrate/${file}`,
+    target: `.agents/skills/orchestrate/${file}`,
+    owner: "bearings"
+  })),
   ...FORGE_A_SKILL_FILES.map((file) => ({
     template: `agents/skills/forge-a-skill/${file}`,
     target: `.agents/skills/forge-a-skill/${file}`,
@@ -783,7 +791,7 @@ async function runFreshInit(repoDir, flags, version) {
 async function runInit(repoDir, flags, version) {
   const state = await inspectManifest(repoDir);
   if (state.kind === "absent") return runFreshInit(repoDir, flags, version);
-  const { runUpdate } = await import("./update-QTWNGAGX.js");
+  const { runUpdate } = await import("./update-4DZKUPFP.js");
   return runUpdate(repoDir, flags, version, state);
 }
 

package/dist/cli.js

@@ -8,7 +8,7 @@ import {
   skillBaselinePath,
   starterSkillNameFromTarget,
   validateHarnesses
-} from "./chunk-5D5YO3E3.js";
+} from "./chunk-WYXKSCUW.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/{update-QTWNGAGX.js → update-4DZKUPFP.js}

@@ -16,7 +16,7 @@ import {
   templatesDir,
   validateHarnesses,
   writeBackup
-} from "./chunk-5D5YO3E3.js";
+} from "./chunk-WYXKSCUW.js";
 
 // src/semver.ts
 function parseSemver(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bearings",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
   "type": "module",
   "engines": {

package/templates/agents/commands/setup-repo.md

@@ -1,17 +1,21 @@
 ---
-description: One-time (re-runnable) project tailoring after `bearings init`. Interviews the developer, explores the repo, and completes the agent-friendly setup.
+description: First-time project tailoring after `bearings init`, and post-update reconciliation when `setupPending`. Not for map refresh.
 ---
 
 # /setup-repo
 
-You are completing the agent-friendly setup that `bearings init` scaffolded.
-The scaffold is generic; your job is everything project-specific. Interview
-the developer relentlessly — one question at a time, with a recommended
-answer per question — and explore the code before asking anything the code
-can answer.
+Pick one mode and stop when that mode finishes.
+
+- Manifest has `setupPending` → **Post-update reconciliation**, then stop.
+- `AGENTS.md` still has `## Setup Required` → **Required workflow**, then stop.
+- Neither → already done. Map drift is `/refresh-repo-map`.
 
 This is the only operation the temporary `## Setup Required` gate in
-`AGENTS.md` permits. Do not remove the gate until step 12 below.
+`AGENTS.md` permits. Do not remove the gate until the Required workflow's
+verify step reports zero failures and zero warnings.
+
+Explore the repo before asking. Ask one question at a time, with a
+recommended answer, only for facts the code cannot answer.
 
 ## Post-update reconciliation
 
@@ -21,19 +25,20 @@ When `.agents/bearings.json` is manifest v2 and has `setupPending`:
    `migrationReconciliations` record.
 2. Resolve every `migrationReconciliations` record through **Migrated checklist
    repairs** below.
-3. For each non-`skill-update` reconciliation, read its Backup File and current target, summarize
+3. For each `skill-update` reconciliation, follow **Starter skill updates**
+   below.
+4. For each remaining reconciliation, read its Backup File and current target, summarize
    the differences, and ask which backed-up changes to apply to the target.
-4. Apply the developer's choice directly to the target regardless of owner,
+5. Apply the developer's choice directly to the target regardless of owner,
    delete the resolved Backup File, and remove its reconciliation record.
-5. A `skippedTemplate` records a declined template revision.
+6. A `skippedTemplate` records a declined template revision.
    Do not apply the declined template — normal project maintenance may
    still update that file.
-6. Run only setup steps supported by current drift; do not reset completed
-   project tailoring.
 7. Run `bearings verify`. Resolve every failure and warning except the
    expected `setup-pending` warning, then remove `setupPending` from the
    manifest.
 8. Run `bearings verify` again and finish only at zero failures and warnings.
+   Stop here. Do not continue into first-time setup. Do not run `/refresh-repo-map`.
 
 ### Starter skill updates (`skill-update`)
 
@@ -87,28 +92,10 @@ follows `.agents/skills/checklist/SKILL.md`.
 
 ## Checklist opener
 
-Add or reuse one project-native command that runs `npx bearings checklist` (or
-the repository's established local bearings invocation). This command builds
-the checklist payload and opens the static previewer.
-
-1. Search existing automation and documentation for an existing equivalent
-   runner command that already builds and opens the checklist previewer. Reuse
-   it and report its exact invocation without editing its runner.
-2. Otherwise, select the first existing safe automation home in this exact
-   priority: `justfile`, `Makefile`, `Taskfile.yml`, `mise.toml`, then
-   `package.json`.
-3. Before editing an existing automation file, show the proposed command and
-   ask the developer for approval. Edit it only after approval. If approval is
-   declined, leave it unchanged and continue through the priority order.
-4. If no existing home is safe and approved, ask the developer to choose
-   between creating one missing automation file from the list above and using
-   the direct fallback. Create a missing file only after the developer selects
-   that strategy and file.
-5. When no automation file is selected, make no automation edit and report the
-   stack-agnostic direct build-and-open fallback: `npx bearings checklist`.
-6. Run the selected command, or the direct fallback, and confirm that it builds
-   successfully and opens the static previewer. Report its exact invocation for
-   future use.
+Reuse an existing equivalent runner command that already invokes
+`npx bearings checklist` (or the repository's established local bearings
+invocation). If none exists, report `npx bearings checklist`. Do not create
+or edit automation files. Do not open the previewer during setup.
 
 ## Required workflow
 
@@ -117,25 +104,18 @@ the checklist payload and opens the static previewer.
    summarise what it contained, and ask per file whether to merge into the
    new scaffold, keep parts, or discard. Apply their choice, then remove
    the resolved backup.
-3. Explore the repo: stack, package manager, canonical install/run/build/
-   test/lint commands, CI, generated paths, secret/config paths, deployment
-   surfaces, project purpose, users/operators, and hard domain/technical
-   constraints. Interview the developer one question at a time for anything
-   the code cannot answer.
-4. Fill only the `AGENTS.md` project-purpose and primary-stack placeholders.
-   Keep `AGENTS.md` a thin router — do not add a skill table, invariants
-   section, or always-on rules block.
-5. Adapt every starter skill:
+3. Fill only the `AGENTS.md` project-purpose and primary-stack placeholders
+   from the repo. Keep `AGENTS.md` a thin router — do not add a skill table,
+   invariants section, or always-on rules block.
+4. Adapt every starter skill:
    - `.agents/skills/commit-convention/SKILL.md`
    - `.agents/skills/defer-work/SKILL.md`
    - `.agents/skills/resurface-deferred-work/SKILL.md`
    - `.agents/skills/recording-decisions/SKILL.md`
-   - Explore the repo for format, lint-fix, lint, typecheck, test, build,
-     and docs verification commands.
    - Replace every `<agent: fill during handoff — …>` marker with a real
      command or explicit `not configured`.
    - Light project tailoring only — do not remove the skill's safety workflow.
-6. Claim starter skills in `.agents/bearings.json` (allowed manifest edit):
+5. Claim starter skills in `.agents/bearings.json` (allowed manifest edit):
    - Set each starter skill `owner` to `agent`.
    - Set `hash` to the sha256 of the file contents (use the same algorithm as
      bearings: UTF-8 body, `sha256:` + hex).
@@ -145,19 +125,14 @@ the checklist payload and opens the static previewer.
      `lastTemplateHash` equals `hash`).
    - Write `.agents/.bearings-baseline/skills/<name>/SKILL.md` equal to the
      live file bytes.
-7. Complete the **Checklist opener** workflow above.
-8. Run the `/refresh-repo-map` workflow to initialize `docs/DOMAIN.md`,
-    `docs/ARCHITECTURE.md`, `docs/CODEBASE_MAP.md`, and
-    `docs/diagrams/c4-component.puml`.
-9. Expose any newly created skills into each configured harness using the
-    manifest's existing symlink/copy mode.
-10. Run `bearings verify`. Fix every failure and every warning.
-11. Confirm the run reports zero failures and zero warnings before
-     proceeding.
-12. Remove the `## Setup Required` section from `AGENTS.md` — only after
-    step 11 confirms zero failures and zero warnings.
-13. Run `bearings verify` again and report the completed setup to the
-    developer.
+6. Complete the **Checklist opener** workflow above.
+7. If `docs/DOMAIN.md`, `docs/ARCHITECTURE.md`, or `docs/CODEBASE_MAP.md`
+   still contains a `<agent:` placeholder, run the `/refresh-repo-map` workflow
+   to initialize those files and `docs/diagrams/c4-component.puml`.
+8. Run `bearings verify`. Fix every failure and every warning. Confirm
+   zero failures and zero warnings. Remove the `## Setup Required` section
+   from `AGENTS.md` — only after that confirmation. Run `bearings verify`
+   again and report the completed setup to the developer.
 
 ## Rules
 
@@ -178,5 +153,3 @@ the checklist payload and opens the static previewer.
   the path).
 - Do not remove the `## Setup Required` section before `bearings verify`
   reports zero failures and zero warnings.
-- Re-running this command later is allowed: skip completed steps and focus
-  on drift between the maps and reality.

package/templates/agents/skills/orchestrate/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: orchestrate
+description: Run a large task as an orchestrator that plans and decides in the main context and delegates context-heavy work to sub-agents. Use only when the developer invokes /orchestrate by name.
+disable-model-invocation: true
+---
+
+# Orchestrate
+
+Act as the orchestrator. The main context holds the plan, the decisions, and
+the synthesis; sub-agents absorb the raw material — file dumps, logs, command
+output — and return conclusions, not transcripts. If this harness cannot start
+sub-agents, tell the developer, then run the same plan inline.
+
+## Workflow
+
+1. Plan in the main context. Break the task into work items and mark each
+   `delegate` or `keep` using the Delegation table. The plan is done when every
+   item has a mark and the delegated items name their dependencies.
+2. Dispatch a sub-agent for every `delegate` item, following Sub-agent briefs.
+   Run independent items concurrently; run items that touch the same files in
+   sequence or merge them into one brief.
+3. Integrate. Read only the sub-agents' conclusions, make the decisions in the
+   main context, and dispatch follow-up sub-agents for gaps the conclusions
+   expose.
+4. Report: the decisions made, what each sub-agent concluded, and the final
+   result with its verification.
+
+## Delegation table
+
+| Work | Sub-agent returns |
+|---|---|
+| Search and exploration across many files | `path#symbol` locations plus a one-paragraph answer |
+| Bulk reading: large files, logs, external docs | Only the facts that bear on the task, with citations |
+| Verbose commands: tests, builds, lints | Pass or fail, plus only the failing output |
+| Implementation of an independent plan slice | Changed file list plus its self-check result |
+
+Keep in the main context: the plan, choices between approaches, targeted reads
+of already-located sections, and every question for the developer.
+
+## Sub-agent briefs
+
+A sub-agent starts with an empty context. Every brief carries:
+
+- The goal and its completion criterion — how the sub-agent knows it is done.
+- Every input it cannot discover cheaply: paths, commands, constraints, and
+  the repository conventions that apply.
+- The return contract: the shortest artifact the orchestrator can act on,
+  in the shape the Delegation table names.
+- For implementation work: the exact plan slice it owns and the boundary of
+  that slice.