home / skills / dyad-sh / dyad / plan-to-issue

plan-to-issue skill

safe

This skill helps collaboratively plan a task and convert approved plans into a structured GitHub issue for streamlined execution.

npx playbooks add skill dyad-sh/dyad --skill plan-to-issue

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.2 KB

---
name: dyad:plan-to-issue
description: Create a plan collaboratively with the user, then convert the approved plan into a GitHub issue.
---

# Plan to Issue

Create a plan collaboratively with the user, then convert the approved plan into a GitHub issue.

## Arguments

- `$ARGUMENTS`: Brief description of what you want to plan (e.g., "add dark mode support", "refactor authentication system")

## Instructions

1. **Enter plan mode:**

   Use `EnterPlanMode` to begin the planning process. Explore the codebase to understand the current implementation and design an approach for: `$ARGUMENTS`

2. **Create a comprehensive plan:**

   Your plan should include:
   - **Summary**: Brief description of the goal
   - **Current state**: What exists today (based on codebase exploration)
   - **Proposed changes**: What needs to be implemented
   - **Files to modify**: List of files that will need changes
   - **Implementation steps**: Ordered list of specific tasks
   - **Testing approach**: What tests should be added
   - **Open questions**: Any decisions that need user input

3. **Iterate with the user:**

   Use `ExitPlanMode` to present your plan for approval. The user may:
   - Approve the plan as-is
   - Request modifications
   - Ask clarifying questions

   Continue iterating until the user approves the plan.

4. **Create the GitHub issue:**

   Once the plan is approved, create a GitHub issue using `gh issue create`:

   ```
   gh issue create --title "<concise title>" --body "$(cat <<'EOF'
   ## Summary
   <1-2 sentence description of the goal>

   ## Background
   <Current state and why this change is needed>

   ## Implementation Plan

   ### Files to Modify
   - `path/to/file1.ts` - <what changes>
   - `path/to/file2.ts` - <what changes>

   ### Tasks
   - [ ] <Task 1>
   - [ ] <Task 2>
   - [ ] <Task 3>
   ...

   ### Testing
   - [ ] <Test requirement 1>
   - [ ] <Test requirement 2>

   ## Notes
   <Any additional context, constraints, or open questions>

   ---
   *This issue was created from a planning session with Claude Code.*
   EOF
   )"
   ```

5. **Report the result:**

   Provide the user with:
   - The issue URL
   - A brief confirmation of what was created

Overview

This skill guides a collaborative planning session, generates a concrete implementation plan, and converts the approved plan into a GitHub issue. It helps developers move from high-level requests (e.g., "add dark mode support") to an actionable issue with files, tasks, tests, and open questions. The goal is to make planning repeatable, reviewable, and ready for execution in the repository workflow.

How this skill works

Start by entering plan mode to inspect the codebase and gather the current state relevant to the requested change. I produce a structured plan that includes a summary, current state, proposed changes, files to modify, ordered implementation steps, testing approach, and any open questions. After iterative review and approval, the skill formats the final plan and creates a GitHub issue using the gh CLI, then returns the new issue URL and a brief confirmation.

When to use it

You need a clear, reviewable implementation plan before work begins
Converting a verbal or high-level request into an actionable issue
Onboarding contributors with a documented set of tasks and files to change
Preparing work items for sprint planning or triage
When you want tests and open questions captured with implementation tasks

Best practices

Provide a concise request string describing the goal and scope
Be prepared to answer open questions about design or constraints during planning
Keep iterations focused: accept, tweak, or ask one area at a time
Include repository access and gh CLI configured for issue creation
Prefer small scopes per plan to generate targeted, testable issues

Example use cases

Add dark mode support: inspect UI components, list files, propose CSS/theme changes and tests
Refactor authentication: document current flow, propose API and frontend changes, list migration steps
Implement feature flag: identify integration points, list files, outline rollout and tests
Migrate to new library: outline compatibility changes, affected files, and testing plan
Add E2E tests: propose test cases, files to add, and CI adjustments

FAQ

What input does the skill require?

A short descriptive request (e.g., "refactor authentication system") so I can focus code inspection and planning.

Can I iterate on the plan before creating the issue?

Yes. The workflow expects iterative review: you can request edits or clarifications until you approve the plan.

How is the GitHub issue created?

Once approved, I format the plan into a Markdown issue body and run gh issue create with the title and body, then return the issue URL.