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

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.