Project Change Router Skill

English version. The default Chinese README is README.md.

project-change-router is an AI coding skill for large repositories, usable from Codex, Claude Code, and DeepSeek Harness. Its goal is not to make agents guess architecture more aggressively. Its goal is to make agents guess less: before editing code, the agent should use a repository-local router bundle to get capability ownership, canonical-root signals, owners, read/write boundaries, reuse risks, and action guidance.

It addresses common structural drift in large projects:

• Agents have limited context and should not spend every task rereading an entire large full-stack repository.
• Agents can lose attention and overfit to local files or similar names.
• Reusable capabilities can be implemented twice, creating parallel implementation centers.
• Code that belongs in a shared lower-level capability can drift into a facade, API route, UI layer, or temporary folder.
• Empty, early, and rebuild repositories have unstable boundaries, so automatic inference can easily freeze temporary structure as architecture fact.

This skill provides a low-token, verifiable, calibratable project direction index and boundary guardrail. It does not replace detailed engineering analysis, and it does not make final architecture decisions for the user. It gives the agent direction, evidence, mandatory constraints, risk reasons, and calibration guidance before implementation starts.


Core Philosophy

Design principles:

• Guess less before trying to guess better. If evidence is weak, preserve unknown and use execution_gate=blocked instead of fabricating certainty.
• Prefer profile data over pure heuristics. Real owners, public entries, capability boundaries, and path patterns should be added to .project-change-router.yaml over time.
• Prefer structural evidence over name similarity. Paths, owners, public APIs, dependencies, and test bindings are more reliable than semantic similarity.
• Be conservative for early repositories. seed and emerging repositories should not automatically extend or extract too easily.
• review is not a failure or a write gate. It is an investigation direction in the advisory action layer; execution_gate decides whether writing is currently permitted.
• Route output is an integrated contract. The execution gate, safety envelope, and typed findings are mandatory; action and unblock suggestions guide the agent but do not replace source-code analysis.
• Results must get better over time. Human overrides, misroutes, profile fixes, and real cases should be written back into feedback and evaluation data.

Two-Layer Usage Model

PCR output has two layers. Do not interpret them as the same thing.

Mandatory guardrail layer:

• Read execution_gate.state first. pass, conditional, and blocked are the only authoritative write states.
• Respect allowed_write_paths, forbidden_write_paths, and must_read_before_edit.
• Identify and protect existing owners, public entries, canonical roots, and dependency direction.
• Do not create a second parallel implementation center when an existing capability may already exist.
• blocked forbids product-code writes. conditional requires every required_command and the bounded envelope. pass still cannot exceed that envelope.
• Trace vetoes, unknown evidence, lifecycle findings, high-risk overlap, and provisional boundaries to typed findings and policy rules; never hide them with an action label.

Advisory direction layer:

• action is the router's current processing tendency, not a final engineering command.
• recommended_next_steps, safe_next_steps, analysis_directions, why_not_actions, and profile_repair_hints are unblock directions and investigation prompts.
• action=review does not mean the task is impossible and does not automatically mean blocked. It prioritizes evidence gathering, profile repair, source reading, or coordination; execution_gate remains authoritative.
• The final implementation plan must still come from real source analysis, dependency tracing, tests, and user confirmation.

Scope

This skill can:

• Bootstrap a repository-local project-change-router/ bundle.
• Discover modules, capabilities, owners, public entries, path ownership, and dependency direction.
• Produce a route report from a request and changed path hints, including mandatory guardrails and advisory actions.
• Orchestrate route, freshness, dependency, public API, structure, governance, and reuse checks through run_change_flow.py, returning a compact safety envelope by default while persisting full evidence as a content-addressed artifact.
• Normalize gate evidence into traceable typed findings and reduce one authoritative gate through a single versioned policy table.
• Reuse trusted global snapshots through a changed-path-driven forward/reverse dependency closure instead of dropping global invariants.
• Split reuse coverage into independent intra-capability, cross-capability, and new/extract/lifecycle extended channels.
• Run guardrails for duplicate implementation, wrong boundaries, public API bypasses, reversed dependencies, and runtime cycles; TypeScript type-only edges are not misclassified as runtime edges.
• Check freshness from the current commit, a content-derived structure digest, indexed paths, stale entries, and actual changed-path coverage.
• Use exact baselines to stop net-new central-file growth, 800/1200-line threshold crossings, forbidden implementation roots, and second canonical owners.
• Generate path-to-capability-map.yaml to expose direct path ownership, shared ownership, and uncovered modules.
• Validate bundles and reports with schemas.
• Run evaluation cases to detect route quality regressions.
• Run governance audits for profile/catalog sync, ownership granularity, contract quality, forbidden density, evaluation coverage, and capability lifecycle metadata.
• Append marked hint blocks during Codex / Claude Code installation and publish the trigger description through the DeepSeek Harness skill catalog so agents are more likely to invoke the skill before feature-level create / modify / delete work.

It should not:

• Replace detailed code reading, dependency tracing, test design, or architecture analysis.
• Treat action as a final command that can be executed without analysis.
• Treat action=review itself as permission or denial; write authority comes only from execution_gate.
• Treat a generated-only bundle as mature architecture fact.
• Reuse or extend a capability only because its name looks similar.
• Create a second implementation center before confirming the canonical root.

Route Actions

resolve_entry.py emits five route actions. These actions are processing guidance and investigation direction, not final architecture commands:

• reuse: use an existing capability without modifying its core implementation.
• extend: add behavior through an existing shared capability or compatible extension point.
• extract: move repeated logic into a shared capability before callers reuse it.
• new: create a new isolated capability boundary because no safe reuse target exists.
• review: prioritize evidence gathering, profile repair, cross-capability coordination, or human confirmation. It neither grants nor removes write authority.

review needs special interpretation. It does not mean the system is useless, it is not a permanent block, and it is not a gate state. In an empty or early repository, a valid route can look like:

{
  "action": "review",
  "routing_confidence": 0.0,
  "routing_confidence_level": "low",
  "decision_confidence": 0.95,
  "decision_confidence_level": "high"
}

This means the router has no confidence about which capability should receive the change, but high confidence in its advisory action. Read execution_gate.state separately to determine write authority: an unindexed relevant path is blocked, while only trusted unrelated and non-expanding historical debt may be conditional.

Repository Stage Policy

The router infers repo_stage:

• seed: empty or very early repository; default to obvious new boundaries or review.
• emerging: some structure exists, but capability boundaries are still conservative; provisional boundaries should not become strong reuse targets automatically.
• structured: module boundaries are more stable; reuse, extend, and extract are more fully enabled.
• governed: routing is primarily driven by profile data, owners, public entries, evaluation, and guardrails.

Capabilities also have stages:

• provisional
• candidate
• stable
• governed-capability
• deprecated

Do not freeze generated capabilities too early. For early repositories, start with minimal ownership/profile data, then add capabilities, public entries, contracts, test bindings, and evaluation cases as real development confirms the boundaries.

Integrated Route Report

A route report is not just an action. It is a complete route contract. Core fields include:

• action
• decision_basis
• routing_confidence
• routing_confidence_level
• decision_confidence
• decision_confidence_level
• primary_capability
• primary_capability_stage
• secondary_capabilities
• candidate_capabilities
• required_reads
• required_checks
• recommended_next_action
• recommended_next_steps
• why_not_actions
• confidence_reasons
• veto_reasons
• positive_signals
• negative_signals
• risk_signals
• authorization_context
• route_fingerprint
• runtime_identity
• typed_findings
• execution_gate
• gate_shadow
• must_read_targets
• inventory_targets
• unresolved_read_targets
• authorization_request

The seven governance output groups are first-class fields in the same route report, not an external add-on:

• post-review handling: block_reason, missing_evidence, analysis_directions, safe_next_steps, suggested_questions, override_requirements
• write constraints: allowed_write_paths, forbidden_write_paths, must_read_before_edit
• profile repair direction: profile_repair_hints, plus repair_suggestions in governance audit reports
• post-change closeout: post_change_closeout
• delete, merge, and deprecation governance: capability_lifecycle_action
• cross-stack composite routing: composite_route
• real regression capture: evaluation_regression_hints

See [references/governance-outputs.md](./references/governance-outputs.md) for the detailed contract.


0.4 Execution Gate and Evidence Model

PCR 0.4 separates routing advice from write authority:

The gate performs no repository scan and no second routing pass. One versioned policy table deterministically reduces schema-valid typed findings. Every finding carries a stable ID, origin, severity, invariant class, delta, task relevance, evidence status, policy rule, paths/capabilities, relevance trace, and evidence digest.

gate_shadow retains the old/new gate comparison for diagnostics only. In 0.4, execution_gate.authoritative=true; the legacy gate no longer grants or denies writes. output_complete=false or schema-v1 input that cannot provide required precision must produce an unknown/incomplete finding and block rather than receive optimistic defaults.

Unified entry point:

python scripts/run_change_flow.py --repo <repo-root> --request "Add invoice refund support" --changed-path services/billing/refund.py --format compact-json

Default compact output always retains the non-projectable safety envelope: execution_gate, veto_reasons, allowed_write_paths, forbidden_write_paths, unknown_evidence, artifact_path, artifact_digest, and output_complete. The complete route, checks, findings, and cache/baseline evidence are stored in a content-addressed artifact. Use --format full-json for the full report or --format artifact-reference for the minimum reference. --field can add ordinary fields; --exclude-field cannot hide safety fields.

Installation

Python requirement:

• Python >= 3.10
• DeepSeek Harness plugin validation follows Harness's current Node requirement: ^22.19.0 || >=24.0.0; filesystem-only installation does not start an additional Node process

Install dependencies:

pip install -r requirements.txt

Or install in development mode:

pip install -e .[dev]

Install for Codex, Claude Code, and DeepSeek Harness:

python scripts/install_skill.py --target all --inject-hints

Install paths:

• Codex: %USERPROFILE%\.codex\skills\project-change-router
• Claude Code: %USERPROFILE%\.claude\skills\project-change-router
• DeepSeek Harness: $DSH_HOME/skills/project-change-router, defaulting to ~/.dsh/skills/project-change-router when DSH_HOME is unset

--inject-hints appends marked blocks only for Codex and Claude Code, which need persistent rule-entry reminders. It never rewrites whole files:

• Codex: appends to ~/.codex/AGENTS.md
• Claude Code: appends to ~/.claude/CLAUDE.md

This is soft enforcement that reminds the agent to invoke the skill before feature-level create / modify / delete work. It is not a background daemon and it does not bypass the conversation trigger model.

DeepSeek Harness publishes PCR's name and description through its skill catalog and supports explicit /project-change-router tokens in user messages, so no Harness-wide prompt document needs to be rewritten.

Compatibility: --target both retains its existing meaning and installs only Codex plus Claude Code; --target deepseek installs only Harness; --target all installs all three. For a project-local Harness installation, use the repository .dsh directory as the home:

python scripts/install_skill.py --target deepseek --dsh-home <repo-root>/.dsh

Harness's native filesystem provider then discovers <repo-root>/.dsh/skills/project-change-router/SKILL.md. Harness also supports <repo-root>/.agents/skills, ~/.agents/skills, and custom skill roots, while this installer intentionally defaults to the official DSH_HOME location.

Install as a DeepSeek Harness GitHub Plugin

The root package.json declares a dsh.bundle. Its Cordis provider reads the root SKILL.md and exposes the same resource directory, so there is no second prompt source. Pin a commit SHA when installing:

dsh plugin --profile <profile-name> add github:WeirdSky924/project-change-router-skill#<commit-sha>
dsh --profile <profile-name> --dump-config

The bundle is native ESM with no TypeScript build, prepare script, or install-time code execution allowance. Project .dsh/skills and user filesystem skills have a higher Harness rank than the bundled provider, preserving the official local-override behavior.

Remove the profile plugin with:

dsh plugin --profile <profile-name> remove project-change-router-skill

Harness community discovery uses the dsh-plugin topic on public GitHub repositories. Before release, configure searchable topics such as dsh-plugin, deepseek-harness, agent-skills, and coding-agent. DeepSeek Harness remains a developer preview, so rerun the provider smoke and installation validation after upgrading between Harness preview releases.

The installer uses staging, a recursive payload hash, recursive Python compilation, governance API probes, and atomic replacement. It replaces the old skill only after the new copy passes all checks, and restores the old copy on failure. This prevents top-level scripts, router_support, schemas, documentation, or the DSH provider from being installed as a mixed version.

The source checkout and destination must be different paths. If this Git checkout already lives at any target's skills/project-change-router path, do not install over itself; use a separate checkout to install multiple targets, or install only the other targets. --verify-only requires the trusted manifest created by an atomic installation. A legacy copy without that manifest must be reinstalled once before hash verification is meaningful.

Safely Upgrade an Existing PCR Installation

The global skill and a repository bundle are separate layers:

• The global skill lives under ~/.codex/skills/project-change-router, ~/.claude/skills/project-change-router, or ~/.dsh/skills/project-change-router and contains scripts and workflow instructions.
• The repository bundle lives under <repo-root>/project-change-router/ and contains that project's long-lived capability, owner, path-map, feedback, and evaluation data.

Updating the global skill neither requires nor authorizes rebuilding repository bundles. Use this upgrade sequence:

1. Update this skill source repository to the version you intend to install. 2. Run the atomic installer:

python scripts/install_skill.py --target all --inject-hints

3. Verify the installed Codex, Claude Code, and DeepSeek Harness copies, including file hashes and reuse-engine API compatibility:

python scripts/install_skill.py --target all --verify-only

4. For a repository that has used PCR for a long time, run read-only compatibility checks only:

python <new-skill-root>\scripts\validate_router_bundle.py --repo <existing-repo> --format json
python <new-skill-root>\scripts\check_bundle_governance.py --repo <existing-repo> --format json
python <new-skill-root>\scripts\check_index_freshness.py --repo <existing-repo> --changed-path <known-path> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\check_deps.py --repo <existing-repo> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\check_public_api.py --repo <existing-repo> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\check_structure.py --repo <existing-repo> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\run_evaluation.py --repo <existing-repo> --format json
python <new-skill-root>\scripts\check_reuse.py --repo <existing-repo> --changed-path <known-path> --strict-completeness --format json
python <new-skill-root>\scripts\run_change_flow.py --repo <existing-repo> --request "Compatibility check only" --changed-path <known-path> --format compact-json

5. Continue using the existing bundle after those checks. Do not run bootstrap_router.py or rebuild_index.py merely because the installed skill changed.

Compatibility guarantees:

• The new skill continues to read bundle schema v1.
• Version 0.4 uses architecture governance API v2 plus typed-finding, gate, change-flow, and authorization API v1 while preserving reuse engine API v2.
• Every current report carries one runtime_identity binding skill version, Git commit when available, installed payload digest, and schema/API/policy/parser versions. Cache, baseline, finding, authorization, and artifact identity all bind to it.
• New evaluation fields in schema v1 remain optional. Safe runtime defaults are read in memory and are not written back to old YAML during compatibility checks; missing or disabled eval

…