Add Plan Command workflow for breaking down issues into sub-tasks

README.md

@@ -17,6 +17,7 @@ A sample family of reusable [GitHub Agentic Workflows](https://githubnext.github
 - [📚 Weekly Research](docs/weekly-research.md) - Collect research updates and industry trends
 - [👥 Daily Team Status](docs/daily-team-status.md) - Assess repository activity and create status reports
 - [📋 Daily Plan](docs/daily-plan.md) - Update planning issues for team coordination
+- [📋 Plan Command](docs/plan.md) - Break down issues into actionable sub-tasks with /plan command
 
 ### Coding & Development Workflows
 - [⚡ Daily Progress](docs/daily-progress.md) - Automated daily feature development following a structured roadmap

docs/plan.md

@@ -0,0 +1,114 @@
+# 📋 Plan Command
+
+The Plan Command is an agentic workflow that helps break down complex issues or discussions into manageable, actionable sub-tasks for GitHub Copilot agents.
+
+> [!WARNING]
+> 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.
+
+## Overview
+
+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:
+- Break down complex work into smaller, focused tasks
+- Provide clear context and acceptance criteria
+- Are properly sequenced with dependencies considered
+- Can be completed independently by GitHub Copilot agents
+
+## How to Use
+
+1. **In an Issue**: Comment `/plan` to break down the issue into sub-tasks
+2. **In a Discussion**: Comment `/plan` in the "Ideas" category to convert the discussion into actionable issues
+
+The workflow will:
+- Analyze the issue/discussion and its comments
+- Create up to 5 focused sub-issues with clear objectives
+- Link each sub-issue back to the parent
+- (For Ideas discussions) Close the discussion with a summary
+
+## What It Creates
+
+Each sub-issue includes:
+- **Clear Title**: Descriptive and action-oriented
+- **Objective**: What needs to be done
+- **Context**: Why this work is needed
+- **Approach**: Suggested implementation steps
+- **Files**: Specific files to modify or create
+- **Acceptance Criteria**: How to verify completion
+
+## Example Usage
+
+### Issue Planning
+```
+Original Issue: "Implement user authentication system"
+
+Comment: /plan
+
+Creates sub-issues like:
+1. [task] Add JWT authentication middleware
+2. [task] Create user login endpoint
+3. [task] Implement password hashing
+4. [task] Add authentication tests
+5. [task] Update API documentation
+```
+
+### Discussion to Tasks
+```
+Discussion (Ideas category): "Should we add real-time notifications?"
+
+Comment: /plan
+
+Creates actionable issues and closes the discussion as "RESOLVED"
+```
+
+## Configuration
+
+The workflow is configured with:
+- **Maximum sub-issues**: 5 (to keep tasks focused)
+- **Timeout**: 10 minutes
+- **Labels**: Automatically applies `task` and `ai-generated` labels
+- **Title prefix**: `[task]` for easy identification
+- **Safe outputs**: Creates issues in a controlled manner
+
+## Best Practices
+
+1. **Use descriptive issues**: The better the original issue/discussion is written, the better the breakdown
+2. **Include context**: Add relevant technical details, constraints, and requirements
+3. **Comment on the plan**: You can add comments on generated sub-issues to refine them
+4. **Iterate if needed**: You can use `/plan` again if the breakdown needs adjustment
+
+## When to Use
+
+✅ **Good use cases:**
+- Breaking down large features into smaller tasks
+- Converting high-level ideas into concrete work items
+- Planning multi-step implementations
+- Creating structured task lists for team coordination
+
+❌ **Not ideal for:**
+- Simple, single-action tasks
+- Issues that are already well-broken down
+- Emergency bug fixes (just fix them directly)
+
+## Limitations
+
+- Creates a maximum of 5 sub-issues per invocation
+- Requires clear, well-written parent issues/discussions
+- Best suited for technical implementation tasks
+- AI-generated plans may need human review and adjustment
+
+## Permissions
+
+This workflow requires:
+- `contents: read` - To read repository files
+- `discussions: read` - To read discussion content
+- `issues: read` - To read issue content
+- `pull-requests: read` - To read PR content
+
+It can also:
+- Create issues (with specific labels and title prefix)
+- Close discussions (only in "Ideas" category)
+
+## See Also
+
+- [Issue Triage](issue-triage.md) - For triaging incoming issues
+- [Daily Plan](daily-plan.md) - For strategic project planning
+- [Daily Progress](daily-progress.md) - For automated feature development

workflows/plan.md

@@ -0,0 +1,141 @@
+---
+name: Plan Command
+description: Generates project plans and task breakdowns when invoked with /plan command in issues or PRs
+on:
+  command:
+    name: plan
+    events: [issue_comment, discussion_comment]
+permissions:
+  contents: read
+  discussions: read
+  issues: read
+  pull-requests: read
+engine: copilot
+tools:
+  github:
+    toolsets: [default, discussions]
+safe-outputs:
+  create-issue:
+    title-prefix: "[task] "
+    labels: [task, ai-generated]
+    max: 5
+  close-discussion:
+    required-category: "Ideas"
+timeout-minutes: 10
+---
+
+# Planning Assistant
+
+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.
+
+## Current Context
+
+- **Repository**: ${{ github.repository }}
+- **Issue Number**: ${{ github.event.issue.number }}
+- **Discussion Number**: ${{ github.event.discussion.number }}
+- **Content**: 
+
+<content>
+${{ needs.activation.outputs.text }}
+</content>
+
+## Your Mission
+
+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.
+
+## Guidelines for Creating Sub-Issues
+
+### 1. Clarity and Specificity
+Each sub-issue should:
+- Have a clear, specific objective that can be completed independently
+- Use concrete language that a SWE agent can understand and execute
+- Include specific files, functions, or components when relevant
+- Avoid ambiguity and vague requirements
+
+### 2. Proper Sequencing
+Order the tasks logically:
+- Start with foundational work (setup, infrastructure, dependencies)
+- Follow with implementation tasks
+- End with validation and documentation
+- Consider dependencies between tasks
+
+### 3. Right Level of Granularity
+Each task should:
+- Be completable in a single PR
+- Not be too large (avoid epic-sized tasks)
+- With a single focus or goal. Keep them extremely small and focused even if it means more tasks.
+- Have clear acceptance criteria
+
+### 4. SWE Agent Formulation
+Write tasks as if instructing a software engineer:
+- Use imperative language: "Implement X", "Add Y", "Update Z"
+- Provide context: "In file X, add function Y to handle Z"
+- Include relevant technical details
+- Specify expected outcomes
+
+## Task Breakdown Process
+
+1. **Analyze the Content**: Read the issue or discussion title, description, and comments carefully
+2. **Identify Scope**: Determine the overall scope and complexity
+3. **Break Down Work**: Identify 3-5 logical work items
+4. **Formulate Tasks**: Write clear, actionable descriptions for each task
+5. **Create Sub-Issues**: Use safe-outputs to create the sub-issues
+
+## Output Format
+
+For each sub-issue you create:
+- **Title**: Brief, descriptive title (e.g., "Implement authentication middleware")
+- **Body**: Clear description with:
+  - Objective: What needs to be done
+  - Context: Why this is needed
+  - Approach: Suggested implementation approach (if applicable)
+  - Files: Specific files to modify or create
+  - Acceptance Criteria: How to verify completion
+
+## Example Sub-Issue
+
+**Title**: Add user authentication middleware
+
+**Body**:
+```
+## Objective
+Implement JWT-based authentication middleware for API routes.
+
+## Context
+This is needed to secure API endpoints before implementing user-specific features. Part of issue or discussion #123.
+
+## Approach
+1. Create middleware function in `src/middleware/auth.js`
+2. Add JWT verification using the existing auth library
+3. Attach user info to request object
+4. Handle token expiration and invalid tokens
+
+## Files to Modify
+- Create: `src/middleware/auth.js`
+- Update: `src/routes/api.js` (to use the middleware)
+- Update: `tests/middleware/auth.test.js` (add tests)
+
+## Acceptance Criteria
+- [ ] Middleware validates JWT tokens
+- [ ] Invalid tokens return 401 status
+- [ ] User info is accessible in route handlers
+- [ ] Tests cover success and error cases
+```
+
+## Important Notes
+
+- **Maximum 5 sub-issues**: Don't create more than 5 sub-issues (as configured in safe-outputs)
+- **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.
+- **Clear Steps**: Each sub-issue should have clear, actionable steps
+- **No Duplication**: Don't create sub-issues for work that's already done
+- **Prioritize Clarity**: SWE agents need unambiguous instructions
+
+## Instructions
+
+Review instructions in `.github/instructions/*.instructions.md` if you need guidance.
+
+## Begin Planning
+
+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 }}).
+
+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".