Roadmap
July 30, 2026 · View on GitHub
This document turns the current analysis into concrete gap matrices for the questions raised about:
- Linux and macOS portability
- automatic support for arbitrary repository and folder types without manual configuration
- robustness and efficiency of Source Discovery and Stack Detection
- whether source breadth and marketplace diversity are actually generic enough in practice
- how plugin, extension, and MCP Server discovery and installation work with automatic wire-in
- whether the project can be extended easily to additional AI agents and IDEs
- whether the internal codebase structure is scalable enough or needs a deeper project refactor
Scope of the original assessment:
- branch:
feature/opencode-link-wirein - assessment date: 2026-04-19 (v1.0.0 baseline); last updated for v2.0.0: 2026-06-01
- evidence source: implementation and checked-in configuration at that time
v1.0.0 Status Update
The release/v1.0.0 execution wave closes the highest-priority roadmap gaps for portability, generic discovery, source utilization, measurable detection quality, host adapter extensibility, and native project-local wire-in. In particular, VS Code/Copilot and OpenCode have native wire-in flows, while Cursor, Zed, Claude Code, and Pi now use the same host adapter model to write project-local native host files, host-specific wire plans, and independently tuned recommendation policies.
The post-merge hardening wave adds scoped package release identity, deterministic package allowlisting, package entry points and declaration output, mutable state-root support outside the package install directory, safe mirror writes with file-manifest verification, bounded mirror evidence file reads, guarded network reads, static public-provider allowlisting for optional AI enrichment, GitHub/repo mirror-time content acquisition, validated PyPI metadata, lazy .env-aware VS Code settings path resolution, explicit recommendation execution in workspace and full rebuild runs, registry-driven recommendation-host enumeration, adapter-derived install bundle discovery, preview-by-default wire mode, non-destructive VS Code/OpenCode managed sections, adapter-owned runtime checks, VS Code native extension install/verify/remove with bounded native commands, asset prerequisite guidance, optional AI enrichment, official upstream allowlisting, mirror diff/explain reporting, isolated CLI, offline workspace, and packed-artifact smoke checks, operational docs/registry/marketplace harvesters, broad deterministic file-family and technology signature packs, .gitignore glob/negation handling, focused install-domain modules, recommendation and mirror module seams, domain-specific manifest validators, localized domain type modules, discovery demand/source/reporting seams, package/reference/local/GitHub/official-index catalog harvester seams, and type-aware ESLint guardrails. Broader native installers beyond VS Code and Cursor, richer interactive quarantine review UIs, deeper provider-specific OAuth automation, and future package/workspace extraction remain tracked follow-up work.
The gap matrices below are retained for traceability. Their evidence cells describe the original 2026-04-19 baseline, while the verdict table summarizes the current status.
v2.0.0 Status Update
The release/v2.0.0 wave builds directly on the v1.0.0 foundation and closes the remaining high-priority gaps in host coverage, documentation accessibility, operational instrumentation, discovery reporting, and test-coverage governance. The key additions are summarised below.
Codex host adapter (#229)
Codex joins VS Code/Copilot, OpenCode, Cursor, Zed, Claude Code, and Pi as a fully registered host adapter. The adapter writes a project-local workspace directory and wire manifest, documents its integration boundaries explicitly, and provides a safe reset path so the project-local Codex state can be torn down without affecting other hosts.
Documentation and README overhaul (#225, #226, #230, #232, #233, #234, #236)
The top-level README was repositioned around the user's outcome rather than the implementation's mechanics. Changes include: a rewritten hero section with concrete value proposition and proof points; a one-command quick-start block that takes a new user from clone to first recommendation without reading further; concrete lifecycle-command outputs showing what each pipeline stage actually produces; command-style conventions unified across all CLI reference pages; supported-host and supported-asset badge rows for at-a-glance coverage; and an animated demo GIF illustrating the full discover → wire flow.
New operational documentation (#239, #248, #252, #254, #255, #256, #258, #259)
Eight new reference documents were added to docs/:
- Workspace evolution — describes how the project-local workspace directory grows across pipeline runs and how to inspect or prune it safely.
- Maintenance playbook — step-by-step procedures for routine upkeep: re-harvesting sources, refreshing mirrors, rotating tokens, and pruning stale catalog entries.
- Quarantine guide — explains the quarantine lifecycle for flagged assets, reviewer workflow, and how quarantine decisions are persisted.
- Safe-default reference — catalogues every security-relevant default (network guards, path constraints, manifest size caps, allowlists) and why each exists.
- Trust center — documents the supply-chain trust model, provider allowlists, and how new sources are evaluated before being added to the default registry.
- Host support matrix — a single authoritative table of every registered host adapter, the asset kinds it supports, and any capability gaps.
- v1-to-v2 upgrade guide — explains what changed between v1.0.0 and v2.0.0 at the config, CLI, and workspace-layout levels, with a migration checklist.
- Release process — documents the tagging, changelog, and smoke-check steps used to cut an official release, including the reproducible-demo requirement.
New discovery and reporting features (#240, #242, #245, #246, #247, #261, #262, #263, #264)
Discovery and reporting gained nine new capabilities:
- Unknown workspace-signal backlog reports (#240) — the
doctorcommand now emits a ranked backlog of workspace signals that did not match any known stack signature, giving visibility into coverage gaps before they become silent misses. - Source and catalog health doctor reports (#242) —
doctoralso reports per-source harvest health: last-successful fetch time, error count, and catalog-entry yield, so stale or broken sources are surfaced proactively. - Candidate source queues (#245) — a structured queue accumulates candidate new sources discovered during harvesting (referenced packages without a configured source, community links found in docs) for human review rather than silent discard.
- Scheduled maintenance workflows (#246) — a GitHub Actions workflow template is provided for periodic source re-harvesting, mirror refresh, and catalog integrity checks on a cron schedule.
- Discover diff summaries (#247) — the
discovercommand can emit a structured diff between the current run's demand profile and the previous one, making it easy to see which signals appeared or disappeared. - Explainability commands (#261) —
explain recommendation <id>andexplain detection <signal>subcommands trace exactly which evidence lines produced a given recommendation or detection result, with source file references. - Experimental environment index metadata (#262) — the workspace index now optionally records environment metadata (Node version, Python version, OS, active host adapters) alongside the demand profile to support cross-environment comparisons.
- Evidence-weighted classification confidence (#263, #264) — stack-detection results now carry a numeric confidence score derived from the count and weight of supporting evidence signals, and a low-confidence threshold can be configured to gate recommendations.
Coverage hardening (#207)
The test suite now enforces a 100 % statement, branch, function, and line coverage gate in CI. A reproducible gap-reporting step prints the exact uncovered lines in a standard format when the gate fails, making it straightforward to identify and close gaps. Broad behavioral tests were added alongside the coverage gate to ensure that coverage numbers reflect meaningful scenario execution rather than trivially covered stubs.
Native-host recommendation fixtures for Cursor, Zed, Claude Code, and Pi (#208)
Golden-file recommendation fixtures were added for all four of the hosts that graduated to full adapter status in v1.0.0. Each fixture covers a representative project archetype (TypeScript monorepo, Python data-science project, documentation-only repo, and a multi-language mixed repo) and is run in CI to prevent silent regressions in host-specific recommendation output.
Demand-detection coverage matrix and false-positive fixtures (#209)
A structured coverage matrix was introduced that maps each file-family and technology-signature pack to its fixture corpus entries. Alongside it, an explicit set of false-positive fixtures was added: repos that should not trigger certain detections, ensuring that broadening the signature packs does not introduce phantom demand signals.
Scenario-based recommendation-limit scaling guidance (#210)
Documentation and configurable defaults were added for scaling the per-run recommendation limit based on project size and complexity signals. The guidance covers four named scenarios (minimal, standard, large monorepo, and research/data-heavy) with recommended cap values and the reasoning behind them, so operators can tune limits without reverse-engineering internal scoring.
Branch-residual coverage suites
Residual-branch coverage suites were added across all major domains — discovery, install, mirror, activate, wire, host adapters, catalog harvesting, and CLI command parsing — to ensure that every defensive branch (error paths, empty-input guards, unsupported-host fallbacks) is exercised by at least one named test case.
The gap matrices below remain as historical baselines recorded against the 2026-04-19 assessment. The verdict table reflects the cumulative state after both the v1.0.0 and v2.0.0 releases.
Overall Verdict
| Question | Current answer | Why |
|---|---|---|
| Will this automatically work on Linux and macOS without issues? | Yes, with CI coverage | OS-aware paths, generated local source seeds, portable link handling, and Windows/macOS/Linux guardrails are now in place. |
| Will this automatically work with almost any type of project folder or repo without manual changes? | Much broader than before | Detector packs now cover software, docs, notebooks, datasets, media/design assets, CAD/hardware, research, game engines, mobile, AI/ML/DL/RL, robotics, security, blockchain, marketing, and fabrication repos. |
| Is Source Discovery and Stack Detection robust enough for almost any project? | Measurable and extensible | Detection has modular file-family and technology signature packs, repo-level fixtures, benchmark coverage, and quality reporting; long-tail domains remain future expansion areas. |
| Are the configured sources generic enough because several marketplaces are included? | Operationally harvested and reportable | Source utilization reporting distinguishes configured sources from actually harvested sources; docs, registry, VS Code Marketplace, npm, and PyPI inputs now contribute bounded evidence. |
| How automatic is plugin, extension, and MCP Server setup through wire-in today? | Broad native file wiring; explicit native install | The pipeline separates stage/activate/wire/native-install, projects shared MCP references, writes native project-local host files where supported, and can explicitly install/verify/remove VS Code extensions. |
| Can this be extended easily to more AI agents and IDEs? | Yes through host adapters | Cursor, Zed, Claude Code, and Pi now prove the adapter surface beyond VS Code/Copilot and OpenCode, including independent recommendation tuning. |
| Is the current single-folder source layout scalable enough for further growth? | Yes for v1.0.0 | New config, discovery, install, manifest-validation, types, wire, host-adapter, path, preflight, HTTP, state-root, CLI parsing, release-artifact, and catalog-harvester seams exist. Future package/workspace extraction remains optional. |
Gap Matrix 1: Linux and macOS Portability
| Gap | Current evidence | Impact | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|
| VS Code wire-in uses Windows-only home and settings env vars | src/host-vscode.ts uses APPDATA for Code/User/settings.json and USERPROFILE for ~/.copilot/agent-harness | Linux and macOS user settings and curated runtime paths will not resolve correctly by default | High | Replace env-var path building with os.homedir() plus OS-aware VS Code settings resolution; support Windows, macOS, Linux explicitly | wire vscode --apply works on all three OSes without env var hacks | P1 / #5 |
| Home-path normalization is Windows-specific | src/host-vscode.ts converts only USERPROFILE-prefixed paths to ~ | Non-Windows paths are only partially normalized and user-facing config becomes inconsistent | Medium | Normalize via os.homedir() and avoid USERPROFILE-only replacement logic | All generated path entries render consistently on Windows, macOS, and Linux | P2 / #6 |
| Checked-in local sources are hardcoded to one Windows machine | discover/sources.json contains C:/Users/ar271/.agents/skills, C:/Users/ar271/.config/opencode, and related paths | Out-of-the-box source discovery is not portable across machines, let alone operating systems | High | Convert seeded local sources to templated home-relative paths or generate them at runtime per OS | Fresh clone on macOS or Linux has no broken local source endpoints | P3 / #7 |
| OpenCode local seeds also assume Windows absolute paths | discover/sources.json contains C:/Users/ar271/.config/opencode and C:/Users/ar271/.config/opencode/context | Local OpenCode discovery silently degrades off the original workstation | High | Resolve OpenCode config roots from home directory at runtime instead of committing workstation-specific paths | Local OpenCode sources auto-resolve correctly across supported OSes | P4 / #8 |
| Cross-platform behavior is not enforced in CI | Current validation covers typecheck, lint, format, and recommendation fixtures, but not OS matrix runs | Regressions can reintroduce platform-specific behavior unnoticed | Medium | Add GitHub Actions matrix for Windows, Ubuntu, and macOS covering workspace commands and wire-in preview/apply/reset smoke tests | CI blocks merges when any OS-specific path or link behavior breaks | P5 / #9 |
| Directory linking is partially portable but not fully validated | src/files.ts uses junctions on Windows and directory symlinks elsewhere | The implementation is promising, but there is no automated proof that link creation/reset is reliable on all targets | Medium | Add wire-in integration tests that assert creation, replacement, and reset of managed links on all OSes | Link lifecycle tests pass on Windows, Linux, and macOS | P6 / #10 |
Gap Matrix 2: Automatic Support for Arbitrary Repository and Folder Types
| Gap | Current evidence | Impact | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|
| Demand profiling only inspects a narrow set of software-oriented files | src/discover.ts shouldInspectFile() focuses on files like package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Dockerfile, deno.json, actor.json, and OpenAPI files | Many repo types produce little or no signal, including CAD, art, music, video, business analysis, research, hardware, game engines, and many niche engineering domains | High | Expand detection plugins beyond software manifests into domain detectors for notebooks, datasets, design tools, engines, CAD files, robotics stacks, DSP/media projects, research assets, and documentation-heavy repos | Representative non-software and mixed-domain repos produce meaningful demand profiles without custom patches | G1 / #12 |
| Local repo classification is centered on agent-asset structures, not generic repos | src/discover.ts classifyLocalDirectoryFile() primarily recognizes SKILL.md, agent markdown, plugin code, instructions, workflows, and OpenCode context structures | Generic repos are not "understood" unless they already resemble an agent/skills ecosystem | High | Split "repo understanding" from "agent asset harvesting" and add a generic repository classifier layer before asset selection | Generic repos can be analyzed even when they contain zero agent assets | G2 / #13 |
| Stack inference depends on a short curated signal vocabulary | src/discover.ts enrichers look for React, Next.js, Astro, Svelte, Hono, Express, Fastify, NestJS, Supabase, Apify, Playwright, OpenAPI, Terraform, Docker, MCP, and a few text markers | Detection quality falls off rapidly outside the explicitly encoded ecosystems | High | Move stack detection to a modular signature registry with broader ecosystem coverage and easier extension | Adding a new stack does not require editing monolithic detection logic | G3 / #14 |
| Package-registry exploration is not generic | collectPackageCandidatesFromDemandProfile() maps only a small set of signals to packages such as typescript, @playwright/test, @modelcontextprotocol/sdk, openapi-typescript, @supabase/supabase-js, react, next, fastapi, and terraform | Marketplace-backed discovery does not generalize to arbitrary ecosystems or domains | High | Replace hardcoded package candidate mapping with dependency graph extraction and ecosystem-aware package scoring | Registry discovery can surface relevant packages from actual repo dependencies across multiple ecosystems | G4 / #17 |
| Non-code folders are likely to be scanned but not understood | The scanner walks broadly, but enrichment is limited to package.json and actor.json plus static filename signals | Large folders full of documents, media, CAD assets, notebooks, or research artifacts incur scan cost with little benefit | Medium | Add file-family detectors for markdown-heavy knowledge repos, notebooks, data folders, media projects, and engineering artifact sets | Pure research or design repos produce targeted signals instead of near-empty profiles | G5 / #15 |
| "No manual configuration" is not realistic today | Source seeds, domain coverage, and repo-type assumptions all favor a specific agent-tooling workflow | Many real-world repos will require added source packs, new detector signatures, or source config changes | High | Introduce optional auto-generated local source templates, detector plugins, and host-specific defaults that derive from the current machine and repo contents | New user on a fresh machine can run the pipeline on common repo archetypes without editing checked-in config | G6 / #16 |
Gap Matrix 3: Source Discovery and Stack Detection Robustness and Efficiency
| Gap | Current evidence | Impact | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|
| Recursive file walk is simple and unbounded | src/files.ts recursively traverses all directories outside a short ignore set with no depth, file-count, byte-size, or time budget | Large monorepos, generated-output repos, dataset repos, or media-heavy repos can be expensive to scan | High | Add scan budgets, optional depth caps, file-count ceilings, and early-stop heuristics; emit telemetry when the budget truncates scanning | Demand profiling remains fast and predictable on very large repos | D1 / #24 |
| Ignore list is helpful but shallow | src/files.ts ignores .git, .idea, .next, .nuxt, .tmp, build, coverage, dist, node_modules, and vendor | Many heavy directories common in other ecosystems are still traversed | Medium | Extend ignore profiles for common generated folders across Java, .NET, Python, data, game dev, CAD, media, ML, and embedded toolchains | Scan cost remains controlled across common repo archetypes | D2 / #25 |
| Enrichment logic is concentrated in a small number of special cases | src/discover.ts only deeply enriches package.json and actor.json | Detection robustness is fragile outside these file types | High | Add parsers for more ecosystems and make enrichers pluggable by file type | Multiple ecosystems get first-class enrichment instead of fallback keyword matching | D3 / #26 |
| Detection quality is hard to measure objectively | Current validation includes recommendation fixtures but not a broad corpus of real repo archetypes | It is difficult to know what classes of projects are detected well versus poorly | High | Build a fixture corpus covering web, mobile, backend, infra, AI/ML, notebooks, research, data engineering, hardware, game dev, CAD, media, security, and mixed monorepos | Coverage reports show precision and recall by repo archetype | D4 / #27 |
| Efficiency is not benchmarked | No performance budget or benchmark harness is enforced in CI | Performance regressions can accumulate silently | Medium | Add benchmark fixtures and CI thresholds for demand-profile generation time and scanned-file volume | Scan time and memory stay within explicit limits across standard fixture sizes | D5 / #28 |
| Signal model is static and centralized | src/discover.ts contains hardcoded signal rules and keyword lists | Extending support becomes slower and riskier as the file grows | Medium | Refactor into data-driven detector modules or JSON/YAML signature packs with tests | New stack signatures can be added with isolated tests and minimal core-code change | D6 / #29 |
Gap Matrix 4: Source Breadth and Diversity vs Effective Coverage
| Aspect | Current state | Strength | Limitation | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|---|
| Configured source count | 30 configured sources across docs, repos, marketplace, registry, package-registry, local-manifest, and local-directory | Good initial breadth for an agent-tooling supply chain | Breadth in config does not equal breadth in active harvesting | Medium | Track configured-vs-effective source utilization in reporting | Reports clearly distinguish dormant from active source kinds | S1 / #18 |
| Authority mix | Weighted toward official-first-party sources | Good trust posture and lower supply-chain risk | Weak long-tail coverage for niche ecosystems and community innovation | Medium | Add more vetted, domain-specific community sources with tiered trust policies | Niche stacks have at least one trusted source path without reducing trust posture | S2 / #19 |
| Marketplace presence | VS Code Marketplace, npm, and PyPI are represented in config | Good theoretical reach | Only package registries are actively harvested in generateCatalog(); marketplace and generic registry entries are not directly harvested | High | Implement active marketplace and docs/registry harvesters or remove dormant source kinds from default claims | Every declared source kind has an operational harvesting path | S3 / #20 |
| Docs sources | Docs sources exist in config | Useful for future breadth | Docs are not currently first-class harvested inputs in the main catalog pipeline | Medium | Add docs harvesters that convert trusted docs into instruction/reference assets consistently | Docs sources contribute measurable catalog entries | S4 / #21 |
| Package registries | npm and PyPI are operational | Real external discovery path exists | Candidate generation is narrow and hardcoded, so effective breadth remains small | High | Feed registries from actual dependency manifests and broader detector outputs | Package-registry coverage reflects actual repo dependencies | S5 / #22 |
| Local sources | Local seeds increase personalization and immediate utility | Helpful on the original machine | They are machine-specific and Windows-specific in checked-in config | High | Generate local sources dynamically per user and OS instead of committing personal absolute paths | Fresh clones on any supported OS get usable local source seeds | S6 / #11 |
| Repo sources | GitHub repo harvesting is the dominant active discovery mechanism | Strong for curated agent ecosystems | Strong bias toward repos that already follow skills/agent conventions | Medium | Add repo archetype detection independent of agent-file conventions | Non-agent repos can still yield relevant assets or recommendations | S7 / #23 |
Gap Matrix 5: Automatic Wire-In for Plugins, Extensions, and MCP Servers
| Gap | Current evidence | Impact | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|
| Automatic wire-in is file-based curation, not full native installation | src/pipeline.ts runs discover → mirror → install → activate → wire, and src/install.ts stages mirrored assets into install/<host>/packages/... | The flow is automated for internal asset projection, but users may assume it also installs native IDE extensions | High | Explicitly separate stage, activate, and native-install concepts in the model and CLI; add native installers only where the host supports them | CLI output and docs distinguish staged assets from truly installed host-native integrations | W1 / #30 |
| VS Code plugin support is implemented, but extension installation is not | src/host-vscode.ts wires chat.pluginLocations, chat.agentSkillsLocations, chat.agentFilesLocations, and related paths; no extension install path exists | Plugins can be materialized into curated locations, but VS Code extensions are not first-class installed assets | High | Add an extension installer abstraction for hosts that support marketplaces, and track extension selections separately from plugins | A selected VS Code extension asset can be discovered, chosen, installed, verified, and removed | W2 / #31 |
| Extension assets exist in the type system but not in the VS Code profile | src/types.ts includes AssetKind = "extension", but CopilotWorkspaceProfileManifest has selectedPluginIds and no selectedExtensionIds | Extension discovery can be represented in theory, but activation and user selection do not model it completely | High | Extend activation manifests and workspace profile manifests with explicit extension selections and lifecycle metadata | Extension assets appear in activation manifests and workspace profiles with round-trip fidelity | W3 / #32 |
| MCP servers are bundled as shared assets, but host wire-in is incomplete | src/mirror.ts routes mcp-server assets into shared-mcp; src/pipeline.ts activates shared; host wire code reads host-specific activation roots only | Shared MCP assets may be discovered and activated, but they are not consistently projected into each host’s wire-in | High | Define a host-consumable shared asset projection layer so shared MCP assets can be surfaced into each supported host intentionally | Shared MCP assets are visible in effective wire plans for all hosts that claim MCP support | W4 / #33 |
| Automatic auth-aware setup assistance is not implemented | Source fetching uses GitHub token env vars in src/github.ts, src/discover.ts, and src/asset-content.ts; no plugin/extension/MCP auth onboarding exists | Assets that require API keys, OAuth, or provider-specific login still require manual setup outside the harness | High | Introduce an auth-capability model per asset and a CLI assistance flow that can prompt for prerequisites, validate env vars, and emit host-specific setup guidance | Selecting an auth-required asset triggers prerequisite checks and guided setup before wire-in | W5 / #34 |
| Installation does not validate host runtime readiness | The current install step copies curated content, but does not verify marketplace availability, CLI presence, login state, or MCP runtime compatibility | Users can reach a “wired” state that still fails at runtime because host prerequisites are unmet | Medium | Add preflight checks for required CLIs, host versions, authentication state, and external runtime dependencies | workspace and wire commands fail fast with actionable prerequisite diagnostics | W6 / #35 |
| User assistance is implicit rather than explicit | The CLI orchestrates pipeline stages, but there is no dedicated interactive setup mode for asset-specific onboarding | New users will not get guided help for auth, marketplace sign-in, or provider-specific post-install configuration | Medium | Add a setup or doctor workflow that explains required actions per selected asset and can optionally open relevant login/setup URLs | A first-time user can complete asset onboarding from a guided CLI flow without reading source code | W7 / #36 |
Gap Matrix 6: Extending to Additional AI Agents and IDEs
| Gap | Current evidence | Impact | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|
| Host support is encoded as a closed set | src/types.ts defines HostTarget as a three-value union for copilot-vscode, opencode, and shared | Adding Claude Code, Cursor, Zed, Codex, Droid, Pi Agent, or others requires core-code edits rather than registration | High | Replace the closed union with a host registry or adapter contract loaded from declarative host definitions plus typed handlers | New hosts can be added without editing central host unions across the codebase | H1 / #37 |
| Workspace orchestration only targets VS Code and OpenCode | src/workspace.ts and src/wire.ts dispatch only vscode and opencode targets | New IDEs and agent hosts cannot participate in the main end-to-end workflow without bespoke command changes | High | Refactor workspace and wire commands around host adapters with a discovery-based dispatch layer | workspace and wire accept any registered host adapter | H2 / #38 |
| Pipeline bundle defaults are host-specific and hardcoded | src/pipeline.ts selects bundle IDs per host, and src/activate.ts hardcodes default bundle IDs for copilot-vscode, opencode, and shared | Each new host currently needs multiple synchronized code changes to declare defaults and bundle behavior | High | Move bundle defaults, asset policies, and host capabilities into per-host configuration objects or manifests | A new host can declare defaults in data rather than in multiple switch statements | H3 / #39 |
| Host wire behavior is implemented as bespoke modules | src/host-vscode.ts and src/host-opencode.ts each contain custom path resolution, materialization, and settings patch logic | Extension to another host requires writing a new host module from scratch instead of reusing a common contract | Medium | Introduce a reusable host adapter interface covering curated roots, asset projection, settings patching, and reset behavior | Most host implementations share a common adapter skeleton with limited custom code | H4 / #40 |
| Asset-to-host compatibility is not yet capability-driven | Asset kinds and host folders are partly encoded in host-specific logic, not in a generalized capability model | It is difficult to reason about which hosts support plugins, instructions, MCP servers, hooks, or extensions | Medium | Add a capability matrix that maps asset kinds to supported host behaviors such as stage, wire, native install, auth assist, and runtime validation | Host support can be reasoned about from a single compatibility model | H5 / #41 |
| Recommendation and selection flows are tuned to current hosts | Activation and workspace profile generation are shaped around Copilot VS Code and OpenCode manifests | New hosts risk partial support unless recommendation, activation, and profile emission are generalized | Medium | Generalize profile emission and recommendation sinks so each host can produce its own selected-assets manifest without changing core recommendation semantics | New host support includes recommendation, activation, and wire plan generation end to end | H6 / #42 |
| The architecture is extensible in concept, but not yet in effort | The staged lifecycle already exists: discover, mirror, install, activate, wire | The project is not boxed in, but “easy extension” is overstated until host abstractions are cleaned up | Medium | Preserve the existing staged pipeline, but refactor around host adapters and shared capability descriptors before adding the next 2 to 3 hosts | Second and third non-default hosts can be added with mostly declarative configuration changes | H7 / #43 |
Gap Matrix 7: Project Refactor and Internal Architecture Scalability
| Gap | Current evidence | Impact | Severity | Concrete remediation | Exit criteria | Implementation issue |
|---|---|---|---|---|---|---|
| The source tree is flat rather than domain-oriented | src/ currently contains 23 root-level .ts files and no services, config, utils, factories, or similar subdirectories | The project is harder to navigate, onboard into, and extend safely as more features and hosts are added | High | Reorganize into domain modules such as domains/discovery, domains/install, domains/activation, domains/wire, plus shared lib, config, and host-adapters packages | New contributors can locate concerns by domain instead of memorizing root-level filenames | A1 / #1 |
| Several files have already become oversized | Top file sizes include src/discover.ts (3191 lines), src/recommend.ts (1784), src/manifest-validation.ts (1269), src/install.ts (928), src/mirror.ts (806), and src/activate.ts (724) | Large files increase review cost, hide regressions, and make safe refactoring materially slower | High | Split large files into focused modules with single responsibilities, preserving stable public entrypoints while moving internal logic into smaller collaborators | No core module exceeds an agreed size budget unless explicitly justified | A2 / #44 |
| Complex orchestration and classification logic is concentrated | In src/discover.ts, key hotspots include generateCatalog around line 177, collectPackageCandidatesFromDemandProfile around line 622, and classifyLocalDirectoryFile around line 1426 | Discovery behavior becomes difficult to reason about, test in isolation, and optimize without unintended side effects | High | Extract scanning, enrichment, classification, and candidate-scoring into dedicated services and strategy modules with narrow interfaces | Major workflows can be unit-tested in isolation without loading the full discovery pipeline | A3 / #45 |
| Configuration handling is scattered across multiple modules | process.env is read directly in src/discover.ts, src/github.ts, src/mirror.ts, src/rebuild.ts, src/pipeline.ts, src/host-vscode.ts, and src/asset-content.ts; no .env* template files were found in the repo | Runtime behavior is harder to validate centrally, and configuration drift or missing env vars is easier to miss | High | Introduce a centralized config loader with schema validation, typed accessors, documented defaults, and a checked-in .env.example; keep real .env files local and out of version control | All environment access flows through a single validated config module | A4 / #2 |
| Shared abstractions are weakly expressed | No class declarations were found under src/**/*.ts, and there are no dedicated service/factory directories; most behavior is encoded in large functional modules | The issue is not “must use classes everywhere,” but missing boundary objects and factories make lifecycle and dependency management harder | Medium | Introduce explicit service boundaries where they add value, along with factories/builders for host adapters, source handlers, registry clients, and wire-plan generation | Core workflows are composed from named services/factories rather than implicit large-file helper clusters | A5 / #3 |
| Types and validation are centralized into broad shared files | src/types.ts is 696 lines and src/manifest-validation.ts is 1269 lines | A small change in one area forces developers to reason about unrelated types and validation rules elsewhere | Medium | Split shared types and schemas by domain, and colocate validators with the manifests or asset families they govern | Type and validation changes are localized to the owning domain | A6 / #46 |
| Security and runtime checks are not centralized as first-class layers | Environment/config checks, host readiness, and asset-specific prerequisites are currently spread across command handlers and host modules | Security posture and runtime diagnostics depend too much on call-site discipline instead of a reusable verification layer | Medium | Add shared preflight, config validation, and policy-check layers invoked consistently by CLI commands and host adapters | Commands fail consistently through shared validation layers with uniform diagnostics | A7 / #4 |
| There is no explicit refactor seam for future package/workspace split | The current implementation is a single package with a single src root, even though the code already has distinct domains like discovery, mirror, install, activation, recommendation, and host wiring | Future scaling into libraries, plugins, or separate runtime packages will be more expensive than it needs to be | Medium | Refactor toward internal package-style boundaries now, even if staying in one npm package initially; keep domain APIs stable enough to support a later workspace split if needed | The codebase can evolve into multiple internal packages without rewriting business logic | A8 / #47 |
Recommended Phasing
| Phase | Goal | Key deliverables | Tracking item |
|---|---|---|---|
| Phase 0 | Establish modular architecture foundations | Create domain folders, central config loading, shared validation/preflight layers, and internal service/factory seams | M0 / #48 |
| Phase 1 | Make the project genuinely cross-platform | Remove hardcoded Windows local paths, replace APPDATA/USERPROFILE assumptions, add OS matrix CI | M1 / #49 |
| Phase 2 | Separate generic repo understanding from agent-asset harvesting | Add a generic repo classifier layer and pluggable detector modules | M2 / #50 |
| Phase 3 | Turn configured source breadth into effective source breadth | Implement harvesters for docs, marketplace, and registry sources that are currently only declarative | M3 / #51 |
| Phase 4 | Make detection measurable and scalable | Add archetype fixture corpus, benchmark suite, coverage reporting, and scan budgets | M4 / #52 |
| Phase 5 | Make wire-in truly host-aware and user-assistive | Add native install support where applicable, auth-aware setup guidance, preflight checks, and shared MCP projection | M5 / #53 |
| Phase 6 | Generalize host support beyond VS Code and OpenCode | Introduce host adapters, capability matrices, declarative host registration, and pilot integrations for new IDEs | M6 / #54 |
| Phase 7 | Reduce file and function complexity | Split oversized modules, localize types/validation, and enforce complexity/size budgets in CI | M7 / #55 |
Suggested Success Metrics
| Area | Metric |
|---|---|
| Portability | Full pipeline and wire-in preview/apply/reset pass on Windows, Ubuntu, and macOS |
| Repo coverage | Fixture corpus spans at least 20 repo archetypes with acceptable detection quality |
| Source effectiveness | Each configured source kind contributes actual harvested entries or is explicitly marked dormant |
| Efficiency | Demand-profile generation stays within defined file-count and runtime budgets on large fixture repos |
| Extensibility | New detector signatures can be added without editing the central detection function |
| Wire-in automation | Selected assets can be staged, validated, authenticated if needed, and projected into the target host without undocumented manual steps |
| Host expansion | A new AI agent or IDE host can be added through a bounded adapter surface and configuration rather than multi-file core rewrites |
| Code organization | Most source files live under domain folders with clear ownership, and root-level orchestration files remain intentionally small |
| Configuration safety | All runtime configuration is schema-validated centrally, documented via .env.example, and never read ad hoc throughout the codebase |
| Complexity control | Core modules and functions stay under agreed size and complexity budgets enforced by CI |