# 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](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](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-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 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`.