vault-architect

name

vault-architect

description

Scaffold a new company-brain vault. Use ONCE when starting a new vault. Confirms the target directory, industry profile, and whether to initialize git (default yes), then runs `cb scaffold` to create the folder tree, _branding/, _attachments/, exports/, and the _system reference files (PROFILE.md, INDEX.md, NODE-TYPES.md, EDGE-TYPES.md, FRONTMATTER-SCHEMA.md). Initializes the vault as a git repository by default. Does NOT write node content — that is the job of intake and atomize.

vault-architect

This skill scaffolds a new company-brain vault. Run it once per vault. It delegates the actual work to the cb scaffold CLI command so the on-disk shape stays single-sourced with the schema package.

When to use

• The user is creating a brand-new company-brain vault.
• The user wants to refresh _system/*.md, _branding/ starters, .gitignore, or the vault README.md after upgrading company-brain (use --force).

When NOT to use

• The user already has a vault and wants to add knowledge — point them at the intake or atomize skills.
• The user wants to change a vault's profile after the fact — that requires re-scaffolding into a new directory and migrating content by hand. The profile is not designed to be flipped in place.

Workflow

1. Confirm with the user

Ask, in order:

1. Target directory. Where should the vault live? Default to the current working directory if the user doesn't specify. Resolve to an absolute path before passing to the CLI.
2. Profile. Which industry profile? Offer these choices with brief explanations:
   • medical-device — patient-facing devices regulated by FDA / MDR / etc. Activates indications-for-use, regulatory-clearance, and ISO-14971-vocabulary risk node types. Generated documents carry the controlled-document-boundary footer.
   • default — industry-agnostic. Only the epistemic and entity node types are active.
   • saas, hardware, services — reserved slots. In v1 these behave like default; content lands in v2.
3. Git. Confirm the user wants the vault initialized as a git repository (the default). Most company vaults benefit from this — it makes them shareable, version-controlled, and ready to push to GitHub / GitLab / Bitbucket / on-prem. Pass --no-git only when:
   • The user does not have git installed.
   • The vault will live inside another git repo (e.g., as an example vault tracked by a parent repo). cb scaffold will detect this case automatically and skip git, so --no-git is mainly an explicit signal.

If the target directory already contains a vault (i.e. _system/PROFILE.md exists), tell the user. Offer to re-run with --force if they want to regenerate the system docs after a company-brain upgrade.

2. Run the command

cb scaffold --profile <name> --path <dir>

For refresh after an upgrade:

cb scaffold --profile <name> --path <dir> --force

For a vault that should not be a git repo:

cb scaffold --profile <name> --path <dir> --no-git

3. Report results

The CLI prints a structured summary. Read it back to the user, then add:

• A reminder of the activated profile-conditional types (if any) so they know what's available.
• If git was initialized, suggest the next step: git remote add origin <url> then git push -u origin main to share the vault with the team.
• The next-step suggestion of adding knowledge via intake vision (for a dictation-friendly first pass) or atomize (for ingesting existing documents).
• The controlled-document-boundary reminder if the profile is medical-device.

What gets created

Path	What's there
.git/ (when git enabled)	Initialized as main branch; one initial commit.
.gitignore	Vault-level. Notably gitignores _system/INDEX.md (regenerated by cb).
README.md	Identifies the vault and links back to company-brain.
_system/PROFILE.md	Declares the active profile.
_system/INDEX.md	Starter file. Gitignored — rebuilt by cb on demand as nodes are added.
_system/NODE-TYPES.md, EDGE-TYPES.md, FRONTMATTER-SCHEMA.md	Rendered from the schema package. Refreshed by --force.
_branding/colors.yaml	Starter brand palette. Edit to match the company.
_branding/README.md	Explains what goes in _branding/.
_attachments/, exports/	Empty folders, ready to receive captures and generated documents. Both committed by default.
pillars/, decisions/, entities/..., risk/...	Empty node-type folders for the chosen profile.

Worked examples

Starting a medical-device vault

cb scaffold --profile medical-device --path /Users/jane/work/acme-monitor-vault

Expected: ~35 folders, 9 files written, git initialized with an initial commit. The user can then git remote add origin [e-mail]:acme/acme-monitor-vault.git && git push -u origin main.

Refreshing system docs after upgrade

cb scaffold --profile medical-device --path /Users/jane/work/acme-monitor-vault --force

This overwrites the five _system/*.md files, the two _branding/ starter files, and the vault .gitignore and README.md. Does not touch any node files, attachments, exports, or git history. The user will see uncommitted changes in git status; reviewing and committing them is the user's call.

Scaffolding an example vault inside another repo

cb scaffold --profile medical-device --path ./examples/some-fictional-vault --no-git

When a vault lives inside another git repo (e.g., the company-brain examples), --no-git skips git initialization to avoid nesting a second repo. cb scaffold also auto-detects this case and skips git even without the flag, but --no-git makes the intent explicit.

Constraints

• This skill never writes node content. Refuse politely if asked to add a pillar, decision, fact, etc. — that is the intake/atomize skills' job.
• This skill never runs cb validate. Mention that the user can run it themselves once nodes exist.
• This skill never modifies an existing PROFILE.md to switch profiles. Doing so silently would leave orphan folders and break retrieval. If the user wants a different profile, scaffold a new vault.
• This skill never pushes to a remote. It suggests the command but the user is responsible for the actual push.