BrainDead — AI Agent Skills

Multi-function skill repository for AI coding agents. Includes:

• Knowledge Vault — Persistent project memory via Obsidian vault (auto-detected, WSL-aware)
• MemoryVault — Per-project Q&A cache in MemoryVault/ (auto-created on query)
• Bug tracking — Full bug lifecycle (unsolved → solving → solved) with vault nodes
• Change classification — Auto-detect bug/feature/major/minor changes
• Agent auto-setup — Automatically configures AGENTS.md/CLAUDE.md/.cursor/rules/ with Knowledge Vault protocol
• GitHub backup — Auto backup to private {user}/KnowledgeGraph repo

Requirements

• Obsidian vault (optional — auto-detected or created at default location)
• git (for dependency updates)
• gh CLI (for backup command — gh auth login required)
• One of: Claude Code, opencode, Cursor, Codex, Copilot, Gemini Code Assist

Quick Install

Windows (PowerShell)

.\install.ps1

WSL / Linux

chmod +x install.sh
./install.sh

What the installer does

1. Detects your Obsidian vault (reads Obsidian config, checks common paths)
2. Scaffolds Knowledge Vault/ inside the vault with GLOBAL-PROJECT-MEMORY.md
3. Downloads dependency skills: obsidian-skills + graphify
4. Detects installed AI agents (Claude Code, opencode, Cursor, Codex, Copilot, Gemini)
5. Installs BrainDead skills to each detected agent
6. Writes brain-config.json with vault path and repo root

Manual Install by Agent

Claude Code

mkdir -p ~/.claude/skills/knowledge-vault
cp -r skills/knowledge-vault/* ~/.claude/skills/knowledge-vault/

opencode

mkdir -p ~/.config/opencode/skills/knowledge-vault
cp -r skills/knowledge-vault/* ~/.config/opencode/skills/knowledge-vault/

Cursor

mkdir -p ~/.cursor/rules
cp skills/knowledge-vault/SKILL.md ~/.cursor/rules/knowledge-vault.mdc

Codex

mkdir -p ~/.codex/skills/knowledge-vault
cp -r skills/knowledge-vault/* ~/.codex/skills/knowledge-vault/

GitHub Copilot

Add this section to .github/copilot-instructions.md in your repository:

## Knowledge Vault Protocol
Before starting any task, read `GLOBAL-PROJECT-MEMORY.md` and the relevant project cluster.
After changes, update the project nodes and GLOBAL-PROJECT-MEMORY.md.
Classify every change (bug/feature/major/minor) and track bugs in the vault.

Gemini Code Assist

mkdir -p ~/.gemini/instruction
cp skills/knowledge-vault/SKILL.md ~/.gemini/instruction/knowledge-vault.md

Slash Commands

Use these in any AI agent chat after installing:

| Command | What it does | |---|---| | /BrainDead | Full pipeline — vault context + knowledge graph + document findings | | /BrainDead backup | Auto backup Knowledge Vault + MemoryVault to private GitHub repo | | /BrainDead update | Pull latest BrainDead from GitHub, re-install skills | | /BrainDead <question> | Query mode — check MemoryVault → Knowledge Vault → research → store → answer |

Examples

/BrainDead                                    — full pipeline
/BrainDead backup                              — backup to GitHub
/BrainDead update                              — update skills
/BrainDead how many tier rank in this project? — query mode

npm Scripts

| Script | Description | |---|---| | npm run push | Interactive push with optional npm package publish | | npm run backup | Same as /BrainDead backup | | npm run setup | Run the installer |

Features

Knowledge Vault (Vault Auto-Detection)

On every session, BrainDead automatically:

1. Checks brain-config.json for cached vault path
2. Detects platform: WSL, native Windows, macOS, or Linux
3. Reads Obsidian's own config (vault.json) to find registered vaults
4. Falls back to default location (Documents/Obsidian Vault)
5. If no vault exists, asks permission to create one
6. Writes resolved path to brain-config.json

WSL support: When running in WSL, vault paths use /mnt/c/... so both Windows Obsidian and WSL agents share the same vault.

Agent Config Auto-Setup

Every /BrainDead session automatically:

• Detects which agent is running (opencode, Claude Code, Cursor, etc.)
• Finds the agent's config file (AGENTS.md, CLAUDE.md, .cursor/rules/, etc.)
• Appends Knowledge Vault protocol rules (never overwrites existing content)
• Subsequent sessions skip re-write (already configured)

Change Classification & Bug Tracking

All changes are automatically classified and tracked:

| Signal | Type | Vault action | |---|---|---| | fix:, bugfix:, hotfix: | bug-unsolved / bug-solved | Create/update bug node | | feat:, feature:, add: | feature | Create/update feature node | | refactor:, rewrite: | major-refactor | Update architecture node | | docs:, chore:, style: | minor | Changelog entry only |

Bugs follow a lifecycle: unsolved → solving → solved, with full root cause and fix documentation.

MemoryVault — Project Q&A Cache

Every /BrainDead <question> creates:

• MemoryVault/<slug>.md in the project root (fast cache)
• A Q&A node in Knowledge Vault/<Project>/ (permanent graph record)

Questions are cached by filename. Re-asking the same question returns the cached answer instantly.

GitHub Backup

/BrainDead backup automatically:

1. Detects your GitHub username via gh CLI
2. Creates a private KnowledgeGraph repo if it doesn't exist
3. Copies Knowledge Vault/ + MemoryVault/ to the repo
4. Generates a README with a table of all projects
5. Pushes to GitHub — zero user interaction required

Project Structure

├── SKILL.md                              # Master skill — dispatches /BrainDead commands
├── skills/
│   ├── knowledge-vault/                  # Core: Obsidian vault integration
│   │   ├── SKILL.md                      # Full protocol definition
│   │   ├── brain-config.json             # Created by installer (vault path, repo root)
│   │   ├── templates/
│   │   │   ├── 00-project-node.md        # Project hub node
│   │   │   ├── 01-feature-node.md        # Feature node
│   │   │   ├── 02-bug-node.md            # Bug tracking node
│   │   │   ├── 03-qa-node.md             # Q&A node
│   │   │   ├── 04-memory-vault.md        # MemoryVault file template
│   │   │   └── handoff.md                # Agent handoff template
│   │   └── reference/
│   │       ├── deep-mode.md              # Full ceremony pipeline
│   │       ├── scoring-guide.md          # Node importance scoring
│   │       ├── platform-adapters.md      # Manual install per agent
│   │       └── mermaid-cheatsheet.md     # Mermaid diagram reference
│   ├── obsidian/                         # Bundled from kepano/obsidian-skills
│   └── graphify/                         # Knowledge graph engine
├── scripts/
│   ├── push.js                           # npm run push — commit + optional publish
│   └── backup-knowledge-graph.js         # Auto backup to GitHub
├── install.ps1                           # Windows auto-installer
├── install.sh                            # WSL/Linux installer
├── .claude-plugin/
│   └── plugin.json                       # Plugin registry
└── bin/
    └── braindead.js                      # CLI entry point

Updating

/BrainDead update

Or manually:

cd path/to/BrainDead
git pull --ff-only
.\install.ps1        # Windows
./install.sh         # Linux/WSL