Skip to content

RFC: Formalize a Squad specification — on-disk artifact contracts, starting with charter.md (credits #1522) #2069

New issue
New issue
Closed
Closed
RFC: Formalize a Squad specification — on-disk artifact contracts, starting with charter.md (credits #1522)#2069
Labels
squadSquad triage inbox — Lead will assign to a membersquad:architectAssigned to architect (Lead Architect)status:needs-decisionBlocked on a product or architecture decisiontriagedIssue has been triagedtype:epicParent issue that decomposes into sub-issuestype:rfcRFC

Description

@bradygaster
bradygaster
opened on Sep 23, 2026

Summary

Two independent inputs today converge on the same underlying gap: Squad has no formal specification for what a "Squad" actually is, in terms of the on-disk artifacts (.squad/, charter.md, team.md, routing.md, skills, decisions, casting registry, etc.) that constitute one.

  1. @dfberry (Dina Berry) — Charter parsing relies on an implicit exact-Markdown schema that is not formally declared or validated #1522 — "Charter parsing relies on an implicit exact-Markdown schema that is not formally declared or validated". Dina's issue is the seed of this effort and should be credited as the origin: charter.md is authoritative, behavior-affecting input (model preference, fallback, reasoning effort, context tier), but its structure is defined only by parser implementation details in packages/squad-sdk/src/agents/charter-compiler.ts, not by any declared contract. She proposed either (a) formalizing the current Markdown structure as a documented, validated schema, or (b) introducing structured metadata with legacy fallback.
  2. A broader argument raised separately today — that Squad needs a canonical reference site (proposed name: squad-spec.io) that clearly and durably articulates "what a Squad is" purely in terms of on-disk artifacts, independent of any single runtime/parser implementation — analogous to how other ecosystems (e.g. editorconfig.org, spdx.org, OpenAPI) publish a spec independent of any one tool.

Why now

Charter drift is already an admitted, lived problem — see comments on #1522 where the repo owner notes charters have "evolved" while working on shrinking/"single-fying" squad.agent.md, and a related open gap on differentiating standard charter.md from the "roles" alternative. This is not hypothetical: it is actively making behavior harder to reason about today.

Proposed scope (starting point, not final)

  1. Inventory the artifact surface — enumerate every on-disk artifact Squad's runtime currently treats as structured/behaviorally significant (charter.md sections/labels, team.md, routing.md, casting registry.json, skills SKILL.md frontmatter, decisions/history markdown, squad.config.ts, etc.) and where each is parsed today.
  2. Formalize the charter contract first (directly resolves Charter parsing relies on an implicit exact-Markdown schema that is not formally declared or validated #1522) — declare required sections/fields, valid values, and legacy-compatibility rules; add validation with user-facing errors for malformed charters.
  3. Draft a versioned specification document (e.g. SPEC.md or a docs section) describing the artifact contracts independent of implementation, suitable for eventual publication as a standalone reference (the squad-spec.io idea) once mature enough to stand alone.
  4. Backfill validators against the declared spec so drift is caught mechanically instead of discovered by users.

Non-goals (for this tracking issue)

Acceptance Criteria

Credits

Routing per .squad/routing.md: this is cross-package architecture and unmatched-work territory — assigning to architect (Lead Architect) for ownership and design-direction.

Activity

  1. bradygaster
    added
    squadSquad triage inbox — Lead will assign to a member
    type:epicParent issue that decomposes into sub-issues
    type:rfcRFC
    triagedIssue has been triaged
    squad:architectAssigned to architect (Lead Architect)
    on Sep 23, 2026

  2. github-actions commented on Sep 23, 2026

    @github-actions
    github-actionsBot
    on Sep 23, 2026 – with GitHub Actions
    Contributor

    📋 Assigned to architect (Lead Architect)

    Issue: #2069 — RFC: Formalize a Squad specification — on-disk artifact contracts, starting with charter.md (credits #1522)

    architect 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:
    architect, work on issue #2069

  3. bradygaster commented on Sep 24, 2026

    @bradygaster
    bradygaster
    on Sep 24, 2026
    CollaboratorAuthor

    Team review: proposed structure and depth for the Squad specification

    The Architect, Docs & DevRel, and Fact Checker independently converged on the same recommendation:

    Do not create one monolithic specification for every .squad/ artifact. Define a small core conformance model, then publish separately versioned artifact profiles, starting with charter.md.

    This follows the strongest patterns from EditorConfig, OCI, SPDX 3.0, OpenTelemetry, JSON Schema vocabularies, and Keep a Changelog. It avoids the failure modes seen in WS-* sprawl, WADL/RAML governance and tooling gaps, and ActivityPub-style under-specified extension points.

    What the specification must promise

    A conforming producer should be able to create an artifact that any conforming consumer can interpret consistently. Validators should return deterministic diagnostics. Editors must preserve unknown namespaced extensions during round trips. Conformance must be capability-specific; v0.1 should not claim that an entire Squad is conformant when only charters are specified.

    Primary audiences:

    1. Humans authoring and reviewing Squad artifacts
    2. Third-party runtimes and consumers
    3. Editors, generators, and migration tools
    4. Validator and conformance-suite implementers
    5. Maintainers evolving the specification

    Recommended specification architecture

    1. Small normative core

    Keep this short and stable. It should define:

    • terminology and RFC 2119/8174 keyword use;
    • Squad-root discovery and path-containment rules;
    • artifact classes: required, optional, generated, runtime state, and implementation-private;
    • producer, consumer, validator, editor, and runtime conformance classes;
    • independent version concepts: specification version, artifact schema/profile version, implementation version, and mutable state revision;
    • identifiers, references, encoding, timestamps, unknown-extension preservation, and common security/trust requirements;
    • compatibility, capability declaration, and namespaced extension rules.

    2. Separately versioned artifact profiles

    Each profile should define its own schema, lifecycle, authority, diagnostics, fixtures, and compatibility rules. Proposed order:

    1. Charter profile v0.1 — behaviorally significant fields and round-trip guarantees
    2. Roster and routing profile — team.md, routing.md, identity joins, ownership, and precedence
    3. Configuration and casting profile — structured configuration, registries, provenance, revisions
    4. Skills profile — discovery, metadata, trust, and compatibility
    5. Decisions/memory/state profiles — only after their authority and backend semantics stabilize

    Other runtime protocols, prompts, CLI commands, storage algorithms, telemetry, GitHub workflows, and website publication should remain implementation profiles or informative guidance—not core conformance requirements.

    Recommended Charter Profile v0.1 outline

    1. Status, scope, audience, and terminology
    2. Charter conformance classes and capability declarations
    3. Machine-readable fields versus unrestricted prose
    4. Required identity and responsibility semantics
    5. Behavioral fields: model preference/fallback, reasoning effort, context tier, and defaults
    6. Canonical headings or structured metadata, including legacy aliases
    7. Precedence and cross-artifact reference rules
    8. Validation rules and stable diagnostic shape
    9. Versioning, compatibility, and migration
    10. Namespaced extensions and round-trip preservation
    11. Security and trust constraints
    12. Positive, negative, legacy, and round-trip fixtures
    13. Informative examples and authoring guidance

    How deep should the guidance go?

    Use MUST only where divergence breaks portability, safety, reference integrity, deterministic interpretation, or round-trip fidelity. Use SHOULD for ecosystem consistency where a documented exception can exist. Use MAY for optional capabilities and extensions.

    Normative:

    • required fields and semantics;
    • valid values and defaults;
    • precedence and identity/reference invariants;
    • version negotiation and compatibility;
    • extension preservation;
    • security boundaries;
    • validator behavior and diagnostic minimums;
    • conformance fixtures.

    Informative:

    • prose style and recommended headings;
    • sample charters and directory diagrams;
    • rationale and migration recipes;
    • CLI UX and suggested error wording;
    • the current TypeScript implementation profile.

    The normative overview should be brief enough to understand quickly, but the profile must be precise enough to implement without reading Squad's source. “One page” is a design constraint for the conceptual core, not a reason to omit validation rules or fixtures.

    Verified starting problem

    The current repository already contains incompatible charter shapes:

    • the parser recognizes headings such as What I Own, Boundaries, and Collaboration;
    • active specialist charters use Accountable Responsibilities, Non-Responsibilities, and Collaboration and Review Authority;
    • the template uses another combination;
    • support-role charters omit the Model section;
    • current canonical serialization does not preserve every behaviorally significant field parsed by the runtime.

    This confirms the issue's premise, but it also means the spec must not simply freeze today's parser behavior. We need an explicit semantic decision about canonical fields, presentation headings/aliases, support-role profiles, and legacy compatibility.

    Evidence from other specifications

    Strong structural models:

    • EditorConfig — minimal authoring surface, independent cores/plugins, conformance tests
    • OCI Image and Distribution specs — narrow specs plus official conformance testing
    • SPDX — stable core with profiles and curated reference artifacts
    • OpenTelemetry specifications — separately versioned core and semantic conventions
    • JSON Schema — vocabularies and machine-checkable meta-schemas, with a warning about confusing draft versioning
    • Keep a Changelog — human-first Markdown convention that spreads through copy-and-adapt examples
    • OpenAPI — neutral governance, schemas, and a broad independent tooling ecosystem

    Cautionary patterns:

    • WADL and RAML: technically credible formats weakened by limited governance commitment or vendor-centered ecosystems
    • WS-*: extension proliferation required a “profile of profiles” to recover interoperability
    • ActivityPub: formal standardization did not prevent incompatible dialects where optional and extension semantics were under-specified
    • OpenSocial: a written standard could not overcome partial implementations, ecosystem incentives, and slow governance

    Success should not be measured by fame or GitHub stars. Require evidence from at least three of these signals: independent implementations, validation tooling, durable governance, third-party compatibility layers, and real authored-to adoption.

    Principal risks

    1. Freezing parser accidents instead of specifying intended semantics
    2. Claiming whole-Squad conformance too early
    3. Producing documentation without enforcement
    4. Combining artifacts with different audiences and change velocities under one version
    5. Silent data loss during parse/serialize round trips
    6. Conflicting sources of authority across files
    7. Extension fragmentation and incompatible dialects
    8. Unsafe treatment of paths, commands, links, imports, and secrets
    9. Measuring only adoption of the reference CLI rather than independent implementation
    10. Over-scoping v0.1 until the specification becomes ceremonial

    Proposed next action and dates

    Accountable owner: architect.

    • By 2026-10-02: publish a charter-conformance audit covering every existing charter, current parser expectations, template differences, round-trip gaps, and the decision points for canonical versus legacy shapes.
    • By 2026-10-08: open a draft RFC PR containing the small normative core, Charter Profile v0.1, artifact inventory/maturity table, initial language-neutral positive/negative/legacy/round-trip fixtures, and a minimal validator or lint path.

    The validator and fixtures should ship with the first normative profile. A spec document alone will not prevent the drift this issue is intended to solve.

  4. bradygaster
    added 7 commits that reference this issue on Sep 24, 2026

    feat: formalize Squad charter profile

    e8b4d02

    feat: formalize Squad charter profile

    d21ab99

    fix: enforce portable charter conformance

    ab80da1

    fix: complete charter conformance gate

    f7d430a

    fix: enforce charter manifest schema

    71634fd

    fix: revise specification suite publication claims

    f5ced9d

    fix: close specification suite contracts

    3a7fb53
  5. bradygaster
    added
    status:needs-decisionBlocked on a product or architecture decision
    on Sep 25, 2026

  6. 2 remaining items

  7. bradygaster
    added 14 commits that reference this issue on Sep 28, 2026

    fix: enforce portable charter conformance

    91be6a2

    fix: complete charter conformance gate

    f7d81a4

    fix: enforce charter manifest schema

    71bd0b3

    docs: draft Squad specification suite

    f081150

    fix: revise specification suite publication claims

    b1c07f6

    fix: close specification suite contracts

    453a294

    docs: align specification claim boundaries

    37bdf7a

    fix: bind Charter claims to immutable revisions

    dd4565a

    docs: clarify specification scope and execution boundaries

    24ebb90

    Merge latest dev for specification validation

    171a102

    Merge latest dev before Charter digest repair

    8c28a2b

    fix: bind Charter digest to portable checkout bytes

    ccc5143

    Merge canonical Vitest and public registry integration from dev

    be95930

    feat: establish Squad Core, Charter, and draft specification suite (#…

    ccb5442
  8. bradygaster
    closed this as completedon Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    squadSquad triage inbox — Lead will assign to a membersquad:architectAssigned to architect (Lead Architect)status:needs-decisionBlocked on a product or architecture decisiontriagedIssue has been triagedtype:epicParent issue that decomposes into sub-issuestype:rfcRFC

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions