Machine-wide agent instructions

Loaded into every Claude Code session on this machine. Other agent runtimes (Codex, Cursor, sub-agents) should also read this file.

Persistent research layer (Obsidian)

This machine has an Obsidian-backed knowledge base that all agents share. Treat it as durable, append-only memory across sessions and across agents.

Vault (working memory + private projects): d:\Vault\AI Vault
Reference libraries (Sciences, Engineering, Math+Compute, Society, Arts+Energy, Walkthroughs, System operating manual): moved to d:\Vault\Compendium\ on 2026-05-21 — also on GitHub at https://github.com/adamhudson777/Compendium
Access: Local REST API plugin on http://127.0.0.1:27123 (vault) — for Compendium use direct filesystem reads
CLI for any agent: node C:/Users/IT_Admin/.claude/bin/obsidian-research.mjs <subcommand> — query now searches both vault (REST API) and Compendium (filesystem walk) by default. Use --vault-only or --compendium-only to restrict scope.
Operating manual (read once per session if unfamiliar): d:\Vault\Compendium\System\AGENTS.md

The contract every agent follows

1. Query before researching. Before WebSearch / WebFetch / deep investigation, run:

# Full-text (fast, exact-token match):
node ~/.claude/bin/obsidian-research.mjs query "your question"
 
# Semantic / vector search (concept-level recall, local embeddings):
node ~/.claude/bin/obsidian-research.mjs query "your question" --semantic --k 8
 
# Hybrid (best — combines both via reciprocal-rank fusion):
node ~/.claude/bin/obsidian-research.mjs query "your question" --hybrid --k 8

Default to --hybrid when looking for prior context — it surfaces concept matches that full-text misses and keyword matches that semantic alone misses. Build on existing notes rather than re-researching.

2. Save what you learn. When research yields a non-obvious finding, save it:

node ~/.claude/bin/obsidian-research.mjs save \
  --title "Concise title" \
  --tags "topic,domain" \
  --source "https://..." \
  --agent "$AGENT_NAME" \
  --body "$(cat <<'EOF'
What you learned, in markdown.
Link to other notes with [[wiki-style]] references.
EOF
)"

Or pipe from stdin: echo "..." | node ~/.claude/bin/obsidian-research.mjs save --title "..." --stdin

3. Log session activity. At natural breakpoints, append a one-line log entry:

node ~/.claude/bin/obsidian-research.mjs log "what I just figured out / decided"

3b. Re-index after a batch of saves. Semantic search relies on a local embedding index. After saving multiple notes in a session, refresh it:

node ~/.claude/bin/obsidian-research.mjs index   # incremental (fast — only re-embeds changed notes)

Auto-capture (WebFetch/WebSearch hook) writes to Sources but does not re-index automatically.

4. Adapt from past notes. Treat saved research as time-stamped claims, not ground truth. Verify against current code/sources before acting on it. Update or supersede notes that turn out to be wrong.

What to save

Save it if: it took non-trivial work to discover, it’s likely useful to a future agent, it contains a finding / decision / non-obvious fact.

Skip it if: it’s already obvious from code/git, it’s ephemeral, or it’s already in a more authoritative doc (CLAUDE.md, README, etc.).

Identity

When saving, set --agent to a stable identity (e.g. claude-code, researcher-subagent, codex-worker-1, cursor). If unsure, set the env var AGENT_NAME once at session start and the CLI will pick it up.

Cross-agent presence (live “who’s working on what right now”)

Multiple Claude Code sessions can run on this machine in parallel — different projects, different windows, sometimes the same project. Each session writes a heartbeat record to ~/.claude/sessions/active/<session-id>.json on every tool use (via the PostToolUse presence-hook.mjs hook). This gives any agent a live view of concurrent activity.

Check on session start

When you start working, run:

node ~/.claude/bin/presence.mjs list

This shows all sessions with a heartbeat in the last 10 minutes — their session-id, project label, age, last tool used, and cwd. If you see another session active in the same project or working on related files, factor that into your plan (don’t fight, don’t duplicate).

JSON form for programmatic consumption: node ~/.claude/bin/presence.mjs list --json.

Combine with the activity log

presence list is machine state (“a session is alive and just ran Edit on X.cs”). For semantic state (“agent X is working on Phase 4 of AgentCreator”), check today’s session log in the vault:

node ~/.claude/bin/obsidian-research.mjs read --path "Research/Sessions/$(date +%F)/log.md"

The activity log is appended via obsidian-research.mjs log "..." and via the WebFetch/WebSearch auto-capture hook. Use it more often when working on shared/concurrent context — a one-line “starting on X” or “decided Y” announcement is cheap and lets other sessions catch up at a glance.

Maintenance

The heartbeat-based view auto-stales: presence files older than 10 min are filtered out of list. Files older than 60 min can be hard-deleted via presence.mjs prune.
A session that crashes leaves a stale presence file. Harmless — it just gets filtered/pruned eventually.
Other agent runtimes (Codex, Cursor, headless claude -p) can participate by piping a JSON payload {session_id, tool_name, tool_input, cwd} into presence-hook.mjs periodically. Claude Code does this automatically via the hook.

Agent registry — the canonical catalog

Every Claude Code subagent on this machine is cataloged in one place, with a selection tree, per-agent description, persistent memory wiring, and the canonical tag each uses for vault saves:

→ C:\Users\IT_Admin\.claude\agents\AGENTS_INDEX.md — read this when you need to pick the right agent for a task.

It lists:

User-level agents at ~/.claude/agents/*.md (auto-loaded in every session): the 8 marketing & design specialists + marketing-design orchestrator + windows-engineer.
Project-scoped agents (auto-loaded only when cwd is inside that project): the 7 tax & books agents at d:\Projects\TaxProfessional\.claude\agents\ (private GitHub: adamhudson777/TaxProfessionals).
Plugin-managed agents at ~/.claude/plugins/cache/ruflo/<plugin>/<ver>/agents/: git-specialist, browser-agent, tester, adr-architect, loop-worker-coordinator.

Cross-project access: project-scoped agents are only auto-loaded when you’re inside their project. From another cwd you can either cd into the project (preferred — agent has its context) or read the .md directly and invoke its prompt manually (degraded). The index notes each agent’s path so this is one-step.

Persistent memory & learning: every agent (user-level, project-scoped, and the relevant plugin agents) pins to the shared learning contract at d:\Vault\Compendium\System\agents-learning-protocol.md. The contract is: query Obsidian first with the agent’s canonical tag, adapt rather than blindly apply, save non-obvious findings with an outcome:* tag, log at breakpoints, re-index after a batch. The canonical-tag table lives in that note. Do not introduce a parallel memory store — ruflo’s AgentDB / ReasoningBank / RVF stack is denylisted at the permission layer.

When you add or deprecate an agent, update both files: the index (AGENTS_INDEX.md) and the protocol’s canonical tag table.

SuperiorAg agents & skills — bulk-installed library

This machine has the full SuperiorAg/Agents and SuperiorAg/Skills libraries installed: 171 agents + 670 skills. They sit alongside the existing marketing-design firm + windows-engineer at ~/.claude/agents/ and ~/.claude/skills/, so they’re auto-loaded in every Claude Code session.

Local vault copy (browseable, source of truth for refresh)

Agents repo: d:\Vault\Agents-main\ — full git clone of github.com/SuperiorAg/Agents. 17 categories: ai-ml, architecture, backend, frontend, mobile, devops-cloud, data-engineering, data-science, security, quality-testing, documentation, language-specialists, integrations, research, product-business, creative-design, meta-orchestration.
Skills repo: d:\Vault\Skills-main\ — full git clone of github.com/SuperiorAg/Skills. 19 categories (above + bio-science, software-engineering).

Browse them in Obsidian or directly. Each agent is a single <slug>.md under a category folder; each skill is a <slug>/SKILL.md plus supporting files.

Refresh workflow

Pull the latest from upstream, then re-install:

# 1. Update the local reference clones in D:\Vault\
cd "d:\Vault\Agents-main"; git pull
cd "d:\Vault\Skills-main"; git pull
 
# 2. Update what's installed under ~/.claude/
node ~/.claude/scripts/install-agents.mjs --update

The --update flag refreshes every installed agent and skill from source. Re-running on already-installed entries is safe (skip-existing).

Adding more agents / skills on demand

If you find an agent or skill in the vault catalog that isn’t installed (or one upstream added new):

node ~/.claude/scripts/install-agents.mjs <agent-slug>           # single agent
node ~/.claude/scripts/install-agents.mjs --skill <skill-slug>   # single skill

The installer scans all category folders to resolve a slug.

Self-Improvement Protocol — appended on install

Every SuperiorAg agent has the Self-Improvement Protocol section appended on install. It tells the agent to read <repo>/.learnings/learnings.jsonl + ~/.claude/learnings/global.jsonl before each task, apply prior lessons, and append a JSONL line on completion (success / failure / correction). The self-improver meta-agent (one of the 171) ratchets the most-important rules into <repo>/.learnings/locked-instructions.md.

Note: this is separate from the Obsidian memory layer described above. The .learnings/ system is per-repo feedback for the SuperiorAg agents specifically; Obsidian remains the canonical cross-session memory for everything else. The two coexist — no conflict.

Installer source

The bootstrap and installer themselves are in the Agents repo:

bootstrap.ps1 / bootstrap.sh — first-time setup (already done on this machine)
install-agents.mjs — staged at ~/.claude/scripts/install-agents.mjs; runnable directly with node

Ruflo (claude-flow) — selectively integrated

This machine has ruflo (formerly claude-flow) integrated as a Claude Code marketplace + a curated subset of plugins + the ruflo MCP server. The local source tree is at d:\Projects\ruflo\.

Hard rule: Obsidian remains the canonical memory layer. Ruflo’s memory stack (AgentDB, RuVector, HNSW indexer, ReasoningBank, RVF, knowledge graph, SONA pattern store) is deliberately not used — it would create a parallel persistent store of the same conceptual content. The deny list in ~/.claude/settings.json blocks the mcp__ruflo__memory_*, agentdb_*, autopilot_*, knowledge_graph_*, rvf_*, ruvector_*, hooks_post_edit, hooks_session_end, intelligence_train, neural_train, daemon_start tools at the permission layer.

Plugins enabled (user scope)

Plugin	What it adds	Backed by
`ruflo-jujutsu`	`/jujutsu`, `git-specialist` agent — diff risk scoring, classification, reviewer suggestion	`mcp__ruflo__analyze_diff*` (stateless)
`ruflo-browser`	`/ruflo-browser`, `browser-agent` — Playwright automation Claude Code lacks natively	`mcp__ruflo__browser_*` (per-session sessions)
`ruflo-testgen`	`/testgen`, `tester` agent — coverage-gap detection and test suggestion	`mcp__ruflo__hooks_coverage-*` (analysis only)
`ruflo-adr`	`/adr create\|list\|status\|supersede\|check\|graph\|search` — file ops on `docs/adr/*.md`	Filesystem only; ignore any `agentdb_*` references in the prompt
`ruflo-loop-workers`	Markdown sugar over native `ScheduleWakeup` and `CronCreate`	Pure prompt wrappers

Skills — many are discoverable, most are off-limits

The harness auto-discovers SKILL.md bundles from d:\Projects\ruflo\.agents\skills\<name>\ when ruflo’s tree is in the cwd. Many of these create or manipulate parallel memory stores. Do not invoke any of these via the Skill tool:

agentdb-advanced, agentdb-learning, agentdb-memory-patterns, agentdb-optimization, agentdb-vector-search
reasoningbank-agentdb, reasoningbank-intelligence
hive-mind-advanced (writes to hive-mind namespace in AgentDB)
flow-nexus-* (cloud platform, requires auth + writes to flow-nexus tenant)
v3-memory-unification, v3-integration-deep, v3-core-implementation, v3-ddd-architecture, v3-cli-modernization, v3-mcp-optimization, v3-performance-optimization, v3-security-overhaul, v3-swarm-coordination (these are ruflo’s own dev-internal skills, not for use by other projects)
worker-benchmarks, worker-integration (ruflo dev internals)
swarm-orchestration, swarm-advanced, hooks-automation (writes to AgentDB by default; native Task + SendMessage covers the same ground without the memory side-effect)

Safe to invoke: agentic-jujutsu, browser, pair-programming, performance-analysis, verification-quality, skill-builder, sparc-methodology, stream-chain, github-* (when working on GitHub repos), claude-api. These are stateless or use the project’s own files.

Do NOT do these things

Do not run claude plugin install ruflo@ruflo (the umbrella). Its hooks.json registers PostToolUse hooks on Write|Edit|MultiEdit that pipe through npx claude-flow@alpha hooks post-edit --update-memory true — every edit would write to AgentDB, creating the parallel memory layer.
Do not run npx claude-flow init or npx ruflo init. Rewrites .claude/settings.json with daemon autostart and 12 background workers (audit/optimize/consolidate/etc. — real polling processes).
Do not run npx claude-flow daemon start. Spawns the 12 workers, all of which write to AgentDB.
Do not enable ruflo-cost-tracker, ruflo-autopilot, ruflo-rag-memory, ruflo-agentdb, ruflo-intelligence, ruflo-knowledge-graph, ruflo-ruvector, ruflo-rvf, ruflo-observability — all create or read from AgentDB.

What to do when something says “store in memory”

If a ruflo command, skill, or agent prompt tells you to store something in mcp__ruflo__memory_* or AgentDB, route it to Obsidian instead via node ~/.claude/bin/obsidian-research.mjs save .... The deny list will block the ruflo memory call regardless.

Marketing & design firm (subagents)

This machine has a full-service marketing & design firm installed as user-level subagents in ~/.claude/agents/ (full catalog: ~/.claude/agents/AGENTS_INDEX.md). Whenever you need to produce a customer-facing landing page, marketing site, product showcase, or launch site for any product — whether you just built it, another agent built it, or it lives in the current working directory — delegate to marketing-design. Don’t try to write the marketing site yourself.

The orchestrator runs an 8-specialist pipeline that produces a deployable, optimized site in marketing-site/ (a sibling subdirectory — never collides with the parent project):

brand-strategist → palette, typography, voice, logo direction (BRAND.md)
copywriter → headlines, value props, CTAs (COPY.md)
designer → picks stack (Next.js / Astro / SvelteKit + Tailwind), builds the site
seo-specialist → meta, OG/Twitter cards, schema.org, sitemap, robots
conversion-specialist → funnel optimization, CTA tagging
analytics-specialist → one provider (Plausible / PostHog / GA4 / Fathom), conversion events, UTM, consent
accessibility-auditor → WCAG 2.2 AA pass
performance-engineer → Core Web Vitals + Lighthouse pass

All eight inherit your session’s model. They coordinate through shared files (BRIEF.md, BRAND.md, COPY.md, OPTIMIZATION_NOTES.md) — not memory — so each runs in its own context window. Invoke with Task(subagent_type="marketing-design", ...) and let it dispatch the others.

Other notes

The current working directory is not always the Obsidian vault. Vault path is fixed at d:\Vault\AI Vault. Reference libraries (Compendium) at d:\Vault\Compendium\.
The MCP server (obsidian in ~/.claude.json) loads at Claude Code startup and provides cleaner native tools, but the CLI works immediately without restart.
API key is in ~/.claude/obsidian.json. Treat it as a secret; never echo it into committed files or chat output.

Standing order: Operator capability — drive the desktop and a browser

This machine has an Operator capability wired in at the user level. It is the standard way to take screenshots, click, type, drive a real browser, and visually verify a build before declaring it done. Every agent — current and future — should reach for it whenever a task can only be confirmed by seeing the running app.

Two MCP servers provide the primitives, both registered in ~/.claude/settings.json with full auto-approval (no permission prompts):

Server	Prefix	What it does
`desktop-operator`	`mcp__desktop-operator__*`	Real mouse/keyboard, screenshot of any region or full screen, window focus/list/active, hotkey chords, scroll. Python + pyautogui + mss + pygetwindow. Source: `~/.claude/mcp-servers/desktop-operator/server.py`. Skipped on headless hosts.
`playwright`	`mcp__playwright__*`	Microsoft’s official Playwright MCP — browser navigate/click/fill/screenshot/eval/wait with robust selectors and accessibility tree. Auto-downloads browsers on first use.

The playbook is the operator skill at ~/.claude/skills/operator/SKILL.md. It documents the screenshot-act-verify loop, the browser-vs-desktop decision tree, the destructive-action confirmation rule, and anti-patterns. Invoke it via the Skill tool when you need the methodology in context, or read it directly. Every agent that touches a UI surface should know its contents.

Safety floor (non-negotiable):

The PyAutoGUI failsafe is on — mouse to the top-left corner (0,0) aborts the next desktop call. Don’t disable it; it’s the kill switch.
Stop and ask the user before clicking Delete / Remove / Uninstall / Sign out / Disconnect / Reset / Discard / Don’t-Save; before confirming “Are you sure / cannot be undone / Permanently” dialogs; before sending messages to non-self recipients; before payment fields; before closing a window with a Save prompt; before UAC / firewall / antivirus changes.
Always screenshot before the first action of a step, and screenshot after to confirm. Never click from memory. Don’t pixel-hunt with offset loops — re-screenshot.
Use wait sparingly (200–800ms typical). For browser waits, prefer Playwright’s selector-based waits over fixed sleeps.

When to skip it: pure code edits, headless test runs, anything verifiable from disk or stdout. Operator tools are for the cases where you genuinely need to see the screen.

Compendium

Explorer

CLAUDE