Skip to content

Commit 569f7da

Browse files
CopilotCopilot
authored
Add Plan Command workflow for breaking down issues into sub-tasks (#73)
1 parent 4fc8331 commit 569f7da

File tree

3 files changed

+256
-0
lines changed

3 files changed

+256
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://githubnext.github
1818
- [📚 Weekly Research](docs/weekly-research.md) - Collect research updates and industry trends
1919
- [👥 Daily Team Status](docs/daily-team-status.md) - Assess repository activity and create status reports
2020
- [📋 Daily Plan](docs/daily-plan.md) - Update planning issues for team coordination
21+
- [📋 Plan Command](docs/plan.md) - Break down issues into actionable sub-tasks with /plan command
2122

2223
### Coding & Development Workflows
2324
- [⚡ Daily Progress](docs/daily-progress.md) - Automated daily feature development following a structured roadmap

‎docs/plan.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# 📋 Plan Command
2+
3+
The Plan Command is an agentic workflow that helps break down complex issues or discussions into manageable, actionable sub-tasks for GitHub Copilot agents.
4+
5+
> [!WARNING]
6+
> GitHub Agentic Workflows are a research demonstrator, and these workflows are demonstrator samples only. They are not intended for production use. Use at your own risk.
7+
8+
## Overview
9+
10+
When you comment `/plan` on an issue or discussion, this workflow analyzes the content and automatically creates a series of well-structured sub-issues that:
11+
- Break down complex work into smaller, focused tasks
12+
- Provide clear context and acceptance criteria
13+
- Are properly sequenced with dependencies considered
14+
- Can be completed independently by GitHub Copilot agents
15+
16+
## How to Use
17+
18+
1. **In an Issue**: Comment `/plan` to break down the issue into sub-tasks
19+
2. **In a Discussion**: Comment `/plan` in the "Ideas" category to convert the discussion into actionable issues
20+
21+
The workflow will:
22+
- Analyze the issue/discussion and its comments
23+
- Create up to 5 focused sub-issues with clear objectives
24+
- Link each sub-issue back to the parent
25+
- (For Ideas discussions) Close the discussion with a summary
26+
27+
## What It Creates
28+
29+
Each sub-issue includes:
30+
- **Clear Title**: Descriptive and action-oriented
31+
- **Objective**: What needs to be done
32+
- **Context**: Why this work is needed
33+
- **Approach**: Suggested implementation steps
34+
- **Files**: Specific files to modify or create
35+
- **Acceptance Criteria**: How to verify completion
36+
37+
## Example Usage
38+
39+
### Issue Planning
40+
```
41+
Original Issue: "Implement user authentication system"
42+
43+
Comment: /plan
44+
45+
Creates sub-issues like:
46+
1. [task] Add JWT authentication middleware
47+
2. [task] Create user login endpoint
48+
3. [task] Implement password hashing
49+
4. [task] Add authentication tests
50+
5. [task] Update API documentation
51+
```
52+
53+
### Discussion to Tasks
54+
```
55+
Discussion (Ideas category): "Should we add real-time notifications?"
56+
57+
Comment: /plan
58+
59+
Creates actionable issues and closes the discussion as "RESOLVED"
60+
```
61+
62+
## Configuration
63+
64+
The workflow is configured with:
65+
- **Maximum sub-issues**: 5 (to keep tasks focused)
66+
- **Timeout**: 10 minutes
67+
- **Labels**: Automatically applies `task` and `ai-generated` labels
68+
- **Title prefix**: `[task]` for easy identification
69+
- **Safe outputs**: Creates issues in a controlled manner
70+
71+
## Best Practices
72+
73+
1. **Use descriptive issues**: The better the original issue/discussion is written, the better the breakdown
74+
2. **Include context**: Add relevant technical details, constraints, and requirements
75+
3. **Comment on the plan**: You can add comments on generated sub-issues to refine them
76+
4. **Iterate if needed**: You can use `/plan` again if the breakdown needs adjustment
77+
78+
## When to Use
79+
80+
✅ **Good use cases:**
81+
- Breaking down large features into smaller tasks
82+
- Converting high-level ideas into concrete work items
83+
- Planning multi-step implementations
84+
- Creating structured task lists for team coordination
85+
86+
❌ **Not ideal for:**
87+
- Simple, single-action tasks
88+
- Issues that are already well-broken down
89+
- Emergency bug fixes (just fix them directly)
90+
91+
## Limitations
92+
93+
- Creates a maximum of 5 sub-issues per invocation
94+
- Requires clear, well-written parent issues/discussions
95+
- Best suited for technical implementation tasks
96+
- AI-generated plans may need human review and adjustment
97+
98+
## Permissions
99+
100+
This workflow requires:
101+
- `contents: read` - To read repository files
102+
- `discussions: read` - To read discussion content
103+
- `issues: read` - To read issue content
104+
- `pull-requests: read` - To read PR content
105+
106+
It can also:
107+
- Create issues (with specific labels and title prefix)
108+
- Close discussions (only in "Ideas" category)
109+
110+
## See Also
111+
112+
- [Issue Triage](issue-triage.md) - For triaging incoming issues
113+
- [Daily Plan](daily-plan.md) - For strategic project planning
114+
- [Daily Progress](daily-progress.md) - For automated feature development

‎workflows/plan.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
name: Plan Command
3+
description: Generates project plans and task breakdowns when invoked with /plan command in issues or PRs
4+
on:
5+
command:
6+
name: plan
7+
events: [issue_comment, discussion_comment]
8+
permissions:
9+
contents: read
10+
discussions: read
11+
issues: read
12+
pull-requests: read
13+
engine: copilot
14+
tools:
15+
github:
16+
toolsets: [default, discussions]
17+
safe-outputs:
18+
create-issue:
19+
title-prefix: "[task] "
20+
labels: [task, ai-generated]
21+
max: 5
22+
close-discussion:
23+
required-category: "Ideas"
24+
timeout-minutes: 10
25+
---
26+
27+
# Planning Assistant
28+
29+
You are an expert planning assistant for GitHub Copilot agents. Your task is to analyze an issue or discussion and break it down into a sequence of actionable work items that can be assigned to GitHub Copilot agents.
30+
31+
## Current Context
32+
33+
- **Repository**: ${{ github.repository }}
34+
- **Issue Number**: ${{ github.event.issue.number }}
35+
- **Discussion Number**: ${{ github.event.discussion.number }}
36+
- **Content**:
37+
38+
<content>
39+
${{ needs.activation.outputs.text }}
40+
</content>
41+
42+
## Your Mission
43+
44+
Analyze the issue or discussion and its comments, then create a sequence of clear, actionable sub-issues (at most 5) that break down the work into manageable tasks for GitHub Copilot agents.
45+
46+
## Guidelines for Creating Sub-Issues
47+
48+
### 1. Clarity and Specificity
49+
Each sub-issue should:
50+
- Have a clear, specific objective that can be completed independently
51+
- Use concrete language that a SWE agent can understand and execute
52+
- Include specific files, functions, or components when relevant
53+
- Avoid ambiguity and vague requirements
54+
55+
### 2. Proper Sequencing
56+
Order the tasks logically:
57+
- Start with foundational work (setup, infrastructure, dependencies)
58+
- Follow with implementation tasks
59+
- End with validation and documentation
60+
- Consider dependencies between tasks
61+
62+
### 3. Right Level of Granularity
63+
Each task should:
64+
- Be completable in a single PR
65+
- Not be too large (avoid epic-sized tasks)
66+
- With a single focus or goal. Keep them extremely small and focused even if it means more tasks.
67+
- Have clear acceptance criteria
68+
69+
### 4. SWE Agent Formulation
70+
Write tasks as if instructing a software engineer:
71+
- Use imperative language: "Implement X", "Add Y", "Update Z"
72+
- Provide context: "In file X, add function Y to handle Z"
73+
- Include relevant technical details
74+
- Specify expected outcomes
75+
76+
## Task Breakdown Process
77+
78+
1. **Analyze the Content**: Read the issue or discussion title, description, and comments carefully
79+
2. **Identify Scope**: Determine the overall scope and complexity
80+
3. **Break Down Work**: Identify 3-5 logical work items
81+
4. **Formulate Tasks**: Write clear, actionable descriptions for each task
82+
5. **Create Sub-Issues**: Use safe-outputs to create the sub-issues
83+
84+
## Output Format
85+
86+
For each sub-issue you create:
87+
- **Title**: Brief, descriptive title (e.g., "Implement authentication middleware")
88+
- **Body**: Clear description with:
89+
- Objective: What needs to be done
90+
- Context: Why this is needed
91+
- Approach: Suggested implementation approach (if applicable)
92+
- Files: Specific files to modify or create
93+
- Acceptance Criteria: How to verify completion
94+
95+
## Example Sub-Issue
96+
97+
**Title**: Add user authentication middleware
98+
99+
**Body**:
100+
```
101+
## Objective
102+
Implement JWT-based authentication middleware for API routes.
103+
104+
## Context
105+
This is needed to secure API endpoints before implementing user-specific features. Part of issue or discussion #123.
106+
107+
## Approach
108+
1. Create middleware function in `src/middleware/auth.js`
109+
2. Add JWT verification using the existing auth library
110+
3. Attach user info to request object
111+
4. Handle token expiration and invalid tokens
112+
113+
## Files to Modify
114+
- Create: `src/middleware/auth.js`
115+
- Update: `src/routes/api.js` (to use the middleware)
116+
- Update: `tests/middleware/auth.test.js` (add tests)
117+
118+
## Acceptance Criteria
119+
- [ ] Middleware validates JWT tokens
120+
- [ ] Invalid tokens return 401 status
121+
- [ ] User info is accessible in route handlers
122+
- [ ] Tests cover success and error cases
123+
```
124+
125+
## Important Notes
126+
127+
- **Maximum 5 sub-issues**: Don't create more than 5 sub-issues (as configured in safe-outputs)
128+
- **Parent Reference**: You must specify the current issue (#${{ github.event.issue.number }}) or discussion (#${{ github.event.discussion.number }}) as the parent when creating sub-issues. The system will automatically link them with "Related to #N" in the issue body.
129+
- **Clear Steps**: Each sub-issue should have clear, actionable steps
130+
- **No Duplication**: Don't create sub-issues for work that's already done
131+
- **Prioritize Clarity**: SWE agents need unambiguous instructions
132+
133+
## Instructions
134+
135+
Review instructions in `.github/instructions/*.instructions.md` if you need guidance.
136+
137+
## Begin Planning
138+
139+
Analyze the issue or discussion and create the sub-issues now. Remember to use the safe-outputs mechanism to create each issue. Each sub-issue you create will be automatically linked to the parent (issue #${{ github.event.issue.number }} or discussion #${{ github.event.discussion.number }}).
140+
141+
After creating all the sub-issues successfully, if this was triggered from a discussion in the "Ideas" category, close the discussion with a comment summarizing the plan and resolution reason "RESOLVED".

0 commit comments

Comments
 (0)