Improve AI-agent operability with unified docs, machine-readable skill routing, and structured health output#1
Conversation
Agent-Logs-Url: https://github.com/uuhan/workhorse/sessions/e474f58f-0368-469b-bff6-62f30efc0e8a Co-authored-by: uuhan <3286111+uuhan@users.noreply.github.com>
Agent-Logs-Url: https://github.com/uuhan/workhorse/sessions/e474f58f-0368-469b-bff6-62f30efc0e8a Co-authored-by: uuhan <3286111+uuhan@users.noreply.github.com>
Agent-Logs-Url: https://github.com/uuhan/workhorse/sessions/e474f58f-0368-469b-bff6-62f30efc0e8a Co-authored-by: uuhan <3286111+uuhan@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 762fc47ea8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| agent-check: | ||
| @python3 scripts/check-agent-docs.py | ||
| @python3 scripts/check-agent-regression.py |
There was a problem hiding this comment.
agent-check runs check-agent-regression.py directly, but that script exits unless target/debug/cargo-work already exists. On a clean checkout, just agent-check will fail before doing any regression validation, so the new local guardrail command is not runnable as introduced. Add a build step (or make this recipe depend on one) so the command works end-to-end.
Useful? React with 👍 / 👎.
| binary = ROOT / "target" / "debug" / "cargo-work" | ||
| if not binary.exists(): | ||
| fail("target/debug/cargo-work does not exist, run cargo build --bin cargo-work first") |
There was a problem hiding this comment.
The regression script hardcodes target/debug/cargo-work, but on Windows cargo build --bin cargo-work outputs cargo-work.exe. This makes the check fail with “does not exist” even when the binary was built successfully, breaking portability for Windows contributors and any future Windows CI usage of this script.
Useful? React with 👍 / 👎.
This PR implements an agent-oriented operating layer for Workhorse so Claude Code/Codex-style agents can route tasks deterministically, execute repeatable workflows, and consume stable machine-readable signals.
It adds a single agent entrypoint, a structured skill index, standardized playbooks, and JSON output for a key inspection command.
Unified agent entry + routing contract
AI_AGENT.mdas the single agent-facing entry doc.Machine-readable skills index
skills/index.jsonwith per-skill metadata:low|medium|high)--dangerous, service restart/replace, destructive admin ops).Standard task playbooks
docs/agent-playbooks.mdwith normalized playbooks for:Agent-friendly CLI structured output
cargo work healthwith--json.status,protocol,ulimit_nofile, plus v2 metadata likeversion/commit/os/arch/family/default_shell).--jsonis not used.CLI options hardening for agent invocation
ping/healthoptions (remote→host) to avoid argument-name collisions with flattenedHorseOptions.Regression + consistency guardrails in repo/CI
scripts/check-agent-docs.pyfor structural/content consistency across agent docs and index.scripts/agent-regression-cases.json+scripts/check-agent-regression.py(12 cases) to validate routing metadata and CLI surface assumptions.agent-validationjob and exposed a localjust agent-checktarget.README.md,README.en.md, andAGENTS.mdto surface the new agent entry/index andhealth --json.# New machine-readable health output for agents cargo work health --json{ "status": "ok", "protocol": "v2", "version": "0.3.0", "commit": "<sha>", "os": "linux", "arch": "x86_64", "family": "unix", "default_shell": "/bin/bash", "ulimit_nofile": 65535 }