jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/openspec/specs/project-graph-lifecycle/spec.md

6.7 KiB
Raw Blame History

Last updated: 2026-06-08

Scope

This spec covers the refactored memory skill layout: memory-vault (renamed from memory-query), memory-project (new), the routing rule in ~/.claude/CLAUDE.md, and the trimmed session-context.sh. The original spec name (project-graph-lifecycle) is retained for path stability.

Requirement 1: Routing rule in ~/.claude/CLAUDE.md

A routing rule block SHALL be added to ~/.claude/CLAUDE.md that tells Claude:

  • Use memory-vault for: conventions, tool behavior, client facts, patterns that generalize beyond one repo.
  • Use memory-project for: codebase structure, module relationships, what exists where in the current repo.
  • Decision heuristic: "Would this be useful outside this repo, next year?" — if yes, vault; if no, project graph.

Scenario: Claude chooses between vault and project graph

  • WHEN Claude needs to answer a question about tool conventions or client context

  • THEN Claude uses memory-vault (vault query, no --graph flag)

  • WHEN Claude needs to answer a question about what modules exist in the current codebase

  • THEN Claude uses memory-project with --graph ./graphify-out/graph.json

Requirement 2: memory-vault skill

The memory-vault SKILL.md SHALL:

2.1 State explicitly that this skill is for cross-project evergreen knowledge — not codebase structure.

2.2 Provide query patterns:

  • graphify query "<topic>" --budget 2000 — explore a topic
  • graphify path "<a>" "<b>" — trace a relationship
  • graphify explain "<node>" — deep-dive a specific node
  • graphify query "<topic>" --dfs --budget 2000 — bounded depth-first

2.3 NOT contain a god-node section or any instruction to start from an injected hub note. Graph traversal entry point is handled internally by graphify.

2.4 Retain the tag-scoped caution note: facet-tag graph edges are not yet verified (ADR-014 open); treat tag-based filtering as experimental.

2.5 Include write guidance pointing to memory-write with the routing heuristic.

Scenario: Claude queries the vault without injected context

  • WHEN no vault graph report is present in session context
  • THEN Claude runs graphify query "<topic>" --budget 2000 directly
  • AND Claude does NOT stall waiting for a god-node entry point

Scenario: Claude stays in vault scope for cross-project questions

  • WHEN the question concerns client conventions or tool behavior
  • THEN Claude queries the vault (no --graph flag)
  • AND Claude does NOT use --graph ./graphify-out/graph.json for this question

Requirement 3: memory-project skill

The memory-project SKILL.md SHALL:

3.1 Cover the onboard lifecycle:

  • graphify extract . --backend ollama --model qwen2.5-coder:7b (from project root)
  • graphify cluster-only . (build community structure for query)
  • Ensure graphify-out/ is present in .gitignore
  • Confirm graphify-out/graph.json exists before reporting complete
  • State that code-only repos use the free AST pass; LLM cost only applies when .md docs are present

3.2 Cover incremental update:

  • graphify update . for routine edits (no --force)
  • graphify update . --force for structural changes (renames, deletions, directory moves)
  • Suggest update after sessions involving significant refactoring

3.3 Cover remove:

  • Delete graphify-out/ when project is inactive or graph is too stale
  • Confirm the graph is always rebuildable via the onboard sequence
  • Leave the .gitignore entry even after removal

3.4 Cover query routing:

  • Use graphify query "<question>" --graph ./graphify-out/graph.json
  • Delegate all query mechanics (traversal, --budget, --dfs, graphify path, graphify explain) to memory-vault — do not duplicate

3.5 Cover graph path discovery:

  • session-context.sh injects the graph path when graphify-out/graph.json exists
  • If no graph path is injected and Claude is in a project context, suggest running the onboard sequence before proceeding with knowledge queries

3.6 State hard constraints:

  • Never commit graphify-out/
  • Model is qwen2.5-coder:7b
  • .gitignore entry for graphify-out/ must survive even if the directory is deleted

Scenario: Claude onboards a new project

  • WHEN a user asks to onboard a project to the memory system
  • THEN Claude runs extract, then cluster-only, then adds the gitignore entry
  • AND Claude confirms graph.json exists before reporting done
  • AND Claude does NOT commit graphify-out/ under any circumstances

Scenario: Claude updates the graph after routine edits

  • WHEN files have been modified but not renamed, deleted, or moved
  • THEN Claude runs graphify update . (no --force)

Scenario: Claude updates the graph after structural changes

  • WHEN files have been renamed, deleted, or directories reorganized
  • THEN Claude runs graphify update . --force to clear ghost nodes

Scenario: Claude starts a session in a project with no graph

  • WHEN no graph path is injected by session-context.sh
  • AND Claude is working in a project context
  • THEN Claude suggests the onboard sequence before knowledge queries
  • AND Claude does NOT silently fall back to vault-only retrieval without noting the gap

Requirement 4: session-context.sh trimmed to project graph pointer

session-context.sh SHALL emit only:

  • The absolute path to <project-root>/graphify-out/graph.json — if and only if that file exists

session-context.sh SHALL NOT emit:

  • Vault graph reports
  • Live convention queries
  • Journal pointers

Scenario: session-context.sh runs in an onboarded project

  • WHEN <project-root>/graphify-out/graph.json exists
  • THEN the script outputs the absolute path to the graph file
  • AND no other memory context is emitted

Scenario: session-context.sh runs in a project with no graph

  • WHEN <project-root>/graphify-out/graph.json does not exist
  • THEN the script outputs nothing (or a minimal "no project graph" note)

Requirement 5: Mirror to .codex/ and .pi/

5.1 .codex/skills/memory-query/ SHALL be renamed to .codex/skills/memory-vault/ with the same SKILL.md content as ~/.claude/plugins/memory/skills/memory-vault/.

5.2 .codex/skills/memory-project/SKILL.md SHALL be created with the same content as ~/.claude/plugins/memory/skills/memory-project/SKILL.md.

5.3 Same renames and additions SHALL be applied to .pi/skills/.

5.4 All three directories (~/.claude/plugins/memory/skills/, .codex/skills/, .pi/skills/) SHALL remain content-identical after this change.

Scenario: Verifying mirror consistency

  • WHEN any of the three skill directories is read
  • THEN the content of memory-vault/SKILL.md is identical across all three
  • AND the content of memory-project/SKILL.md is identical across all three