331 lines
10 KiB
Markdown
331 lines
10 KiB
Markdown
# 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 <mode-id>` 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 <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.
|
|
|
|
```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 <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):
|
|
```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-id> # 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 <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
|