Arc Notes System

ARC Labs Studio - Notes System (Obsidian-Backed)

Overview

The arc-notes-system defines how each ARC project mounts an Obsidian vault as a gitignored notes/ symlink for operational, ephemeral, and per-feature notes. It complements /arc-memory, which covers the committed memory/ tree of evergreen documentation.

Memory vs Notes — The Four-Layer Model

The split keeps the repo lean, lets each developer keep personal scratch without polluting git history, and still surfaces cross-cutting decisions in the committed memory/ tree.

Vault Folder Structure

The Obsidian vault is the source of truth. Each project owns one folder under 01 - Projects/:

$HOME/Documents/ObsidianVault/
└── 01 - Projects/
    └── <ProjectName>/         # e.g. FavRes, PizzeriaLaFamiglia
        ├── features/          # Active per-feature notes (FVRS-XXX, PIZ-XXX, etc.)
        ├── archive/           # Archived feature notes (post-merge)
        ├── decisions/         # Cross-cutting decision records (mirrors memory/DECISIONS.md scope)
        ├── plans/             # Auto-synced Claude Code plans (Stop hook target)
        └── troubleshooting/   # Debugging session notes written during active work

Each project's repo gets a notes/ symlink pointing at its vault folder:

ln -s "$HOME/Documents/ObsidianVault/01 - Projects/<ProjectName>" notes

Setup Steps (New ARC Repo)

Apply this checklist to any ARC project (app, package, or web) that needs the notes integration. Templates live in this skill's templates/ directory.

1. Create the vault folder. In Obsidian, create 01 - Projects/<ProjectName>/ with the five subfolders above. Skip subfolders the project doesn't need (see Applicability).

2. Add the SessionStart hook. Copy templates/setup-notes.sh.template to .claude/hooks/setup-notes.sh, replace <PROJECT_NAME> with the project's vault folder name, and chmod +x it. The hook:

   • Is idempotent (re-running is a no-op).
   • Uses $HOME — works across machines and worktrees.
   • Skips silently if the vault is absent (cross-machine safe).

3. Add the Stop hook for plan auto-sync. Copy templates/sync-plans.sh.template to .claude/hooks/sync-plans.sh and chmod +x it. No placeholders to replace. The hook:

   • Finds plans from ~/.claude/plans/ modified in the last 8 hours.
   • Copies to notes/plans/YYYY-MM-DD-<branch-slug>-<plan-stem>.md.
   • Strips branch type prefix: feature/FVRS-222-foo → FVRS-222-foo.
   • Skips silently when notes/plans/ is absent.

4. Gitignore the symlink. Add notes (no trailing slash — it's a symlink, not a directory) to .gitignore. Never commit the symlink or its contents.

5. Wire the hooks into .claude/settings.local.json. Merge the contents of templates/settings.local.json.fragment into the project's settings.local.json. Both hooks.SessionStart and hooks.Stop must be registered, and Write(./notes/**) must be in permissions.allow so Claude can write troubleshooting and feature notes without prompting.

6. Document it in the project's CLAUDE.md. Append the contents of templates/CLAUDE-md-section.md (with <ProjectName> replaced) to the bottom of the project's CLAUDE.md so every Claude session knows the convention.

7. Bootstrap the symlink locally. Trigger the SessionStart hook once (start a Claude session, or run .claude/hooks/setup-notes.sh manually) to create the notes symlink in the working tree.

Cross-Machine Support

• No hardcoded user paths. Every script and template uses $HOME. Never hardcode /Users/<name>/... — it breaks on other machines, on CI, and on worktrees mounted under different paths.
• Vault path convention: $HOME/Documents/ObsidianVault/01 - Projects/<ProjectName>.
• Fallback when the vault is absent. If the vault directory does not exist on a given machine (CI, fresh clone, contributor without Obsidian), setup-notes.sh exits 0 silently — notes/ is simply not created and the Stop hook becomes a no-op. The project remains fully usable; the notes integration is opt-in per machine.
• Worktrees. The SessionStart hook re-runs in each worktree, so each worktree gets its own notes/ symlink pointing at the same vault folder.

Naming Conventions

Tickets use the project's Linear team key (FVRS, PIZ, etc.). Branch slug strips the type prefix (feature/FVRS-222-foo → FVRS-222-foo).

When to Write Where

Rule of thumb: if the entire team needs it, commit it under memory/. If only you (or the next debugging session) needs it, write it under notes/.

Applicability

Bootstrap Script (ARCDevTools)

A one-shot bootstrap script lives in ARCDevTools at scripts/arc-setup-notes-system.sh. It performs all six setup steps (creates the hook scripts from these templates, wires the JSON, appends the CLAUDE.md section, and adds notes to .gitignore) for any ARC repo. Use it when onboarding a new project; use this skill's templates when bootstrapping manually or when scripting a custom variant.

Examples

Setting up a new app

User says: "Set up the notes system for the new ChessTrainer app."

1. Create $HOME/Documents/ObsidianVault/01 - Projects/ChessTrainer/ with the five subfolders.
2. Copy templates/setup-notes.sh.template → .claude/hooks/setup-notes.sh, replace <PROJECT_NAME> with ChessTrainer, chmod +x.
3. Copy templates/sync-plans.sh.template → .claude/hooks/sync-plans.sh, chmod +x.
4. Add notes to .gitignore.
5. Merge templates/settings.local.json.fragment into .claude/settings.local.json.
6. Append templates/CLAUDE-md-section.md (with ChessTrainer substituted) to CLAUDE.md.
7. Run .claude/hooks/setup-notes.sh once — the symlink is created.

Capturing a debug session mid-flow

User says: "We just spent two hours debugging the SwiftData migration — write it up."

1. Resolve current ticket (e.g. FVRS-205) and today's date.
2. Create notes/troubleshooting/2026-05-15-FVRS-205-swiftdata-version-mismatch.md.
3. Capture symptoms, root cause, fix, and links to the relevant commit/PR.
4. No commit — notes/ is gitignored. Obsidian sync handles distribution.

Promoting a draft decision to an ADR

User says: "We've been using TabRouter isolation for two weeks and it's sticking — promote it."

1. Read notes/decisions/2026-05-01-tabrouter-isolation.md.
2. Append a new ADR entry to committed memory/DECISIONS.md with the final rationale.
3. Optionally archive the draft by moving it under notes/archive/.
4. Commit only the memory/DECISIONS.md change.

Related Skills