| name | score-api |
| description | Unified facade over the five Score suites ( parse , symbol , semantic , analysis , discovery ) providing a single LLM friendly surface for querying any Clef project s structure , symbols , semantics , data flows , and search indexes . Every Clef app gets ScoreApi registered automatically LLMs can immediately ask questions about the codebase without configuration . Actions are designed for natural language invocation : parameter names read as English , results are structured for tool use consumption , and error variants include actionable suggestions |
ScoreApi
Unified facade over the five Score suites ( parse , symbol , semantic , analysis , discovery ) providing a single LLM friendly surface for querying any Clef project s structure , symbols , semantics , data flows , and search indexes . Every Clef app gets ScoreApi registered automatically LLMs can immediately ask questions about the codebase without configuration . Actions are designed for natural language invocation : parameter names read as English , results are structured for tool use consumption , and error variants include actionable suggestions
Design Principles
- Query, Don't Grep: Score provides structured queries — use them instead of raw file reading.
- Concepts Are Independent: No concept references another — all coupling is through syncs.
- Variants Over Exceptions: Every action outcome is an explicit named variant.
Step-by-Step Process
Step 1: Survey the Architecture
List all concepts to understand the application's domain model and concept graph.
Step 2: Inspect a Concept
Get full details of a concept — purpose, type parameters, actions, state fields, invariants.
Arguments: $0 name (string)
Step 3: Map the Sync Network
List all syncs to understand cross-concept coordination rules.
Step 4: Trace Static Action Flows
Follow the chain of effects from any starting action through syncs to downstream actions, computed from the registered sync graph (no flow needs to have run).
Arguments: $0 startConcept (string), $1 startAction (string)
Step 5: Trace a Runtime Flow
Given a flowId returned by an invokeConcept call, return the full causal action+sync tree (FlowTrace) joined with typed step records (RuntimeFlow) and the DTG overlay path. Counterpart to getFlow — answers 'what actually happened' rather than 'what could happen'.
Arguments: $0 flowId (string)
Step 6: Resolve a Stack Trace to Concepts + AST
Parse raw stack-trace text and resolve every frame to concept, action, handler, symbol, the precise tree-sitter AST node at the position (kind/text/line range), and an ancestor chain. Use as the entry point for any error investigation.
Arguments: $0 stackTrace (string)
Step 7: Correlate a Stack Trace with a Flow
Join a stack trace and a flowId by (concept, action) — identifies which step in the runtime flow corresponds to each frame, with isFailing flagging the step whose variant is non-ok. The single-shot answer to 'which step in the flow caused this error'.
Arguments: $0 stackTrace (string), $1 flowId (string)
Step 8: Search the Codebase
Use natural language search across the project. Combines embeddings, text, and symbols.
Arguments: $0 query (string), $1 limit (int)
Step 9: Analyze Dependencies
Trace dependencies and dependents to understand impact before making changes.
Arguments: $0 symbol (string), $1 edgeKinds (string)
Anti-Patterns
Bypassing Score for raw file access
Reading .concept files directly instead of using Score queries — misses parsing, validation, and cross-references.
Bad:
# Manually grep for concept actions
grep -r "action create" repertoire/
Good:
# Use Score API
score listConcepts
score getConcept --name User
score getFlow --from User/create
Assuming concept coupling
Looking for direct references between concepts — concepts are independent by design.
Bad:
# Wrong: searching for concept-to-concept imports
grep "import.*from.*User" repertoire/profile/
Good:
# Right: find syncs that connect User and Profile
score listSyncs --involves User,Profile
