Ai Handrail

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
• Source: ForeverSc/ai-handrail
• License: MIT

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