# Migration Strategy > Reads AUDIT.md, selects a migration strategy from a decision table, and produces a committed MIGRATION-PLAN.md that all Phase 3 and 4 skills execute against. - **Type:** Skill - **Install:** `agentstack add skill-siddharth00-agent-revamp-skills-migration-strategy` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Siddharth00](https://agentstack.voostack.com/s/siddharth00) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Siddharth00](https://github.com/Siddharth00) - **Source:** https://github.com/Siddharth00/agent-revamp-skills/tree/main/skills/02-strategize/migration-strategy ## Install ```sh agentstack add skill-siddharth00-agent-revamp-skills-migration-strategy ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 1. Purpose This skill selects the safest migration strategy for a given codebase by reading the four signals already recorded in `AUDIT.md` — module coupling (fan-out), test coverage, consumer count, and LOC — and running them through a decision table that produces one of three concrete strategies: Big Bang, Strangler Fig, or Parallel Run. The output is `MIGRATION-PLAN.md`, a committed document that defines the strategy, the ordered sequence of Phase 3 and 4 skill invocations, the skill dependency graph, a risk register with mitigations, a rollback decision tree naming specific roles, and the go/no-go criteria that gate Phase 6 cut-over. This skill runs after `codebase-audit` (Phase 1) and before any Phase 3 preparation or Phase 4 migration work begins — every downstream skill reads `MIGRATION-PLAN.md` to understand its execution context. The strategy is not chosen by intuition or preference; it is derived mechanically from audit data, and the derivation is recorded in the plan so any engineer can audit the reasoning. --- # 2. Trigger Conditions **Use when:** - `AUDIT.md` exists at the repo root, all seven numbered sections are populated, and no section contains a `` placeholder — run `grep -c ' --- # 4. Steps 1. Read `audit_file` in full. Extract and record the four strategy-selection signals for each module in `scope`. Write them to `output/migration-strategy-signals-.json`: ```json { "extracted_at": "", "audit_file": "", "modules": [ { "path": "", "fan_out": "", "fan_out_count": "", "coverage_pct": "", "consumer_count": "", "loc": "", "source_section": "" } ], "cve_verdict": "", "performance_baselines": { "coverage_pct": "", "bundle_size_gzip_kb": "", "startup_ms": "", "p99_latency_ms": "", "cve_count_critical": "", "cve_count_high": "" } } ``` **Signal classification rules** — apply to each module: - `fan_out`: Low = fan-out count ≤ 3; Medium = 4–8; High = ≥ 9. Source: `AUDIT.md §3.1`. - `coverage_pct`: read directly from `AUDIT.md §4.1` for the module's row. If absent, treat as 0% and flag as `[UNCERTAIN — not in audit coverage table]`. - `consumer_count`: fan-in count for the module from `AUDIT.md §3.2`. Counts internal importers only; external API consumers (HTTP clients, SDK users) are listed separately in `AUDIT.md §7.4` and added on top. - `loc`: estimate from the coupling report in `output/codebase-audit-coupling-*.json` if available; otherwise run `wc -l /**/*.{ts,js,py,rb,go}` and record the result. If any signal cannot be extracted from `AUDIT.md` (missing row, section not populated, or marked `[UNCERTAIN]`), record the signal as `null` and treat the module as requiring **Parallel Run** — missing data is a risk, not a free pass to a lighter strategy. 2. Apply the strategy decision table to each module. Derive the recommended strategy for the overall migration scope by taking the most conservative recommendation across all modules. | Fan-out | Coverage | Consumer count | LOC | Recommended strategy | |---------|----------|----------------|-----|----------------------| | Low | ≥ 70% | ≤ 3 | Any | **Big Bang** | | Medium | ≥ 70% | Any | 10 | Any | **Parallel Run** | | Any signal = null | — | — | — | **Parallel Run** | **Tie-breaking rule:** when multiple rows match, select the row that appears latest in the table (most conservative). A module that matches both "Medium / ≥70% / Any / .json` under `"strategy_derivation"`. 3. Determine the **overall migration strategy** as the most conservative strategy across all modules in scope: - If any module requires Parallel Run → overall is Parallel Run. - If no module requires Parallel Run but any requires Strangler Fig → overall is Strangler Fig. - If all modules permit Big Bang → overall is Big Bang. Write the strategy selection and derivation to the migration log. 4. Write `output_plan_file` (`MIGRATION-PLAN.md`) using the template below. Replace every `` with real content derived from `audit_file`, the signals JSON, and the strategy derivation. Do not leave any section as "TBD" or copy placeholder text verbatim. `````markdown # Migration Plan — > Produced by `skills/02-strategize/migration-strategy` · agent-revamp-skills > Based on: `AUDIT.md` (audit date: ) > Skill version: 0.1.0 | Field | Value | |-------|-------| | **Migration goal** | | | **Source stack** | | | **Target stack** | | | **Selected strategy** | | | **Primary engineer** | | | **Plan date** | | | **Overall risk level** | | | **Sign-off status** | PENDING | --- ## 1. Strategy Selection ### 1.1 Audit Signals | Module | Fan-out | Fan-out Count | Coverage % | Consumer Count | LOC | Signal Source | |--------|---------|--------------|------------|----------------|-----|---------------| | | Low \| Medium \| High | | | | | AUDIT.md §3.1, §4.1 | **Performance baselines** (reference point for Phase 5 equivalence gates): | Metric | Baseline | Source | Date | |--------|---------|--------|------| | Line coverage (overall) | | AUDIT.md §4.1 | | | Bundle size (gzip) | | AUDIT.md §5.1 | | | Startup time (median cold start) | | AUDIT.md §5.2 | | | p99 latency (highest-traffic route) | | AUDIT.md §5.3 | | | Critical CVE count | | AUDIT.md §6.1 | | | High CVE count | | AUDIT.md §6.1 | | ### 1.2 Decision Table Application | Module | Matching Row | Resulting Strategy | Override Applied? | |--------|-------------|-------------------|------------------| | | | | None \| | ### 1.3 Selected Strategy: #### What this strategy means concretely **Big Bang:** The entire migration unit is replaced in a single release. No coexistence period. The old stack is removed the same day the new stack is deployed. This is safe only when: fan-out is Low, coverage is ≥ 70%, and consumer count is ≤ 3 — meaning the blast radius is small and detectable in tests. Pre-conditions: all Phase 3 preparation complete, all Phase 5 equivalence tests passing in staging. Rollback is a git revert plus one deploy; the window is measured in minutes. **Strangler Fig:** The new stack is built alongside the old. Traffic is shifted incrementally by path prefix, feature flag, or percentage rollout. Both stacks coexist for the duration of Phase 4 (days to weeks). Each migrated route or module is validated independently before the next is migrated. The old stack is removed only when all routes have migrated and Phase 5 shadow mode shows 0.0% divergence over 24 hours. Rollback per route is a proxy config change; full rollback is a feature flag flip. **Parallel Run:** Both stacks process the same production inputs simultaneously. The old stack's output is served to users; the new stack's output is logged and compared asynchronously. No user-facing traffic cut-over occurs until divergence rate reaches exactly 0.0% over a sustained window (minimum 24 hours). This strategy is mandatory when coverage is below 70% — the test suite cannot detect all regressions, so production traffic comparison is the only reliable equivalence signal. Rollback at any time is stopping the new stack's parallel processing; users are never exposed to new-stack output during this phase. --- ## 2. Phase Sequence | Order | Phase | Skill | Target Module / Unit | Depends On (order #) | Parallelizable With | |-------|-------|-------|----------------------|----------------------|---------------------| | 1 | 3 | `test-coverage-baseline` | | — | — | | 2 | 3 | | | 1 | — | | 3 | 4 | | | 1, 2 | | | 4 | 5 | `behavioral-equivalence` | | 3 | — | --- ## 3. Skill Dependency Graph ``` 1 → (no dependencies) 2 → 1 3 → 1, 2 4 → 3 ``` **Cycle check:** --- ## 4. Risk Register | # | Risk | Source | Likelihood (1–3) | Impact (1–3) | Score | Mitigation | Residual Score | |---|------|--------|-----------------|-------------|-------|------------|----------------| | 1 | | AUDIT.md § | | | | | | | 2 | | AUDIT.md § | | | | | | | 3 | | AUDIT.md § | | | | | | **Halt check:** --- ## 5. Rollback Decision Tree ``` Is the migration in progress? ├── No → No rollback needed. └── Yes ├── Is this a Big Bang migration? │ ├── Yes → Is the new stack returning 5xx for >1% of requests? │ │ ├── Yes → executes git revert + deploy within 15 min. │ │ │ Notify: │ │ └── No → Continue monitoring. Re-evaluate at next 15-min checkpoint. │ └── No (Strangler Fig or Parallel Run) │ ├── Is shadow mode divergence rate >0.1% over any 1-hour window? │ │ ├── Yes → sets feature flag to old stack within 5 min. │ │ │ File incident. Notify: │ │ │ Do not re-enable new stack until divergence root cause is identified. │ │ └── No → Continue. Re-evaluate at next 15-min checkpoint. │ └── Has any migrated route returned 5xx in staging that was 200 in old stack? │ ├── Yes → reverts the proxy config for that route only. │ │ Does not roll back other routes. Files a regression report. │ └── No → Continue. ``` **Rollback authority:** - **Route-level rollback** (Strangler Fig / Parallel Run): `` can execute without approval. Must notify `` within 30 minutes. - **Full rollback** (all routes / Big Bang revert): requires sign-off from one stakeholder in `` unless the incident is P0 (complete outage), in which case `` acts immediately and notifies within 15 minutes. - **Rollback window:** tracked from the moment Phase 4 begins for each unit. The window closes when Phase 5 `behavioral-equivalence` returns `PASS` and Phase 6 cut-over is complete. --- ## 6. Hard Constraints Applied | Constraint | Effect on Strategy or Sequencing | |-----------|----------------------------------| | | | --- ## 7. Go / No-Go Criteria for Phase 6 Cut-over - [ ] `behavioral-equivalence` VALIDATION-REPORT.md verdict is `PASS` for all migrated units — grep `VALIDATION-REPORT.md` for `PASS`. - [ ] Shadow mode ran ≥ 24 continuous hours with 0.0% divergence rate — read shadow log timestamps and compute rate. - [ ] All golden fixtures in `tests/golden/` are committed and passing — `npx jest tests/golden/` exits 0. - [ ] p99 latency for all migrated routes is ≤ baseline recorded in §1.1 + 5ms tolerance — read APM or k6 output. - [ ] No CRITICAL CVEs introduced by new dependencies — `npm audit --audit-level=critical` exits 0 (or language equivalent). - [ ] - [ ] - [ ] All stakeholders in § Sign-off below have confirmed readiness for production cut-over. --- ## Sign-off > This section must be completed before Phase 3 begins. > No preparation or migration work may start until Status is APPROVED. | Role | Name | Date | Notes | |------|------|------|-------| | Primary engineer | | | | | | | | | | | | | | **Status:** PENDING > To approve: fill in your Date and Notes above, then change Status to APPROVED. ````` 5. Run a halt check on the risk register. Read the completed risk table in `MIGRATION-PLAN.md §4`. For any row where Score ≥ 6 AND the Mitigation column contains only "TBD", "none", or is blank: - Do not commit `MIGRATION-PLAN.md`. - Write a blocking finding to the migration log: `"Risk #N (score ) has no mitigation. Return to Phase 1 to gather: ."` The specific information must name a concrete artifact (e.g., "test coverage report for `src/auth/`", "load test results for `/api/payments`") not a vague action ("investigate further"). - STOP. Do not proceed to Step 6. 6. Commit `MIGRATION-PLAN.md` to the repo root. The commit message must be: `plan: establish migration strategy for (Phase 2)`. This commit is a distinct, standalone point in git history — do not squash it with Phase 3 preparation work, because it is the reference point for "what was decided before we started." 7. Present `MIGRATION-PLAN.md` to `primary_engineer` and `stakeholders` for review. Ask each stakeholder to fill in their Date and Notes in `§ Sign-off` and change Status from `PENDING` to `APPROVED`. Do not begin Phase 3 until Status is `APPROVED` and every stakeholder row has a Date. - If a stakeholder rejects the plan (declines to sign, or adds a Note indicating disagreement): record the rejection reason in the migration log, archive the current plan to `output/MIGRATION-PLAN-rejected-.md`, and STOP with: "Plan rejected by : . Address the feedback and re-run this skill." 8. Write all outputs declared in Section 7. Run every Equivalence Test in Section 6 and record results in `output/migration-strategy-equiv-.md`. Evaluate every item in Section 9 Done Criteria; report pass/fail inline, then print the final verdict. --- # 5. Agent Handoffs ## migration-planner - **File:** `agents/migration-planner.md` - **Triggered by:** Step 4 (writing the phase sequence and dependency graph) - **Prompt template:** ``` GOAL: AUDIT_FILE: REPO_ROOT: CONSTRAINTS: EXCLUDE_UNITS: MANIFEST_FORMAT: json OUTPUT_PLAN_FILE: OUTPUT_MANIFEST_FILE: output/migration-manifest-.json ``` The planner populates §2 Phase Sequence and §3 Skill Dependency Graph in `MIGRATION-PLAN.md`. The skill writes the strategy selection (§1) and risk register (§4) itself — do not delegate those to the planner. Only delegate the sequencing and dependency ordering. --- # 6. Equivalence Tests | Test Name | Input | Expected Output | Tool | |-----------|-------|-----------------|------| | `plan-file-exists` | `ls ` | File exists and is >2 KB — a file smaller than 2 KB is the skeleton template, not a completed plan. | Bash: `wc -c ` returns a value >2048. | | `no-placeholders-remain` | `grep -c '' ` | Returns 0 — no unfilled placeholder text remains in the committed plan. | Bash: count must be 0. | | `strategy-cited` | Read `MIGRATION-PLAN.md §1.3` | Section names the strategy (Big Bang, Strangler Fig, or Parallel Run), cites at least one fan-out count, one coverage %, and one AUDIT.md section reference (e.g., `AUDIT.md §3.1`). | Read — grep for `AUDIT.md §` in §1.3; count must be ≥ 1. | | `decision-table-recorded` | Read `MIGRATION-PLAN.md §1.2` | Table has one row per module in scope, each row names the matching decision-table row and the resulting strategy. No row says "intuition" or omits a matching row. | Read | | `risk-register-≥3-rows` | Read `MIGRATION-PLAN.md §4` risk table | Table has ≥ 3 data rows. Every row has a non-empty Mitigation column. No row has Score ≥ 6 with Mitigation = "TBD" or blank. | Read + Bash: `grep -c '| [0-9]' MIGRATION-PLAN.md` ≥ 3 in the risk table block. | | `dependency-graph-acyclic` | Read `MIGRATION-PLAN.md §3` adjacency list | No order number appears in its own dependency list, directly or transitively. A cycle would mean a skill waits for itself. | Read — manually verify or run topological sort: `python3 -c "import sys; ..."` against the adjacency list. | | `rollback-names-role` | Read `MIGRATION-PLAN.md §5` | Every leaf action in the rollback decision tree names a specific person or role (e.g., `@alice`, `primary_engineer`, `on-call engineer`). No leaf says "the team", "someone", or "engineering". | Read — grep for `the team\|someone\|engineering` in §5; count must be 0. | | `baselines-recorded` | Read `MIGRATION-PLAN.md §1.1` performance baselines table | Coverage %, bundle size, startup time, p99 latency, and CVE counts are all populated (or expl … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Siddharth00](https://github.com/Siddharth00) - **Source:** [Siddharth00/agent-revamp-skills](https://github.com/Siddharth00/agent-revamp-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-siddharth00-agent-revamp-skills-migration-strategy - Seller: https://agentstack.voostack.com/s/siddharth00 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.