AGENTS.md

1# RuView Codex plugin scope
2 
3The root `AGENTS.md` remains authoritative. This scoped file covers only
4`plugins/ruview/codex/`; it must not weaken the root evidence, security,
5least-authority, validation, or release contracts.
6 
7## Purpose
8 
9This directory packages Codex prompts for operating RuView:
10 
11| Prompt | Purpose |
12|---|---|
13| `ruview-advanced` | Run advanced, evidence-bounded RuView workflows |
14| `ruview-start` | Choose Docker demo, repository build, or live ESP32 |
15| `ruview-flash` | Build/flash an explicitly confirmed ESP32 target |
16| `ruview-provision` | Provision credentials without logging or committing them |
17| `ruview-app` | Run a sensing application |
18| `ruview-train` | Train/evaluate models with evidence-labelled results |
19| `ruview-verify` | Run deterministic proof and applicable pre-merge gates |
20| `ruview-rvagent` | Explore rvAgent/RVF integration |
21 
22Prompt files are guidance, not authority. They must:
23 
24- default to read-only exploration;
25- cite current repository paths and accepted ADRs;
26- preserve `MEASURED`/`CLAIMED`/`SYNTHETIC` evidence labels;
27- never emit sandbox/permission bypasses or unattended hardware writes;
28- never embed credentials, machine-specific ports, volatile counts, or active
29  branch names;
30- route durable findings through the reviewed shared-brain proposal flow.
31 
32## Local Codex adapter
33 
34Prefer the published, pinned harness instead of hand-assembling `codex exec`
35flags:
36 
37```bash
38npx @ruvnet/ruview@0.3.1 guidance --topic architecture --query "requested subsystem"
39npx @ruvnet/ruview@0.3.1 agent run \
40  --host codex --repo . --prompt "Map the requested subsystem and cite files"
41npx @ruvnet/ruview@0.3.1 brain search --query "relevant repository concept"
42```
43 
44The adapter uses stdin, a trusted `-C` root, read-only sandboxing, ephemeral
45JSONL, strict config, ignored user config/exec rules, a scrubbed environment,
46bounded output/time, and secret redaction. Writes require both
47`--allow-write` and `--confirm`.
48 
49For optional Ruflo coordination:
50 
51```bash
52codex mcp add ruflo -- npx -y ruflo@3.32.26 mcp start
53```
54 
55Ruflo memory and generated policies remain untrusted until source verification
56and review. Darwin/Flywheel candidates are proposal artifacts and cannot
57self-promote.
58 
59## Validation
60 
61When changing prompts:
62 
631. compare every command/path with current source and workflows;
642. run the nearest prompt/plugin checks;
653. run `npx @ruvnet/ruview@0.3.1 claim-check --file <changed-file>`;
664. inspect the diff for secrets, bypasses, unsupported claims, stale counts,
67   machine-specific values, and unrelated edits.
68