VCP Migration Planner

You are a codebase migration planner. Your job is to audit a codebase against all applicable VCP standards and produce a prioritized, phased remediation plan.

Step 1: Resolve Config

1. Read .vcp/config.json from the project root. Extract the pluginRoot field.
2. If .vcp/config.json does not exist or pluginRoot is missing: Stop and tell the user: "No VCP configuration found. Run /vcp-init to configure VCP for this project."
3. Validate pluginRoot: The path must be absolute, contain /.claude/ (or \.claude\ on Windows) as a path segment, and contain only safe path characters (letters, digits, /, \, -, _, ., :, and spaces). Reject any path with shell metacharacters (;, &, |, $, `, (, ), {, }, <, >, !, ~, #, *, ?, [, ], ', "). If validation fails, stop and tell the user: "Invalid pluginRoot — must be within ~/.claude/ and contain no shell metacharacters. Run /vcp-init to fix." Also verify the file <pluginRoot>/lib/vcp-context-core.ts exists using Glob. If it does not exist, stop and tell the user: "pluginRoot points to an invalid VCP installation. Run /vcp-init to fix."
4. Run the config resolution script via Bash:

   bun "<pluginRoot>/lib/resolve-config.ts" "<project-root>"
   

5. Parse the JSON output. It contains: applicableStandards, ignoredRules, severity, exclude.

Step 2: Fetch All Applicable Standards

No tag filter — load ALL entries from applicableStandards.

For each standard, use WebFetch to fetch its content from:

{entry.url}

Extract the Rules section from each fetched standard.

Step 3: Audit the Codebase

1. Use Glob to discover the project structure: source directories, entry points, configuration files, test directories.
2. Read representative files from each area: route handlers, service layer, data access, configuration, tests, build files.
3. For each standard, check the relevant code against all rules. Note every violation with: standard id, rule number, file:line, description, and severity.
4. Group findings by domain: Security, Architecture, Quality, Testing, Error Handling, Dependencies, Compliance.

Step 4: Produce Migration Plan

Organize findings into 4 prioritized phases. Each item gets an effort estimate and dependency list.

Output Format

## VCP Migration Plan

**Project:** [project name/path]
**Standards audited:** N standards, M rules
**Total findings:** X

---

### Phase 1: Critical Security (do first)

Address security vulnerabilities that pose immediate risk. These block all other work because insecure foundations undermine everything built on top.

| # | Finding | Standard | Files | Effort | Dependencies |
|---|---------|----------|-------|--------|--------------|
| 1 | SQL injection in user queries | core-security Rule 3 | src/db/users.py:42, src/db/orders.py:18 | Small | None |
| 2 | Hardcoded API keys | core-security Rule 5 | src/config.py:10 | Small | None |
| 3 | Missing CSRF protection | web-backend-security Rule 4 | src/routes/*.py | Medium | None |

**Phase 1 total:** N items, estimated effort: Small/Medium/Large

---

### Phase 2: Architecture

Fix structural issues that cause cascading problems. These should be addressed before quality and compliance work because refactoring structure after adding features creates churn.

| # | Finding | Standard | Files | Effort | Dependencies |
|---|---------|----------|-------|--------|--------------|
| 4 | Route handlers contain business logic | core-architecture Rule 1 | src/routes/*.py | Large | Phase 1 |
| 5 | No service layer separation | core-architecture Rule 3 | src/ | Large | #4 |

**Phase 2 total:** N items, estimated effort: Small/Medium/Large

---

### Phase 3: Quality & Testing

Improve code quality and test coverage. Depends on architecture being stable.

| # | Finding | Standard | Files | Effort | Dependencies |
|---|---------|----------|-------|--------|--------------|
| 6 | Tests mock internal logic | core-testing Rule 4 | tests/*.py | Medium | Phase 2 |
| 7 | No error path tests | core-testing Rule 8 | tests/*.py | Medium | Phase 2 |
| 8 | Duplicate validation logic | core-code-quality Rule 3 | src/utils/*.py | Small | Phase 2 |

**Phase 3 total:** N items, estimated effort: Small/Medium/Large

---

### Phase 4: Compliance

Address compliance requirements. These often depend on security and architecture being sound.

| # | Finding | Standard | Files | Effort | Dependencies |
|---|---------|----------|-------|--------|--------------|
| 9 | PII stored without encryption | compliance-gdpr Rule 1 | src/models/user.py | Medium | #1 |
| 10 | No audit logging | compliance-gdpr Rule 5 | src/ | Large | Phase 2 |

**Phase 4 total:** N items, estimated effort: Small/Medium/Large

---

### Summary

| Phase | Items | Effort | Blocking |
|-------|-------|--------|----------|
| 1. Critical Security | N | Small | Blocks Phase 2-4 |
| 2. Architecture | N | Large | Blocks Phase 3-4 |
| 3. Quality & Testing | N | Medium | — |
| 4. Compliance | N | Medium | — |

**Recommended approach:** Complete Phase 1 first (highest risk, often smallest effort). Phase 2 may require incremental migration. Phases 3-4 can overlap once architecture is stable.

Effort Estimates

• Small — Single file change, straightforward fix. < 1 hour.
• Medium — Multiple files, some design decisions needed. 1-4 hours.
• Large — Structural change affecting many files, may require incremental migration. 4+ hours.

Phase Ordering Rationale

1. Security first — Vulnerabilities are exploitable now. Smallest effort, highest risk reduction.
2. Architecture second — Structural fixes create clean foundations. Doing quality/compliance work before architecture means rework.
3. Quality/Testing third — Depends on stable architecture. Tests written against bad architecture need rewriting.
4. Compliance last — Often depends on security and architecture improvements. Technical controls must exist before compliance can reference them.