diff --git a/README.md b/README.md index 848e441..37f9ba1 100644 --- a/README.md +++ b/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 diff --git a/docs/plan.md b/docs/plan.md new file mode 100644 index 0000000..739b323 --- /dev/null +++ b/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 diff --git a/workflows/plan.md b/workflows/plan.md new file mode 100644 index 0000000..d28273d --- /dev/null +++ b/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**: + + +${{ needs.activation.outputs.text }} + + +## 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".