Automattic / Automattic/agents-api
Align guidelines substrate with the upstream Knowledge rename (Gutenberg #79149 / #77230)
- Dominant language
- PHP
- Stars
- 33
- Forks
- 8
- Avg merge
- 1h 36m
- Merged PRs (30d)
- 31
Description
## Summary
Agents API ships a `WP_Guidelines_Substrate` that mirrors the WordPress Guidelines storage primitive: CPT `wp_guideline`, taxonomy `wp_guideline_type`, a filterable `wp_guideline_types()` registry, a scope model (`private_user_workspace_memory` vs `workspace_shared_guidance`), the `*_workspace_guidelines` / `*_agent_memory` capability namespace (with `promote_agent_memory`), and a `guidelines` REST base.
Upstream is consolidating and **renaming this primitive from "Guidelines" to "Knowledge"**, on the rationale that editorial guidelines are just *one* type of persistent, agent-facing knowledge a site stores — alongside skills, memory, and plans/notes — and they all share the same structural shape (titled, versioned, instructional documents over REST), differing only in lifecycle and multiplicity:
- Proposal: WordPress/gutenberg#77230 — *"Evolve CPT to enable support for skills, memory, and plans via taxonomy"*
- Reference implementation: WordPress/gutenberg#79149 — *"Knowledge: Rename the Guidelines CPT storage primitive to Knowledge"*
Our substrate already implements the *evolved* (typed + private-memory + promote) shape this proposal describes, just under the older `guideline` names. This issue tracks aligning our names and built-in types with the upstream primitive so consumers target one vocabulary.
## Proposed alignment (per gutenberg#79149)
| Surface | Current | Upstream |
| --- | --- | --- |
| CPT slug | `wp_guideline` | `wp_knowledge` |
| Taxonomy | `wp_guideline_type` | `wp_knowledge_type` |
| Types registry + filter | `wp_guideline_types()` | `wp_knowledge_types()` |
| Capability namespace | `*_guidelines` | `*_knowledge` |
| REST base | `/wp/v2/guidelines` | `/wp/v2/knowledge` |
| Meta keys | `_wp_guideline_*` | `_wp_knowledge_*` |
Built-in types, defined by behavior:
- `content` → `instruction` (loaded by default when applicable)
- `artifact` → `note` (private freeform working text; the save-time fallback term)
- `memory` stays `memory`
`skill` is **not** a built-in upstream type — it would come through the `wp_knowledge_types()` filter. Decide whether we ship it as a default here or leave it to consumers.
## Considerations
- **Timing.** gutenberg#79149 is explicitly an *illustration* of a proposal still gathering feedback (gutenberg#77230). Recommend we **track upstream and mirror once it lands** rather than rename ahead of it, to avoid churn if the final shape changes — same pattern as #94 (consume Abilities API lifecycle filters once they land). Alternatively, adopt now behind compatibility aliases.
- **Backwards compatibility.** Consumers already build on the `wp_guideline*` names, the `*_guidelines` caps, and the `_wp_guideline_*` meta. A rename needs a deprecation/aliasing path (old constants/filters delegating to new), plus migration for existing posts/terms/meta.
- **Runtime contracts.** The consumption side — `WP_Agent_Memory_Registry`, `WP_Agent_Context_Section_Registry`, the context injection/conflict-resolution layer — reads through this substrate. The rename is storage-layer + a compatibility shim; the runtime contracts that map `instruction` / `note` / `memory` to agent context should keep working unchanged.
## Acceptance
- [ ] Decision: mirror-on-land vs adopt-now-with-aliases.
- [ ] `wp_knowledge` CPT + `wp_knowledge_type` taxonomy + `wp_knowledge_types()` filter, with the built-in type renames.
- [ ] `*_knowledge` capability namespace and `/wp/v2/knowledge` REST base.
- [ ] Backwards-compatible aliases for the previous names/meta + a migration path.
- [ ] Smoke coverage updated for the new names; existing runtime-contract smokes still green.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.