MetaFlow

AI metadata overlays for Copilot instructions, prompts, skills, and agents.

Features

• Overlay Resolution: Combine multiple repositories and enabled capabilities (instructions, prompts, skills, agents) into one effective workspace configuration.
• Synchronization with Provenance: Write files to .github/ with machine-readable provenance headers for traceability.
• Profile Management: Switch between profiles to enable/disable artifact subsets.
• Capability Management: Toggle individual capabilities on/off, bulk-toggle folder branches in tree mode, browse artifact contents under each layer, and work across multiple repositories.
• Capability Details Webview: Open a reusable capability-details panel that shows metadata, warnings, artifact inventory, and rendered CAPABILITY.md content.
• Drift Detection: Detect locally-edited synchronized files; protect from overwrite.
• Settings Injection: Configure Copilot alternate-path settings for settings-backed artifacts.
• TreeView UI: Visual tree views for config summary, profiles, capabilities, warnings, and effective files.

Recommended mode (automatic)

MetaFlow works best in automatic mode, which is the default.

• Set up .metaflow/config.jsonc once.
• Save config changes.
• MetaFlow refreshes and applies automatically.

Use command palette actions for diagnostics and explicit control, not as the primary day-to-day workflow.

Installation

Install from VSIX:

powershell -File ./scripts/install-vsix.ps1 -VsixPath ../<metaflow-release>.vsix -Cli code

Install the newest locally packaged VSIX automatically:

powershell -File ./scripts/install-latest-vsix.ps1 -WorkspaceRoot .. -Cli code -AllProfiles

# Install into stable and insiders across all local profiles
powershell -File ./scripts/install-latest-vsix.ps1 -WorkspaceRoot .. -Cli code,code-insiders -AllProfiles

Direct CLI fallback:

code --install-extension <metaflow-release>.vsix --force

If VS Code shows "Please restart VS Code before reinstalling ...", close all VS Code windows and run:

Stop-Process -Name "CodeSetup-*" -ErrorAction SilentlyContinue

Then retry the script command above.

Configuration

Create .metaflow/config.jsonc in your workspace root (or run MetaFlow: Initialize Configuration):

{
    "metadataRepos": [
        {
            "id": "primary",
            "name": "primary",
            "localPath": "../my-ai-metadata", // path to metadata repo clone
            "enabled": true,
            "capabilities": [
                { "path": "company/core", "enabled": true },
                { "path": "standards/sdlc", "enabled": false },
            ],
        },
    ],
    "filters": {
        "include": [],
        "exclude": [],
    },
    "profiles": {
        "default": { "enable": ["**/*"], "disable": [] },
        "lean": { "disable": ["agents/**"] },
    },
    "activeProfile": "default",
    "injection": {
        "instructions": "settings",
        "prompts": "settings",
        "skills": "synchronize",
        "agents": "synchronize",
    },
}

MetaFlow: Initialize Configuration seeds primary as enabled and discovered capabilities as disabled so capability activation is opt-in.

Legacy preview configs that still use metadataRepo, layers, or flat layerSources are accepted during the pre-release window. On load/open, MetaFlow rewrites them to the canonical repo-grouped metadataRepos[*].capabilities shape and shows a migration notice.

If enabled capabilities surface the same effective relative path, MetaFlow reports a warning in the Capabilities view, Preview, Status, and the apply summary. Apply remains non-blocking and uses the later-wins result selected by the engine.

Optional CAPABILITY.md per layer

Layer roots may include CAPABILITY.md to provide capability metadata consumed by MetaFlow.

---
name: SDLC Traceability
description: Shared SDLC traceability metadata.
license: MIT
---

• name and description are required.
• license is optional (MIT, Apache-2.0, MIT OR Apache-2.0, or SEE-LICENSE-IN-REPO).
• Unknown fields are tolerated with warning diagnostics.

This metadata is shown in metaflow status, in the Capabilities/Effective Files views, and in the capability details webview.

Capabilities tree branch toggles

When metaflow.layersViewMode is set to tree, folder rows in the Capabilities view expose checkboxes for branch-wide enable or disable operations.

• Checking a folder enables every descendant capability under that path prefix.
• Unchecking a folder disables every descendant capability under that path prefix.
• A folder checkbox is shown as checked only when every descendant capability is enabled.
• Mixed and fully disabled branches both render as unchecked, with the tooltip and description showing the enabled ratio for mixed branches.
• Concrete capability rows and artifact-type rows keep their existing checkbox behavior.

Artifact-type rows such as instructions, prompts, agents, and skills can also expand when the selected layer contains metadata under that class.

• Artifact-type rows stay toggleable at the class level.
• Nested folders and files under an artifact type are browse-only and do not expose checkboxes.
• Browse rows prefer frontmatter or manifest display names when available.
• Browse tooltips retain the canonical artifact path and description so friendly labels do not hide the internal identifier.

Optional METAFLOW.md per repository root

Metadata repository roots may include METAFLOW.md to provide repository-level metadata consumed by MetaFlow tooltips.

---
name: Primary
description: Shared repository-level metadata for this workspace.
---

• name and description are optional.
• The manifest is distinct from the repository README.md.
• Repository metadata is currently surfaced in repository tooltips.

Commands

Settings

Copilot settings injected by MetaFlow: Apply

• chat.instructionsFilesLocations (and legacy github.copilot.chat.codeGeneration.instructionFiles)
• chat.promptFilesLocations (and legacy github.copilot.chat.promptFiles)
• chat.agentFilesLocations
• chat.agentSkillsLocations
• chat.hookFilesLocations (file-based hook entries from hooks.preApply / hooks.postApply)

MetaFlow: Clean removes the above injected keys from workspace settings.

Architecture

The extension uses a pure TypeScript engine (no VS Code imports) for overlay resolution, enabling fast unit testing. The engine modules live in the workspace package at packages/engine/src/engine/ and handle:

• Capability resolution and file-map building
• Include/exclude filter evaluation
• Profile enable/disable pattern application
• Artifact classification (settings vs synchronized files)
• Provenance header generation and drift detection
• Synchronization with state tracking

VS Code integration (commands, views, diagnostics) wraps the engine in src/src/commands/ and src/src/views/.

Development

cd src
npm install
npm run compile
npm run test:unit    # unit tests
npm run gate:integration # integration tests (Extension Host)
npm run lint

Lint monitoring (non-blocking warnings)

Warnings are intentionally non-failing, but still monitored:

• npm run lint — runs ESLint; warnings are allowed.
• npm run lint:monitor — writes JSON report to .eslint-report.json.
• npm run lint:summary — prints totals and top warning rule IDs.
• npm run lint:monitor:summary — monitor + summary in one command.

Example summary output:

[lint-summary] files=28 errors=0 warnings=5

[lint-summary] top-warning-rules=@typescript-eslint/naming-convention:5

VS Code tasks

From Terminal → Run Task:

• MetaFlow: Lint Extension
• MetaFlow: Compile Extension (TS)
• MetaFlow: Test Extension Unit
• MetaFlow: Build Extension

The lint monitor and summary helpers are available as npm scripts rather than workspace tasks. Run npm run lint:monitor, npm run lint:summary, or npm run lint:monitor:summary from src/ when you need those reports.

GitHub CI and Release

This repository uses GitHub Actions to validate and publish the extension:

• .github/workflows/ci.yml runs npm run gate:quick (build + lint + unit tests) plus npm run gate:integration under headless xvfb-run on PRs and pushes.
• .github/workflows/release.yml packages and publishes on v* tags, and can also be triggered manually.

Publishing secrets

Set these repository secrets before publishing:

• VSCE_PAT — VS Code Marketplace Personal Access Token
• OVSX_PAT — Open VSX token

If one secret is missing, the workflow skips publishing to that marketplace and continues with any remaining configured target.

License

MIT