nyldn · nyldn · Aug 23, 2026 · Aug 23, 2026
@@ -1,31 +1,88 @@
-# AI Optimizer contributor instructions
+# AI Optimizer agent instructions
 
 AI Optimizer is a public, macOS-only diagnostic and narrowly owned maintenance
-CLI for Claude Code, Codex, MCP, skills, and coding workspaces.
-
-## Safety invariants
-
-- `doctor` and `scan` are read-only.
-- Never print command arguments, environment values, credentials, MCP endpoint
-  values, or workspace file contents.
-- Mutating commands may write only AI Optimizer-owned configuration, reports,
-  release installation paths, and launchd label
-  `io.github.nyldn.ai-optimizer.daily`.
-- Never silently edit or upgrade Claude Code, Codex, MCP servers, skills,
-  companion tools, or repositories.
-- Keep runtime code compatible with `/usr/bin/ruby` 2.6 and standard library
-  only.
-- Every lifecycle change needs an isolated install/uninstall or
-  schedule/unschedule round-trip test.
-
-## Verification
-
-Run all of these before claiming completion:
-
-```sh
-/usr/bin/ruby -w test/test_all.rb
-scripts/check-syntax.sh
-scripts/build-release.sh
-test/install_test.sh
-gitleaks git --redact --exit-code 1 .
-```
+CLI for Claude Code, Codex, MCP, skills, and coding workspaces. Codex reads this
+file automatically. Claude Code receives the same contract through `CLAUDE.md`.
+
+## Choose the workflow
+
+- Use the **Operator workflow** when the user asks to inspect, configure,
+  optimize, maintain, or repair their AI coding environment.
+- Use the **Development workflow** when the user asks to change AI Optimizer
+  itself.
+- If both apply, gather operator evidence first, then develop against a failing
+  test without mixing host-specific data into the repository.
+
+## Operator workflow
+
+1. From this repository root, run the read-only handshake:
+
+   ```sh
+   ./bin/ai-optimizer agent-context --json
+   ```
+
+   Add `--workspace-root PATH` only when the user identifies a different
+   workspace container. Do not run `setup`, scheduling, package-manager, or
+   repair commands merely to gather context.
+
+2. Read `overall_status`, `prioritized_actions`, and both embedded reports.
+   Treat priorities as:
+
+   - `P0`: required product/platform failure or unknown state;
+   - `P1`: non-required failure or unknown state;
+   - `P2`: warning that needs review.
+
+3. Preserve the user's authorization boundary:
+
+   - For inspect, explain, review, or status requests, remain read-only.
+   - When the user explicitly asks for fixes, investigate each finding at its
+     owning source and make the smallest reversible change.
+   - Ask before deleting data, creating credentials, authenticating remote MCP
+     services, enabling schedules, upgrading unrelated software, or changing
+     another repository's behavior.
+
+4. Never print or commit credentials, environment values, MCP endpoints,
+   command arguments from user sessions, workspace names, or workspace file
+   contents. AI Optimizer reports are deliberately redacted; do not weaken that
+   boundary while investigating.
+
+5. Verify repairs with the affected tool's native doctor or focused test, then
+   re-run:
+
+   ```sh
+   ./bin/ai-optimizer agent-context --json
+   ```
+
+   Report exact evidence, remaining findings, changed paths, and rollback
+   instructions. Do not claim the environment is healthy solely because a
+   command exited successfully.
+
+## Development workflow
+
+1. Read `README.md`, `docs/architecture.md`, and the relevant tests.
+2. Preserve these invariants:
+
+   - `doctor`, `scan`, and `agent-context` are read-only.
+   - Mutating commands may write only AI Optimizer-owned configuration,
+     reports, release installation paths, and launchd label
+     `io.github.nyldn.ai-optimizer.daily`.
+   - Never silently edit or upgrade Claude Code, Codex, MCP servers, skills,
+     companion tools, or repositories.
+   - Keep runtime code compatible with `/usr/bin/ruby` 2.6 and the standard
+     library only.
+   - Every lifecycle change needs an isolated install/uninstall or
+     schedule/unschedule round-trip test.
+
+3. Write a failing regression test before implementation.
+4. Run the smallest relevant test while iterating.
+5. Before claiming completion, run:
+
+   ```sh
+   /usr/bin/ruby -w test/test_all.rb
+   scripts/check-syntax.sh
+   scripts/build-release.sh
+   test/install_test.sh
+   gitleaks git --redact --exit-code 1 .
+   ```
+
+See `docs/agent-workflow.md` for the handshake schema and integration examples.
@@ -3,6 +3,15 @@
 All notable changes are documented here. AI Optimizer follows semantic
 versioning.
 
+## 0.1.8 - 2026-08-23
+
+- Add a read-only `agent-context` handshake with embedded doctor and workspace
+  reports, deduplicated priorities, authorization boundaries, and completion
+  gates for coding agents.
+- Give Codex and Claude Code one shared repository-root operating contract,
+  including distinct environment-operator and product-development workflows.
+- Document and test the complete agent onboarding and verification loop.
+
 ## 0.1.7 - 2026-08-23
 
 - Warn (and therefore fail `--strict`) when a linked skill directory cannot be

@@ -1,5 +1,14 @@
 # AI Optimizer
 
-Read `AGENTS.md` first. Keep diagnostics observational, structured, redacted,
-and deterministic. Product writes must be explicit, contained, reversible, and
-covered by lifecycle tests.
+@AGENTS.md
+
+Follow `AGENTS.md` as the shared Codex/Claude contract. For any environment
+assessment, begin with the read-only repository handshake:
+
+```sh
+./bin/ai-optimizer agent-context --json
+```
+
+Do not infer repair authority from a diagnostic finding. If the user asked for
+changes, make the smallest reversible fix, verify it with the owning tool, and
+re-run the handshake before reporting completion.
@@ -27,13 +27,16 @@ skills, repositories, or launchd unless you explicitly add `--schedule`.
 - A `scan` that summarizes Git workspace coverage without reporting repository
   names or file contents.
 - The same stable findings in readable text or one clean JSON document.
+- A shared `agent-context` handshake that tells Codex or Claude Code what to
+  inspect, how to prioritize findings, where mutation authority stops, and how
+  to verify repairs.
 - Opt-in evening diagnostics through one product-owned user launch agent.
 - No telemetry and no autonomous code repair.
 
 Example:
 
 ```text
-AI Optimizer 0.1.7
+AI Optimizer 0.1.8
 
 [PASS] system.macos - macOS is supported
 [PASS] tools.claude.present - Claude Code is available
@@ -53,6 +56,7 @@ automation.
 ai-optimizer setup [--workspace-root PATH] [--schedule]
 ai-optimizer doctor [--json] [--strict]
 ai-optimizer scan [--json] [--strict] [--workspace-root PATH]
+ai-optimizer agent-context [--json] [--strict] [--workspace-root PATH]
 ai-optimizer report [--json]
 ai-optimizer schedule [--hour H] [--minute M]
 ai-optimizer schedule status
@@ -63,6 +67,21 @@ ai-optimizer version
 The default workspace root is `~/git` when it exists, otherwise the current
 directory.
 
+## Use with Codex or Claude Code
+
+Clone or open this repository, then start either agent from its root. Codex
+automatically reads `AGENTS.md`; Claude Code loads `CLAUDE.md`, which imports
+the same operating contract. Both are directed to begin with:
+
+```sh
+./bin/ai-optimizer agent-context --json
+```
+
+The handshake combines current doctor and workspace evidence with deduplicated
+priorities, remediation, safety rules, and completion checks. It is read-only.
+See [Working with Codex and Claude Code](docs/agent-workflow.md) for the schema,
+recommended prompt, and repair loop.
+
 ## Evening maintenance
 
 Scheduling is opt-in:
@@ -114,7 +133,7 @@ ai-optimizer unschedule
 
 ## Privacy and mutation boundary
 
-`doctor` and `scan` are read-only. Reports contain status identifiers,
+`doctor`, `scan`, and `agent-context` are read-only. Reports contain status identifiers,
 counts, tool versions, and remediation. They do not contain environment values,
 command arguments, MCP endpoints, tokens, workspace names, or workspace file
 contents.
@@ -138,7 +157,7 @@ The direct path verifies the installer before it runs, then the installer
 verifies the release archive before changing live paths:
 
 ```sh
-VERSION=0.1.7
+VERSION=0.1.8
 curl -fLO "https://github.com/nyldn/ai-optimizer/releases/download/v$VERSION/install.sh"
 curl -fLO "https://github.com/nyldn/ai-optimizer/releases/download/v$VERSION/install.sh.sha256"
 shasum -a 256 -c install.sh.sha256

@@ -1 +1 @@
-0.1.7
+0.1.8
@@ -0,0 +1,76 @@
+# Working with Codex and Claude Code
+
+AI Optimizer gives coding agents a deterministic, read-only starting point.
+The repository's `AGENTS.md` and `CLAUDE.md` route both Codex and Claude Code to
+the same command:
+
+```sh
+./bin/ai-optimizer agent-context --json
+```
+
+Use the installed command instead when you are not working from a checkout:
+
+```sh
+ai-optimizer agent-context --json
+```
+
+## What the handshake returns
+
+The single JSON document contains:
+
+- `overall_status`: `healthy`, `review`, or `action_required`;
+- `agent_contract`: the read-only boundary, workflow, prohibited behavior, and
+  completion gates;
+- `prioritized_actions`: deduplicated `P0`, `P1`, and `P2` findings with their
+  affected tools and existing remediation;
+- `reports.doctor`: current macOS, tool, MCP, skill, and product findings;
+- `reports.scan`: the same health evidence plus privacy-preserving workspace
+  coverage.
+
+The command does not write configuration, start services, install packages,
+authenticate providers, or edit repositories. Its exit behavior matches
+`doctor` and `scan`: required failures exit 1, while warnings exit 1 only with
+`--strict`.
+
+## Recommended agent loop
+
+```text
+read repository instructions
+        ↓
+run agent-context --json
+        ↓
+inspect prioritized evidence
+        ↓
+stay read-only or apply an explicitly requested, reversible repair
+        ↓
+run focused native verification
+        ↓
+run agent-context --json again and report remaining findings
+```
+
+This deliberately separates diagnosis from mutation. An LLM can understand
+what to inspect and how to verify it without receiving blanket authority to
+rewrite the host.
+
+## Starting a session
+
+From the repository root, start either agent normally:
+
+```sh
+codex
+```
+
+or:
+
+```sh
+claude
+```
+
+A useful first request is:
+
+> Assess this Mac's AI coding environment. Follow the repository agent
+> contract, fix only safe and reversible issues I authorized, and report
+> anything that needs my decision.
+
+Codex automatically discovers `AGENTS.md`; Claude Code loads `CLAUDE.md`, which
+imports the same contract.
@@ -11,6 +11,7 @@ flowchart LR
     D --> E[Finding objects]
     E --> F[Human report]
     E --> G[JSON report]
+    G --> L[Agent context handshake]
     H[Explicit setup or schedule] --> I[Owned config and direct-install launchd state]
     J[Explicit brew services start] --> K[Homebrew-managed launchd state]
 ```
@@ -31,6 +32,14 @@ Statuses are `pass`, `warn`, `fail`, `info`, `skip`, and `unknown`.
 Required `fail` or `unknown` findings exit 1. A top-level internal failure
 exits 3.
 
+## Agent context
+
+`agent-context` runs the doctor and workspace scanner over one read-only check
+context. It embeds both redacted reports in a single JSON document, deduplicates
+actionable findings, assigns deterministic P0/P1/P2 priorities, and includes a
+static authorization and verification contract for Codex and Claude Code. It
+does not infer repair commands or introduce another mutation path.
+
 ## Ownership
 
 Configuration and reports live under

@@ -1,6 +1,6 @@
 # Privacy
 
-AI Optimizer 0.1.7 has no telemetry and sends no diagnostic data anywhere.
+AI Optimizer 0.1.8 has no telemetry and sends no diagnostic data anywhere.
 
 ## Read
 
@@ -27,7 +27,7 @@ finding.
 
 ## Write
 
-`doctor` and `scan` do not write. `setup`, `schedule`, and `unschedule`
+`doctor`, `scan`, and `agent-context` do not write. `setup`, `schedule`, and `unschedule`
 write or remove only AI Optimizer-owned files and the documented launchd label.
 Scheduled maintenance writes one local run receipt after the execution-time
 evening guard. Configuration, receipts, and scheduler logs use owner-only

@@ -9,6 +9,7 @@
 require_relative "ai_optimizer/config"
 require_relative "ai_optimizer/checks"
 require_relative "ai_optimizer/doctor"
+require_relative "ai_optimizer/agent_context"
 require_relative "ai_optimizer/scheduler"
 require_relative "ai_optimizer/maintenance"
 require_relative "ai_optimizer/cli"