# Legacy Kickstart

> Use when the user wants a guided, end-to-end AI modernization of a legacy project. Triggers when user says "AI化改造", "AI-friendly modernization", "modernize this project", "make this project AI-ready", "对这个项目进行AI改造", "help me modernize this codebase", or wants a one-click guided experience through discovery, documentation, and safety rails.

- **Type:** Skill
- **Install:** `agentstack add skill-foreversc-ai-handrail-legacy-kickstart`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ForeverSc](https://agentstack.voostack.com/s/foreversc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ForeverSc](https://github.com/ForeverSc)
- **Source:** https://github.com/ForeverSc/ai-handrail/tree/main/skills/legacy-kickstart

## Install

```sh
agentstack add skill-foreversc-ai-handrail-legacy-kickstart
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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]`

2. **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

3. **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

4. **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)

5. **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

2. **Recommend next domain:**
   - Refer back to the modernization plan
   - Suggest the next-priority domain
   - Explain why it should be next

3. **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](https://github.com/ForeverSc)
- **Source:** [ForeverSc/ai-handrail](https://github.com/ForeverSc/ai-handrail)
- **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-foreversc-ai-handrail-legacy-kickstart
- Seller: https://agentstack.voostack.com/s/foreversc
- 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%.