diff --git a/.schemas/README.md b/.schemas/README.md new file mode 100644 index 00000000..88b63d4a --- /dev/null +++ b/.schemas/README.md @@ -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.json` | Portable JSON schemas used by active validators or plugin manifests. | +| `.schemas/.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) diff --git a/README.md b/README.md index 3abca2e6..c100b828 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/agents/README.md b/agents/README.md new file mode 100644 index 00000000..ccb9490a --- /dev/null +++ b/agents/README.md @@ -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.md` | Portable agent specification (flat structure). | +| `agents//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) diff --git a/cookbook/README.md b/cookbook/README.md new file mode 100644 index 00000000..b6a87901 --- /dev/null +++ b/cookbook/README.md @@ -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/.md` | A focused recipe, example, or playbook. | +| `cookbook//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) diff --git a/hooks/README.md b/hooks/README.md new file mode 100644 index 00000000..d938bac1 --- /dev/null +++ b/hooks/README.md @@ -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//README.md` | Hook purpose, inputs, outputs, risks, and usage. | +| `hooks//hook.sh` | Actual hook implementation (or other language-specific entrypoint). | +| `hooks//.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) diff --git a/instructions/README.md b/instructions/README.md new file mode 100644 index 00000000..1b283ff3 --- /dev/null +++ b/instructions/README.md @@ -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/.instructions.md` | Portable instruction file for a reusable domain or workflow. | +| `instructions//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) diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 00000000..f1af10e5 --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,72 @@ +--- +file_type: "documentation" +title: "Portable Plugins" +description: "Ownership and migration rules for installable LightSpeed plugin bundles." +version: "v0.1.0" +last_updated: "2026-05-18" +author: "Codex" +maintainer: "LightSpeed Team" +owners: ["LightSpeed Team"] +tags: ["plugins", "ai-ops", "installable-assets", "governance"] +status: "draft" +--- + +# Portable Plugins + +## Overview + +`plugins/` stores installable LightSpeed AI operations plugin bundles. Each +plugin should package a focused set of agents, skills, instructions, hooks, or +workflows that can be installed into supported tools. + +## Ownership + +LightSpeed Team owns this folder. The first implementation target is the +`lightspeed-github-ops` pilot plugin. + +## Structure + +| Path | Purpose | +| --- | --- | +| `plugins/README.md` | Ownership and migration rules for this folder. | +| `plugins//README.md` | Plugin purpose, contents, install notes, and support status. | +| `plugins//plugin.json` | Plugin manifest for compatible tooling. | +| `plugins//skills/` | Plugin-local skills when bundling is useful. | +| `plugins//agents/` | Plugin-local agent specs when bundling is useful. | + +## Plugin Family Strategy + +| Plugin family | Purpose | Status | +| --- | --- | --- | +| `lightspeed-github-ops` | Community health, labels, templates, PR review, frontmatter, release prep. | Pilot | +| `lightspeed-wordpress-block-theme` | Block theme standards and workflows. | Planned | +| `lightspeed-wordpress-block-plugin` | Custom block plugin standards and workflows. | Planned | +| `lightspeed-content-ops` | Publishing, editorial, and reusable content operations. | Backlog | + +## Usage + +- Build the smallest useful plugin first. +- Keep plugin manifests accurate and dependency-light. +- Link bundled assets back to their source collections where relevant. +- Avoid broad materialisation tooling until the pilot proves the pattern. + +## Validation + +Validate changed Markdown files now. Add manifest validation once the validation +reset introduces `validate:plugins`. + +```bash +npx markdownlint-cli2 "plugins/**/*.md" +``` + +## Migration Rules + +- Create plugin bundles from proven source assets, not from unreviewed legacy + folders. +- Keep each plugin focused on one audience and operating context. +- Record bundled assets in the migration map or plugin README. + +## 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) diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 00000000..3cb13e03 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,76 @@ +--- +file_type: "documentation" +title: "Portable Skills" +description: "Ownership and migration rules for self-contained LightSpeed skills." +version: "v0.1.0" +last_updated: "2026-05-18" +author: "Codex" +maintainer: "LightSpeed Team" +owners: ["LightSpeed Team"] +tags: ["skills", "ai-ops", "portable-assets", "governance"] +status: "draft" +--- + +# Portable Skills + +## Overview + +`skills/` stores self-contained LightSpeed skills. A skill should describe a +repeatable workflow clearly enough that an agent can load `SKILL.md`, follow the +steps, and use any local assets, scripts, templates, or examples safely. + +## Ownership + +LightSpeed Team owns this folder. Skills should be portable by default and +bundled into plugins only when a plugin needs them. + +## Structure + +| Path | Purpose | +| --- | --- | +| `skills/README.md` | Ownership, backlog, and migration rules for this folder. | +| `skills/.skill.md` | Portable skill specification (flat structure). | +| `skills//SKILL.md` | Portable skill specification (folder structure entrypoint). | +| `skills//assets/` | Optional static assets used by the skill. | +| `skills//scripts/` | Optional helper scripts owned by the skill. | +| `skills//templates/` | Optional reusable output templates. | +| `skills//examples/` | Optional examples and fixtures. | + +## Initial Skills Backlog + +| Skill | Plugin fit | Priority | Status | +| --- | --- | --- | --- | +| `lightspeed-frontmatter-audit` | `lightspeed-github-ops` | P0 | Planned | +| `lightspeed-pr-review` | `lightspeed-github-ops` | P0 | Planned | +| `lightspeed-label-governance` | `lightspeed-github-ops` | P0 | Planned | +| `lightspeed-release-prep` | `lightspeed-github-ops` | P1 | Backlog | + +## Usage + +- Convert repeatable prompt workflows into skills when they have clear steps, + inputs, outputs, and validation. +- Keep examples and teaching material in `cookbook/` unless the skill needs + them as fixtures. +- Keep scripts small, local to the skill, and documented. +- Do not include secrets, production data, or customer data in examples. + +## Validation + +Validate changed Markdown files now. Add skill structure checks once the +validation reset introduces skill validation. + +```bash +npx markdownlint-cli2 "skills/**/*.md" +``` + +## Migration Rules + +- Review each legacy prompt before deciding whether it becomes a skill, + cookbook recipe, archive item, or deletion candidate. +- Record source and target paths in the migration map. +- Keep a skill self-contained once migrated. + +## 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) diff --git a/workflows/README.md b/workflows/README.md new file mode 100644 index 00000000..2c80c030 --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,64 @@ +--- +file_type: "documentation" +title: "Portable Workflows" +description: "Ownership and migration rules for portable LightSpeed agentic workflows." +version: "v0.1.0" +last_updated: "2026-05-18" +author: "Codex" +maintainer: "LightSpeed Team" +owners: ["LightSpeed Team"] +tags: ["workflows", "ai-ops", "automation", "governance"] +status: "active" +stability: "incubating" +--- + +# Portable Workflows + +## Overview + +`workflows/` stores portable agentic workflows that can run across AI tools or +plugin contexts. GitHub Actions remain in `.github/workflows/`. + +## Ownership + +LightSpeed Team owns this folder. Keep workflow definitions focused on agentic +processes rather than repository CI configuration. + +## Structure + +| Path | Purpose | +| --- | --- | +| `workflows/README.md` | Ownership and migration rules for this folder. | +| `workflows//README.md` | Workflow purpose, inputs, outputs, risks, and validation. | +| `workflows//workflow.yml` | Portable workflow definition file. | +| `workflows//.md` | Optional tool adapter notes for supported runtimes. | + +## Usage + +- Use this folder for portable AI workflows, playbooks with state, or + multi-step agent processes. +- Keep GitHub Actions, reusable workflow YAML, and CI triggers in + `.github/workflows/`. +- Prefer workflows that can be tested locally or dry-run safely. +- Link related skills, hooks, schemas, and plugins from each workflow. + +## Validation + +Validate changed Markdown files now. Add workflow structure checks once the +validation reset introduces portable workflow validation. + +```bash +npx markdownlint-cli2 "workflows/**/*.md" +``` + +## Migration Rules + +- Do not move GitHub Actions into this folder. +- Convert durable agentic processes only after inputs, outputs, and safety + checks are documented. +- Record source and target paths 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)