Markdown Audit: CI/CD Linting Scope Optimization

[ashleyshaw]

Summary

Comprehensive audit of 9,024 markdown files identified significant CI/CD optimization opportunities:

• 90.2% of files are portable assets (agents/skills/workflows) including 21% vendored content
• 35-45% estimated CI time savings possible by excluding vendored directories
• 100% frontmatter adoption in GitHub templates vs. 16.5% in portable assets
• Inconsistent exclusion patterns between testing.yml and meta.yml workflows

Key Findings

🔴 CRITICAL: Vendored Content Overhead

Finding	Impact	Files Affected
Bundled plugin-provided documentation in 4+ agents	CI bloat, duplicate linting	1,928+
Platform-managed and directory-installed content	False positives, maintenance burden	800+
Same reference files (figma/gotchas.md) replicated	Duplicate linting, inflated metrics	4+ copies

Recommendation: Exclude */plugin-provided/, */platform-managed/, */directory-installed/ from CI

🟡 HIGH: Inconsistent Exclusion Patterns

testing.yml excludes: .github/reports/, reports/, .github/projects/**

meta.yml excludes (more comprehensive): .github/reports/, */plugin-provided/, */platform-managed/, */directory-installed/*, /agentskills-main/

Recommendation: Unify patterns; use shared .markdownlintignore in both workflows

🟡 MEDIUM: Report Files in Linting Coverage

• 91 report files currently being linted but should be excluded
• Reports are generated outputs, not source documentation

Recommendation: Formally exclude .github/reports/, .github/audits/, .github/metrics/

Frontmatter Adoption

Category	Files	Adoption %	Notes
A (Docs)	754	84.2%	✅ Strong
B (Portable Assets)	8,140	16.5%	⚠️ Weak
D (Templates)	37	100.0%	✅ Excellent
E (Reports)	91	90.1%	✅ Strong

Implementation Phases

Phase 1: CRITICAL (Weeks 1-2) — 35-45% CI time savings

• Update .markdownlint-cli2.config.cjs with vendor exclusions
• Update .github/workflows/testing.yml to match meta.yml
• Verify: ~5,600 files linted (down from ~9,000)

Phase 2: MEDIUM (Weeks 3-4)

• Establish frontmatter schema for Category B
• Create migration guide for agents/*/
• Update meta.agent.js for auto-frontmatter

Phase 3: LONG-TERM (Month 2+)

• Phased Category B standardization
• Quarterly audit reviews

Files to Modify

1. .markdownlint-cli2.config.cjs
2. .github/workflows/testing.yml
3. .github/workflows/meta.yml
4. CLAUDE.md (documentation updates)

Success Criteria

• ✅ CI markdown linting time reduced by 35-45%
• ✅ Consistent exclusion patterns between workflows
• ✅ No false positives from third-party content
• ✅ Full test suite passes

Detailed Audit Report: See .github/projects/active/markdown-audit-ci-optimization/MARKDOWN_AUDIT_FINDINGS.md

Implementation Guide: See .github/projects/active/markdown-audit-ci-optimization/IMPLEMENTATION_GUIDE.md

[linear-code]

LS-1765

[github-actions]

⚠️ This issue does not follow a required issue template.

Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)

The issue will remain open and flagged until the body is corrected.
Please update the issue with one of the official templates:

• https://github.com/lightspeedwp/.github/issues/new/choose

If this was opened by automation, update the automation to preserve the template sections before creating the issue.

[github-actions]

⏱️ Aging and SLA annotation

• Age: 12 day(s)
• SLA state: SLA risk
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-08-05T11:18:50.862Z

Maintained by project-meta-sync workflow.

[ashleyshaw]

Superseded by PR #1223 which includes complete audit findings and implementation guide. New issue created with proper template.