adopt-existing-project

Adopt an Existing Project

Existing applications require migration, not scaffolding. Preserve behavior and data while moving toward the production contract incrementally.

Gate 0 — Check adoption state

Read .engineering-baseline-lock.json first.

• pending: run this skill before any application implementation or refactor.
• approved: execute only the approved plan and scope.
• in_progress: resume from recorded plan/checkpoint; do not restart discovery.
• complete: use the normal Engineering Baseline workflow unless the user asks for a new full assessment.
• not_required: the project was empty/new when installed; use Production Full-Stack for creation.

If the file is absent but the repository contains an existing application, treat adoption as pending.

Gate 1 — Read-only discovery

Until the user approves a plan, do not edit, create, move, rename, format or delete project files. Do not install dependencies, run migrations, start containers, execute application scripts, or invoke autofix tools. Read-only inspection and safe version/status commands are allowed.

1. Confirm the repository root and current working directory. Never assume the folder containing this skill is the application root.
2. Run scripts/inspect_project.py --project <root> from this skill and inspect the relevant files it identifies.
3. Read repository instructions, README, manifests, lockfiles, entry points, source layout, tests, schemas/migrations, CI, Docker/deployment, environment examples, generated contracts and security documentation.
4. Inspect Git status and preserve all existing user changes.
5. Map runtime components, data stores, integrations, trust boundaries, public APIs, persisted data, authentication/authorization and deployment assumptions.
6. Identify existing commands for build, test, lint, typecheck, migrations and local startup, but do not execute them before approval.

Read references/discovery.md for the complete inventory.

Gate 2 — Present assessment and ask questions

Before modifying anything, respond in chat with:

1. Current architecture and directory map.
2. Existing behavior and compatibility surfaces that must be preserved.
3. Production-readiness gaps against Production Full-Stack.
4. Security gaps across every required framework—not a generic summary.
5. Ponytail opportunities: deletion, reuse, dependency reduction, duplication removal and simpler native/platform alternatives.
6. Relevant Superpowers workflows for each proposed phase.
7. A risk-ordered, reversible migration plan with files/areas affected.
8. The minimum unanswered questions needed to proceed.

Ask questions that materially change architecture, compatibility, security, deployment or migration. Do not silently choose on the user's behalf. Use references/questions-and-plan.md.

End with an explicit approval request. Silence, an unrelated reply, or approval of only one decision is not approval of the whole plan.

Gate 3 — Record approval and establish safety net

Only after explicit approval:

1. Run scripts/adoption_state.py approve --project <root> from this skill.
2. Use Superpowers brainstorming/writing-plans to turn the approved proposal into a checkpointed implementation plan.
3. Use a feature branch or Superpowers worktree workflow unless the user declines or the environment cannot support it.
4. Record baseline build/test/lint/typecheck behavior. If existing checks fail, separate pre-existing failures from new regressions.
5. Add characterization/contract tests around public APIs, critical workflows, authorization, persisted data and integration boundaries before refactoring.
6. Back up or rehearse migration/rollback for stateful or irreversible changes.
7. Run scripts/adoption_state.py start --project <root> when implementation begins.

Gate 4 — Incremental migration

Use small independently verifiable changes. Do not combine directory moves, behavior changes, security rewrites and cosmetic refactors in one step.

Order by dependency and risk:

1. Characterization tests and observability needed to detect regressions.
2. Ponytail cleanup proven behavior-neutral.
3. Critical/high security fixes and server-side policy enforcement.
4. Configuration, secrets, error handling, logging, rate limits and audit events.
5. Queue/worker, caching, pagination and resource/concurrency boundaries.
6. Directory/architecture migration with compatibility adapters where needed.
7. Docker/Compose, CI/CD, operations, backup/restore and production evidence.
8. Impeccable frontend consistency and accessibility improvements.

For each step use the relevant Superpowers skill:

• systematic-debugging for failures or unexpected behavior.
• test-driven-development for fixes and new behavior.
• executing-plans or subagent-driven-development only when available and suitable; never claim subagents that the host does not provide.
• requesting-code-review after each meaningful phase.
• verification-before-completion before every completion claim.
• finishing-a-development-branch when the approved work is complete.

Read references/migration-and-verification.md.

Framework enforcement for existing code

Security Review is mandatory during discovery and after every phase:

• STRIDE: evaluate all six categories for every component/data flow/trust boundary; record threats, mitigations, verification and residual risk.
• OWASP ASVS 5.0.0 Level 2: build a requirement-level matrix from the official Level 2 catalog. Record every applicable requirement ID as pass/fail/N/A with reason and evidence. Chapter-level prose is not compliance.
• OWASP Top 10:2025: assess all ten categories plus the explicit SSRF gate.
• NIST CSF 2.0: record Govern, Identify, Protect, Detect, Respond and Recover outcomes, owners and gaps.
• Zero Trust: verify each protected resource/action server-side; do not trust network location, frontend state, cookies, headers, parameters or bodies.

Do not say frameworks were applied unless the matrices and verification evidence exist. Scanners supplement manual verification; they do not replace it.

Ponytail refactor contract

Ponytail may reduce code only after behavior is protected by tests or equivalent evidence. Preserve public APIs, response contracts, database semantics, events, security controls, accessibility and error behavior unless the approved plan explicitly changes them. Prefer deletion and reuse, but never trade away correctness, security, observability or compatibility.

Completion

Run all baseline and new checks, review the final diff, rehearse rollback where needed, update documentation/evidence, and show results. Then run:

python3 <this-skill-dir>/scripts/adoption_state.py complete --project <root>

Do not mark complete with failing new checks, unverified migrations, missing framework evidence, or unaccepted critical/high residual risk.