| name | init-vault |
| description | Scaffold a new Obsidian vault with the canonical layout — WORKSTATE, ARCHITECTURE, CHANGELOG, README, CLAUDE.md, per-folder READMEs — so the living-docs auto-update hook can maintain it. Invoke when user says "init a new vault", "create a vault", "scaffold a vault", "new Obsidian vault", or similar. |
Scaffold a new Obsidian vault at ~/Agents/Workspaces/<parent>/<VaultName>/ with the canonical layout used across based-stack vaults (LanguageAcademy, OrchestratedOncology, PortfolioV2, etc.). The resulting vault is compatible with the living-docs-auto-update hook, so WORKSTATE/ARCHITECTURE/CHANGELOG auto-maintain going forward.
What the user should confirm before you start
Ask (one question at a time, multiple-choice preferred):
- Vault name — short,
CamelCase if a per-project vault, plain word if topical.
- Vault type — one of:
- Per-project (like LanguageAcademy) — full
projects/{product, marketing, seo, geo, strategy}/, notes/, reference/, Resources/ layout. Best for a single product or business initiative with a sibling code repo.
- Knowledge / research —
notes/, reference/{books, frameworks, research}/, optional projects/ for investigations. Best for focused research or a subject-matter vault.
- Topical personal (like Main) — user-defined category folders. Best when the vault hosts many unrelated workstreams.
- Second brain / PKM — PARA (
00 Inbox/, 01 Projects/, 02 Areas/, 03 Resources/, 04 Archive/) + Daily/ + MOCs/. The popular BASB + LYT hybrid seen in "my Obsidian setup" threads on X. Best for personal knowledge management, journaling, and capture-heavy workflows. Ships more starter content than the other variants so a fresh clone is usable on day one.
- Location — under
~/Agents/Workspaces/Development/ (per-project default) or ~/Agents/Workspaces/ directly (topical default). Allow override.
- Paired code repo? — if per-project, ask whether there's a sibling at
~/dev/<slug>/. If yes, note it in the vault's CLAUDE.md + WORKSTATE for cross-referencing.
- Git init? — default yes. Private repo on the user's GitHub under
sachio222 naming pattern <slug>-vault. Confirm with user before creating/pushing.
The canonical layout you create
<VaultName>/
├── .obsidian/ # empty — Obsidian populates on first open
├── README.md # orientation for humans/LLMs
├── CLAUDE.md # first-read for new Claude sessions
├── ARCHITECTURE.md # vault structure + conventions
├── DESIGN.md # design system index (omit for topical vaults)
├── CHANGELOG.md # dated work log, newest first
├── WORKSTATE.md # Now / Next / Blocked / Recently shipped — LIVING DOC
├── <VaultName>.md # landing card / seed note
├── skills-index.md # which skills apply to which workstream (per-project only)
│
├── notes/ # fast-moving thinking
│ ├── README.md
│ ├── daily/
│ ├── inbox/
│ ├── ideas/
│ ├── meetings/
│ └── plans/
│
├── projects/ # per-project only — active workstreams
│ ├── README.md
│ ├── product/README.md
│ ├── marketing/README.md
│ ├── seo/README.md
│ ├── geo/README.md
│ └── strategy/README.md
│
├── reference/ # slow-moving canonical knowledge
│ ├── README.md
│ ├── books/
│ ├── frameworks/
│ └── research/
│
└── Resources/ # per-project only — produced assets
├── README.md
├── Brand/
└── Marketing/
Topical vaults skip projects/, Resources/, and DESIGN.md; they use user-named category folders instead (e.g., Creative/, Development/, Gaming/, Hardware/, System/, Writing/).
Knowledge vaults skip projects/ and Resources/; keep reference/ as the hub.
Second-brain / PKM vaults replace the projects/ notes/ reference/ trio with a PARA-based layout — see the dedicated section below.
Second-brain / PKM layout
The layout below is the PARA + Daily Notes + MOCs hybrid popular in Obsidian X/Twitter threads. Actionability decreases left-to-right across the PARA folders: Projects (active with a deadline) → Areas (ongoing responsibility) → Resources (topic reference) → Archive (inactive). Daily Notes handle capture, MOCs handle navigation, 00 Inbox/ holds fleeting captures until the weekly review.
<VaultName>/
├── .obsidian/ # empty — Obsidian populates on first open
├── README.md
├── CLAUDE.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── WORKSTATE.md
├── <VaultName>.md # home dashboard MOC
│
├── 00 Inbox/ # fleeting captures — process weekly
│ └── README.md
├── 01 Projects/ # PARA P — active, with a deadline
│ └── README.md
├── 02 Areas/ # PARA A — ongoing responsibility
│ └── README.md
├── 03 Resources/ # PARA R — topic-based reference
│ └── README.md
├── 04 Archive/ # PARA A — completed / inactive
│ └── README.md
│
├── Daily/ # YYYY-MM-DD daily notes
│ └── README.md
├── MOCs/ # Maps of Content — curated entry points
│ ├── README.md
│ └── Home.md
└── Attachments/
└── README.md
Conceptual sources (all mainstream in Obsidian PKM circles on X):
- PARA — Tiago Forte's Building A Second Brain. File by actionability, not topic.
- Daily Notes — universal capture layer; one dated note per day.
- MOCs — Nick Milo's Linking Your Thinking. Notes-of-links as curated entry points, used when a subject accumulates 5+ notes.
- Inbox — Getting-Things-Done legacy; weekly review routes captures into the right PARA folder or trash.
Numbering. The 00 / 01 / 02 / 03 / 04 prefixes are an Obsidian-on-X convention that keeps PARA folders top-of-tree in stable sort order. Non-PARA utility folders (Daily/, MOCs/, Attachments/) sit below without prefixes so they read as distinct from the PARA system.
Shareability goal. This variant ships more starter content than the others — a pre-populated home MOC, PARA-folder READMEs with filing rules, a Home.md MOC, and a CLAUDE.md that describes the capture → file → archive workflow. A fresh clone is usable on day one without the new owner having to design anything.
Topical-vault software/tools documentation pattern
Topical vaults commonly accumulate software-install / tools docs (media players, photo viewers, DAWs, editors, backups, etc.). Two conventions that travel together.
1. Consume vs. produce split. When a topical vault hosts software docs, split them along a clear axis:
- Consume / system (suggested folder:
System/) — apps for using or administering: media players, photo/image viewers, file managers, backups, remote access, security tools, specs. Example docs: Media-Players.md, Photo-Viewers.md, File-Managers.md, Video-Libraries.md.
- Produce / create (suggested folder:
Creative/) — apps for making: photo editors, audio/DAW tools, video editors, drawing/graphics, animation, product design, writing. Example docs: Photo-Tools.md, Music-Audio-Tools.md, Video-Tools.md, Drawing-Graphics-Tools.md, Animation-Tools.md, Writing-Tools.md.
Each doc cross-links its counterpart (e.g., a "Media Players" doc points to "Music-Audio Tools" for DAWs; a "Photo Viewers" doc points to "Photo Tools" for RAW editors). When the user asks for a "[domain] tools" doc, first pick the axis — is this for consuming or producing? — and place it in the matching folder.
Do not pre-create System/ or Creative/ during init; let the user name their own top-level folders. Apply the axis only when populating docs.
2. Six-part install-guide template. Every software/tools doc inside a topical vault follows this layout:
- System-context header — one-line machine/OS summary + any specs-driven caveats ("Cycles CPU only", "iGPU bottleneck", "Wayland only", etc.).
- "Install most at once" bulk-install block — grouped install lines: official repos first (
pacman/apt/brew), then AUR/community (yay/paru), then Flatpak / upstream binary last. Lets the user paste and install the whole category at once.
- Claude integrations summary table — placed near the top, before per-tool sections. Columns: Tool · Integration type · Link. Mark widely-used integrations with ★ and flag official-from-vendor MCPs separately from community ones. Explicitly note which tools have no integration ("Nothing reputable found for X, Y, Z").
- Per-tool sections — each tool gets
### Name, a short description (what it's best for, who it's aimed at), bulleted links (Site, Docs, GitHub, Claude integration: if any), then the install snippet.
- Verify-installs block at the end:
for p in pkg1 pkg2 pkg3; do pacman -Q "$p" 2>/dev/null || echo "$p: not installed"; done
- Cross-references use Obsidian wiki-links —
[[Note#Heading]] for section targets, [[Note#Heading|display]] inline. Mark cross-domain references with ↪ when a tool's "home" section lives in another doc.
3. Consumer-doc variant (consume-side docs). When a doc is about consuming (players, viewers, library managers), prepend two sections before the bulk-install block:
- "The problem this doc fixes" — one or two paragraphs on what's confusing about the defaults (e.g., "macOS has Photos.app doing two jobs; Linux splits it across viewer + library manager"). Orients the reader before the install list.
- "Pick a vibe" — a short table that helps the user choose by mood / use-case rather than feature matrix. Columns: Vibe · Pick · Notes. Bold the headline recommendation per row.
Example vibe-table shape:
| Vibe | Pick | Notes |
|--------------------------------|----------------|----------------------------------------|
| **Apple Photos / Lightroom** | digiKam | Heavy, Qt/KDE, faces/geotags/tags/RAW |
| Simpler library manager | Shotwell | GNOME, events-by-date, clean and fast |
| **Minimal Preview.app feel** | qView | Qt, opens instantly, keyboard-driven |
4. Starter skeleton. If the user asks for a new software doc during (or after) vault init, scaffold it with this skeleton — fill in content, don't leave placeholders in the final doc:
# <Category> <Players|Viewers|Tools|Editors>
System: <OS/distro> · <DE/compositor>
<One-sentence scope. For <opposite axis>, see [[../<OtherFolder>/<OtherDoc>]].>
## The problem this doc fixes <!-- consume-side only -->
<Why the defaults are confusing and what this doc solves.>
## Pick a vibe (the short version) <!-- consume-side only -->
| Vibe | Pick | Notes |
|------|------|-------|
| … | … | … |
## Recommended install (cover all bases)
\```bash
sudo pacman -S <pkg1> <pkg2>
\```
\```bash
paru -S <aur-pkg>
flatpak install -y flathub <flathub-id>
\```
## Claude integrations
| Tool | Integration | Link |
|------|-------------|------|
| … | … | … |
## <Tool A>
<Short description — best for, aimed at whom.>
- Site: <url>
- Docs: <url>
- GitHub: <url>
- **Claude integration:** <if any>
\```bash
sudo pacman -S <pkg>
\```
## Verify installs
\```bash
for p in <pkg1> <pkg2>; do pacman -Q "$p" 2>/dev/null || echo "$p: not installed"; done
\```
Non-negotiables for software/tools docs:
- Verify package names against
pacman -Si / yay -Si (or the platform equivalent) before writing. Never invent package names.
- Curl-check any GitHub URLs for community MCPs before citing them.
- Prefer official repos → AUR → Flatpak → upstream binary, in that order.
- When an AUR build is known to fail, flag it and give a working alternative (e.g., Flatpak).
- Never omit the verify-installs loop — it's how the user confirms the paste actually landed.
Canonical file contents
Seed each file with a minimum-viable template. Key requirements:
WORKSTATE.md (required — the living doc hook targets this)
# Workstate
**Last updated:** <today in YYYY-MM-DD>
Single source of truth for what's active on [[<VaultName>]]. **A new session should read this first.**
## Now
- (fill in when a workstream starts)
## Next
- (queued)
## Blocked
_(none)_
## Recently shipped
- <today> — Vault scaffolded via `/init-vault` with canonical layout.
## Open questions
_(none tracked)_
## Parked ideas
_(park ideas here that aren't active but you don't want to forget)_
---
## For a new session starting on <VaultName>
1. You've already read this.
2. (list 2-3 key docs specific to this vault)
3. Living-docs hook maintains Now/Next/Recently-shipped automatically after each session end.
ARCHITECTURE.md
# Architecture — <VaultName>
Structure of the [[<VaultName>]] Obsidian vault.
## Layout
\```
<copy of the file tree above, actual to this vault>
\```
## Conventions
- Obsidian `[[wikilink]]` syntax for internal navigation
- Every folder has a `README.md` index
- Dated artifacts: `<Topic> - YYYY-MM-DD.md`
- Versioned drafts: `<Doc> v2.md` (preserve history)
- READMEs list primary notes + point to relevant skills
## Related
- [[README]]
- [[WORKSTATE]]
- [[CLAUDE]]
CHANGELOG.md
# Changelog
Work log for [[<VaultName>]]. Newest first. Not a formal semver changelog — project memory.
---
## <today> — Vault initialized via /init-vault
Canonical layout scaffolded: WORKSTATE, ARCHITECTURE, CHANGELOG, README, CLAUDE.md, per-folder READMEs. Living-docs auto-update hook will maintain this going forward.
CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code when working in this vault.
## What this is
<One-line description based on vault type + user's answer to purpose.>
## Read first
1. `WORKSTATE.md` — single source of truth for what's active.
2. `README.md` if WORKSTATE references something unfamiliar.
3. <If paired code repo:> `~/dev/<slug>/CLAUDE.md` for code-level orientation.
## Conventions
- Obsidian `[[wikilinks]]` for internal navigation
- Per-folder READMEs as indices
- Living-docs hook (from based-stack) auto-maintains WORKSTATE, ARCHITECTURE, CHANGELOG after each session
- Implementation plans live in `notes/plans/YYYY-MM-DD-<name>.md`
## Relevant skills
(Per-project vaults: generate a starter list from the workstream → skill mapping in skills-index.md)
(Topical / knowledge vaults: skip, or point to skills-index globally)
README.md
# <VaultName> — Vault
<One-line description.>
**Read [[WORKSTATE]] first** — it's the single source of truth for what's active, next, and blocked.
## Layout
<Table listing top-level folders with one-line descriptions>
## Top-level notes
- [[<VaultName>]] — seed note
- [[WORKSTATE]] — active state
- [[ARCHITECTURE]] — vault structure
- [[CHANGELOG]] — work log
- (DESIGN if per-project, skills-index if per-project)
## Setup on a new machine
\```bash
git clone git@github.com:sachio222/<slug>-vault.git \
~/Agents/Workspaces/<parent>/<VaultName>
# Re-create the Goldilocks plugin symlink (standard on all based-stack vaults)
~/dev/obsidian-plugins/obsidian-goldilocks-essentials/install-in-vault.sh \
~/Agents/Workspaces/<parent>/<VaultName>
\```
<VaultName>.md (seed note)
# <VaultName>
<One-paragraph description.>
## Links
- (project website, repo, etc., if applicable)
## Vault orientation
Start here: **[[WORKSTATE]]** (what's active) and **[[README]]** (layout).
### Top-level
- [[README]]
- [[WORKSTATE]]
- [[ARCHITECTURE]]
- [[CHANGELOG]]
### Workstreams (per-project)
- [[projects/product/README|Product]]
- [[projects/marketing/README|Marketing]]
- [[projects/seo/README|SEO]]
- [[projects/geo/README|GEO]]
- [[projects/strategy/README|Strategy]]
### Supporting
- [[notes/README|notes/]]
- [[reference/README|reference/]]
- [[Resources/README|Resources/]]
Per-folder READMEs
One paragraph explaining purpose + a short list of what belongs there. See any existing based-stack vault (LanguageAcademy, OrchestratedOncology) for reference examples — don't reinvent.
Second-brain starter files
For PKM vaults, ship real starter content so a clone is immediately useful.
<VaultName>.md (home dashboard)
# <VaultName>
<One-line description: who this vault is for / what it's for.>
> **How this is organized:** PARA (Projects / Areas / Resources / Archive) for filing + Daily Notes for capture + MOCs for navigation. Read [[CLAUDE]] for the workflow.
## Today
- [ ] Open [[Daily/<today>|today's daily note]]
- [ ] Process [[00 Inbox/README|inbox]] (aim: weekly)
## Active
- [[01 Projects/README|Projects]] — deadline-driven work
- [[02 Areas/README|Areas]] — ongoing responsibilities
## Reference
- [[03 Resources/README|Resources]] — topic-based notes
- [[MOCs/Home|Home MOC]] — curated entry points
## Cold storage
- [[04 Archive/README|Archive]] — done, dropped, or dormant
MOCs/Home.md (top-level Map of Content)
# Home MOC
Top-level Map of Content. An MOC is a curated note-of-links — use it as a front door into a subject once that subject has 5+ notes.
## How to use
Link back to this MOC from any note that fits a subject below. When a section grows past ~10 entries, promote it into its own MOC (e.g., `MOCs/Writing.md`, `MOCs/Reading.md`).
## Subjects
- _(empty — populate as the vault grows)_
PARA + utility folder READMEs — one-paragraph filing rules
00 Inbox/README.md — Fleeting captures and unsorted notes. Everything lands here first. Process weekly: route each note to 01 Projects/, 02 Areas/, 03 Resources/, or delete. Empty inbox = reviewed brain.01 Projects/README.md — Active work with a deadline. A project has a defined end state. When done, move the folder to 04 Archive/. One folder per project; name as YYYY-MM — <Project> for chronological sort.02 Areas/README.md — Ongoing responsibilities with no end date. Health, finances, home, a specific role. Areas are maintained, not completed. If an area spawns a deadline-driven effort, that effort becomes a Project.03 Resources/README.md — Topic-based reference you pull from. Books, research, recipes, how-to. Not tied to a specific Project or Area.04 Archive/README.md — Inactive items from the other three folders. Searchable history; only delete when certain you won't want it back.Daily/README.md — One dated note per day, YYYY-MM-DD.md. Use Obsidian's Daily Notes core plugin or Templater for a template.MOCs/README.md — Maps of Content. Create one when a subject accumulates 5+ notes and you want a curated front door. Link from [[Home]] downward.Attachments/README.md — Shared images and binaries embedded across the vault.
CLAUDE.md additions (second-brain workflow)
Include this section under ## Conventions in the generated CLAUDE.md:
Capture → File → Archive workflow. Write fleeting thoughts into 00 Inbox/ or a Daily/YYYY-MM-DD.md note. During weekly review, move notes out of Inbox into 01 Projects/ (deadline-driven), 02 Areas/ (ongoing), or 03 Resources/ (topic reference) — or delete them. When a project or area goes inactive, move the whole folder to 04 Archive/. Build an MOC (MOCs/<Subject>.md) when a subject accumulates 5+ notes and you want a curated front door.
Steps to execute
- Confirm answers to the 5 questions above.
- Pick the right subfolder set based on vault type (per-project / knowledge / topical).
- Create the folder structure with
mkdir -p.
- Write each file using the templates above, substituting
<VaultName>, dates, and user-provided context.
- Verify with
find <VaultPath> -type f | sort and show the user the tree.
- Optionally git init (if user confirmed):
cd <VaultPath>
git init
- Install the Goldilocks plugin symlink (standard on every based-stack vault — do this by default, no need to ask):
if [ -x ~/dev/obsidian-plugins/obsidian-goldilocks-essentials/install-in-vault.sh ]; then
~/dev/obsidian-plugins/obsidian-goldilocks-essentials/install-in-vault.sh <VaultPath>
fi
If the install script is missing on this machine, skip silently and mention it in the post-scaffold summary so the user can restore it later. Do not abort the scaffold over a missing plugin.
After scaffolding
Tell the user:
- Open the vault in Obsidian — community plugins install on first open.
- The
living-docs-auto-update hook (from based-stack) will maintain WORKSTATE/ARCHITECTURE/CHANGELOG automatically after each Claude Code session that touches this vault. No action needed — verify by ending a session with Ctrl+C twice or /exit.
- Fill in Now/Next in WORKSTATE with the real active work so the next session can resume properly. The hook won't invent context, only maintain it.
Non-negotiables
- Never create the
.obsidian/ folder with content. Leave empty; Obsidian populates on first open.
- Always include WORKSTATE.md even for minimal vaults — it's the living-docs hook's anchor.
- Always use the
<today> date for "Last updated" and first CHANGELOG entry.
- Never scaffold over an existing vault — check the target path is empty first. If not empty, abort and ask.
