lightspeedwp · ashleyshaw · May 19, 2026 · May 18, 2026 · May 19, 2026 · May 19, 2026
@@ -0,0 +1,63 @@
+---
+file_type: "documentation"
+title: "Portable Schemas"
+description: "Ownership and migration rules for portable LightSpeed AI asset schemas."
+version: "v0.1.0"
+last_updated: "2026-05-18"
+author: "Codex"
+maintainer: "LightSpeed Team"
+owners: ["LightSpeed Team"]
+tags: ["schemas", "validation", "ai-ops", "governance"]
+status: "active"
+---
+
+# Portable Schemas
+
+## Overview
+
+`.schemas/` stores portable JSON, YAML, and frontmatter schemas for reusable
+LightSpeed AI assets and plugin metadata. It is for schemas that can travel
+outside this repository's GitHub-native `.github` folder.
+
+## Ownership
+
+LightSpeed Team owns this folder. Keep repo-governance schemas in
+`.github/schemas/` until a migration issue records the source path, target path,
+validation command, and consumer.
+
+## Structure
+
+| Path | Purpose |
+| --- | --- |
+| `.schemas/README.md` | Ownership and migration rules for this folder. |
+| `.schemas/<schema-name>.schema.json` | Portable JSON schemas used by active validators or plugin manifests. |
+| `.schemas/<schema-name>.schema.yaml` | Portable YAML schemas where YAML is the source contract. |
+
+## Usage
+
+- Add a schema here only when a portable asset or validator consumes it.
+- Keep schemas small and focused on active contracts.
+- Document the consuming skill, plugin, hook, workflow, or validation command.
+- Avoid carrying legacy schema complexity forward without a current use case.
+
+## Validation
+
+Run targeted syntax checks before opening a PR. Do not treat mutating format
+commands as validation evidence.
+
+```bash
+npx markdownlint-cli2 ".schemas/README.md"
+```
+
+## Migration Rules
+
+- Move schemas from `.github/schemas/` only through a tracked migration issue.
+- Preserve the source path in the migration map.
+- Update links and validation commands in the same slice.
+- Leave obsolete schemas behind for archive or deletion review rather than
+  copying them here by default.
+
+## Related Documentation
+
+- [Portable AI plugin restructure PRD](../.github/projects/active/portable-ai-plugin-restructure/portable-ai-plugin-restructure-prd-2026-05-14.md)
+- [Issue #290: Add ownership indexes for new top-level folders](https://github.com/lightspeedwp/.github/issues/290)
@@ -3,7 +3,7 @@ title: "LightSpeed Community Health & Automation Repository"
 description: "Central hub for LightSpeed organization's community health files, automation standards, label management, governance documentation, and org-wide resources for GitHub usage and contribution."
 version: "2.0"
 created_date: "2025-01-10"
-last_updated: "2025-12-07"
+last_updated: "2026-05-18"
 file_type: "documentation"
 maintainer: "LightSpeed Team"
 authors: ["LightSpeed Team"]
@@ -49,6 +49,17 @@ For comprehensive documentation, see the [docs/](./docs/) folder and [.github/RE
 - [.github/agents/agent.md](./.github/agents/agent.md) - Agent specifications
 - [.github/prompts/prompts.md](./.github/prompts/prompts.md) - Prompt library
 
+### Portable AI Source Folders
+
+- [.schemas/README.md](./.schemas/README.md) - Portable schema ownership
+- [agents/README.md](./agents/README.md) - Portable agent specs
+- [cookbook/README.md](./cookbook/README.md) - Recipes and examples
+- [hooks/README.md](./hooks/README.md) - Hooks and guardrails
+- [instructions/README.md](./instructions/README.md) - Portable instruction scope
+- [plugins/README.md](./plugins/README.md) - Plugin family strategy
+- [skills/README.md](./skills/README.md) - Skill folder rules
+- [workflows/README.md](./workflows/README.md) - Agentic workflow boundary
+
 ### 📖 Standards & Guidelines
 
 - [.github/instructions/coding-standards.instructions.md](./.github/instructions/coding-standards.instructions.md) - Coding standards

@@ -0,0 +1,61 @@
+---
+file_type: "documentation"
+title: "Portable Agents"
+description: "Ownership and migration rules for portable LightSpeed agent specifications."
+version: "v0.1.0"
+last_updated: "2026-05-18"
+author: "Codex"
+maintainer: "LightSpeed Team"
+owners: ["LightSpeed Team"]
+tags: ["agents", "ai-ops", "governance", "portable-assets"]
+status: "draft"
+---
+
+# Portable Agents
+
+## Overview
+
+`agents/` stores portable agent specifications that can be reused across
+LightSpeed repositories and AI tools. Version 1 of this structure is for specs;
+runtime code is migrated separately only when the new contract is clear.
+
+## Ownership
+
+LightSpeed Team owns this folder. Repo-only maintenance agents stay in
+`.github/agents/` until they are rewritten or confirmed as portable.
+
+## Structure
+
+| Path | Purpose |
+| --- | --- |
+| `agents/README.md` | Ownership and migration rules for this folder. |
+| `agents/<agent-id>.agent.md` | Portable agent specification (flat structure). |
+| `agents/<agent-id>/AGENT.md` | Portable agent specification (folder structure entrypoint). |
+
+## Usage
+
+- Use this folder for reusable agent specs, not one-off project instructions.
+- Remove assumptions about `.github`-relative paths before migration.
+- Keep tool-specific setup notes in adapter sections, not in the core contract.
+- Record each migrated agent in the migration map with source and target paths.
+
+## Validation
+
+Validate changed Markdown files and any future agent schema checks before a PR.
+
+```bash
+npx markdownlint-cli2 "agents/**/*.md"
+```
+
+## Migration Rules
+
+- Migrate reusable specs from `.github/agents/` only after frontmatter and links
+  are updated.
+- Keep agents that maintain this repository under `.github/agents/`.
+- Do not move JavaScript runners here by default; rewrite useful runtime
+  behaviour into hooks, workflows, or skill-local scripts when needed.
+
+## Related Documentation
+
+- [Portable AI plugin restructure PRD](../.github/projects/active/portable-ai-plugin-restructure/portable-ai-plugin-restructure-prd-2026-05-14.md)
+- [Issue #290: Add ownership indexes for new top-level folders](https://github.com/lightspeedwp/.github/issues/290)
@@ -0,0 +1,61 @@
+---
+file_type: "documentation"
+title: "Portable Cookbook"
+description: "Ownership and migration rules for portable LightSpeed recipes and examples."
+version: "v0.1.0"
+last_updated: "2026-05-18"
+author: "Codex"
+maintainer: "LightSpeed Team"
+owners: ["LightSpeed Team"]
+tags: ["cookbook", "recipes", "examples", "ai-ops"]
+status: "active"
+---
+
+# Portable Cookbook
+
+## Overview
+
+`cookbook/` stores recipes, examples, playbooks, and implementation guides that
+teach reusable LightSpeed AI operations patterns. It is for durable guidance
+that is useful, but not structured enough to be an installable skill.
+
+## Ownership
+
+LightSpeed Team owns this folder. Keep active project notes in
+`.github/projects/` and permanent governance documentation in `docs/`.
+
+## Structure
+
+| Path | Purpose |
+| --- | --- |
+| `cookbook/README.md` | Ownership and migration rules for this folder. |
+| `cookbook/<recipe-id>.md` | A focused recipe, example, or playbook. |
+| `cookbook/<topic>/README.md` | Optional topic index when several recipes share a domain. |
+
+## Usage
+
+- Convert legacy prompts into cookbook recipes when they teach a pattern but do
+  not need a strict skill workflow.
+- Keep each recipe practical, reproducible, and linked to source evidence.
+- Prefer short examples over broad tutorials.
+- Promote repeatable operational workflows to `skills/` instead.
+
+## Validation
+
+Validate changed Markdown files before a PR.
+
+```bash
+npx markdownlint-cli2 "cookbook/**/*.md"
+```
+
+## Migration Rules
+
+- Move example prompts from `.github/prompts/` only after reviewing whether they
+  should become a skill, recipe, archive item, or deletion candidate.
+- Preserve the original prompt path in the migration map.
+- Remove stale `.github` path assumptions during conversion.
+
+## Related Documentation
+
+- [Portable AI plugin restructure PRD](../.github/projects/active/portable-ai-plugin-restructure/portable-ai-plugin-restructure-prd-2026-05-14.md)
+- [Issue #290: Add ownership indexes for new top-level folders](https://github.com/lightspeedwp/.github/issues/290)
@@ -0,0 +1,61 @@
+---
+file_type: "documentation"
+title: "Portable Hooks"
+description: "Ownership and migration rules for portable LightSpeed hooks and guardrails."
+version: "v0.1.0"
+last_updated: "2026-05-18"
+author: "Codex"
+maintainer: "LightSpeed Team"
+owners: ["LightSpeed Team"]
+tags: ["hooks", "guardrails", "automation", "ai-ops"]
+status: "active"
+---
+
+# Portable Hooks
+
+## Overview
+
+`hooks/` stores portable hooks, guardrails, and adapters that support safe AI
+operations across tools. Hooks must be small, auditable, and tool-neutral where
+possible.
+
+## Ownership
+
+LightSpeed Team owns this folder. Legacy agent runner code stays in place until
+it is rewritten into a smaller hook, workflow, or skill-local script.
+
+## Structure
+
+| Path | Purpose |
+| --- | --- |
+| `hooks/README.md` | Ownership and migration rules for this folder. |
+| `hooks/<hook-id>/README.md` | Hook purpose, inputs, outputs, risks, and usage. |
+| `hooks/<hook-id>/hook.sh` | Actual hook implementation (or other language-specific entrypoint). |
+| `hooks/<hook-id>/<adapter>.md` | Optional tool adapter notes for Codex, Copilot, Claude, or other runtimes. |
+
+## Usage
+
+- Prefer dry-run behaviour for any hook that can edit files or external state.
+- Document inputs, outputs, permissions, and failure modes.
+- Keep secrets out of examples and test data.
+- Avoid broad runtime frameworks unless the maintenance return is clear.
+
+## Validation
+
+Validate changed Markdown files and any hook scripts before a PR.
+
+```bash
+npx markdownlint-cli2 "hooks/**/*.md"
+```
+
+## Migration Rules
+
+- Do not move JavaScript agent runners directly into this folder.
+- Rewrite only the useful, portable behaviour.
+- Keep destructive or external-write hooks behind explicit confirmation and
+  documented dry-run paths.
+
+## Related Documentation
+
+- [Portable AI plugin restructure PRD](../.github/projects/active/portable-ai-plugin-restructure/portable-ai-plugin-restructure-prd-2026-05-14.md)
+- [Issue #290: Add ownership indexes for new top-level folders](https://github.com/lightspeedwp/.github/issues/290)
@@ -0,0 +1,61 @@
+---
+file_type: "documentation"
+title: "Portable Instructions"
+description: "Ownership and migration rules for portable LightSpeed instruction files."
+version: "v0.1.0"
+last_updated: "2026-05-18"
+author: "Codex"
+maintainer: "LightSpeed Team"
+owners: ["LightSpeed Team"]
+tags: ["instructions", "ai-ops", "governance", "portable-assets"]
+status: "draft"
+---
+
+# Portable Instructions
+
+## Overview
+
+`instructions/` stores portable instruction files that can be reused across
+LightSpeed projects and AI tools. These instructions should describe domain
+behaviour without assuming they live inside `.github`.
+
+## Ownership
+
+LightSpeed Team owns this folder. Instructions for maintaining this repository
+stay in `.github/instructions/` or `.github/custom-instructions.md`.
+
+## Structure
+
+| Path | Purpose |
+| --- | --- |
+| `instructions/README.md` | Ownership and migration rules for this folder. |
+| `instructions/<domain>.instructions.md` | Portable instruction file for a reusable domain or workflow. |
+| `instructions/<domain>/README.md` | Optional domain index when several instruction files belong together. |
+
+## Usage
+
+- Use this folder for reusable instructions that belong outside repo-specific
+  `.github` governance.
+- Keep WordPress block theme and block plugin guidance separated when migrated.
+- Prefer clear domain boundaries over large catch-all instruction files.
+- Link related skills, agents, or cookbook recipes from the instruction body.
+
+## Validation
+
+Validate changed Markdown files and future frontmatter checks before a PR.
+
+```bash
+npx markdownlint-cli2 "instructions/**/*.md"
+```
+
+## Migration Rules
+
+- Move generic instructions from `.github/instructions/` only after removing
+  `.github`-specific assumptions.
+- Keep repo-maintenance instructions in `.github/instructions/`.
+- Record every moved instruction in the migration map.
+
+## Related Documentation
+
+- [Portable AI plugin restructure PRD](../.github/projects/active/portable-ai-plugin-restructure/portable-ai-plugin-restructure-prd-2026-05-14.md)
+- [Issue #290: Add ownership indexes for new top-level folders](https://github.com/lightspeedwp/.github/issues/290)