Implements a plan from a markdown file, phase by phase, with semantic branch names and commits between phases. Use when user says "implement this plan", "implement plan", "execute this plan", "run this plan", or references a plan file path to implement. Can also push and open a PR if explicitly asked. Do NOT use for creating plans, reviewing plans, or general code tasks without a plan file.
Reads a markdown plan file, creates a semantic git branch, implements each phase with commits between them, and runs verification steps.
Read the plan file at the given path. Extract:
feat), bug fix (fix), refactor (refactor), chore (chore), docs (docs), or test (test)?If the plan file doesn't exist or is empty, stop and tell the user.
If the plan has no clear phases or sections, treat the entire implementation as a single phase.
Derive the branch name from the plan's title and change type:
<type>/<short-kebab-description>
Type mapping:
feat/fix/refactor/chore/docs/test/Branch name rules:
Create the branch from the current HEAD before writing any code.
For each phase in the plan:
<type>(<scope>): <what this phase accomplishes>
Do not move to the next phase until the current one is committed.
If a phase's instructions are ambiguous or reference code that doesn't exist, stop and ask the user before guessing.
After all phases are implemented and committed, look for a verification/testing section in the plan. Common patterns:
pnpm test, pnpm build, migration commands)For each verification step that can be automated (shell commands, test runs, build checks):
fix(<scope>): resolve <what failed>Report the verification results to the user. If any manual checks are listed, remind the user to perform them.
After verification, present a summary:
Stop here. Do not push or create a PR unless the user explicitly asks.
If the user says to push, create a PR, or similar:
-u flagUser says: "implement this plan docs/plans/goal-entry-value-plan.md"
Actions:
docs/plans/goal-entry-value-plan.mdfeat (adds new capability)feat/goal-entry-valuefeat(backend): add goal type and entry value columnsfeat(frontend): add value input for goal entriespnpm --filter backend run test, pnpm --filter frontend run buildUser says: "implement this plan docs/plans/remove-weight-unit-plan.md"
Actions:
docs/plans/remove-weight-unit-plan.mdrefactor (removing unnecessary field)refactor/remove-weight-unitrefactor(backend): drop weightUnit columnrefactor(backend): remove weightUnit from entities and DTOsrefactor(frontend): remove weight unit selector, hardcode kgUser says: "implement this plan docs/plans/some-plan.md and open a PR"
Actions:
1-7. Same as above
8. Push branch: git push -u origin feat/some-feature
9. Create PR with title and summary from plan
Cause: wrong path or file doesn't exist. Solution: ask the user to confirm the path. Check relative to the current working directory.
Cause: the plan may be outdated or based on a different branch state. Solution: stop and ask the user. Do not guess or improvise — the plan is the source of truth.
Cause: the fix may have introduced new issues or the plan's approach may be flawed. Solution: after two failed fix attempts for the same verification step, stop and report the failure to the user with the error output. Let them decide how to proceed.