Squad Test

.copilot/skills/docs-standards/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: "docs-standards"
+description: "Microsoft Style Guide + Squad-specific documentation patterns"
+domain: "documentation"
+confidence: "high"
+source: "earned (PAO charter, multiple doc PR reviews)"
+---
+
+## Context
+
+Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability.
+
+## Patterns
+
+### Microsoft Style Guide Rules
+- **Sentence-case headings:** "Getting started" not "Getting Started"
+- **Active voice:** "Run the command" not "The command should be run"
+- **Second person:** "You can configure..." not "Users can configure..."
+- **Present tense:** "The system routes..." not "The system will route..."
+- **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements)
+
+### Squad Formatting Patterns
+- **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data
+- **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy
+- **Experimental warnings:** Features in preview get callout at top
+- **Cross-references at bottom:** Related pages linked after main content
+
+### Structure
+- **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)**
+
+### Test Sync Rule
+- **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit
+
+## Examples
+
+✓ **Correct:**
+```markdown
+# Getting started with Squad
+
+> ⚠️ **Experimental:** This feature is in preview.
+
+Try this:
+\`\`\`bash
+squad init
+\`\`\`
+
+Squad helps you build AI teams...
+
+---
+
+## Install Squad
+
+Run the following command...
+```
+
+✗ **Incorrect:**
+```markdown
+# Getting Started With Squad  // Title case
+
+Squad is a tool which will help users... // Third person, future tense
+
+You can install Squad with npm & configure it... // Ampersand in prose
+```
+
+## Anti-Patterns
+
+- Title-casing headings because "it looks nicer"
+- Writing in passive voice or third person
+- Long paragraphs of dense text (breaks scannability)
+- Adding doc pages without updating test assertions
+- Using ampersands outside code blocks