cc-os/CLAUDE.md

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 the docs/implementation-status.md index and its docs/implementation-status/ leaf files (read 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 index: headline timeline + per-component one-liners. Full detail (per-plugin build history, eval-harness records) lives in leaf files under docs/implementation-status/, read on demand; plugin rename/cache-refresh runbooks are in docs/implementation-status/operational-procedures.md.
• 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). docs/implementation-status.md is the index; full detail per item is in its leaf files under docs/implementation-status/ — read the relevant leaf 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 (orchestration/delegation rules, kickoff conventions, standing safety, decision-memo format) 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.
• os-backlog (plugins/os-backlog/) — git-issues backlog surface (ADR-0042 retired Planka 2026-07-16): tracker routing (forgejo:/github:/repo: in .cc-os/config), issue-create/issues CLI, capture/list/route skills, ten-label taxonomy with human-only next; non-repo/ops work lives in the private jared/ops Forgejo repo.
• Graphify v0.8.31 (~/.local/bin/graphify; PyPI package is graphifyy, double-y) — vault graph at ~/Documents/SecondBrain/graphify-out/, per-project graphs at <project-root>/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-tickets) 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 per the index+progressive-disclosure convention: a one-line headline entry in docs/implementation-status.md plus the detail in the relevant docs/implementation-status/<component>.md leaf file (create one if needed; don't restate what an ADR already records), and (c) update the design paragraph in THIS file only if the design itself changed. Never append status history to this file, and never let the index file regrow into a changelog — the os-doc-hygiene file_length signal (400 lines / ~4k tokens) enforces this.
• Plugin and skill naming: before naming ANY new cc-os plugin, skill, or slash command, Read plugins/cc-architect/references/conventions/cc-os-naming.md (canonical repo copy; the SecondBrain vault note of the same name now defers to it) 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/operational-procedures.md.