Fr Execute

fr-execute

Implements a single phase from a plan.

Announce at start: "I'm using fr-execute to implement this phase."

Mode selection

PR format (unified)

When creating the PR for an agentic phase:

• Title: [{owner}/{repo}] {slug} · Phase {n}/{total} · {phase_title} — matches the Issue title shape so VK / GH / PR surfaces align.
• Body: first content block is the tracking block copied verbatim from the Issue body (the 📦 Repo: / 📋 Plan: / … lines plus the **Goal (from plan):** paragraph). Then proceed with your PR summary.

The fr pickup output below provides the canonical PR title template.

Label lifecycle (no manual transition verbs in v2)

The Issue moves: fr:ready → fr:in-progress → fr:pr-ready → closed. v2 has no manual transition verbs — every label flip is derived from what the renderer can observe on the Issue plus its linked PRs:

• fr:ready: the phase has a tracking_issue but no assignee, no draft PR, and no open non-draft PR.
• fr:in-progress: the Issue has an assignee OR a draft linked PR.
• fr:pr-ready: an open non-draft, non-merged linked PR exists.
• closed: state.completion.at is set on the phase AND a merged PR is observed AND no open linked PR remains (per _phase_complete in render.py).

The fr apply step at the end of the phase pushes whichever transitions the renderer projects from current GitHub state. To trigger fr:in-progress, assign yourself to the Issue (or open a draft PR); to trigger fr:pr-ready, take the PR out of draft.

Procedure

1. Get phase scope:

   fr pickup <plan-dir> --phase N
   

   Output is markdown: phase title, dependency reminder, PR title template, tasks + steps, and a pointer to _prose.md for plan-level context. The Depends on: line surfaces blockers — if any blocker phase is not yet Complete, stop and report.

2. Implement (superpowers:executing-plans, parallel phases: subagent-driven-development): end every task red → green → refactor or record no-refactor-because: P<n>.T<m> in the journal.

3. Tick steps as you complete them:

   fr plan edit <plan-dir> --tick P<n>.T<n>.S<n> --state x
   # or, to record a deliberate skip:
   fr plan edit <plan-dir> --tick P<n>.T<n>.S<n> --state - --note "<reason>"
   

4. Mark the phase complete (after every step is ticked):

   fr plan edit <plan-dir> --complete-phase N
   # manual phases require --note describing what was done
   fr plan edit <plan-dir> --complete-phase N --note "<runbook ref>"
   

   A phase carrying acceptance: [row-ids] — flip those matrix rows now (not-implemented → skipped/ci), citing the test refs; the CLI warns on unflipped rows (see fr-acceptance). Discovered edges may ADD rows (fr acceptance add) — defended at PR time, never silent scope drift.

5. Open the PR. Delegate to superpowers:finishing-a-development-branch. Use the PR title from fr pickup and the body shape above. Caveat — under fr-goal LOCAL mode, do NOT open a per-phase PR. Push the branch only; the single PR is fr-goal's step 8, opened (as a draft) by the orchestrator after its review pass — opening here reorders deliver ahead of review and reintroduces the #320 merge-race. Per-phase PRs remain the behaviour for the standalone dispatched (Issue/VK) flow only.

6. Reconcile GitHub state:

   fr apply <plan-dir>           # preview the projected mutations
   fr apply <plan-dir> --yes     # push label / state changes
   

   fr apply is idempotent. Safe to run before your PR merges — renderer needs BOTH completion.at AND a merged PR observed before projecting CLOSED, so this only sets pr-ready. Re-run after merge (or let the runner) to close.

Constraints

• Don't touch other phases. One phase = one PR, except fr-goal LOCAL mode (step 5's caveat) — never open a per-phase PR there.
• Stop if blocked — report what's missing.
• Step IDs: P<n>.T<n>.S<n>.

v1 plan migration

If you encounter a .md plan file (not a folder), it's a v1 plan that needs migration to the v2 plan-as-folder format before any execution:

fr migrate v1-to-v2           # preview (default)
fr migrate v1-to-v2 --yes     # apply: creates <slug>/ folders, moves .md to .md.v1-archive

Migration is repo-wide (converts every v1 plan, rewrites spec tables); commit as its own PR. "Legacy layout detected" → fr migrate dirs --yes.