Repository navigation
feat: establish Squad Core, Charter, and draft specification suite (#2069) - #2074
Conversation
🟠 Impact Analysis — PR #2074Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (16 files)
root (15 files)
squad-sdk (8 files)
tests (4 files)
|
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 15 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 2 active Copilot thread(s) resolved (2 outdated skipped) |
| ✅ | CI passing | All checks passing |
Files Changed (43 files, +8306 −176)
| File | +/− |
|---|---|
.changeset/formalize-charter-profile.md |
+5 −0 |
.gitattributes |
+4 −1 |
docs/specification/README.md |
+169 −0 |
docs/specification/artifact-inventory.md |
+144 −0 |
docs/specification/automation-v0.1.md |
+88 −0 |
docs/specification/ceremony-v0.1.md |
+159 −0 |
docs/specification/charter-v0.1.md |
+404 −0 |
docs/specification/configuration-casting-v0.1.md |
+124 −0 |
docs/specification/coordination-handoff-v0.1.md |
+87 −0 |
docs/specification/core-v0.1.md |
+219 −0 |
docs/specification/execution-preferences-v0.1.md |
+102 −0 |
docs/specification/github-work-lifecycle-binding-v0.1.md |
+194 −0 |
docs/specification/governance-review-v0.1.md |
+162 −0 |
docs/specification/interoperability-conventions-v0.1.md |
+196 −0 |
docs/specification/planning-activation-v0.1.md |
+109 −0 |
docs/specification/state-memory-requirements-v0.1.md |
+99 −0 |
docs/specification/team-routing-v0.1.md |
+117 −0 |
docs/specification/work-lifecycle-v0.1.md |
+125 −0 |
package-lock.json |
+41 −44 |
package.json |
+2 −1 |
packages/squad-sdk/CHANGELOG.md |
+14 −0 |
packages/squad-sdk/src/agents/charter-compiler.ts |
+290 −93 |
packages/squad-sdk/src/agents/charter-markdown.ts |
+234 −0 |
packages/squad-sdk/src/agents/charter-validator.ts |
+579 −0 |
packages/squad-sdk/src/agents/index.ts |
+33 −0 |
packages/squad-sdk/src/parsers.ts |
+31 −0 |
packages/squad-sdk/src/state/io/charter-io.ts |
+92 −21 |
packages/squad-sdk/src/types.ts |
+10 −0 |
test-fixtures/spec/charter-v0.1/legacy/template-style.md |
+21 −0 |
test-fixtures/spec/charter-v0.1/manifest.json |
+1292 −0 |
test-fixtures/spec/charter-v0.1/manifest.schema.json |
+610 −0 |
test-fixtures/spec/charter-v0.1/negative/invalid-behavior.md |
+19 −0 |
test-fixtures/spec/charter-v0.1/positive/canonical.md |
+19 −0 |
test-fixtures/spec/charter-v0.1/round-trip/extensions.edited.md |
+54 −0 |
test-fixtures/spec/charter-v0.1/round-trip/extensions.md |
+50 −0 |
test-fixtures/spec/suite-v0.1/evidence.schema.json |
+468 −0 |
test-fixtures/spec/suite-v0.1/governance-rejection.example.json |
+66 −0 |
test-fixtures/spec/suite-v0.1/index.json |
+320 −0 |
test-fixtures/spec/suite-v0.1/index.schema.json |
+272 −0 |
test/charter-compiler.test.ts |
+16 −4 |
test/charter-spec.test.ts |
+614 −0 |
test/config-integration.test.ts |
+5 −12 |
test/specification-suite.test.ts |
+647 −0 |
Total: +8306 −176
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
bradygaster
added
type:feature
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved moderate issues affect extension isolation, validation coverage, and canonical/extension-preserving serialization.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 4
Open (4)
What changed in this PR
Formalizes the Squad core and squad-charter/v0.1 profile with SDK validation, parsing, serialization, fixtures, and documentation.
Changes:
- Adds core/profile specifications and artifact roadmap.
- Adds validator diagnostics, canonical/legacy parsing, and preference serialization.
- Adds conformance fixtures, tests, public exports, and an SDK changeset.
| File | Reviewed change |
|---|---|
test/charter-spec.test.ts |
Charter conformance and round-trip tests |
test-fixtures/spec/charter-v0.1/round-trip/extensions.md |
Extension round-trip fixture |
test-fixtures/spec/charter-v0.1/positive/canonical.md |
Canonical positive fixture |
test-fixtures/spec/charter-v0.1/negative/invalid-behavior.md |
Invalid behavior fixture |
test-fixtures/spec/charter-v0.1/manifest.json |
Fixture manifest |
test-fixtures/spec/charter-v0.1/legacy/template-style.md |
Legacy compatibility fixture |
packages/squad-sdk/src/types.ts |
Public validator types |
packages/squad-sdk/src/state/io/charter-io.ts |
Charter serialization; canonical headings and unknown extensions require preservation fixes |
packages/squad-sdk/src/parsers.ts |
Parser API exports |
packages/squad-sdk/src/agents/index.ts |
Agent API exports |
packages/squad-sdk/src/agents/charter-validator.ts |
Charter validation; fenced headings, duplicate fields, and path identity checks require fixes |
packages/squad-sdk/src/agents/charter-compiler.ts |
Charter parsing; fenced heading isolation requires a fix |
docs/specification/README.md |
Specification index |
docs/specification/core-v0.1.md |
Core specification |
docs/specification/charter-v0.1.md |
Charter profile specification |
docs/specification/artifact-inventory.md |
Artifact inventory and roadmap |
.changeset/formalize-charter-profile.md |
SDK minor changeset |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
e8b4d02 to
d21ab99
Compare
🏗️ Architectural Review
Automated architectural review — informational only. |
🔒 Security Review
🔒 Security review: 1 info.
Automated security review — informational only. |
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> fix: complete charter profile conformance Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> docs: remove specification trailing whitespace Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Source-Commit: d21ab99
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
71634fd to
37bdf7a
Compare
bradygaster
changed the title
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Sorry for putting all of this in one comment instead of commenting on each line. I'm sending this from my phone :)
I had some difficulty reading this file. I think part of it is the terminology and part is that I'm not sure the current inventory covers all the Squad concepts we have today.
A few thoughts/questions:
- Do we need the promotion roadmap here? I understand the idea, but I'm not sure it adds much beyond the status/maturity information in the table.
- "Repository evidence" was confusing to me as a column name. Same for "Disposition". Maybe something like "Implementation / artifacts" and "Spec status" would be easier to understand.
- Related to that, entries like "agents/{id}/charter.md, compiler, validator, fixtures" are hard to follow. I understand the path, but what exactly are compiler, validator and fixtures here? Are these specific files/components? If they are evidence, maybe we should link to the actual implementation.
- I'm also wondering if the table structure itself can be simplified. Maybe: Capability | Implementation / artifacts | Spec coverage | Status | What's missing.
- Do we cover SubSquads / workstreams anywhere? This feels like a first class Squad concept that should appear in the inventory.
- Does Spec Kit itself have a spec we can look at for comparison? I'm curious how they structure this.
- We have portable export/import, but what about creating a Squad from a preset/template? To me these are different capabilities: moving an existing Squad vs using a reusable definition to create one.
- I think we're also missing some of the multi-Squad concepts: upstreams, Squad registry and discovery, cross-Squad communication/delegation, and potentially spawning/creating another Squad.
- Related to that, should SubSquads be treated separately from cross-Squad communication? They have different semantics even though both involve more than one team/squad.
This also made me wonder about a bigger question: are we specifying a single Squad, or the model for how Squads can compose and interact? With SubSquads, upstreams, registry/discovery and cross-Squad communication, I think that distinction matters.
There was a problem hiding this comment.
Addressed the bounded inventory/scope concerns in 24ebb90 (current integrated head: 171a102).
The inventory now uses Capability, Implementation / artifacts, Spec status, Spec coverage, and What's missing; distinguishes Squad-root artifact paths from repository implementation links; and links the Charter compiler, validator, fixture manifest, ceremony builder/templates, scheduler, and relevant CLI implementations. Separate informative entries cover preset/template instantiation, SubSquads/workstreams, upstream inheritance, peer registry/discovery, cross-Squad communication/delegation, and creation/spawning. Presets are explicitly distinct from full export/import, SubSquads from independent peers, and discovery-only registration from inheritance. The README and inventory explicitly say this is a working inventory, not a complete specification of Squad composition; the new entries confer no normative claims. Autonomous creation/spawning remains a scope gap rather than an implementation claim.
The promotion roadmap remains informative, and a Spec Kit comparison is deferred rather than made a prerequisite of this draft. No multi-Squad schema or runtime behavior was added.
Validation after normally merging current dev: npm test -- test/docs-build.test.ts test/docs-links.test.ts test/charter-spec.test.ts test/charter-compiler.test.ts test/config-integration.test.ts test/specification-suite.test.ts passed all 173 tests; npm run lint:docs and npm run build with SKIP_BUILD_BUMP=1 passed. Fresh CI is starting for the updated head. Does this bounded scope clarification address the concern for merging the working draft, with the identified gaps retained as promotion work? Leaving this thread open for your disposition.
Auto-resolved by the GitHub Copilot app.
There was a problem hiding this comment.
-
should the charter have its schema/profile version inside the file? I'm thinking about what happens when we have v0.2/v1/etc., or when a charter is copied/exported and no longer has the original surrounding context. A self-describing artifact feels useful here, but maybe there is a reason we intentionally don't want that.
-
In the canonical document shape, I think we may be missing some things that exist in Squad today. Is that intentional because we're trying to keep the portable charter smaller than the full Squad charter?
-
One thing I was thinking about is execution identity. For example, should there be a way to explicitly say which managed identity/service identity this agent is intended to use after compilation? I see that authorization is intentionally outside this profile, so maybe it belongs somewhere else, but I think we should at least decide where execution identity lives.
-
Similar question about tools. Should tool/capability declarations be part of the charter, or are those intentionally runtime/configuration concerns outside the charter? Again, I think making that boundary explicit would help.
There was a problem hiding this comment.
Clarified these boundaries in informative Charter §13.1 in 24ebb90 (current integrated head: 171a102), without changing the normative document shape or runtime behavior.
§3 already explicitly selects the profile through the API or accompanying manifest, requires selection for portable conformance (SQC014 when missing), and states that v0.1 has no embedded marker. §13.1 now explains that a copied charter still needs that context and that an embedded marker is a future profile-design question. The smaller portable charter is intentional, not a complete product configuration.
Authenticated execution principals belong to trusted runtime configuration/provider bindings, separate from charter display/path identity. Tool declarations belong to runtime/config integration, with a link to the existing agent configuration; §11 independently enforces availability and authorization. The suite explicitly does not yet define a portable principal-binding or tool-declaration schema. Interop authority requirements are related design work, not implemented bindings; opaque extensions cannot establish authenticated identity or grants.
The Charter document digest was refreshed in both the conformance manifest and suite index; behavioral fixtures, evidence payload, capabilities, and maturity are unchanged. The combined docs/Charter/spec validation passed all 173 tests; build (SKIP_BUILD_BUMP=1), type-check, docs lint, and all 54 SDK subpath imports passed. Does this explicit boundary address your concerns for the v0.1 working draft, while leaving self-description and portable binding schemas for future design? Leaving this thread open for your disposition.
Auto-resolved by the GitHub Copilot app.
There was a problem hiding this comment.
I'm not sure this is enough yet to describe the ceremony capabilities we have in Squad today.
Right now it feels more like a spec for the ceremony execution lifecycle than a spec for ceremonies themselves. We have triggers, participants, cooldown, execution records, state transitions, etc., which are important, but I think we should look again at the actual ceremony capabilities we support and make sure the model represents them.
One thing in particular is scheduling. We already did work around scheduling and "schedule.json". Rather than defining scheduling again specifically for ceremonies, should ceremonies reference the common scheduling model? A ceremony could define what should happen, participants, inputs/outputs, conditions, etc., while the scheduling spec defines when/how it is triggered. That could also let us reuse the same scheduling model for things other than ceremonies.
I also didn't really understand section 5, "Candidate operations and roles":
"ceremony.consume", "ceremony.evaluate", "ceremony.facilitate", and "ceremony.record"
What does "candidate" mean here? Candidate to become part of the normative API later? And what exactly does each operation do? For example, what does "consume" consume and what does "evaluate" return? Who calls these operations? If these are intended to eventually become an interoperable ceremony API, I think we need to explain the contract around them, not only list their names.
I think it may also help to separate three concepts more clearly:
- Ceremony definition: what the ceremony is, participants/roles, agenda/process, inputs, expected outputs, conditions, etc.
- Trigger/scheduling: when it should run and what causes it to run. Ideally reusing the common scheduling model where possible.
- Ceremony execution: claim, facilitator, state transitions, cooldown, concurrency/idempotency, recording decisions/actions and completion.
The current spec seems strongest on #3. I'm not sure #1 and #2 capture everything we already have today.
I would also compare this against our current "ceremonies.md", SDK "defineCeremony()", templates/plugins, and scheduling work before we lock the v0.1 model. Ceremonies are one of the extensibility primitives in Squad, so I think it's worth making sure the spec doesn't accidentally define a smaller concept than the one the product already has.
There was a problem hiding this comment.
Addressed the draft-model clarity concerns in 24ebb90 (current integrated head: 171a102). The Ceremony document remains a non-normative, non-claimable requirements draft.
§1 now explicitly separates definition, shared trigger/scheduling, and execution, and says the draft does not completely specify today's extensibility surface. §2.1 links and compares defineCeremony(), current config, Markdown template/reference, agenda/process, and hook/enforcement metadata; it records unresolved conversion and plugin/template mapping instead of implying coverage. §2.2 references the shared Automation schedule.json model and actual scheduler/CLI, keeps cron/time/retry concerns out of the ceremony definition, and identifies the still-unproven binding from builder/Markdown timing to common scheduled tasks.
§5 now calls the four candidate names non-contract placeholders—not SDK APIs or claimable capabilities—and describes intended caller/input/result for each. Exact types, authorization, order, failures, and atomicity remain explicitly unresolved. Promotion criteria now require complete definition mappings, shared scheduling binding, and replacement/removal of placeholders with versioned operation contracts. No scheduling engine, hook execution, runtime lifecycle, or normative API was added.
After normal integration with current dev, the docs build/link, Charter/compiler/config, and specification suites passed all 173 tests; docs lint and npm run build (SKIP_BUILD_BUMP=1) also passed. Does this appropriately bound the requirements draft for merge without prematurely locking a smaller ceremony API? Leaving this thread open for your disposition.
Auto-resolved by the GitHub Copilot app.
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Part of #2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Preserve Charter AJV dependency and specification digest bindings. Part of #2069. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Part of #2069
Combined review
This is the single combined review for the Squad specification work and supersedes #2078. It preserves the executable Core + Charter foundation from #2074 and folds in #2078's broader draft specification suite with reviewable source-commit provenance.
No pull request is merged by this change. Issue #2069 remains open for the broader architectural program.
Claim boundaries
Claimable
parse,validate,edit,legacy-consume, andruntime, backed by the portable manifest, manifest schema, fixtures, reference implementation, and exact SHA-256 specification/evidence revision bindings.Non-claimable requirements drafts
Governance, Team/Routing, Coordination/Handoff, Work Lifecycle, GitHub lifecycle binding, Interoperability, Configuration/Casting, Execution Preferences, Planning/Activation, Ceremony, Automation, State/Memory, and the other future-profile material remain non-claimable.
Governance relational checks are explicitly TypeScript reference-implementation checks, not portable normative evidence. A future executable governance profile requires language-neutral relational invariants and portable cases.
Consolidation scope
This intentionally combines the two dependent PRs into one coherent review:
devThis is the user-authorized exception to the repository's normal >20-file guidance. The latest contract revision modifies nine existing specification, schema, fixture, and test files only; it adds no profile, dependency, or unrelated path.
Contract revision
Charter claims now bind two immutable, independently reproducible revisions even while suite publication metadata remains null:
sha256:bac80dbac473cac35824ffdf0d7e219a96945f7e82b00c24936e8e707bd5b9e6over the exact Charter Markdown bytessha256:1f09c1954e056ea2072e3c79e286869790ae69751cba0ca4cfd58fd2fa0a92bbover the RFC 8785 canonical manifest with only the top-levelrevisionmember omittedThe Charter manifest schema and suite index schema reject missing, mutable, malformed, or unsupported bindings. The human registry and machine index are semantically cross-checked for Charter identity, maturity, class, dependencies, capabilities, manifest/schema, and revision evidence.
Source provenance
The branch was rebuilt on current
devwhile preserving the seven logical source commits and recording their original SHAs:d21ab99fa90c9df315b2897123f74231d12c1656— Core + Charter foundationab80da18087b7d37755db2c3cc5880d194a10f52— portable Charter conformancef7d430a78e38dc00496f1799d76398df0f2a4884— Charter conformance gate71634fde5ce288868fa2ff00ddfcb8dc7c58d3ee— Charter manifest schemac03ba950fde071c8ec58a64504fdb7b5cf1206ef— draft specification suitef5ced9d051a727457df807f7ed49cb6271f9aef0— publication-claim revision3a7fb5391975486eebc91bfecb5a624f425bbc6d— suite contract revisionAll rewritten and follow-up commit references use
Part of #2069, so merging this PR will not close the epic. The review follow-ups are37bdf7a7(claim-boundary alignment) anddd4565a4(immutable revision binding).Current combined head:
dd4565a482d1d0e88d2065c325eaaa5e2810edf6Validation
Targeted
npx vitest run test/specification-suite.test.ts test/charter-spec.test.ts test/charter-compiler.test.ts— 84/84 passednpm run lint— passednpm run lint:eslint— 0 errors; repository baseline warnings onlynpm run lint:docs— markdownlint and cspell passed across 200 filesnpm run docs:build— passed; existing TypeDoc warnings onlyjq emptygit diff --check— passedFull
SKIP_BUILD_BUMP=1 npm run build— passed without version or lockfile driftdevbaseline — 9,537 passed; 9 failed; 24 skipped; 47 tododev; no consolidation-specific full-suite regression was identifiedGitHub checks
All current-head checks for
dd4565a482d1d0e88d2065c325eaaa5e2810edf6completed successfully. The replacement Squad CI run passedgh-aw strict compile,Changeset Drift,changes,Shebang EOL,docs-quality,Policy Gates,samples-build,sdk-exports-validation, andtest. Repo Health, Impact Analysis, and both readiness runs also passed; Scope Boundary was intentionally skipped by its path filter. Earlier cancelled jobs were superseded by these successful replacements for the same head.Review notes
devbase are preserved.