Plan: Release Strategy — Multi-Repo Coordinated Releases#
Summary#
Design and document a release strategy feature that extends agent-core from single-issue/single-repo orchestration to coordinated multi-repo, multi-sprint releases with staged E2E validation gates. The deliverable is a structured design document (not code) stored in artefacts, covering lifecycle model, data models, pipeline changes, and an actionable execution plan.
Files#
| File | Action | Description |
|---|---|---|
plan/release-strategy.md | create | Main design document: vision, lifecycle, coordination model, data models, pipeline changes, validation, API changes, execution plan |
plan/release-manifest-schema.json | create | JSON schema for the release manifest data model |
plan/execution-plan.md | create | Ordered implementation tasks with dependencies, complexity, parallelisation, milestones |
Steps#
- Define release lifecycle model — document phases (planning → development → staging → validation → ship), actors (agent, human, CI), gates per phase, and how existing directives (careful/auto/quick) map to release-level gates.
- Design multi-repo coordination model — document RC branch strategy per repo, cross-repo dependency graph, coordinated merge flow (
feature → RC → staging → master), and howWorktreeService.getOrCreateWorktree()extends to manage RC branches across repos. - Design data models — define ReleaseManifest (release ID, repos, branches, issues, lifecycle state), ReleaseTask (links TaskEntity to a release), and CrossRepoDependency (repo A change requires repo B change). Document as JSON schemas with field references.
- Design pipeline/phase extensions — document new phases (
validate,promote) or hooks that integrate intoPHASE_ORDERandPhaseRouterService, howInternalAdapterService.handleSignal()handles release-scoped signals, and howClaudeInvocationServicepasses release context to skills. - Design validation/gating model — document how E2E tier results (tier1→tier2a→…→tier2d) feed into release gates, how
PhaseHooksServicetriggers E2E runs on RC branches, failure handling (auto-fix + retry vs. human escalation), and partial validation rollback. - Design API/webhook changes — document new REST endpoints for release CRUD, release status queries, and promotion triggers; webhook event handling for cross-repo PR merges and CI results; extension to
ControlApiModulecontrollers. - Write execution plan — produce ordered implementation task list with S/M/L complexity, dependency graph, parallelisation opportunities, and milestone structure (M1: data model, M2: single-repo RC flow, M3: multi-repo coordination, M4: E2E validation gates).
Verification#
- Design document covers all three levels (vision, low-level design, execution plan) per acceptance criteria
- Every execution task is specific enough to become a standalone GitHub issue with clear scope
- Document references actual codebase constructs (entities, services, methods) rather than abstract concepts
Risks#
- Scope creep in design: Release strategy touches nearly every module — risk of over-designing. Mitigation: constrain design to minimum viable release flow first (single-repo RC → validate → promote), then layer multi-repo.
- Sprint-aware planning complexity: Tracking sprint scope, deferrals, and manifest updates adds significant state management. Mitigation: defer sprint tracking to a follow-on design; focus on release lifecycle and validation gates first.
Open Questions#
- Should releases be tracked as a new DB entity (ReleaseEntity) or as metadata on existing TaskEntity groupings?
- What is the minimum set of E2E tiers required as a release gate vs. optional quality signals?