[Epic] Portable AI plugin restructure: validation, docs, pilot, and release

[ashleyshaw]

Epic Summary

Restart the validation layer smaller, document the architecture, test local tool compatibility, pilot the plugin in one LightSpeed repository, and prepare release readiness notes.

Linked Stories/Tasks

• Batch 05: validation reset.
• Batch 06: pilot and release.
• Child issue links:
  • [Maintenance] Fix invalid JSON schema syntax before validator reset #311 [Maintenance] Fix invalid JSON schema syntax before validator reset
  • [Build/CI] Split validation commands from mutating format and fix commands #312 [Build/CI] Split validation commands from mutating format and fix commands
  • [Build/CI] Add read-only validate:structure command #313 [Build/CI] Add read-only validate:structure command
  • [Build/CI] Add read-only plugin and skill validators #314 [Build/CI] Add read-only plugin and skill validators
  • [Build/CI] Add read-only frontmatter and local link validators #315 [Build/CI] Add read-only frontmatter and local link validators
  • [Test Coverage] Fix misleading coverage reporting and noisy import side effects #316 [Test Coverage] Fix misleading coverage reporting and noisy import side effects
  • [Compatibility] Run local tool smoke tests for the pilot plugin #317 [Compatibility] Run local tool smoke tests for the pilot plugin
  • [Feature] Pilot lightspeed-github-ops in one LightSpeed repository #318 [Feature] Pilot lightspeed-github-ops in one LightSpeed repository
  • [Documentation] Document pilot findings and follow-up decisions #319 [Documentation] Document pilot findings and follow-up decisions
  • [Research] Create future plugin pack backlogs #320 [Research] Create future plugin pack backlogs
  • [Release] Prepare pilot plugin restructure release readiness checklist #321 [Release] Prepare pilot plugin restructure release readiness checklist

Milestones & Timeline

• Milestone: Portable AI Plugin Restructure - Stabilisation.
• Sequence: runs after pilot plugin skeleton exists; some validation tasks can start earlier if they are read-only.

Delivery Plan

Phase 1 — Safety-net foundations

Active workstream.

Includes:

• [Maintenance] Fix invalid JSON schema syntax before validator reset #311 [Maintenance] Fix invalid JSON schema syntax before validator reset
• [Build/CI] Split validation commands from mutating format and fix commands #312 [Build/CI] Split validation commands from mutating format and fix commands
• [Build/CI] Add read-only validate:structure command #313 [Build/CI] Add read-only validate:structure command
• [Build/CI] Add read-only plugin and skill validators #314 [Build/CI] Add read-only plugin and skill validators
• [Build/CI] Add read-only frontmatter and local link validators #315 [Build/CI] Add read-only frontmatter and local link validators
• [Test Coverage] Fix misleading coverage reporting and noisy import side effects #316 [Test Coverage] Fix misleading coverage reporting and noisy import side effects

Phase 2 — Pilot proof

Starts after the validation baseline is complete and the pilot plugin package is stable.

Includes:

• [Compatibility] Run local tool smoke tests for the pilot plugin #317 [Compatibility] Run local tool smoke tests for the pilot plugin
• [Feature] Pilot lightspeed-github-ops in one LightSpeed repository #318 [Feature] Pilot lightspeed-github-ops in one LightSpeed repository

Phase 3 — Capture and package

Starts after the pilot has produced stable findings.

Includes:

• [Documentation] Document pilot findings and follow-up decisions #319 [Documentation] Document pilot findings and follow-up decisions
• [Research] Create future plugin pack backlogs #320 [Research] Create future plugin pack backlogs
• [Release] Prepare pilot plugin restructure release readiness checklist #321 [Release] Prepare pilot plugin restructure release readiness checklist

Phase Gate

Before Phase 2 begins, confirm:

• Validation baseline complete.
• Validation commands are non-mutating.
• Validation signal is trustworthy enough for pilot use.
• Pilot plugin package is stable.

Acceptance Criteria

• Validation commands are non-mutating.
• Plugin, skill, frontmatter, structure, and link checks exist.
• Invalid JSON schema syntax fixed.
• Tool compatibility smoke tests documented.
• One LightSpeed repo pilot completed.
• Future plugin pack backlog drafted.
• Release readiness checklist completed.
• Milestone closed.

Dependencies / Blockers

• Needs a stable pilot plugin package.
• Needs local dependencies bootstrapped with npm ci.

Additional Context

This epic owns the safety net. It should prevent the migration from becoming another large, hard-to-validate JavaScript layer too early.

Definition of Ready (DoR)

• Epic goal and scope defined.
• Linked stories/tasks listed.
• Milestones and timeline mapped.
• Dependencies/blockers identified.
• Estimate added.
• Stakeholders/approvers listed.

Definition of Done (DoD)

• All linked stories/tasks completed and closed.
• Documentation/changelog updated.
• QA and testing complete.
• Milestone closed and release notes prepared.

[linear-code]

LS-600