269 lines
8.7 KiB
Markdown
269 lines
8.7 KiB
Markdown
# Ontoref Protocol Update — Ontology Enrichment Prompt
|
|
|
|
**Purpose:** Bring `{project_name}` up to the current ontoref protocol version and enrich its
|
|
ontology to reflect the project's actual state. Run this prompt in the project's Claude Code
|
|
session with ontoref available.
|
|
|
|
**Substitutions required before use:**
|
|
- `{project_name}` — kebab-case project identifier
|
|
- `{project_dir}` — absolute path to project root
|
|
|
|
**Requires:** `ontoref` installed globally (`just install-daemon` from the ontoref repo).
|
|
|
|
---
|
|
|
|
## Bootstrap — source ontoref env vars
|
|
|
|
Before running any direct `nickel export` command, source the ontoref env into the current
|
|
shell. This sets `NICKEL_IMPORT_PATH` and `ONTOREF_ROOT` without launching a full command:
|
|
|
|
```sh
|
|
cd {project_dir}
|
|
. $(which ontoref) --env-only
|
|
# NICKEL_IMPORT_PATH and ONTOREF_ROOT are now available in this shell session
|
|
```
|
|
|
|
All `nickel export` commands in this prompt assume these vars are set.
|
|
|
|
---
|
|
|
|
## Context for the agent
|
|
|
|
You are enriching the ontoref ontology for project `{project_name}`. The ontology lives in
|
|
`.ontology/` and the reflection layer in `reflection/`. Your goal is to make the ontology
|
|
reflect current architectural reality — not aspirational state, not stale state.
|
|
|
|
Read the project's `.claude/CLAUDE.md` and any `CLAUDE.md` at root before starting. Understand
|
|
what the project actually does. All changes must pass `nickel export` cleanly.
|
|
|
|
---
|
|
|
|
## Phase 1 — Infrastructure: add missing v2 files
|
|
|
|
Run the infrastructure detection and update steps. These are additive — nothing is overwritten.
|
|
|
|
```sh
|
|
cd {project_dir}
|
|
|
|
# Step 1a: detect missing files
|
|
test -f .ontology/manifest.ncl && echo "manifest: present" || echo "manifest: MISSING"
|
|
test -f .ontology/connections.ncl && echo "connections: present" || echo "connections: MISSING"
|
|
|
|
# Step 1b: add manifest.ncl if missing (template installed with ontoref)
|
|
test -f .ontology/manifest.ncl || \
|
|
sed 's/{{ project_name }}/{project_name}/g' \
|
|
"$ONTOREF_ROOT/templates/ontology/manifest.ncl" > .ontology/manifest.ncl
|
|
|
|
# Step 1c: add connections.ncl if missing
|
|
test -f .ontology/connections.ncl || \
|
|
sed 's/{{ project_name }}/{project_name}/g' \
|
|
"$ONTOREF_ROOT/templates/ontology/connections.ncl" > .ontology/connections.ncl
|
|
|
|
# Step 1d: validate both files parse
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/manifest.ncl \
|
|
> /dev/null && echo "manifest: ok"
|
|
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/connections.ncl \
|
|
> /dev/null && echo "connections: ok"
|
|
```
|
|
|
|
If either validation fails, read the file, fix the import path or schema mismatch, and revalidate
|
|
before continuing.
|
|
|
|
---
|
|
|
|
## Phase 2 — Audit: understand current state
|
|
|
|
Run these commands and read the output before making any changes to core.ncl or state.ncl.
|
|
|
|
```sh
|
|
# Full project self-description (identity, axioms, practices, gate)
|
|
ontoref describe project
|
|
|
|
# Semantic diff vs HEAD — shows what changed since last commit
|
|
ontoref describe diff
|
|
|
|
# What modes are available, what gates allow
|
|
ontoref describe guides
|
|
|
|
# Current gate state and dimension health
|
|
ontoref describe gate
|
|
|
|
# API surface available (requires daemon running)
|
|
ontoref describe api
|
|
```
|
|
|
|
Read the output of each command. Note:
|
|
- Which dimensions are in non-ideal states and why
|
|
- Which practices have no corresponding nodes in core.ncl
|
|
- What the diff reports as added/removed/changed since HEAD
|
|
- Whether the gate is aligned with what the project actually does today
|
|
|
|
---
|
|
|
|
## Phase 3 — Enrich core.ncl
|
|
|
|
Open `.ontology/core.ncl`. For each of the following, apply only what is actually true:
|
|
|
|
### 3a. Nodes — add missing, update stale descriptions
|
|
|
|
For any practice or capability the project has implemented since the last ontology update,
|
|
add a node with:
|
|
- `id` — kebab-case, stable identifier
|
|
- `level` — `'Axiom | 'Tension | 'Practice | 'Project | 'Moment`
|
|
- `description` — one sentence, present tense, what it IS (not what it should be)
|
|
- `adrs` — list any ADR IDs that govern this node
|
|
|
|
Do NOT add aspirational nodes. If a feature is not yet implemented, do not add it.
|
|
|
|
### 3b. Edges — declare real dependencies
|
|
|
|
For any new nodes, declare edges to the nodes they depend on or implement:
|
|
|
|
```nickel
|
|
{ from = "new-node-id", to = "existing-node-id", kind = 'Implements }
|
|
```
|
|
|
|
Valid edge kinds: `'Implements | 'Depends | 'Extends | 'Supersedes | 'Tensions`
|
|
|
|
### 3c. Tensions — update descriptions
|
|
|
|
For tension nodes (`level = 'Tension`), update the description to reflect the current root cause
|
|
if it has changed. Tensions describe real trade-offs the project has made, not theoretical ones.
|
|
|
|
After editing, validate:
|
|
```sh
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/core.ncl > /dev/null
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 4 — Update state.ncl
|
|
|
|
Open `.ontology/state.ncl`. For each dimension:
|
|
|
|
1. Read `current_state` and `transition` conditions
|
|
2. Check whether a transition condition has been met based on recent work
|
|
3. If the project has advanced: update `current_state` to the new state
|
|
4. Update `blocker` and `catalyst` to reflect current reality (not stale reasoning)
|
|
|
|
Do NOT advance a dimension optimistically. Only advance if the transition condition is
|
|
demonstrably met (code exists, tests pass, ADR written — not "in progress").
|
|
|
|
After editing:
|
|
```sh
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/state.ncl > /dev/null
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 5 — Fill manifest.ncl
|
|
|
|
Open `.ontology/manifest.ncl`. Declare any content assets the project has:
|
|
|
|
- Branding assets (logos, icons) in `assets/branding/` or equivalent
|
|
- Architecture diagrams in `docs/`, `assets/`, or `architecture/`
|
|
- Screenshots or demo recordings
|
|
- Agent prompt templates in `reflection/templates/`
|
|
- Mode step templates in `reflection/templates/`
|
|
|
|
For each asset, use `m.make_asset` with accurate `source_path` (relative to project root),
|
|
correct `kind`, and a one-sentence `description`. Only declare assets that actually exist on disk.
|
|
|
|
Check:
|
|
```sh
|
|
ls assets/ 2>/dev/null; ls docs/ 2>/dev/null; ls reflection/templates/ 2>/dev/null
|
|
```
|
|
|
|
After editing:
|
|
```sh
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/manifest.ncl > /dev/null
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 6 — Declare connections.ncl
|
|
|
|
Open `.ontology/connections.ncl`. Declare cross-project relationships if they exist:
|
|
|
|
- `upstream` — projects this one depends on or consumes APIs from
|
|
- `downstream` — projects that consume this one's APIs or outputs
|
|
- `peers` — symmetric sibling services with shared concerns
|
|
|
|
For each connection: `project` must be a slug registered in the shared daemon, `node` is an
|
|
ontology node id in that project, `via` is `"http" | "local" | "nats"`.
|
|
|
|
If no cross-project relationships exist, leave all arrays empty — that is valid and correct.
|
|
Do NOT invent connections.
|
|
|
|
After editing:
|
|
```sh
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" .ontology/connections.ncl > /dev/null
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 7 — Migrate ADR check_hint (if present)
|
|
|
|
Check for deprecated `check_hint` fields:
|
|
```sh
|
|
grep -rl 'check_hint' {project_dir}/adrs/ 2>/dev/null
|
|
```
|
|
|
|
If any files are found, for each ADR:
|
|
|
|
1. Read the `check_hint` string — it describes what to verify
|
|
2. Map it to the closest typed `check` variant:
|
|
- Shell command → `'NuCmd { cmd = "...", expect_exit = 0 }`
|
|
- File search (grep/rg) → `'Grep { pattern = "...", paths = ["..."], must_be_empty = true }`
|
|
- Cargo.toml dep check → `'Cargo { crate = "...", forbidden_deps = ["..."] }`
|
|
- File presence → `'FileExists { path = "...", present = true }`
|
|
- API response → `'ApiCall { endpoint = "...", json_path = "...", expected = ... }`
|
|
3. Replace `check_hint` with `check` using the typed variant
|
|
4. Validate:
|
|
```sh
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" adrs/adr-NNN-*.ncl > /dev/null
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 8 — Final validation
|
|
|
|
Run all validations in sequence:
|
|
|
|
```sh
|
|
# All .ontology/ files
|
|
for f in .ontology/core.ncl .ontology/state.ncl .ontology/gate.ncl \
|
|
.ontology/manifest.ncl .ontology/connections.ncl; do
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" "$f" > /dev/null \
|
|
&& echo "ok: $f" || echo "FAIL: $f"
|
|
done
|
|
|
|
# All ADRs
|
|
for f in adrs/adr-*.ncl; do
|
|
nickel export --import-path "$NICKEL_IMPORT_PATH" "$f" > /dev/null \
|
|
&& echo "ok: $f" || echo "FAIL: $f"
|
|
done
|
|
|
|
# Re-run describe diff to confirm changes are coherent
|
|
ontoref describe diff
|
|
|
|
# Final project state
|
|
ontoref describe project
|
|
```
|
|
|
|
---
|
|
|
|
## Delivery
|
|
|
|
Report:
|
|
1. Files changed and what was changed in each
|
|
2. Nodes added / updated / removed in core.ncl
|
|
3. Dimension state transitions applied in state.ncl
|
|
4. Assets declared in manifest.ncl
|
|
5. Connections declared in connections.ncl
|
|
6. ADRs migrated from check_hint to typed check
|
|
7. Any validation errors that could not be resolved (with reason)
|
|
|
|
Do NOT commit. The developer reviews the diff before committing.
|