drm-copilot is a mixed Python + VS Code extension workspace for packaging, publishing, and validating agentic development customizations. It provides a runtime that maps a single orchestration model onto three coding-agent ecosystems — GitHub Copilot, Claude Code, and Codex — and ships the tooling needed to author, distribute, and enforce that model.
The repository contains four primary deliverables:
a under , , , and that defines standing instructions, skills, subagents, rules, and enforcement hooks;
Stdio MCP server exposing drm-copilot repo-automation tools.
2026-11-16
星數
—
工具
—
可用率
—
multi-ecosystem agentic runtime
.github/
.claude/
.codex/
.agents/
a VS Code extension and stdio MCP bridge in extensions/drm-copilot/ that runs bundled scripts against the active workspace and exposes them as MCP tools;
a standalone npm MCP package in packages/mcp-server/ that publishes the same stdio MCP server for npx or global npm usage outside the VS Code extension host.
a Python/Poetry toolchain at the repo root for documentation, context collection, customization conversion/publishing, shell quality checks, and developer workflows, plus a per-language quality toolchain for Python, TypeScript, PowerShell, modern C# (.NET 8+, No-COM), legacy VSTO C# (.NET Framework), and Bash;
scripts/powershell/ — PowerShell tooling, including the PoshQC quality module.
scripts/bash/ — shell tooling validated by bash scripts/bash/shell-qc.sh.
extensions/drm-copilot/ — the VS Code extension that bundles and executes workspace-facing helpers and hosts the MCP server.
packages/mcp-server/ — the standalone npm package for the drm-copilot stdio MCP server.
.github/ — GitHub Copilot customization surface: copilot-instructions.md, instructions/, prompts/, skills/, agents/, codex/, and CI workflows.
.claude/ — the Claude Code runtime surface: rules/, skills/, agents/, hooks/, agent-memory/, and settings.json.
.codex/ and .agents/ — the Codex-native runtime surface: prompts and skills.
docs/features/ — feature, backlog, and planning documents, organized into potential/, active/, completed/, archive/, and research/. Multi-feature epics use docs/features/epics/<epic-slug>/epic.md as their single home once created (see Epic orchestration below).
CLAUDE.md and AGENTS.md — generated standing-instruction roots for Claude Code and Codex respectively.
Agentic runtime architecture
The repository maintains parallel customization surfaces for three coding-agent ecosystems, derived from one canonical policy set. The Claude Code surface (.claude/, documented in CLAUDE.md) is the primary runtime and follows a four-layer architecture.
Standing instructions — CLAUDE.md and .claude/rules/ provide persistent policy context. CLAUDE.md carries repository-wide tone, the policy-compliance reading order, and architectural context. Rule files carry language-specific toolchain and coding standards, scoped by file path through YAML frontmatter (for example python.md, typescript.md, powershell.md, csharp.md, quality-tiers.md, architecture-boundaries.md, orchestrator-state.md, ci-workflows.md, benchmark-baselines.md).
Skills — .claude/skills/ define reusable, user-invocable workflows. Each SKILL.md declares its own allowed-tools, context, and agent routing. The catalog includes orchestrate, epic-orchestrate, feature-promotion-lifecycle, atomic-plan-contract, execute-hard-lock, feature-review-workflow, pr-author, pr-context-artifacts, pr-base-branch-merge-base, commit-message, research-issue, acceptance-criteria-tracking, policy-compliance-order, evidence-and-timestamp-conventions, the per-language change-budget routers and QA gates (python-, powershell-, csharp-), the orchestration state machines, remediation-handoff-atomic-planner, human-exception-runbook, the review skills (review-feature, review-epic, review-staged), and the cross-ecosystem translator translate-copilot-to-claude (Claude-to-Codex conversion is handled by the Codex-native converter described below, not a separate translator skill).
Subagents — .claude/agents/ define named specialist personas, each declaring its tool allowlist, model, preloaded skills, hooks, and memory scope. The current roster is orchestrator, epic-orchestrator, atomic-planner, atomic-executor, feature-review, epic-review, staged-review, task-researcher, prd-feature, status-updater, pr-author, commit-message, human-exception-runbook, and the language engineers python-typed-engineer, typescript-engineer, powershell-typed-engineer, and csharp-typed-engineer.
Enforcement — .claude/settings.json defines tool/path permissions, and .claude/hooks/ contains PreToolUse and SubagentStop scripts that block dangerous commands and validate completion gates (for example enforce-pr-author-skill.ps1, enforce-promotion-mcp-only.ps1, enforce-orchestration-preimplementation-gate.ps1, enforce-checkpoint-monotonic.ps1, the per-language batch-budget and test-purity checks, and the validate-*-output.ps1 gates for each subagent).
Orchestration model
The runtime is orchestrator-driven. The orchestrator agent runs in the main thread and delegates all deep implementation to specialist subagents; it does not implement directly when a delegated specialist exists.
Startup — on each invocation the orchestrator reads CLAUDE.md, the applicable .claude/rules/ files, and the checkpoint at artifacts/orchestration/orchestrator-state.json, resuming from the recorded next_step when a matching objective exists.
Change-budget routing — the orchestrator first estimates the change budget. A small path (1–3 production files plus tests) runs promotion → active folder → minimal plan → implementation → QC → small-audit review. A large path (4+ production files or cross-cutting changes) runs scope → promotion → research → spec → atomic planning → atomic execution → feature review.
Delegation — planning goes to atomic-planner, task-by-task execution to atomic-executor, audits to feature-review/epic-review/staged-review, investigation to task-researcher, and PR creation exclusively to pr-author (the only authorized caller of gh pr create/gh pr edit --body, gated by the enforce-pr-author-skill.ps1 hook, which verifies a SHA-256 receipt that binds the --body-file body bytes to a sibling artifacts/pr_body_<N>.receipt.json).
Checkpointing — the orchestrator persists artifacts/orchestration/orchestrator-state.json after every completed step, including the selected path, workflow variables, per-step statuses, delegation receipts, and any blocked reason. The structural invariants are enforced by validate_orchestration_artifacts and scripts/dev_tools/validate_orchestrator_state.py.
Memory — agents maintain persistent, file-based, project-scoped memory under .claude/agent-memory/, indexed per agent in a MEMORY.md.
Epic orchestration
The epic-orchestrate skill and the epic-orchestrator agent schedule a multi-feature epic as a dependency graph of child features, run each child through the standard orchestrator lifecycle in parallel, isolated git worktrees, and fan the results back into a shared integration branch before driving the final integration-to-main PR. An epic's dependency manifest and free-text narrative (goal, scope, non-goals, shared design, decomposition) live together in a single home, docs/features/epics/<epic-slug>/epic.md, whose YAML frontmatter is the machine-parsed source of truth and whose body is the human-readable narrative and the source for the epic's GitHub issue body.
Other ecosystem surfaces
The .github/ directory mirrors this model for GitHub Copilot (copilot-instructions.md, instructions/*.instructions.md, skills/, prompts/). The .codex/ and .agents/ directories provide the Codex-native equivalent (prompts plus .agents/skills/). The canonical policy source is the .github/instructions/* set; the other surfaces mirror or are generated from it (see the Codex-native converter and the push-down tools). The published MCP server is the runtime bridge that exposes the repository automation tools to all three ecosystems.
Root Python tooling
The Poetry project (drm-copilot, see pyproject.toml) provides CLI entrypoints and supporting modules for tasks such as:
collecting commit context and PR context;
converting customization trees between ecosystems (Codex-native converter);
publishing customization trees into another workspace;
JSON formatting/validation and Markdown label formatting;
shell quality checks;
feature-folder, potential-entry, and issue-support workflows;
The Codex-native converter is a Python-first workflow that reviews or applies a deterministic migration from GitHub Copilot or Claude runtime customization surfaces into the native Codex layout. The Python CLI is the authoritative converter surface; the VS Code command and MCP tool are thin wrappers over the same bundled Python runner.
Review and apply commands
Review mode: poetry run codex-native-converter review --source-root <source-root> --source-ecosystem <github-copilot|claude>
--selected-path <path> (repeatable) restricts the reviewed source surface.
--artifact-root <artifact-root> overrides the default report location.
--enable-repo-prompts allows .codex/prompts/** output when repository prompts are intentionally enabled.
Repo-wide GitHub instruction files that declare applyTo: "**" are merged into the generated AGENTS.md. Narrower .github/instructions/*.instructions.md files map to .agents/skills/**. GitHub prompt assets under .github/prompts/*.md are treated as optional launcher inputs and do not block validation by themselves when prompt output is disabled.
Artifact outputs
Each run writes a deterministic report set beneath the selected artifact root:
conversion-report.md (includes three Mermaid topology views of the source-to-destination mapping)
mapping-catalog.json
validation-results.json
proposed-tree/
The CLI prints the resolved artifact root and the final validation outcome to stdout so wrapper layers can surface or collect the generated evidence.
Fail-closed validation model
The converter blocks destination writes when it finds unresolved hard-gate mappings, unresolved handoff mappings, unresolved MCP rewrites, duplicate targets, lingering .github, .claude, or CLAUDE.md runtime references in generated native output, malformed artifacts, unsupported ecosystems, or missing required inputs. Review mode still writes the report set so the caller can inspect blocking findings without mutating the destination tree. The converter is implemented in scripts/dev_tools/codex_native_converter/, with modules split to satisfy the 500-line file-size policy.
VS Code extension
The active extension package lives in extensions/drm-copilot/. It contributes a VS Code command surface and a Codex-facing stdio MCP server named drm-copilot (contributed through an mcpServerDefinitionProviders entry). The extension is the authoritative development surface; packages/mcp-server/ provides an external distribution channel for the same MCP server source.
newClaudeWorktreeSession creates or reuses a git worktree, optionally activates the workspace Poetry environment, runs an optional pre-session PowerShell script, and starts claude in an integrated terminal. The pre-session script path defaults to .claude/hooks/pre-claude-session.ps1 and is configurable via drmCopilotExtension.newClaudeWorktreeSession.preClaudeScriptPath. A missing script at that path is not an error.
newCodexWorktreeSession performs the equivalent flow for Codex: it adds the worktree to the Codex trusted-projects list, runs an optional post-session script (default .codex/scripts/post-codex-worktree-session.ps1, configurable via drmCopilotExtension.newCodexWorktreeSession.postCodexScriptPath), and starts codex.
removeSecondaryWorktrees removes secondary git worktrees created by these commands.
MCP tool surface
The drm-copilot MCP server exposes the following repo-automation tools (tool prefix mcp__drm-copilot__ when consumed by Claude Code):
collect_commit_context
collect_pr_context
run_codex_native_converter
push_down_copilot_customizations
push_down_codex_and_agents_customizations
push_down_claude_customizations
new_potential_entry
new_potential_bug_entry
potential_to_issue
new_active_feature_folder
link_parent_child
run_poshqc_format
run_poshqc_analyze
run_poshqc_test
run_poshqc_analyze_autofix
run_poshqc_suite
resolve_policy_audit_template_asset
resolve_execute_hard_lock_prompt
resolve_atomic_plan_prompt
validate_orchestration_artifacts
Every tool requires a workspace_root argument. The MCP server cannot infer the calling agent's checkout, so callers must pass the absolute worktree/checkout root explicitly; an omitted value returns a structured ok: false error rather than silently defaulting. Downstream skills should depend on the MCP server name drm-copilot rather than on raw VS Code command IDs. The same tool surface is available through the published npm package @danmoisan/drm-copilot-mcp.
Standalone npm MCP package
packages/mcp-server/ publishes the same stdio MCP server implemented in extensions/drm-copilot/src/mcp-server.ts, so consumers can run the server without cloning this repository or building from source.
Consumer usage
npx -y @danmoisan/drm-copilot-mcp
npm install -g @danmoisan/drm-copilot-mcp
drm-copilot-mcp
MCP client configuration
Add the following to an MCP client configuration file such as claude_desktop_config.json:
Set cwd to the absolute path of the destination workspace root. Tool callers must still pass workspace_root explicitly on each call; it is a required argument and the server does not infer a default workspace root.
Package behavior and contents
The published package name is @danmoisan/drm-copilot-mcp.
The package bundles extensions/drm-copilot/src/mcp-server.ts into packages/mcp-server/out/mcp-server.js as a CommonJS executable with a #!/usr/bin/env node shebang.
The prepack flow copies extensions/drm-copilot/resources/ into packages/mcp-server/resources/ so the published tarball contains the script-backed tools and templates required at runtime.
The npm tarball intentionally includes only out/mcp-server.js and resources/.
The MCP tool API surface matches the VS Code extension.
Local package build and validation
Run the standalone package workflow from the repository root:
The repository can publish each scoped customization tree into another workspace from the Python CLI, a VS Code command, or an MCP tool.
Surface
Python entrypoint
VS Code command
MCP tool
Copilot (.github)
poetry run python -m scripts.dev_tools.push_down_copilot_customizations --destination <root>
pushDownCopilotCustomizations
push_down_copilot_customizations
Codex + agents (.codex, .agents)
poetry run python -m scripts.dev_tools.push_down_codex_and_agents_customizations --destination <root>
pushDownCodexAndAgentsCustomizations
push_down_codex_and_agents_customizations
Claude Code (.claude, config/, CLAUDE.md)
bundled publisher
pushDownClaudeCustomizations
push_down_claude_customizations
During Copilot publication, supported script references are rewritten to stable live VS Code command references contributed by the extension. The Claude push-down tool accepts optional packs (language pack selection; core is always included), a csharp_variant (modern default or legacy), and a memory_mode (overwrite default, merge, or skip).
Destination exclusion manifest
A destination repository can keep specific Claude push-down payload paths out of its tree by committing a manifest at .push-down-exclusions in the destination root. The file sits outside every published root, so the push-down never writes, merges, or deletes the manifest; this repository ships no manifest and does not deliver one. The Copilot and Codex publishers do not read it.
Grammar:
The file is UTF-8 text; a leading byte-order mark is stripped, and line endings may be LF or CRLF.
One entry per line. Blank lines and lines whose first non-blank character is # are ignored, so each entry can carry a comment with its reason and issue reference.
Each entry is a destination-relative POSIX path. Normalization trims surrounding whitespace, converts \ to /, strips one leading ./, and collapses repeated /.
An entry without wildcards matches a payload path exactly, or as a directory prefix: foo/bar matches foo/bar and every path under foo/bar/. A trailing / is optional and only documents intent; foo/bar and foo/bar/ match the same set.
An entry containing * or ? is a wildcard entry matched against the whole path: ** matches any run of characters including /, * matches any run excluding /, and ? matches exactly one character other than /. Every other character is literal.
Comparison is ordinal and case-sensitive; an entry must use the bundle's canonical case.
Entries are evaluated in file order, and the first matching entry is the one reported for a path.
A malformed manifest fails the run with ExclusionManifestError before any destination write. The error names the manifest path .push-down-exclusions and, where one applies, the offending line number. The eight malformed conditions are: the manifest path is not a regular file; the text is not valid UTF-8; an entry is empty after normalization; an entry is absolute (leading / or a drive prefix such as X:); an entry contains a .. segment; an entry begins with !; an entry contains [ or ]; an entry combines a wildcard with a trailing /. A manifest containing only comments and blank lines is valid and filters nothing.
A matched payload path is not written. Each skipped path and each entry that matched no payload path is reported with one line:
push-down exclusion: skipped <path> (entry <normalized>, line <n>) when the destination holds no file at the path.
push-down exclusion conflict: destination file present, not overwritten: <path> (entry <normalized>, line <n>) when the destination already holds a file at the path. The destination bytes are unchanged and the run still succeeds.
push-down exclusion: entry matched no payload path: <normalized> (line <n>) for a stale or out-of-scope entry. This is not an error.
These lines appear in the summary artifact's exclusions object (with conflict_count, entries, manifest_path, skipped, skipped_count, and unmatched_entries), in the MCP result's warnings field, in the drm-copilot output channel, and on Python CLI stdout after the Wrote push-down summary artifact to: line. The VS Code command additionally shows a warning notification when at least one conflict is reported. When no manifest exists, behavior is unchanged: no exclusions key, no warnings field, no additional lines, and no notification.
Limitations: the push-down never deletes destination files, so a file already present at an excluded path is removed by the destination once. Detection of dangling references (an excluded file that other pushed-down content still cites) is a non-goal of this feature and is not reported.
Sync AGENTS.md from instructions
drmCopilotExtension.syncAgentsFromInstructions regenerates AGENTS.md in the destination workspace by discovering all .github/instructions/*.instructions.md files under the active workspace root, aggregating their content deterministically, and writing the consolidated result. This replaces any manual edits to AGENTS.md with a fully generated output derived from the canonical instruction files.
Requirements
Root toolchain
Python 3.10+
Poetry
Extension development
VS Code (engine ^1.138.0)
Node.js 20+ recommended
npm
Standalone MCP package
Node.js 18+
npm or npx
Runtime expectations for extension and MCP commands
Python commands expect python on PATH.
PowerShell commands prefer pwsh and fall back to powershell on Windows when available.
An open workspace folder is required for workspace-targeted extension commands.
The MCP bridge must be built before launch: npm --prefix extensions/drm-copilot run build.
The standalone npm package requires cwd in the MCP client configuration to point at the target workspace root.
Script-backed MCP tools require Python 3 and PowerShell 7+ on the consumer machine even when the server is started through npm.
The checked-in workspace settings pin the VS Code PowerShell extension to C:\Program Files\PowerShell\7\pwsh.exe on Windows so the Pester Test Explorer runs under PowerShell 7 instead of Windows PowerShell 5.1. If your local pwsh.exe lives elsewhere, override powershell.powerShellAdditionalExePaths and powershell.powerShellDefaultVersion in local VS Code settings.
Per-language toolchains (only when working in that language)
Python: Poetry-managed Black, Ruff, Pyright, and Pytest (installed via poetry install).
TypeScript: Node.js with Prettier, ESLint, tsc, and the configured test runner (installed via npm ci).
PowerShell: PowerShell 7+ and the bundled PoshQC module (PSScriptAnalyzer, Pester 5.x); install tooling with Install-PoshQCTools.
Modern C#: the .NET 8+ SDK with the CSharpier dotnet tool and the analyzer/test packages restored by the solution.
Legacy VSTO C#: the .NET Framework build toolchain (msbuild, vstest.console.exe) plus CSharpier.
Bash: shfmt, shellcheck, bats, and (for coverage) kcov.
Language toolchain ecosystems
The repository defines a separate, fully specified quality toolchain for each supported language. Every toolchain is run in a fixed stage order and the loop restarts from stage 1 whenever a stage fails or rewrites files. The canonical definitions live in .claude/rules/ and .github/instructions/. Coverage thresholds are uniform across all module tiers (T1–T4): line coverage >= 85%, with no regression on changed lines. Branch coverage >= 75% applies additionally to languages whose coverage tooling measures branch coverage; PowerShell (Pester) and bash (kcov) are exempt from the branch threshold because neither tool measures branch coverage, and they remain fully subject to the line threshold and the no-regression requirement.
test: poetry run pytest --cov --cov-branch --cov-report=term-missing
TypeScript (Prettier → ESLint → tsc → Vitest)
Canonical rule: .claude/rules/typescript.md. Architecture boundaries are enforced with dependency-cruiser (.dependency-cruiser.cjs); T1/T2 modules add fast-check property tests and T1 modules add StrykerJS mutation testing in pre-merge or nightly pipelines.
The bundled VS Code extension uses the same format/lint/type-check stages with a Jest-based unit runner. Run extension checks from the extension folder or with npm --prefix extensions/drm-copilot ...:
build: npm --prefix extensions/drm-copilot run build
format: npm --prefix extensions/drm-copilot run format
lint: npm --prefix extensions/drm-copilot run lint
type-check: npm --prefix extensions/drm-copilot run typecheck
unit tests: npm --prefix extensions/drm-copilot run test
Determinism is enforced through an injected TimeProvider (FakeTimeProvider in tests); DateTime.Now, DateTime.UtcNow, Random.Shared, Thread.Sleep, and Task.Delay are banned via BannedApiAnalyzers. T1/T2 modules add CsCheck property tests, T1 modules add Stryker.NET mutation testing, and T1 classifier modules add Verify.Xunit golden tests.
Legacy VSTO C# (.NET Framework)
Distributed as the csharp-legacy Claude pack (.claude-variants/csharp-legacy), selectable through the push_down_claude_customizations tool with csharp_variant: "legacy". It applies the same stage order on the .NET Framework / VSTO toolchain:
format: dotnet tool run csharpier format . (apply) and dotnet tool run csharpier check . (verify)
test: bash scripts/bash/shell-qc.sh test or bash scripts/bash/shell-qc.sh test --coverage (Bats with kcov coverage)
CI builds kcov from source and uploads the Bash coverage artifacts.
Development workflows
PowerShell repo session
To activate the workspace virtual environment and replace the default PowerShell prompt with a repo-relative prompt, run:
& ./scripts/dev-tools/Enter-DrmCopilotShell.ps1
When the current directory is inside this repository, the prompt renders as (drm-copilot):\ plus the relative path from the repo root.
Fix-all helper
poetry run dev.fix-all runs the available auto-fixing stages across the repository.
CI and release workflows
The repository uses the following GitHub Actions workflows under .github/workflows/:
ci.yml — Python quality and tests across Python 3.10–3.13, security scanning, documentation validation (README and LICENSE presence), package build/install verification, PowerShell formatting/analysis/tests (PoshQC on Windows), shell coverage (Bats + kcov), and extensions/drm-copilot tests on Ubuntu and Windows.
publish-mcp-npm.yml — tag-driven npm publication of @danmoisan/drm-copilot-mcp, gated on the extension test matrix.
publish-extension.yml — tag-driven publication of the VS Code extension to the Marketplace, gated on the extension test matrix; pull requests that touch the extension build and package without publishing.
npm-audit-gate.yml — npm dependency audit gate.
npm publish release procedure
Trigger: push a git tag matching mcp-server-v* such as mcp-server-v0.0.1.
Gate: the workflow runs the extension test matrix on Ubuntu and Windows before publish.
Publish steps: install packages/mcp-server dependencies, run prepack, build out/mcp-server.js, then npm publish --provenance --access public.
Credential: publication uses npm trusted publishing over OIDC (workflow permission id-token: write); no npm token secret is used.
Release prerequisite: keep packages/mcp-server/package.json and extensions/drm-copilot/package.json version values aligned before tagging.
VS Code extension release procedure
Trigger: push a git tag matching v*.
Gate: the extension test matrix runs before publish.
Publish: the workflow builds and packages the extension with @vscode/vsce and publishes with @vscode/vsce publish, using the repository secret VSCE_PAT.
Policy and skills references
Repository tone and policy: CLAUDE.md, .github/copilot-instructions.md, and .github/instructions/.