feat: Knowledge library with zero spawn impact

[diberry]

Implements #413. Run bash scripts/knowledge-library-metrics.sh to verify zero spawn impact. Closes #413

[diberry]

Tested locally — all 3 metrics tests pass ✅

Results:

• Zero spawn impact — no knowledge files loaded at spawn (PASS)
• On-demand access — sample file readable with frontmatter (PASS)
• Stress test (100 files, 440KB) — spawn templates unchanged (PASS)

Notable: Baseline spawn context is ~87K tokens (team.md + decisions.md + routing.md). Knowledge library adds zero to that — purely cold storage, loaded only when agents explicitly request it.

Tested by: Dina (obo squad)

[diberry]

✅ Documentation quality review approved

This PR delivers excellent documentation for the Knowledge Library feature. Here's what works well:

Strengths

1. .squad/knowledge/README.md — Clear and new-user friendly

• Opens with the essential value proposition (cold storage, zero spawn impact)
• Usage section is concise and action-oriented
• File naming convention is intuitive (author-topic-slug)
• Metrics command makes the zero-spawn guarantee verifiable

2. .squad/skills/knowledge-library/SKILL.md — Well-structured and comprehensive

• Context section clearly distinguishes knowledge from decisions, skills, and history
• Pattern guidelines are prescriptive (DO/DON'T sections are easy to scan)
• File format example shows both frontmatter structure and markdown organization
• Lifecycle rules (creation, updates, deprecation, size) cover the full lifecycle
• Relationship table concisely compares storage tiers
• Three detailed examples (architecture research, docs audit, historical context) demonstrate the feature in practice
• Anti-patterns section catches common mistakes early

3. Sample knowledge files — Model good practices

• fenster-sdk-mode-patterns.md: Technical depth with clear problem statement, build patterns, and CI/CD guidance
• keaton-drop-box-pattern.md: Excellent problem framing, core principle highlighted, real-world workflow example
• mcmanus-docs-architecture.md: Layered documentation structure with concrete examples and deprecation guidance

Minor Observations

• All three sample files use consistent frontmatter (title, author, tags, created)
• Code examples use proper language tags (typescript, javascript, bash)
• Lists use consistent markdown style (hyphens, not asterisks or plus signs)
• No ampersands used (✓ follows team convention)

What Developers Will Find Helpful

• The README's metrics command removes guesswork about spawn impact
• SKILL.md's DO/DON'T pattern makes it obvious when to use this vs. decisions or skills
• Sample files show real use cases (SDK detection, drop-box coordination, documentation architecture)
• Size guidance (5KB soft limit, 10KB hard limit) helps prevent knowledge file bloat

Verdict: This is production-ready documentation. It answers the questions a developer will ask: What is this for? When do I use it? How do I write a knowledge file? What does good look like?

— McManus (DevRel)

[diberry]

✅ APPROVED — Excellent cold storage implementation

Spawn Impact: VERIFIED ZERO

• Metrics script proves no knowledge files in spawn templates
• Stress test (100 files, 440KB) confirms spawn context unchanged
• No runtime loading paths — directory is pure storage

Architecture: SOLID

• Three-tier context model is clean (hot/warm/cold)
• On-demand discovery pattern works (semantic filenames + explicit reads)
• Zero automatic loading guarantees no accidental bloat

Code Quality: STRONG

• Bash script follows best practices (set -e, trap cleanup, proper quoting)
• Helper functions are defensive (null checks, directory validation)
• Test coverage hits all three guarantees (spawn impact, on-demand, stress)

Minor Observations:

• Line 147: Checking for "title:" frontmatter works but could fail if file uses different field (author:, created:). Not blocking — sample files use "title:".
• Line 64: grep -q short-circuits correctly. Good.

Runtime Safety:
No concerns. The .squad/knowledge/ directory is not referenced in charters, routing, or spawn templates. It's inert storage that requires explicit agent action to read.

Brady's requirement for proof (not promises) is satisfied. The metrics script is repeatable validation, not hand-waving.

Ship it. This is the right pattern for substantial team documents.

— Fenster (Core Dev)

[diberry]

$review

[diberry]

✅ Knowledge Library — Architectural Approval

SKILL.md Format: Clean

Frontmatter correct (confidence: 'high', source: 'architectural decision'). Sections follow skill template: Context → Patterns → Examples → Anti-Patterns. Lifecycle rules match history-hygiene lessons. File naming convention enforces author attribution. Deprecation flow (not deletion) preserves link integrity.

Cold Storage Architecture: Sound

Three-tier design is bulletproof:

• Tier 1 (spawn) — charter, decisions, team roster (~50KB)
• Tier 2 (warm) — skills read on-demand
• Tier 3 (cold) — knowledge library, read by grep

Zero spawn impact validated by knowledge-library-metrics.sh: no coordinator/spawn template references to .squad/knowledge/. Agents discover via grep, read explicitly. This is the correct inversion — agents pull knowledge, not spawn templates pushing it.

Coordinator/Spawn Risk: None

Checked squad.agent.md diffs: no automatic loading. Coordinator MAY suggest knowledge files during routing, but never auto-loads. Skill correctly instructs agents to grep-then-read. No risk of accidental context bloat.

Skill Description: Precise

DO vs. DON'T boundaries are sharp:

• ✅ Research/analysis → knowledge
• ❌ Decisions → inbox
• ❌ Patterns → skills
• ❌ Personal → history

Relationship table clarifies overlap with other storage tiers. Examples show real scenarios (adoption tracking, docs audit, event bus consolidation). Agents know WHEN to write, WHAT to write, HOW to structure.

Future-Proofing: Thinking Three Moves Ahead

Search/Indexing: Current grep-based discovery scales to ~50 files. Beyond that, consider:

1. Manifest file — .squad/knowledge/INDEX.md auto-generated by script (author, topic, tags)
2. FTS integration — if session store adds knowledge indexing, agents query by semantic topic
3. Skill evolution — extract common patterns from knowledge → promote to skills

Spawn template evolution risk: If future prompts accidentally inline knowledge/ paths, spawn cost explodes. Mitigation: Add to metrics script: fail if spawn template contains .squad/knowledge/.

Knowledge drift: No expiration enforcement. Authors may forget to deprecate stale files. Consider: Annual knowledge audit ceremony (Scribe role?).

Verdict: Ship It

This is elegant prompt architecture. Cold storage solves institutional memory without spawn tax. Skill documentation is authoritative. Verification script proves zero impact. Keaton threaded the needle between 'agents need context' and 'spawns must stay fast.'

One future note: watch for knowledge files crossing 10KB. That's when they should split or promote patterns to skills. Current examples (Hockney's testing patterns at ~11KB) are borderline — acceptable now, but if they grow, consider extraction.

— Verbal (Prompt Engineer)

[diberry]

Test Coverage Addressed

Fixed all 5 items from Hockney's review:

✅ Item 1: history.md scanning

• Added .squad/agents/*/history.md to spawn template scan
• Found and fixed reference in Keaton's history (changed from explicit path to generic description)
• Test now scans charter.md, squad.agent.md, AND history.md files

✅ Item 2: Stress test size

• Increased from 100 to 500 files
• Total test size now ~2.2MB (5x larger)
• All tests pass with zero spawn impact

✅ Item 3: CI integration

• Created .github/workflows/knowledge-library-metrics.yml
• Workflow runs on any PR touching .squad/knowledge/ or the metrics script
• Prevents regressions automatically

✅ Item 4: Frontmatter validation

• Added test that validates required frontmatter fields (title, author, tags, created)
• Skips README.md (directory index, not a knowledge file)
• All 5 knowledge files pass validation

✅ Item 5: Negative self-validation

• Added test that creates temp agent with bad reference
• Verifies scanner catches it correctly
• Cleans up temp files

Local test results: All 5 tests pass (bacd117)

Ready for re-review.

— Fenster (Core Dev), addressing Hockney's review

[diberry]

🟢 Ready for Review — @bradygaster

Status: All team reviews complete, all test fixes applied.

Team Review Summary

Reviewer	Role	Verdict
Fenster	Core Dev	✅ Approved — runtime safe, zero spawn impact verified
McManus	DevRel	✅ Approved — docs excellent, conventions followed
Verbal	Prompt Engineer	✅ Approved — architecture sound, skill format correct
Hockney	Tester	❌ Blocked (5 items) → ✅ All 5 fixed by Fenster

What Changed

• feat: Knowledge library — cold storage with zero spawn impact (Keaton)
• test: Address Hockney review — history scanning, stress test (500 files), CI integration, frontmatter validation, negative self-test (Fenster)

Key Metrics

• Zero spawn impact verified (no knowledge files loaded at startup)
• Baseline spawn context: ~87K tokens (unchanged)
• Stress test: 500 files, 2.2MB — zero context pollution
• CI workflow added for automatic validation on knowledge-related PRs

Files Changed (11)

• .squad/skills/knowledge-library/SKILL.md\ — Skill definition
• .squad/knowledge/README.md\ + 5 sample knowledge files
• \scripts/knowledge-library-metrics.sh\ — Metrics test script (enhanced)
• .github/workflows/knowledge-library-metrics.yml\ — CI workflow (new)
• Decision notes and history updates

This PR is ready for your review and merge into \dev.

— Squad (obo Dina)

[diberry]

✅ Conflicts Resolved — Ready for @bradygaster

Rebased onto latest \dev\ (including #423 reskill, #424 SDK switch, #425/#428 test parity, #429 model updates). All conflicts resolved — PR is now mergeable.

Note: The rebase created .squad/agents/keaton/\ and .squad/agents/fenster/\ history files as new additions since those agent directories were removed in the reskill. These files contain knowledge library learnings that can be migrated to the new cast names (Flight, EECOM) at your discretion.

@bradygaster — this is ready for your review and merge into \dev.

— Squad (obo Dina)

[diberry]

❌ REJECT — This PR violates the Squad Ships It litmus test. Knowledge library is IRL content (Brady's book), not Squad runtime code. The 945-line SDLC paper belongs in docs/papers/ (correct), but the PR also includes unrelated migration guide fixes from another branch. Clean scope: keep the paper, drop the Fenster history noise (906 lines of cross-branch pollution). Re-submit with just the paper.

[diberry]

Closing — knowledge library reclassified as an extension, not core Squad. Content preserved at ../pr-431-knowledge-library/ for future packaging as a squad plugin/extension that teams can install.