Implementation Roadmap

Prioritized phases for Avalanche AI. Each phase states its outcome, the packages it touches, its exit criteria, and what it deliberately leaves out. The ordering is by dependency and risk: identity and policy before tools, tools before write execution, execution before the dashboard.

Phase 0 — Foundation and upstream audit ✅

Outcome. The fork exists, tracks upstream, builds in-tree, and every architectural decision is grounded in the actual source.

Delivered.

• upstream and origin remotes; upstream master baseline preserved in the fork.
• Full upstream audit: workspace layout, plugin conventions, profile/bundle system, agent loop, tool pipeline, prompt assembly, CLI boot, build constraints.
• This document set: UPSTREAM_AUDIT.md, ARCHITECTURE.md, FORK_STRATEGY.md, IMPLEMENTATION_ROADMAP.md, SECURITY_THREAT_MODEL.md, TESTING_STRATEGY.md.
• Package skeleton: 19 packages with manifests, tsconfig references, and generated path aliases.
• PROFILE_TEMPLATES.avalanche registered.

Exit criteria. pnpm install and pnpm run gen-tsconfig-paths succeed; every avalanche package resolves from source; no upstream package modified except the one-entry template registration.

Phase 1 — Shared runtime vertical slice ✅

Outcome. A working vertical slice: the harness starts, the avalanche profile loads, all seven domains register, the orchestrator picks an agent, a read-only tool call is recorded, and the task is inspectable via API and CLI, with tests.

Delivered.

• Shared services: avalanche-context, avalanche-memory, avalanche-policy, avalanche-verification, avalanche-evidence, avalanche-tooling, avalanche-network, avalanche-agents.
• Seven domain descriptor packages.
• avalanche-orchestrator: full intent → policy → plan → tool execution → verification → receipt lifecycle, durable task records, cancellation.
• avalanche-network: read-only JSON-RPC allowlist, five read tools, injectable transport, chain-id verifier.
• avalanche-cli: doctor, agent list|describe, network list, task create|inspect|list|cancel, evidence list|verify, receipt list|inspect, global --json.
• avalanche-app: one cordis.patch.yml mounting everything over dsh-base.
• Tests: 10 spec files, 93 tests, including a real Loader composition test that boots the shipped patch.

Exit criteria met. pnpm exec vitest run packages/avalanche → 10 files / 93 tests pass. The Loader test mounts every shipped row, routes a task to the developer domain, executes a real avalanche_chain_status call through a stub RPC transport, asserts the receipt cites the executor-recorded tool call, and re-reads the task and evidence chain from disk in a second and third boot.

Known limits carried forward. No write path, no signing, no dashboard, no MCP integration. Memory is lexical; persistence is file-based.

Phase 2 — Documentation and knowledge surfaces

Outcome. Domains can answer from Avalanche documentation with citations, and the runtime distinguishes documentation facts from chain facts.

Scope.

• Optional @deepseek-ai/dsh-mcp-client row for https://build.avax.network/api/mcp, mounted disabled by default and enabled by a profile overlay.
• Catalog every MCP tool through avalancheTooling.register with an explicit risk profile (chain:read for platform_*/info_* reads, no permissions for docs lookup).
• A docs retrieval package around the MCP client that records source on every returned chunk.
• Extend the evidence payload with a source discriminator (chain-observed, documentation, agent-inference).

Exit criteria. A documentation question routes to a domain, returns cited excerpts, and the task record shows documentation origin; a chain question still goes through the network registry. MCP outage degrades to an explicit unavailable result, never to model invention.

Phase 3 — Policy-hardened write preparation

Outcome. The runtime can prepare state-changing actions without executing them: transaction building, simulation against a fork, approval binding, and human-readable diffs.

Scope.

• tx:prepare tools that build unsigned transactions from explicit intent; no key material accepted.
• Foundry-based fork simulation tool behind chain:simulate; result recorded as simulation evidence and attached to the receipt.
• Approval workflow: task parks at awaiting-approval, operator inspects the simulation and the exact fingerprint, grant() resumes or decide() rejects; single-use consumption enforced.
• CLI: task approve <id>, task reject <id>, task resume <id>; receipt inspect shows the approval and simulation blocks.

Exit criteria. A Fuji-fork simulation produces a recorded diff; approval cannot be reused; a rejected approval leaves the task failed with the approval record cited. No transaction is broadcast anywhere.

Phase 4 — Dashboard

Outcome. Vite + React + TypeScript operator console over the same services and API.

Scope.

• New packages/avalanche/avalanche-dashboard client package (Vite + React, no Next.js) and a dsh --profile avalanche-web composition or a web-enabled avalanche overlay.
• Views: domains, network status, task timeline (intent → policy → plan → tools → verification → receipt), evidence browser with chain-verify action, receipt inspector, approval queue.
• Every view reads from the service layer through the API; no business logic in the client.

Exit criteria. Real browser test (Playwright) against the composed profile: create a task, watch it reach succeeded, open the receipt, verify the evidence chain, and see a tampered ledger rejected.

Phase 5 — Guarded write execution

Outcome. Approved transactions can be signed and submitted on Fuji only, with chain evidence.

Scope.

• Rust signer/verifier behind a narrow service contract; keys never enter LLM context, never appear in a task record, and are read from an operator-controlled environment or OS keystore.
• Submission tool gated by chain:write + approval + Fuji environment; mainnet remains globally denied.
• Post-submission verification: receipt hash, block inclusion, status; all from chain observation.
• Rollback/abort playbook and incident evidence bundle.

Exit criteria. End-to-end Fuji test: approved transfer broadcasts, receipt cites transaction hash and inclusion evidence, mainnet attempt denied at policy, key never serialized.

Phase 6 — Analytics and memory depth

Outcome. Data domain gains real analytics; memory gains semantic recall.

Scope.

• Python analytics worker for chain metrics (offline computation over recorded data; no direct chain writes).
• Vector search over memory and documentation with origin retained.
• PostgreSQL for durable task/evidence indexing when file-based storage hits its limits; Redis only if a measured latency need exists.

Exit criteria. Analytics results carry source and computation metadata; semantic recall returns origin; storage migration preserves hash-chain verification.

Phase 7 — Hardening and release

Outcome. Release candidate with external security review, operational runbooks, and full gate compliance.

Scope.

• Threat-model review against SECURITY_THREAT_MODEL.md, pen-test of the approval and evidence paths.
• Upstream sync rehearsal; conflict playbook.
• README, package READMEs, generated catalogs, translation pairs, coverage gates.

Exit criteria. All repo gates green on the fork; documented upgrade path from upstream; signed release notes.

Sequencing rules

• No phase skips the policy gate: every new tool is catalogued with a risk profile before it registers.
• No phase introduces a second runtime: new capabilities are packages and rows in the same composition.
• No phase exposes keys to the model: the signer is a service call, not a tool argument.
• Evidence format changes are versioned and backward-readable; receipts never lose verifiability.