run-plan

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

Updated Apr 30, 2026

Search Tags:#automation #git #workflow #planning #worktree #review #triage

Ready to run

npx skills add https://github.com/fppfurtado/pragmatic-dev-toolkit --skill run-plan-fppfurtado

💬 Prompt for ChatGPT / Claude Chat▼

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.