Phase project init

Phase Project Init

This skill prepares an empty or new project so the rest of the phase workflow has the structure it expects. Run it once, at the very start of a project.

Empty repo only. If the project already has code and git history, use phase-adopt instead — it lands the same scaffolding through a docs-lane PR rather than the direct bootstrap commit below.

It is not itself a phase — bootstrapping needs no phase plan or log. It is the one time it is acceptable to make a direct commit to the default branch (the initial scaffold commit), because there is nothing yet to branch from. Every commit after this one goes through the branch + worktree + PR cycle.

What "set up" means

By the end, the project has:

1. A git repository with an initial commit and a known default branch.
2. A knowledge bundle at development/ — a design/ layer, a phase_log/ layer with the three templates and a seeded phase_index.md, and the reserved root files — plus its schema and validator under scripts/okf/.
3. The conventions the phase skills rely on, optionally documented at the project root.
4. A clear answer to "what's the first phase?" — handed off to phase-tracker (single effort) or phase-loop (large umbrella plan).

Procedure

Step 1: Confirm the project root and intent

Confirm the directory to initialize and that it is meant to be a new phase-workflow project. If it already has a development/phase_log/, stop — it's already initialized; offer phase-recap instead. Ask the user one question if anything is ambiguous: project name, default branch name (main unless they say otherwise), and whether this project will keep living design docs.

Step 2: Initialize git

• If not already a repo, git init and set the default branch (git branch -M main or the chosen name).
• Create a .gitignore if none exists — minimal and appropriate to the stack the user names (don't guess heavily; a near-empty .gitignore is fine to start). Include .worktrees/ — every phase worktree is created there and must never be tracked by the primary checkout.
• Note the branch-protection convention to the user: the default branch is protected by policy — all later changes reach it only through PRs. Local git can't enforce this; if a remote exists, suggest enabling branch protection there. Record it as a rule, not an enforced setting.

Step 3: Create the knowledge bundle

development/ is a knowledge bundle: everything inside it is a concept — a document with front matter that the validator checks. Evidence and analysis (audits, triage notes, scratch research) live outside it, so the directory explains itself without anyone reading an ignore file.

Copy this skill's bundled payload wholesale — the asset tree is already the target shape:

• assets/development/ → development/
  • index.md, log.md, .okfignore — the reserved root files.
  • design/index.md, design/_element_template.md — the curated current-state layer.
  • phase_log/phase_plan_template.md, phase_log/phase_log_template.md, phase_log/phase_index.md — the phase-history layer, seeded and empty.
• assets/scripts/okf/ → scripts/okf/
  • manage_bundle.py — the validator and graph builder. Stdlib only, so it runs before the project has installed anything.
  • profile.md — the schema contract it enforces.

Then prove the scaffold is sound before committing it:

python3 scripts/okf/manage_bundle.py validate

A fresh bundle reports two concepts (the design template and the profile). If it reports an error, fix the scaffold rather than proceeding — every later phase depends on this being clean.

Keep design/ even if the project has nothing to document yet; the layer costs one index file and phase-tracker Step 3.5 fills it in as phases land.

Step 4: Install the conventions (optional but recommended)

The phase skills each embed their own conventions, so they work without these files. Installing them at the project root makes the project self-documenting and lets the skills' reference links resolve:

• TERMINOLOGY.md — the Major / Minor / Patch glossary and the scoped-recap rules.
• templates/recap_template.md and templates/response_templates.md — the recap report format and the labeled response banners.
• phase_project.md — the portable workflow charter (used in Step 5).

If the full phase-skills suite is available alongside the skills, copy those files to the project root. If only the individual skills were dropped in, skip this — nothing breaks.

Step 5: Seed or update the project's CLAUDE.md

Add the phase workflow charter to the project's CLAUDE.md: paste the content of phase_project.md (everything below its ---). It is self-sufficient — it drives the workflow even without the skills, and it carries the terminology, response banners, and git rules into the project. If a CLAUDE.md exists, append the charter (don't overwrite the project's existing guidance); if not, create one with it. phase_project.md is the single source for this section — don't hand-write a divergent version.

Step 6: Initial commit

Stage the scaffolding with an explicit file list (the development/ tree, scripts/okf/, .gitignore, any conventions/CLAUDE.md added) and commit to the default branch:

chore: bootstrap phase workflow scaffolding

End with the Co-Authored-By: trailer. This is the only sanctioned direct-to-default-branch commit; say so when you make it.

Step 7: Hand off to the first phase

Determine the first unit of work with the user and route to the right skill:

• One concrete effort → phase-tracker, starting at 1.1.0 (the first Minor of Major 1). Cut the branch + worktree (under .worktrees/) and write the plan.
• A large multi-step plan / umbrella → phase-decompose to chunk it into a quality roadmap, then phase-loop to run the cycles until complete. The umbrella/roadmap plan is 1.0.0 (MAJOR.0.0).

Numbering starts at Major 1. Reserve MAJOR.0.0 for a Major's umbrella/roadmap plan; the first real feature is 1.1.0.

Setup summary

When done, give the user a short report: repo initialized (default branch), development/phase_log/ created with templates + seeded index, conventions installed (or skipped), CLAUDE.md created/updated (or not), initial commit made, and the proposed first phase with the skill that will run it.

What this skill should not do

• Do not run it on an already-initialized project (one that has development/phase_log/). Use phase-recap to load state instead.
• Do not put anything but concepts inside development/. Audits, triage notes, scratch research, and tooling go elsewhere in the repo — the validator fails on strays, and that refusal is the point.
• Do not treat the bootstrap as a phase — no plan/log for the setup itself.
• Do not commit project source code in the bootstrap commit; this commit is scaffolding only. Real work starts on a branch in the next step.
• Do not invent project specifics (stack, design docs, branch names) — ask when unsure.