Bootstrap vault
Canonical first-run entry point for any Sauce-shape vault hosting cowork. Interactively interviews the user, dynamically introspects installed blueprints + engagement-type registry, materializes per-engagement context dirs + nav-button table on Cowork.md, and emits a 7-section bootstrap report including inline audit-receipt. Phrasings = "bootstrap this vault", "set up cowork", "first-time cowork setup", "onboard this vault to cowork".From its SKILL.md
npx -y skills add willfell/sauce --skill bootstrap-vaultAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
25.8 KB, as published. Nobody here has run it
cowork:bootstrap-vault
The canonical first-run entry point for any Sauce-shape vault hosting cowork. Replaces the v0.30.0 binary vault_scope interview with a dynamic, blueprint-introspecting, engagement-aware flow. Interactively interviews the user one question at a time, probes MCP backends, introspects the engagement-type registry + each installed blueprint's bootstrap_contributions[], materializes per-engagement context directories, renders an engagement × cadence nav-button table on Cowork.md, and emits a 7-section bootstrap report with an inline audit receipt. Runs serially (no parallel sub-skill dispatch from this orchestrator body). Idempotent on re-bootstrap via additive-merge semantics — never clobbers existing engagement context files.
Inputs
{
resume_from_step?: number, // re-bootstrap continues mid-flow if interrupted
debug_log?: boolean // emit per-step Notices for tracing
}
If resume_from_step is set, skip steps < resume_from_step and pick up from there (caller is responsible for supplying any state the resumed step needs).
Pre-flight
-
Use Skill
cowork:check-vault-routingwith{ required: ["obsidian"], bootstrapped_required: false }. (NEW input argbootstrapped_required— bootstrap-vault is the ONE skill that runs against an unbootstrapped vault.) If the return is not"ready", emit the following Notice and exit:cowork:bootstrap-vault aborted -- obsidian MCP unavailable -
Use Skill
cowork:date-contextwith{}. Capturecontext. Ifcontext.errorexists, emit Notice and exit. -
Read
<vault>/ranch/platform-installed.jsonviamcp__obsidian__read_note. If the cowork blueprint is NOT in theblueprints[]array, emit Noticecowork not installed in this vault; add cowork to subscription then run "sauce update" firstand exit. -
Check for prior bootstrap state via
mcp__obsidian__get_notes_infoon<vault>/spice/cowork/context/vault-config.md.- Absent: fresh bootstrap — continue to step 5 with
prior_state = "fresh". - Present: read frontmatter via
mcp__obsidian__get_frontmatter. Parse:-
engagements[]present + non-empty:prior_state = "re-bootstrap". Captureexisting_engagements. Continue with additive-merge semantics per §3-bis of the design doc. -
vault_scopepresent +engagements[]absent: v0.30.0 legacy state. Emit the following Notice verbatim:cowork:bootstrap-vault aborted -- detected v0.30.0 vault_scope schema. Migrator not shipped in v0.31.0 (planned for v0.31.x). To proceed now: remove the vault_scope frontmatter from vault-config.md (or delete the file entirely) and re-run bootstrap to perform a fresh interview. Your existing context/*.md files will not be touched.Exit without writing.
-
Neither present: schema-invalid file. Ask user
vault-config.md exists but doesn't match expected shape; replace? (yes/no).no→ exit.yes→prior_state = "fresh", continue.
-
- Absent: fresh bootstrap — continue to step 5 with
-
Check for prior bootstrap report at
<vault>/spice/cowork/bootstrap-report.md. If present, do NOT prompt yet — additive-merge re-runs idempotently replace it. (v0.30.0's prompt-to-replace removed in v0.31.0.)
Discover (MCP probing — no user interaction)
-
Probe each known MCP backend with one lightweight read; capture
mcp_map:- gmail:
mcp__claude_ai_Gmail__list_labels— success →"connected", error →"missing" - google-calendar:
mcp__claude_ai_Google_Calendar__list_calendars— same coding - brex:
mcp__claude_ai_Brex__get_user_myself— same coding - imessage: no MCP available yet, mark
"unavailable"unconditionally - obsidian: from step 1, always
"connected"here
On any backend missing, emit the exact Notice:
cowork:bootstrap-vault -- <backend> MCP missing; will mark engagement-scoped questions for that backend as skip - gmail:
6.bis. Auto-detect connected MCPs (NEW v0.96.0). Before any engagement interview runs (and before context-builder is later invoked per-engagement), enumerate the agent's tool list and call classifyConnectedKinds({ reachable_namespaces, tools_by_namespace, vault_root }) from helpers/kind-classifier-helper.js. Walk every mcp__<ns>__<tool> tool name in your current tool inventory; build reachable_namespaces[] (deduped) and tools_by_namespace = { <ns>: [<tool_short_name>, ...] }. The helper consults spice/cowork/data/kind-patterns.json for deterministic namespace + tool-name glob matching and persists per-namespace results in spice/cowork/data/kind-classifier-cache.json keyed by classifier_version. Capture result shape { classified, unclassified, new_since_last_fire, cache_hits } as classifier_result. Pass classifier_result INTO context-builder as input so its Section 0 (auto-fill) can pre-populate the per-MCP interview from the classification. Classifier failures are non-fatal — on any throw, set classifier_result = { classified: [], unclassified: [], new_since_last_fire: [], cache_hits: 0 } and continue. The final bootstrap report (step 24) shows the auto-detection result (in §1) + the user's overrides (in §2) for transparency.
-
Capture
blueprints_installed = []from theblueprints[]array of platform-installed.json read in step 3. -
Load engagement-type registry from materialized path. List
<vault>/spice/cowork/context/engagement-types/*.jsonviamcp__obsidian__list_files_in_dir. If the dir is not found (the registry is materialized at install time; an absent dir means the vault has not been installed against a v0.83.0+ workshop), emit Noticecowork:bootstrap-vault aborted -- spice/cowork/context/engagement-types/ not found; ensure sauce update --bump-pins ran against v0.83.0+ workshopand exit. If the dir is empty, emit Noticecowork:bootstrap-vault aborted -- spice/cowork/context/engagement-types/ is empty; ensure sauce update --bump-pins ran against v0.83.0+ workshopand exit. For each.jsonfile, Read + parse; key byid. Captureengagement_types_registry = { <id>: <manifest>, ... }. -
NEW — Load blueprint bootstrap_contributions:
- For each blueprint in
blueprints_installed:- Read its
manifest.jsonfrom the workshop tree. - If
bootstrap_contributions[]field is present + non-empty, accumulate intocontributions_registry = { <blueprint>: [...], ... }. - Absent or empty → passive blueprint, skip.
- Read its
- For each blueprint in
-
Probe vault surface via
mcp__obsidian__list_directoryatspice/. For each<module>dir present, shallowlist_directoryto count entries. Capturevault_surface = { <module>_count, ... }. (Historically this step also asserted a[//]: # (COWORK_CALLOUTS)anchor in the daily template — a vestigial precondition from the v0.45.0 callout-patching surface that v0.65.0's atomic-note write contract retired. Orchestrators now write tospice/cowork/daily/.../YYYY-MM-DD/<slug>.mdand never patch the daily callout, so the anchor is no longer required; precondition removed in [email protected].)
Interview (interactive — one question at a time)
-
If
prior_state == "re-bootstrap", present existing engagements summary table and Ask user:Found N existing engagement(s): <list of id (type) label>. What would you like to do? (a) Add a new engagement (existing untouched) (b) Update an existing engagement's fields (c) Drop an engagement (requires confirmation) (d) Re-run full interview (existing replaced)Capture
re_bootstrap_mode. Drop mode (c) requires per-engagement confirmationDrop engagement '<id>'? This deletes vault-config.md entry only; context dir spice/cowork/context/<id>/ stays untouched. (yes/no).For fresh state (
prior_state == "fresh"), skip step 11; flow directly to step 12. -
Ask user:
How many engagements does this vault host? (1, 2, 3, or "exploring" — add one for now with type=personal-exploring placeholder). Captureengagement_count. -
Per-engagement interview loop. For each new engagement E (count from step 12, OR the single engagement being updated/added in re-bootstrap modes):
-
13a. Ask
Engagement ID (lowercase-hyphens, e.g., "accuris", "ero-acme", "personal"). Must be vault-unique.Validate against^[a-z][a-z0-9-]+$and uniqueness against existing engagements. Re-ask on failure. -
13b. Ask
Engagement type? Options: <list keys of engagement_types_registry, with labels>. Validate againstengagement_types_registry. Re-ask on failure. CaptureE.type. -
13c. Compute the field set for E:
fields = engagement_types_registry[E.type].required_fields + engagement_types_registry[E.type].optional_fields + ⋃ {contributions_registry[B].engagement_field_offer : E.type ∈ that offer's consumed_by_types}Required fields ask without blank-allowed (re-ask on blank). Optional fields ask with blank-allowed (default applies per the offer's
default_valueif any; flag asUSING DEFAULTfor report §5). -
13d. For each MCP backend marked
connectedinmcp_map, ask the engagement-scoped MCP question — but ONLY if the engagement type'srender_aspectsreferences that backend (or a blueprint'sengagement_field_offerdoes). E.g., gmail:Which gmail label/account does engagement '<id>' use?. Skip backends whoserender_aspectsare all"skip"for this type. -
13e. Cadence overrides: present
engagement_types_registry[E.type].default_cadences. Ask userOverride any cadences for engagement '<id>'? (yes/no). If yes, walk cadences one at a time and capture overrides. -
13f. Anti-echo opt-in (v0.95.1 Y/N1 — Knobs 1 + 2 BUNDLED). Ask user:
Enable anti-echo memory-drift detection for engagement '<id>'? Adds a 'outside yesterday's frame' callout per daily atomic note AND flags stuck frames across days. (default: no)Idempotent re-bootstrap default: if
existing_engagements[E.id].overrides.render_aspects.anti_echo == "include"ANDexisting_engagements[E.id].overrides.tripwire_aspectsalready includes"frame_drift", the question defaults toY(current-state Y); otherwise defaults toN. Blank input accepts the default.- On Y: stage TWO writes to
E.overrides(do NOT touch bundle defaults — overrides are a sparse layer):E.overrides.render_aspects.anti_echo: "include"E.overrides.tripwire_aspects: [...engagement_types_registry[E.type].tripwire_aspects, "frame_drift"](REPLACE-semantics array; copy the engagement-type's bundle defaults then append"frame_drift"; do not duplicate if already present)
- On N: write NOTHING — leave
E.overridesuntouched so the engagement inherits the engagement-type's bundle defaults verbatim at runtime (render_aspects.anti_echo: "skip"; tripwire_aspects: bundle's default array). The opt-in-everywhere posture (design § 2.5) means default-N preserves pre-v0.95.1 behavior for every engagement.
Power-user case (Knob 1 only, no Knob 2): documented in the bootstrap-report §5 and About-Cowork prose — user manually edits
vault-config.mdengagements[].overridespost-bootstrap to setrender_aspects.anti_echo: "include"without also adding"frame_drift"totripwire_aspects. - On Y: stage TWO writes to
-
13g. Lens-shift opt-in (v0.95.1 Y/N2 — Knob 3 SEPARATE). Ask user:
Enable weekly cold-perspective morning briefing for engagement '<id>'? Fires a memory-skip MB on Saturday mornings (default 07:00), paired with that day's warm MB on the Daily Hub for empirical anti-echo. (default: no)Idempotent re-bootstrap default: if
existing_engagements[E.id].cadences.lens_shiftis currently set (any cron value), the question defaults toY; otherwise defaults toN. Blank input accepts the default. (Rationale for the split from Y/N1: Knob 3 doubles MB cost weekly + produces a visible second atomic note — operationally distinct from Knobs 1+2's per-note callout additions, worth its own explicit consent per design § 6.5.)- On Y: stage ONE write to
E.cadences:E.cadences.lens_shift: { cron: "0 7 * * 6" }(canonical default — Saturday 07:00)
- On N: write NOTHING — no
lens_shiftentry appears inE.cadences. The default warm-MB cadence on Saturday (governed bydefault_cadences.morning) is unaffected by this answer; only the cold-MB companion is gated bylens_shiftopt-in.
- On Y: stage ONE write to
-
13h. Preference-learning opt-in (v0.96.0 Y/N3 — Rail L). Ask user:
Enable preference learning for this engagement? Adds a 'Was today useful?' rating callout to every atomic note; per-kind weights update nightly from your ticks. Atomic-note quality should improve over 1-2 weeks. (default: yes)Idempotent re-bootstrap default: if
existing_engagements[E.id].learning_enabled === false, the question defaults toN; otherwise (unset ORtrue) defaults toY. Blank input accepts the default.- On Y: stage ONE write to
E(top-level engagement record key, not insideoverrides):E.learning_enabled: true- No installer change for
learned_weights— lazy-initialized bycowork:learn-from-checkson first post-upgrade fire (per S0.5 mitigation).
- On N: stage ONE write to
E:E.learning_enabled: false— composeBody never emits the rating callout;cowork:learn-from-checksskips this engagement.
- On Y: stage ONE write to
-
13i. Capture engagement E as a full record (id, type, type_schema_version, label, captured field map, cadences, overrides, learning_enabled).
-
-
Vault-scoped questions (from
contributions_registrywherevault_questionkind exists): ask once per vault, not per engagement. Capture into the vault-wide substitution map. -
Ask
Where should I drop the cron-job SKILL.md bodies? Options: (a) print in bootstrap-report only [default]; (b) print AND copy to <vault>/.scratch/cron-bodies/ for easy paste. Capturecron_drop_mode.
Compose (write files)
-
Accumulate substitution maps:
- Vault-wide: vault-question answers (step 14) + vault basename + today's date +
mcp_map. - Per engagement E:
E.id+E.type+ E's captured field map.
- Vault-wide: vault-question answers (step 14) + vault basename + today's date +
-
Write/update
<vault>/spice/cowork/context/vault-config.md:Frontmatter:
type: cowork-vault-config updated: <today> updated_by: cowork:bootstrap-vault cowork_version: 0.2.0 schema_version: 1 engagements: - id: <id> type: <type> type_schema_version: <from registry> label: <label> ...captured fields... cadences: morning: <bool> midday: <bool> eod: <bool> weekly: <bool> monthly: <bool> # v0.95.1 Knob 3 — present ONLY when user opted in to Y/N2 at step 13g: lens_shift: cron: "0 7 * * 6" # canonical default — Saturday 07:00 # v0.95.0 cowork-spine layered-preferences schema. Present ONLY when # user staged at least one override (e.g., Y/N1 anti-echo opt-in at # step 13f). Sparse — only keys the user overrode appear; everything # else inherits the engagement-type's bundle defaults at runtime. # v0.95.1 Y/N1-driven shape (when user answered Y): overrides: render_aspects: anti_echo: "include" # Knob 1 tripwire_aspects: # Knob 2 — REPLACES bundle array (per overrides schema) - <each entry from engagement_types_registry[E.type].tripwire_aspects> - "frame_drift" - ... mcp_map: gmail: connected | missing ...Body: human-readable per-engagement summary block + MCP map block. Re-bootstrap modes: preserve any non-managed body content via patch-merge (use
mcp__obsidian__patch_noteif a fresh write would clobber; usemcp__obsidian__write_notefor fresh state). Theoverridesandcadences.lens_shiftkeys are managed-region content: bootstrap-vault re-writes them on every run, but never clobbers other body content. User edits tooverrides(e.g., Knob 1 power-user case addingrender_aspects.anti_echo: "include"WITHOUTframe_driftintripwire_aspects) survivesauce updatebecause the installer never touches this canonical path (<vault>/spice/cowork/context/vault-config.mdis bootstrap-vault-owned, NOT infiles[]). -
For each engagement E, ensure the directory
<vault>/spice/cowork/context/<E.id>/exists. Then for each template file inengagement-templates/<E.type>/:- Read the template body from the workshop tree.
- Substitute
{{<field>}}placeholders using E's substitution map. - Unresolved placeholders → leave intact + FLAG for report §5.
- Write to
<vault>/spice/cowork/context/<E.id>/<filename>.mdviamcp__obsidian__write_note. - Idempotence (re-bootstrap): if the target file already exists, do NOT clobber — instead write
<filename>.template.mdalongside so the user can diff + merge by hand.
Plus apply
context_file_offercontributions from blueprint manifests: each offer that targets engagement E (type match inconsumed_by_types) materializes its declared template into the engagement's context dir. -
Seed (or update) vault-wide files in
<vault>/spice/cowork/context/:active-threads.md— seed empty schema if absent; preserve if present.weekly-snapshot.md— seed empty schema if absent; preserve if present.README.md— overwrite fromengagement-shared-templates/README.md(read-only template source).obsidian-vault-guide.md— overwrite from template source.
-
Render the nav-button table on
<vault>/spice/cowork/Cowork.md:- Header section with a
[!warning]callout that auto-suppresses (dataviewjs guard:if (vault-config.md exists && engagements[].length > 0) hide). - Static markdown table: rows = engagements, columns = supported cadences (union across all engagements).
- Each cell = nav-button using
invoke_commandaction with{ command_id: "cowork:<orchestrator-id>", args: { engagement_id: "<id>" } }(requires [email protected]argspassthrough — N1). - Below the table: dataviewjs block reading recent daily notes for engagement-tagged H2 callouts; surfaces a "Last run" timestamp column per (engagement, cadence) pair.
- Header section with a
-
Write
<vault>/.claude/cowork-routing.md(N3 resolution): NL routing cheat-sheet listing phrasings → skill IDs + engagement-id disambiguation rules. One section per engagement with engagement-aware phrasing examples. -
Compose cron paste-blocks per (engagement, cadence) pair from the recommended-schedule table in design §3-sexies. If
cron_drop_mode == "b", also write each block to<vault>/.scratch/cron-bodies/<engagement>-<cadence>.md.
Audit
-
NEW — Run audit inline via
Use Skill cowork:run-audit-receiptwith{ vault_path: <vault>, workshop_path: <workshop> }. The sub-skill wrapsnode platform/cli/sauce-cli.js audit --vault <vault> --only cowork --format jsonvia Bash, parses the JSON, and returns{ status, summary, receipt_lines, raw_violations }. Captureaudit_receipt. Embedreceipt_linesverbatim into report §6.Alternative if Bash dispatch is unavailable in skill context (sub-skill returns
status: "unavailable"): emit a placeholder + run-this-yourself instruction into §6 (degraded mode). Bootstrap continues either way — bootstrap-vault's job is to MATERIALIZE state; the audit surfaces any post-write drift but does not gate completion.
Report
-
Compose the bootstrap report (7 sections per design §3-octies) and write to
<vault>/spice/cowork/bootstrap-report.mdviamcp__obsidian__write_notewith frontmatter:type: cowork-bootstrap-report generated: <today> generated_by: cowork:bootstrap-vault cowork_version: 0.2.0 prior_state: fresh | re-bootstrap engagement_count: <N> engagements_summary: [<id (type)>, ...] audit_receipt: pass | fail | warnSections:
- §1 What I discovered —
mcp_mapas a table,vault_surfacestats as a list, blueprints installed, daily-template marker presence (always confirmed by step 10 or we would have exited). v0.96.0 NEW: append aKind classifier resultssubsection listingclassifier_result.classified(one row per detected namespace → kind),classifier_result.unclassified(namespaces the deterministic classifier could not place; user resolved during per-engagement context-builder runs or skipped), andclassifier_result.new_since_last_fire(namespaces detected for the first time this run — surfaced aspending_confirmations[]to downstream cadences via plan-dispatch). - §2 Engagements — per-engagement subsection (id, type, label, captured fields, cadences).
- §3 Cron jobs — per-engagement table with columns
cadence | schedule | job-name | SKILL.md bodypopulated from step 22. - §4 Skipped — per-(engagement, cadence) one-liner with reason: missing MCP / engagement-type opt-out / user override.
- §5 Unresolved fields — per engagement, list every
{{...}}placeholder still unresolved AND everyUSING DEFAULTflag, with the exactranch/platform-config.jsonvariableskey the user should populate. - §6 Audit receipt — verbatim
receipt_linesfrom step 23 (or the degraded-mode instruction if Bash was unavailable). - §7 Manual Obsidian + natural-language parity — pointer to
spice/cowork/Cowork.md(nav-button table) + NL phrasing examples (drawn from.claude/cowork-routing.mdwritten in step 21) + scheduled cron pointer to §3.
- §1 What I discovered —
-
Use Skill
cowork:scaffold-timeframeswith{}. Capture the receipt astimeframe_scaffold. Include it in the final bootstrap report under "Timeframe scaffold" heading: listcreated+existed+missing_promptsarrays. -
(Bootstrap-only) Emit stub finance snapshot. First-run readiness aid: write a one-line stub
cowork-finance-snapshotso the CoworkReadiness panel can render "last runs" rows with at least one entry before any scheduled job has fired. Use Skillcowork:write-run-note-financewith{ engagement: bootstrapped_engagement, date: <today YYYY-MM-DD>, weekday: <today dddd>, month_name: <today MMMM>, body: "(stub finance snapshot emitted by cowork:bootstrap-vault — replace with first real run)", prompt_source: null, warning: "bootstrap_stub" }. Best-effort: log status; do not fail the bootstrap if the write fails.
Done
- Emit final Notice:
Bootstrap complete (<engagement_count> engagement(s)). Open spice/cowork/bootstrap-report.md for next steps.This orchestrator never patches the daily note and never mutatesactive-threads.mdorweekly-snapshot.mdbeyond the empty-schema seed in step 19. Cadenced state writes are owned by the cron-scheduled orchestrators.
Dependencies
This orchestrator depends on:
cowork:check-vault-routing(extended in S2 withbootstrapped_requiredinput)cowork:date-context(UNCHANGED from v0.30.0)cowork:run-audit-receipt(NEW sub-skill in S2 — wraps audit CLI invocation)
This orchestrator writes to (or seeds):
<vault>/spice/cowork/context/vault-config.md(canonical engagement record)<vault>/spice/cowork/context/<engagement-id>/<file>.md(per-engagement materialization)<vault>/spice/cowork/context/active-threads.md(seed empty)<vault>/spice/cowork/context/weekly-snapshot.md(seed empty)<vault>/spice/cowork/context/README.md(overwrite from template)<vault>/spice/cowork/context/obsidian-vault-guide.md(overwrite from template)<vault>/spice/cowork/Cowork.md(nav-button table + dataviewjs last-run block)<vault>/.claude/cowork-routing.md(NL routing cheat-sheet)<vault>/spice/cowork/bootstrap-report.md(7-section report)
This orchestrator does NOT write to:
<vault>/ranch/platform-installed.json(installer-owned)<vault>/ranch/platform-config.json(user-owned; bootstrap only READS placeholders for the report)<vault>/.obsidian/*(per landmine #12 allowlist; bootstrap-vault touches NONE of the allowlisted paths)<vault>/ranch/templates/Daily Note.md(daily blueprint owns)
Error modes
| Mode | Behavior |
|---|---|
obsidian MCP missing | Step 1 exits cleanly with Notice. No state written. |
platform-installed.json lacks cowork | Step 3 exits cleanly with Notice. |
| v0.30.0 legacy state detected | Step 4 exits cleanly with the detailed Notice. No state mutated. |
| User-supplied invalid engagement ID | Step 13a re-asks until valid. |
| User-supplied unregistered engagement type | Step 13b re-asks until valid. |
| Required field left blank | Step 13c re-asks (required fields cannot default). |
| Audit (step 23) returns FAIL | Report §6 surfaces the failure verbatim; bootstrap continues — bootstrap-vault's job is to MATERIALIZE state; if audit detects post-write drift, the report makes it visible. User runs corrective action. |
| Existing context file conflict in re-bootstrap | Step 18 writes alongside (.template.md); never clobbers. |
Outputs
Structured report frontmatter (per step 24) written to <vault>/spice/cowork/bootstrap-report.md. Final Notice (per step 25) confirms completion + engagement count.
Reference
Canonical spec: Docs/plans/2026-05-11-v0.31.0-bootstrap-vault-skill-spec.md (spec-locked 2026-05-11). Architectural decisions: Docs/plans/2026-05-11-v0.31.0-cowork-engagement-model-design.md (§3-bis through §3-novies). Cycle plan: Docs/plans/2026-05-11-v0.31.0-cowork-engagement-model-plan.md (S3).