@intentsolutionsio/obsidian-project-documentation 3.2.1

package/skills/obsidian-project-documentation/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: obsidian-project-documentation
+description: Document technical projects in Obsidian vault. Use when the User mentions "document this", "close out", "wrap up", "update notes", "track progress", "where are we at", or asks about project docs.
+version: 3.2.1
+allowed-tools: Read, Bash, AskUserQuestion, Task
+---
+
+# Obsidian Project Documentation Assistant
+
+This skill helps maintain project documentation in an Obsidian vault while working with Claude Code. It
+automatically captures project progress and insights into structured, consistent notes.
+
+**Architecture:** This skill acts as a lightweight launcher that detects project context, asks clarifying
+questions if needed, then launches an agent to handle the documentation work in the background.
+
+## How This Works
+
+Three situations trigger this skill, falling into two execution paths:
+
+| Situation | Trigger | Path |
+| --------- | ------- | ---- |
+| **1** — New session start | User opens a project and says hello, or Claude Code starts | **Path A** — read-only context load |
+| **2** — Mid-session documentation | "document this", "update notes", "track progress", etc. | **Path B** — full documentation run |
+| **3** — Session end | "wrap up", "close out", "we're done for today", etc. | **Path B** — full documentation run |
+
+**Path A is read-only.** It must never launch the documentation agent or write to the vault.
+
+**Path B launches the agent.** It performs context detection and spawns the manager agent to write vault notes.
+
+## Shared Step: Load Configuration
+
+Before following either path, load the config:
+
+### Step 1: Load Configuration
+
+```bash
+cat ~/.claude/obsidian-project-assistant-config.json 2>/dev/null
+```
+
+Expected format:
+
+```json
+{
+  "vault_path": "/path/to/ObsidianVault",
+  "areas": ["Hardware", "Software", "Woodworking", "Music Synthesis"],
+  "auto_commit": false,
+  "auto_push": false,
+  "git_enabled": true
+}
+```
+
+**If config doesn't exist (first-run setup):**
+
+Use AskUserQuestion to ask the User for their Obsidian vault path:
+
+```text
+Question: "Where is your Obsidian vault? (e.g. ~/Documents/ObsidianVault)"
+Options:
+  - ~/Documents/ObsidianVault
+  - ~/Documents/MyVault
+  - Other (custom path)
+```
+
+Then write the config to `~/.claude/obsidian-project-assistant-config.json`:
+
+```bash
+cat > ~/.claude/obsidian-project-assistant-config.json <<EOF
+{
+  "vault_path": "<user-provided path with ~ expanded to $HOME>",
+  "areas": ["Hardware", "Software", "Woodworking", "Music Synthesis"],
+  "auto_commit": false,
+  "auto_push": false,
+  "git_enabled": true
+}
+EOF
+```
+
+Confirm the config was written, then follow the appropriate path below.
+
+## Path A: Session Start (Situation 1)
+
+Read-only. Do not launch the agent. Do not write to the vault.
+
+### Step A1: Detect Project Name
+
+Use the same detection logic as Step B2 (git repo name → directory name) to determine which vault note to load.
+
+### Step A2: Read Project Context
+
+```bash
+cat "{vault_path}/Projects/{project_name}.md" 2>/dev/null
+```
+
+Also read `CLAUDE.md` from the current working directory if it exists.
+
+### Step A3: Welcome the User
+
+Greet the User by name, summarise:
+
+- Current project phase and status from the vault note
+- The next steps recorded at the end of the last session
+- Any decisions or open questions worth flagging
+
+Keep this brief — it is an orientation, not a report.
+
+## Path B: Documentation Run (Situations 2 & 3)
+
+### Step B1: Quick Context Detection
+
+#### Detect Project Name
+
+Try these methods in order:
+
+1. **From the User's message** - If the User explicitly mentions project name in their request
+2. **From git repository**:
+
+   ```bash
+   git rev-parse --is-inside-work-tree 2>/dev/null && basename $(git rev-parse --show-toplevel)
+   ```
+
+   Transform kebab-case → Title Case (e.g., "obsidian-project-assistant" → "Obsidian Project Assistant")
+
+3. **From directory name**:
+
+   ```bash
+   basename $(pwd)
+   ```
+
+If none of these work or result is generic (like "src", "build", "test"), refer to Step B2 below.
+
+#### Detect Project Area
+
+Run all four area detections in parallel and count matches. This avoids the false positives of a sequential
+if/elif chain where the first match wins regardless of signal strength.
+
+```bash
+HW=$(find . -maxdepth 2 -type f \( -name "*.ino" -o -name "*.pcb" -o -name "*.sch" -o -name "platformio.ini" -o -name "arduino_secrets.h" \) 2>/dev/null | wc -l)
+SW=$(find . -maxdepth 2 -type f \( -name "package.json" -o -name "requirements.txt" -o -name "Cargo.toml" -o -name "go.mod" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \) 2>/dev/null | wc -l)
+WW=$(find . -maxdepth 2 -type f \( -name "*.stl" -o -name "*.blend" -o -name "*.f3d" -o -name "*.skp" -o -name "cut-list.md" \) 2>/dev/null | wc -l)
+MS=$(find . -maxdepth 2 -type f \( -name "*.pd" -o -name "*.maxpat" -o -name "*.syx" -o -name "*.amxd" -o -name "patch-notes.md" \) 2>/dev/null | wc -l)
+```
+
+Select the area using this decision logic:
+
+- If `HW > 0` AND `SW > 0`: area is ambiguous (embedded software) — refer to Step B2
+- Else if exactly one count is greater than all others: use that area
+- Else if all counts are zero, or no clear winner: refer to Step B2
+
+If no clear match, refer to Step B2 below.
+
+#### Extract Description
+
+Try to extract a brief description:
+
+1. Check if README.md exists and read first paragraph
+2. Check package.json for description field
+3. Parse the User's message for description
+4. See Step B2 below if the previous steps fail.
+
+### Step B2: Ask Clarifying Questions
+
+If project_name is null OR area is null, use AskUserQuestion before launching agent:
+
+**If project name is unclear:**
+
+```text
+Question: "What would you like to name this project?"
+Options:
+  - [Current directory name]
+  - [Git repo name if available]
+  - Other (custom input)
+```
+
+**If area is unclear:**
+
+```text
+Question: "What type of project is this?"
+Options:
+  - Hardware
+  - Software
+  - Woodworking
+  - Music Synthesis
+  - Other (custom input)
+```
+
+### Step B3: Launch Documentation Agent
+
+Launch an `obsidian-project-documentation:manager` agent with a prompt that includes all of the following context
+variables. Every variable must be populated from the sources listed — do not leave any as empty or undefined.
+
+| Variable | Source |
+| -------- | ------ |
+| `{vault_path}` | `vault_path` from config |
+| `{project_name}` | Detected or user-supplied in Step 2–3 |
+| `{area}` | Detected or user-supplied in Step 2–3 |
+| `{description}` | Extracted or user-supplied in Step 2–3 |
+| `{cwd}` | Run `pwd` |
+| `{current_date}` | Run `date +%Y-%m-%d` |
+| `{auto_commit}` | `auto_commit` from config |
+| `{auto_push}` | `auto_push` from config |
+| `{git_enabled}` | `git_enabled` from config |
+| `{user_original_message}` | The exact message the User sent that triggered this skill |
+
+Use this prompt template, substituting each `{variable}` with its value:
+
+```text
+Vault Path: {vault_path}
+Project Name: {project_name}
+Project Area: {area}
+Description: {description}
+Working Directory: {cwd}
+Current Date: {current_date}
+auto_commit: {auto_commit}
+auto_push: {auto_push}
+git_enabled: {git_enabled}
+User's original message: {user_original_message}
+```
+
+### Step B4: Report Results
+
+When the agent completes, inform the User:
+
+```text
+✅ Project documented successfully!
+📝 Updated: {path_to_note}
+📋 Summary: {what_was_documented}
+🔄 Git: {commit_status} {push_status}
+```
+
+## Error Handling
+
+If errors occur:
+
+- **Config missing**: Run first-run setup (ask for vault path, write config)
+- **Vault not accessible**: Verify vault_path in config
+- **Git operations fail**: Report error, but still create/update note
+- **Template missing**: Use a basic template or ask the User to reinstall
+
+## Important things to remember
+
+- Use absolute paths for all file operations.
+- Use the current date for all timestamp operations.
+- Handle errors gracefully (missing templates, git failures, etc.).
+- When refering to the User, use their name and not 'User'. If in any doubt of the User's pronouns, ask the
+  User but always remember them.

package/skills/obsidian-project-documentation/area-mapping.md

@@ -0,0 +1,267 @@
+# Area Mapping Reference
+
+Quick reference for file extensions and patterns that indicate project areas.
+
+## File Extension to Area Mapping
+
+| Extension | Area | Description |
+| --------- | ---- | ----------- |
+| `.ino` | Hardware | Arduino sketch files |
+| `.cpp`, `.h` | Hardware* | C/C++ (embedded context) |
+| `.pcb` | Hardware | PCB design files |
+| `.sch` | Hardware | Schematic files |
+| `.js`, `.ts` | Software | JavaScript/TypeScript |
+| `.py` | Software | Python |
+| `.go` | Software | Go |
+| `.rs` | Software | Rust |
+| `.java` | Software | Java |
+| `.rb` | Software | Ruby |
+| `.php` | Software | PHP |
+| `.stl` | Woodworking | 3D model (STL) |
+| `.obj` | Woodworking | 3D object file |
+| `.blend` | Woodworking | Blender file |
+| `.f3d` | Woodworking | Fusion 360 file |
+| `.skp` | Woodworking | SketchUp file |
+| `.pd` | Music Synthesis | Pure Data patch |
+| `.maxpat` | Music Synthesis | Max/MSP patch |
+| `.syx` | Music Synthesis | SysEx MIDI file |
+| `.fxp` | Music Synthesis | VST preset |
+| `.amxd` | Music Synthesis | Ableton M4L device |
+| `.sh` | Software | Shell |
+
+*Note: `.cpp` and `.h` can be Software or Hardware depending on context. Check for embedded indicators.
+
+## Configuration File Mapping
+
+| File | Area | Description |
+| ---- | ---- | ----------- |
+| `platformio.ini` | Hardware | PlatformIO configuration |
+| `arduino_secrets.h` | Hardware | Arduino secrets |
+| `package.json` | Software | Node.js package |
+| `requirements.txt` | Software | Python dependencies |
+| `Cargo.toml` | Software | Rust package |
+| `go.mod` | Software | Go module |
+| `pom.xml` | Software | Java Maven |
+| `build.gradle` | Software | Java Gradle |
+| `cut-list.md` | Woodworking | Woodworking cut list |
+| `materials.md` | Woodworking | Materials list |
+| `patch-notes.md` | Music Synthesis | Synth patch notes |
+| `tuning-table.txt` | Music Synthesis | Musical tuning data |
+
+## Keyword Indicators
+
+### Hardware Keywords
+
+```text
+arduino, esp32, esp8266, teensy, stm32
+circuit, pcb, schematic, breadboard
+sensor, actuator, microcontroller, mcu
+i2c, spi, uart, serial, gpio
+led, button, motor, servo
+voltage, current, resistor, capacitor
+```
+
+### Software Keywords
+
+```text
+api, rest, graphql, endpoint
+backend, frontend, fullstack
+server, client, database, db
+web, mobile, desktop, app
+framework, library, package
+npm, pip, cargo, composer
+react, vue, angular, flask, django
+docker, kubernetes, container
+```
+
+### Woodworking Keywords
+
+```text
+joinery, dovetail, mortise, tenon
+dado, rabbet, tongue, groove
+finish, stain, polyurethane, lacquer
+wood, lumber, hardwood, plywood, mdf
+oak, maple, walnut, cherry, pine
+table, saw, router, planer, jointer
+shop, workshop, woodshop, bench
+clamp, chisel, plane, sandpaper
+```
+
+### Music Synthesis Keywords
+
+```text
+oscillator, vco, vca, vcf
+filter, lowpass, highpass, bandpass
+envelope, adsr, attack, decay, sustain, release
+lfo, modulation, frequency, amplitude
+modular, eurorack, rack, module
+patch, voice, polyphony, monophonic
+cv, gate, trigger, clock
+midi, note, cc, sysex
+synthesis, synth, analog, digital
+waveform, sine, saw, square, triangle
+```
+
+## Detection Priority
+
+When multiple areas match:
+
+1. **Hardware + Software**: Ask user (likely embedded software project)
+2. **Woodworking + Hardware**: Ask user (could be CNC or electronics enclosure)
+3. **Music Synthesis + Hardware**: Ask user (likely hardware synthesizer build)
+4. **Music Synthesis + Software**: Ask user (software synthesizer or plugin)
+
+## Special Cases
+
+### Embedded Software (Hardware + Software)
+
+If both hardware and software indicators present:
+
+- Check for microcontroller keywords (arduino, esp32, etc.) → Hardware
+- Check for web/api keywords → Software
+- When in doubt, ask user to choose primary area
+
+### 3D Printing Projects
+
+`.stl`, `.gcode` files could be:
+
+- Woodworking (jigs, fixtures, furniture parts)
+- Hardware (enclosures, brackets, mechanical parts)
+- Music Synthesis (eurorack panels, knobs)
+
+Check context and ask user if needed.
+
+### CAD/Design Projects
+
+`.blend`, `.f3d`, `.skp` files could be:
+
+- Woodworking (furniture design)
+- Hardware (enclosure design)
+- General 3D modeling
+
+Look for other context clues or ask user.
+
+## Custom Area Support
+
+Users can add custom areas in config.json:
+
+```json
+{
+  "areas": [
+    "Hardware",
+    "Software",
+    "Woodworking",
+    "Music Synthesis",
+    "Photography",
+    "3D Printing"
+  ]
+}
+```
+
+If user has custom areas, ask them to classify or provide detection rules.
+
+## Canonical Technology Names for Relationship Matching
+
+When populating the `technologies:` frontmatter field or matching cross-project relationships, use these canonical
+names for consistency. Matching is case-insensitive; always write the canonical form listed here.
+
+### Hardware
+
+| Canonical Name | Aliases / Indicators |
+| -------------- | -------------------- |
+| Arduino | arduino, `.ino` |
+| ESP32 | esp32, esp-32 |
+| ESP8266 | esp8266, esp-8266 |
+| Teensy | teensy |
+| STM32 | stm32, bluepill |
+| Raspberry Pi | raspberry pi, rpi, raspi |
+| Raspberry Pi Pico | pico, rp2040 |
+| KiCad | kicad, `.kicad_pcb` |
+| I2C | i2c, i²c, wire |
+| SPI | spi |
+| UART | uart, serial |
+| MQTT | mqtt |
+| BLE | ble, bluetooth le, bluetooth low energy |
+| WiFi | wifi, wi-fi, wireless |
+| CNC | cnc, gcode, `.gcode` |
+
+### Software
+
+| Canonical Name | Aliases / Indicators |
+| -------------- | -------------------- |
+| JavaScript | javascript, `.js` |
+| TypeScript | typescript, `.ts` |
+| Python | python, `.py` |
+| Go | golang, `.go` |
+| Rust | rust, `.rs`, cargo |
+| Java | java, `.java` |
+| Ruby | ruby, `.rb` |
+| PHP | php, `.php` |
+| Shell | bash, sh, zsh, `.sh` |
+| React | react, reactjs |
+| Vue | vue, vuejs |
+| Angular | angular |
+| Flask | flask |
+| Django | django |
+| Express | express, expressjs |
+| FastAPI | fastapi |
+| Docker | docker, dockerfile, container |
+| Kubernetes | kubernetes, k8s, helm |
+| PostgreSQL | postgresql, postgres |
+| MySQL | mysql |
+| MongoDB | mongodb, mongo |
+| SQLite | sqlite |
+| Redis | redis |
+| AWS | aws, amazon web services |
+| Claude API | claude api, anthropic, claude code |
+
+### Woodworking
+
+| Canonical Name | Aliases / Indicators |
+| -------------- | -------------------- |
+| Dovetail joinery | dovetail |
+| Mortise and tenon | mortise, tenon |
+| CNC routing | cnc router |
+| Hand-cut joinery | hand-cut, hand cut |
+| Lathe turning | lathe, turned, turning |
+| Oak | oak |
+| Maple | maple |
+| Walnut | walnut |
+| Cherry | cherry |
+| Pine | pine |
+| Plywood | plywood |
+| MDF | mdf |
+| Oil finish | oil, danish oil, tung oil |
+| Polyurethane | polyurethane |
+| Fusion 360 | fusion 360, `.f3d` |
+| SketchUp | sketchup, `.skp` |
+
+### Music Synthesis
+
+| Canonical Name | Aliases / Indicators |
+| -------------- | -------------------- |
+| Eurorack | eurorack, euro-rack |
+| Pure Data | pure data, pd, `.pd` |
+| Max/MSP | max/msp, maxmsp, `.maxpat` |
+| Ableton Live | ableton, live, `.als`, `.amxd` |
+| MIDI | midi, `.syx`, `.mid` |
+| CV/Gate | cv, gate, cv/gate |
+| Analog synthesis | analog, analogue |
+| FM synthesis | fm, fm synthesis, frequency modulation |
+| Granular synthesis | granular |
+| Wavetable synthesis | wavetable |
+| VCO | vco, oscillator |
+| VCF | vcf, filter |
+| VCA | vca, amplifier |
+| ADSR | adsr, envelope |
+| OSC | osc, open sound control |
+
+## Future Enhancements
+
+Potential improvements for area detection:
+
+- Machine learning classification based on file content
+- User training: remember classifications for similar projects
+- Directory path patterns (~/arduino-projects → Hardware)
+- Git repository topics/keywords from GitHub
+- README.md badge detection (shields.io)