phase

Phase Workflow: Start and Finish Phases

Overview

Manages the lifecycle of PLAN.md phases: starting a phase (creating a branch, updating status) and finishing it (running gates, creating PRs). Enforces the branch-per-phase convention and ensures PRs are never created without validation.

Arguments

• /plangate:phase start N [description] — Start phase N with optional description
• /plangate:phase finish [N] — Finish current or specified phase

---

Mode: Start

Step 1: Validate Git State

git status

Verify:

• Working tree is clean (no uncommitted changes)
• Currently on main or a base branch
• No untracked files that should be committed

If working tree is dirty, warn the user and ask whether to stash or commit first.

Step 2: Read PLAN.md

Read PLAN.md and find Phase {N}. Extract:

• Phase title/description
• Task list for this phase
• Any prerequisites or dependencies on previous phases

If the argument doesn't include a description, derive one from the phase title in PLAN.md.

Step 3: Create Branch

Generate branch name following convention:

feat/phase-{N}-{kebab-case-description}

Examples:

• feat/phase-1-foundation-and-setup
• feat/phase-2-core-api-endpoints
• feat/phase-3-auth-and-permissions

git checkout -b feat/phase-{N}-{description}

Step 3.5: Ensure .plangate/ is gitignored

Check if .plangate/ is in .gitignore. If not, add it:

grep -q '\.plangate/' .gitignore 2>/dev/null || echo -e '\n# Plangate orchestration state\n.plangate/' >> .gitignore

This prevents checkpoint files from being committed. Stage the .gitignore change if modified.

Step 4: Update PLAN.md Status

Change the phase status to "In Progress":

• Find the phase heading in PLAN.md
• If there's a status indicator, update it (e.g., **Status: In Progress**)
• Stage both PLAN.md and .gitignore (if modified)
• Commit this change: git commit -m "chore: start phase {N} — {description}"

Step 5: Report

Phase {N} started.
Branch: feat/phase-{N}-{description}
Tasks: {count} tasks to complete

Ready to implement. Use /plangate:orchestrate {N} to begin task execution.

---

Mode: Finish

Step 1: Identify Current Phase

If phase number is provided, use it. Otherwise, detect from current branch name:

git branch --show-current

Parse feat/phase-{N}-... to extract N.

Step 2: Verify Phase Completion

Read PLAN.md and check that ALL tasks for this phase are checked off (- [x]).

If any tasks are unchecked (- [ ]), warn:

Phase {N} has {count} uncompleted tasks:
- [ ] {task 1}
- [ ] {task 2}

Complete all tasks before finishing the phase.

STOP — do not proceed with incomplete tasks.

Step 3: Run Pre-PR Gate

Invoke the plangate:gate skill. This runs typecheck + lint + build + tests.

If the gate fails, STOP. Report the failures and do not proceed to PR creation.

Step 4: Update PLAN.md Status

Update the phase status to "Complete":

• Change status indicator to **Status: Complete**
• Commit: git commit -m "chore: complete phase {N}"

Step 5: Push and Create PR

First, verify a remote exists:

git remote get-url origin 2>/dev/null

If no remote is configured:

1. Ask the user: "No Git remote configured. Would you like to create a GitHub repo with gh repo create, or skip the PR step?"
2. If they want to create: run gh repo create {project-name} --private --source=. --push, then push main separately (git push origin main)
3. If they want to skip: report that the phase is complete locally and they can push/PR later. STOP here.

If remote exists, push:

git push -u origin feat/phase-{N}-{description}

Create PR using the user's template:

gh pr create --base main --head feat/phase-{N}-{description} \
  --title "feat(phase-{N}): {phase title}" \
  --body "$(cat <<'EOF'
## Summary
{2-3 bullet points summarizing what this phase implemented}

## Implementation
{Key technical decisions and approaches}

## Testing
{What was tested and how}

## Technical Details
{Architecture notes, migration details, etc.}

## Next Phase
{What Phase N+1 will cover, if applicable}

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Step 6: Report

Phase {N} complete!
PR: {PR_URL}
Branch: feat/phase-{N}-{description}

Summary:
- {count} tasks completed
- All gates passed (typecheck, lint, build, tests)
- PR created and ready for review

---

Key Principles

Never Skip the Gate

The pre-PR gate is mandatory. Even if you "just ran it" during orchestration, run it again. Code may have changed.

Clean Commits

Phase start and finish get their own clean commits (chore: prefix). Implementation commits use feat: or fix: prefixes.

One Phase Per Branch

Each phase gets its own branch. Never mix phases on a single branch.

Integration

• Works with plangate:orchestrate for task execution within a phase
• Uses plangate:gate for validation before PR creation
• Follows the branch naming convention from CLAUDE.md