Architectural shift: abstract metaconcepts above tool-specific formats #62

Summary

Rethink DevSync's core model from file distribution to practice distribution. Packages should store abstract metaconcepts (rules, commands, skills, MCP servers) that are tool-agnostic, with translation to tool-specific formats happening at install time.

This is a vision-level architectural shift, not a single feature.

The Problem Today

Currently, DevSync packages contain files that are essentially tool-specific artifacts:

• A rule is a .md file that gets copied to .claude/rules/ or .cursor/rules/
• An MCP config is a JSON file that gets copied with path adjustments
• Content is passed through, not translated

This means:

1. Packages are implicitly tied to the format they were authored in
2. "Install" means "copy files to the right directories" — smart routing, dumb content
3. Users can't adapt or merge practices — only overwrite/skip/rename at the file level
4. MCP configs with credentials require manual scrubbing rather than declarative extraction

The New Model

Abstract metaconcepts

A package stores intent, not files:

• Rule: A practice with a name, description, principles, enforcement patterns, and examples — not a markdown blob written for one tool
• Command: A capability declaration (what it does, what inputs it needs, what it produces) — not a shell script
• MCP Server: A service declaration (what it does, what credentials it needs, how to describe them to users) — not a JSON config file
• Skill: A workflow declaration (steps, context needed, outputs) — not a directory with a SKILL.md

Translation at install time

The ai_tools/ layer becomes responsible for translating abstract declarations into tool-native formats. This is an expansion of what it already does (routing files to directories) into also handling content generation.

"Adapt, don't overwrite" workflow

Because practices are stored as structured concepts with intent, an AI-assisted merge becomes possible:

• User has existing testing rules
• User installs a package with testing best practices
• Instead of overwriting, DevSync (or an AI skill using DevSync) can semantically merge: "Your rules already cover X. The package adds Y and Z. Here's a combined version."

This is content-level merging, not file-level conflict resolution.

MCP credential extraction

A concrete example of the pattern:

Today: User has .claude/settings.local.json with real API keys. package create scrubs them into ${ENV_VAR} placeholders. Recipient gets a JSON file with holes.

New model: package create extracts the MCP server declaration: "This package needs a filesystem MCP server. It requires ALLOWED_DIRECTORIES (description: comma-separated paths to allow). It uses the @anthropic/mcp-filesystem package." At install time, DevSync builds the correct config format for the target tool, prompts for credentials with helpful descriptions, and writes the final config — never storing secrets.

What Changes

Keep

• Multi-tool translation engine (ai_tools/) — this is the core differentiator
• Package manifest format (evolve ai-config-kit-package.yaml to support declarations)
• devsync install and devsync package create commands
• devsync tools detection
• Secret detection and credential safety patterns

Evolve

• Package format: from file references to practice declarations
• Install logic: from file copying to content generation
• Conflict resolution: from file-level (skip/overwrite/rename) to content-level (merge/adapt/replace)
• MCP handling: from config scrubbing to declarative extraction

Simplify/Remove

• Library system (download/list/update/delete cache) — install directly from source
• Template system — subsumed by the new package model
• TUI browser — defer, not core to the new model
• Installation tracking — simplify to "what's installed where"
• Multiple install commands (install, package install, template install, mcp install) — unify to one install verb

Acceptance Criteria

This is a large effort. Initial acceptance criteria for the first milestone:

• Define the abstract schema for each metaconcept (rule, command, skill, MCP server)
• Update ai-config-kit-package.yaml format to support declarations alongside file references (backwards compatible)
• Implement declaration-based MCP install: extract credentials at create time, prompt and build config at install time
• Prove the model with one end-to-end example: create a package from a real project, install it to 2+ tools from declarations
• Document the new package format

Open Questions

1. How much translation should DevSync do vs. delegating to AI at install time? (DevSync stays AI-free per vision, but a Claude Code skill could handle the AI-assisted merge)
2. Should the abstract format be YAML declarations, structured markdown, or something else?
3. How to handle backwards compatibility with existing file-based packages?
4. Where does the "adapt/merge" workflow live — in DevSync CLI or as an AI skill that uses DevSync under the hood?

Vision Alignment

• ✅ Zero-friction: still pip install, still CLI
• ✅ IDE-agnostic: strengthens this — practices truly portable across tools
• ✅ Git as distribution: packages still live in Git repos
• ✅ Lean CLI: simplifies command surface area
• ✅ Credential safety: improves this — credentials are declarative, never in files
• ✅ Standards-first: abstract format is a new standard, but grounded in existing YAML/markdown

⚠️ Vision tension: "Not a code generator" — the install step now generates tool-specific content from declarations. This is a deliberate expansion of scope that should be acknowledged in VISION.md. It's generation in service of translation, not content creation.