fp-implement (Phase 3 — Implementation)

Translate the approved plan into commits, one step at a time. Each step is a
self-contained atomic commit pushed immediately — so if this turn is
interrupted, nothing is lost and the next run can pick up where it left off.

---

Setup

STATE=".agents/skills/feature-pipeline/scripts/state.sh"

Check preconditions before touching any code. Skipping this check is how bad
state propagates — an unapproved plan being implemented defeats the whole
purpose of the approval gate in /fp-plan:

approved=$($STATE get planApproved)   # must be "true"
branch=$($STATE get branch)
pr=$($STATE get prNumber)

If planApproved != true, tell the user clearly and end the turn:

⚠ Plan not yet approved. Run /fp-plan first and wait for approval.

Checkout the branch so all commits land in the right place:

git checkout "$branch"

---

Reading the plan

Fetch the approved plan from the PR body — this is the source of truth because
the user may have edited it during the approval step in /fp-plan:

gh pr view "$pr" --json body

If the fetch fails or the ## Plan section is empty, ask the user to paste
the plan. Don't guess or reconstruct from memory.

---

Implementation loop

Work through each numbered step in order. The one-step-one-commit discipline
matters: it keeps the diff reviewable, makes rollback surgical (git revert
on a single commit), and gives /fp-review clear commit messages to annotate.

For each step:

1. Implement the change in the relevant file(s). Read the file before editing
   so you don't clobber unrelated content.

2. Stage only the relevant hunks — don't sweep in unrelated changes:

   git add -p   # or git add <specific-files> when the step is clearly scoped

3. Commit with a conventional message so CI and reviewers can parse intent:

   git commit -m "<type>(<scope>): <description>"
   git push

4. Print one confirmation line:

     ✓ Step N committed: <short-hash>  <commit message>

Handling obstacles

If a step hits an unexpected blocker (import error, schema conflict, test
failure that reveals a new problem not in the plan) — stop immediately. Partial
work committed half-done is harder to untangle than a clean stop with a note.

• Leave a TODO comment at the exact location explaining what's needed.
• Commit the partial work so nothing is lost:

  git commit -m "wip(<scope>): partial step N — <obstacle summary>"
  git push

• Record the blockage in state so the next run can see it:

  $STATE set ciStatus "blocked"

• Print what the obstacle is, what file/line is involved, and what additional
  information would unblock it. Then end your turn — don't attempt the next
  step while this one is unresolved.

---

Phase completion

When all steps are committed and pushed, advance state so /fp-review knows to
start the sandbox pass:

$STATE set phase 4

Update the PR labels to reflect current status. needs-plan is no longer
accurate once code exists; in-progress signals the PR is ready for review:

# via GitHub MCP:
mcp__github__update_pull_request — remove "needs-plan", add "in-progress"

Print the M2 stop hook and end your turn. The stop hook is mandatory — it's
what tells the user which skill to run next and gives them a moment to scan
the commit list before review starts:

╔══ STOP HOOK M2 ══════════════════════════════════════════════════════════════╗
║  Implementation complete — <N> commits pushed to <branch>                    ║
║  Run /fp-review to start sandbox review.                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝

---

Constraints

• One commit per plan step — no squashing, no combining steps. Reviewers need
  to be able to understand each change in isolation.
• Never commit secrets, generated registry artifacts (docs/graph/*,
  registry/gaia.json), or files unrelated to the current step.
• Any registry mutations (registry/nodes/) must go through
  gaia dev add / gaia dev merge / gaia dev split — hand-edits skip
  timeline logging and break the audit trail.
• No force-pushes. If a commit needs to be undone, use git revert.
• End the turn after the stop hook. Sandbox review belongs to /fp-review.