Codex/ash refactor

[ashleyshaw]

General Pull Request

This PR establishes the first set of portable AI source folder ownership docs for the repository. It adds top-level README files for the new portable asset areas so contributors have clear rules for what belongs in each folder, what should stay under .github/, and how future migrations should be handled.

The change is documentation-first and supports the ongoing portable AI/plugin restructure work by defining boundaries for schemas, agents, cookbook content, hooks, instructions, plugins, skills, and workflows. It also updates the root README.md so these new folders are discoverable from the main repository entrypoint.

Linked issues

Closes #290

Changelog

Added

• Added ownership and migration guidance for new portable top-level folders:
  • .schemas/
  • agents/
  • cookbook/
  • hooks/
  • instructions/
  • plugins/
  • skills/
  • workflows/

Changed

• Updated the root README.md to document the new portable AI source folders and link to each folder’s README.
• Clarified which assets should remain in .github/ versus which can be migrated into portable top-level locations over time.

Fixed

• Reduced ambiguity around where reusable AI assets should live during the portable plugin restructure work.

Removed

• None.

---

Risk Assessment

Risk Level: Low

Potential Impact:

This is a documentation-only change. If incorrect, the main risk is contributors placing files in the wrong location or following the wrong migration path for portable assets.

Mitigation Steps:

• Scope is limited to README/documentation files.
• No runtime code, workflows, or automation behaviour changed.
• Each new folder README includes explicit ownership, usage, validation, and migration rules.
• Root documentation was updated alongside the new folders to keep navigation consistent.

---

How to Test

Prerequisites

• Check out PR Codex/ash refactor #325 locally.

Test Steps

1. Open the root README.md and confirm the new Portable AI Source Folders section is present.
2. Open each new folder README and confirm it defines:
   • overview
   • ownership
   • structure
   • usage
   • validation
   • migration rules
3. Verify the guidance is consistent about:
   • what remains in .github/
   • what is intended to become portable
   • how migrations should be tracked
4. Confirm linked references resolve correctly, especially:
   • the portable AI plugin restructure PRD
   • issue #290

Expected Results

• The repository root README clearly links to all new portable source folders.
• Each new folder contains a focused README with governance and migration guidance.
• Documentation is internally consistent and supports the planned portable asset restructure.

Edge Cases to Verify

• Links render correctly in GitHub
• Relative paths are valid from each README location
• No folder guidance contradicts existing .github ownership rules
• Validation commands shown in docs match the repo’s current tooling expectations

---

Checklist (Global DoD / PR)

• All AC met and demonstrated
• Tests added/updated (unit/E2E as appropriate)
• A11y considerations addressed where relevant
• Docs/readme/changelog updated (if user-facing)
• Security/perf impact reviewed where relevant
• Code/design reviews approved
• CI green; linked issues closed; release notes prepared (if shipping)
• Risk assessment completed above
• Testing instructions provided above

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Rate limit exceeded

@ashleyshaw has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 2 minutes and 38 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 74b7c4d4-222f-40f2-aad4-ed7a615d4042

📥 Commits

Reviewing files that changed from the base of the PR and between c511cf0 and 850c67b.

📒 Files selected for processing (9)

• .schemas/README.md
• README.md
• agents/README.md
• cookbook/README.md
• hooks/README.md
• instructions/README.md
• plugins/README.md
• skills/README.md
• workflows/README.md

Note

.coderabbit.yml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'auto_labels', 'auto_assign', 'auto_review'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ash-refactor

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request establishes a new organizational structure for portable AI assets by introducing eight top-level directories, each containing documentation on ownership, migration rules, and usage. The feedback primarily highlights the need to update validation commands to use glob patterns for comprehensive linting, clarify the location of the referenced 'migration map,' and ensure that the main repository documentation and architecture diagrams are updated to reflect these structural changes.

[gemini-code-assist]

The 'migration map' is referenced here and in several other READMEs, but its location is not specified. Please clarify where this map is located (e.g., a specific file like MIGRATION.md or a link to a tracking issue) to ensure contributors can follow the migration rules.

[ashleyshaw]

There is no MIGRATION.md file, we need a new file added to /docs folder

[ashleyshaw]

@copilot apply changes based on this feedback

[ashleyshaw]

@copilot apply changes based on this feedback add a /docs/MIGRATION.md file and add any migration notes that we need to consider.

[gemini-code-assist]

With the addition of these 8 new top-level folders for Portable AI assets, the 'Repository Structure' overview (lines 91-108) and the Mermaid architecture diagrams (lines 125 and 356) are now incomplete. Please ensure these sections are updated to reflect the new repository layout.

[Copilot]

Pull request overview

Adds first-pass ownership/index READMEs for the new top-level “portable” source folders introduced by the portable AI plugin restructure work, and updates the root README to link to them.

Changes:

• Added folder-level README contracts for new portable source roots (/.schemas, /agents, /cookbook, /hooks, /instructions, /plugins, /skills, /workflows).
• Documented purpose, ownership, expected structure, migration rules, and basic Markdown validation commands for each folder.
• Updated the root README.md to include the new “Portable AI Source Folders” section and refreshed last_updated.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
.schemas/README.md	Defines ownership and migration rules for portable schema assets.
agents/README.md	Defines scope/structure for portable agent specifications.
cookbook/README.md	Defines scope/structure for portable recipes and examples.
hooks/README.md	Defines scope/structure for portable hooks/guardrails and safety expectations.
instructions/README.md	Defines scope/structure for portable instruction files outside .github/.
plugins/README.md	Defines plugin family strategy and rules for installable plugin bundles.
skills/README.md	Defines skill folder contract and an initial skills backlog table.
workflows/README.md	Defines portable agentic workflow boundary vs GitHub Actions.
README.md	Updates last_updated and adds links to the new portable folder indexes.

Comments suppressed due to low confidence (2)

skills/README.md:46

• The "Initial Skills Backlog" table is formatted with an extra leading pipe (||), which creates blank columns when rendered. Reformat it as a normal Markdown table so the columns align as intended.

| 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 |

plugins/README.md:45

• The "Plugin Family Strategy" table uses || row prefixes, which renders with blank columns. Reformat to a standard Markdown table so the three columns (Plugin family, Purpose, Status) render correctly.

| 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 |

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• coderabbit.ai
  • Triggering command: /usr/local/bin/node node /home/REDACTED/work/.github/.github/scripts/validation/validate-coderabbit-yml.cjs /home/REDACTED/work/.github/.github/scripts/validation/__fixtures__/valid-coderabbit.yml (dns block)
  • Triggering command: /usr/local/bin/node node /home/REDACTED/work/.github/.github/scripts/validation/validate-coderabbit-yml.cjs /home/REDACTED/work/.github/.github/scripts/validation/__fixtures__/invalid-coderabbit.yml (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[ashleyshaw]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All the portable folder README tables already use standard single-pipe Markdown formatting (| col |). The review comments about double-pipe formatting (|| col |) were addressed in commit 850c67b, and all subsequent checks confirm the tables are correctly formatted. No additional changes are needed.