From 05d0aa7cfa17a3277b0a049ec88e22b39bcd867b Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 00:47:53 +0200 Subject: [PATCH 01/15] Add portable AI source folder READMEs Introduce ownership, structure, usage, validation, and migration guidance for portable LightSpeed AI assets by adding README files for .schemas, agents, cookbook, hooks, instructions, plugins, skills, and workflows. Update the root README's last_updated date and add a "Portable AI Source Folders" index that links to the new READMEs. These documents standardize where portable specs, schemas, recipes, hooks, instructions, plugins, skills, and workflows should live and how to migrate assets from .github paths. --- .schemas/README.md | 64 +++++++++++++++++++++++++++++++++++ README.md | 13 +++++++- agents/README.md | 62 ++++++++++++++++++++++++++++++++++ cookbook/README.md | 62 ++++++++++++++++++++++++++++++++++ hooks/README.md | 61 +++++++++++++++++++++++++++++++++ instructions/README.md | 62 ++++++++++++++++++++++++++++++++++ plugins/README.md | 73 ++++++++++++++++++++++++++++++++++++++++ skills/README.md | 76 ++++++++++++++++++++++++++++++++++++++++++ workflows/README.md | 63 ++++++++++++++++++++++++++++++++++ 9 files changed, 535 insertions(+), 1 deletion(-) create mode 100644 .schemas/README.md create mode 100644 agents/README.md create mode 100644 cookbook/README.md create mode 100644 hooks/README.md create mode 100644 instructions/README.md create mode 100644 plugins/README.md create mode 100644 skills/README.md create mode 100644 workflows/README.md diff --git a/.schemas/README.md b/.schemas/README.md new file mode 100644 index 00000000..045540f6 --- /dev/null +++ b/.schemas/README.md @@ -0,0 +1,64 @@ +--- +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" +stability: "draft" +--- + +# 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..dd6cec5b --- /dev/null +++ b/agents/README.md @@ -0,0 +1,62 @@ +--- +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: "active" +stability: "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 with frontmatter and tool-neutral behaviour. | +| `agents//` | Optional folder for larger agents that need assets, examples, or adapter notes. | + +## 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/README.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..66195640 --- /dev/null +++ b/cookbook/README.md @@ -0,0 +1,62 @@ +--- +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" +stability: "draft" +--- + +# 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/README.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..cd700933 --- /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" +stability: "draft" +--- + +# 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//.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/README.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..f5a147eb --- /dev/null +++ b/instructions/README.md @@ -0,0 +1,62 @@ +--- +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: "active" +stability: "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/copilot-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/README.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..384462ed --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,73 @@ +--- +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: "active" +stability: "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//.github/plugin/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/README.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..43dde575 --- /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: "active" +stability: "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` | Required entrypoint for a skill. | +| `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/README.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..d38ca6ce --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,63 @@ +--- +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: "draft" +--- + +# 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//.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/README.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) From a5d33e649f9c33158726bd5a1c16683030d7f0db Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:04:50 +0200 Subject: [PATCH 02/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- .schemas/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.schemas/README.md b/.schemas/README.md index 045540f6..88b63d4a 100644 --- a/.schemas/README.md +++ b/.schemas/README.md @@ -9,7 +9,6 @@ maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["schemas", "validation", "ai-ops", "governance"] status: "active" -stability: "draft" --- # Portable Schemas From 49475f24e2a4dac90a6c8c5d2a8095db93a06fd1 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:05:18 +0200 Subject: [PATCH 03/15] Update agents/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw --- agents/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/agents/README.md b/agents/README.md index dd6cec5b..d997e8ea 100644 --- a/agents/README.md +++ b/agents/README.md @@ -30,8 +30,8 @@ LightSpeed Team owns this folder. Repo-only maintenance agents stay in | Path | Purpose | | --- | --- | | `agents/README.md` | Ownership and migration rules for this folder. | -| `agents/.agent.md` | Portable agent specification with frontmatter and tool-neutral behaviour. | -| `agents//` | Optional folder for larger agents that need assets, examples, or adapter notes. | +| `agents/.agent.md` | Portable agent specification (flat structure). | +| `agents//AGENT.md` | Portable agent specification (folder structure entrypoint). | ## Usage From 8d56740241050311bb25ee18107bf0bf753f2f08 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:05:30 +0200 Subject: [PATCH 04/15] Update plugins/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw --- plugins/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/README.md b/plugins/README.md index 384462ed..098e9464 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -31,7 +31,7 @@ LightSpeed Team owns this folder. The first implementation target is the | --- | --- | | `plugins/README.md` | Ownership and migration rules for this folder. | | `plugins//README.md` | Plugin purpose, contents, install notes, and support status. | -| `plugins//.github/plugin/plugin.json` | Plugin manifest for compatible tooling. | +| `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. | From 4900b097ce285d2bfedacb1f9f7acb2e001748c6 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:05:45 +0200 Subject: [PATCH 05/15] Update workflows/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw --- workflows/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/workflows/README.md b/workflows/README.md index d38ca6ce..6069ef3f 100644 --- a/workflows/README.md +++ b/workflows/README.md @@ -30,6 +30,7 @@ processes rather than repository CI configuration. | --- | --- | | `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 From 9a48b371649741ab0ac14a30e75f14a76858e556 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:05:57 +0200 Subject: [PATCH 06/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- instructions/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/instructions/README.md b/instructions/README.md index f5a147eb..ba32bb19 100644 --- a/instructions/README.md +++ b/instructions/README.md @@ -8,8 +8,7 @@ author: "Codex" maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["instructions", "ai-ops", "governance", "portable-assets"] -status: "active" -stability: "draft" +status: "draft" --- # Portable Instructions From 4e9743b8637ed3addd68f188a612df6ec01c2338 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:06:14 +0200 Subject: [PATCH 07/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- agents/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/agents/README.md b/agents/README.md index d997e8ea..76ee247c 100644 --- a/agents/README.md +++ b/agents/README.md @@ -8,8 +8,7 @@ author: "Codex" maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["agents", "ai-ops", "governance", "portable-assets"] -status: "active" -stability: "draft" +status: "draft" --- # Portable Agents From 1cf97662c38a4d94c8242a77e82a4989445406e2 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:06:32 +0200 Subject: [PATCH 08/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- hooks/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/hooks/README.md b/hooks/README.md index cd700933..27f2c71f 100644 --- a/hooks/README.md +++ b/hooks/README.md @@ -9,7 +9,6 @@ maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["hooks", "guardrails", "automation", "ai-ops"] status: "active" -stability: "draft" --- # Portable Hooks From 782218eda3b47093f7ff517edbfb86001f85ef55 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:06:55 +0200 Subject: [PATCH 09/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- cookbook/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/cookbook/README.md b/cookbook/README.md index 66195640..3521158a 100644 --- a/cookbook/README.md +++ b/cookbook/README.md @@ -9,7 +9,6 @@ maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["cookbook", "recipes", "examples", "ai-ops"] status: "active" -stability: "draft" --- # Portable Cookbook From eda0db87262c89dcf4196d10a4e0e58022d8f3a7 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:07:07 +0200 Subject: [PATCH 10/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- workflows/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workflows/README.md b/workflows/README.md index 6069ef3f..9520e07d 100644 --- a/workflows/README.md +++ b/workflows/README.md @@ -9,7 +9,7 @@ maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["workflows", "ai-ops", "automation", "governance"] status: "active" -stability: "draft" +stability: "incubating" --- # Portable Workflows From a033c2427c1dea7d539124ffe4a879dc4a93c4f9 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:07:17 +0200 Subject: [PATCH 11/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- plugins/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/plugins/README.md b/plugins/README.md index 098e9464..e17aded4 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -8,8 +8,7 @@ author: "Codex" maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["plugins", "ai-ops", "installable-assets", "governance"] -status: "active" -stability: "draft" +status: "draft" --- # Portable Plugins From 89f75a9b61995eeb613ceeb2cc40e33f77f22cf3 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:07:30 +0200 Subject: [PATCH 12/15] Update hooks/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw --- hooks/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/hooks/README.md b/hooks/README.md index 27f2c71f..5e92642a 100644 --- a/hooks/README.md +++ b/hooks/README.md @@ -30,6 +30,7 @@ it is rewritten into a smaller hook, workflow, or skill-local script. | --- | --- | | `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 From c9e44ee96549afe27187d77a173c25d37176d522 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:07:46 +0200 Subject: [PATCH 13/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- skills/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/skills/README.md b/skills/README.md index 43dde575..f4ced672 100644 --- a/skills/README.md +++ b/skills/README.md @@ -8,8 +8,7 @@ author: "Codex" maintainer: "LightSpeed Team" owners: ["LightSpeed Team"] tags: ["skills", "ai-ops", "portable-assets", "governance"] -status: "active" -stability: "draft" +status: "draft" --- # Portable Skills From b2389a06dafc47a2653556bf699e7bee140def45 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:07:58 +0200 Subject: [PATCH 14/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw --- instructions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instructions/README.md b/instructions/README.md index ba32bb19..9cd4f3fa 100644 --- a/instructions/README.md +++ b/instructions/README.md @@ -22,7 +22,7 @@ behaviour without assuming they live inside `.github`. ## Ownership LightSpeed Team owns this folder. Instructions for maintaining this repository -stay in `.github/instructions/` or `.github/copilot-instructions.md`. +stay in `.github/instructions/` or `.github/custom-instructions.md`. ## Structure From 850c67bbc7ea3c16f358c07dc45bbb130ca3d682 Mon Sep 17 00:00:00 2001 From: Ash Shaw Date: Tue, 19 May 2026 19:22:49 +0200 Subject: [PATCH 15/15] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Ash Shaw --- agents/README.md | 2 +- cookbook/README.md | 2 +- hooks/README.md | 2 +- instructions/README.md | 2 +- plugins/README.md | 2 +- skills/README.md | 5 +++-- workflows/README.md | 2 +- 7 files changed, 9 insertions(+), 8 deletions(-) diff --git a/agents/README.md b/agents/README.md index 76ee247c..ccb9490a 100644 --- a/agents/README.md +++ b/agents/README.md @@ -44,7 +44,7 @@ LightSpeed Team owns this folder. Repo-only maintenance agents stay in Validate changed Markdown files and any future agent schema checks before a PR. ```bash -npx markdownlint-cli2 "agents/README.md" +npx markdownlint-cli2 "agents/**/*.md" ``` ## Migration Rules diff --git a/cookbook/README.md b/cookbook/README.md index 3521158a..b6a87901 100644 --- a/cookbook/README.md +++ b/cookbook/README.md @@ -45,7 +45,7 @@ LightSpeed Team owns this folder. Keep active project notes in Validate changed Markdown files before a PR. ```bash -npx markdownlint-cli2 "cookbook/README.md" +npx markdownlint-cli2 "cookbook/**/*.md" ``` ## Migration Rules diff --git a/hooks/README.md b/hooks/README.md index 5e92642a..d938bac1 100644 --- a/hooks/README.md +++ b/hooks/README.md @@ -45,7 +45,7 @@ it is rewritten into a smaller hook, workflow, or skill-local script. Validate changed Markdown files and any hook scripts before a PR. ```bash -npx markdownlint-cli2 "hooks/README.md" +npx markdownlint-cli2 "hooks/**/*.md" ``` ## Migration Rules diff --git a/instructions/README.md b/instructions/README.md index 9cd4f3fa..1b283ff3 100644 --- a/instructions/README.md +++ b/instructions/README.md @@ -45,7 +45,7 @@ stay in `.github/instructions/` or `.github/custom-instructions.md`. Validate changed Markdown files and future frontmatter checks before a PR. ```bash -npx markdownlint-cli2 "instructions/README.md" +npx markdownlint-cli2 "instructions/**/*.md" ``` ## Migration Rules diff --git a/plugins/README.md b/plugins/README.md index e17aded4..f1af10e5 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -56,7 +56,7 @@ Validate changed Markdown files now. Add manifest validation once the validation reset introduces `validate:plugins`. ```bash -npx markdownlint-cli2 "plugins/README.md" +npx markdownlint-cli2 "plugins/**/*.md" ``` ## Migration Rules diff --git a/skills/README.md b/skills/README.md index f4ced672..3cb13e03 100644 --- a/skills/README.md +++ b/skills/README.md @@ -29,7 +29,8 @@ bundled into plugins only when a plugin needs them. | Path | Purpose | | --- | --- | | `skills/README.md` | Ownership, backlog, and migration rules for this folder. | -| `skills//SKILL.md` | Required entrypoint for a skill. | +| `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. | @@ -59,7 +60,7 @@ Validate changed Markdown files now. Add skill structure checks once the validation reset introduces skill validation. ```bash -npx markdownlint-cli2 "skills/README.md" +npx markdownlint-cli2 "skills/**/*.md" ``` ## Migration Rules diff --git a/workflows/README.md b/workflows/README.md index 9520e07d..2c80c030 100644 --- a/workflows/README.md +++ b/workflows/README.md @@ -48,7 +48,7 @@ Validate changed Markdown files now. Add workflow structure checks once the validation reset introduces portable workflow validation. ```bash -npx markdownlint-cli2 "workflows/README.md" +npx markdownlint-cli2 "workflows/**/*.md" ``` ## Migration Rules