Context
Follow-up to #700 action item 4: "Consider versioning agent identities/charters as first-class artifacts".
The original issue phrased this as "consider", so it was scoped out of the v0.7.0 engine foundations PR (#1072) to keep that PR focused on no-self-review enforcement + the decisions drop-box. This issue tracks the design discussion and implementation separately.
Motivation
GitHub Squad's agent orchestration model persists agent charters (system prompt, allowed tools, role, etc.) as versioned plain-text artifacts alongside the code they operate on. Benefits:
- Audit trail: reviewers can see exactly which agent charter produced a given decision record or code change.
- Reproducibility: re-running an old execution requires the exact charter version, not whatever the registry currently holds.
- Rollback: a buggy charter edit can be reverted the same way a buggy code commit is.
Open Questions
- Where should charter versions live? Git repo?
agents/ directory mirroring skills/? A dedicated charters/ directory?
- Are charters separate from
AgentIdentity (frozen Pydantic model) or do we version the identity model itself with content hashes?
- Is there a compatibility requirement for cross-version execution (e.g. replay a v1.0 execution against a v1.2 charter)?
- How do we integrate with the decisions drop-box? Add a
charter_version field to DecisionRecord?
References
Acceptance Criteria (draft)
Context
Follow-up to #700 action item 4: "Consider versioning agent identities/charters as first-class artifacts".
The original issue phrased this as "consider", so it was scoped out of the v0.7.0 engine foundations PR (#1072) to keep that PR focused on no-self-review enforcement + the decisions drop-box. This issue tracks the design discussion and implementation separately.
Motivation
GitHub Squad's agent orchestration model persists agent charters (system prompt, allowed tools, role, etc.) as versioned plain-text artifacts alongside the code they operate on. Benefits:
Open Questions
agents/directory mirroringskills/? A dedicatedcharters/directory?AgentIdentity(frozen Pydantic model) or do we version the identity model itself with content hashes?charter_versionfield toDecisionRecord?References
docs/design/agents.md§3.1 AgentIdentity (current runtime model)docs/design/operations.mdReview Gate Invariants (where charter_version would plug into the audit trail)Acceptance Criteria (draft)
docs/design/agents.mdcovering storage location, diff/merge semantics, and interop withDecisionRecordCharterVersionmodel (if separate fromAgentIdentity)