docs(ai): consolidate canonical ai/* sources (#64) #461
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| --- | ||
| title: "Claude Canonical Reference" | ||
| description: "Authoritative Claude-specific guidance and pointers for LightSpeed repositories." | ||
| version: "v1.0.0" | ||
| last_updated: "2026-05-28" | ||
| file_type: "documentation" | ||
| maintainer: "LightSpeed Team" | ||
| authors: ["LightSpeed Team"] | ||
| license: "GPL-3.0" | ||
| tags: ["ai", "claude", "agents", "governance"] | ||
| domain: "governance" | ||
| stability: "stable" | ||
| --- | ||
|
|
||
| # Claude Canonical Reference | ||
|
|
||
| This document is the canonical Claude-specific entry point. | ||
|
|
||
| ## Core References | ||
|
|
||
| - [CLAUDE.md](../CLAUDE.md) - runtime and repo boundary instructions for Claude. | ||
| - [AGENTS.md](../AGENTS.md) - non-negotiable global AI rules. | ||
| - [Custom instructions](../.github/custom-instructions.md) - repo-local | ||
| operating constraints. | ||
|
|
||
| ## Usage Notes | ||
|
|
||
| - Treat `CLAUDE.md` as the direct Claude runtime contract. | ||
| - Apply `AGENTS.md` defaults for standards, safety, accessibility, and | ||
| maintainability. | ||
| - Follow `.github` boundary rules before moving or creating reusable assets. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| title: "Gemini Canonical Reference" | ||
| description: "Authoritative Gemini-specific guidance and pointers for LightSpeed repositories." | ||
| version: "v1.0.0" | ||
| last_updated: "2026-05-28" | ||
| file_type: "documentation" | ||
| maintainer: "LightSpeed Team" | ||
| authors: ["LightSpeed Team"] | ||
| license: "GPL-3.0" | ||
| tags: ["ai", "gemini", "agents", "governance"] | ||
| domain: "governance" | ||
| stability: "stable" | ||
| --- | ||
|
|
||
| # Gemini Canonical Reference | ||
|
|
||
| This document is the canonical Gemini-specific entry point. | ||
|
|
||
| ## Core References | ||
|
|
||
| - [AGENTS.md](../AGENTS.md) - global AI rules and contribution standards. | ||
| - [Custom instructions](../.github/custom-instructions.md) - repo-local | ||
| operating constraints. | ||
| - [Model recommendation prompt](../.github/prompts/model-recommendation.prompt.md) | ||
| - legacy reference for model selection and migration notes. | ||
|
|
||
| ## Usage Notes | ||
|
|
||
| - Follow `AGENTS.md` as the baseline for all Gemini-authored changes. | ||
| - Keep repo-native governance changes in `.github/` and reusable assets in top | ||
| level portable folders. | ||
| - Treat prompt-library model notes as secondary guidance, not canonical policy. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| --- | ||
| title: "AI Runner Inventory" | ||
| description: "Canonical inventory of JavaScript and Bash runners plus telemetry hooks used in this repository." | ||
| version: "v1.0.0" | ||
| last_updated: "2026-05-28" | ||
| file_type: "documentation" | ||
| maintainer: "LightSpeed Team" | ||
| authors: ["LightSpeed Team"] | ||
| license: "GPL-3.0" | ||
| tags: ["ai", "runners", "javascript", "bash", "telemetry"] | ||
| domain: "governance" | ||
| stability: "active" | ||
|
There was a problem hiding this comment.
This new documentation file sets Useful? React with 👍 / 👎. |
||
| --- | ||
|
|
||
| # AI Runner Inventory | ||
|
|
||
| This file documents runner entry points currently used by repository automation. | ||
|
|
||
| ## JavaScript Runners | ||
|
|
||
| - `scripts/agents/*.agent.js` - primary operational agent runners. | ||
| - `scripts/workflows/release/*.cjs` - workflow runtime wrappers for release and | ||
| telemetry logic. | ||
| - `scripts/validation/*.js|*.cjs` - validation runners used in CI and local | ||
| quality gates. | ||
|
|
||
| ## Bash Runners | ||
|
|
||
| - GitHub workflow inline shell remains present in selected workflows during | ||
| phased migration. | ||
| - Local shell hooks under `.husky/` (`pre-commit`, `pre-push`) orchestrate | ||
| Node-based checks. | ||
| - Portable shell helpers under `skills/**/scripts/*.sh` remain out of scope for | ||
| phase-1 workflow migration. | ||
|
|
||
| ## Telemetry Hooks | ||
|
|
||
| - `.github/workflows/release.yml` trigger telemetry is emitted via | ||
| `scripts/workflows/release/trigger-telemetry.cjs` and uploaded as | ||
| `trigger-telemetry.json` artifact. | ||
| - Workflow-level health and metrics updates are recorded through existing | ||
| metrics automation and reporting workflows in `.github/workflows/`. | ||
|
|
||
| ## Migration Direction | ||
|
|
||
| - Default new runner logic to Node CLI scripts. | ||
| - Avoid introducing new Bash-heavy control-flow in workflows. | ||
| - Keep legacy shell runner inventory explicit until phase-2 migration is | ||
| complete. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| --- | ||
| title: "AI Agents Canonical Reference" | ||
| description: "Authoritative index for LightSpeed AI agent governance and implementation sources." | ||
| version: "v1.0.0" | ||
| last_updated: "2026-05-28" | ||
| file_type: "documentation" | ||
| maintainer: "LightSpeed Team" | ||
| authors: ["LightSpeed Team"] | ||
| license: "GPL-3.0" | ||
| tags: ["ai", "agents", "governance", "automation"] | ||
| domain: "governance" | ||
| stability: "stable" | ||
| --- | ||
|
|
||
| # AI Agents Canonical Reference | ||
|
|
||
| This file is the canonical AI agents index for the LightSpeed `.github` control | ||
| plane. | ||
|
|
||
| ## Primary Sources | ||
|
|
||
| - [AGENTS.md](../AGENTS.md) - organisation-wide AI rules and coding standards. | ||
| - [Main agent index](../agents/agent.md) - portable agent specs. | ||
| - [Repo-local custom instructions](../.github/custom-instructions.md) - | ||
| maintenance boundaries for this repository. | ||
|
|
||
| ## Agent Source-of-Truth Policy | ||
|
|
||
| - Global governance and behaviour rules belong in `AGENTS.md`. | ||
| - Reusable agent specs belong in `agents/`. | ||
| - Repo-local operational instructions belong in `.github/instructions/` and | ||
| `.github/custom-instructions.md`. | ||
| - Legacy `.github/agents/` content is transitional and should not become the | ||
| long-term canonical source for reusable specs. | ||
|
|
||
| ## Related Canonical AI Docs | ||
|
|
||
| - [Claude](./Claude.md) | ||
| - [Gemini](./Gemini.md) | ||
| - [Runners](./RUNNERS.md) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For body edits like this added paragraph,
scripts/validation/validate-frontmatter-freshness.jsrequires the affected Markdown frontmatter to change; runningnpm run validate:frontmatter:changed -- --base 457671513f9064159c70bbde3edb716d7e5c6602^ --head 457671513f9064159c70bbde3edb716d7e5c6602reports failures forAGENTS.md,CLAUDE.md, andREADME.mdbecause their versions were not bumped, andCLAUDE.mdalso keepslast_updated: "2026-05-20". Please update the edited documents' frontmatter with these content changes so the freshness gate passes.Useful? React with 👍 / 👎.