bearings 0.5.2 → 0.5.4

package/templates/initial-setup.md

@@ -0,0 +1,112 @@
+# Initial bearings Setup
+
+Complete or resume the first setup using the exact scope supplied by bearings.
+This is a direct setup recipe supplied by the CLI, not an installed command.
+The **bearings Commands for This Task** header is authoritative for resume and
+completion. Use its initiating executable instead of fetching another package
+version. If no header was supplied, use `npx bearings` as the command prefix.
+
+## 1. Read the Pending Work
+
+Read `.agents/bearings.json`, its `setupPending`, and the supplied setup scope,
+including listed file reconciliations and their backup, baseline, and incoming
+artifacts. Require `setupPending.kind: init`.
+
+- If no setup is pending, report that result and stop.
+- If the kind is `update` or `reconstruction`, use `/update-bearings-setup`.
+- If the journal or exact scope is missing, invalid, or inconsistent, report
+  the blocker and use `bearings init` to obtain the current handoff.
+
+The journal is durable state; read it without editing it. Work only on listed
+task targets and recorded reconciliations. Preserve `protectedSkills` and all
+skills outside the task scope. Read other repository files as evidence only.
+
+On resume, inspect current outputs and prior developer answers first. Keep
+completed tailoring and resolved content; continue only unfinished work.
+An interrupted session is not a reason to reinstall or restart the interview.
+Checkpoint each fully completed task through step 7. Reread the journal after
+each checkpoint and continue only its remaining tasks.
+
+## 2. Inspect, Then Ask
+
+Inspect the repository's purpose, code, configuration, existing knowledge,
+and command runners as needed for the listed tasks. Use evidence before
+asking. Ask one necessary project question at a time, with a recommended
+answer, only when the repository and prior answers cannot establish the fact.
+Cite paths for technical claims; keep uncertain intent explicit.
+
+## 3. Resolve Collisions
+
+For each listed collision, read the current target and recorded backup.
+Summarize the useful content and differences. Ask the developer whether to
+merge, keep parts, keep either version, or discard backed-up content. Apply
+only that choice, preserving existing project decisions. A recorded
+reconciliation permits the chosen target edit regardless of owner.
+
+For map targets, pass the choice and evidence to `/refresh-repo-map` in step 5;
+that command is their only writer. A map reconciliation without an explicit
+map task is blocked: report the scope mismatch rather than widen the scope.
+Keep reconciliation artifacts until the completion CLI accepts the outcome.
+
+## 4. Tailor Listed Seeds, Indexes, and Starter Skills
+
+Process only listed seed, index, and starter paths: `reason: tailor` tasks, or
+their recorded `reason: reconcile` tasks after the collision choice is applied:
+
+- **Agent seed:** fill the listed seed's project name, purpose, and stack
+  from evidence. Keep `AGENTS.md` a thin router, without a skill registry or
+  an always-on rules block.
+  Remove a legacy `## Setup Required` blocking section. Also remove any obsolete
+  `## Pending bearings Setup` section before checkpointing the seed.
+- **Indexes:** retain existing entries; fill listed index placeholders from
+  existing records. Use an explicit empty state when there are no records.
+  Setup does not itself approve new decisions or deferred work.
+- **Starter skills:** make light project-specific changes to the listed
+  skills. Replace handoff markers with real commands or explicit
+  `not configured`; preserve each skill's safety workflow.
+
+Leave finished content intact. Do not adapt every installed skill or edit
+unchanged custom skills to address unrelated verification warnings.
+Ownership, hashes, template lineage, baselines, and exposure copies belong
+to the CLI; edit only the scoped live content.
+
+## 5. Refresh Only Listed Maps
+
+Pass the exact `reason: map` target paths to `/refresh-repo-map` as an explicit
+setup target scope, with any collision choices. First setup lists all four map
+artifacts, including `docs/diagrams/c4-component.puml`. Refresh only those
+paths; a single map task is not a whole-map refresh. Preserve each selected
+artifact's contracts, sync-marker rules, and routing probes.
+
+## 6. Report the Checklist Opener
+
+Reuse and report an existing equivalent runner that 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 or open the previewer during setup.
+
+## 7. Complete Through the CLI
+
+Review each completed task and reconciliation against its required output and
+the developer's choices. Use the header's **Complete** command from the
+repository and append `--setup-path <path...>` with only the fully completed
+paths, quoted as shell arguments. This durably checkpoints their content and
+choices so resume will not repeat them. Reread the journal after each success.
+
+Without a supplied header, the checkpoint form is
+`npx bearings init --complete-setup --setup-path <path...>`, using the
+established local bearings invocation when applicable. Omitting `--setup-path`
+completes all remaining tasks; use that form only when all their outputs and
+choices are ready. A successful partial checkpoint is not whole-setup completion.
+
+The CLI validates scoped completion and owns manifest updates, skill claims,
+baseline and copy reconciliation, and artifact cleanup. Never clear
+`setupPending`, remove reconciliation records, or rewrite bookkeeping by hand.
+Neither a successful agent session nor `bearings verify` alone proves setup
+complete.
+
+If validation fails, retain progress and report **setup pending**, the exact
+blocked paths, and the next action. Fix only in-scope content problems;
+unrelated warnings do not expand the task scope. Report completion only after
+the completion CLI succeeds and the journal confirms no pending setup.
+Finish with changed paths, validation result, and the checklist opener.