154 lines
10 KiB
Markdown
154 lines
10 KiB
Markdown
# 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` (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 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 `~/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/operational-procedures.md`.
|