Skip to content

Instantly share code, notes, and snippets.

@jfarcand

jfarcand/IMPLEMENTATION-PLAN-v0.5.md Secret

Last active April 16, 2026 20:13
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jfarcand/a1a664a1136a610567d7ea926b7e610f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jfarcand/a1a664a1136a610567d7ea926b7e610f to your computer and use it in GitHub Desktop.
Download ZIP
Atmosphere — Implementation Plan v0.5 (worktree: feat/ai-agent-foundation, private)
Raw
IMPLEMENTATION-PLAN-v0.5.md

Implementation Plan — AI Agent Foundation v0.5

Worktree: .claude/worktrees/ai-agent-foundation Branch: feat/ai-agent-foundation Strategy reference: v0.5 gist (supersedes v0.1–v0.4) Date: 2026-04-15 Status: plan draft — no code yet, pending ChefFamille review

This plan covers: 8 foundation primitives · 2 proof samples · documentation (in-repo + sibling site) · 6 test surfaces (unit, contract, integration, Playwright E2E, OpenClaw compat, chrome-devtools MCP validation) · release prep. Target size ~24 hours across 3 focused sessions.

Phase 0 — Worktree warmup (~15 min)

Before any code runs in the worktree, deal with the Maven cache staleness issue (per feedback_stale_maven_cache.md):

cd .claude/worktrees/ai-agent-foundation
git config core.hooksPath .githooks    # session-start hook per CLAUDE.md
./mvnw install -am -q -pl modules/ai -DskipTests   # warm the local cache

Verify baseline is green:

./mvnw compile -pl modules/ai             # zero warnings (mandatory)
./mvnw test -pl modules/ai -DskipITs      # existing tests still pass

If warnings or failures: stop, fix, then proceed. We never start a new feature on a red baseline.

Phase 1 — Primitive implementation (eight primitives, ~12 h total)

Ordering rationale

Earlier primitives enable later ones:

  1. AgentState — foundation of every other primitive that touches state
  2. AgentWorkspace — consumes AgentState for its OpenClaw / Claude-Code adapter reads
  3. ProtocolBridge — architectural relocate of existing transports (MCP, A2A, AG-UI, gRPC) + elevation of InMemoryProtocolBridge. Must be in place before AiGateway and AgentIdentity wire into it.
  4. AiGateway — facade over existing router + budget + credentials. Small consolidation; needs ProtocolBridge named so gateway boundary is unambiguous.
  5. AgentIdentity — per-user identity / credentials / permissions / audit. Uses AgentState for audit storage, AiGateway for per-user credential lookup.
  6. ToolExtensibilityPoint — per-user MCP client, pluggable trust, dynamic tool discovery. Uses AgentIdentity for trust provider resolution.
  7. Sandbox — standalone SPI + Docker default. Doesn't depend on other v0.5 primitives but needs AgentIdentity for per-user sandbox credential scoping.
  8. AgentResumeHandle — needs ProtocolBridge in place (bridge-agnostic reattach semantics) and AgentState (reconstituted conversation + run state). Last because it depends on most of the others.

Per-primitive template

Every primitive lands through the same five-step cycle. No primitive is "done" until all five steps are green.

  1. SPI design — write the interface + the Javadoc contract + the package-info.
  2. Default implementation — the Atmosphere-house default (e.g., FileSystemAgentState, InMemoryProtocolBridge, DockerSandbox).
  3. Contract test — run against all seven runtimes in CI. Test harness extends AbstractAgentRuntimeContractTest or a new parallel harness per primitive.
  4. Wire existing code — relocate / delegate / deprecate whatever the primitive supersedes. No backward-compat shims except the documented AiConversationMemory thin delegation.
  5. Full compile with zero warnings — ./mvnw compile -pl modules/ai before commit.

Primitive 1 — AgentState (~2 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/state/AgentState.java — SPI
  • modules/ai/src/main/java/org/atmosphere/ai/state/FileSystemAgentState.java — default backend
  • modules/ai/src/main/java/org/atmosphere/ai/state/DatabaseAgentState.java — optional SQLite/Redis backend
  • modules/ai/src/main/java/org/atmosphere/ai/state/AutoMemoryStrategy.java — sub-SPI + 4 built-ins
  • modules/ai/src/main/java/org/atmosphere/ai/state/MemoryEntry.java — record
  • modules/ai/src/main/java/org/atmosphere/ai/state/RuleSet.java — record
  • modules/ai/src/main/java/org/atmosphere/ai/state/package-info.java
  • modules/admin/src/main/java/org/atmosphere/admin/state/StateController.java — inspection endpoints
  • modules/ai/src/main/java/org/atmosphere/ai/AiConversationMemory.java — edit to delegate
  • modules/adk/src/main/java/org/atmosphere/ai/adk/AdkAgentRuntime.java — fix latent capability lie (honor context.history())

Contract test: modules/ai-test/src/test/java/org/atmosphere/ai/test/AgentStateContractTest.java — write fact, restart, recall, delete, recall-empty loop per runtime.

Deliverable gate: seven green runs in CI.

Primitive 2 — AgentWorkspace (~1 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/workspace/AgentWorkspace.java — SPI
  • modules/ai/src/main/java/org/atmosphere/ai/workspace/OpenClawWorkspaceAdapter.java
  • modules/ai/src/main/java/org/atmosphere/ai/workspace/ClaudeCodeWorkspaceAdapter.java
  • modules/ai/src/main/java/org/atmosphere/ai/workspace/AtmosphereNativeWorkspaceAdapter.java
  • modules/ai/src/main/java/org/atmosphere/ai/workspace/package-info.java
  • cli/atmosphere — add --workspace <path> flag

Contract test: AgentWorkspaceContractTest — load OpenClaw workspace, load Claude Code workspace, load native workspace, assert identical AgentState population across the three and identical behavior under each of the seven runtimes.

OpenClaw fixture: check in a minimal OpenClaw-format workspace under modules/ai-test/src/test/resources/fixtures/openclaw-workspace/ with AGENTS.md, SOUL.md, USER.md, IDENTITY.md, MEMORY.md, memory/2026-04-15.md, skills/example/SKILL.md, and a JSONL session file.

Primitive 3 — ProtocolBridge (~1 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/bridge/ProtocolBridge.java — SPI
  • modules/ai/src/main/java/org/atmosphere/ai/bridge/InMemoryProtocolBridge.java — promoted from LocalAgentTransport
  • modules/mcp/src/main/java/org/atmosphere/ai/mcp/McpProtocolBridge.java — wrap existing server host
  • modules/a2a/src/main/java/org/atmosphere/ai/a2a/A2aProtocolBridge.java — wrap existing JSON-RPC
  • modules/agui/src/main/java/org/atmosphere/ai/agui/AgUiProtocolBridge.java — wrap existing event mapper
  • modules/grpc/src/main/java/org/atmosphere/ai/grpc/GrpcProtocolBridge.java — wrap existing service
  • modules/coordinator/src/main/java/org/atmosphere/coordinator/transport/LocalAgentTransport.java — delete, migrated to InMemoryProtocolBridge

Contract test: ProtocolBridgeContractTest — invoke the same @Agent through all five bridges, assert identical AgentLifecycleListener event sequence, identical AiInterceptor application, identical tracing, identical response content.

Architectural discipline: no special case for "local". @Coordinator dispatch, @Prompt invocations, MCP calls, A2A calls all enter through ProtocolBridge.dispatch(...).

Primitive 4 — AiGateway (~1 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/gateway/AiGateway.java — facade
  • modules/ai/src/main/java/org/atmosphere/ai/gateway/PerUserRateLimiter.java — new, small
  • modules/ai/src/main/java/org/atmosphere/ai/gateway/UnifiedTraceExporter.java — new, small
  • Existing DefaultModelRouter, StreamingTextBudgetManager, MicrometerAiMetrics — wire behind AiGateway, no behavior change

Contract test: AiGatewayContractTest — every LLM call traverses the gateway, per-user rate limit gates fire, unified trace export emits across all seven runtimes.

Primitive 5 — AgentIdentity (~1 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/identity/AgentIdentity.java — SPI
  • modules/ai/src/main/java/org/atmosphere/ai/identity/PermissionMode.java — enum
  • modules/ai/src/main/java/org/atmosphere/ai/identity/CredentialStore.java — pluggable sub-SPI
  • modules/ai/src/main/java/org/atmosphere/ai/identity/AtmosphereEncryptedCredentialStore.java
  • modules/ai/src/main/java/org/atmosphere/ai/identity/OsKeychainCredentialStore.java
  • modules/ai/src/main/java/org/atmosphere/ai/identity/OAuthDelegatedCredentialStore.java
  • modules/durable-sessions/src/main/java/org/atmosphere/session/DurableSession.java — add permissionMode field
  • modules/admin/src/main/java/org/atmosphere/admin/identity/IdentityController.java — audit + session share endpoints

Contract test: AgentIdentityContractTest — per-user credentials resolve correctly on each runtime, permission modes gate tool execution correctly, audit log captures all tool calls per user, read-only session share produces a replay-only view.

Primitive 6 — ToolExtensibilityPoint (~1.5 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/tool/ToolExtensibilityPoint.java — SPI
  • modules/ai/src/main/java/org/atmosphere/ai/tool/ToolIndex.java — semantic search over tool descriptions
  • modules/ai/src/main/java/org/atmosphere/ai/tool/DynamicToolSelector.java — maxToolsPerRequest selector
  • modules/mcp/src/main/java/org/atmosphere/ai/mcp/PerUserMcpClientConfig.java — parse MCP.md
  • modules/ai/src/main/java/org/atmosphere/ai/tool/McpTrustProvider.java — pluggable sub-SPI (reuses AgentIdentity.CredentialStore backends)

Contract test: ToolExtensibilityContractTest — add 100 synthetic tools, agent request selects top-N correctly, per-user MCP tools load correctly with each of the three trust providers, dynamic discovery works across all seven runtimes.

Primitive 7 — Sandbox (~1.5 h)

Files:

  • modules/sandbox/pom.xml — new module
  • modules/sandbox/src/main/java/org/atmosphere/ai/sandbox/Sandbox.java — SPI
  • modules/sandbox/src/main/java/org/atmosphere/ai/sandbox/DockerSandbox.java — default backend
  • modules/sandbox/src/main/java/org/atmosphere/ai/sandbox/SandboxExec.java — record
  • modules/sandbox/src/main/java/org/atmosphere/ai/sandbox/SandboxFs.java — record
  • modules/sandbox/src/main/java/org/atmosphere/ai/sandbox/SandboxSnapshot.java — record
  • modules/sandbox/src/main/java/org/atmosphere/ai/sandbox/@SandboxTool.java — annotation

Contract test: SandboxContractTest — spawn a Docker sandbox, execute shell, read/write files, expose a port, snapshot + restore, hibernate + resume. Run across all seven runtimes (sandbox behavior is runtime-independent but we prove the cross-runtime hookup).

Backlog (not in v0.5): Firecracker, Kata, Vercel Sandbox, E2B, Modal, Blaxel — all land as separate optional modules later.

Primitive 8 — AgentResumeHandle (~2 h)

Files:

  • modules/ai/src/main/java/org/atmosphere/ai/resume/AgentResumeHandle.java — SPI
  • modules/ai/src/main/java/org/atmosphere/ai/resume/RunRegistry.java — runId → ExecutionHandle
  • modules/ai/src/main/java/org/atmosphere/ai/resume/RunEventReplayBuffer.java — reuse BroadcasterCache if the shape fits
  • modules/durable-sessions/src/main/java/org/atmosphere/session/DurableSession.java — add activeRuns field
  • modules/durable-sessions/src/main/java/org/atmosphere/session/DurableSessionInterceptor.java — reattach on reconnect when runId header present
  • modules/ai/src/main/java/org/atmosphere/ai/StreamingSession.java — expose runId()

Contract test: AgentResumeHandleContractTest — start a long-running tool call, disconnect mid-stream, wait 5 seconds, reconnect with runId header, assert missed events replay correctly and the in-flight run continues, assert cancellation cleanup fires if client never reconnects before TTL.

Phase 2 — Proof samples (~4 h total)

Proof sample #1 — samples/personal-assistant/ (~2 h)

Exercises: AgentState, AgentWorkspace, AgentIdentity, ToolExtensibilityPoint, AiGateway, ProtocolBridge (crew members via InMemoryProtocolBridge), multi-channel continuity.

Files:

  • samples/personal-assistant/pom.xml
  • samples/personal-assistant/src/main/java/org/atmosphere/samples/personalassistant/PrimaryAssistant.java
  • samples/personal-assistant/src/main/java/org/atmosphere/samples/personalassistant/SchedulerAgent.java
  • samples/personal-assistant/src/main/java/org/atmosphere/samples/personalassistant/ResearchAgent.java
  • samples/personal-assistant/src/main/java/org/atmosphere/samples/personalassistant/DrafterAgent.java
  • samples/personal-assistant/src/main/java/org/atmosphere/samples/personalassistant/Application.java
  • samples/personal-assistant/.agent-workspace/AGENTS.md
  • samples/personal-assistant/.agent-workspace/SOUL.md
  • samples/personal-assistant/.agent-workspace/USER.md
  • samples/personal-assistant/.agent-workspace/IDENTITY.md
  • samples/personal-assistant/.agent-workspace/MEMORY.md (example seed)
  • samples/personal-assistant/.agent-workspace/skills/README.md
  • samples/personal-assistant/.agent-workspace/atmosphere/CHANNELS.md
  • samples/personal-assistant/.agent-workspace/atmosphere/MCP.md
  • samples/personal-assistant/.agent-workspace/atmosphere/PERMISSIONS.md
  • samples/personal-assistant/README.md

Default runtime: Spring AI. Flag --runtime=<name> switches to any of the other six.

Demo flow (documented in README):

  1. Run with Spring AI, have a conversation with the primary assistant.
  2. The assistant asks the user's name, remembers it.
  3. User asks the assistant to schedule a meeting → SchedulerAgent crew member fires via InMemoryProtocolBridge.
  4. Restart on LangChain4j → conversation history + user name preserved.
  5. Switch channel to Slack → same session, same memory.
  6. User inspects memory via admin control plane.

Proof sample #2 — samples/coding-agent/ (~2 h)

Exercises: Sandbox, AgentResumeHandle, plus inherits everything from sample #1 through the shared foundation.

Files:

  • samples/coding-agent/pom.xml
  • samples/coding-agent/src/main/java/org/atmosphere/samples/codingagent/CodingAgent.java
  • samples/coding-agent/src/main/java/org/atmosphere/samples/codingagent/RepoCloneTool.java — @SandboxTool
  • samples/coding-agent/src/main/java/org/atmosphere/samples/codingagent/FileReadTool.java — @SandboxTool
  • samples/coding-agent/src/main/java/org/atmosphere/samples/codingagent/PatchProposeTool.java — @SandboxTool
  • samples/coding-agent/src/main/java/org/atmosphere/samples/codingagent/GitCommitTool.java — @SandboxTool
  • samples/coding-agent/src/main/java/org/atmosphere/samples/codingagent/Application.java
  • samples/coding-agent/.agent-workspace/AGENTS.md (instructions for code tasks)
  • samples/coding-agent/README.md

Demo flow:

  1. Run the coding agent, ask it to clone a small public repo (e.g., a "hello world" project).
  2. Sandbox spawns a Docker container, repo clones, files are readable.
  3. User asks the agent to fix a specific typo in a file.
  4. Disconnect mid-patch (kill the client).
  5. Reconnect with the same runId → AgentResumeHandle reattaches, patch proposal continues.
  6. Agent proposes the patch as a diff.
  7. User approves via PermissionMode.PLAN flow.
  8. Agent commits and the sandbox preserves the change.

Phase 3 — Documentation (~3–4 h total)

Two documentation surfaces. Both must be updated before release.

In-repo /docs and AGENTS.md (~1 h)

  • Update AGENTS.md top-level to reference the eight primitives and two samples.
  • Update modules/ai/README.md with the new primitives: AgentState, AgentWorkspace, AgentIdentity, ToolExtensibilityPoint, AiGateway, AgentResumeHandle.
  • Update modules/sandbox/README.md (new module).
  • Update modules/coordinator/README.md to surface the existing ResultEvaluator SPI + LlmResultEvaluator + SanityCheckEvaluator prominently under a new "Evaluation" section (this machinery exists and is under-documented, not missing).
  • Update samples/README.md to add the two new samples.
  • Update module READMEs wherever the primitive touches: modules/admin/README.md, modules/durable-sessions/README.md.
  • Update CHANGELOG.md — per feedback_no_fabricated_stats.md, every bullet must correspond to a real commit with a reachable hash. Compose after implementation, not before.

Sibling atmosphere.github.io repo (~2–3 h)

The site is Astro/Starlight under docs/ and the marketing site under website/. Per reference_atmosphere_github_io.md, updates there are release-gating. All edits confirmed with ChefFamille before we switch to the sibling repo.

docs/src/content/docs/reference/ updates:

  • ai.md — add sections for each of the eight primitives with SPI signatures + contract test commands.
  • agents/ — expand agents subdirectory with workspace / state / identity reference pages.
  • evaluation.md — new page documenting the existing LlmJudge / ResultEvaluator / LlmResultEvaluator / SanityCheckEvaluator surface with example code paths for online (async-journaled) and offline (explicit AgentFleet.evaluate()) modes.

docs/src/content/docs/tutorial/ updates:

  • Add personal-assistant.md tutorial walking through sample #1.
  • Add coding-agent.md tutorial walking through sample #2.
  • Add openclaw-workspace.md tutorial explaining zero-config OpenClaw compatibility.

docs/src/content/docs/architecture.md — add a section on the eight primitives + the Atmosphere 1.0 analogy (foundation, not product). Update the architecture diagram if any exists.

website/ — no public announcement yet (under-the-radar cadence per v0.5). Marketing site stays as-is until the quiet tease window.

Documentation discipline

  • Every factual claim maps to source in the worktree OR a real git commit hash (per feedback_no_fabricated_stats.md).
  • No invented API signatures — every signature block is copy-pasted from the real source.
  • No "best-in-class" / "most sophisticated" superlatives — the v2-gist failure mode is banned.
  • Every number is verified (sample count, primitive count, runtime count).

Phase 4 — Testing (~5 h total)

Six test surfaces. Each one gates release.

4.1 Unit tests (inline with each primitive, ~baked into the 12 h estimate)

Per-primitive unit tests using JUnit 5. Already scoped inside each primitive's implementation time.

4.2 Contract tests across all seven runtimes (~baked into the 12 h estimate)

Each primitive ships its own contract test extending the existing pattern (AbstractAgentRuntimeContractTest.expectedCapabilities() discipline). No primitive is done until seven green runs in CI.

4.3 Integration tests (~30 min incremental)

modules/integration-tests/ gains new test classes for the foundation primitives + the two samples' happy paths. Runs as part of ./mvnw install.

4.4 Playwright E2E tests (~2 h)

New: modules/playwright-e2e/ (or equivalent scaffolded under the CI lane). Tests run against the sample apps via a real browser.

Test targets:

  • Admin control plane UI (modules/quarkus-admin-extension/runtime/src/main/resources/META-INF/resources/admin/index.html) — user can browse memory, edit a memory entry, delete a memory entry, view audit log, share a session read-only, view the trace timeline, view the eval results tab.
  • Personal assistant sample web UI — full conversation flow, memory recall after restart, channel switch.
  • Coding agent sample web UI — submit a task, see sandbox provision, view patch proposal, approve via PLAN mode.

Flow:

  • playwright.config.ts — target base URL http://localhost:8080 (default Spring Boot port).
  • tests/admin.spec.ts — admin UI smoke.
  • tests/personal-assistant.spec.ts — sample #1 happy path.
  • tests/coding-agent.spec.ts — sample #2 happy path.
  • CI lane: spin up each sample, run Playwright against it, teardown.

4.5 OpenClaw compatibility tests (~1 h)

New: modules/ai-test/src/test/java/org/atmosphere/ai/test/OpenClawCompatTest.java.

Approach:

  • Check in a known-good OpenClaw workspace fixture under modules/ai-test/src/test/resources/fixtures/openclaw/ — realistic AGENTS.md + SOUL.md + USER.md + IDENTITY.md + MEMORY.md + memory/*.md + skills/*/SKILL.md + JSONL sessions.
  • Point Atmosphere at the fixture via OpenClawWorkspaceAdapter.
  • Assert:
    • System prompt assembled from AGENTS.md + SOUL.md + USER.md + IDENTITY.md matches expected.
    • MEMORY.md facts load as AgentState.getFacts().
    • memory/YYYY-MM-DD.md loads as daily notes.
    • Skills load via the precedence chain.
    • JSONL session transcripts load as AgentState.getConversation().
  • Run on all seven runtimes — same fixture, seven runtime configs, identical behavior.

Stretch: pull a real OpenClaw repo workspace via gh api in CI and run the compat test against it. Reject the build if OpenClaw upgrades a field Atmosphere can't parse.

4.6 Chrome DevTools MCP final validation (~1 h)

Purpose: browser-driven full-stack validation that the documentation matches what the user actually sees. Tests the integration surface, not the unit surface.

Tooling: Use the mcp__chrome-devtools__* tools already available in this Claude session to:

  • Launch the personal assistant sample and the coding agent sample in separate browser pages.
  • Drive the UI exactly as the documentation describes (step-by-step from the tutorial pages).
  • Monitor console for unexpected errors (mcp__chrome-devtools__list_console_messages).
  • Capture network requests (mcp__chrome-devtools__list_network_requests) — assert every documented endpoint is actually called, actually returns 200 with the documented shape.
  • Take screenshots (mcp__chrome-devtools__take_screenshot) for each tutorial step — check they match the written doc. Screenshots go into the sibling atmosphere.github.io/docs/src/assets/ for publication.
  • Run a Lighthouse audit on each sample (mcp__chrome-devtools__lighthouse_audit) — admin UI + both samples should score ≥ 90 on accessibility and performance.
  • Final acceptance: the ChefFamille demo flow runs end-to-end in a real browser with zero console errors.

Exit criteria: all three UI flows (admin, sample #1, sample #2) complete without any red events.

Explicit v0.5 non-goals (scope discipline)

These are NOT deferred to a future version — they are explicit non-goals for v0.5. If they prove valuable later, they become their own plan, not a backlog promise.

  • Eval dataset abstraction (EvalDataset record or similar). Users compose List<AgentCall> explicitly. No new type.
  • Eval run / regression tracking across time. Coordination journal logs individual runs; framework-level regression tooling is LangSmith product territory, not Atmosphere foundation.
  • Human feedback calibration / annotation UI. LangSmith product feature, not a foundation primitive.
  • Dedicated eval CLI commands (atmosphere eval run <dataset> etc.). Users invoke AgentFleet.evaluate() via code.

Phase 5 — Release prep (~1 h)

  1. Zero-warning compile: ./mvnw compile at worktree root. No new @SuppressWarnings except explicitly justified.
  2. Checkstyle + PMD: ./mvnw checkstyle:checkstyle pmd:check. Must pass across all touched modules.
  3. Full build: ./mvnw install. Must be green.
  4. Pre-push validation: ./scripts/pre-push-validate.sh. Required before any push.
  5. Cancel stale CI runs: gh run list --branch feat/ai-agent-foundation --json databaseId,status -q '.[] | select(.status == "queued" or .status == "in_progress") | .databaseId' | xargs -I{} gh run cancel {} before the push lands.
  6. Commit strategy: one commit per primitive + one per sample + one for docs + one for tests. Conventional-commit prefixes (feat(ai), feat(sandbox), docs, test). No AI attribution trailers ever (per CLAUDE.md and feedback_commit_messages.md).
  7. PR stays open for review: ChefFamille approves before merge. No auto-merge.
  8. Release timing: nothing public until the full six-primitive test matrix is green on main. Per v0.5 under-the-radar cadence.

Risk register

# Risk Probability Mitigation
1 ProtocolBridge rename breaks existing MCP / A2A / AG-UI consumers Medium Thin delegation layer for old symbols during the migration commit; deprecate-and-delete in a follow-up release
2 ADK latent capability lie fix reveals deeper integration bug Low–Medium Keep the fix scoped; if it expands, extract to a separate commit with its own regression test
3 OpenClaw canonical spec changes during implementation Low Pin the fixture to a specific OpenClaw tag; document the pin; upgrade deliberately
4 Docker sandbox fails in CI where no Docker daemon is available High Skip the sandbox contract test when DOCKER_HOST is unreachable; CI runner configured with Docker service
5 AgentResumeHandle event replay buffer interacts badly with BroadcasterCache Medium If reuse doesn't work cleanly, ship a dedicated buffer — don't force the fit
6 Playwright tests flake on CI due to timing Medium Use explicit waitFor assertions everywhere; no sleep calls; per feedback_no_flaky_tests.md — if a test flakes, fix the test, don't quarantine
7 Sibling atmosphere.github.io repo is release-gating but might be out of sync Low Before any docs commit, cd ../atmosphere.github.io && git pull && git status — confirm clean working tree, then edit
8 The javap worry from v0.3 resurfaces for some runtime we missed Low The Action 1 verification already covered all seven; if it surfaces, the fix is one-runtime-at-a-time and we stay honest via contract tests
9 Total time blows past the 24 h estimate Medium Commit after each primitive so we never lose progress; split into three 8-hour sessions rather than one marathon

Open questions

These need ChefFamille's call before we start code:

  1. Sandbox default resource limits — what CPU / memory / wall-time per sandbox by default? My lean: 1 CPU · 512 MB · 5 min wall-time · no network by default. User overrides in .agent/atmosphere/SANDBOX.md or equivalent.
  2. @SandboxTool semantics when no Docker — fail hard or fall back to in-JVM execution with a warning? My lean: fail hard. Non-deterministic backend swap is a footgun.
  3. Per-user credential store encryption — what cipher / KDF for AtmosphereEncryptedCredentialStore? My lean: AES-GCM with an OS-level keychain-derived key, no plaintext fallback.
  4. Read-only session share token TTL — default how long? My lean: 24 hours, admin can revoke earlier.
  5. Chrome DevTools validation on CI — is the MCP tool set available in CI runners, or is this only a local-dev validation step? If CI-only, we document the acceptance test as a manual gate per release. My lean: manual gate, documented, performed by release engineer (ChefFamille).

Next steps

Once ChefFamille approves this plan:

  1. Clean up stale TODOs (session memory).
  2. Warm the Maven cache in the worktree per Phase 0.
  3. Start Primitive 1 (AgentState) with the five-step cycle.
  4. Report at each primitive completion; ChefFamille can re-prioritize or adjust between primitives.

No code runs before plan approval. No code runs on the main worktree — everything happens in .claude/worktrees/ai-agent-foundation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment