Zaxy v0.5 Public Positioning and First-Run Trust Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Ship v0.5 as a repo-grounded public-positioning and first-run trust release.

Architecture: Keep Eventloom, embedded Kuzu, Memory Checkout, MCP, and Coordinate as the existing architecture. This release aligns public messaging, validates first-run onboarding, polishes examples, and hardens MCP discovery without broad feature expansion.

Tech Stack: Python 3.11+, Typer CLI, MCP Python SDK, pytest, ruff, mypy, Markdown docs, static site builder.

---

Current Constraints

File Structure

Task 1: Package Metadata and Public Positioning

Files:

Add this test to tests/test_packaging.py:

def test_package_metadata_centers_coordinator_memory() -> None:
    """Package discovery metadata should match the v0.5 public positioning."""
    pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))

    assert pyproject["project"]["description"] == (
        "Coordinator memory for auditable multi-agent projects"
    )
    keywords = pyproject["project"]["keywords"]
    assert "coordinator-memory" in keywords
    assert "multi-agent" in keywords
    assert "auditable-memory" in keywords

Create tests/test_v05_positioning.py:

"""Tests for v0.5 public positioning and release-gate docs."""

from __future__ import annotations

from pathlib import Path


def test_readme_leads_with_coordinator_memory_positioning() -> None:
    """README should lead with the v0.5 ownable product thesis."""
    text = Path("README.md").read_text(encoding="utf-8")

    assert text.startswith("# Zaxy\n\n**Coordinator Memory for Agent Teams.**")
    assert "auditable, replayable, and coordinated memory" in text
    assert "Eventloom append-only source of truth" in text
    assert "embedded Kuzu graph projection" in text
    assert "temporal knowledge graph fabric" not in text.splitlines()[3]


def test_why_zaxy_states_coordinator_memory_thesis() -> None:
    """Why Zaxy should explain the product thesis before architecture."""
    text = Path("docs/why-zaxy.md").read_text(encoding="utf-8")

    assert "Coordinator Memory for Agent Teams" in text
    assert "worker-local findings" in text
    assert "accepted parent mission state" in text
    assert "vector search alone cannot audit" in text

Run:

pytest tests/test_packaging.py::test_package_metadata_centers_coordinator_memory \
  tests/test_v05_positioning.py::test_readme_leads_with_coordinator_memory_positioning \
  tests/test_v05_positioning.py::test_why_zaxy_states_coordinator_memory_thesis -q

Expected: fail because the package description, README headline, and Why Zaxy thesis still use older wording.

In pyproject.toml, change:

description = "Event-sourced temporal knowledge graph fabric for AI agent memory"

to:

description = "Coordinator memory for auditable multi-agent projects"

Add these keywords to the existing list without removing embedded/runtime terms:

"auditable-memory",
"coordinator-memory",
"multi-agent",

In README.md, change the headline and opening paragraph to:

# Zaxy

**Coordinator Memory for Agent Teams.**

Zaxy gives agent teams auditable, replayable, and coordinated memory: parent
missions, isolated worker sessions, cited findings, conflict review, approval
packets, and accepted merge-back into one durable project history. Under the
hood, it uses an Eventloom append-only source of truth and an embedded Kuzu graph
projection instead of flattening project memory into markdown files and vector
chunks.

In docs/why-zaxy.md, add or replace the opening thesis with:

Zaxy is **Coordinator Memory for Agent Teams**. It keeps worker-local findings
separate from accepted parent mission state, preserves citations and replayable
history, and makes conflicts reviewable before they contaminate shared project
memory. Vector search alone cannot audit who claimed what, when it was accepted,
or which evidence supported the decision.

Run:

pytest tests/test_packaging.py::test_package_metadata_centers_coordinator_memory \
  tests/test_v05_positioning.py::test_readme_leads_with_coordinator_memory_positioning \
  tests/test_v05_positioning.py::test_why_zaxy_states_coordinator_memory_thesis -q

Expected: pass.

git add pyproject.toml README.md docs/why-zaxy.md tests/test_packaging.py tests/test_v05_positioning.py
git commit -m "docs: center v0.5 coordinator memory positioning"

Task 2: First-Run Documentation and Validation Checklist

Files:

Append to tests/test_v05_positioning.py:

def test_getting_started_documents_five_minute_first_run() -> None:
    """Getting started should provide the measured v0.5 first-run path."""
    text = Path("docs/getting-started.md").read_text(encoding="utf-8")

    assert "Five-minute first run" in text
    assert "pipx install zaxy-memory" in text
    assert "zaxy init" in text
    assert "zaxy memory bootstrap --eventloom-path .eventloom" in text
    assert "zaxy memory checkout" in text
    assert "zaxy doctor --eventloom-path .eventloom" in text
    assert "No Neo4j, Postgres, Docker, or graph password is required" in text


def test_first_run_validation_template_exists() -> None:
    """External validation should have a concrete reporting template."""
    text = Path("docs/first-run-validation.md").read_text(encoding="utf-8")

    assert "# First-Run Validation" in text
    assert "Time to successful `zaxy doctor`" in text
    assert "Where did you get stuck?" in text
    assert "Operating system" in text
    assert "Python version" in text

Run:

pytest tests/test_v05_positioning.py::test_getting_started_documents_five_minute_first_run \
  tests/test_v05_positioning.py::test_first_run_validation_template_exists -q

Expected: fail because docs/first-run-validation.md does not exist and getting-started lacks the exact v0.5 path.

Add a section near the top:

## Five-minute first run

The default local path is embedded and repo-local. No Neo4j, Postgres, Docker,
or graph password is required for the first run.

pipx install zaxy-memory zaxy init zaxy memory bootstrap --eventloom-path .eventloom zaxy memory checkout "current project memory and next useful action" --eventloom-path .eventloom zaxy doctor --eventloom-path .eventloom


Success means:

- `.eventloom/` exists;
- `zaxy memory bootstrap` returns model-facing guidance;
- `zaxy memory checkout` returns a prompt-ready checkout with diagnostics;
- `zaxy doctor` reports no blocking local setup errors.

Use this content:

# First-Run Validation

Use this checklist with someone who has not worked on Zaxy before. The goal is
to verify that a normal local developer can install, initialize, inspect memory,
and run one example in less than five minutes.

## Commands

pipx install zaxy-memory zaxy init zaxy memory bootstrap --eventloom-path .eventloom zaxy memory checkout "current project memory and next useful action" --eventloom-path .eventloom zaxy doctor --eventloom-path .eventloom python examples/single_agent_memory.py


## Report

- Operating system:
- Shell:
- Python version:
- Install method:
- Time to successful `zaxy doctor`:
- Time to first successful example:
- Did any command require Docker, Neo4j, Postgres, or a graph password?
- Where did you get stuck?
- Which error message was least useful?
- What should the quick start say differently?

In the README docs list, add:

- First-run validation: `docs/first-run-validation.md`

Run:

pytest tests/test_v05_positioning.py -q

Expected: pass.

git add README.md docs/getting-started.md docs/first-run-validation.md tests/test_v05_positioning.py
git commit -m "docs: add v0.5 first-run validation path"

Task 3: MCP and Coordinate Quickstarts

Files:

Append to tests/test_v05_positioning.py:

def test_mcp_quickstart_names_recommended_local_clients() -> None:
    """MCP quickstart should route users through one clear local path per client."""
    text = Path("docs/mcp-quickstart.md").read_text(encoding="utf-8")

    assert "# MCP Quickstart" in text
    assert "zaxy init" in text
    assert "codex mcp add" in text
    assert "Claude Desktop" in text
    assert "Cursor" in text
    assert "memory_bootstrap" in text
    assert "memory_checkout" in text


def test_coordinate_quickstart_has_full_review_workflow() -> None:
    """Coordinate quickstart should show the whole accepted-state workflow."""
    text = Path("docs/coordinate-quickstart.md").read_text(encoding="utf-8")

    for command in (
        "zaxy coordinate start",
        "zaxy coordinate worker create",
        "zaxy coordinate assign",
        "zaxy coordinate report",
        "zaxy coordinate brief",
        "zaxy coordinate decide",
        "zaxy coordinate promote",
        "zaxy coordinate checkout",
        "zaxy coordinate handoff",
    ):
        assert command in text
    assert "worker-local findings are not trusted parent state" in text

Run:

pytest tests/test_v05_positioning.py::test_mcp_quickstart_names_recommended_local_clients \
  tests/test_v05_positioning.py::test_coordinate_quickstart_has_full_review_workflow -q

Expected: fail because the quickstart docs do not exist.

Use concise content:

# MCP Quickstart

MCP is Zaxy's primary framework-neutral interface. Start with the default local
path:

zaxy init zaxy memory bootstrap --eventloom-path .eventloom


For Codex, copy or run the `codex mcp add` command printed by `zaxy init`.

For Claude Desktop:

zaxy ide-config claude-desktop --eventloom-path .eventloom


For Cursor:

zaxy ide-config cursor --eventloom-path .eventloom


At session start, call `memory_bootstrap`. Before substantial work, call
`memory_checkout` with the current task. After using projected context, call
`memory_feedback` so Zaxy can reinforce useful memory.

Use concise content:

# Coordinate Quickstart

Coordinate keeps worker-local exploration separate from trusted parent mission
state. Worker-local findings are not trusted parent state until the coordinator
reviews and promotes them.

zaxy coordinate start "Ship auth refactor" --mission auth-main zaxy coordinate worker create --mission auth-main --worker auth-api zaxy coordinate assign --mission auth-main --worker auth-api "Trace API auth failures" zaxy coordinate report --mission auth-main --worker auth-api \ --summary "API failures trace to expired JWKS cache handling" \ --evidence "src/auth/jwks.py:42" \ --claim-key auth.failure.cause \ --claim-value expired-jwks-cache zaxy coordinate brief --mission auth-main FINDING_ID="$(python - <<'PY' from pathlib import Path from zaxy.coordination import CoordinationManager brief = CoordinationManager(eventloom_path=Path('.eventloom')).brief('auth-main') print(brief.findings[0].finding_id) PY )" zaxy coordinate decide --mission auth-main --finding "$FINDING_ID" --status accepted zaxy coordinate promote --mission auth-main --finding "$FINDING_ID" zaxy coordinate checkout --mission auth-main zaxy coordinate handoff --mission auth-main --summary "Accepted auth finding promoted."


Use `zaxy coordinate approval-packet` when a remote reviewer needs to inspect
pending or conflicted findings before promotion.

In docs/mcp.md, add near the top:

For a concise local setup path, see MCP Quickstart (`mcp-quickstart.md`).

In docs/coordinate-roadmap.md, add near the top:

For the shortest working workflow, see Coordinate Quickstart (`coordinate-quickstart.md`).

In README.md, add the docs links:

- MCP quickstart: `docs/mcp-quickstart.md`
- Coordinate quickstart: `docs/coordinate-quickstart.md`

Run:

pytest tests/test_v05_positioning.py -q

Expected: pass.

git add README.md docs/mcp.md docs/mcp-quickstart.md docs/coordinate-roadmap.md docs/coordinate-quickstart.md tests/test_v05_positioning.py
git commit -m "docs: add v0.5 MCP and Coordinate quickstarts"

Task 4: Single-Agent Example

Files:

Create tests/test_examples_v05.py:

"""Smoke tests for v0.5 public examples."""

from __future__ import annotations

import json
import subprocess
import sys
from pathlib import Path


def test_single_agent_memory_example_runs() -> None:
    """Single-agent example should run without sidecars and print JSON evidence."""
    result = subprocess.run(
        [sys.executable, "examples/single_agent_memory.py"],
        check=False,
        capture_output=True,
        text=True,
    )

    assert result.returncode == 0, result.stderr
    payload = json.loads(result.stdout)
    assert payload["session_id"] == "single-agent-demo"
    assert payload["bootstrap"]["session_id"] == "single-agent-demo"
    assert payload["checkout"]["session_id"] == "single-agent-demo"
    assert payload["event_count"] >= 2

Run:

pytest tests/test_examples_v05.py::test_single_agent_memory_example_runs -q

Expected: fail because examples/single_agent_memory.py does not exist.

Use this script:

"""Single-agent durable memory example.

Run:
    python examples/single_agent_memory.py
"""

from __future__ import annotations

import asyncio
import json
import tempfile
from pathlib import Path

from zaxy import MemoryFabric
from zaxy.capabilities import build_memory_bootstrap


async def run_example(eventloom_path: Path) -> dict[str, object]:
    session_id = "single-agent-demo"
    fabric = MemoryFabric(eventloom_path)
    try:
        await fabric.append(
            "decision.recorded",
            actor="user",
            payload={
                "decision": "Use Memory Checkout before major project work.",
                "topic": "memory activation",
            },
            session_id=session_id,
        )
        await fabric.after_turn(
            role="assistant",
            content="I will call Memory Checkout before roadmap and implementation work.",
            session_id=session_id,
            query="memory activation policy",
            source="example",
        )
        checkout = await fabric.checkout_memory(
            "What should the agent do before major project work?",
            session_id=session_id,
            limit=5,
            max_recent_events=10,
        )
    finally:
        await fabric.close()

    bootstrap = build_memory_bootstrap(
        session_id=session_id,
        current_task="single-agent durable memory demo",
        eventloom_path=eventloom_path,
        workspace_root=Path("."),
        activity="bootstrap",
    )
    event_count = len(list(eventloom_path.glob("*.jsonl")))
    return {
        "session_id": session_id,
        "bootstrap": {
            "session_id": bootstrap["session_id"],
            "recommended_tool": bootstrap["recommended_tool"],
        },
        "checkout": {
            "session_id": checkout.session_id,
            "query": checkout.query,
            "quality": checkout.quality,
            "warning_count": len(checkout.warnings),
        },
        "event_count": event_count,
    }


def main() -> None:
    with tempfile.TemporaryDirectory(prefix="zaxy-single-agent-") as tmp:
        payload = asyncio.run(run_example(Path(tmp) / ".eventloom"))
    print(json.dumps(payload, indent=2, sort_keys=True))


if __name__ == "__main__":
    main()

Add under quick start or examples:

Run the single-agent memory example:

python examples/single_agent_memory.py

Run:

pytest tests/test_examples_v05.py::test_single_agent_memory_example_runs -q

Expected: pass.

git add README.md examples/single_agent_memory.py tests/test_examples_v05.py
git commit -m "docs: add single-agent memory example"

Task 5: LangGraph and Coordinate Example Smoke Coverage

Files:

Append to tests/test_examples_v05.py:

def test_coordinate_three_worker_example_runs() -> None:
    """Coordinate example should produce a complete mission summary."""
    result = subprocess.run(
        [sys.executable, "examples/coordinate_three_worker_project.py"],
        check=False,
        capture_output=True,
        text=True,
    )

    assert result.returncode == 0, result.stderr
    payload = json.loads(result.stdout)
    assert payload["mission_id"] == "auth-main"
    assert payload["worker_count"] == 3
    assert payload["accepted_count"] >= 1
    assert payload["handoff_id"]


def test_langgraph_example_runs_without_langgraph_dependency() -> None:
    """LangGraph example should smoke-test the dependency-light adapter."""
    result = subprocess.run(
        [sys.executable, "examples/langgraph_memory.py"],
        check=False,
        capture_output=True,
        text=True,
    )

    assert result.returncode == 0, result.stderr
    payload = json.loads(result.stdout)
    assert payload["session_id"] == "langgraph-demo"
    assert payload["has_zaxy_context"] is True
    assert payload["kind"] in {"memory_checkout", "context_assembly"}

Run:

pytest tests/test_examples_v05.py::test_coordinate_three_worker_example_runs \
  tests/test_examples_v05.py::test_langgraph_example_runs_without_langgraph_dependency -q

Expected: one or both may fail if output is not JSON or keys differ.

For examples/coordinate_three_worker_project.py, ensure main() prints only JSON to stdout:

print(json.dumps(run_demo(), indent=2, sort_keys=True))

Ensure the returned payload includes:

{
    "mission_id": brief.mission_id,
    "worker_count": len(brief.workers),
    "accepted_count": len(checkout.accepted_findings),
    "conflict_count": len(brief.conflicts),
    "handoff_id": handoff.handoff_id,
}

For examples/langgraph_memory.py, add or update main() so it runs the dependency-light node and prints:

{
    "session_id": "langgraph-demo",
    "has_zaxy_context": bool(state.get("zaxy_context")),
    "kind": state.get("zaxy", {}).get("kind", "context_assembly"),
}

In docs/integrations.md, add a short v0.5 runnable example note:

Smoke the dependency-light LangGraph path without installing LangGraph:

python examples/langgraph_memory.py

Run:

pytest tests/test_examples_v05.py -q

Expected: pass.

git add docs/integrations.md examples/langgraph_memory.py examples/coordinate_three_worker_project.py tests/test_examples_v05.py
git commit -m "test: smoke v0.5 public examples"

Task 6: MCP Tool Description Polish

Files:

Add to tests/test_mcp.py inside TestToolSchema:

    def test_v05_tool_descriptions_are_model_actionable(self) -> None:
        """Core MCP tools should describe when a model should call them."""
        descriptions = {tool.name: tool.description for tool in TOOLS}

        assert "session start" in descriptions["memory_bootstrap"].lower()
        assert "before substantial work" in descriptions["memory_checkout"].lower()
        assert "after using retrieved context" in descriptions["memory_feedback"].lower()
        assert "worker-local" in descriptions["coordination_report_finding"].lower()
        assert "accepted coordination state" in descriptions["coordination_checkout"].lower()
        assert "remote reviewer" in descriptions["coordination_approval_packet"].lower()

Run:

pytest tests/test_mcp.py::TestToolSchema::test_v05_tool_descriptions_are_model_actionable -q

Expected: fail because current descriptions are terse.

In src/zaxy/mcp_server.py, update these Tool(description=...) strings:

description="At session start, return compact Zaxy memory guidance and the recommended first checkout call.",

for memory_bootstrap.

description="Before substantial work, checkout current, cited, prompt-ready memory state for a session.",

for memory_checkout.

description="After using retrieved context, record whether a memory item was useful, stale, corrected, or reinforced.",

for memory_feedback.

description="Record a worker-local coordination finding with evidence; it is not trusted parent state until reviewed and promoted.",

for coordination_report_finding.

description="Return accepted coordination state for prompt injection, with optional diagnostics for pending or conflicted findings.",

for coordination_checkout.

description="Return a portable pending/conflicted finding packet for a remote reviewer.",

for coordination_approval_packet.

In docs/mcp.md, add a "Model call rhythm" section:

## Model Call Rhythm

Use Zaxy tools in this order:

1. At session start, call `memory_bootstrap`.
2. Before substantial work, call `memory_checkout`.
3. For multi-agent missions, use Coordinate tools to record worker-local findings and promote only accepted state.
4. After using retrieved context, call `memory_feedback`.

Run:

pytest tests/test_mcp.py::TestToolSchema::test_v05_tool_descriptions_are_model_actionable -q

Expected: pass.

git add src/zaxy/mcp_server.py tests/test_mcp.py docs/mcp.md
git commit -m "docs: make MCP tools model-actionable"

Task 7: Docs Site Coverage and Rendered Pages

Files:

Modify REQUIRED_DOCS in tests/test_docs_site.py to include:

    "docs/v1-roadmap.md",
    "docs/mcp-quickstart.md",
    "docs/coordinate-quickstart.md",
    "docs/first-run-validation.md",

Add a test:

def test_v05_docs_render_to_static_site() -> None:
    """v0.5 roadmap and quickstarts should be published to the static site."""
    for path in (
        "site/docs/v1-roadmap.html",
        "site/docs/mcp-quickstart.html",
        "site/docs/coordinate-quickstart.html",
        "site/docs/first-run-validation.html",
    ):
        assert Path(path).exists()

Run:

pytest tests/test_docs_site.py::test_v05_docs_render_to_static_site -q

Expected: fail until generated pages exist.

Run:

python scripts/build-site-docs.py

Expected: renders documentation pages under site/.

Run:

pytest tests/test_docs_site.py::test_v05_docs_render_to_static_site -q
scripts/validate-docs.sh --root .

Expected: pass.

git add tests/test_docs_site.py site/README.html site/docs
git commit -m "docs: publish v0.5 roadmap quickstarts"

Task 8: Changelog and Release Gate Notes

Files:

Append to tests/test_v05_positioning.py:

def test_changelog_has_unreleased_v05_section() -> None:
    """v0.5 planning work should have a changelog section before release."""
    text = Path("CHANGELOG.md").read_text(encoding="utf-8")

    assert "## 0.5.0 - Unreleased" in text
    assert "Coordinator Memory for Agent Teams" in text
    assert "first-run validation" in text
    assert "MCP Quickstart" in text

Run:

pytest tests/test_v05_positioning.py::test_changelog_has_unreleased_v05_section -q

Expected: fail until changelog is updated.

Add this section above 0.4.0:

## 0.5.0 - Unreleased

- Repositioned Zaxy around **Coordinator Memory for Agent Teams** across package metadata, README, docs, and the static site.
- Added first-run validation docs so new users can report install, init, bootstrap, checkout, doctor, and example timing.
- Added MCP Quickstart and Coordinate Quickstart docs for the v0.5 public path.
- Added single-agent, LangGraph, and Coordinate example smoke coverage.
- Improved MCP tool descriptions so model-facing clients know when to call bootstrap, checkout, feedback, and coordination tools.

In docs/v1-roadmap.md, under v0.5, add a brief status note:

**Implementation status:** planned in
`docs/superpowers/plans/2026-05-30-v0-5-public-positioning-first-run-trust.md`.

Run:

pytest tests/test_v05_positioning.py -q

Expected: pass.

git add CHANGELOG.md README.md docs/v1-roadmap.md tests/test_v05_positioning.py
git commit -m "docs: record v0.5 release gate notes"

Task 9: Full Verification

Files:

Run:

pytest tests/test_v05_positioning.py tests/test_examples_v05.py tests/test_mcp.py::TestToolSchema tests/test_packaging.py tests/test_docs_site.py -q

Expected: all pass.

Run:

ruff check src tests examples
mypy src

Expected: both pass.

Run:

python scripts/build-site-docs.py --check
scripts/validate-docs.sh --root .

Expected: both pass.

Run:

pytest

Expected: pass with coverage at or above 92%.

Run:

zaxy doctor --release-smoke

Expected: pass or report only known release-version issues if 0.5.0 has not been cut yet. If it fails because CHANGELOG.md has an unreleased section rather than a released version, record that as expected pre-release state in the handoff.

git add CHANGELOG.md README.md pyproject.toml docs examples tests src/zaxy/mcp_server.py site
git commit -m "test: verify v0.5 release gate docs"

Implementation Notes

Success Checklist