feat: add official fixtures and demo walkthroughs

Alexxigang · Alexxigang · commit ba65fb4f88ed · 2026-03-13T00:12:39.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.18.0 - 2026-03-13
+
+- added official fixtures for generic JSON, Cline/Roo, AGENTS.md, Cursor, and Claude layouts
+- added demo guide with reproducible CLI walkthroughs
+- documented fixture usage for contributors and demos
+
 ## 0.17.0 - 2026-03-12
 
 - added GitHub Actions CI for tests and CLI smoke checks
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -32,3 +32,7 @@ Please include:
 ## Continuous integration
 
 Pull requests are validated by GitHub Actions on Python 3.11 and 3.12. The workflow runs unit tests and a small end-to-end CLI smoke test.
+
+## Fixtures and demos
+
+When adding a new adapter or workflow, prefer adding or updating a sample under `fixtures/` and documenting a reproducible command in `docs/demo.md`.
diff --git a/README.md b/README.md
@@ -59,6 +59,10 @@ The architecture is intentionally adapter-first, so more products can be added w
 
 GitHub Actions runs unit tests plus a CLI smoke test for `bundle` and `verify` on pushes and pull requests.
 
+## Fixtures
+
+Official sample inputs live in `fixtures/`. See `docs/demo.md` for reproducible walkthroughs using the included demo data.
+
 ## Installation
 
 ```bash
diff --git a/docs/demo.md b/docs/demo.md
@@ -0,0 +1,43 @@
+# Demo Guide
+
+This repository includes official sample fixtures under `fixtures/`.
+
+## Quick demo
+
+List adapters:
+
+```bash
+memory-migrate adapters
+```
+
+Inspect a fixture:
+
+```bash
+memory-migrate inspect --input ./fixtures/cline-memory-bank
+```
+
+Run a one-shot release demo:
+
+```bash
+memory-migrate release   --input ./fixtures/cline-memory-bank   --to agents-md   --profile agent-rules   --output-dir ./dist/demo-release   --zip ./dist/demo-release.zip
+```
+
+Verify the release bundle:
+
+```bash
+memory-migrate verify --manifest ./dist/demo-release/manifest.json
+```
+
+## Useful fixture conversions
+
+Convert generic JSON into Cursor rules:
+
+```bash
+memory-migrate convert   --input ./fixtures/generic-json/sample.json   --to cursor-rules   --profile developer-strict   --output ./dist/cursor-rules
+```
+
+Generate a doctor report from AGENTS instructions:
+
+```bash
+memory-migrate doctor --input ./fixtures/agents-md --output ./dist/agents-doctor.json
+```
diff --git a/fixtures/README.md b/fixtures/README.md
@@ -0,0 +1,18 @@
+# Fixtures
+
+This directory contains official sample inputs for Agent Memory Bridge.
+
+These fixtures are intended for:
+
+- local demos
+- regression tests
+- adapter development
+- documentation examples
+
+Available sample sets:
+
+- `generic-json/`: simple canonical-friendly JSON list
+- `cline-memory-bank/`: Roo/Cline style Memory Bank
+- `agents-md/`: `AGENTS.md` plus `.agents/notes`
+- `cursor-rules/`: `.cursor/rules` instruction bundle
+- `claude-project/`: `CLAUDE.md` plus `.claude/memories`
diff --git a/fixtures/agents-md/.agents/notes/handoff.md b/fixtures/agents-md/.agents/notes/handoff.md
@@ -0,0 +1 @@
+If switching tools, preserve profile, decisions, and project context first.
diff --git a/fixtures/agents-md/AGENTS.md b/fixtures/agents-md/AGENTS.md
@@ -0,0 +1,5 @@
+# AGENTS
+
+- Respect existing repository conventions.
+- Prefer deterministic outputs.
+- Keep migration artifacts auditable.
diff --git a/fixtures/claude-project/.claude/memories/release-notes.md b/fixtures/claude-project/.claude/memories/release-notes.md
@@ -0,0 +1 @@
+Release bundles should include compare, manifest, and verify artifacts.
diff --git a/fixtures/claude-project/CLAUDE.md b/fixtures/claude-project/CLAUDE.md
@@ -0,0 +1,4 @@
+# CLAUDE
+
+This project migrates reusable memory between AI agent ecosystems.
+Focus on adapters, canonical schemas, and release-grade outputs.
diff --git a/fixtures/cline-memory-bank/activeContext.md b/fixtures/cline-memory-bank/activeContext.md
@@ -0,0 +1 @@
+Current focus: adapter coverage and release workflow.
diff --git a/fixtures/cline-memory-bank/decisionLog.md b/fixtures/cline-memory-bank/decisionLog.md
@@ -0,0 +1 @@
+Prioritize file-based formats before private/cloud integrations.
diff --git a/fixtures/cline-memory-bank/productContext.md b/fixtures/cline-memory-bank/productContext.md
@@ -0,0 +1 @@
+Users need a low-friction way to carry memory across agent products.
diff --git a/fixtures/cline-memory-bank/progress.md b/fixtures/cline-memory-bank/progress.md
@@ -0,0 +1 @@
+CLI, diagnostics, bundle, release, and verify are implemented.
diff --git a/fixtures/cline-memory-bank/projectbrief.md b/fixtures/cline-memory-bank/projectbrief.md
@@ -0,0 +1 @@
+Build an open-source memory migration toolkit for AI agents.
diff --git a/fixtures/cline-memory-bank/systemPatterns.md b/fixtures/cline-memory-bank/systemPatterns.md
@@ -0,0 +1 @@
+Use canonical package plus adapter-based import/export.
diff --git a/fixtures/cline-memory-bank/techContext.md b/fixtures/cline-memory-bank/techContext.md
@@ -0,0 +1 @@
+Python 3.11+, standard library first, deterministic JSON output.
diff --git a/fixtures/cline-memory-bank/userContext.md b/fixtures/cline-memory-bank/userContext.md
@@ -0,0 +1 @@
+Prefers concise updates and audit-friendly outputs.
diff --git a/fixtures/cursor-rules/.cursor/rules/python-backend.mdc b/fixtures/cursor-rules/.cursor/rules/python-backend.mdc
@@ -0,0 +1,7 @@
+---
+title: Python Backend Rule
+alwaysApply: true
+globs: src/**/*.py
+---
+
+Prefer typed service modules over large script files.
diff --git a/fixtures/generic-json/sample.json b/fixtures/generic-json/sample.json
@@ -0,0 +1,23 @@
+[
+  {
+    "id": "pref-editor",
+    "kind": "preference",
+    "title": "Editor Preference",
+    "content": "Use Vim keybindings when available.",
+    "tags": ["developer", "editor"]
+  },
+  {
+    "id": "project-api",
+    "kind": "project",
+    "title": "API Project",
+    "content": "Primary stack is Python, FastAPI, and PostgreSQL.",
+    "tags": ["backend", "api"]
+  },
+  {
+    "id": "decision-auth",
+    "kind": "decision",
+    "title": "Auth Decision",
+    "content": "Use GitHub OAuth for the first release.",
+    "tags": ["auth", "decision"]
+  }
+]
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory-migrate-plugin"
-version = "0.17.0"
+version = "0.18.0"
 description = "Open-source toolkit for migrating memories across AI agent systems."
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/src/memory_migrate_plugin/__init__.py b/src/memory_migrate_plugin/__init__.py
@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"
diff --git a/tests/test_roundtrip.py b/tests/test_roundtrip.py
@@ -107,6 +107,19 @@ def test_detect_format_prefers_agents_md(self) -> None:
             matches = detect_format(root)
             self.assertEqual(matches[0][0], "agents-md")
 
+
+    def test_official_fixtures_are_detectable(self) -> None:
+        fixtures = {
+            "fixtures/generic-json/sample.json": "generic-json",
+            "fixtures/cline-memory-bank": "cline-memory-bank",
+            "fixtures/agents-md": "agents-md",
+            "fixtures/cursor-rules": "cursor-rules",
+            "fixtures/claude-project": "claude-project",
+        }
+        for raw_path, expected in fixtures.items():
+            matches = detect_format(Path(raw_path))
+            self.assertEqual(matches[0][0], expected)
+
     def test_agents_md_adapter_reads_main_and_notes(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+If switching tools, preserve profile, decisions, and project context first.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Release bundles should include compare, manifest, and verify artifacts.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Current focus: adapter coverage and release workflow.`