Automattic / Automattic/agents-api

Align guidelines substrate with the upstream Knowledge rename (Gutenberg #79149 / #77230)

Open
#326 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.