ontoref/reflection/templates/agent-protocol-upgrade-prompt.md

Agent Protocol Upgrade Prompt

Purpose: Bring an existing ontoref-adopted project up to the agent-aware protocol v2. Covers: just recipe convention compliance, reflection mode step schema, agent CLAUDE.md entry-point, graph readiness, and a full agent simulation smoke test.

Prerequisite: Project already has .ontology/, reflection/modes/, and ontoref installed globally (~/.local/bin/ontoref, via just install-daemon from the ontoref repo). If the project hasn't adopted ontoref at all, run project-full-adoption-prompt.md first.

Substitutions required before use:

• {project_name} — kebab-case project identifier
• {project_dir} — absolute path to project root

---

Phase 0 — Discovery: what is the current state

Run these before touching anything.

cd {project_dir}

# What does ontoref already see about this project?
ONTOREF_ACTOR=agent ontoref describe capabilities

# Just recipe categorization
ONTOREF_ACTOR=agent ontoref describe capabilities \
  | from json | get just_recipes | group-by category | transpose key value \
  | each { |r| { category: $r.key, count: ($r.value | length) } }

# Project flags: which features are detected?
ONTOREF_ACTOR=agent ontoref describe capabilities \
  | from json | get project_flags

# Justfile convention violations
ONTOREF_ACTOR=agent ontoref validate justfile

# Existing reflection modes
ls reflection/modes/*.ncl 2>/dev/null || echo "no modes"

# Ontology graph — see nodes/edges and their level classification
ONTOREF_ACTOR=agent ontoref graph ontology

Identify:

• Which canonical just modules are missing (required: build, test, dev, ci)
• Whether default and help recipes exist in the root justfile
• Whether reflection modes have actor and on_error fields in their steps[]
• Whether .ontology/core.ncl nodes have level fields (for graph coloring)
• Whether reflection/backlog.ncl exists (for has_backlog flag)

---

Phase 1 — Just recipe convention compliance

1a. Run the validator

ONTOREF_ACTOR=agent ontoref validate justfile --fmt json

Act on these fields in the output:

• missing_required_modules — canonical just files that must be created
• missing_required_recipes — default and/or help missing from root justfile
• missing_required_variables — project_root not declared anywhere

1b. Fix missing required modules

For each name in missing_required_modules, create justfiles/{name}.just:

# {name} recipes for {project_name}

[doc("Show {name} help")]
help:
    @just --list

Import it in the root justfile:

import 'justfiles/{name}.just'

Recipe → module mapping:

Module	What goes here
build	Compilation, linking, binary generation, asset bundling
test	Unit, integration, property-based tests
dev	fmt, lint, watch, clean, local dev setup
ci	CI pipeline orchestration (ci-full, ci-lint, ci-test, ci-audit)
distro	Packaging, install-*, release, distribution targets
docs	Documentation generation and serving
nickel	Nickel typecheck, export, contract validation
deploy	Deployment to staging/production environments

Move existing recipes to the correct module file. Group by concern, not by file size.

1c. Fix missing required recipes

If default is missing from root justfile:

default:
    @just --list

If help is missing:

[doc("Show available recipes")]
help:
    @just --list

1d. Fix missing required variables

project_root := justfile_directory()

1e. Verify

ONTOREF_ACTOR=agent ontoref validate justfile
# Expected: "✓ justfile validates against convention"

---

Phase 2 — Reflection mode step schema

For run start / step report / graph <mode-id> to work, each mode NCL file needs steps with the v2 fields. Check what each mode currently has:

for f in reflection/modes/*.ncl; do
  echo "=== $f ==="
  nickel export --import-path $NICKEL_IMPORT_PATH "$f" 2>/dev/null \
    | jq '[.steps[] | {id, actor: (.actor // "MISSING"), on_error: (.on_error // "MISSING")}]'
done

Or via the ontoref CLI:

ONTOREF_ACTOR=agent ontoref describe mode | from json \
  | each { |m| { id: $m.id, steps: ($m.steps | length),
      missing_fields: ($m.steps | where { |s| ($s.actor? | is-empty) or ($s.on_error? | is-empty) } | length) } }

2a. Required fields per step

Each step in steps[] must have:

{
  id         = "kebab-step-id",
  action     = "What this step does (human-readable).",
  actor      = 'Agent,     # 'Human | 'Agent | 'Both
  on_error   = 'Stop,      # 'Stop | 'Continue | 'Retry
  depends_on = [],         # list of { step = "id", kind = 'Always } or { step = "id", kind = 'OnSuccess }
}

actor decision:

• Agent does it autonomously (builds, file writes, nickel export, API calls) → 'Agent
• Human must do it (review, approve, deploy decision) → 'Human
• Either depending on context → 'Both

on_error decision:

• Failure invalidates subsequent steps (build fails → tests cannot run) → 'Stop
• Step can fail without blocking others (optional lint, docs) → 'Continue
• Transient failures should be retried → 'Retry

2b. Verify graph output for each mode

ONTOREF_ACTOR=agent ontoref graph <mode-id>

Each mode should render a flowchart TD with nodes colored by actor class (human/agent/both) and dependency edges. If you see note["Failed to export mode"], the NCL export is broken.

---

Phase 3 — CLAUDE.md agent entry-point

Add this block to .claude/CLAUDE.md. Insert before the last major section or append at the end.

## Agent Entry-Point Protocol

When arriving at this project as an agent, execute these discovery steps in order
before any code changes:

```sh
# 1. Project capabilities — what this project has and can do (JSON for parsing)
ONTOREF_ACTOR=agent ontoref describe capabilities

# 2. Available reflection modes — operational DAGs you can execute
ONTOREF_ACTOR=agent ontoref describe mode

# 3. Start a run before any structured work session
ONTOREF_ACTOR=agent ontoref run start <mode-id> --task "description"

# 4. Report each step as you complete it
ONTOREF_ACTOR=agent ontoref step report <mode-id> <step-id> --status pass|fail|skip

# 5. Verify mode completion (checks all required steps are reported)
ONTOREF_ACTOR=agent ontoref mode complete <mode-id>

Graph output (Mermaid DSL, parseable):

ONTOREF_ACTOR=agent ontoref graph ontology     # ontology nodes + edges
ONTOREF_ACTOR=agent ontoref graph deps         # Rust crate dependency graph
ONTOREF_ACTOR=agent ontoref graph flow         # current run step statuses
ONTOREF_ACTOR=agent ontoref graph <mode-id>    # mode DAG colored by actor

Justfile validation:

ONTOREF_ACTOR=agent ontoref validate justfile  # check against convention schema

The describe capabilities JSON output contains: project_flags (has_rust, has_ui, has_mdbook, has_nats, has_precommit, has_backlog, has_git_remote, open_prs, crates), just_recipes (categorized by canonical module), backlog_pending count, and full ontology/reflection metadata.

---

Phase 4 — Graph readiness

4a. Ontology node levels

graph ontology colors nodes by the level field. Nodes without level fall back to project class (dark neutral). Add level to nodes in .ontology/core.ncl where the distinction matters:

{ id = "my-node", name = "Name", level = 'Practice, ... }
# 'Axiom | 'Tension | 'Practice | 'Project | 'Moment

Validate:

ONTOREF_ACTOR=agent ontoref graph ontology
# classDef coloring should be visible in the Mermaid output

4b. Crate dependency graph (Rust projects only)

ONTOREF_ACTOR=agent ontoref graph deps

Single-crate project — no inter-crate deps to show is the correct output for non-workspace projects. If workspace members are missing, check Cargo.toml [workspace] has members listed.

---

Phase 5 — Smoke test: full agent simulation

cd {project_dir}

# Discovery
ONTOREF_ACTOR=agent ontoref describe capabilities | from json \
  | select project_flags backlog_pending

# List modes — pick one for the test
ONTOREF_ACTOR=agent ontoref describe mode | from json

# Start a run (replace <mode-id> and <first-step-id> with real values from above)
ONTOREF_ACTOR=agent ontoref run start <mode-id> \
  --task "agent protocol upgrade smoke test"

# Pending steps
ONTOREF_ACTOR=agent ontoref run status

# Report one step
ONTOREF_ACTOR=agent ontoref step report <mode-id> <first-step-id> --status pass

# Flow graph — reported step should show as pass
ONTOREF_ACTOR=agent ontoref graph flow

# Complete the run
ONTOREF_ACTOR=agent ontoref mode complete <mode-id>

Expected:

• describe capabilities → parseable JSON, non-empty project_flags and just_recipes
• run start → { run_id, mode, task, started_at }
• run status → all steps pending before any reports
• graph flow → reported step colored pass, rest pending
• mode complete → ok: true if all Stop-on-error steps were reported, else blockers list

---

Checklist

Just recipe convention

• validate justfile returns ok
• Required canonical modules present: build, test, dev, ci
• Root justfile has default and help recipes
• project_root variable declared

Reflection mode step schema

• All modes export cleanly via nickel export
• Every step has actor, on_error, depends_on fields
• graph <mode-id> renders with actor-colored nodes for all modes

CLAUDE.md agent entry-point

• .claude/CLAUDE.md has Agent Entry-Point Protocol section

Graph readiness

• graph ontology renders without errors, node levels correct
• graph deps renders without errors
• graph flow renders after a run with at least one reported step

Smoke test

• describe capabilities parses as JSON without errors
• run start → step report → mode complete cycle completes without errors
• mode complete returns ok: true

Do NOT commit without developer review