Skip to content

docs: Add extensibility and building extensions guides#436

Merged
bradygaster merged 2 commits intobradygaster:devfrom
diberry:squad/extensibility-guide
Mar 18, 2026
Merged

docs: Add extensibility and building extensions guides#436
bradygaster merged 2 commits intobradygaster:devfrom
diberry:squad/extensibility-guide

Conversation

@diberry
Copy link
Copy Markdown
Collaborator

@diberry diberry commented Mar 16, 2026 •
edited
Loading

Summary

Consolidates the extensibility decision tree and building extensions how-to into a single PR.

What this adds

Extensibility guide (guide/extensibility.md):

Building extensions guide (guide/building-extensions.md):

  • 5-step practical tutorial for authoring extensions
  • Directory structure, local testing, sharing via marketplace
  • Real examples and cross-links to related docs

Changes

  • New: docs/src/content/docs/guide/extensibility.md
  • New: docs/src/content/docs/guide/building-extensions.md
  • New: docs/.gitignore (Astro build artifacts)
  • Updated: test/docs-build.test.ts (both guide pages)
  • Reverted: .copilot/mcp-config.json and .gitignore (accidental local changes)

Closes #328

Notes

These two guides are complementary:

  • Extensibility = the MAP (where does my idea belong?)
  • Building extensions = the RECIPE (how do I build one?)

@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 16, 2026

⚠️ NEEDS CHANGES — The extensibility guide (559 lines) is valuable but TOO VERBOSE for Brady's 'small and strategic' preference. Decision tree + examples are good, but trim: (1) compress Layer 1/2/3 sections, (2) remove redundant escalation examples, (3) cut the .worktrees/ submodule artifact (worktree pollution). Target: 300-350 lines max. Also update test assertion correctly.

@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 16, 2026

Compressed from 559 lines to 100 lines (82% reduction).

Kept:

  • Three-layer decision tree
  • Claire's RFC as worked example
  • Escalation signals

Cut:

  • Verbose layer explanations
  • Extended how-to sections
  • Repetitive examples

Brady-approved length achieved. 🎯

@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 16, 2026

✅ APPROVED

The compression is excellent. Every concern from my previous review has been addressed:

  • Three-layer model: Still crystal clear. The table and decision tree are easy to navigate.
  • Length: Dropped from 559 to ~100 lines (82% reduction). This hits Brady's 'small and strategic' bar perfectly.
  • Claire's RFC example: Still works as a powerful concrete illustration — shows a sophisticated workflow mapping entirely to Layer 2 primitives without core changes.
  • Escalation guidance: Strong signals throughout. 'You likely need...' and 'You DON'T need...' sections make the boundaries obvious.
  • Language: Clean — no bare ampersands, proper language throughout.

The compression preserved what matters (decision tree, worked example, clear signals) and cut the noise. This is ready to merge.

andikrueger pushed a commit to andikrueger/squad that referenced this pull request Mar 16, 2026
@bradygaster
Fix bradygaster#422: Add context to thinking spinner (bradygaster#436)
41c214f 
* 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>

* Fix bradygaster#422: Add context to thinking spinner

Changed ThinkingIndicator default label from 'Thinking...' to
'Routing to agent...' to give users meaningful feedback during
SDK connection and initial routing phases.

When activityHint is provided (e.g., 'Keaton thinking...'), it
still takes priority. The new default eliminates the 'is it broken?'
anxiety during the 3-5 second cold connection wait.

Updated tests to reflect new default label.

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

* docs: Update Marquez history with bradygaster#422 resolution

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

* Fix bradygaster#420/bradygaster#425: Add immediate SDK connection feedback

Before this fix, the first message sent to the REPL had 2-7 seconds of
dead air while createSession() blocked on SDK connection. Users thought
the shell was hung.

Changes:
- Set 'Connecting to SDK...' hint BEFORE createSession() in dispatchToCoordinator
- Set 'Connecting to <agent>...' hint BEFORE createSession() in dispatchToAgent
- Use setImmediate to give React a tick to render before blocking
- Update hint to 'Routing...' or 'thinking...' after connection completes

The ThinkingIndicator now displays immediately, eliminating perceived hang.

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

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry diberry mentioned this pull request Mar 16, 2026
Closed
@diberry diberry changed the title docs: Add extensibility guide for self-sorting change ideas docs: Add extensibility and building extensions guides Mar 16, 2026
@diberry diberry force-pushed the squad/extensibility-guide branch from f964572 to ad4b999 Compare March 16, 2026 21:21
docs: Add extensibility and building extensions guides
5ea54fd 
- Extensibility guide: decision tree for where ideas belong
  (Squad Core vs Extension vs Team Config)
- Building extensions guide: 5-step practical tutorial
- Updated test assertions for both new guide pages

Closes bradygaster#328

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry diberry force-pushed the squad/extensibility-guide branch from ad4b999 to 5ea54fd Compare March 16, 2026 21:27
Merge remote-tracking branch 'upstream/dev' into squad/extensibility-…
bb49c7c 
…guide

# Conflicts:
#	docs/src/content/docs/guide/building-extensions.md
#	docs/src/content/docs/guide/extensibility.md
#	test/docs-build.test.ts
@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 16, 2026

@bradygaster This PR is ready for your review. Clean diff — 3 files: extensibility guide (decision tree), building extensions guide (5-step tutorial), and test update. Merge conflict resolved, all tests passing.

This was referenced Mar 16, 2026
Closed
Closed
@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 17, 2026

@bradygaster This PR is ready for your review.

@bradygaster bradygaster merged commit 38be241 into bradygaster:dev Mar 18, 2026
2 checks passed
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