Functional Distinction Between writing-plans and executing-plans in OpenAI Superpowers

The writing-plans skill generates detailed implementation blueprints from high-level specifications, while the executing-plans skill consumes those blueprints to perform actual code changes, run tests, and manage commits.

In the openai/plugins repository, the Superpowers plugin provides autonomous development capabilities through specialized skills. The writing-plans and executing-plans skills represent two distinct phases of the software development lifecycle—architecting the work versus performing the work.

How writing-plans Designs Implementation Strategies

In plugins/superpowers/skills/writing-plans/SKILL.md, the writing-plans skill is defined as a blueprint generator that operates before any code is touched. It takes high-level specifications and produces complete, bite-sized implementation plans.

Key responsibilities include:

• Mapping out file structures and responsibilities with explicit paths
• Breaking work into 2–5 minute tasks containing exact code snippets and test commands
• Enforcing a "no placeholders" policy through self-review checklists
• Persisting the final plan to docs/superpowers/plans/ as a markdown document

When invoked via superpowers:writing-plans, the skill announces its intent and generates a structured document containing task checkboxes, verification commands, and architectural context. This output serves as the immutable contract for the implementation phase.

How executing-plans Performs the Implementation

Located in plugins/superpowers/skills/executing-plans/SKILL.md, the executing-plans skill functions as the operational engine that consumes pre-generated plans. It runs after a plan exists and transforms the documented steps into actual repository changes.

The execution workflow involves:

1. Loading the saved plan from docs/superpowers/plans/
2. Critically reviewing the plan for open questions or ambiguities
3. Creating a TodoWrite entry to track progress
4. Executing each task sequentially, marking states as in_progress and completed
5. Running exact verification commands (such as pytest or git operations) as specified in the plan
6. Handing off to superpowers:finishing-a-development-branch upon successful completion

If the skill encounters blockers—such as missing dependencies, failing verification steps, or unclear instructions—it stops immediately and returns to the review step rather than proceeding with potentially broken changes.

Critical Differences in Workflow Integration

While both skills require superpowers:using-git-worktrees to ensure isolated workspaces, they differ in their dependencies and integration points:

• writing-plans optionally integrates with superpowers:subagent-driven-development for parallel plan generation across multiple worktrees
• executing-plans strictly depends on the output of writing-plans and transitions to superpowers:finishing-a-development-branch for final cleanup

The writing-plans skill announces: "I'm using the writing-plans skill to create the implementation plan." Conversely, executing-plans announces: "I'm using the executing-plans skill to implement this plan."

Practical Example: From Specification to Committed Code

Consider a workflow where you need to add a new API endpoint. First, you invoke the planning skill:

superpowers:writing-plans

This generates a markdown file at docs/superpowers/plans/2024-10-01-add-feature.md containing structured tasks:

### Task 1: Add new API endpoint

**Files:**
- Create: `src/api/new_endpoint.py`
- Modify: `src/app.py:120-135`
- Test: `tests/api/test_new_endpoint.py`

- [ ] **Step 1: Write the failing test**

```python
def test_new_endpoint_returns_200(client):
    resp = client.get("/api/v1/new")
    assert resp.status_code == 200

• Step 2: Run test (should fail)

pytest tests/api/test_new_endpoint.py::test_new_endpoint_returns_200 -v

• Step 3: Implement minimal endpoint

def new_endpoint():
    return "", 200

• Step 4: Run test (should pass)

pytest tests/api/test_new_endpoint.py::test_new_endpoint_returns_200 -v

• Step 5: Commit

git add src/api/new_endpoint.py src/app.py tests/api/test_new_endpoint.py
git commit -m "feat: add new API endpoint"

Once this plan exists, invoking `superpowers:executing-plans` loads the document, executes each checkboxed step sequentially, and manages the state transitions from `in_progress` to `completed` as it runs the exact commands specified.

## Summary

- **writing-plans** operates during the design phase, generating immutable implementation blueprints with specific file paths, code blocks, and verification commands
- **executing-plans** operates during the implementation phase, consuming those blueprints to perform actual code changes, run tests, and manage git commits
- Both skills require isolated git worktrees but serve opposite ends of the development lifecycle
- Plans are stored in `docs/superpowers/plans/` and serve as the contract between the two skills
- Failure handling differs: writing-plans prompts for clarification on ambiguous specs, while executing-plans halts immediately on blockers

## Frequently Asked Questions

### What is the primary functional distinction between writing-plans and executing-plans?

The **writing-plans** skill generates detailed implementation blueprints from high-level specifications, deciding which files to touch and what code to write. The **executing-plans** skill consumes these blueprints to physically perform the work, executing the exact commands and code changes specified in the plan. One designs the roadmap; the other drives the implementation.

### Can executing-plans run without a pre-existing plan?

No. According to the source code in [`plugins/superpowers/skills/executing-plans/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/executing-plans/SKILL.md), the skill requires a saved plan file from `docs/superpowers/plans/`. It loads this document, reviews it critically, and only proceeds with execution if the plan contains no open questions or placeholder text.

### How do these skills handle failures or ambiguous instructions?

**writing-plans** checks for missing details, placeholder text, or ambiguous specification sections during generation, prompting the human partner to clarify before finalizing the plan. **executing-plans** stops immediately upon encountering blockers such as missing dependencies, failing verification commands, or unclear instructions, returning to the review step if the plan requires updates.

### Where are the generated plans stored in the repository?

The **writing-plans** skill saves generated implementation plans to the `docs/superpowers/plans/` directory as markdown documents. The **executing-plans** skill subsequently loads these files from the same location to begin the implementation workflow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}