Instruction File Standards

[ashleyshaw]

Overview

Create docs/INSTRUCTIONS_STANDARDS.md — documentation standards for portable, reusable instruction files for agents, Copilot, and teams.

Research & Content Creation

Planning Reference:

• PLAN-EXPANDED.md § 3. INSTRUCTIONS_STANDARDS.md

Research Prompt:

Document instruction file standards for LightSpeed. Research and create:

1. Instruction file purpose — Portable, reusable guidance for Copilot, agents, teams
2. File format — Markdown + YAML frontmatter specification
3. Folder structure — instructions/{scope}.instructions.md pattern
4. Frontmatter — Required vs. optional fields, NO references field constraint (use inline links)
5. Mandatory sections: Role declaration, Overview, General Rules, Detailed Guidance, Examples, Validation
6. Best practices — Clarity, conciseness, actionability
7. Real examples — Reference existing instruction files from .github/instructions/ and instructions/
8. Deprecation & migration — How to update/retire old instructions

Mermaid diagrams (2-3 required):

• Instruction hierarchy: global → repo-specific → agent-specific
• Instruction lifecycle: creation → review → publication → deprecation

Key constraint: Document that references frontmatter field is removed; use inline links instead.

Definition of Ready

• Planning reviewed
• Real instruction file examples identified from repo
• Constraint understood: NO references field

Definition of Done

• docs/INSTRUCTIONS_STANDARDS.md created
• 2-3+ Mermaid diagrams included
• Real examples from repo
• references field constraint documented
• All validation checks pass
• UK English throughout
• PR docs(standards): Agent & Skills Standards Comprehensive Documentation - Batch 1 #1251 updated

Files & References

File: docs/INSTRUCTIONS_STANDARDS.md
Epic: #1261
PR: #1251
Plan: PLAN-EXPANDED.md

[linear-code]

LS-1814

[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: 11 day(s)
• SLA state: SLA risk
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-08-04T21:46:07.391Z

Maintained by project-meta-sync workflow.

[ashleyshaw]

♻️ Reopened automatically — this issue was closed with unchecked items remaining in the body. Please complete all tasks before closing.