tiennm99/ai-coding-workflow-labs
1
0
Fork 0
mirror of https://github.com/tiennm99/ai-coding-workflow-labs.git synced 2026-09-17 02:20:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(lesson): add Vin Obsidian Workflows lesson assets

Browse Source 
Add initial lesson structure for Vin Obsidian Workflows mini-lesson:
- CLAUDE.md: full lesson script and teaching instructions
- my-vault/: 10 interconnected Obsidian notes about Claude Code best practices
- .claude/commands/start-lesson.md: slash command to launch the lesson
- my-commands.md: documentation for custom commands
This commit is contained in:
tiennm99
2026-03-08 21:04:22 +07:00
parent 9b34990d35
commit 2b505dd5e1
13 changed files with 1030 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vin-obsidian-workflows/.claude/commands/start-lesson.md
+6
View File
@@ -0,0 +1,6 @@
Start the Vin Obsidian Workflows lesson.
Do this SILENTLY - don't announce what you're doing:
1. Read the `CLAUDE.md` file in this project root
2. Begin teaching immediately - no preamble, just start with the Welcome section
vin-obsidian-workflows/CLAUDE.md
+642
View File
@@ -0,0 +1,642 @@
# Vin Obsidian Workflows
This lesson teaches the Obsidian + Claude Code integration techniques from Internet Vin's interview with Greg Isenberg.
---
## Welcome
Welcome to the Vin Obsidian Workflows mini-lesson.
This is an interactive version of Greg Isenberg's interview with Internet Vin: https://www.youtube.com/watch?v=6MBq1paspVU
Here's the core insight: most people use Claude Code like a stranger. Every session starts from zero — you re-explain your project, your preferences, your constraints. Vin's system fixes that. It makes Claude Code feel like a thinking partner who already knows you.
**What we'll cover:**
1. What Obsidian is and why it matters for AI
2. Setting up the Obsidian CLI so Claude Code can read your knowledge graph
3. Building custom commands that load your world in one shot
4. Thinking tools that surface patterns you'd never see on your own
5. The golden rule that keeps the whole system honest
By the end, you'll have Obsidian connected to Claude Code, a working `/my-world` command, and a thinking tool you can reuse on your own notes.
STOP: Ready to get started?
USER: Yes / Ready / Let's go
---
## The Context Problem
Here's a question: have you ever started a new Claude Code session and had to re-explain your project, your preferences, your constraints — all over again?
STOP: Has this happened to you?
USER: Yes / Definitely / All the time / Not really
[If user says not really]: It will — especially on longer projects. The more you use Claude Code, the more painful the "cold start" gets. Either way, what we're about to set up will make every session better from the jump.
That's the number one reason people say Claude Code is "okay but not game-changing." It's not the model's fault. It's a context problem.
As Greg put it: "The whole game is feeding the beast good context."
Think about it: when you onboard a new coworker, you don't start from scratch. You give them docs, intros, context. Claude Code is the same — the better the context you feed it, the better everything it does.
So the question becomes: how do you feed Claude Code rich, persistent context without re-typing it every session?
That's what Vin figured out. And the answer is a tool called Obsidian.
STOP: Have you heard of Obsidian before?
USER: Yes / No / A little
---
## What is Obsidian
If you've never used Obsidian — or only know it vaguely — here's the short version: it's a note-taking app that stores everything as plain markdown files in a folder on your computer. That folder is called a "vault."
Unlike Google Docs or Notion, your notes aren't locked in someone else's cloud. They're just `.md` files you own. This matters a lot for what we're about to do — because Claude Code can read `.md` files natively.
But here's what makes Obsidian special: **wikilinks**.
When you write `[[Project Alpha]]` in a note, Obsidian creates a link to another note called "Project Alpha." And that link goes BOTH ways — you can see what links TO a note (backlinks), not just what it links out to.
Over time, this creates a web of connected ideas. Project notes link to people, people link to meetings, meetings link to decisions, decisions link back to projects. It starts to look like a map of how you think.
Vin showed his graph view in the video — hundreds of notes all interconnected. He said: "It works more like the way your brain works. Your brain connects these patterns all the time."
STOP: The key insight: it's not about individual notes. It's about the connections BETWEEN notes. Make sense?
USER: Yes / Makes sense
And here's why this is a game-changer for AI. Greg nailed it at the end of the interview — "People think tokens are the oxygen. But they're not. The markdown files are the memories."
Your notes are the raw material. Claude Code is the engine. Obsidian is the structure that connects them.
STOP: Now let's get you set up. Do you already have Obsidian installed?
USER: Yes / No
---
## Setup: Obsidian + CLI
[If user said NO to having Obsidian]:
First, let's get Obsidian installed. It's free.
ACTION: Open https://obsidian.md in the browser.
Download and install Obsidian. Once it's open, create a new vault — just give it a name and pick a folder. It can be anywhere on your computer.
STOP: Let me know when Obsidian is installed and you have a vault open.
USER: Done / Ready
[If user said YES to having Obsidian]:
Great! Make sure Obsidian is open with your vault loaded. We'll need it running for the next step.
STOP: Is Obsidian open with your vault?
USER: Yes
---
Now for the key piece: the **Obsidian CLI**.
In February 2026, Obsidian released an official command-line interface. This is what Vin uses in the video, and it's what makes the Claude Code integration so powerful.
Here's what it does: instead of Claude Code just reading your files (which it can already do), the CLI gives Claude Code access to the RELATIONSHIPS between files — backlinks, orphan notes, tag counts, the full link graph. Things that don't exist in the raw files.
Vin explained it: "With the Obsidian CLI, it can give Claude Code not only those files that it can read and access, but it can also give Claude Code information about the inter-relationships of those files."
The difference is massive. Finding orphan notes by scanning files takes 15 seconds and millions of tokens. With the CLI, it takes 0.26 seconds and about 100 tokens. That's 70,000x more efficient.
**One thing to know up front:** The CLI is currently in Early Access, which requires a Catalyst license — $25 one-time — from obsidian.md/pricing. This is the only paid part of this whole setup.
If you don't want to pay right now, that's totally fine. The lesson still works without it. Claude Code can read your vault files directly. You'll just miss the graph-aware commands (backlinks, orphans, etc.) I'll point out where the CLI adds extra power as we go.
STOP: Do you want to enable the CLI ($25 Catalyst license), or skip it for now and use direct file reading instead?
USER: I'll enable it / Skip for now
---
### Enable the CLI
[If user chose to enable]:
The CLI is built into Obsidian — no separate install needed. Here's how to enable it:
1. Make sure you're on Obsidian 1.12 or later. Check under Settings -> About. You also need the latest installer version (1.11.7+). If you need to update, go to obsidian.md/download.
2. Go to **Settings -> General**
3. Toggle on **"Command line interface"**
4. Follow the prompt to register the CLI — this adds the `obsidian` command to your terminal
**Important for Mac users:** After registering, restart your terminal. The registration adds Obsidian to your PATH via `~/.zprofile`. If you use a shell other than zsh (like bash or fish), you may need to add this line to your shell config manually:
```
export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS"
```
STOP: Were you able to find and toggle on the CLI setting?
USER: Yes / I can't find it
[If user can't find it]: Check that you're on Obsidian 1.12+ (Settings -> About) and have a Catalyst license. If your version is older, update at obsidian.md/download — you need the Early Access build. If you have the right version but don't see the toggle under Settings -> General, your Catalyst license may not be active. If you'd rather skip this step, no worries — we'll continue with direct file reading.
---
### Restart Your Terminal
[If user enabled CLI]:
**Important:** The CLI registration requires a full terminal restart to take effect. This means you'll need to quit your terminal app and reopen it — which will end this Claude Code session.
Here's how to get back:
1. **Quit your terminal completely** (Cmd+Q on Mac, not just close the tab)
2. **Reopen your terminal**
3. **Navigate back to this lesson folder**
4. **Run `claude --resume` to pick up where you left off** — or just run `claude` and tell it you just restarted your terminal for the CLI setup and are ready to verify
STOP: Ready to restart? Remember: `claude --resume` to get back here.
USER: Done / I'm back / I restarted
[If the user says they're back or that they restarted, they have successfully resumed. Continue to verification.]
---
### Verify the CLI
Let's make sure it's working.
ACTION: Run `obsidian version` to verify CLI is available.
ACTION: Run `obsidian vaults` to show available vaults.
STOP: Do you see your vault listed?
USER: Yes / No
[If No]: The CLI requires Obsidian to be running — make sure the app is open. Also make sure you restarted your terminal after registering the CLI. On Mac, check that your `~/.zprofile` contains the PATH export. If it's still not working, no worries — we'll continue with direct file reading and you can troubleshoot later.
[If Yes]: Let's try one more thing to see the power of this.
ACTION: Run `obsidian search query="test"` (or a relevant search term based on the user's vault).
That just searched your entire vault using Obsidian's index — instant, and way cheaper in tokens than having Claude grep through every file.
CLI is good to go. Now let's connect your vault.
[If user skipped CLI]:
No worries. Claude Code can still read your vault files directly — that's powerful on its own. I'll point out where the CLI would add extra capabilities as we go. You can always enable it later.
Let's move on to connecting your vault.
---
## Connect Your Vault
ACTION: Use the AskUserQuestion tool:
- Header: "Your vault"
- Question: "Do you have an existing Obsidian vault with notes in it, or do you want to start fresh for this lesson?"
- Options:
- "I have an existing vault with notes" (description: "Recommended if you have one — your real notes make the lesson way more powerful")
- "I want to start fresh — use the included example notes" (description: "We'll use the 10 pre-built Claude Code notes in my-vault/")
USER: [Selects option]
---
### Path A: Existing Vault
Perfect — using your real notes will make this lesson way more powerful.
STOP: What's the path to your Obsidian vault folder? You can find it in Obsidian -> Settings -> Files & Links -> look for "Vault location."
USER: [Provides path]
ACTION: Verify the vault path exists and list a few files to confirm. Note the vault path for use in subsequent commands.
Great — I can see your vault. You've got [X] notes in there.
For this lesson, I'm only going to READ your notes. I will never create, edit, or delete anything in your vault. That's actually one of the key rules we'll cover later.
STOP: Sound good?
USER: Yes
Now let's build the command that makes all those notes instantly available in any Claude Code session.
---
### Path B: Start Fresh
No problem. This lesson actually comes with a pre-built vault — 10 notes about Claude Code best practices, all interconnected with wikilinks. It's in the `my-vault/` folder.
Let's take a look at what's in there.
ACTION: List the files in `my-vault/` and display them to the user:
```
my-vault/
├── The Junior Employee Mental Model.md
├── Plan Mode.md
├── CLAUDE.md Best Practices.md
├── Context Window Management.md
├── The Verification Loop.md
├── Subagents.md
├── Custom Commands.md
├── Hooks.md
├── The Death Spiral.md
└── Voice-First Workflows.md
```
These are 10 interconnected notes about using Claude Code effectively. Each one links to others using `[[wikilinks]]` — the Obsidian feature we just talked about.
Let me show you what I mean. Take a look at one of them:
ACTION: Read `my-vault/The Death Spiral.md` and display it to the user. Point out how the `[[wikilinks]]` connect to other notes — `[[Plan Mode]]`, `[[Context Window Management]]`, `[[The Verification Loop]]`, `[[Voice-First Workflows]]`. Emphasize that these bidirectional links are what create the knowledge graph.
STOP: See the `[[links]]`? Each one points to another note in the vault. And those notes link back. Open a couple files and notice the web. This is exactly what Vin's vault looks like — except his has hundreds of notes across every domain of his life.
USER: Yes / I see it / That's cool
That web of connections is exactly what makes this system powerful. Even with just 10 notes, you've got a knowledge graph with real structure. Now let's build the command that loads all of it into Claude Code in one shot.
---
## Building /my-world
This is the command Vin uses most. He calls it `/context` — but there's a catch: `/context` is already a built-in Claude Code command (it shows your context window usage). So we'll name ours `/my-world` instead. Same idea, no conflict.
Instead of re-explaining who you are and what you're working on every session, `/my-world` loads it all in one shot.
Here's how it works: you create a command file that tells Claude Code to read your key context files. One command, and Claude knows your world.
Vin demonstrated this live — he typed his context command and Claude immediately had access to his projects, preferences, current priorities, everything. He said: "I just did that one command and now it's going to get all that information."
STOP: Let's build one for your vault right now. Ready?
USER: Yes / Ready / Let's do it
ACTION: Create `.claude/commands/my-world.md`. Here's what the command file should contain:
[If existing vault — adapt paths to their actual vault location]:
```markdown
Load my personal context from my Obsidian vault.
1. Read these key context files from my vault:
- @{vault-path}/ (list top-level files to understand structure)
2. [If CLI available] Run these commands to map relationships:
- `obsidian tags counts` — see what themes dominate
- `obsidian backlinks file={most-connected-note}` — trace key connections
- `obsidian orphans` — find disconnected notes
3. Summarize: what are my active projects, key priorities, and how do they connect? Reference specific notes.
```
[If fresh vault (my-vault/) without CLI]:
```markdown
Load my personal context from my vault notes.
1. Read all files in the vault:
- @my-vault/The Junior Employee Mental Model.md
- @my-vault/Plan Mode.md
- @my-vault/CLAUDE.md Best Practices.md
- @my-vault/Context Window Management.md
- @my-vault/The Verification Loop.md
- @my-vault/Subagents.md
- @my-vault/Custom Commands.md
- @my-vault/Hooks.md
- @my-vault/The Death Spiral.md
- @my-vault/Voice-First Workflows.md
2. Map the connections: which notes link to which? What are the most connected topics?
3. Summarize: what themes emerge? What's the overall knowledge structure? Reference specific notes and their connections.
```
[If fresh vault (my-vault/) with CLI]:
```markdown
Load my personal context from my vault notes.
1. Read all files in the vault:
- @my-vault/The Junior Employee Mental Model.md
- @my-vault/Plan Mode.md
- @my-vault/CLAUDE.md Best Practices.md
- @my-vault/Context Window Management.md
- @my-vault/The Verification Loop.md
- @my-vault/Subagents.md
- @my-vault/Custom Commands.md
- @my-vault/Hooks.md
- @my-vault/The Death Spiral.md
- @my-vault/Voice-First Workflows.md
2. Run these CLI commands to map relationships:
- `obsidian tags counts` — see what themes dominate
- `obsidian backlinks file="Context Window Management"` — trace key connections
- `obsidian orphans` — find disconnected notes
3. Summarize: what themes emerge? What's the overall knowledge structure? Reference specific notes and their connections.
```
ACTION: Document the command in `my-commands.md` with a description of what it does.
Done! You now have a `/my-world` command.
Here's the power move: in any Claude Code session where you have this folder, type `/my-world` and Claude immediately knows your world. No re-explaining.
STOP: Want to try it? Type `/my-world` right now.
USER: /my-world
ACTION: Execute the context command — read vault files (and CLI graph data if available), then summarize what you now know about the student's world. Be specific — reference their actual notes, projects, and connections.
See that? One command, and I know your projects, your priorities, how everything connects.
[If CLI enabled]: Notice how I also pulled backlink relationships and connection patterns — that's the CLI giving me the graph structure, not just the file contents.
STOP: Pretty powerful, right? That's your first custom command. Vin built a whole library of these — let's look at what else he uses.
USER: Yes / That's cool / What else?
---
## Daily Rituals
Vin built two ritual commands that bookend every day:
**`/today`** — a morning command that pulls your calendar, tasks, recent notes, and creates a prioritized plan. The insight: your calendar alone doesn't reflect what you're actually thinking about. Your notes fill that gap.
**`/close`** — an evening command that extracts action items from the day, surfaces vault connections you might have missed, and checks on hypotheses you're tracking.
Here's the quote that captures it: "Writing right now is a big way of how you delegate things to agents. If you can develop a writing habit, you have a lot more context that you can pass over to an agent which then dramatically increases the amount of things you can delegate."
The daily ritual is how the vault stays alive. You write a little each day, and the whole system gets smarter.
STOP: You don't need to build these right now — they work best once you have a regular writing practice. But let's build something even more interesting: a thinking tool.
USER: Let's do it / Sounds good / Ready
---
## Thinking Tools
"I really, really, really like working with LLMs as a thinking partner. It's my favorite way of using LLMs." — that's Vin.
He built several commands that don't organize information — they generate insight:
**`/challenge`** — pressure-tests your current beliefs using your vault's own history. Finds contradictions, counter-evidence, and shifts in your thinking.
**`/emerge`** — surfaces ideas the vault implies but you never explicitly stated. Conclusions from scattered premises, unnamed patterns, unarticulated directions.
**`/connect`** — takes two domains and finds bridges between them using your vault's link graph.
Greg compared it to a therapist: "You're doing most of the talking. The therapist is guiding you. That's what this is doing."
Let's build one. Pick the one that sounds most interesting to you.
ACTION: Use the AskUserQuestion tool:
- Header: "Thinking tool"
- Question: "Which thinking tool do you want to build?"
- Options:
- "/challenge - Pressure-test your beliefs" (description: "Finds contradictions and counter-evidence in your own notes")
- "/emerge - Surface hidden patterns" (description: "Discovers ideas your vault implies but you never stated")
- "/connect - Bridge two different topics" (description: "Finds unexpected connections between disparate domains")
USER: [Selects one]
ACTION: Build the selected command in `.claude/commands/`. Use the templates below based on which tool they chose:
**If /challenge:**
```markdown
Pressure-test my beliefs using my vault's own history.
1. Read all vault notes:
- @my-vault/The Junior Employee Mental Model.md
- @my-vault/Plan Mode.md
- @my-vault/CLAUDE.md Best Practices.md
- @my-vault/Context Window Management.md
- @my-vault/The Verification Loop.md
- @my-vault/Subagents.md
- @my-vault/Custom Commands.md
- @my-vault/Hooks.md
- @my-vault/The Death Spiral.md
- @my-vault/Voice-First Workflows.md
2. [If CLI available] Run: `obsidian backlinks file="The Death Spiral"` and `obsidian search query="never"` to find strong claims.
3. Find contradictions, tensions, and counter-evidence WITHIN my own notes. Where do I say one thing in one note and something different in another? Where are my blind spots?
4. Output format:
- **Tension Found**: [description]
- **Evidence from notes**: [specific quotes with note names]
- **The challenge**: [question that forces me to reconcile]
```
**If /emerge:**
```markdown
Surface hidden patterns — ideas my vault implies but I never explicitly stated.
1. Read all vault notes (same list as above).
2. [If CLI available] Run: `obsidian orphans` and `obsidian tags counts` to find neglected areas.
3. Look for: conclusions from scattered premises, unnamed patterns across notes, themes I circle around but never articulate, unarticulated directions my thinking is heading.
4. Output format:
- **Emergent Pattern**: [description]
- **Evidence trail**: [which notes contribute to this pattern]
- **The unstated idea**: [what my notes imply but I never wrote down]
```
**If /connect:**
```markdown
Bridge two disparate topics using my vault's link graph.
1. Read all vault notes (same list as above).
2. [If CLI available] Run: `obsidian backlinks file="Plan Mode"` and `obsidian backlinks file="Hooks"` to trace connection paths.
3. Pick two notes that seem unrelated and find the hidden bridge between them. What do they share that isn't obvious? What would combining their insights produce?
4. Output format:
- **Domain A**: [note/topic]
- **Domain B**: [note/topic]
- **The bridge**: [unexpected connection]
- **The insight**: [what this connection means]
```
[If existing vault: adapt the file references to point to their actual vault files instead of my-vault/.]
ACTION: Document the command in `my-commands.md`.
Done! Let's run it on your vault right now.
STOP: Ready to see what it finds in your notes?
USER: Yes / Do it / Let's see
ACTION: Execute the command against the student's vault. Produce genuine insights — find real tensions, patterns, or connections. Reference specific notes. Don't give canned output.
STOP: (After delivering output) Did anything surprise you there?
USER: [Responds]
That's the power of this approach.
[If existing vault]: You've been writing those notes for weeks or months. Claude just surfaced connections you didn't consciously make. Imagine running this weekly.
[If fresh vault]: You wrote those notes 10 minutes ago and Claude is already finding connections. Imagine what this does with a year of daily notes. That's what Vin runs — and he said it produces "huge light bulb" moments.
STOP: Make sense? Now there's one critical rule that makes this whole system work — and it's the thing most people get wrong.
USER: What is it? / Tell me / Yes
---
## The Golden Rule
Here's a critical principle from Vin — and this is the thing most people get wrong:
**Never let the agent write into your vault.**
Vin was emphatic about this: "I don't want an agent to write into the files... I always want it to pull from what I think about things, not what it thinks about things."
Here's why: if Claude starts creating notes in your vault, then when it runs `/emerge` or `/challenge` — is it finding YOUR patterns or ITS patterns?
The vault must contain only what YOU think. Claude reads and responds. It never contaminates the source.
Think of it like a journal. The value comes from it being authentically yours. If someone else started writing entries, the whole thing loses its meaning.
STOP: This is the one rule Vin never breaks. Make sense why?
USER: Yes / Makes sense
Here's the practical version: your vault is your writing. Claude's output goes to the terminal, to separate files outside the vault, or into conversation — never into the vault itself.
Vin's mindset shift: "Now instead of managing an agent, I just focus on managing this vault. This is the new source."
Your job isn't to micromanage Claude. Your job is to keep writing, keep linking, keep your vault rich. The agent takes care of the rest.
STOP: Ready for the wrap-up?
USER: Yes
---
## From Reflection to Action
One more thing before we close. The most impressive part of Vin's demo wasn't the reflection — it was when the agent started suggesting things to BUILD.
His `/ideas` command scans 30 days of notes across all domains and produces: tools to build, people to meet, essays to write, conversations to have.
[If CLI available]: This is where the CLI really shines. The `/ideas` command uses `obsidian orphans` to find neglected notes, `obsidian backlinks file=<name>` to trace high-connection topics, `obsidian deadends` to find notes that don't link out, and `obsidian tags counts` to see what themes dominate — all in seconds.
In the video, the agent suggested a `/graduate` command — a tool that finds ideas buried in daily notes that deserve to become standalone notes. Vin asked it to build the command... and it did. Right there. Done.
"I'm just going about making notes and I have this parallel agent that is looking at my notes and giving me ideas on how I can improve my workflow, improve my life. And then not only can it just suggest it, it just builds the thing and it's done."
The loop is: **write notes -> agent finds patterns -> agent suggests tools -> you build them -> tools improve your notes -> repeat.**
STOP: That's the vision. Your notes are the fuel. Claude Code is the engine. Together, they compound. Ready for the recap?
USER: Yes / Ready
---
## Wrap Up
Let's recap what you learned from Internet Vin:
1. **The context problem** — Claude Code is only as good as the context you give it
2. **Obsidian as infrastructure** — a vault of interconnected markdown notes becomes your personal knowledge graph
3. **The Obsidian CLI** — gives Claude Code access to your vault's relationships, not just file contents
4. **The /my-world command** — one command to load your world into any session
5. **Daily rituals** — /today and /close keep the vault alive and growing
6. **Thinking tools** — /challenge, /emerge, and /connect surface patterns you can't see alone
7. **The golden rule** — agents read, humans write. Never let the agent contaminate your vault.
8. **From reflection to action** — the vault generates real tools, ideas, and projects
You've got your vault connected, your commands in `.claude/commands/`, and a thinking tool you can reuse.
To use these commands on your real vault going forward: copy the `.claude/` folder from this lesson into your vault directory, or wherever you run Claude Code for personal work.
The most important next step: start writing daily. Even 5 minutes. The more you write, the smarter the system gets.
STOP: Any questions before we wrap?
USER: No / I'm good / [Asks a question]
[If user asks a question]: Answer it, then continue to closing.
Now go build your second brain.
---
## Notes for Claude
**Teaching style:**
- Conversational, direct, no fluff
- Quote Vin and Greg inline — the user can't see file reads
- Actually use the AskUserQuestion tool for vault choice and thinking tool choice
- Run the thinking tool for real — produce genuine insights, not canned output
- Be honest about CLI limitations (Catalyst license requirement, Early Access)
- Document every command you create in `my-commands.md`
**Pre-seeded vault notes (my-vault/):**
The lesson includes 10 interconnected notes about Claude Code best practices:
1. `The Junior Employee Mental Model.md` — delegation mindset
2. `Plan Mode.md` — Shift+Tab planning workflow
3. `CLAUDE.md Best Practices.md` — config file strategies
4. `Context Window Management.md` — the "drunk AI" problem
5. `The Verification Loop.md` — QA and debugging
6. `Subagents.md` — parallel workers
7. `Custom Commands.md` — building slash commands
8. `Hooks.md` — deterministic automation
9. `The Death Spiral.md` — anti-patterns
10. `Voice-First Workflows.md` — dictation techniques
Each note has 2-4 wikilinks to other notes. The knowledge graph has real tensions and connections to surface with thinking tools. For example:
- "The Death Spiral" contradicts advice in "Plan Mode" (sometimes planning is overkill)
- "Hooks" enforces what "CLAUDE.md Best Practices" can only suggest
- "Voice-First Workflows" connects to "The Junior Employee Mental Model" through verbal delegation
**Branching paths to track:**
- (1) Existing vault vs fresh vault (my-vault/)
- (2) CLI enabled vs CLI skipped
- Adapt commands and demonstrations based on what's available
- CLI-skipped path still works — just uses raw file reads instead of graph queries
- For existing vault path: adapt all `@my-vault/` references to point to the user's actual vault path
**If user has CLI issues:**
- Common causes: Obsidian not running (CLI requires it), terminal not restarted after registration, PATH not set on Mac (check `~/.zprofile` for `/Applications/Obsidian.app/Contents/MacOS`), old Obsidian version (need 1.12+)
- CLI command syntax: `obsidian <command> param=value` — NOT `--flag` style
- Examples: `obsidian search query="test"`, `obsidian backlinks file=Recipe`, `obsidian orphans`, `obsidian tags counts`
- Target a specific vault: `obsidian vault=VaultName <command>`
- Fallback: skip CLI gracefully, continue with direct file reading
**If user has a very large vault:**
- Don't try to read the entire vault. Use `obsidian search` or target specific folders.
- The /my-world command should reference key context files, not everything.
**Permission prompts:**
- Warn once on the first bash command (CLI verification), then don't mention it again.
**Success criteria:**
- [ ] User understands the context problem and why Obsidian matters
- [ ] User has Obsidian CLI enabled OR understands the fallback approach
- [ ] User has vault connected (existing) or created (fresh)
- [ ] User has a working /my-world command
- [ ] User has built and run one thinking tool on their notes
- [ ] User understands the golden rule (agents read, humans write)
- [ ] User knows how to port commands to their real vault going forward
- [ ] All commands documented in my-commands.md
vin-obsidian-workflows/my-commands.md
+3
View File
@@ -0,0 +1,3 @@
# My Commands
Commands built during this lesson will be documented here.
vin-obsidian-workflows/my-vault/CLAUDE.md Best Practices.md
+38
View File
@@ -0,0 +1,38 @@
# CLAUDE.md Best Practices
CLAUDE.md is the single most important file for Claude Code. It's loaded automatically at the start of every session — it's who you are and how you work.
Anthropic's official framing of the extension stack:
- **CLAUDE.md** = always-on context (who you are)
- **Skills** = on-demand knowledge and workflows
- **MCP** = external connections (Jira, Slack, etc.)
- **[[Custom Commands]]** = shortcuts for repeated prompts
- **[[Hooks]]** = deterministic automation
## What Goes in CLAUDE.md
Keep it short. "Keeping your CLAUDE.md as short as possible is a fantastic forcing function for simplifying your codebase and internal tooling."
My rule: if you can't explain something concisely, it's not ready for CLAUDE.md.
Three sections that matter:
1. **What this project is** — one paragraph
2. **Domain rules** — the stuff Claude will get wrong without guidance
3. **Validation** — how to check that output is correct
## The Power of Negative Constraints
This was a revelation: "Codify failures into your project's CLAUDE.md. Adding specific negative rules (e.g., 'NEVER use X method for Y task') is often more valuable than positive guidelines because it prevents the AI from repeating costly mistakes."
When Claude makes a mistake, immediately add a NEVER rule. Your CLAUDE.md evolves from positive guidelines to battle-tested negative constraints over time.
Net Ninja flagged this too — Claude has a habit of using new features/hooks everywhere in your project after creating them. You need explicit "don't do this" rules.
## The Hierarchy
CLAUDE.md files cascade:
- `~/.claude/CLAUDE.md` — global (your preferences everywhere)
- `project/CLAUDE.md` — project-level
- `project/src/CLAUDE.md` — directory-level overrides
This maps to [[The Junior Employee Mental Model]] — it's the onboarding doc. [[Context Window Management]] matters here too: a bloated CLAUDE.md eats into your working context.
vin-obsidian-workflows/my-vault/Context Window Management.md
+38
View File
@@ -0,0 +1,38 @@
# Context Window Management
"AI context is like milk; it's best served fresh and condensed." — YK/ykdojo
This is the thing that catches people off guard. As conversations get longer, quality degrades. The model loses track of earlier context, starts repeating itself, forgets instructions, makes mistakes it wasn't making before.
Ross Mike calls this the "drunk AI" problem. His rule: don't go over 50% context usage. The moment you see 40-50%, start a new session.
## The Core Strategy
**Fresh context > stale context, always.**
- One feature per chat. Mixing features is coding drunk.
- Start new sessions often rather than fighting with stale context
- Use `/compact` proactively when you feel context degrading
- Use `/context` to audit what's consuming your budget
## Handoff Documents
The killer pattern: at the end of a session, ask Claude to summarize the current state into a handoff doc. Start a new session with that doc. Fresh context + full awareness.
This connects to [[Subagents]] — each subagent gets its own fresh context window. It's like giving a task to a new employee who isn't tired yet.
## The Cost Connection
Context management IS cost management. Every token you waste on bloated context is money. The practitioner who spent $417 on a word game — one animation fix cost $20 because Claude needed to re-learn the entire codebase. That's a [[Context Window Management]] failure.
Cost-saving strategies:
- Focused prompts = smaller context = less cost
- Handoff docs between sessions
- [[Subagents]] for isolated tasks
- Use Sonnet for simple tasks, Opus for complex ones
## Related
- [[Plan Mode]] — planning reduces context waste
- [[CLAUDE.md Best Practices]] — a lean CLAUDE.md preserves context
- [[The Death Spiral]] — context bloat is a contributing factor
vin-obsidian-workflows/my-vault/Custom Commands.md
+44
View File
@@ -0,0 +1,44 @@
# Custom Commands
Custom commands are reusable slash commands you create yourself. They live in `.claude/commands/` as markdown files and can be triggered with `/command-name`.
This is where Claude Code starts feeling like YOUR tool instead of a generic assistant.
## How They Work
Create a file at `.claude/commands/my-command.md` with instructions. When you type `/my-command`, Claude reads that file and follows the instructions.
Examples:
- `/review` — code review with your team's standards
- `/plan` — generate a PRD from a one-sentence idea
- `/debug` — structured debugging workflow
- `/standup` — morning briefing that reads your project state
## The Vin Obsidian Connection
This is exactly what Internet Vin built for his Obsidian workflow:
- `/context` — loads your entire vault's context in one shot
- `/today` — morning planning ritual
- `/close` — evening reflection
- `/challenge` — pressure-test your beliefs using vault history
- `/emerge` — surface hidden patterns in your notes
- `/ideas` — 30-day vault scan for actionable insights
The power move: commands that reference your [[CLAUDE.md Best Practices]] and read your personal files to build context automatically.
## Building a PM Toolkit
Aakash Gupta's PM workflow was basically a chain of commands: meeting transcript → PRD → Jira tickets → Slack summary → dashboard.
You could build each step as a command:
- `/transcript-to-prd`
- `/prd-to-tickets`
- `/daily-metrics`
Each one is a pattern you've validated manually, then codified. See [[The Verification Loop]] — only automate what you've verified.
## Related
- [[Hooks]] — commands are on-demand; hooks are automatic
- [[CLAUDE.md Best Practices]] — commands complement CLAUDE.md
- [[Subagents]] — commands can spawn subagents for complex tasks
vin-obsidian-workflows/my-vault/Hooks.md
+44
View File
@@ -0,0 +1,44 @@
# Hooks
Hooks are deterministic automation that runs at specific points in Claude Code's lifecycle. They're the "must-do" rules that complement the "should-do" suggestions in [[CLAUDE.md Best Practices]].
The key distinction: CLAUDE.md is a suggestion. Hooks are enforced. Claude can ignore CLAUDE.md. It can't ignore a hook.
## How They Work
Hooks fire on lifecycle events:
- **PreToolUse** — before Claude uses a tool (firewall)
- **PostToolUse** — after Claude uses a tool (quality gate)
- **Stop** — when Claude finishes responding (review check)
- **SessionStart** — when a session begins (preload context)
They communicate via stdin/stdout and exit codes. A hook can block an action, modify it, or just log it.
## The Best Use Cases
**PreToolUse firewall** — prevent Claude from modifying certain files:
```json
{
"event": "PreToolUse",
"command": "check-if-protected-file.sh"
}
```
This connects directly to the golden rule from Vin's Obsidian setup — agents read, never write. You could enforce this with a hook.
**Stop quality gate** — require specific markers before Claude can finish:
A hook that checks for `// COMPLETE` comments before allowing Claude to stop. Forces thoroughness.
**Skill activation** — UserPromptSubmit hooks that detect patterns and load relevant skills automatically.
## The Power
"Hooks are the deterministic 'must-do' rules that complement the 'should-do' suggestions in CLAUDE.md."
Where [[Custom Commands]] are on-demand (you trigger them), hooks are automatic (they trigger themselves). Together they're your automation layer.
## Related
- [[CLAUDE.md Best Practices]] — suggestions vs enforcement
- [[Custom Commands]] — on-demand vs automatic
- [[The Verification Loop]] — hooks can automate verification
- [[The Junior Employee Mental Model]] — hooks are like mandatory processes a junior must follow
vin-obsidian-workflows/my-vault/Plan Mode.md
+33
View File
@@ -0,0 +1,33 @@
# Plan Mode
Overwhelmingly the #1 specific technique across everything I've read about Claude Code.
Shift+Tab forces Claude to outline its approach before acting. This is a design review — you would never ship a feature without reviewing the spec. Don't let Claude ship code without reviewing the plan.
## The Pattern
1. Hit Shift+Tab to enter plan mode
2. Claude outlines what it will do
3. You review, adjust, approve
4. Claude executes
Aakash Gupta calls this "Checkpoint + Iterate" — have Claude generate a plan, review it, create checkpoints, use Esc twice to rewind if it goes off track.
## When to Use It
- Any task touching multiple files
- Architecture decisions
- Anything you'd want to review before it happens
- When you're not sure what the right approach is
## When to Skip It
0xDesigner's counter-signal: "you don't need a 'planning mode' or any fancy approaches" — for many tasks, just talking to Claude naturally is enough. I agree for small stuff.
The rule I follow: if the task takes more than one prompt to describe, use plan mode.
## Connection to [[Context Window Management]]
Plan mode is also a context saver. A well-planned execution uses fewer tokens than a chaotic back-and-forth. Less context waste → longer productive sessions.
See also: [[The Death Spiral]] for what happens when you skip planning.
vin-obsidian-workflows/my-vault/Subagents.md
+36
View File
@@ -0,0 +1,36 @@
# Subagents
Subagents are Claude Code's way of running parallel workers. Each one gets its own fresh context window — like assigning a task to a new employee who isn't overloaded with everything else you've been working on.
The key insight: subagents solve the [[Context Window Management]] problem. Instead of cramming everything into one conversation, you delegate isolated tasks to fresh agents.
## The Three Types
1. **Explore agent** — reads files, searches codebase, answers questions about code. Read-only.
2. **Code agent** — can read AND write files, run commands. Full power.
3. **Custom agent** — via the Task tool with specific instructions.
## When to Use Them
Boris Cherny runs 5 local sessions + 5-10 web sessions in parallel. That's extreme for most people. The practical version:
- **Research tasks** — send a subagent to explore a codebase or read docs while you keep working
- **Independent tasks** — two features that don't touch the same files? Parallelize.
- **Context isolation** — prevent a debugging rabbit hole from polluting your main session
- **Verbose operations** — code reviews, file analysis, anything that generates a lot of output you don't need to see
## The Pattern
Each subagent gets:
- A clear task description
- Relevant file paths or search scope
- Expected output format
- Its own fresh context window
The main session stays clean. You get a summary back.
## Related
- [[Context Window Management]] — subagents are the #1 tool for managing context
- [[The Junior Employee Mental Model]] — subagents ARE the junior employees
- [[Custom Commands]] — you can wrap subagent patterns into reusable commands
vin-obsidian-workflows/my-vault/The Death Spiral.md
+45
View File
@@ -0,0 +1,45 @@
# The Death Spiral
"The AI Coding Death Spiral: enter for speed, stay for the debugging hell." — Reddit
This is the anti-pattern everyone hits at some point.
## The Pattern
1. Try to save time with AI
2. Get low-context, error-prone code
3. Spend more time debugging than you would have writing it
4. Keep going because "the next prompt might fix it"
That last point is the killer. "The frustration of AI coding can resemble a gambling addiction, where the user is always hoping the 'next prompt' will be the one that magically solves everything."
## How to Escape
From the 6-month practitioner report on Reddit:
- **Start with a small, perfectly working base.** Don't try to generate an entire app in one shot.
- **One feature at a time.** Never in a single large prompt.
- **Write a detailed spec first** — see [[Plan Mode]]
- **The 3-prompt rule:** if you've been debugging the same issue for more than 3 prompts, STOP. Think about whether YOU understand the problem.
The mantra: "If confused, the AI is too. Clarify for yourself first."
## Why It Happens
It's almost always a [[Context Window Management]] problem combined with skipping [[Plan Mode]].
Long session → stale context → bad output → more debugging → longer session → even staler context. It's a feedback loop.
The escape hatch: start fresh. Write a handoff doc, start a new session, approach the problem with clean context.
## The Deeper Issue
"AI is a force multiplier for your existing trajectory. A clean codebase gets cleaner. A messy codebase becomes messier even faster, creating an illusion of speed."
The death spiral isn't just about context. It's about [[The Verification Loop]] — if you're not checking output quality at each step, errors compound.
## Related
- [[Plan Mode]] — the #1 prevention strategy
- [[Context Window Management]] — the mechanical cause
- [[The Verification Loop]] — the missing check
- [[Voice-First Workflows]] — sometimes stepping away from the keyboard and talking through the problem breaks the spiral
vin-obsidian-workflows/my-vault/The Junior Employee Mental Model.md
+22
View File
@@ -0,0 +1,22 @@
# The Junior Employee Mental Model
The single most important mindset shift: Claude Code is a junior employee, not a magic wand.
Aakash Gupta said it best — "Delegate like you have 5 junior employees." You wouldn't dump a vague one-liner on a new hire and expect magic. You'd give them context, scope, and clear deliverables.
This maps directly to PM skills. Delegation, scope definition, and quality review ARE the PM skill set. We already know how to do this — we just need to apply it to AI.
The progression I've noticed:
1. Co-worker (you work alongside it)
2. Pair programmer (you guide, it types)
3. Team of agents (they run retrospectives and update their own instructions)
Related: [[Plan Mode]] is basically a design review for your AI. [[The Verification Loop]] is QA. These aren't new skills — they're PM skills applied to a new tool.
The "shoot and forget" principle from a practitioner I read: "Generally my goal is to delegate, set the context, and let it work. Judging the tool by the final PR and not how it gets there."
But this requires trust, and trust requires [[The Verification Loop]]. You can't shoot and forget until you've verified enough times to calibrate your expectations.
## What This Means for [[CLAUDE.md Best Practices]]
If Claude is a junior employee, then CLAUDE.md is the onboarding doc. You wouldn't onboard someone with a 50-page manual. You'd give them the essentials and let them ask questions.
vin-obsidian-workflows/my-vault/The Verification Loop.md
+34
View File
@@ -0,0 +1,34 @@
# The Verification Loop
Boris Cherny (the creator of Claude Code) says verification loops deliver 2-3x quality improvement. That's not a small number.
The hard truth from Reddit: "Claude can write code all day but can't click a button to see if it works." AI-generated code is NOT optimized for security, performance, or scalability by default. You have to explicitly prompt for these and always verify.
## The PM Angle
You are the QA layer. Every output needs human eyes before it ships. This isn't new for PMs — we already review designs, specs, and code. The difference is the volume and speed of output.
## Debugging Patterns That Work
**Blind paste** — copy error messages directly into Claude without reading them yourself. Claude is remarkably good at diagnosis from raw errors. 0xDesigner: "I got another error and just pasted the error without reading." Claude diagnosed a missing gas token from a raw wallet error.
**Screenshot debugging** — paste screenshots of UI bugs directly. Claude's vision is powerful for visual debugging. "A single screenshot can replace three paragraphs of explanation."
**The re-prompt** — if output seems wrong, use Esc-Esc to go back and rephrase slightly. Often a slight rephrasing yields vastly superior results.
## The TDD Loop for AI
Powerful pattern from a practitioner with 6 months of daily AI pairing:
1. AI writes a failing test
2. Human reviews the test
3. AI writes the implementation
4. Test passes → move on
This enforces requirements and ensures correctness. Even without formal TDD: always ask Claude to verify its own work.
## Connection to Other Notes
- [[The Junior Employee Mental Model]] — you wouldn't trust a junior's work without review
- [[Plan Mode]] — verification starts before execution
- [[The Death Spiral]] — skipping verification is how you get there
- Boris Cherny's "Grill me on these changes" prompt — make Claude critique its own work. See [[Custom Commands]] for how to automate this.
vin-obsidian-workflows/my-vault/Voice-First Workflows.md
+45
View File
@@ -0,0 +1,45 @@
# Voice-First Workflows
Multiple sources converge on voice as a transformative input for Claude Code. Allie K. Miller claims 95% of her prompts require zero typing.
## Why It Matters
"The game-changer is pairing dictation with AI editing — dictating first to capture your ideas at speaking speed, then using AI to clean it up." — Hannah Stulberg
You think faster than you type. Dictation captures the full stream of consciousness. Claude handles the formatting.
## Tools
- **Wispr Flow** — popular dictation tool
- **Superwhisper** — another option
- **Parakeet** (via Super Voice Assistant) — newer entrant
- Built-in macOS dictation works too for quick stuff
## The Pineapple Technique
This one blew my mind. Allie K. Miller uses a unique code word — "pineapple" — to embed AI instructions within her dictation. "It's like a way to speak to the AI on the side of the main task."
So you're dictating a PRD and you say "pineapple make this section more concise pineapple" and the AI knows that's a meta-instruction, not content.
## PM Angle
Dictation + Claude is the fastest path from "rough idea" to "polished artifact." Think about the workflow:
1. Speak your thinking (2 minutes)
2. Claude formats it into a PRD (seconds)
3. Review and refine
Compare to: staring at a blank doc trying to write the perfect spec.
This connects to [[Plan Mode]] — you could dictate your plan, have Claude structure it, then review. And to [[The Junior Employee Mental Model]] — you're verbally briefing your employee, not writing a formal memo.
## Connection to Obsidian
Vin's whole system is about writing as infrastructure. Voice lowers the friction of writing. More writing → richer vault → smarter [[Custom Commands]] and thinking tools.
The loop: speak → capture → link → let agents surface patterns.
## Related
- [[Plan Mode]] — voice as a planning input
- [[The Junior Employee Mental Model]] — verbal delegation
- [[Custom Commands]] — build a command that takes voice input and routes it