PRD: SDK-First Feature Parity — Full Test Results (32/50 verified, 6 gaps, 12 need setup)

SDK-First Squad Feature Parity — Full Test Results

Goal: Ensure squad init --sdk produces squads that work identically to regular markdown squads for all MVP use cases.

Test bed: SdkSquad — Snake game repo initialized with squad init --sdk (Matrix universe)
Tested: 2026-03-10
Method: Systematic filesystem verification + active feature exercise across 2 sessions

Results Summary

Status	Count	%
✅ Verified	32	64%
❌ Known Gap	6	12%
⚠️ Needs Setup	12	24%
Total	50	100%

Feature Matrix

#	Feature	Category	MD Squad	SDK Squad	Notes
1	`squad init` — creates `.squad/` structure	Init & Setup	✅	✅ Verified	Directory structure identical
2	`squad init --sdk` — creates `squad.config.ts`	Init & Setup	N/A	✅ Verified	defineSquad/defineAgent working
3	Team casting — universe selection	Init & Setup	✅	✅ Verified	Matrix universe cast correctly
4	Casting state files	Init & Setup	✅	✅ Verified	policy.json, registry.json, history.json present
5	`.gitattributes` merge drivers	Init & Setup	✅	✅ Verified	merge=union rules for decisions, history, logs
6	Config stays in sync with team.md	Init & Setup	N/A	❌ Gap	#337 — config not updated on team changes
7	Adding team members (markdown)	Team Mgmt	✅	✅ Verified	charter, history, routing, team.md all updated
8	Adding members updates config	Team Mgmt	N/A	❌ Gap	#337 — new agent not added to config
9	Removing team members	Team Mgmt	✅	✅ Verified	Alumni folder, registry retired, roster cleaned
10	Removing members updates config	Team Mgmt	N/A	❌ Gap	#337 — removed agent not cleaned from config
11	Plugin marketplace check	Team Mgmt	✅	✅ Verified	No marketplaces → silently skipped (correct)
12	Agent spawn with charter inline	Spawning	✅	✅ Verified	6 agents spawned successfully
13	Model selection (4-layer)	Spawning	✅	✅ Verified	haiku for non-code, sonnet for code, task-aware working
14	Response mode selection	Spawning	✅	✅ Verified	Direct, Lightweight, Standard, Full all exercised
15	Parallel fan-out	Spawning	✅	✅ Verified	5 agents in parallel, all returned
16	Drop-box pattern	Spawning	✅	✅ Verified	Inbox→merge→clear cycle working
17	Skill-aware routing	Spawning	✅	✅ Verified	Skills dir, SKILL.md format, injection mechanism
18	Routing table	Routing	✅	✅ Verified	Matches roster, confirmed during add/remove
19	Directive capture	Routing	✅	✅ Verified	Preference captured to decisions/inbox/
20	Eager execution	Routing	✅	✅ Verified	3-agent parallel with anticipatory Scribe
21	Orchestration logging	Routing	✅	✅ Verified	Per-agent log entries with correct format
22	GitHub repo connection	Issues	✅	✅ Verified	Connected to bradygaster/squad, filed issues
23	Issue triage	Issues	✅	✅ Verified	Triaged #338-340, assigned squad:{member} labels
24	Issue→PR lifecycle	Issues	✅	⚠️ Setup	Needs real issue→branch→PR→merge cycle
25	Label routing	Issues	✅	✅ Verified	squad labels applied via gh CLI
26	Auto-triggered ceremonies	Ceremonies	✅	✅ Verified	Config valid; condition matching correct
27	Manual ceremonies	Ceremonies	✅	⚠️ Setup	Needs user-requested ceremony trigger
28	Ceremony cooldown	Ceremonies	✅	⚠️ Setup	Needs sequential ceremony trigger
29	Ralph activation	Ralph	✅	✅ Verified	Work-check scan executed on bradygaster/squad
30	Work-check cycle	Ralph	✅	✅ Verified	Scan→categorize→report working
31	Idle-watch mode	Ralph	✅	⚠️ Setup	Needs long-running session with periodic poll
32	Watch mode	Ralph	✅	⚠️ Setup	Needs `npx squad watch` exercise
33	PRD intake	PRD Mode	✅	✅ Verified	PRD.md created, referenced in decisions
34	Lead decomposition	PRD Mode	✅	✅ Verified	50 features into P0-P3 tiers
35	Work item routing	PRD Mode	✅	✅ Verified	Priority-respecting parallel dispatch
36	Human team members	Human & Copilot	✅	⚠️ Setup	Needs human member add + pause test
37	@copilot member	Human & Copilot	✅	❌ Gap	#339 — routing without roster entry
38	@copilot auto-assign	Human & Copilot	✅	❌ Gap	#339 — not wired
39	Skill extraction	Skills	✅	✅ Verified	sdk-parity-testing skill extracted
40	Skill confidence lifecycle	Skills	✅	⚠️ Setup	Needs independent validation for bump
41	Skills directory structure	Skills	✅	✅ Verified	Correct format with YAML frontmatter
42	Worktree awareness	Worktree & Git	✅	⚠️ Setup	Needs multi-worktree environment
43	Scribe git commits	Worktree & Git	✅	✅ Verified	Multiple commits observed
44	Merge drivers	Worktree & Git	✅	✅ Verified	All 4 merge=union rules present
45	Reviewer lockout	Reviewer	✅	⚠️ Setup	Needs rejection scenario
46	Deadlock handling	Reviewer	✅	⚠️ Setup	Needs all-agents-locked scenario
47	Client compatibility	Platform	✅	⚠️ Setup	CLI confirmed; needs VS Code test
48	MCP integration	Platform	✅	✅ Verified	GitHub + Azure MCP detected
49	Constraint budget	Platform	✅	⚠️ Setup	Needs active constraint
50	Multi-agent artifact	Platform	✅	⚠️ Setup	Needs multi-agent deliverable

Known Gaps (Blocking Issues)

Issue	Description	Features Blocked
#337	`squad.config.ts` ↔ `team.md` sync broken	#6, #8, #10
#338	Ralph missing from generated config	#29–#32 (at SDK level)
#339	@copilot routing without roster entry	#37–#38

Key Findings

What works well (SDK = markdown parity confirmed)

Init & casting — identical directory structure, correct universe selection, casting state files
Agent spawning — charter inline, model selection, parallel fan-out, drop-box pattern all working
Routing — routing table, directive capture, eager execution, orchestration logging
Issues Mode — repo connection, triage, label routing all working
Ralph — activation and work-check cycle functional (coordinator-level, not config-dependent)
PRD Mode — intake, decomposition, priority-aware routing
Skills — extraction, directory structure, SKILL.md format

What's broken (SDK-specific gaps)

Config sync (SDK init: Adding team members doesn't update squad.config.ts #337) — the root cause. squad.config.ts is generated once at init and never updated. Add/remove member, Ralph, @copilot — all fail to update config.
Ralph in config (SDK init: Ralph (Work Monitor) missing from generated squad.config.ts #338) — Ralph is a built-in member but not included in generated config. Works at coordinator level but SDK consumers can't reference it.
@copilot wiring (SDK init: @copilot routing configured without team.md roster entry #339) — routing.md has @copilot rules pre-configured, but team.md roster and config are missing the entry. Routing references a non-existent member.

What needs specific test environments

Issue→PR lifecycle (Research: Should Squad use /fleet instead of task/delegate for agent spawning? #24) — needs a real issue pickup with branch/PR/merge
Ceremonies (Squad Pings You — notification via Teams/MCP #27-28) — needs multi-agent design task to trigger
Human members (JetBrains + GitHub.com surface research (deferred to v0.5.0) #36) — needs human added to test coordinator pause
Worktree (chore: remove internal team-docs from main #42) — needs git worktree add for multi-worktree
Reviewer protocol (v0.4.0 preview release #45-46) — needs review/rejection scenario
VS Code (release: v0.4.0 — CI/CD pipeline + workflow tests #47) — needs Copilot Chat testing
Constraints/artifacts (chore: move blogs from team-docs/blog to docs/blog, enforce naming convention #49-50) — need active constraint session

Bonus: EMU Auth Gotcha

Enterprise Managed User (bradyg_microsoft) token interfered with GraphQL writes even when personal account (bradygaster) was active. gh issue create worked (REST?) but gh issue edit failed (GraphQL). Fix: gh auth logout --user {emu_account}. Possible gh CLI bug worth reporting.

Skill Extracted

Created .squad/skills/sdk-parity-testing/SKILL.md with 6 reusable patterns:

Filesystem-first verification before active exercise
Config-roster divergence detection
Tiered test priority (P0→P3)
Drop-box verification
Issue-as-test-output pattern
EMU auth gotcha

MVP Exit Criteria

✅ All P0 features verified (Init, Team Mgmt, Spawning) — except config sync (SDK init: Adding team members doesn't update squad.config.ts #337)
✅ All P1 features verified (Routing, Issues, Ralph) — except full PR lifecycle (Research: Should Squad use /fleet instead of task/delegate for agent spawning? #24)
⚠️ Known gaps SDK init: Adding team members doesn't update squad.config.ts #337, SDK init: Ralph (Work Monitor) missing from generated squad.config.ts #338, SDK init: @copilot routing configured without team.md roster entry #339 need fixes or PRs
⚠️ 12 P2/P3 features need specific test setups (documented above)
✅ PRD updated with final status for every row

feat: breathtaking first-run wow moment (github#362)

📋 Assigned to EECOM (Core Dev)

Issue: #341 — PRD: SDK-First Feature Parity — Full Test Results (32/50 verified, 6 gaps, 12 need setup)

EECOM will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
EECOM, work on issue #341

📋 Assigned to FIDO (Quality Owner)

Issue: #341 — PRD: SDK-First Feature Parity — Full Test Results (32/50 verified, 6 gaps, 12 need setup)

FIDO will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
FIDO, work on issue #341

test: add SDK feature parity batch 2 tests (github#347/github#341)

Impact on This Matrix — ⚠️ Needs Setup Features

This matrix tracks 50 features with 12 marked ⚠️ Needs Setup. Three PRs now provide automated tests for 11 of those 12:

⚠️ Feature	Batch	PR	Status
#40 Skill Confidence	1	#422 (merged)	✅ Tested
#42 Worktree	1	#422 (merged)	✅ Tested
#45 Reviewer Lockout	1+3	#422, #428	✅ Tested (deepened)
#46 Deadlock Handling	1+3	#422, #428	✅ Tested (deepened)
#27 Manual Ceremonies	2	#425	✅ Tested
#28 Ceremony Cooldown	2	#425	✅ Tested
#36 Human Team Members	2	#425	✅ Tested
#49 Constraint Budget	2	#425	✅ Tested
#50 Multi-Agent Artifact	2	#425	✅ Tested
#31 Ralph Idle-Watch	3	#428	✅ Tested
#47 Platform Detection	3	#428	✅ Tested
#24 Issue→PR Lifecycle	—	—	⚠️ Still needs setup
#32 Watch Mode	—	—	⚠️ Still needs setup

132 tests total across 3 batches (22 + 64 + 46). All use real SDK implementations.

Remaining gap: #24 and #32 require gh CLI mocking infrastructure to test. Once PRs #425 and #428 merge, 11 of 12 ⚠️ features can be re-evaluated as ✅ in this matrix.

docs: add 50-feature SDK test matrix audit (github#347/github#341)

chore: remove SDK-FEATURE-TEST-MATRIX.md

test: add SDK feature parity batch 3 tests (github#347/github#341)

Real-World SDK-First Impact Analysis — tamresearch1 (Production Squad)

We tested the SDK-First migration path against our production squad setup (tamresearch1 — 47KB ralph-watch, 14 skills, 8 agents, 3 ceremonies, cross-machine coordination). Here's what we found:

⚠️ Critical Findings

1. Schema Incompatibility
Our SquadConfig has properties with no SDK-First equivalents:

models.nuclearFallback — fallback chain for model unavailability
routing.governance — reviewer lockout enforcement
platforms — multi-platform detection (CLI vs VS Code)
casting — persistent naming system (universe allocation, registry)

These would be silently lost during migration.

2. Governance File Overwrite Risk
Running squad build in SDK-First mode regenerates charters, team.md, and routing.md. Our 20+ custom agent charters (with accumulated history, learned patterns, and skill references) would be overwritten.

3. Feature Parity Gaps
Based on your test results (32/50 verified), the gaps that affect us:

Ceremonies — we depend on auto-triggered before/after ceremonies
Decision inbox — drop-box pattern for parallel agent writes
Skill loading — agents read skills at spawn time from .squad/skills/
Cross-machine coordination — .squad/cross-machine/ task queue

4. Import Path Migration
Would require changing from @bradygaster/squad to @bradygaster/squad-sdk across our scripts and configurations.

📊 Our Assessment

Dimension	Score	Notes
Feature parity	~64%	6 verified gaps affect our workflow
Migration safety	🔴	File overwrite risk is a blocker
Schema compat	🔴	Custom config properties would be lost
Rollback safety	🟡	Git revert possible but messy

✅ Recommendation

Keep SDK-First opt-in for new projects. Don't make it the default until:

Feature parity reaches 100% (all 50 tests passing)
File protection mechanism exists (preserve existing charters/history)
Schema supports extension properties (or migration tooling validates no data loss)
Issues SDK init: Adding team members doesn't update squad.config.ts #337, SDK init: Ralph (Work Monitor) missing from generated squad.config.ts #338, SDK init: @copilot routing configured without team.md roster entry #339 are resolved

Happy to help test specific gaps — our squad is a good stress test since we use nearly every feature. Let us know which gaps to validate first.