Skip to content

docs: add docs quality CI — markdown lint, spell check, link validation#396

Merged
bradygaster merged 4 commits intobradygaster:devfrom
diberry:squad/docs-quality-ci
Mar 15, 2026
Merged

docs: add docs quality CI — markdown lint, spell check, link validation#396
bradygaster merged 4 commits intobradygaster:devfrom
diberry:squad/docs-quality-ci

Conversation

@diberry
Copy link
Copy Markdown
Collaborator

@diberry diberry commented Mar 14, 2026

Docs Quality CI — Content Checks (Not Build/Deploy)

Adds a comprehensive docs quality pipeline that catches content regressions before they ship. This is specifically about content quality, not build/generation.

What's new

File Purpose
.markdownlint-cli2.jsonc Markdown lint rules (heading hierarchy, code blocks, empty links — prose-friendly config)
cspell.json Spell check with 100+ project terms (agent names, tech jargon, contributor names)
test/docs-links.test.ts Internal link + anchor validation — verifies every relative .md link resolves AND #heading anchors exist in target files
.github/workflows/squad-docs-links.yml Weekly external link scan via lychee — auto-creates issue on broken links
.lycheeignore Exclusions for rate-limited/auth-gated URLs

CI changes

squad-ci.yml now runs two new steps before build:

  1. npx markdownlint-cli2 — catches markdown formatting issues (~5s)
  2. npx cspell — catches spelling errors (~5s)

Plus test/docs-links.test.ts runs as part of npm test (vitest) — catches broken internal links and anchor mismatches.

Local development

npm run lint:docs — runs both markdownlint + cspell locally.

Design decisions

  • Rules disabled for existing content: Markdownlint has ~15 rules disabled to pass cleanly on existing docs (MD013 line length, MD033 inline HTML, MD040 code block language, etc.). These can be gradually re-enabled.
  • cspell dictionary is comprehensive: Scanned all docs, added every project-specific term. Should have zero false positives on existing content.
  • Link validation is internal-only in CI: External links are checked weekly (not on every PR) to avoid flaky CI from network issues.
  • Anchor validation uses github-slugger algorithm: Heading → anchor conversion matches what Astro/GitHub actually generate.
  • 3 known pre-existing broken links are skipped: Documented in test file, to be fixed separately.

What this catches going forward

  • ✅ Typos in docs (cspell)
  • ✅ Broken internal cross-links (docs-links.test.ts)
  • ✅ Invalid heading anchors (docs-links.test.ts)
  • ✅ Markdown formatting regressions (markdownlint)
  • ✅ Dead external links (weekly lychee scan → auto-issue)

What this does NOT do

  • ❌ Prose/style linting (vale) — deferred, high setup cost
  • ❌ Duplicate content detection — PAO charter rule covers this
  • ❌ Readability scoring — subjective, needs tuning

Closes no specific issue — this is infrastructure for docs quality management.

@diberry diberry mentioned this pull request Mar 15, 2026
Closed
diberry and others added 2 commits March 15, 2026 07:29
@diberry
docs: add docs quality CI — markdown lint, spell check, link validation
5d94377 
- Add markdownlint-cli2 config for consistent markdown formatting
- Add cspell config with project-specific dictionary
- Add internal link + anchor validation test (docs-links.test.ts)
- Add weekly external link check workflow (lychee)
- Add lint:docs script for local development
- Wire markdown lint + spell check into squad-ci.yml

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry
ci: separate docs-quality job from test job
736366b 
Moves markdownlint and cspell into an independent docs-quality job that
doesn't depend on the full npm ci/build. This ensures docs quality checks
run even when the main build has unrelated failures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry diberry force-pushed the squad/docs-quality-ci branch from 4b1e469 to 736366b Compare March 15, 2026 14:29
Copilot AI added 2 commits March 15, 2026 07:32
fix: add jqlang to spell check dictionary
b9e1b64
fix: correct broken troubleshooting anchor link
e9e267f 
Point to dedicated troubleshooting.md instead of non-existent guide.md#troubleshooting anchor.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 15, 2026

@bradygaster Ready for your review — adds markdownlint, cspell, and link-checking CI for docs quality. CI is green. — squad obo dina

@bradygaster bradygaster merged commit c4d9a82 into bradygaster:dev Mar 15, 2026
2 checks passed
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey E2E tests - 7 real user scenarios, 39 assertions (b…
ae4a212 
…radygaster#408)

* chore(squad): Phase 2 launch — thinking feedback, P0 bugs, dual telemetry

Phase 1 complete: 5 issues closed (bradygaster#325, bradygaster#326, bradygaster#327, bradygaster#328, bradygaster#329), 5 PRs merged.
Phase 2 launched with Cheritto (thinking feedback), Hockney (P0 bugs), Saul (dual telemetry).
Decision inbox merged and archived.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore(squad): Phase 2 Wave 1 merged, Wave 2 launched

Session: 2026-02-23T2145-phase2-wave2
Phase 2 Wave 1 complete (PRs bradygaster#351, bradygaster#352, bradygaster#353 merged).
Wave 2 launched: Cheritto on ghost response detection (bradygaster#332), Hockney on error hardening (bradygaster#334).

Changes:
- Session log created: 2026-02-23T2145-phase2-wave2.md
- Merged 3 inbox decisions (Cheritto, Hockney, Saul)
- Deleted inbox files post-merge

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore(squad): Epic bradygaster#323 complete — all phases shipped 🎉

All 3 phases delivered:
- Phase 1 (Testing Wave): 6 issues closed
- Phase 2 (Improvement): 6 issues closed
- Phase 3 (Breathtaking): 7 issues closed
- 17 PRs merged, 19 issues closed total

Session log: 2026-02-23T2320-epic-complete.md
Decisions merged from inbox: P2 UX Polish, first-run wow moment

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* hostile QA: end-to-end quality assessment — 10 findings, 4 HIGH severity

Candid assessment requested by Brady. Traced every code path in cli-entry.ts,
shell/index.ts, shell/commands.ts, App.tsx, coordinator.ts, spawn.ts, and the
SDK adapter client.

Key findings:
- Dead sessions never evicted from agentSessions Map after connection drop
- No React ErrorBoundary — any render throw kills the shell
- Nasty-inputs corpus (95 strings) is never imported by any test
- No SIGTERM handler in interactive shell
- MemoryManager exported but never instantiated (dead code)
- Single streaming content slot clobbers multi-agent output
- User input silently dropped during processing (no type-ahead buffer)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore(squad): quality review findings — 7 issues filed

Quality audit complete: 5 agents assessed CLI across testing, coverage, stability, accessibility, UX.
Results: 4 P0 blockers (bradygaster#365–bradygaster#368), 3 P1 items (bradygaster#369–bradygaster#371).
Blocking: Waingro dead sessions, ErrorBoundary, dropped input; Marquez help text consistency.

Changes:
- Logged session summary to .squad/log/2026-02-24T0205-quality-review-complete.md
- Updated .squad/identity/now.md with quality review findings and new issue numbers

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore(squad): merge decision — Marquez UX audit findings

Quality assessment merged from inbox (Grade B): 11 improvements (3 P0, 4 P1, 4 P2). help text, stub commands, vocabulary, separators, roster.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore(squad): test sprint launch

Session: 2026-02-24T0210-test-sprint
Changes:
- Logged test sprint: 5 agents, 7+ issues
- Branches: P0 fixes, stale tests, E2E, hostile/SDK, A11y

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: add human journey E2E tests for 7 real user scenarios

Test the actual human experience, not internal modules. Each describe
block maps to a filed GitHub issue and simulates what a real person
does when they encounter Squad for the first time and beyond.

Journeys tested (39 assertions):
1. I just installed this — squad init creates .squad/, shows ceremony,
   gives clear next step, writes first-run marker, exits cleanly
2. My first conversation — welcome banner shows agent roster with
   names/roles/emojis, project description, focus area, first-run
   ceremony is one-time only
3. I'm waiting and getting anxious — ThinkingIndicator appears
   immediately, shows elapsed time, activity hints override default,
   NO_COLOR mode works
4. Something went wrong — friendly error messages with remediation
   tips, no stack traces leaked, whitespace input handled gracefully
5. I want to talk to a specific agent — @agent routing, case-
   insensitive matching, comma syntax, unknown names fall to
   coordinator
6. I'm a power user now — /help, /status, /agents, /history, /quit
   all return useful output, unknown commands guide to /help
7. I came back the next day — state persists, first-run consumed,
   team still loaded, focus area survives between sessions

Closes bradygaster#383, bradygaster#384, bradygaster#385, bradygaster#386, bradygaster#394, bradygaster#396, bradygaster#398

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Copy polish: warmer, human-centered messages across CLI

Every message now feels helpful, not corporate. Changes include:

- cli-entry.ts: 'Your AI team, always ready' instead of generic desc
- commands.ts: Status output changed from 'Root/Active now' to 'Home/Active'
- Help text: 'Check your team' instead of 'Show which squad'
- InputPrompt: 'Message or @agent' instead of corporate placeholder
- App.tsx: 'Your team is assembled. Let's try:' (warmer tone)
- init.ts: 'Your team is assembled' instead of 'ready'
- ThinkingIndicator: Dynamic thinking phrases (Processing, Working)
- All command help: Casual verbs (Who's here, Fresh screen, Leave)

Tests updated to match new output strings. All 125+ CLI tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey — Power user (bradygaster#396) (bradygaster#481)
ed383c6 
Add E2E journey test covering advanced shell features:
- /help and /status slash commands
- Tab completion for /commands and @agent names
- Ctrl+C cancel during processing
- Double Ctrl+C exit
- Multiple slash commands in sequence
- @agent direct routing with complex messages

Closes bradygaster#396

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey — My first conversation (bradygaster#384) (bradyg…
1ccf737 
…aster#482)

* test: human journey — Power user (bradygaster#396)

Add E2E journey test covering advanced shell features:
- /help and /status slash commands
- Tab completion for /commands and @agent names
- Ctrl+C cancel during processing
- Double Ctrl+C exit
- Multiple slash commands in sequence
- @agent direct routing with complex messages

Closes bradygaster#396

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: human journey — My first conversation (bradygaster#384)

Add E2E journey test covering a new user's first interaction with Squad:
- Welcome banner display (title, version, agents, help hint)
- First message submission and coordinator routing
- Thinking indicator during processing
- Receiving agent responses via ShellApi
- /help command exploration
- /status agent roster check
- @agent direct message routing
- Graceful exit (exit, quit, Ctrl+C)

28 tests across 8 journey steps using createShellHarness() pattern.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey — Something went wrong (bradygaster#386) (bradyga…
051dfd2 
…ster#483)

* test: human journey — Power user (bradygaster#396)

Add E2E journey test covering advanced shell features:
- /help and /status slash commands
- Tab completion for /commands and @agent names
- Ctrl+C cancel during processing
- Double Ctrl+C exit
- Multiple slash commands in sequence
- @agent direct routing with complex messages

Closes bradygaster#396

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: human journey — My first conversation (bradygaster#384)

Add E2E journey test covering a new user's first interaction with Squad:
- Welcome banner display (title, version, agents, help hint)
- First message submission and coordinator routing
- Thinking indicator during processing
- Receiving agent responses via ShellApi
- /help command exploration
- /status agent roster check
- @agent direct message routing
- Graceful exit (exit, quit, Ctrl+C)

28 tests across 8 journey steps using createShellHarness() pattern.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: human journey — Something went wrong (bradygaster#386)

Add E2E journey tests covering error scenarios users may encounter:

- SDK connection failure shows helpful error message
- Agent dispatch failure is caught and shown to user
- Invalid /command shows conversational hint with /help
- Network-like errors during streaming are handled gracefully
- ErrorBoundary catches React rendering errors
- Shell remains usable after errors (can submit new messages)
- Error messages are user-friendly, not raw stack traces

21 tests across 7 describe blocks verify the full error UX.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey — I'm waiting and getting anxious (bradygaster#385)…
cceeab8 
… (bradygaster#484)

* test: human journey — Power user (bradygaster#396)

Add E2E journey test covering advanced shell features:
- /help and /status slash commands
- Tab completion for /commands and @agent names
- Ctrl+C cancel during processing
- Double Ctrl+C exit
- Multiple slash commands in sequence
- @agent direct routing with complex messages

Closes bradygaster#396

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: human journey — I'm waiting and getting anxious (bradygaster#385)

Add E2E journey test covering the user experience while waiting for
agent responses: thinking indicators, phase labels, activity hints,
streaming content updates, /status visibility, Ctrl+C cancellation,
and recovery after cancel.

14 test cases validate the full anxiety-to-reassurance path.

Closes bradygaster#385

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@diberry @bradygaster