docs: introduction (concepts + vocabulary) + capability map#243
Draft
lezama wants to merge 3 commits into
Draft
Conversation
Adds docs/adopting-agents-api.md — a migration guide for teams that already run a custom WordPress AI agent runtime and want to converge onto the shared substrate. Covers: - What stays the consumer's (UX, prompts, concrete tools, storage policy). - A capability map: each capability a custom runtime commonly owns -> the Agents API primitive that can replace it, with adoption notes. - An incremental, contract-test-gated adoption strategy (swap one primitive at a time behind a record/replay safety net, lowest-coupling first). - How every default is overridable via filters. - A "gaps and open questions" section to fill in collaboratively as real runtimes adopt the substrate. Draft: the capability map is intentionally incomplete where contracts are still firming up; the gaps section tracks what remains. Indexed from docs/README.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replaces the migration-strategy draft with a focused capability map: a reference table from each capability an AI agent runtime needs to the Agents API primitive that provides it, grouped by area (runtime/loop, tools, transcripts, memory/context, identity/auth, approvals/consent, orchestration), with the contract file and topic page for each. Adds an extension-points table listing the override filters. Pure reference — no migration-process narrative. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lezama
changed the title
Adds docs/introduction.md — a plain-language on-ramp for newcomers that breaks down the core idea, the three cooperating layers (AI Client, Abilities API, Agents API), the vocabulary the rest of the docs assume (agent, loop, turn, turn runner, tool executor, mediation, transcript/session, principal, workspace, memory, compaction, budget, approval, channel, workflow/routine), and a walkthrough of how a single turn flows. Addresses the feedback that the existing docs presuppose the nomenclature. Referenced from the top of README.md, docs/README.md, and readme.txt so new readers land on it first. The capability map stays as the reference the introduction points to once the terms are known. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lezama
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Draft. Onboarding documentation for newcomers, addressing the feedback that the existing docs presuppose the project's nomenclature.
docs/introduction.md(the on-ramp) — plain-language breakdown of: the one-sentence version, the three cooperating layers (AI Client / Abilities API / Agents API), the core vocabulary the rest of the docs assume (agent, conversation loop, turn, turn runner, tool executor, mediation, transcript/session, principal, workspace, memory, compaction, iteration budget, approval, channel, workflow/routine), a walkthrough of how one turn flows, and what's the consumer's vs. the substrate's.docs/capability-map.md— the reference table (capability → primitive → contract) the introduction points to once the terms are known.Referenced from the top of
README.md,docs/README.md, andreadme.txtso new readers land on the introduction first.Changes
docs/introduction.md— new concepts/vocabulary on-ramp.docs/capability-map.md— capability → primitive reference.README.md,readme.txt,docs/README.md— point newcomers at the introduction up top.Docs-only; no source or test changes. Internals-free; all intra-doc and source links verified.
Not in this PR
A separate request — implementing PHPStan at max (object types,
list<T>overtype[]) — is a code/CI change and will land as its own PR.