Phase 3: pluggable OSS-first adapter framework - #27
Merged
Conversation
Make every backend a documented, swappable adapter (zero lock-in): - claude/workflow/adapters/README.md: the adapter contract (capabilities / health-check / fallback / data-residency) + the OSS-first menu per category (tickets, knowledge base, memory, design) and how to enable each overlay. - claude/workflow/adapters/mcp/: ready-to-paste .mcp.json overlays (atlassian, backlog, openmemory, penpot, obsidian). - workflow.yaml: add memory: and design: adapter sections (+ schema entries); point to adapters/README.md. - installer: .mcp.json.example now points at the adapters/mcp/ menu. - workflow/README.md: note backends are pluggable adapters.
There was a problem hiding this comment.
Pull request overview
This PR formalizes a pluggable, OSS-first “adapter” layer for workflow backends (tickets, knowledge base, memory, design), documenting a stable contract and providing ready-to-paste MCP overlay snippets so teams can opt into cloud/self-hosted integrations without breaking local-first defaults.
Changes:
- Documented the adapter contract and OSS-first backend menu in
claude/workflow/adapters/README.md. - Extended
workflow.yaml(+ JSON schema) to includememoryanddesignbackend sections alongside existing categories. - Added MCP overlay snippet JSONs for Atlassian, Backlog.md, OpenMemory, Penpot, and Obsidian; updated installer/example docs to point to the overlay menu.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| install.sh | Updates .mcp.json.example note to point users to the overlay menu location. |
| claude/workflow/workflow.yaml | Adds memory and design backend sections and references adapter documentation. |
| claude/workflow/workflow.schema.json | Extends schema to allow memory and design keys. |
| claude/workflow/README.md | Notes that backends are pluggable adapters and links to adapter docs. |
| claude/workflow/adapters/README.md | Introduces the adapter contract and an OSS-first backend matrix + enablement steps. |
| claude/workflow/adapters/mcp/atlassian.json | Adds an Atlassian MCP overlay snippet. |
| claude/workflow/adapters/mcp/backlog.json | Adds a Backlog.md MCP overlay snippet. |
| claude/workflow/adapters/mcp/openmemory.json | Adds an OpenMemory MCP overlay snippet. |
| claude/workflow/adapters/mcp/obsidian.json | Adds an Obsidian MCP overlay snippet. |
| claude/workflow/adapters/mcp/penpot.json | Adds a Penpot MCP overlay snippet. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…e README path - Add adapters/mcp/mem0.json (the hosted mem0 backend advertised in workflow.yaml) + a README table row; label openmemory as the local mem0 server. - installer: the .mcp.json.example note now points to the installed adapters README ($(content_ref)/workflow/adapters/README.md), not a root-relative path.
design.optional_mcp advertised figma/canva but shipped no overlays. Add
adapters/mcp/{figma,canva}.json (Figma Dev Mode local MCP on :3845; Canva hosted
MCP) + README rows, so every advertised backend now has a ready-to-use overlay.
… clarify mappings - workflow.schema.json: add a shared 'adapterConfig' definition (requires 'default' string, 'optional_mcp' array-of-strings, no extra keys) and reference it from tickets/knowledge_base/memory/design — so validation catches config mistakes. workflow.yaml validates against it. - adapters/README.md: note that some overlays serve multiple backends (Jira + Confluence both come from atlassian.json).
…able OpenMemory (self-hosted mem0) is the local-service overlay; mem0 (hosted) is the cloud option — align the Memory row with the overlay table's API-key note.
| knowledge_base: | ||
| default: markdown # docs/ or an Obsidian-compatible vault | ||
| optional_mcp: [obsidian, kgb_canon] | ||
| memory: |
olehsvyrydov
added a commit
that referenced
this pull request
Jun 6, 2026
* Phase 3: pluggable OSS-first adapter framework Make every backend a documented, swappable adapter (zero lock-in): - claude/workflow/adapters/README.md: the adapter contract (capabilities / health-check / fallback / data-residency) + the OSS-first menu per category (tickets, knowledge base, memory, design) and how to enable each overlay. - claude/workflow/adapters/mcp/: ready-to-paste .mcp.json overlays (atlassian, backlog, openmemory, penpot, obsidian). - workflow.yaml: add memory: and design: adapter sections (+ schema entries); point to adapters/README.md. - installer: .mcp.json.example now points at the adapters/mcp/ menu. - workflow/README.md: note backends are pluggable adapters. * Address Copilot review on PR #27: mem0 overlay + fix .mcp.json.example README path - Add adapters/mcp/mem0.json (the hosted mem0 backend advertised in workflow.yaml) + a README table row; label openmemory as the local mem0 server. - installer: the .mcp.json.example note now points to the installed adapters README ($(content_ref)/workflow/adapters/README.md), not a root-relative path. * Address Copilot re-review on PR #27: add figma + canva design overlays design.optional_mcp advertised figma/canva but shipped no overlays. Add adapters/mcp/{figma,canva}.json (Figma Dev Mode local MCP on :3845; Canva hosted MCP) + README rows, so every advertised backend now has a ready-to-use overlay. * Address Copilot re-review on PR #27: schema-validate adapter config + clarify mappings - workflow.schema.json: add a shared 'adapterConfig' definition (requires 'default' string, 'optional_mcp' array-of-strings, no extra keys) and reference it from tickets/knowledge_base/memory/design — so validation catches config mistakes. workflow.yaml validates against it. - adapters/README.md: note that some overlays serve multiple backends (Jira + Confluence both come from atlassian.json). * Address Copilot re-review on PR #27: fix mem0 residency in the menu table OpenMemory (self-hosted mem0) is the local-service overlay; mem0 (hosted) is the cloud option — align the Memory row with the overlay table's API-key note.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes every backend a documented, swappable adapter — the 'no lock-in' promise, made concrete. Defaults run fully local with zero paid accounts; everything else is an opt-in overlay.
claude/workflow/adapters/README.md— the adapter contract (capabilities / health-check / fallback / data-residency) + the OSS-first menu per category (tickets, knowledge base, memory, design: default → OSS overlay → cloud) + how to enable each, and how to add a new adapter.claude/workflow/adapters/mcp/*.json— ready-to-paste.mcp.jsonoverlays:atlassian,backlog(Backlog.md),openmemory,penpot,obsidian(all valid JSON).workflow.yaml— addsmemory:anddesign:adapter sections (+ schema entries) alongside the existingtickets:/knowledge_base:; points to the adapters doc..mcp.json.examplenow points users at theworkflow/adapters/mcp/menu.workflow/README.md— notes backends are pluggable adapters.Why
Phase 3's adapter layer: the file-based defaults stay authoritative (the 5-minute first run never breaks), and Jira/Confluence/OpenMemory/Penpot/Figma become additive overlays selected in
workflow.yaml+ an MCP snippet.Verification
workflow.yamlvalid YAML; schema valid JSON; all 8 overlay snippets valid JSON..mcp.json.examplereferences the adapters menu.(The local Hub UI — the other half of Phase 3 — is a separate, larger slice.)