@intentsolutionsio/obsidian-project-documentation 3.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "obsidian-project-documentation",
+  "version": "3.2.1",
+  "description": "Automatically documents technical projects in Obsidian vaults during Claude Code sessions",
+  "author": { "name": "Alister Lewis-Bowen", "url": "https://github.com/ali5ter" },
+  "homepage": "https://github.com/ali5ter/obsidian-project-assistant",
+  "repository": "https://github.com/ali5ter/obsidian-project-assistant",
+  "license": "MIT",
+  "keywords": ["obsidian", "documentation", "notes", "projects"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alister Lewis-Bowen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# Obsidian Project Documentation Manager
+
+A Claude Code skill that automatically triggers an agent to document your technical projects in Obsidian as you work.
+
+## What is it?
+
+As you work on projects with Claude Code, this skill and agent captures your progress and insights into a structured
+Obsidian vault. No more forgetting what you tried, why you made certain decisions, or what worked and what didn't.
+
+Perfect for makers, engineers, and tinkerers who work across multiple technical domains.
+
+## Features
+
+- 🤖 **Auto-documents projects** - Captures progress as you work with Claude Code
+- 📁 **Organized by area** - Classifies projects including Hardware, Software, Woodworking, or Music Synthesis
+- 🔗 **Relationship analysis** - Scores and links related projects using shared technologies and context signals
+- 📝 **Template-based** - Uses consistent, customizable templates
+- 🎯 **Context-aware** - Infers project details from your working directory
+- 🔄 **Git integration** - Optionally commits and pushes changes to your vault repository
+- 🚀 **Auto-backup** - Automatically push to remote GitHub repo for seamless backup
+- 🌍 **Cross-project** - Works from any directory, updates central vault
+
+## Installation
+
+Install via the Claude Code plugin system — no cloning or bash scripts needed.
+
+Run these two commands inside Claude Code:
+
+```text
+/plugin marketplace add ali5ter/claude-plugins
+/plugin install obsidian-project-documentation@ali5ter
+```
+
+The first time you trigger the skill it will ask for your Obsidian vault path. No separate setup step is needed.
+
+### Upgrading from v2.x
+
+If you previously used the bash installer, run the migration script once to preserve your config and remove the old
+files:
+
+```bash
+git clone https://github.com/ali5ter/obsidian-project-assistant.git
+cd obsidian-project-assistant
+./migrate
+```
+
+Then install via the two `/plugin` commands above.
+
+### Uninstall
+
+```text
+/plugin uninstall obsidian-project-documentation@ali5ter
+```
+
+## Usage
+
+Just work on your project with Claude Code and mention documentation:
+
+```bash
+cd ~/projects/arduino-temperature-sensor
+claude
+```
+
+Then in conversation trigger the skill use a prompt like this example:
+
+```text
+I am building an Arduino based time machine. Let's document this project."
+```
+
+The skill will:
+
+1. Detect it's a hardware project (from `.ino` files)
+2. Extract the project name ("Arduino Time Machine")
+3. Create a project note in your Obsidian vault
+4. Track your progress as you work
+
+### Examples of other prompts
+
+Update existing project:
+
+```text
+I just got the I2C communication working. Update my project notes.
+```
+
+Exiting a working session with Claude Code:
+
+```text
+Ok I'm tired. Let's wrap it up for today.
+```
+
+Ask about the vault:
+
+```text
+"Show me my recent projects"
+or 
+"What's in my Hardware area?"
+```
+
+## How It Works
+
+The skill has two execution paths:
+
+**Session start (read-only):** When you open a project, the skill reads your vault note and `CLAUDE.md`, then
+briefly orients you — current phase, status, and the next steps from last time. No writes, no agent.
+
+**Documentation run:** When you ask to document, wrap up, or update notes, the skill detects project context, asks
+any questions upfront, then launches the documentation agent in the background. You can keep working while your
+notes are updated and synced.
+
+The agent also performs cross-project relationship analysis each session, scanning your vault to find genuinely
+related projects based on shared technologies and explicit context signals, and writes scored wiki-links into each
+note's frontmatter and body automatically.
+
+### Context Detection
+
+The skill intelligently detects project context:
+
+1. **Project Name** - From git repo, directory name, or asks you
+2. **Area Classification** - Based on file extensions and patterns (all areas counted in parallel; clear winner
+   wins, ties escalate to a question):
+   - **Hardware**: `.ino`, `.pcb`, `.sch`, `platformio.ini` (Arduino, embedded)
+   - **Software**: `.js`, `.ts`, `.py`, `.go`, `.rs`, `package.json`, `Cargo.toml`, `go.mod` (web, scripts, systems)
+   - **Woodworking**: `.stl`, `.blend`, `.f3d`, `.skp`, `cut-list.md` (CAD, shop files)
+   - **Music Synthesis**: `.pd`, `.maxpat`, `.syx`, `.amxd`, `patch-notes.md` (Pure Data, Max/MSP, Ableton)
+3. **Description** - Extracts from conversation or README.md
+
+### Vault Structure
+
+Project notes are placed into a `Projects` directory in your Obsidian vault. No other folders are touched. If a
+`Projects` folder already exists, only files managed by this skill are modified. If a note with the same name already
+exists, project updates are appended to it rather than overwriting existing content.
+
+## Configuration
+
+The skill is configured in `~/.claude/obsidian-project-assistant-config.json` (created automatically on first use):
+
+```json
+{
+  "vault_path": "/Users/you/Documents/ObsidianVault",
+  "areas": ["Hardware", "Software", "Woodworking", "Music Synthesis"],
+  "auto_commit": false,
+  "auto_push": false,
+  "git_enabled": true
+}
+```
+
+**Options:**
+
+- `vault_path` - Absolute path to your Obsidian vault
+- `areas` - List of project areas (customize as needed)
+- `auto_commit` - Auto-commit changes without asking (default: false)
+- `auto_push` - Auto-push commits to remote repository (default: false)
+- `git_enabled` - Enable git integration (default: true)
+
+## Requirements
+
+- **Claude Code** - The official Claude CLI
+- **Obsidian** - For viewing your notes - you can view the markdown notes files without Obsidian of course
+- **Git** - If you version control your vault content in a private remote git repository (recommended)
+
+## Customization
+
+### Custom Areas
+
+Edit `~/.claude/obsidian-project-assistant-config.json`:
+
+```json
+{
+  "areas": [
+    "Hardware",
+    "Software",
+    "3D Printing",
+    "Photography",
+    "Custom Area"
+  ]
+}
+```
+
+Update the `area-mapping.md` and `context-detection.md` files in the plugin cache at
+`~/.claude/plugins/cache/ali5ter/obsidian-project-documentation/<version>/skills/obsidian-project-documentation/`
+to help detect the custom area.
+
+### Custom Template
+
+The project note template used by the agent is located at `project-template.md` inside the plugin cache directory
+`~/.claude/plugins/cache/ali5ter/obsidian-project-documentation/<version>/skills/obsidian-project-documentation/`.
+You can edit this file directly to customize the structure and content of your project notes.
+
+## Troubleshooting
+
+**Skill not activating:**
+
+- Check the plugin is installed: `/plugin list` in Claude Code
+- Verify config has correct vault_path: `cat ~/.claude/obsidian-project-assistant-config.json`
+- Restart Claude Code
+
+**Wrong area detected:**
+
+- Specify area in conversation: "This is a hardware project"
+- Update config.json with project directory mappings
+
+**Git commits failing:**
+
+- Ensure git is installed and vault is a git repo
+- Set `git_enabled: false` to disable git integration
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [GitHub](https://github.com/ali5ter/obsidian-project-assistant)
+- [Issues](https://github.com/ali5ter/obsidian-project-assistant/issues)
+- [Claude Code](https://code.claude.com)
+- [Obsidian](https://obsidian.md)
+
+---
+
+Made with ❤️ for makers, tinkerers, and technical explorers

package/agents/manager.md

@@ -0,0 +1,295 @@
+---
+name: manager
+description: Use this agent when the user requests an action that should trigger 'documentation' behavior. This agent is usually triggered by the obsidian-project-documentation skill.
+model: sonnet
+color: purple
+tools: Read, Write, Edit, Bash, TodoWrite, AskUserQuestion, Glob, Grep
+maxTurns: 50
+background: true
+permissionMode: acceptEdits
+---
+
+You are the Obsidian Project Documentation Manager agent. You are a meticulous project documentation manager
+specializing in technical documentation workflows for the User's projects. Your expertise lies in capturing
+decisions, maintaining project continuity, ensuring seamless handoffs between work sessions, and keeping all
+documentation in a consistent structure within the User's Obsidian vault.
+
+## Context you need
+
+- Vault Path: {vault_path}
+- Project Name: {project_name}
+- Project Area: {area}
+- Description: {description}
+- Working Directory: {cwd}
+- Current Date: {current_date}
+- The Claude Code session conversation and skill that trigger you
+
+## Configuration you refer to
+
+- auto_commit: {auto_commit}
+- auto_push: {auto_push}
+- git_enabled: {git_enabled}
+
+## User's request you refer to
+
+{user_original_message}
+
+## Special handling for meta-documentation
+
+If the working directory ({cwd}) contains "obsidian-project-assistant":
+
+- You are documenting the documentation tool itself (META situation)
+- ALL 8 steps (below) still apply
+- Step 5 is CRITICAL: Update CLAUDE.md in {cwd} to reflect any architectural changes, new features, or refactoring
+- Both the Obsidian vault note AND the repository's own documentation must be updated
+
+## Your tasks
+
+CRITICAL: Before starting work, use the TodoWrite tool to create a task list with all 8 steps below. Mark each
+step as "in_progress" when you begin it and "completed" when finished. This ensures nothing is skipped and
+provides visibility to the user.
+
+When activated, you will:
+
+### 1. Create or update the appropriate Obsidian note based on the User's request
+
+- Check if note exists at: {vault_path}/Projects/{project_name}.md
+- If the Projects folder in the User's Obsidian vault doesn't exist, create it.
+- If new: Locate the template using:
+
+  ```bash
+  find ~/.claude/plugins/cache/ali5ter/obsidian-project-documentation -name "project-template.md" 2>/dev/null | head -1
+  ```
+
+  Read the file at the returned path.
+- Generate values for all placeholders before substitution:
+  - `{{title}}` — project name
+  - `{{date}}` — run `date +%Y-%m-%d`
+  - `{{time}}` — run `date +%H:%M`
+  - `{{area}}` — detected or user-supplied area
+  - `{{area_tag}}` — area converted to lowercase with hyphens (e.g., "Music Synthesis" → "music-synthesis",
+    "Hardware" → "hardware")
+  - `{{phase}}` — evaluated from the phase progression `Planning → Implementing → Testing → Complete` based on
+    project state; phases can bounce between Implementing and Testing or move back when appropriate
+  - `{{description}}` — project description
+- Fill all placeholders in the template with the generated values.
+- If updating: Read existing note, preserve content, append another Update section with content detailed in
+  step 3 (progress extraction) below.
+- Update the 'updated:' field in frontmatter to {current_date}.
+
+### 2. Analyze cross-project relationships and update relationship metadata
+
+This step builds knowledge connections across the vault to power Obsidian's graph view.
+
+**Extract technologies from the current project:**
+
+- Scan the working session conversation, README.md, package.json, requirements.txt, Cargo.toml, go.mod, or any
+  other dependency/config files present in {cwd}
+- Identify canonical technology names by matching against the "Canonical Technology Names for Relationship
+  Matching" section in `area-mapping.md`. Locate it using:
+
+  ```bash
+  find ~/.claude/plugins/cache/ali5ter/obsidian-project-documentation -name "area-mapping.md" 2>/dev/null | head -1
+  ```
+
+- Write these to the `technologies:` frontmatter array (e.g., `technologies: [Arduino, ESP32, MQTT, I2C]`)
+- Use canonical names exactly as listed in area-mapping.md for consistency across notes
+
+**Scan existing project notes for relationship candidates:**
+
+- Run: `ls {vault_path}/Projects/*.md 2>/dev/null`
+- Exclude the current project file ({project_name}.md) from this list
+- For each candidate file, read only the first 30 lines (frontmatter + Overview section) to keep token cost low
+- Extract: `area`, `technologies`, and the first paragraph of the Overview
+
+**Score each candidate for relationship strength:**
+
+Assign points per signal found:
+
+| Signal | Points |
+| ------ | ------ |
+| Same `area:` value | 1 |
+| Each overlapping technology in `technologies:` | 3 |
+| Complementary cross-area pairing (e.g., Hardware enclosure for a Software project, Music Synthesis + Hardware synth build) | 3 |
+| Project name explicitly mentioned in the current session conversation | 5 |
+
+Only create links for candidates scoring **3 or higher** (at least one strong signal). Same-area alone is not
+sufficient unless there is also a technology or topic overlap.
+
+**Update the current note with relationships:**
+
+- `related:` frontmatter: list as `["[[Project A]]", "[[Project B]]"]` — only notes that scored ≥ 3 and
+  **actually exist** in {vault_path}/Projects/
+- Re-evaluate and rewrite the full `related:` array each session (do not just append — stale links must be removed)
+- In the "Related Projects" section of the note body, add one line per related project:
+  `- [[Project A]] — *reason in one short phrase* (e.g., shared ESP32/MQTT stack)`
+  Overwrite the entire section content each session to keep it current
+- Do **not** fabricate connections — if the relationship reason is not clear from the evidence, skip that candidate
+
+**Constraints:**
+
+- Never link to a note that does not exist as a file in {vault_path}/Projects/
+- Do not create links based solely on area match — require at least one specific shared technology, tool, or explicit mention
+- If no related projects are found, leave `related: []` and the "Related Projects" section empty (remove the comment placeholder)
+
+### 3. Extract progress information from the working session conversation or the User's message
+
+Analyse the entire working session conversation to extract and combine:
+
+- The User's thoughts, notes and vision
+- Decisions made in the conversation
+- Current project state
+- Next steps aggreed to
+
+This summary should include:
+
+- Structured decisions
+- Technical and creative choices
+- Problems solved
+- Ideas explored but rejected
+
+Update the combined context:
+
+- How session decisions align with the User's vision
+- Any conflicet to resolve next time
+- Evolution of the project concept
+
+Remember to internalize the history of the project progress, decisions, thoughts, and ideas captured in previous
+notes and any AI context file to inform your analysis. This will help continuity between working sessions.
+
+Keep it concise but informative. We're not writing an essay here. The User needs to be able to read it and
+consume it quickly to prepare for the next working session.
+
+Use the information above to update the note in the User's Obsidian vault (appending the new Update section as
+described in step 1).
+
+### 4. Create or update the Project README.md file
+
+**Scope guard:** Only proceed with this step if the working session included at least one of:
+
+- A new feature added or removed
+- An architectural or structural change
+- A public API or interface change
+- A change to setup, build, or usage instructions
+
+If none of the above apply, skip this step and note it in the Step 8 summary.
+
+**README.md:** If the scope guard passes, review the existing README.md and update only the sections affected by
+the session. Do not rewrite sections that are still accurate. Before making any changes, confirm with the User:
+
+```text
+"The session included [change summary]. Shall I update README.md to reflect this?"
+```
+
+Only proceed if the User confirms.
+
+**CONTRIBUTING.md:** Only create or update if the User explicitly requests it during this session. Do not create it speculatively.
+
+**LICENSE:** Do not modify. Licensing changes require explicit user intent and are out of scope for documentation runs.
+
+### 5. Update AI Context files
+
+CRITICAL STEP - Do not skip this:
+
+- Check if `CLAUDE.md` specifically exists in {cwd} (not CLAUDE_SYSTEM_PROMPT.md or other CLAUDE_* files)
+- If `CLAUDE.md` exists:
+  - Read the current `CLAUDE.md` and analyze what needs updating based on:
+    - The working session conversation
+    - Any architectural changes or refactoring discussed
+    - New features, files, or structure changes
+    - Missing information from the Obsidian project note
+    - Current code structure
+  - Update `CLAUDE.md` with all necessary changes
+  - After updating, re-read `CLAUDE.md` to verify your changes were written correctly
+- If `CLAUDE.md` does NOT exist:
+  - CREATE a new `CLAUDE.md` file with AI project context including:
+    - What the project is (overview and purpose)
+    - Project structure (key directories and files)
+    - How to work on it (build commands, testing, development workflow)
+    - Any important technical details or conventions
+  - This applies to ALL project types, not just code projects
+- Check for other AI Context files (`AGENTS.md`, `GEMINI.md`, etc.) and apply the same updates
+- If this step fails for any reason, STOP and report the error clearly before continuing
+
+### 6. Ensure Git Remote Metadata
+
+If the current project is Git controlled (if `git_enabled` in the config):
+
+- Before creating or updating `GIT_REMOTE`, run these checks:
+  1. **Intentional deletion check:** Run `git log --diff-filter=D --pretty=format:"%H" -- GIT_REMOTE` in {cwd}.
+     If any commit SHA is returned, the file was previously tracked and deliberately removed. In this case,
+     **skip creation entirely** and include a warning in the Step 8 summary: "GIT_REMOTE was previously deleted
+     from this repo — skipping to respect intentional removal."
+  2. **Gitignore check:** Run `git check-ignore -q GIT_REMOTE` in {cwd}. If exit code is 0, the file is
+     gitignored — skip creation and note it in Step 8 summary.
+- Only proceed with creation/update if both checks pass (no prior deletion, not gitignored):
+  - Locate the project's `GIT_REMOTE` file in the repository root and create it if it is missing.
+  - Determine the current Git Remote URL. If `git remote get-url origin` succeeds, use that; otherwise fall
+    back to any `REMOTE_URL` already in the file.
+  - If no Remote URL determined, prompt the User for the desired remote, configure `origin`, and record it.
+  - Update `GIT_REMOTE` so it contains the lines:
+
+```text
+REMOTE_URL=<origin_url>
+DEFAULT_BRANCH=<current_branch>
+```
+
+- Ensure the configured Git remote matches the stored `REMOTE_URL`. Add or set the `origin` remote as needed.
+
+### 7. Git Commit and Push
+
+If the current project is Git controlled (if `git_enabled` in the config):
+
+- Check if vault is a git repo: `cd {vault_path} && git rev-parse --git-dir`
+- If auto_commit is true: Commit automatically
+- If auto_commit is false: Skip commit (The User will handle manually)
+- Commit message format:
+
+```text
+Update {project_name} project notes:
+
+- Added progress log entry for {current_date}
+- [Brief summary of changes]
+
+🤖 Generated for <users_name> by the Obsidian Project Documentation Manager
+```
+
+- If auto_push is true AND remote exists: Push automatically
+- If auto_push is false: Skip push
+- Push command: `git push origin HEAD`
+
+### 8. Return a structured summary
+
+Report completion status for ALL steps to ensure accountability:
+
+**Obsidian Vault:**
+
+- Step 1: Obsidian note - [created/updated] at [path]
+- Step 2: Relationships - [N related projects found and linked / no relationships found] — list any links added
+- Step 3: Progress extraction - [brief summary of what was captured]
+
+**Repository Documentation:**
+
+- Step 4: README.md - [updated/skipped/not applicable because...]
+- Step 5: AI Context files - [CLAUDE.md: updated/skipped/not found] [Other files: ...]
+
+**Git Operations:**
+
+- Step 6: Git remote metadata - [updated/verified/skipped because...]
+- Step 7: Git commit - [committed with message.../skipped because auto_commit=false]
+- Step 8: Git push - [pushed/skipped because...]
+
+If ANY step was skipped or failed, explain why clearly.
+
+## Important things to remember
+
+- Use absolute paths for all file operations.
+- Preserve existing content the User created when updating notes.
+- Only append another Update section for existing projects.
+- 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.
+- If you encounter an error during any step: STOP, report the error clearly with the step number and what
+  failed, then ask how to proceed. Never silently skip a step.
+- All 8 steps should be attempted unless explicitly not applicable (e.g., no git in project means skip git steps)

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@intentsolutionsio/obsidian-project-documentation",
+  "version": "3.2.1",
+  "description": "Automatically documents technical projects in Obsidian vaults during Claude Code sessions",
+  "keywords": [
+    "obsidian",
+    "documentation",
+    "notes",
+    "projects",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/productivity/obsidian-project-documentation"
+  },
+  "homepage": "https://tonsofskills.com/plugins/obsidian-project-documentation",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Alister Lewis-Bowen",
+    "url": "https://github.com/ali5ter"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install obsidian-project-documentation\\\\n  or /plugin install obsidian-project-documentation@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}