setup-kb-infra

name	setup-kb-infra
description	Materialize and reconcile Knowledge Bank Infrastructure on this machine. Connect the KB provider, collect bindings, install the lookup and capture skills, and bootstrap the automations — on first run and on every later run. Use when the user runs /setup-kb-infra, says bootstrap/install/wire up kb-infra, or asks to update, sync, reconcile, or health-check the setup.

Setup

Purpose

Setup materializes the spec into a working setup on this machine and keeps it in sync over time. It is a reconcile, not a one-shot installer: it reads the desired state from the spec (the source of record), reads the actual materialized state, and closes the gap. The first run reconciles from nothing; every later run reconciles from whatever already exists. It writes only gitignored local/ bindings and the user's own harness config; it never commits a personal value.

This mirrors the plan/apply model behind ADR 0001's Terraform analogy: compute the drift, show it, then apply only the delta.

Branches

• all (default): full reconcile — plan, then apply across every element.
• check: read-only health check — report drift and stop; change nothing.
• scoped: reconcile one element — provider, bindings, skills, or a named automation.

Run the full reconcile unless the user scopes it. Later steps assume earlier bindings exist; if a scoped run needs a missing binding, collect it first. Every step is idempotent: touch only what is missing, changed, or newly added, and leave correct state alone.

Workflow

1. Plan: diff desired against actual

Compare the spec (desired) with the materialized state (actual) and produce a drift report before changing anything:

• Version: read the current spec version from the git tags (git describe --tags); vX.Y.Z tags are the source of truth. Compare it against the version recorded in local/installed.yml to see how far the installed setup has fallen behind.
• Desired: the endpoint, sink, source, sink-capability, and source-capability vocabulary in _preamble.md, the endpoints, sinks, and sources plus their capabilities each enabled automation declares, the skills under skills/, the automations and provider-agnostic execution profiles under docs/automations/, one harness-owned automation-local state file or equivalent state handle, and one cadence plus one concrete local model/reasoning selection per enabled automation.
• Actual: local/bindings.yml (a key present with a blank or placeholder value is not a binding), local/installed.yml, the snapshotted prompts under local/automations/, each automation's resolved harness-owned state, the live harness automation configuration, and the installed skill copies.
• Drive the endpoint, sink, and source checks from the desired set — the endpoints, sinks, and sources each enabled automation declares — not from whatever keys happen to be in bindings.yml. For each declared endpoint, probe that it resolves to a concrete KB owner; a present key is not proof of a binding.
• Drift to surface, by category:
  • the spec version has advanced past the installed version;
  • an endpoint an enabled automation declares does not resolve to a concrete KB owner: its bindings.yml entry is absent, blank, or still a placeholder (for example a TODO/FIXME hint), or its hint points at a page that no longer resolves live. Verify by resolution, not by key presence;
  • a sink an enabled automation targets is unbound, disabled-yet-needed, or unreachable;
  • a sink capability an enabled automation declares is absent, blank, or does not resolve to a concrete executable command or native workflow instruction;
  • a source an enabled automation declares is unbound or unreachable; a best-effort source (for example a <social-profile-source> platform) may be intentionally blank, which is a skip, not a gap;
  • a source capability an enabled automation declares is absent, blank, or does not resolve to a concrete read command or native workflow instruction;
  • bindings whose endpoint or sink is no longer in the spec (retired);
  • skills whose source differs from the installed copy (stale install) or is not installed;
  • automations new to the spec, or whose fresh compose differs from the snapshot in local/automations/, or removed from the spec;
  • an enabled automation whose harness-owned state location is missing or unreachable, lacks last_completed_at, or contains a nonblank value that is not an ISO 8601 timestamp;
  • cadences missing for an enabled automation, including a cadence that an automation declares as required prompt context;
  • a concrete model or reasoning effort missing for an enabled automation, unsupported by the current harness, or different across the local desired state, installed-state record, and live harness automation;
  • a newer supported model mapping that better matches an automation's declared execution profile; report this as an optimization proposal, not a silent upgrade of an otherwise valid explicit local choice.

In check mode, report this plan and stop.

Completion criterion: the user sees a categorized drift report and nothing has changed yet.

2. Connect the KB Provider

Confirm which provider backs this instance. Validate the connector by reading one real page. Record the provider and a start hint in local/bindings.yml if it is not already present and valid.

Completion criterion: a live read from the provider succeeded, or the exact connector blocker is reported.

3. Reconcile the Endpoint Bindings

Read the endpoint vocabulary from _preamble.md. Resolve every endpoint the plan flagged as unbound, ambiguous, or stale — including endpoints whose bindings.yml key exists but is blank, a placeholder, or does not resolve to a real page.

A binding value is a resolution hint — a KB location — or blank; never write status prose (for example UNBOUND: ...) into it, and never treat "resolve by meaning" as a resolution for an endpoint that currently resolves to no owner.

Blank is acceptable only when the endpoint genuinely resolves to a real owner by meaning. When it does not — a missing, ambiguous, or brand-new endpoint (for example a persona or published-context surface the user must create) — that is a hard gap, not an auto-resolvable one. Grill the user one question at a time, like grill-me, to close it: point it at an existing page, or decide together to create a new page and record where it lives. Do not move on by self-marking it unbound.

Only the user may leave a needed endpoint unresolved, as an explicit deferral; record that as their decision, not as a binding hint. If the run cannot grill because it is non-interactive, stop and report the unresolved endpoints as a blocker rather than fabricating a resolution. Leave already-valid bindings untouched. Propose removing bindings for retired endpoints; do not delete a personal value without confirmation.

Completion criterion: every endpoint an enabled automation needs resolves to a KB owner, or the user has explicitly deferred it; no needed endpoint is left as a self-authored "unbound" note, and retired bindings are resolved.

4. Reconcile the Sink, Source, and Capability Bindings

Read the sink and source vocabulary from the preamble. For each sink an enabled automation targets, confirm its link and local clone path, collecting only what the plan flagged as missing, disabled-yet-needed, or unreachable. For each source an enabled automation declares, collect its binding the same way — a <transcript-source> is a list of local locations; a <social-profile-source> is one public profile URL per platform (currently X and LinkedIn). A best-effort source platform may be left blank as an explicit skip, not a gap. Record them in local/bindings.yml.

For each sink or source capability an enabled automation declares, resolve the role to the bound implementation's executable command or native workflow instruction. Store it under that sink or source's capabilities map in local/bindings.yml. A generic automation must never hardcode one implementation's command in committed docs; the materialized capability line is where that concrete value belongs. A required blank capability is a hard gap: define it with the user, disable the dependent automation, or stop rather than inventing an operation. Source capability instructions must remain read-only even when the same external system is also bound as a writable sink.

Completion criterion: every sink an enabled automation needs has a binding or is marked disabled, every declared sink capability resolves to a concrete operation, every declared source is bound or explicitly left blank, and every declared source capability resolves to a concrete read operation.

5. Reconcile the Runtime Model Bindings

Read each enabled automation's provider-agnostic Execution profile from its source under docs/automations/. Inspect the harness's currently supported models and reasoning/delegation settings, then propose a concrete mapping in the plan:

• frontier selects the strongest available model for ambiguous, high-value work;
• balanced selects a strong everyday model with a better cost/capability tradeoff;
• efficient selects the fastest low-cost model that can reliably satisfy a narrow, repeatable contract;
• parallel selects a frontier model plus the harness's explicit multi-agent or delegation mode. If the harness has no such mode, report the degraded mapping and ask before substituting a single-agent setting.

Record the accepted concrete model and reasoning_effort for every enabled automation under models in local/bindings.yml. A recorded, supported concrete selection is the user's local choice: do not replace it merely because a newer model exists. Surface a newer profile-aligned mapping in the plan and change it only when the user accepts that optimization or explicitly asks for current recommendations. Never commit provider-specific model identifiers.

Completion criterion: every enabled automation has an accepted model and reasoning selection supported by the local harness, or the exact unsupported profile is reported as a blocker.

6. Reconcile the Installed Skills

Copy lookup, capture, and setup-kb-infra into the harness skill directory, re-copying only those whose source differs from the installed copy. Prefer ~/.agents/skills/<name>/ and ~/.claude/skills/<name>/, which together cover current harnesses. Use materialized copies, not symlinks or hard links.

Confirm the capture approval-draft styling on first run: the shipped default is a dark, Notion-style palette. Ask the user whether it works or whether they want it restyled, and record the choice in local/bindings.yml; do not re-ask once it is recorded.

Completion criterion: each skill's installed copy matches its source, and the draft-style choice is recorded.

7. Reconcile the Automations

For each enabled automation, compose a lean, self-contained paste-ready prompt — it is the running agent's entire world, since the run executes in the sink checkout with the spec not present (see ADR 0005). Compose into a new artifact; never edit the source automation file or the preamble under docs/ — those are read-only, reference surfaces by role, and must stay free of resolved bindings or any personal value. The composed prompt is the only place resolved bindings appear; write it only to local/automations/<name>.md and/or the harness, and start it with a generated-file banner that names its source (docs/automations/<name>.md) and marks it do-not-edit.

Compose these parts in order, and only these — never the full endpoint/sink catalog, the provider block, undeclared cadence context, or blank overrides:

1. The banner, then # <Name> and a one-line intro. When the automation's primary sink resolves to a repo clone, name that clone as the working directory and state the spec is not checked out there; when the sink is a tool or the KB (no clone), state only that the spec is not checked out and everything needed is in the prompt.
2. ## Local state: one resolved line naming this automation's harness-owned automation-local state path or equivalent state handle. When the harness exposes a file, inject its absolute path. State that last_completed_at follows the Operating Rules below. Never inject another automation's state location.
3. ## Operating rules: the preamble's Operating Rules, verbatim.
4. ## Context surfaces: one line per endpoint the automation declares, joining its role description from the preamble vocabulary with its resolved hint from local/bindings.yml. Omit the section when the automation declares no endpoints.
5. ## Sink / ## Sources: one resolved line per declared sink and source: the role description plus the clone path and repo, or the tool handle. Omit when none.
6. ## Sink capabilities: one resolved line per capability the automation declares, joining its role description from the preamble with the concrete command or workflow instruction under the bound sink's capabilities map. Omit when none are declared. Never inject undeclared capabilities.
7. ## Source capabilities: one resolved line per read capability the automation declares under its owning source, joining its role description from the preamble with the concrete command or native workflow instruction under that bound source's capabilities map. Omit when none are declared. Never inject undeclared capabilities, and never turn a source capability into write authority.
8. ## Coverage cadence: only when the automation declares Coverage cadence: required, emit its human-readable recurrence and timezone from the cadence binding, and state that the current run owns the window through the next scheduled run. Omit it otherwise; do not inject cadence merely because one exists.
9. Any convention the automation declares (for example KB Reconcile's follow-up marker policy) inlined as its own section, resolved from docs/knowledge-bank-conventions.md — never left as a path for the run to open.
10. The automation body from the source's ## Prompt block, appended verbatim.

Before composing, create a missing harness-owned state file from local/automation-state.example.yml, or initialize the equivalent property when the harness exposes structured state instead of a file. On every later reconcile, preserve its existing last_completed_at value. Never backfill a timestamp from an invocation, thread update, or run that lacks explicit completion evidence. Never point runtime state into the kb-infra checkout or a sink checkout; those are not runtime state providers.

Confirm the cadence, model, and reasoning bindings. Model selection is harness metadata: never inject the execution profile, concrete model, or reasoning effort into the composed prompt. Detect the harness: if it can create a scheduled automation from an agent, create or update it; otherwise output the paste-ready prompt and name where it goes. Update only automations the plan flagged as new, prompt-changed, cadence-drifted, or model-drifted, and offer to retire automations removed from the spec. After applying, snapshot each installed automation's composed prompt to local/automations/<name>.md and update local/installed.yml with the current spec version, timestamp, and per-automation cadence, concrete model, reasoning effort, and hash, so the next run can compute drift.

Completion criterion: every enabled automation is created, updated, or handed over as a paste-ready prompt with its target, cadence, model, and reasoning effort, and its resolved state location, while local/installed.yml plus the local/automations/ snapshots are current.

8. Report

Report the plan applied: what changed, every binding recorded or removed, every skill re-copied, every automation created, updated, retired, or handed over, and anything still unbound or drifted.

Completion criterion: the user can see the full state of the setup, what the reconcile changed, and the exact next manual action, if any.

State

• The spec version lives in the git vX.Y.Z tags, not in a committed file; read it with git describe --tags. scripts/bump-version.sh advances it from conventional commits.
• Record the installed state in gitignored local/installed.yml (spec version, timestamp, and per-automation cadence, concrete model, reasoning effort, and content hash) with the composed prompts snapshotted under local/automations/, per the preamble State Model. Use it only to compute drift; never store copied KB facts, answered grill questions, or anything beyond replaceable materialization state.
• Deleting the record must not make the next run less correct — only slower, by forcing a full re-materialize.
• Record runtime completion separately in harness-owned automation-local state for each enabled automation. Its only required property is last_completed_at. The automation updates it only under the shared Operating Rules; setup validates and preserves it but never infers completion.

Rules

• Write bindings only to gitignored local/. Never commit a personal value or a concrete sink- or source-capability command.
• Keep runtime completion state in the harness's automation state namespace; do not mix it into KB content, a sink work queue, or local/installed.yml. Never point runtime state into the kb-infra checkout.
• Never write a personal value into a committed spec file.
• Never write a provider-specific model identifier into the committed spec; committed automations declare provider-agnostic execution profiles only.
• The spec source is read-only. Setup reads docs/ and skills/ to compose prompts and never edits them; resolved bindings and other personal values live only in the materialized prompt (local/automations/ and the harness), never in the source.
• Be idempotent: a re-run with no spec change and healthy state makes no changes and grills nothing.
• Do not re-grill bindings that are already recorded and still resolve.
• A present binding key is not proof of a binding: treat a blank, placeholder, or non-resolving value as unbound, and drive the check from the endpoints and sinks the enabled automations declare.
• A binding value is a resolution hint or blank — never status prose. Never self-mark a needed endpoint unbound: resolving it by grilling, or an explicit user deferral, are the only outcomes.
• check mode is read-only: it plans and reports, and writes nothing.
• Retire, don't orphan: when an endpoint, sink, or automation leaves the spec, propose removing its materialized counterpart, but delete a personal value only with confirmation.
• Use bindings.example.yml as the shape for local/bindings.yml, and installed.example.yml as the shape for local/installed.yml. Use automation-state.example.yml as the shape for each automation's runtime-state file.
• The follow-up marker policy ships as a repo default; offer to override it into a binding, do not assume.
• Treat local/bindings.yml as replaceable: re-running setup rebuilds it from the live KB and the user's answers.