# 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
  `<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-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".
