run-plan

Execute plans from docs/plans in an isolated Git worktree with micro-commits.

Updated Apr 30, 2026
One-click install
npx skills add https://github.com/fppfurtado/pragmatic-dev-toolkit --skill run-plan-fppfurtado
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: run-plan
Source: https://github.com/fppfurtado/pragmatic-dev-toolkit/tree/main/skills/run-plan
Command: npx skills add https://github.com/fppfurtado/pragmatic-dev-toolkit --skill run-plan-fppfurtado

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Planning and executing changes across a codebase often requires careful isolation, auditable commits, and governance. This Skill provides a repeatable workflow to run plans in dedicated worktrees, apply changes in small blocks, and gate validation before completion.

Core Features & Use Cases

  • Isolated worktree execution for plan changes
  • Micro-commit per block to keep history small and traceable
  • Per-block reviewers and a final gate before done
  • End-to-end plan execution from docs/plans with automated status updates

Quick Start

Create or select a plan in docs/plans, then run /run-plan <slug> to execute it in a dedicated worktree.

Frequently Asked Questions about run-plan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I execute a development plan in an isolated git worktree?

To execute a plan in an isolated git worktree, place a valid plan file in the docs/plans directory and run the execution command with the plan slug. The system applies changes in small blocks with micro-commits and runs a final validation gate before completion.

What is the best way to keep git history traceable when applying multi-step codebase changes?

The best way to keep git history traceable during multi-step changes is using micro-commits per block. This approach applies plan changes sequentially in an isolated worktree, ensuring each modification is small, auditable, and gated by reviewers before final completion.

Do I need a specific repository structure to automate plan execution with worktrees?

Yes, automating plan execution requires a Git repository containing a plans directory and a valid plan file. You also need a SKILL.md frontmatter to define the skill scope and prerequisites before triggering the isolated worktree workflow.

Can I use automated reviewers for each block of a plan before final validation?

Yes, automated per-block reviewers can be assigned to evaluate changes as they are applied in the isolated worktree. These reviewers coordinate with a gate-driven final validation step to ensure all plan blocks meet quality standards before completion.

How does triage integrate with plan execution in a git workflow?

Triage integrates with plan execution by retrieving valid plans from the /triage output. Once retrieved, the plan is executed in a dedicated worktree where changes are applied in blocks, reviewed, and validated against governance gates before merging.

When should I avoid using isolated worktrees for plan execution?

You should avoid using isolated worktrees for plan execution if your repository lacks a docs/plans directory or a valid plan file. Additionally, without a SKILL.md frontmatter to define prerequisites, the automated gating and micro-commit workflow cannot properly orchestrate the changes.