# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. It is orientation only — implementation history, component details, and operational procedures live in [docs/implementation-status.md](docs/implementation-status.md) (read it on demand, e.g. before touching a plugin or claiming something isn't built yet). ## What this repository is `cc-os` is the user's **personal operating layer for Claude Code**: the family of always-on, globally installed `os-*` plugins that run on every machine the user works from, plus the research/evals that inform them. The founding piece is a **cross-project memory system** (for a multi-client freelancer), but the scope is the whole operating layer — memory, decisions, process/backlog management, status, notifications — and the long-term intent is that the `os-*` plugins are **aware of each other and cooperate** (ADR-023). By contrast, `~/dev/cc-plugins` holds optional, as-needed plugins; anything that should be ambient on every machine belongs here. Everything is markdown-as-truth: specs, ADRs, and the build plan in `docs/` are the source of truth for what is being built. When asked to "build," work from the staged tasks in `docs/memory-system/04-build-plan.md`, not ad hoc. ## Directory layout Numbered files within a directory are not a required reading order — read the one whose topic you need. - **`docs/adr/`** — the ADR system (one file per decision + generated `README.md` index), managed via `/os-adr:*` skills. Migrated 2026-07-12 from the monolithic `docs/memory-system/03-architecture-decisions.md`, which is retained as the historical source (provenance: `migration_source` frontmatter) but is no longer where new decisions go. - **`docs/memory-system/`** — the design of the memory system itself. `02-system-design.md` is the architecture, `03-architecture-decisions.md` is the historical ADR log (see `docs/adr/` above), `04-build-plan.md` the build outline with step status, `06-graphify-evaluation.md` justifies the Graphify pivot. - **`docs/implementation-status.md`** — the status timeline, full per-component detail for every shipped plugin (os-vault, os-context, os-status, os-doc-hygiene, os-adr), eval-harness records, and plugin rename/cache-refresh procedures. - **`docs/graphify/`** — verified handbook for the Graphify knowledge-graph tool. Skim `00-README.md` for the model; keep `09-best-practices-checklist.md` open when running it. Claims are provenance-tagged (`[github]` trustworthy; `[interview]` / `[unverified claim]` not). - **`graphify-interview`, `memory-systems-compared060326`** (repo root) — raw source transcripts. Only open to trace a claim's origin; treat as *intent*, not *fact*. - **`plugins/`** — source of the global plugins, symlinked into `~/.claude/plugins/`. - **`openspec/`** — spec-driven change management (see workflow below). - **`.claude/`, `.codex/`, `.pi/`** — **identical** copies of the OpenSpec skills for three AI assistants. Only open when changing a skill — and mirror any change across all three. ## The current design in one paragraph This is a work in progress, not a frozen spec; **when a conversation changes the design, update this paragraph (and the relevant `docs/memory-system/` files + an ADR) to match.** Two memory types kept as **separate systems**: **episodic** ("what happened, when") handled by **memsearch** (Milvus Lite, embedded, single global store for ALL clients by design — ADR-015), and **semantic/knowledge** ("how do we…") handled by the existing **`~/Documents/SecondBrain` Obsidian vault** as the single source of truth (ADR-012). Notes keep `summary` + six flat namespaced facets (`type/`/`client/`/`project/`/`domain/`/`tool/`/`convention/`) plus `scope/` (ADR-011); hierarchy comes from hub notes, wikilinks, and Graphify graph edges — not nested tags (Graphify is a structure extractor, not a topic clusterer; hubs are author-provided, ADR-014). The vault is queried via a **Graphify knowledge graph** (local Ollama SLM for doc extraction, tree-sitter AST for code); Graphify replaced the originally-planned Ruby/SQLite tag-index CLI (2026-06-03 pivot). Retrieval is hook-injected + on-demand; freshness is lazy (write-time hook + SessionStart reconcile, no daemon); the vault and memsearch store auto-sync to private Forgejo repos via SessionEnd hooks. Ships as a global Claude Code plugin (`os-vault`) with skills. Projects are onboarded one at a time; bulk vault migration is deferred to last (ADR-013). ## Implemented components (inventory) All build-plan steps required for the memory system are complete (2026-06-15). Full detail for each item is in [docs/implementation-status.md](docs/implementation-status.md) — read it before modifying any of these: - **os-vault** (`plugins/os-vault/`) — vault write/query/reorganize/onboard-project/ design-template skills, SessionStart/End hooks, memsearch + vault git sync. Write-behavior eval harness in `plugins/os-vault/eval/`. - **os-context** (`plugins/os-context/`, renamed 2026-07-13 from os-orchestration) — a prompt-composer SessionStart plugin: concatenates `prompts/session-start/*.md` (currently just `10-orchestration.md`, the session-orchestration + delegation-economics rules) into one additionalContext block for all sessions; this repo carries no local override. Eval harness in `plugins/os-context/eval/`. - **os-status** (`plugins/os-status/`) — aggregated deterministic SessionStart checks (subagent-model env override, ADR system present, vault hub note present). ADR-022. - **os-doc-hygiene** (`plugins/os-doc-hygiene/`) — stale/bloated-doc monitoring; check/clean/status/sweep skills. - **os-adr** (`plugins/os-adr/`) — ADR system: Ruby `lib/adr/` + CLIs, create/init/migrate/ find skills; Eval A/B/C harnesses. cc-os retrofit done 2026-07-12 (promoted ahead of pilots — ADR-020 amendment / `docs/adr/0020`); remaining rollout: pilot projects one at a time, then wider. - **Graphify** v0.8.31 (`~/.local/bin/graphify`; PyPI package is `graphifyy`, double-y) — vault graph at `~/Documents/SecondBrain/graphify-out/`, per-project graphs at `/graphify-out/` (gitignored); both disposable/rebuildable. - **memsearch** v0.4.6 (marketplace plugin) — `~/.memsearch/memory/YYYY-MM-DD.md` daily files + Milvus index; `/memory-recall`, `/memory-config`. **Eval discipline (applies to every harness above):** scenario Task blocks are held-out — never run them informally; reserve sets are never even read informally. Before designing or running any autoresearch eval, Read `~/Documents/SecondBrain/howto/running-autoresearch-skill-evals.md`. Wording loops for os-adr Eval B, os-vault WS2, and os-orchestration WS4 are complete and shipped (2026-07-04/07/08); their run-sets AND reserves are contaminated for future wording tuning — next signal is production IRL session audits. ## Issue tracking Issues (created via `/to-issues`) live on self-hosted Forgejo (`jared/cc-os`), queried with the `tea` CLI — not GitHub/`gh`. See `docs/issue-workflow.md`. ## OpenSpec workflow Changes are managed spec-driven via OpenSpec. Use the matching skills rather than editing spec files by hand: `openspec-explore`, `openspec-propose`, `openspec-apply-change`, `openspec-verify-change`, `openspec-archive-change` (slash commands under `/opsx:*`). Live changes in `openspec/changes/`, completed in `openspec/changes/archive/`, stable specs in `openspec/specs/`. `openspec/config.yaml` uses `schema: spec-driven`; project context for OpenSpec artifacts comes from `docs/` and this file. ## Conventions specific to this repo - **Provenance discipline:** when writing about Graphify or anything sourced from the interview transcripts, keep the inline source tags and never promote an `[interview]` / `[unverified claim]` to fact without checking a primary source (the GitHub repo is the authority; anchored to Graphify v0.8.30). - **Dates are absolute** (e.g. `2026-06-03`); design docs carry a `_Last updated:_` / status line — keep these current when editing. - **Decisions live in ADRs** in `docs/adr/` (index: `docs/adr/README.md`). Don't silently reverse a locked decision; record the superseding decision via `/os-adr:create` with the reasoning. **When** a task involves an architecture-level choice, or changes/replaces an approach this codebase already uses (a library, a convention, a plugin structure) → **first** run `/os-adr:find` to check whether a recorded decision covers it, and **when** you make such a choice → record it with `/os-adr:create`. A task that reverses an Accepted ADR is not complete until the superseding ADR exists. - **Keep records current:** when a build step completes, (a) mark it done in `docs/memory-system/04-build-plan.md`, (b) record it in `docs/implementation-status.md` (timeline entry + component pointer), and (c) update the design paragraph in THIS file only if the design itself changed. Never append status history to this file — it goes in implementation-status.md. - **Plugin and skill naming:** before naming ANY new cc-os plugin, skill, or slash command, Read `~/Documents/SecondBrain/cc-os-plugin-skill-naming-convention.md` and follow it. In brief: plugins are `os-[domain]`; skills are verb-first kebab-case, invoked as `/os-[domain]:[verb]`; no `commands/` dispatcher directories; **never set a `name:` field in SKILL.md frontmatter** (it collapses the slash command to a bare unnamespaced form). - **After editing any plugin source** (SKILL.md, hooks, CLIs), run `bin/refresh-plugins` — source edits don't reach sessions until the cache is refreshed. Rename/move procedure and cache details: docs/implementation-status.md → "Operational procedures".