# Ai Handrail

> Use when working with legacy projects, old codebases, or inherited systems that need modernization. Triggers when user mentions legacy code, old project, inherited codebase, technical debt, legacy refactoring, safe modernization, understanding an unfamiliar large codebase before making changes, AI化改造, AI-friendly modernization, make this project AI-ready, or modernize this project.

- **Type:** Skill
- **Install:** `agentstack add skill-foreversc-ai-handrail-ai-handrail`
- **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

## Install

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

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

## About

# AI Handrail — Legacy Project Modernization Suite

A skill suite for incrementally making legacy projects AI-friendly. Core principle: **add handrails first, then refactor**.

## When to Use

- Inheriting or onboarding to a large existing codebase
- Planning modernization of legacy systems
- Needing to understand old code before making changes
- Adding AI-assisted development to projects without docs/tests
- Reducing risk of breaking changes in critical business systems

## When NOT to Use

- Greenfield projects
- Small scripts or utilities with obvious structure
- Projects already well-documented with comprehensive test suites

## Project Type Profiles

Discovery (Phase 0) automatically detects the project type and loads a corresponding profile from `skills/legacy-discovery/profiles/`. Profiles provide stack-specific reconnaissance checklists, critical path patterns, risk labels, and structural analysis tools.

| Profile | File | Triggers |
|---------|------|----------|
| Frontend | `profiles/frontend.md` | React, Vue, Angular, Svelte, etc. |
| Backend-Node | `profiles/backend-node.md` | Express, Fastify, NestJS, Koa, etc. |
| Backend-Java | `profiles/backend-java.md` | Spring Boot, Quarkus, Jakarta EE, etc. |
| Backend-Python | `profiles/backend-python.md` | Django, Flask, FastAPI, etc. |
| Backend-Go | `profiles/backend-go.md` | Go with gin, echo, chi, net/http, etc. |
| Fullstack | `profiles/fullstack.md` | Both frontend + backend signals detected |

Profiles extend the base workflow — they add stack-specific checks without replacing core steps. Subsequent skills (doc-bootstrap, safety-rails, refactor-plan) use the detected project type to apply profile-aware guidance.

## Sub-Skills

This suite contains 4 skills used in sequence, plus an orchestrator for guided end-to-end experience:

### Orchestrator → `legacy-kickstart` (Recommended Starting Point)
One-click guided modernization. Read `skills/legacy-kickstart/SKILL.md`.
**Use when:** You want a full guided experience — project scan, modernization plan, then automated phased execution. Best for first-time users or when starting fresh on a large legacy project.

### Phase 0 → `legacy-discovery`
Understand the project. Read `skills/legacy-discovery/SKILL.md`.
**Use when:** Starting work on an unfamiliar legacy project.

### Phase 1 → `legacy-doc-bootstrap`
Create AI-consumable documentation. Read `skills/legacy-doc-bootstrap/SKILL.md`.
**Use when:** Discovery is complete and knowledge needs to be persisted.

### Phase 2 → `legacy-safety-rails`
Build guardrails. Read `skills/legacy-safety-rails/SKILL.md`.
**Use when:** Documentation exists but no safety nets protect refactoring.

### Phase 3 → `legacy-refactor-plan`
Plan safe, incremental changes. Read `skills/legacy-refactor-plan/SKILL.md`.
**Use when:** Guardrails are in place and actual code changes are needed.

## Hard Rules (apply to ALL sub-skills)

1. **No full-project scans.** Analyze one domain / critical path / subsystem per round.
2. **Lockfile is truth.** Read `package-lock.json`, `yarn.lock`, `Gemfile.lock`, `poetry.lock`, `go.sum`, etc. Never assume latest versions.
3. **Project code is primary reference.** Existing implementations beat external documentation.
4. **High-impact old dependencies require source-backed verification.** If an outdated dependency has a large blast radius, you must review the lockfile, project code, and package source code for the pinned version instead of trusting generic examples.
5. **80/20 rule.** Identify P0 critical paths first. Don't chase completeness in round one.
6. **Complex logic needs a flowchart.** State-heavy and branch-heavy legacy behavior must be documented visually.
7. **Non-standard behavior must be tagged.** Hidden traps and counter-intuitive side effects should be recorded explicitly, not left implicit.
8. **No hidden assumptions.** If something is unknown, mark it `UNKNOWN` — never guess silently.
9. **Human checkpoints are non-negotiable.** Business rules, schema changes, deletions, and behavioral changes require explicit human approval.
10. **Guardrails before depth.** Tests → observability → feature flags → rollback plan → then refactor.
11. **No source edits before tests exist.** `TEST-MISSING` or missing module-to-test mapping means add tests first, then change code.

## Risk Labels

Tag every module/area analyzed. Full label definitions in `docs/naming.md`.

- `P0-CRITICAL` — core revenue/safety path
- `HIGH-RISK` — complex, fragile, or undertested
- `LEGACY-SEALED` — do not touch without explicit approval
- `SAFE-TO-EXTRACT` — low coupling, safe to isolate
- `DOC-MISSING` / `TEST-MISSING` — prerequisite work needed before changes
- `HUMAN-REVIEW` — requires human sign-off
- `DEAD-CODE` — unused code, mark as AI-ignorable
- `CIRCULAR-DEP` — circular dependency, high coupling risk
- `HOTSPOT` — frequently modified file, high bug probability

Profile-specific labels (e.g., `GLOBAL-CSS`, `GOROUTINE-LEAK`, `CONTRACT-DRIFT`) are defined in each profile and in `docs/naming.md`.

## Per-Round Completion Criteria

Every analysis round must answer exactly 4 questions:

1. What specific area was analyzed this round?
2. What has been confirmed?
3. What remains unknown?
4. What should be analyzed next and why?

## 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-ai-handrail
- 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%.