# 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. ```sh 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 ```sh 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`: ```just # {name} recipes for {project_name} [doc("Show {name} help")] help: @just --list ``` Import it in the root `justfile`: ```just 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`: ```just default: @just --list ``` If `help` is missing: ```just [doc("Show available recipes")] help: @just --list ``` ### 1d. Fix missing required variables ```just project_root := justfile_directory() ``` ### 1e. Verify ```sh ONTOREF_ACTOR=agent ontoref validate justfile # Expected: "✓ justfile validates against convention" ``` --- ## Phase 2 — Reflection mode step schema For `run start` / `step report` / `graph ` to work, each mode NCL file needs steps with the v2 fields. Check what each mode currently has: ```sh 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: ```sh 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: ```nickel { 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 ```sh ONTOREF_ACTOR=agent ontoref graph ``` 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. ```markdown ## 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 --task "description" # 4. Report each step as you complete it ONTOREF_ACTOR=agent ontoref step report --status pass|fail|skip # 5. Verify mode completion (checks all required steps are reported) ONTOREF_ACTOR=agent ontoref mode complete ``` Graph output (Mermaid DSL, parseable): ```sh 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 DAG colored by actor ``` Justfile validation: ```sh 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: ```nickel { id = "my-node", name = "Name", level = 'Practice, ... } # 'Axiom | 'Tension | 'Practice | 'Project | 'Moment ``` Validate: ```sh ONTOREF_ACTOR=agent ontoref graph ontology # classDef coloring should be visible in the Mermaid output ``` ### 4b. Crate dependency graph (Rust projects only) ```sh 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 ```sh 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 and with real values from above) ONTOREF_ACTOR=agent ontoref run start \ --task "agent protocol upgrade smoke test" # Pending steps ONTOREF_ACTOR=agent ontoref run status # Report one step ONTOREF_ACTOR=agent ontoref step report --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 ``` 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 ` 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