Architectural shift: abstract metaconcepts above tool-specific formats

[troylar]

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.

[troylar]

Updated Direction: AI-Baked-In (Option B)

After discussion, the decision is to integrate AI directly into the CLI rather than keeping DevSync as a dumb tool layer that AI assistants orchestrate.

Why

The "holy shit" moment requires zero orchestration from the user. Two commands:

devsync extract                                    # AI reads your project, produces a shareable package
devsync install github.com/company/standards       # AI adapts to your setup, merges intelligently

Nobody says "holy shit" about a library that other tools call. The value is in the CLI itself being intelligent.

The AI Pipeline

AI is the engine for the entire workflow, not just one step:

1. Extract — AI reads project rules, MCP configs, commands, skills, hooks, CLAUDE.md → understands intent → produces abstract declarations, scrubs secrets and project-specific details
2. Package — AI structures declarations into a clean shareable format with descriptions that help recipients understand the practices
3. Install — AI translates declarations to tool-native formats, prompts for credentials with helpful context
4. Adapt — AI merges incoming practices with recipient's existing setup. Not file-level skip/overwrite — content-level "your rules already cover X, the package adds Y, here's a combined version"

API Key Requirement

This means DevSync requires an LLM API key. Make it painless:

• Use existing ANTHROPIC_API_KEY (users are likely already Claude users)
• Support OPENAI_API_KEY as alternative
• First run prompts once, stores in ~/.devsync/config
• LLM calls are small (extracting intent from markdown, not generating novels) — cheap

Vision Update Needed

DevSync goes from "package manager for AI configs" to "AI-powered config distribution for AI coding tools."

Drop the "works offline" constraint — the tools being configured are AI coding assistants that require internet. The offline principle was holding back the actual value.

Update "Not a code generator" to acknowledge that install-time content generation (translating abstract practices to tool-specific formats) is a deliberate expansion of scope in service of the core mission.

Revised Product Identity

• pip install devsync — still zero friction
• AI-powered extraction and adaptation — the differentiator
• Write once, install to any tool — still the core promise
• Intelligent merging — the thing nothing else does
• Credential safety preserved — AI extracts declarations, never stores values

What This Supersedes

• Library system (download/cache) — replaced by direct install with AI adaptation
• Template system — subsumed entirely
• File-level conflict resolution — replaced by AI content merging
• Manual manifest authoring — replaced by AI extraction
• TUI browser — defer, not the core experience

[troylar]

Completed by PR #79 (v0.12.0). DevSync v2 shipped with: abstract practice declarations (PracticeDeclaration, MCPDeclaration), AI-powered extraction and adaptation, content-level merging, declarative MCP credential handling, and simplified 6-command CLI. Any remaining work (abstract commands/skills declarations) can be tracked as separate issues.