README: a section on working with agents proposal #70 landed andymccall wants agents-in-readme into main · 0 changes · opened 1 month ago

Summary

This proposal adds a one-paragraph "Working with agents" section to README.md. It covers delegated, scoped, time-limited agent keys, the author/signer split, how attribution appears in oxy log, oxy verify and the hub, and links to the design doc and the guide. It is a reasonable README-level summary. The diff alone doesn't let me confirm that the command syntax and links are accurate, so those are the main things to check. The rest of my findings are about readability. I found no outright errors.

Findings

Correctness

1. The command syntax needs checking against the CLI. README.md:

(`oxy identity delegate add agent.identity --scope changes --expires 8h`)

I can't see the CLI source in this proposal, so I can't confirm three things:

• that oxy identity delegate add is the actual subcommand path,
• that agent.identity is the expected positional argument (a file path? a name?),
• that --scope changes and --expires 8h are valid flag names and value formats.

README examples are often copied verbatim, so it's worth running this exact line once before merging. If agent.identity is a file the user must first create, a short note would prevent confusion.

2. The linked targets should be checked. README.md:

See [docs/ai_native_agent_workflows.md](docs/ai_native_agent_workflows.md) for the design and [docs/guide.md](docs/guide.md) §9 for the setup.

Neither file is part of this diff. Please confirm that both exist on main and that §9 of the guide is the agent setup section. Section numbers drift as documents change. Linking to a heading anchor (e.g. docs/guide.md#working-with-agents) would be sturdier than "§9".

3. The policy claim is unspecific. README.md:

and a policy can require that a person approved it.

This is accurate in spirit, since only people can approve. A reader won't know where such a policy is configured, though. Consider pointing to the relevant section or naming the setting, so the README doesn't promise a capability without a path to it.

Clarity

4. The paragraph is a single 80-word sentence. README.md:

An AI agent works in Oxygen under its own key, delegated by you for a scope and a time (...): every change it makes is authored by you and signed by the agent, so ... and a policy can require that a person approved it.

It carries the delegation model, a command, the author/signer split, three surfaces, an example, and policy all at once. Splitting it would make it easier to scan, e.g.:

• the key and delegation sentence (with the command in its own code block),
• the "authored by you, signed by the agent" sentence,
• the attribution and policy sentence,
• the links.

5. "for a scope and a time" reads awkwardly. Something like "limited to a scope and an expiry" says the same thing more naturally and matches the --scope / --expires flags.

6. The attribution example could say where it appears. README.md:

("Andy McCall · via Claude Code")

This is a good concrete example. A few words such as "e.g. the hub shows …" would tell the reader which of the three surfaces renders it in this form.

Summary

Proposal #70 adds a short README section explaining delegated agent keys, attribution, and policy/approval hooks. The content matches the proposal’s stated purpose and is broadly accurate, but the wording around “authored by you” could mislead, one approval phrase has a tense problem, and the section would benefit from being broken into shorter sentences.

Findings

Correctness

• File README.md, added line after line 8

  “every change it makes is authored by you and signed by the agent”

  This is internally confusing: the sentence says the agent works under its own key and makes changes, but then says the changes are “authored by you.” If the agent is doing the work, “authored by you” is misleading. It would be clearer to say the changes are attributed to you or recorded as authored by you and signed by the agent.

• File README.md, same line

  “a policy can require that a person approved it.”

  The verb tense is off for a requirement. Prefer the subjunctive: “that a person approve it,” or, if describing a completed approval requirement, “that a person has approved it.”

Clarity

• File README.md, added line after line 8

  “An AI agent works in Oxygen under its own key, delegated by you for a scope and a time (oxy identity delegate add agent.identity --scope changes --expires 8h): every change it makes is authored by you and signed by the agent, so oxy log, oxy verify and the hub show who did the work ("Andy McCall · via Claude Code") and a policy can require that a person approved it. See docs/ai_native_agent_workflows.md for the design and docs/guide.md §9 for the setup.”

  This is one very dense sentence with an inline command, an example, two tool names, and two document references. Consider splitting it into two or three sentences: one for the delegation command, one for attribution/verification, and one for policy and references.

• File README.md, same line

  “delegated by you for a scope and a time (oxy identity delegate add agent.identity --scope changes --expires 8h)”

  The command is not explicitly introduced as an example, so it could read as the exact required invocation. Adding “for example:” or placing the command on its own line would make the intended generality clearer.

This proposal adds a new section to the README explaining how AI agents operate within Oxygen, detailing the delegation of scoped, time-bound keys, the separation of change authorship and agent signatures, and pointing users to the relevant design and guide documents.

I found nothing wrong with the additions in README.md; the change is sound.