Aseptic: A Structured Multi-Agent Coordination Methodology for Parallel Software Development

Abstract

Aseptic is a filesystem-based methodology for governing the work of multiple AI coding agents operating concurrently across interdependent software projects. Developed empirically between 2026-06-12 and 2026-06-17 across five active codebases — fossic (Rust event store), cerebra (Python AI cognition system), lumaweave (TypeScript graph visualization), policy-scout (governance tooling), and lattica (a Tauri 2/React federation hub) — the methodology provides two interlocking layers of discipline: a per-agent pass governance layer (blast-radius, cross-pollination, living reports, merge-gates, pass-complete) and a multi-agent coordination layer (hub-and-spoke file routing, grounding passes, unified passages, supervision model, coordination patterns).

Aseptic addresses three failure modes endemic to multi-agent AI development: loss of context between sessions, undetected inter-project impact from local changes, and coordination collapse when agents work against stale assumptions. The methodology emerged through self-application — Aseptic was bootstrapped on itself (fossic v0.10.x, commit 7323f09) and has been continuously refined through 14 formally documented coordination patterns, one validated Unified Passage, and a federation round involving all five projects.

This paper documents the full system, traces its evolution chronologically, identifies seven significant gaps, and proposes a concrete MCP server and Claude Code skills architecture for mechanizing the methodology.

---

1. Introduction

Modern AI-assisted software development has outpaced its coordination infrastructure. A single developer working with multiple AI coding agents across multiple projects faces a coordination problem that has no established solution: each agent instance has a fresh context window, zero memory of prior sessions, and no native awareness of what other agents are doing in adjacent codebases. The result is a pattern the Aseptic documentation explicitly names: "stale assumptions about platform state are the most common source of cross-project bugs."

Existing approaches to this problem are inadequate. Simple file-based notes lack structure and decay rapidly. Chat history is not machine-readable by agents in other sessions. Shared documentation wikis require manual maintenance and provide no pass-level traceability. Version control history captures what changed but not why, who was notified, or what adjacent systems were affected.

Aseptic fills this gap with a discipline rather than a platform. It is a set of structured artifacts (blast-radius files, cross-pollination notices, coordination files, living reports) and behavioral protocols (grounding passes, manifest snippets, relay conventions, supervision model) that a developer and their AI agents follow to maintain coherent multi-project state across session boundaries. Critically, it is filesystem-native — all coordination state lives in git-tracked files that any agent can read, any session can ground in, and any audit can reconstruct from.

This paper documents Aseptic as it actually exists, derived entirely from the artifacts produced by the system itself: 269 files consolidated from five projects, spanning blast-radius logs, coordination inbound/outbound message archives, cross-pollination notices, pass-complete reports, merge-gate records, and methodology documentation.

---

2. System Overview

2.1 Architecture: Hub and Spoke

Aseptic operates on a hub-and-spoke topology. Lattica functions as the coordination hub: it hosts the docs/coordination/ directory tree that all project Claudes read for platform-wide state, runs the advocate coordination round structure, and owns the mail routing manifest. The spoke projects — fossic, cerebra, lumaweave, policy-scout, and the ai-stack/bo joint node — operate autonomously on their own codebases but deposit coordination artifacts into Lattica's tree and read it during grounding passes.

The developer is the courier: AI agents cannot directly message each other. Coordination travels via the filesystem, and the developer relays manifest snippets between sessions. This is explicit and intentional. From COORDINATION_PROTOCOL.md: "The developer is coordinating multiple projects in parallel. Their bandwidth is the scarcest resource. Save it for decisions, not lookups."

2.2 Core Concepts

Pass. The atomic unit of work. A pass is a bounded coding or documentation session with a version identifier (semver-like: v0.3.5, or with letter suffixes for cleanup passes: v0.3.5z → v0.3.5y → ...). Every pass produces at minimum a blast-radius file.

Blast-radius. A per-pass artifact documenting the precise scope of change: files created/modified/deleted, public API changes, schema changes, configuration changes, dependency changes, behavior changes, and living report updates. Filed at pass completion. Can be retroactive for pre-Aseptic passes (marked with epistemic caveats). Location: docs/aseptic/blast-radius/pass-<version>.md.

Cross-pollination. A per-pass artifact documenting impact to adjacent projects. Three severity tiers: FYI (awareness only), NEEDS-AWARENESS (read before implementing the named feature), ACTION-REQUIRED (breaking change requiring immediate action). Each section includes a pre-drafted advocate-agent message ready to copy-paste into the recipient project's session. Filed at docs/aseptic/cross-pollination/pass-<version>.md in the authoring project, mirrored to lattica/docs/coordination/cross-pollination/<project>/ in the hub.

Living reports. Three accumulating documents per project: TECH_DEBT.md, POLISH_DEBT.md, and DEVIATION.md. Entries are opened at the pass where a finding is made and resolved in a later pass when addressed. Every pass touches living reports (bumping last_reviewed). These are the project's institutional memory between sessions.

Pass-complete. A structured pass completion message containing SHA(s), date, deliverables checklist, API changes, living report updates, adjacent project impact summary, and open items entering the next version. Stored at docs/aseptic/pass-complete/pass-<version>.md.

Merge-gate. A pre-push checkpoint report listing all commits, their contents, a pre-push checklist (no secrets, no instrumentation, living reports correct, no accidental staging), and manual actions required post-push. Created and filed before git push origin main, then developer approval sought.

Coordination files. Inbound and outbound relay messages between project Claudes, routed through the developer. Filename convention: YYYY-MM-DD_<source>_to_<target>_<topic>.md. Required YAML front matter: source, target, date, topic, status, related, severity.

Mail routing manifest. An append-only chronological log (mail_routing.md) in Lattica's coordination directory. Every coordination file filed gets a one-line entry: YYYY-MM-DD · [source → target] · channel · filename.md. Historical entries are never edited.

Grounding pass. A lightweight (5–10 minute) read-only pass run before any substantive coding pass. Five-step checklist: (1) check mail, (2) check cross-pollination from other projects, (3) check current states of dependency projects, (4) check unified-passage status, (5) update own current_state.md if relevant. Produces no commits.

Unified Passage (UP). A synchronized cross-project execution mechanism for work requiring genuine multi-project coordination. Five phases: DRAFT → REVIEW → ARM → EXECUTE → POST_FLIGHT. Each phase requires participant acknowledgment before advancing. Only the developer can authorize ARM→EXECUTE. UP directory structure lives at docs/coordination/unified-passage/UP-NNN/.

Supervision model. Lattica Claude and Fossic Claude operate as peer supervisors, each owning a substrate slice (Lattica: shell architecture, tile composition, advocate coordination; Fossic: event sourcing substrate, cross-consumer vocabulary). They cross-gate each other's work at arc closes.

---

3. Methodology Evolution (Chronological)

3.1 Pre-Aseptic: Fossic Solo (v0.1.0 – v0.9.0, before 2026-06-12)

Fossic was built through approximately nine major passes before Aseptic existed. The structure is reconstructable from retroactive blast-radius files filed during the bootstrap:

• v0.1.0 (commit b92d00f): Core Rust event store — 13 files, Store::open/declare/append/read_range, BLAKE3 content-addressed event identity, deduplication property, events/streams/meta schema.
• v0.2.0 (commit adfa3de): Branches, snapshots, pattern-matched reducers, glob dispatch.
• v0.3.0 (commit 0ed84a0): Subscriptions and WAL-backed live event delivery — SubscriptionMode::synchronous(), SubscriptionMode::post_commit(). Threading: std::thread + crossbeam-channel, NOT Tokio (a spec error that persisted to v0.11.0).
• v0.4.0–v0.9.0: Cross-stream queries, upcasters, transforms, PyO3 Python binding, Tauri IPC companion, CI/wheels/release automation, Node binding.

None of these passes had blast-radius files, living reports, or cross-pollination notices. This is the "retroactive era" — the baseline against which Aseptic's contribution is measured.

3.2 Aseptic Bootstrap on Fossic (v0.10.x, 2026-06-12)

On 2026-06-12, Aseptic was bootstrapped on fossic itself in a single pass (commit 7323f09). This pass created 25 files: all methodology docs, three living reports seeded from a TIDYUP survey (4 tech debt, 4 polish debt, 3 deviations), and retroactive blast-radius files for passes 1–8.

The chicken-and-egg problem is explicit: pass v0.10.x could not file its own blast-radius at the time (Aseptic was creating itself). The self-referential file was filed retroactively by the next pass (v0.10.w).

v0.10.w: Corrected retroactive blast-radius files against real SHAs. The bootstrap estimates had wrong content for passes 2–8 — each ascribed the wrong pass's content. Closed three bootstrap gaps: ADR namespace, retroactive file convention formalization, and DV-002 (purge semantics).

v0.10.0t: First cross-pollination pass. Cerebra's Phase 6/7/8 cycle runtime vocabulary (22 event types) integrated into AGENT_TRACE_VOCABULARY.md §7. First multi-project knowledge propagation event.

v0.10.1: event_type_filter added to ReadQuery across all four layers (Rust/Python/Node/Tauri) — motivated by Policy Scout's need to read PolicyViolation events without client-side filtering.

v0.11.0: Threading model spec correction. FOSSIC_V1_SPEC.md §14 rewritten from Tokio to std::thread + crossbeam-channel. DV-003 resolved.

Assessment: The bootstrap pass demonstrated that Aseptic's outputs fitting the formats they documented was the first signal the methodology was self-consistent. It also immediately surfaced format drift — the bootstrap estimates had wrong content for multiple passes. The correction in v0.10.w became the template for blast-radius amendment discipline.

3.3 Lattica Bootstrap and Cross-Project Launch (v0.0.0z–v0.1.0, 2026-06-13)

v0.0.0z (commit 4615664): First descending-letter cleanup pass. Moved fossic historical blast-radius files from an incorrect location into docs/aseptic/examples/fossic-pass-history/ with a README. Git rename with history preserved.

v0.0.0y (commit b5b3982): Coordination infrastructure established. Created docs/coordination/ with README, COORDINATION_PATTERNS.md (10 banked patterns from fossic experience), SUPERVISION_MODEL.md (Lattica/Fossic peer-supervisor split formalized). First inbound relay artifacts filed.

v0.0.0x (commit 01e6993): Two-commit SHA pattern locked in PASS_REPORTING.md — blast-radius files now reference a stable commit SHA before the blast-radius commit, ending the amend-with-SHA pattern. pass-complete/ directory created. First cross-project relay: Cerebra pass-9.3 (CatalystInvoked, CatalystArmSelected) acknowledged and routed to Fossic Claude.

v0.1.0 (commit b52f0cd): Round-1 close. ADR-009 locked — the first platform identity decision: hybrid Mode A (single-bundle React composition tiles) + Mode B (Tauri 2 child webview embedding) federated frontend model. Six advocate rounds closed with locked responses. Living reports updated. This commit established Lattica's architectural identity.

The advocate round structure is the key mechanism here: each project deposited requirements.md and capabilities.md. Lattica Claude synthesized these into per-project locked responses covering specific requirement IDs. The round structure (round-1a, round-2a, round-3a) allowed iterative refinement before locking.

3.4 First Code and Coordination Formalization (v0.2.0–v0.2.1.c, 2026-06-14)

v0.2.0 (commit 73adebc): Lattica's first code commit. Tauri 2 + Vite 7 + React 19 scaffold, fossic store integration, canary event on startup, HelloTile proving live subscription, 10 fossic Tauri commands, ADR-011 through ADR-014 locked. Merge-gate protocol first exercised.

The B-prompt incident (between v0.2.0 and v0.2.1.a): Five parallel Claude sessions accidentally executed the same prompt, producing off-script artifacts: UNIFIED_PASSAGE.md, PORTABLE_COMMS_SNIPPET.md, UP-NNN-TEMPLATE.md, partial COORDINATION_PATTERNS.md edits (P-011 added but P-012 missing), and an attempted file rename. These were left as working-tree artifacts, never committed.

v0.2.1.a: COORDINATION_PROTOCOL.md formalized and distributed to all 6 project teams as mirrors. 14 outbound coordination responses filed, 8 inbound files, 9 cross-pollination mirrors. STATUS.md sweep (F-001 through F-005 flags, surfacing inconsistencies without editing). Mail routing manifest established.

v0.2.1.c: Adopted the B-prompt artifacts after triage — UNIFIED_PASSAGE.md, PORTABLE_COMMS_SNIPPET.md, UP-NNN-TEMPLATE.md adopted as-is; P-012 ("For project:" sections) drafted and added to close the gap the B-prompt left. The accidental Claudes produced 95% of the deliverable; one pass absorbed it cleanly.

The B-prompt incident is the most revealing event in the methodology's history. Five agents running the same prompt simultaneously produced useful artifacts but also duplications, version string drift, and the P-012 gap. The off-script triage pattern was the response: classify each artifact as ADOPT / MERGE / DEFER rather than accepting or rejecting the entire set.

3.5 Multi-Agent Coordination at Scale (v0.2.1.u–z, 2026-06-14)

This period saw Aseptic's coordination layer exercised concurrently across all six projects.

Cerebra pass-9.4 (ReinjectionTriggered): Cerebra filed a cross-pollination notice. Lattica routed to Fossic for vocabulary integration. Pattern established: Cerebra cross-pollinates → Lattica acknowledges and routes → Fossic integrates into AGENT_TRACE_VOCABULARY.md.

v0.2.1.y: UP-001 (first Unified Passage) DRAFT created. OVERVIEW.md, ASSIGNMENTS.md, ROLLBACK.md filed. Participants (Cerebra + Fossic) sent ARM-trigger notifications.

v0.2.1.w: UP-001 ARM phase. Cerebra's pre-flight filed. ARM→EXECUTE transition pending developer authorization.

v0.3.2: UP-001 POST_FLIGHT filed. Cerebra had authored SignalEvaluatedRenderer.tsx and .css as a Python-only project with no TypeScript infrastructure. Lattica committed the files to src/renderers/cerebra/. Zero integration friction. P-013 pattern (guest author in host repo) empirically validated.

3.6 Component Contributions and Pattern Solidification (v0.3.2–v0.3.5.z, 2026-06-15)

v0.3.2y/z: P-014 (don't hardcode dynamic values) surfaced from UP-001 smoke test. Refined to distinguish "static-should-be-live" from "live-should-be-static-with-rationale."

v0.3.3: P-013 host designation correction — prior documentation had incorrectly stated "LumaWeave is host" for Policy Scout's renderer contributions; actual host is Lattica. Lesson: project Claude observations are valuable signal but should be verified against architectural source-of-truth before promoting to canonical docs.

v0.3.4–v0.3.5: Cerebra (Python-only, no TypeScript) authored OutcomeRecordedRenderer.tsx, ClutchDecisionMadeRenderer.tsx, and their CSS files as multiple guest-author contributions. Lattica committed each to src/renderers/cerebra/.

v0.3.5w–z: Design round initiated. Per-project design requests filed. Backend-prep investigation round. Each project submitted design/requests/<project>/design-request.md. Compiled into BACKEND_PREP_REPORT.md.

ai-stack/bo P-013 contribution (2026-06-15): ai-stack/bo Claude authored AiStackTopologyTile.tsx and .css directly into Lattica's filesystem. Fossic sidecar (fossic_sidecar.py) built and smoke-tested, proving the Ollama + nvidia-smi polling → fossic append pipeline.

3.7 Federation Round (2026-06-16)

The federation round is the methodology's most ambitious coordination exercise. All projects simultaneously submitted federation_design.md, needs-wiring.md, and reconciliation.md to a central compilation.

Key federation deliverables: Each project documented its proposed outbound event types for the hub relay, expected inbound subscriptions, IPC/store topology, and open binding questions. Lattica compiled PLATFORM_BASELINE_2026-06-16.md, PLATFORM_BASELINE_2026-06-16_v2.md, LATTICA_RECONCILIATION_BRIEF.md, and FEDERATION_DESIGN_2026-06-16.md.

Notable events:

• Cerebra CORS fix: Cerebra daemon was not sending Access-Control-Allow-Origin headers. Lattica tile's fetch() to http://localhost:7432 was CORS-blocked. First operational bug caught through cross-project coordination.
• LumaWeave hub store concurrent access: Confirmed WAL-mode SQLite supports concurrent multi-process access (relay agent appending + Tauri subscriptions reading).
• Policy Scout lockdown-bundle and approval-timeout: Two new CLI additions cross-pollinated — --json output flags and configurable timeout (was hardcoded 24h; now configurable 1–8760h range).
• Track A multi-ACK: All projects (cerebra, lumaweave, policy-scout, ai-stack/bo) confirmed Track A status via inbound close messages.

---

4. Core Protocols in Detail

4.1 Pass Lifecycle

Phase sequence:

1. Grounding — 5–10 minute read-only check (mail, cross-pollination, current states, UP status). No commits.
2. Execution — Two-attempt cap: fix and one retry both fail → stop and report. Five-pass cascade halt if unrelated failures share a signature.
3. Verification — typecheck, relevant tests. For visual changes: note manual verification requirement explicitly.
4. Blast-radius file — Two-commit SHA pattern: commit 1 is content; commit 2 is blast-radius + pass-complete; the blast-radius references commit 1's SHA.
5. Living report updates — Bump last_reviewed on all three reports. Open or resolve entries.
6. Cross-pollination (if adjacent impact) — File in own repo and mirror to hub.
7. Pass-complete — Structured completion message including SHA pair, checklist, open items.
8. Merge gate — Pre-push checklist filed. Discord approval sought via #approve-this before push.
9. Push — Only after explicit developer approval.
10. PASS COMPLETE report — Filed to #changelog. The ── PASS COMPLETE · delimiter triggers a version bump.

Descending-letter cleanup passes (v0.3.5z → v0.3.5y → ...): Cleanup passes off a base version use descending letters. They do not trigger arc closes, represent bounded housekeeping scope, and cannot include unrelated changes.

4.2 Blast-Radius Analysis

The blast-radius file is the highest-fidelity record in the system. Its sections are fixed: Files (created/modified/deleted), Public APIs (added/modified/removed), Schema changes, Configuration changes, Dependency changes, Behavior changes, Living report updates, Pass notes.

Critical discipline: verify against on-disk code, not audit docs. Stale audits have pointed to testids and components that no longer existed. The blast-radius is produced by diffing reality, not by recalling a plan.

Retroactive blast-radius files are marked: "All items in this file are retroactive estimates created at the Aseptic bootstrap. Verify against git log before trusting as precise record." This epistemic marking prevents future agents from treating estimates as ground truth.

4.3 Cross-Pollination

Cross-pollination triggers when a pass has meaningful adjacent-surface impact: a public API change affecting consumer projects, a shared schema or vocabulary change, a behavioral change with cross-project implications, or an actionable observation about another project's state.

Filing protocol:

1. File at <own-project>/docs/aseptic/cross-pollination/pass-<version>.md
2. Mirror to lattica/docs/coordination/cross-pollination/<own-project>/pass-<version>.md
3. Append entry to mail_routing.md immediately
4. End pass-complete report with "For <project>:" manifest snippets for each affected project

Pre-drafted messages are a key discipline. Each section of a cross-pollination file includes the exact text an advocate agent can use to brief the receiving project's Claude — eliminating the developer needing to synthesize.

4.4 Inbound/Outbound Message Routing

• Spoke → Hub: Files at inbound/YYYY-MM-DD_<source>_to_lattica_<topic>.md
• Hub → Spoke: Files at outbound/YYYY-MM-DD_lattica_to_<target>_<topic>.md
• Spoke → Spoke (via hub): Source writes to outbound; Lattica acknowledges and routes a copy to target's outbound queue.

Required YAML front matter: source, target, date, topic, status (one of: outbound | inbound | inbound-acknowledged | closed | superseded), related, severity.

Thread lifecycle: A thread closes when the originating issue is resolved. Acknowledgment-of-acknowledgment is the loop terminator — if you receive a message confirming receipt of your acknowledgment, do not respond.

Manifest snippets (P-012): End-of-pass reports include structured per-recipient blocks:

For cerebra:
- File: <absolute-path>
- From: Lattica
- Action: <one-line ask>

Format is load-bearing: grep-able, copy-paste-ready, minimal courier overhead.

4.5 Unified Passage (UP)

The UP mechanism is invoked for genuinely synchronized cross-project work. The canonical test: would working without synchronization cause one project to be left behind in a breaking state?

Directory structure:

coordination/unified-passage/UP-NNN/
  OVERVIEW.md        — what, why, participants, scope
  ASSIGNMENTS.md     — per-project deliverables with clear owner
  ROLLBACK.md        — pre-drafted rollback plan per participant
  pre-flight/        — per-project pre-flight confirmations
  acknowledgments/   — per-project review acknowledgments
  EXECUTION_LOG.md   — append-only execution record
  POST_FLIGHT.md     — outcome, deviations, retrospective

Phase transitions: DRAFT → REVIEW (participants acknowledge) → ARM (participants file pre-flights) → EXECUTE (developer authorizes, participants execute) → POST_FLIGHT (all confirm completion).

UP-001 (empirical validation, 2026-06-14): Cerebra (Python-only, no TypeScript) contributed SignalEvaluatedRenderer.tsx and .css to Lattica's tree. Full five-phase cycle exercised. Zero integration friction. Validated P-013 (guest author in host repo), which immediately generalized to three more contributions.

4.6 Off-Script Triage

When unexpected artifacts appear on disk, the protocol classifies each file:

• ADOPT: Content correct, complete, well-reasoned. Fix version strings and commit.
• MERGE: Content partially correct but has gaps. Complete the gaps and commit.
• DEFER: Decision requires developer judgment. Do not touch until directed.

The triage pass is read-only — no staging, no edits, no commits. It produces a report categorizing every unstaged artifact. Developer reviews and authorizes the adoption pass.

---

5. Gap Analysis

Gap 1: The Courier Bottleneck Is Structural

The developer is the only relay between Claude sessions. Every manifest snippet, every cross-pollination, every inbound/outbound message requires the developer to copy text and paste it into another session. The protocol reduces this overhead (P-003, P-012, structured manifest format), but cannot eliminate it while Claude sessions have no native inter-session communication.

At five projects, the courier load is manageable. At ten projects, it becomes the primary bottleneck. There is no automated mechanism to detect which sessions have unread mail, trigger grounding passes, or queue manifest snippets for delivery.

Severity: High — this is the fundamental scalability ceiling.

Gap 2: Grounding Pass Relies on Correct Self-Assessment

The grounding pass is manual and relies on the Claude instance accurately reading and synthesizing coordination state. The STATUS.md sweep (2026-06-14) found: F-001 (coordination file with no front matter), F-002 (placeholder never filled), F-003 (missing status field), F-004 (cross-pollination directories entirely unused despite protocol requiring use), F-005 (ADR superseded without updating references). These flags were surfaced by a sweep pass, not by routine grounding.

There is no automated validator that checks: did grounding correctly identify all unread mail? Are there cross-pollination files from the last 48 hours that haven't been acknowledged?

Severity: Medium — gaps accumulate silently between sweep passes.

Gap 3: Mail Routing Manifest Has No Enforcement

The mail_routing.md accumulated backfilled entries retroactively throughout the period studied — meaning files existed on disk that had never been logged. Multiple agents contributed backfill sweeps independently. The protocol says "append immediately" but this is behavioral discipline, not enforced constraint. In a multi-agent system where each agent has session amnesia, drift is structurally guaranteed.

Severity: Medium — the manifest is the audit trail; silent gaps undermine its reliability.

Gap 4: Format Convention Drift Is Documented as Inevitable

P-007 explicitly states: "Format isn't load-bearing for code work, so agents reconstruct it from fuzzy memory if the canonical template isn't pasted directly into the prompt." The evidence is visible throughout the corpus: version strings drifting, blast-radius files with inconsistent section ordering, YAML front matter fields present in some files and absent in others.

The current mitigation is template pasting in prompts. But there is no schema validation, no linting, no automated correction. Every format discipline is enforced only by agent behavioral compliance, which degrades with context loss.

Severity: Medium — format drift is noise in the audit trail, and noise compounds.

Gap 5: Unified Passage Is Expensive With No Lightweight Variant

UP-001 occupied multiple passes across multiple days and required five files of documentation before execution began. There is no "lightweight passage" mechanism for work that requires acknowledgment from other projects but not full multi-phase coordination. For example, when Cerebra ships a new event type that fossic must document, the current choice is: (a) handle informally via cross-pollination and hope fossic gets to it, or (b) spin up a full UP. Neither is right.

Severity: Medium — without a lightweight variant, work either gets under-coordinated (informal) or over-coordinated (full UP).

Gap 6: Accidental Parallel Execution Has No Prevention

The B-prompt incident (5 Claude sessions executing the same prompt simultaneously) produced useful output but also duplications, version string drift, and the P-012 gap. The off-script triage protocol is reactive, not preventive. A session-lock mechanism — writing a session.lock file at session start and clearing it at close — would surface conflicts before work begins.

Severity: Low-Medium — the triage handles recovery well, but the incident had a cost.

Gap 7: Federation Design Has No Automated Diffing Against Implementation

The 2026-06-16 federation round produced federation_design.md and needs-wiring.md files for each project describing intended relay vocabulary, stream patterns, and what still needs wiring. There is no automated mechanism to compare needs-wiring.md against actual implementation state, or to detect when a federation commitment has been satisfied. The methodology relies on each project Claude voluntarily updating current_state.md when a needs-wiring item is resolved.

Severity: Medium — the federation design is load-bearing architecture; its completion state should be mechanically trackable.

---

6. MCP Server Design

An Aseptic MCP server encodes the methodology's coordination layer as machine-invocable tools. Rather than having Claude agents manually maintain files, the MCP server is the authoritative interface for all coordination state mutations. All state is stored as git-tracked files — human-readable without the server.

6.1 Tool Definitions

aseptic_grounding_pass(project) → GroundingReport Runs the 5-step grounding checklist automatically. Reads unread inbound mail, new cross-pollination files since last grounding (compared against manifest), current states of dependency projects, active UP directories with pending actions. Returns {unread_mail, new_cross_pollinations, dependency_state_changes, up_actions_pending, recommended_action}. Does not write any files.

aseptic_file_inbound(source, target, topic, content, related?, severity?) → FiledFile Files an inbound coordination message. Creates the file at the correct path, adds required YAML front matter, appends the mail routing manifest entry. Validates that source/target are known projects and that the file does not already exist.

aseptic_file_outbound(source, target, topic, content, severity?) → FiledFile Same as above but for outbound messages. Additionally validates that the recipient project exists in the project registry.

aseptic_cross_pollinate(project, pass_version, sections[]) → FiledFiles Creates a cross-pollination file in both the project's own aseptic/cross-pollination/ and the hub mirror. Each section has {target, severity, summary, pre_drafted_message}. Appends mail routing entries for all recipient projects. Returns paths to both files.

aseptic_open_pass(project, version, summary, type) → BlastRadiusTemplate Validates version against the project's current version (must be a legal successor). Creates the blast-radius file template pre-populated with sections. If session locking is enabled, acquires it. Returns the template path.

aseptic_close_pass(project, version, blast_radius) → PassCloseResult Validates the blast-radius data (required sections present, SHA referenced). Creates the pass-complete file. Generates the merge-gate report draft. Returns manifest snippets for all affected adjacent projects. Releases session lock.

aseptic_merge_gate(project, version, commits[]) → MergeGateReport Creates the formal merge-gate report. Validates commits (no secrets pattern match, living report timestamps current, blast-radius SHA matches commit 1). Registers the pass as "awaiting push approval."

aseptic_living_report_add(project, type, id, content, pass_opened) → void Opens a new living report entry. Appends to the correct report file. Validates the ID does not already exist.

aseptic_living_report_resolve(project, type, id, resolution, pass_resolved) → void Resolves a living report entry. Updates status to resolved, adds resolution summary. Does not remove the entry (audit trail preservation).

aseptic_start_unified_passage(id, participants[], deliverables[], rollback) → UPDirectory Scaffolds the UP directory from the template. Creates OVERVIEW.md, ASSIGNMENTS.md, ROLLBACK.md. Registers the UP as DRAFT phase. Sends outbound coordination files to all participants. Returns directory path and participant manifest snippets.

aseptic_advance_unified_passage(id, to_phase, authorization_token?) → UPAdvanceResult Advances a UP to the next phase. For ARM→EXECUTE, requires authorization_token (developer-provided), preventing automated execution without human checkpoint. Validates that all required acknowledgments/pre-flights are present.

aseptic_status_dashboard() → PlatformStatus Returns {active_passes, pending_mail_by_project, stale_current_states, unacknowledged_cross_pollinations, active_ups, mail_routing_gaps}. Does not write anything. Directly addresses Gaps 2, 3, and 7.

aseptic_validate_coordination_file(path) → ValidationResult Validates a coordination file for: YAML front matter presence and required fields, status field validity, routing consistency (source/target match filename convention), mail routing manifest entry. Returns a list of violations, not pass/fail. Directly addresses Gap 4.

aseptic_update_current_state(project, content) → void Replaces (not appends) the project's current_state.md. Validates content is under the one-screen limit.

aseptic_add_pattern(id, title, example, application, status) → void Appends a new coordination pattern to COORDINATION_PATTERNS.md. Validates ID doesn't collide.

aseptic_acknowledge_close(thread_id, project) → void Marks an inbound coordination thread as closed. Updates status: closed in the file's front matter. Detects ack-of-ack scenarios and emits a LOOP_TERMINATOR flag to prevent additional responses.

6.2 Mapping to Protocol Documents

---

7. Claude Code Skills Design

7.1 What Claude Code Skills Are

Claude Code skills are invokable slash commands (e.g., /aseptic-ground) that encode opinionated, multi-step workflows using MCP server tools as their substrate. Where MCP tools are low-level and single-purpose, skills are high-level workflows that make decisions, combine multiple tool calls, and surface intermediate results for review before proceeding.

Skills are defined in .claude/ configuration and appear in the Claude Code CLI. They can be triggered explicitly by the developer (/aseptic-ground) or matched automatically when descriptions align with what the user is asking.

7.2 Skills vs. MCP Tools

Best as MCP tools (atomic, no decisions): filing individual coordination files, updating current states, adding pattern entries, resolving living report entries, status dashboard reads.

Best as skills (workflow, context-aware, may pause for review): full grounding pass workflow, pass open → close lifecycle, cross-pollination generation from blast-radius data, unified passage initialization, off-script triage, end-of-pass report generation.

7.3 Skill Designs

---

/aseptic-ground Trigger: "Run the Aseptic grounding pass for the current project before any coding work."

Workflow: (1) Identifies current project from working directory. (2) Calls aseptic_grounding_pass(project). (3) If unread_mail non-empty: displays each message with source/topic/severity and prompts "Review before coding?". (4) If new_cross_pollinations non-empty: lists each with severity and affected surface. (5) If up_actions_pending non-empty: displays each action with UP ID and required deliverable. (6) Outputs: "Grounding complete. N mail items, M cross-pollinations, K UP actions."

---

/aseptic-pass-start <version> <summary> Trigger: "Open a new Aseptic pass with the given version identifier."

Workflow: (1) Validates version against current project version. (2) Calls aseptic_open_pass(). (3) Creates blast-radius template. (4) Confirms: "Pass v<version> opened. Blast-radius template at docs/aseptic/blast-radius/pass-<version>.md. Fill in sections as you work."

---

/aseptic-pass-close Trigger: "Complete the current Aseptic pass: validate blast-radius, create pass-complete, generate merge-gate, output manifest snippets."

Workflow: (1) Reads current pass's blast-radius template. Identifies unfilled sections, surfaces gaps: "Section 'Behavior changes' appears empty. Confirm no behavioral changes? [Y/n]". (2) Calls aseptic_close_pass(). (3) Validates living reports are at current version. (4) Generates merge-gate draft, displays for review. (5) Validates all coordination files produced this pass. (6) Outputs manifest snippets for all adjacent projects. Developer confirms before forwarding.

---

/aseptic-cross-poll <pass-version> Trigger: "Generate a cross-pollination notice from the current pass's blast-radius."

Workflow: (1) Reads blast-radius for <pass-version>. Analyzes which sections have adjacent-project impact. (2) For each impacted project, determines severity (ACTION-REQUIRED if breaking, NEEDS-AWARENESS if API-additive, FYI otherwise). (3) Generates draft with pre-drafted advocate messages. (4) Displays draft for review. Developer confirms severity classifications. (5) Calls aseptic_cross_pollinate(). (6) Returns mail routing entries and manifest snippets.

---

/aseptic-relay <to-project> <topic> Trigger: "Draft and file an outbound coordination relay message to another project."

Workflow: (1) Opens buffer with YAML front matter pre-filled. (2) Developer writes message body. (3) Calls aseptic_file_outbound(). (4) Appends mail routing entry. (5) Returns manifest snippet:

For <to-project>:
- File: <absolute-path>
- From: <source>
- Action: <one-line ask>

---

/aseptic-up-init <id> Trigger: "Initialize a new Unified Passage with the given ID."

Workflow: (1) Validates <id> follows UP-NNN format and does not collide. (2) Prompts for: participants, high-level deliverable description, rollback criteria. (3) Calls aseptic_start_unified_passage(). (4) Creates OVERVIEW.md, ASSIGNMENTS.md, ROLLBACK.md. (5) Outputs participant notification snippets. (6) Displays: "UP-<id> in DRAFT phase. Send manifest snippets to participants to begin REVIEW."

---

/aseptic-triage Trigger: "Inspect unstaged/untracked files, classify as ADOPT/MERGE/DEFER, produce triage report without modifying anything."

Workflow: (1) Runs git status --porcelain to enumerate unstaged and untracked files. (2) For each file: reads content, checks against expected schema (front matter, section headers, version strings). (3) Classifies: ADOPT / MERGE / DEFER. (4) Outputs triage table in off-script-triage.md format. (5) States explicitly: "No files modified. To adopt, run /aseptic-adopt <files>."

---

/aseptic-status Trigger: "Show current platform coordination status: active passes, pending mail, cross-pollination gaps, UP phases, stale current states."

Workflow: (1) Calls aseptic_status_dashboard(). (2) Renders structured table per section. (3) Highlights overdue items (mail unacknowledged >48h, current_state.md not updated >72h, UP phase unchanged >96h). No writes.

---

8. Conclusion

Aseptic is not a framework invented speculatively — it is a methodology that emerged from practice, refined by failure, and documented by the agents that used it. Its core insight is simple: AI coding agents have session amnesia, so the coordination artifacts must live in the filesystem, not in the agents. Every protocol (blast-radius, cross-pollination, grounding pass, mail routing, unified passage) is a structured file that any agent can read cold and act on correctly without needing the history of how it got there.

The 269 source files examined in this study represent approximately four to five days of intensive multi-agent development. In that time: one event store went from undocumented to formally specified (fossic v0.10.x); a multi-project platform went from concept to working code with locked architectural decisions (lattica v0.3.5); a five-project federation design was produced, interviewed, and archived. Fourteen coordination patterns were banked. One Unified Passage was executed end-to-end and validated a new pattern (P-013) that immediately generalized to three more contributions.

The gaps are real but addressable. The courier bottleneck (Gap 1) is the hardest — it requires either native inter-session messaging (which Claude does not currently support) or automated session triggering (which an MCP server could partially enable). The format drift and manifest enforcement gaps (Gaps 2–4) are directly solvable by the MCP server's validation tools. The UP lightweight variant gap (Gap 5) is a design addition.

Building Aseptic as an MCP server transforms it from behavioral discipline into enforced infrastructure. The protocol's most fragile parts — manual manifest appending, format compliance, session isolation — become automatic. The developer's courier role shrinks from "copy-paste manifest snippets and hope nothing gets dropped" to "authorize ARM→EXECUTE and confirm push." Building it as Claude Code skills makes that infrastructure accessible at the invocation level the developer already uses: a /aseptic-ground at session start, a /aseptic-pass-close before committing, an /aseptic-relay when a cross-project message is needed.

The discipline remains — the methodology does not disappear behind automation — but its execution cost drops to the point where compliance is easier than non-compliance.

---

Derived from 269 source files across 5 projects, spanning passes v0.1.0 through v0.3.5r (2026-06-12 to 2026-06-17). All claims are grounded in artifacts from the aseptic-mcp directory tree.