# Phase Adopt > Phase Adopt - Skill: `awjackson2/phase-adopt` (Agent Skill) - Install (CLI): `npx skillmds@latest add awjackson2/phase-adopt` - Raw SKILL.md: https://api.skillmd.com/api/skills/awjackson2/phase-adopt/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: awjackson2 (https://skillmd.com/u/awjackson2) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/awjackson2/phase-adopt --- # Phase Adopt This skill brings the phase workflow to a project that **already exists** — it has source code, a git history, probably a shared default branch, maybe an agent guide (`CLAUDE.md` / `AGENTS.md`). It is the existing-repo counterpart to `phase-project-init` (use that one only for an empty/new repo). Key difference from init: the default branch is already established and may be protected and shared, so adoption does **not** make a bootstrap commit straight to it. The scaffolding lands through a **docs-lane PR**, exactly like any other doc change in a live repo. It is **not a phase** (no plan/log for adopting). It reuses the same templates `phase-project-init` installs — its payload lives under that skill's `assets/`, so `phase-project-init` must be installed alongside this skill; if it isn't, ask the user to add it rather than reconstructing the payload by hand. ## Procedure ### Step 1: Survey the repo Determine: is it a git repo? (Usually yes for an existing project. If not, ask whether the user wants git — it is optional in this workflow. Without git, skip the docs-lane PR machinery below and land the scaffolding as plain file writes; an empty directory belongs to `phase-project-init` instead.) What is the default branch? Is there an agent guide (`CLAUDE.md` / `AGENTS.md`)? Is there already a `development/phase_log/`? If the log already exists, **stop** — the project is adopted; run `phase-recap` to load state instead. ### Step 2: Decide the numbering origin The repo has prior work that predates the workflow. Settle with the user where new tracked phases begin. Default and recommended: - Treat **all pre-workflow history as legacy** that simply isn't phase-numbered, and start the first *new* tracked effort at **Major 1** (`1.1.0`), or at a fresh Major if the user wants to reserve low numbers for backfill. - Honor appendability going forward: once adopted, related future work appends near its theme like any phase ([TERMINOLOGY.md → Core principle](../../../TERMINOLOGY.md)). Confirm the choice; it affects every future number. ### Step 3: Optional — backfill a light history If the user wants `phase-recap` to have a baseline on day one, reconstruct a **handful** of retroactive index entries from real git signals — tags, merge commits, PR titles, major commit messages. Rules: - **Do not fabricate.** Each backfilled line is summarized from a real commit/PR/tag and marked `(reconstructed from git history)`. No invented plan/log files, or at most a stub log that says it was reconstructed. - Keep it to milestones, not every commit — a readable baseline, not a transcript. - Number backfilled entries as a clearly-legacy block (e.g. `0.x` or a "pre-adoption" note) so they don't collide with the new numbering origin from Step 2. - If the user doesn't want backfill, seed an empty index with a one-line note that history predates the workflow. ### Step 4: Install the scaffolding (docs-lane branch) On a fresh `docs/adopt-phase-workflow` branch cut from the up-to-date default branch: - Install the **knowledge bundle** by copying `phase-project-init/assets/development/` → `development/`. That lands the reserved root files (`index.md`, `log.md`), the `design/` layer with its element template, and the three phase-log templates. The seeded index gets the Step 3 backfill (or the empty-with-note form). - Check the bundle boundary before opening the PR. On an existing repo this matters more than on a fresh one: if the project already had a `development/` directory holding notes, audits, or tooling, those are strays — the bundle holds only concepts, and **finding them is the finding**. Move them out of the bundle rather than loosening the boundary, and say plainly what you moved and why. - If the project will keep living design docs, create `development/design/` and mention `phase-tracker` Step 3.5 will sync them. - Copy `phase-project-init/assets/.github/pull_request_template.md` → `.github/pull_request_template.md` (unless the repo already has a PR template the team wants to keep — then offer to merge the phase-artifacts and agent-signatures sections into it instead of overwriting). - Add `.worktrees/` to the project's `.gitignore` (create the file if absent) — every phase worktree is created there and must never be tracked by the primary checkout. - Optionally install the conventions at the project root (`TERMINOLOGY.md`, `templates/recap_template.md`, `templates/response_templates.md`) so the skills' links resolve and the repo self-documents. These ship only with the full phase-skills repository; if only the skills were installed, skip this — nothing breaks. ### Step 5: Seed or update the project's agent guide Add the **phase workflow charter** by pasting the content of `phase-project-init/assets/phase_project.md` (everything below its `---`) — the charter ships as an asset of that skill so this step works in every install; never skip it because a repo-root `phase_project.md` wasn't found. Install it into whichever agent guide file(s) the project's agents read — `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex, Copilot, and other agents), or **both** if in doubt. If a guide file exists, **append** the charter (don't overwrite the project's existing guidance); if not, create it with the charter. The asset is the single source for this section — don't hand-write a divergent version. Include it in the same docs-lane PR as the scaffolding. ### Step 6: Open the docs-lane PR Stage the scaffolding with an explicit file list, commit (`docs: adopt phase workflow scaffolding`, with the `Co-Authored-By:` trailer), push, and open a PR to the default branch. Merge it before starting the first phase — adoption is itself a normal change going through the normal gate, not a privileged direct commit. ### Step 7: Hand off to the first phase Route the first tracked effort: - **Large multi-step goal** → `phase-decompose` to build the umbrella, then `phase-loop`. - **One concrete effort** → `phase-tracker` at the Step 2 origin number. ## Setup summary Report: default branch detected, numbering origin chosen, backfill done/skipped (and how many entries), scaffolding PR opened, which agent guide file(s) got the charter (`CLAUDE.md` / `AGENTS.md`), and the proposed first phase with the skill that will run it. ## What this skill should not do - Do not use it on an empty repo (use `phase-project-init`) or an already-adopted one (use `phase-recap`). - Do not commit the scaffolding straight to the default branch — it goes through a docs-lane PR. - Do not fabricate backfilled history; reconstruct only from real git signals and mark it as reconstructed. - Do not renumber or rewrite the project's existing git history. - Do not treat adoption as a phase; it needs no plan or log.