jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/CLAUDE.md

9.5 KiB
Raw Blame History

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 (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-orchestration, 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 — 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-orchestration (plugins/os-orchestration/) — injects ORCHESTRATION.md (session-orchestration + delegation-economics rules) into all sessions; this repo carries no local override. Eval harness in plugins/os-orchestration/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".