executing-plans

Executing Plans

Overview

Load plan, review critically, execute all tasks, report when complete.

Announce at start: "I'm using the executing-plans skill to implement this plan."

Note: Tell your human partner that Metaforge works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use metaforge:subagent-driven-development instead of this skill.

The Process

Step 1: Load and Review Plan

1. Read plan file
2. Review critically - identify any questions or concerns about the plan
3. If concerns: Raise them with your human partner before starting
4. If no concerns: Create TodoWrite and proceed

Step 2: Execute Tasks

For each task:

1. Mark as in_progress
2. Follow each step exactly (plan has bite-sized steps)
3. Run verifications as specified
4. Mark as completed

Step 3: Complete Development

After all tasks complete and verified:

• Announce: "I'm using the finishing-a-development-branch skill to complete this work."
• REQUIRED SUB-SKILL: Use metaforge:finishing-a-development-branch
• Follow that skill to verify tests, present options, execute choice

When to Stop and Ask for Help

STOP executing immediately when:

• Hit a blocker (missing dependency, test fails, instruction unclear)
• Plan has critical gaps preventing starting
• You don't understand an instruction
• Verification fails repeatedly

Ask for clarification rather than guessing.

When to Revisit Earlier Steps

Return to Review (Step 1) when:

• Partner updates the plan based on your feedback
• Fundamental approach needs rethinking

Don't force through blockers - stop and ask.

Remember

• Review plan critically first
• Follow plan steps exactly
• Don't skip verifications
• Reference skills when plan says to
• Stop when blocked, don't guess
• Never start implementation on main/master branch without explicit user consent
• During fullstack plans: create checkpoint commits (and tags) after each phase, protect MCP-managed files, and use the feasibility matrix for mid-cycle changes

Full-Stack Plan Execution

The sections below activate when executing a fullstack plan — a plan that follows the phase model (Phases 1-5) with domain skill annotations and git checkpoints. Non-fullstack plans execute normally using the base process above.

Detecting a Fullstack Plan

A plan is fullstack when any of the following is true:

• Tasks are annotated with use metaforge:backend-schema, use metaforge:api-client-gen, use metaforge:frontend-page, or use metaforge:scaffold-project (this is the primary signal)
• The plan header or tasks reference a feature name (e.g., "Blog Posts", "Comments")
• Phases are numbered 1-5 with checkpoint conventions

Fullstack plans SHOULD declare feature_name: <name> in their metadata (plan frontmatter) for reliable detection and checkpoint naming.

When detected, the sections below govern execution. When not detected, skip them and follow the base process only.

Domain Skill Dispatch

When a plan task specifies a domain skill, invoke it via the Skill tool before executing the task steps. The domain skill provides MCP tool guidance, verification criteria, and phase-specific instructions that the base executing-plans skill does not cover.

Domain Skill Mapping:

Task Annotation	Domain Skill	Phase	Purpose
use metaforge:scaffold-project	metaforge:scaffold-project	Phase 1	Scaffold monorepo from template (scaffold-mcp)
use metaforge:backend-schema	metaforge:backend-schema	Phase 2	Design content-types via strapi-mcp
use metaforge:api-client-gen	metaforge:api-client-gen	Phase 3	Generate typed TS API client (api-types-mcp)
use metaforge:frontend-page	metaforge:frontend-page	Phase 4	Build pages with shadcn-mcp + api-types-mcp
use metaforge:verification-before-completion	metaforge:verification-before-completion	Phase 5	Fullstack integration checks

Dispatch Rules:

1. Read the plan task's description. If it contains a use metaforge:<skill> annotation, invoke that skill before executing any steps.
2. The domain skill will guide MCP tool usage and provide phase-specific verification. Follow its instructions over generic executing-plans steps when they conflict.
3. Domain skills are invoked once per task, at the start of task execution.
4. Tasks without a domain skill annotation execute normally — follow the plan steps as written.
5. Non-fullstack plans never trigger domain skill dispatch.

Git Checkpoints

After each fullstack phase completes successfully, create a git commit with a standard checkpoint message. These checkpoints enable Option B rollback (see Option B Pivot Handling below).

Checkpoint Commits:

Phase	Commit Message	When
Phase 1	checkpoint:scaffold	After scaffold_init succeeds + verification passes
Phase 2	checkpoint:feature/<name>/schema	After schema_commit succeeds + schema_read verifies
Phase 3	checkpoint:feature/<name>/types	After generate_api_client succeeds + npx tsc --noEmit passes
Phase 4	checkpoint:feature/<name>/pages	After all pages built + npm run build succeeds
Phase 5	checkpoint:feature/<name>/verified	After all integration checks pass

These verification tools are provided by the respective MCP servers (scaffold-mcp, strapi-mcp, api-types-mcp, strapi-routes-mcp). Refer to the corresponding domain skill for usage details.

Feature Name Extraction:

Extract <name> from the plan in this order of priority:

1. feature_name: <name> metadata field in the plan frontmatter (most reliable)
2. Plan header title — extract the noun phrase after "for" or ":" if present (e.g., # Implementation Plan for Blog Posts → blog-posts)
3. The first domain-annotated task's feature reference
4. Ask the user ("What feature name should I use for checkpoints?")
5. If all above fail: use unnamed-feature as fallback

Convert to lowercase kebab-case: Blog Posts → blog-posts.

Rules:

• Create the checkpoint commit immediately after phase verification passes, before starting the next phase.
• After each checkpoint commit, run git tag <checkpoint-name> so the checkpoint is a valid git ref. (Commit messages alone are not valid refs; rollback commands use the tag.)
• Do NOT create checkpoints for non-fullstack plans.
• If a phase fails verification, do not checkpoint — fix the issue first.
• Checkpoint commits must include all files changed in that phase.

File Protection Guard

During fullstack plan execution, perform a best-effort pre-write check. Before any Write or Edit tool call, check if the target file path matches a protected pattern. This is a cooperative skill-level guard, not filesystem enforcement. It is only active during fullstack plan execution. For programmatic enforcement, a PreToolUse hook can be configured. The guard deactivates after metaforge:finishing-a-development-branch completes.

Protected Paths (MCP-Managed, Agent Read-Only):

Path Pattern	Managed By
backend/**	scaffold-mcp + strapi-mcp
frontend/src/api/**	api-types-mcp
frontend/src/components/ui/**	shadcn-mcp
frontend/src/**/*.css	shadcn-mcp
frontend/node_modules/**	npm
.strapi-mcp/temp/**	strapi-mcp

User-Editable Paths (Agent Can Write):

Path Pattern	Purpose
frontend/src/pages/**	Page components
frontend/src/layouts/**	Layout components
frontend/src/hooks/**	Custom hooks
frontend/src/lib/**	Utility functions

Check Procedure:

Before every file write:

1. Compare the target path against the protected path patterns above.
2. If it matches a protected pattern → refuse the write and output: "This file is managed by <MCP>. Use the corresponding domain skill instead." Replace <MCP> with the specific MCP name from the table.
3. If it does not match → proceed normally.
4. If the path is not covered by any pattern (e.g., root config files, test files) → proceed normally (default allow).

Rationale: MCP-generated files must remain the single source of truth. If the Agent hand-edits src/api/namespaces/articles.ts, the next generate_api_client will overwrite those edits or produce merge conflicts.

Option B Pivot Handling

Users can interrupt fullstack execution mid-cycle with a change request. This section defines how to assess feasibility and execute (or reject) the pivot.

Detection: The user sends a change request while in the middle of Phase 2, 3, or 4 execution — after at least one checkpoint commit exists.

Process:

1. Identify which phase/domain the change affects (schema, types, pages, or template).
2. Create pivot branch: git checkout -b pivot/<change-name> off the last completed checkpoint.
3. Invoke the affected domain skill via the Skill tool with the user's change request as context. The domain skill will guide you through re-applying the relevant MCP tools for the delta (not re-executing the full task from scratch).
4. Feasibility check: Run npx gitnexus analyze to refresh the index, then use gitnexus_impact on the staged changes. The index must be fresh before impact analysis is meaningful. If npx gitnexus analyze fails, stop and report the failure. Do not proceed to impact analysis with a stale index.
5. Apply the feasibility matrix (see below) to determine the action.
6. If FEASIBLE: Auto-execute affected downstream phases, verify each, then merge the pivot branch: git checkout - && git merge pivot/<change-name>.
7. If NOT FEASIBLE: Present concrete rollback options (see below).

Feasibility Matrix:

Pivot Type	Downstream Impact	Action
Add/remove field	Re-gen API types	Auto-proceed
Add content-type	Re-gen types + maybe new pages	Auto-proceed
Rename content-type	Re-gen types + update all page imports	Check usage; warn if pages affected
Change field type (string → relation)	Types change shape + pages need rewrite	Warn; require user confirmation
Delete content-type with pages	Pages break, types break	Block — explain rollback needed
Change template (React → Vue)	Entire frontend replace	Block — explain rollback to Phase 1
Switch component library	All pages rewrite	Block — explain rollback to Phase 1

Risk Thresholds (from gitnexus_impact):

Risk Level	Consumers Affected	Action
LOW	0-3	Auto-proceed
MEDIUM	4-9	Warn user, ask to proceed
HIGH/CRITICAL	10+	Block, require user override

When both the feasibility matrix and risk threshold suggest different actions, use the more conservative one (block > warn > auto-proceed).

Rollback Options (when pivot is not feasible):

Present the user with concrete rollback choices:

This change is not feasible to apply mid-cycle. Options:

1. Roll back to checkpoint:feature/<name>/schema, redesign, replay phases 3+4
   Command: git reset --hard checkpoint:feature/<name>/schema

2. Roll back to checkpoint:scaffold, redo from Phase 2
   Command: git reset --hard checkpoint:scaffold

3. Continue without the change and finish the current cycle.

(These commands use git tags created after each checkpoint commit, so they are valid refs.)

Wait for user confirmation before executing any rollback. Never git reset --hard without explicit user consent.

Integration

Required workflow skills:

• metaforge:using-git-worktrees - REQUIRED: Set up isolated workspace before starting
• metaforge:writing-plans - Creates the plan this skill executes
• metaforge:finishing-a-development-branch - Complete development after all tasks