Agentic development workflows — enhancement plan

Status: Proposed (2026-07-19), pending ADR 030 acceptance. Governing ADR: ADR 030 — Agentic development workflows program Branch series: claude/agentic-workflows-enhancement-* (in flight across repos)

What this plan is

The Architecture Enhancement Guide (2026-06) covers the platform — what AlphaSwarm ships. This plan covers the process — how AlphaSwarm is built when the builders are increasingly coding agents (Cursor, Claude Code, Codex; claude/* branches and Codex automerges are already routine across the estate). It answers: what must change so that an agent session in any of the 42 repos can bootstrap, verify, and land trustworthy changes with minimal human babysitting — and so that we can measure whether that is getting better.

Document set

Document	Contents
gaps.md	Current-state assessment: strengths to build on, the ten cross-cutting gaps with file-level evidence, inconsistency clusters, and external landscape calibration (what was verified vs. what remains unverified)
workstreams.md	The plan: WS0 quick wins plus WS1–WS7 structural workstreams, each with evidence, actions, worked artifacts, and acceptance criteria; phased sequencing
metrics.md	Measurement program: baseline instrumentation for agent-authored PRs, KPI definitions and readiness thresholds, experimentation discipline, dashboards

Method and evidence base

This plan was produced 2026-07-19 by a structured multi-agent analysis, then synthesized and edited:

• Repo analysis: 41 per-repo inventories plus 7 cross-cutting deep dives (guidance canon, agentic docs suite, CI/CD — all 57 workflow files read in full, cross-repo DevEx consistency, platform-runtime dogfooding, eval and quality infrastructure, context/KB/index infrastructure) over the full working trees of all 42 alphaswarm* repos. Claims cite real files, and where load-bearing, line anchors.
• External research: two internal deep-research reports on enterprise agentic-coding standards (2026-07), re-verified by adversarial multi-voter fact-checking against live primary sources on 2026-07-19. Verified findings and — equally important — the claims that did not survive verification are listed in gaps.md §4.
• Prior internal art, which this plan executes rather than rediscovers: the org audit (2026-07-14), alphaswarm_internal/TESTING_FRAMEWORK_BLUEPRINT.md (991 lines), alphaswarm_config/ANALYSIS.md, the docs-repo ADR series through ADR 029, and the index-debt notes in alphaswarm_index.

The headline findings, in five sentences

1. AlphaSwarm's concepts are ahead of the industry playbooks: the hash-locked spec runtimes, DataMCPTool boundary, promotion gates, and intervention nodes already implement — with stronger invariants — most of what the 2026 enterprise-agentic-coding literature recommends.
2. The execution surfaces agents depend on have decayed: ~40% of the estate has no CI, several existing gates are silently broken or report-only, and "green" frequently certifies nothing (see gaps.md §2, gaps G1–G3).
3. Bootstrap is the #1 session blocker: unpublished sibling packages, six PATs, three checkout strategies, and near-zero lockfiles mean agents burn turns reverse-engineering installs, or simply fail (gaps.md G4).
4. The guidance canon — the org's single biggest agentic asset — has no mechanical freshness enforcement, so it drifted into contradictions that now mislead the agents it was written for (gaps.md G5–G8).
5. The org cannot yet answer "did the coding agents make things better": no revert-rate, time-to-merge, or first-push-green measurement exists for agent-authored PRs, and the eval gate is inert (gaps.md G9; fixed by metrics.md).

Reading order

Skim gaps.md §1 (strengths) to see what we deliberately do not rebuild → read the gap table §2 → then workstreams.md top-to-bottom (WS0 is actionable this week) → metrics.md defines how we will know it worked.

Registration and tracking

• A pointer row in alphaswarm_index/index.md must be added via the curator process — the index's sole-writer invariant is preserved.
• alphaswarm_internal/plans/ gets a manifest entry pointing here (it is an archive of 172 plans with unclear liveness; this plan must not silently join it — liveness is enforced by the last_reviewed staleness discipline of this repo and the KPI cadence in metrics.md).
• Per-repo execution tracking stays in each repo's existing convention (.cursor/plans/* debt notes in the monolith; AGENTS.md Validation-block updates elsewhere).