Legacy Kickstart

Legacy Kickstart — Guided Modernization Orchestrator

One-click entry point for making a legacy project AI-friendly. Orchestrates a lightweight project scan, produces a modernization plan, and then drives the user through discovery → doc-bootstrap → safety-rails for a chosen domain.

Goal

Take a user from "I have an old project" to "one domain is fully analyzed, documented, and guarded" in a single guided session.

When to Use

• User wants a full guided modernization experience
• User says "help me modernize this project" or "对这个项目进行AI改造"
• User is unsure where to start with a legacy codebase
• First-time users of AI Handrail who want end-to-end guidance

When NOT to Use

• User already knows which domain to focus on (use legacy-discovery directly)
• User only needs one specific phase (use the individual skill)
• Greenfield projects
• Small scripts or utilities with obvious structure

Mandatory Workflow

Step 1: Project-Level Overview (Lightweight Scan)

This is intentionally shallow — a triage pass, not a full discovery.

1. Detect project type — scan project metadata files to identify the tech stack:

• package.json, go.mod, pom.xml, build.gradle, pyproject.toml, Gemfile, Cargo.toml, *.csproj, etc.
• Match against detection signals defined in skills/legacy-discovery/profiles/ to identify project type
• Record: Project Type: [frontend | backend-node | backend-java | backend-python | backend-go | fullstack | unclassified]

1. Read project metadata — gather basic facts:

• Project name, language, framework, and versions (from lockfiles)
• CI/CD configuration (.github/workflows/, Jenkinsfile, .gitlab-ci.yml, etc.)
• Deployment configuration (Dockerfile, docker-compose.yml, Kubernetes manifests, etc.)
• README and any existing documentation

1. Map directory structure — identify top-level layout:

• Run a shallow directory listing (top 2 levels)
• Identify naming conventions (feature-based, layer-based, domain-based)
• Count files per top-level directory

1. Identify all business domains / top-level modules — for each candidate domain:

• Name and brief description (inferred from directory name, code, and any docs)
• File count
• Has tests? (look for test/, __tests__/, *_test.*, *.spec.* nearby)
• Has documentation? (look for README, docs, comments)
• Git change frequency (run git log --oneline --since="6 months ago" -- | wc -l for a rough hotspot signal)

1. Quick risk grading per domain — assign HIGH / MEDIUM / LOW based on:

| Factor | HIGH signal | MEDIUM signal | LOW signal | |--------|------------|---------------|------------| | File count | >50 files | 10-50 files | 100 commits | 20-100 commits | <20 commits | | Coupling signals | Imported by many modules | Some imports | Self-contained |

Overall risk = highest factor wins. Tie-break: prefer higher risk.

Step 2: Produce Modernization Plan Document

Generate docs/legacy-modernization/modernization-plan.md using the template from templates/modernization-plan.md.

The document must contain:

• Project type and tech stack summary
• Business domain inventory with brief descriptions
• Risk score per domain (HIGH / MEDIUM / LOW) with justification
• Recommended modernization order (highest risk + highest value first)
• Estimated effort per domain (Light / Medium / Heavy)
• Current state assessment (docs, tests, CI status)

Output rules:

• Create the docs/legacy-modernization/ directory if it doesn't exist
• Write the plan as a real file, not just chat output
• Tell the user where the file was saved

Step 3: Ask User Which Domain to Start

Present the domain list with risk levels and recommended order:

1. Show a summary table of domains, risk levels, and recommended priority
2. Highlight the recommended first domain and explain why
3. Ask the user to choose one domain (or accept the recommendation)
4. Confirm the chosen domain before proceeding

Important: Wait for user response. Do not proceed without explicit user selection.

Step 4: Execute Phase 0 → 1 → 2 on Selected Domain

Automatically run three phases in sequence on the user-selected domain. Each phase follows its own skill's complete workflow.

Phase 0 — Discovery

1. Announce: "Starting Phase 0: Discovery for [domain]"
2. Read and follow the full workflow in skills/legacy-discovery/SKILL.md
3. Scope is pre-set to the selected domain — skip the "establish boundaries" negotiation
4. Complete all discovery steps, produce all discovery outputs
5. Brief progress report: what was found, key risks, unknowns

Phase 1 — Doc Bootstrap

1. Announce: "Starting Phase 1: Documentation for [domain]"
2. Read and follow the full workflow in skills/legacy-doc-bootstrap/SKILL.md
3. Use discovery outputs as input
4. Produce all documentation artifacts
5. Brief progress report: what docs were created

Phase 2 — Safety Rails

1. Announce: "Starting Phase 2: Safety Rails for [domain]"
2. Read and follow the full workflow in skills/legacy-safety-rails/SKILL.md
3. Use discovery + documentation outputs as input
4. Produce test recommendations and guardrail artifacts
5. Brief progress report: what guardrails were established

Cross-phase rules:

• Each phase must fully complete before the next begins
• If any phase encounters a HUMAN-REVIEW decision point, stop and ask the user before continuing
• If a phase fails or cannot complete, report the issue and ask the user how to proceed
• Do not skip phases

Step 5: Summary and Next Steps

After completing all three phases for the selected domain:

1. Summarize what was accomplished:

• Domain analyzed
• Documents created (list file paths)
• Guardrails established
• Key findings and risks identified

1. Recommend next domain:

• Refer back to the modernization plan
• Suggest the next-priority domain
• Explain why it should be next

1. Ask user:

• "Would you like to continue with [next domain]?"
• If yes: loop back to Step 4 with the new domain
• If no: end the session with a summary of overall progress

Kickstart-Specific Rules

1. Project-level overview is intentionally shallow. It is a triage/screening pass, not a full discovery. Deep analysis only happens on the user-selected domain in Step 4.
2. Deep work follows each sub-skill's own workflow. The kickstart orchestrator does not replace or simplify the sub-skills — it coordinates them.
3. HUMAN-REVIEW stops execution. Any HUMAN-REVIEW decision point encountered during Phase 0/1/2 must pause execution and ask the user.
4. One domain at a time. Even though the overview scans all domains, deep work is always scoped to one domain per round.
5. Modernization plan is a living document. After completing a domain, update the plan to reflect progress (mark domain status, adjust priorities if new information emerged).
6. No silent failures. If a phase encounters issues (e.g., no test framework found, ambiguous domain boundaries), report to user and ask how to proceed.

Hard Rules (inherited from suite)

1. Lockfile is truth. Read actual dependency versions from lockfiles.
2. Project code is primary reference. Existing implementations beat external documentation.
3. 80/20 rule. Focus on P0 critical paths first.
4. No hidden assumptions. Mark unknowns as UNKNOWN.
5. Human checkpoints are non-negotiable. Business rules, schema changes, and deletions require explicit approval.
6. Guardrails before depth. Tests → observability → feature flags → rollback plan → then refactor.
7. Complex logic needs a flowchart. Discovery and documentation outputs must include a flowchart for branch-heavy or stateful legacy behavior.
8. Hidden traps must be documented. Non-standard patterns and counter-intuitive side effects cannot stay implicit.
9. High-impact outdated dependencies require source inspection. Verify their APIs from the pinned version's project usage and source inspection before planning changes.
10. Source edits are blocked until tests exist. If a module is TEST-MISSING or lacks module-to-test mapping, stop and establish tests before planning refactors.

Risk Labels

Use the same label system as the rest of the suite. See the root SKILL.md for the full list.

Output Files

| File | Created in | |------|-----------| | docs/legacy-modernization/modernization-plan.md | Step 2 | | All outputs from legacy-discovery | Step 4 Phase 0 | | All outputs from legacy-doc-bootstrap | Step 4 Phase 1 | | All outputs from legacy-safety-rails | Step 4 Phase 2 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ForeverSc
• Source: ForeverSc/ai-handrail
• License: MIT

Install and usage instructions live in the source repository linked above.