plan-flow-skill 1.0.0

package/rules/tools/auth-pr-tool.mdc

@@ -0,0 +1,362 @@
+---
+description: "Include when PR authentication is needed for GitHub or Azure DevOps access"
+alwaysApply: false
+---
+
+# PR Authentication Tool
+
+## Purpose
+
+Provides authentication mechanism for accessing Pull Requests from GitHub or Azure DevOps using Personal Access Tokens (PATs). This tool handles platform detection, credential loading, authentication, and access verification.
+
+## Usage
+
+This tool can be used by skills or commands that need to authenticate and access PRs from GitHub or Azure DevOps.
+
+**Example**: Used by the `review-pr` skill to authenticate before fetching PR information.
+
+## Inputs
+
+| Input      | Required | Description                                      |
+| ---------- | -------- | ------------------------------------------------ |
+| `pr_link`  | Yes      | The URL of the Pull Request                      |
+
+The tool automatically detects the platform from the PR URL:
+- **GitHub**: URLs contain `github.com`
+- **Azure DevOps**: URLs contain `dev.azure.com` or `visualstudio.com`
+
+## Configuration
+
+### Environment Variables
+
+Store authentication tokens in `.plan.flow.env` (this file is gitignored for security):
+
+```bash
+# GitHub Authentication
+GITHUB_TOKEN=ghp_your_token_here
+
+# Azure DevOps Authentication
+AZURE_DEVOPS_PAT=your_pat_here
+```
+
+## Workflow
+
+### Step 1: Detect Platform
+
+Analyze the PR URL to determine the platform:
+
+```bash
+# Extract platform from PR URL
+# GitHub: github.com
+# Azure DevOps: dev.azure.com or visualstudio.com
+```
+
+### Step 2: Load Credentials from `.plan.flow.env` (REQUIRED FIRST STEP)
+
+**ALWAYS start by reading the `.plan.flow.env` file:**
+
+```bash
+# Read .plan.flow.env and extract credentials
+```
+
+| Platform     | Environment Variable | Purpose                                           |
+| ------------ | -------------------- | ------------------------------------------------- |
+| GitHub       | `GITHUB_TOKEN`       | GitHub Personal Access Token                      |
+| Azure DevOps | `AZURE_DEVOPS_PAT`   | Azure DevOps Personal Access Token                |
+
+### Step 3: Authenticate Using Credentials
+
+#### For GitHub PRs:
+
+```bash
+# Authenticate using token from .plan.flow.env
+echo "$GITHUB_TOKEN" | gh auth login --with-token
+
+# Verify authentication
+gh auth status
+```
+
+#### For Azure DevOps PRs:
+
+```bash
+# Set the PAT for Azure DevOps CLI
+export AZURE_DEVOPS_EXT_PAT="$AZURE_DEVOPS_PAT"
+
+# Or use directly in curl requests with Basic Auth
+curl -u ":$AZURE_DEVOPS_PAT" "https://dev.azure.com/{org}/{project}/_apis/git/pullrequests/{pr_id}?api-version=7.0"
+```
+
+**Alternative method using curl with Bearer token:**
+
+```bash
+# Azure DevOps API call using PAT
+curl -H "Authorization: Basic $(echo -n ":$AZURE_DEVOPS_PAT" | base64)" \
+  "https://dev.azure.com/{org}/{project}/_apis/git/pullrequests/{pr_id}?api-version=7.0"
+```
+
+### Step 4: Verify Access
+
+Test that the credentials work by fetching the PR:
+
+```bash
+# For GitHub
+gh pr view {pr_number} --repo {owner/repo}
+
+# For Azure DevOps (using curl with PAT)
+curl -s -u ":$AZURE_DEVOPS_PAT" \
+  "https://dev.azure.com/{org}/{project}/_apis/git/pullrequests/{pr_id}?api-version=7.0"
+```
+
+### Step 5: Handle Missing or Invalid Credentials
+
+**ONLY if `.plan.flow.env` credentials are missing or empty**, inform the user:
+
+```
+⚠️ Credentials not found in .plan.flow.env
+
+Please add your credentials to .plan.flow.env:
+
+For GitHub:
+  GITHUB_TOKEN=ghp_your_token_here
+
+For Azure DevOps:
+  AZURE_DEVOPS_PAT=your_pat_here
+
+See .example.plan.flow.env for the template.
+```
+
+**If authentication fails:**
+
+```
+⚠️ Authentication failed
+
+Please verify your credentials in .plan.flow.env are valid.
+
+For GitHub:
+  - Check your GITHUB_TOKEN is valid
+  - Create a new token at: https://github.com/settings/tokens
+
+For Azure DevOps:
+  - Check your AZURE_DEVOPS_PAT is valid
+  - Create a new token at: https://dev.azure.com/{org}/_usersSettings/tokens
+```
+
+## Authentication Methods
+
+### GitHub Authentication
+
+#### Method 1: GitHub CLI (gh) - Recommended
+
+```bash
+# Authenticate using token from .plan.flow.env
+echo "$GITHUB_TOKEN" | gh auth login --with-token
+
+# Verify access
+gh auth status
+
+# Use gh commands
+gh pr view {pr_number} --repo {owner/repo}
+gh api repos/{owner}/{repo}/pulls/{pr_number}
+```
+
+#### Method 2: Direct API Calls with curl
+
+```bash
+curl -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github.v3+json" \
+  "https://api.github.com/repos/{owner}/{repo}/pulls/{pr_number}"
+```
+
+### Azure DevOps Authentication
+
+#### Method 1: Azure DevOps CLI (az)
+
+```bash
+# Set PAT for Azure DevOps CLI
+export AZURE_DEVOPS_EXT_PAT="$AZURE_DEVOPS_PAT"
+
+# Use az commands
+az repos pr show --id {pr_id} --organization {org} --project {project}
+```
+
+#### Method 2: Direct API Calls with curl (Basic Auth)
+
+```bash
+# Using Basic Auth with PAT
+curl -u ":$AZURE_DEVOPS_PAT" \
+  "https://dev.azure.com/{org}/{project}/_apis/git/pullrequests/{pr_id}?api-version=7.0"
+```
+
+#### Method 3: Direct API Calls with curl (Bearer Token)
+
+```bash
+# Using Bearer token
+curl -H "Authorization: Basic $(echo -n ":$AZURE_DEVOPS_PAT" | base64)" \
+  -H "Content-Type: application/json" \
+  "https://dev.azure.com/{org}/{project}/_apis/git/pullrequests/{pr_id}?api-version=7.0"
+```
+
+## Allowed Commands
+
+### GitHub Commands
+
+| Allowed Action               | Purpose                                      |
+| ---------------------------- | -------------------------------------------- |
+| `gh auth status`             | Check authentication status                  |
+| `gh auth login --with-token` | Authenticate using PAT from `.plan.flow.env` |
+| `gh pr view`                 | Read PR information                          |
+| `gh pr diff`                 | Read PR diff/changes                         |
+| `gh pr files`                | List files changed in PR                     |
+| `gh api` (GET requests only) | Fetch additional PR data                     |
+
+### Azure DevOps Commands
+
+| Allowed Action                                        | Purpose                                 |
+| ----------------------------------------------------- | --------------------------------------- |
+| `az devops configure`                                 | Configure Azure DevOps defaults         |
+| `az devops invoke --area git --resource pullRequests` | Fetch PR details                        |
+| `az devops invoke --area git --resource blobs`        | Fetch file contents                     |
+| `az devops invoke --area git --resource diffs`        | Fetch PR diff                           |
+| `az devops invoke --area git --resource commits`      | Fetch commit information                |
+| `az repos pr show`                                    | Show PR details                         |
+| `az repos pr list`                                    | List PRs (for finding existing reviews) |
+| `curl` with GET + PAT auth                            | Direct API calls to Azure DevOps        |
+
+## Security Notes
+
+- **NEVER** commit `.plan.flow.env` to version control
+- **NEVER** use browser authentication or interactive login (`gh auth login`) in automated contexts
+- **ALWAYS** use PAT from `.plan.flow.env` for programmatic access
+- **ALWAYS** try `.plan.flow.env` credentials FIRST before any other method
+- Tokens should have minimal required scopes for the operation
+
+## Required Scopes
+
+### GitHub
+
+Common scopes needed:
+
+- `repo` - Full control of private repositories (for private repos)
+- `public_repo` - Access public repositories (for public repos)
+- `read:org` - Read org membership (if reviewing org repos)
+
+### Azure DevOps
+
+Common scopes needed:
+
+- `Code (read)` - Read code and pull requests
+- `Code (read & write)` - Read and write code (if needed)
+- `Pull Request Threads (read & write)` - Read and write PR comments (if needed)
+
+## Example Usage in Skills/Commands
+
+```markdown
+### Step 0: Authenticate for PR Access
+
+Use the PR authentication tool:
+
+1. Provide PR URL: `{pr_link}`
+2. Tool detects platform (GitHub or Azure DevOps)
+3. Tool loads credentials from `.plan.flow.env`
+4. Tool authenticates using appropriate method
+5. Tool verifies access by fetching PR
+
+After authentication, you can proceed to fetch PR information.
+```
+
+## Error Handling
+
+### Missing Credentials
+
+If credentials are not found in `.plan.flow.env`:
+
+```
+⚠️ Credentials not found in .plan.flow.env
+
+Please add your credentials to .plan.flow.env:
+
+For GitHub:
+  GITHUB_TOKEN=ghp_your_token_here
+
+For Azure DevOps:
+  AZURE_DEVOPS_PAT=your_pat_here
+
+See .example.plan.flow.env for the template.
+```
+
+### Invalid Credentials
+
+If authentication fails:
+
+```
+⚠️ Authentication failed
+
+Please verify your credentials in .plan.flow.env are valid.
+
+For GitHub:
+  - Check your GITHUB_TOKEN is valid
+  - Create a new token at: https://github.com/settings/tokens
+
+For Azure DevOps:
+  - Check your AZURE_DEVOPS_PAT is valid
+  - Create a new token at: https://dev.azure.com/{org}/_usersSettings/tokens
+```
+
+### Platform Detection Failure
+
+If the platform cannot be determined from the URL:
+
+```
+⚠️ Unable to determine platform from PR URL
+
+Please provide a valid PR URL from:
+- GitHub: https://github.com/{owner}/{repo}/pull/{number}
+- Azure DevOps: https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{id}
+```
+
+## Output
+
+After successful authentication, the tool provides:
+
+- **Platform**: Detected platform (GitHub or Azure DevOps)
+- **Authentication Status**: Confirmed authenticated
+- **Ready for PR Operations**: Can now fetch PR information, diffs, files, etc.
+
+## Related Files
+
+| File                            | Purpose                              |
+| ------------------------------- | ------------------------------------ |
+| `.plan.flow.env`                | Authentication tokens (gitignored)   |
+| `.example.plan.flow.env`        | Example env file template            |
+
+---
+
+## Examples
+
+For detailed error handling examples, see the Error Handling section above.
+
+### Correct Usage (GOOD)
+
+```bash
+# Always load credentials from .plan.flow.env first
+source .plan.flow.env
+
+# Then authenticate using the loaded token
+echo "$GITHUB_TOKEN" | gh auth login --with-token
+
+# Verify access before proceeding
+gh auth status
+```
+
+### Incorrect Usage (BAD - NEVER Do This)
+
+```bash
+# BAD - Using interactive login
+gh auth login  # Never use interactive login in automated contexts
+
+# BAD - Hardcoding tokens
+GITHUB_TOKEN="ghp_hardcoded_token"  # Never hardcode tokens
+
+# BAD - Skipping .plan.flow.env
+gh auth login --with-token <<< "ghp_token"  # Always use .plan.flow.env
+```

package/rules/tools/interactive-questions-tool.mdc

@@ -0,0 +1,337 @@
+---
+description: "Include when multiple-choice questions need to be asked via Plan mode's Questions UI"
+alwaysApply: false
+---
+
+# Interactive Questions Tool
+
+## Purpose
+
+Provides a standardized way to ask interactive questions using Plan mode's Questions UI. This tool automatically switches to Plan mode, presents questions via the Questions UI, waits for user responses, and switches back to Agent mode.
+
+## Usage
+
+This tool is used by:
+- Commands that need to gather information from users (e.g., `discovery-plan`, `create-plan`)
+- Skills that require user input before proceeding
+- Any process that needs interactive question-answer sessions
+
+**Example**: Used by the `discovery-plan` command to ask clarifying questions about requirements.
+
+---
+
+## How to Use Interactive Questions
+
+**⚠️ CRITICAL INSTRUCTION**: You must **ACTUALLY CALL** the tools using the tool calling mechanism. Do NOT write text describing what you would do. Do NOT say "Switching to Plan mode" or "I will switch". **ACTUALLY INVOKE** the `SwitchMode` and `AskQuestion` tools. If you cannot call the tools, use the fallback instructions provided.
+
+**MANDATORY WORKFLOW**:
+
+1. **IMMEDIATELY CALL** `SwitchMode` tool to enter Plan mode (auto-switch, no asking) - **ACTUALLY CALL THE TOOL, DO NOT DESCRIBE IT**
+2. **IMMEDIATELY CALL** `AskQuestion` tool for each question - **ACTUALLY CALL THE TOOL, DO NOT DESCRIBE IT**
+3. Wait for responses
+4. **IMMEDIATELY CALL** `SwitchMode` tool to return to Agent mode (auto-switch, no asking) - **ACTUALLY CALL THE TOOL, DO NOT DESCRIBE IT**
+
+**CRITICAL**: You must use the tool calling mechanism to invoke these tools. Do not write text describing what you would do. Actually make the tool calls.
+
+**DO NOT check if tools are available. DO NOT ask permission. DO NOT describe the action. Just call the tools directly.**
+
+---
+
+### Step 1: Automatically Switch to Plan Mode
+
+**MANDATORY - AUTO-SWITCH**: Before asking questions, **IMMEDIATELY CALL** the `SwitchMode` tool to switch to Plan mode. Do not describe switching. Do not say "Switching to Plan mode". **ACTUALLY CALL THE TOOL**. Do not ask the user if they want to switch - just call the tool:
+
+**YOU MUST ACTUALLY CALL THIS TOOL - DO NOT JUST DESCRIBE IT**:
+
+```
+SwitchMode(target_mode_id: "plan", explanation: "Discovery phase: Gathering requirements via interactive questions")
+```
+
+**CRITICAL**: You must use the tool calling mechanism to invoke `SwitchMode`. Do not write text saying you're switching. Actually make the tool call.
+
+**Parameters**:
+- `target_mode_id`: Always `"plan"` for Plan mode
+- `explanation`: Brief description of why switching (include context about what questions will be asked)
+
+**Example Usage**:
+
+```
+// For discovery questions
+SwitchMode(target_mode_id: "plan", explanation: "Discovery phase: Gathering requirements via interactive questions")
+
+// For contract creation questions
+SwitchMode(target_mode_id: "plan", explanation: "Contract creation: Asking clarifying questions about integration scope")
+```
+
+**Fallback (if SwitchMode tool not available)**:
+If the `SwitchMode` tool is not available or the tool call fails, provide clear instructions to the user:
+
+```markdown
+## Switching to Plan Mode
+
+**Action Required**: Please switch to Plan mode to proceed with questions.
+
+**Context**: [Context description]
+
+Once in Plan mode, I will present questions via the Questions UI.
+```
+
+**After switching to Plan mode (or providing instructions), proceed immediately to Step 2.**
+
+---
+
+### Step 2: Ask Questions Using AskQuestion Tool
+
+**MANDATORY**: After entering Plan mode, **IMMEDIATELY CALL** the `AskQuestion` tool for each question. Do NOT check if it's available. Do NOT use text format if the tool is available. **ACTUALLY CALL THE TOOL** - do not just describe asking questions. Just call the tool directly.
+
+**Question Topics**:
+- **Functional Requirements**: What the feature must do
+- **Non-Functional Requirements**: Performance, security, scalability
+- **Technical Questions**: Architecture, dependencies, patterns
+- **UI/UX Questions**: User experience, design considerations
+
+**Question Format**:
+
+```
+AskQuestion({
+  question: "What is the primary user action for this feature?",
+  options: [
+    "A. Create new items",
+    "B. View existing items",
+    "C. Edit existing items",
+    "D. Delete items",
+    "E. All of the above"
+  ],
+  explanation: "Understanding the core functionality helps scope the implementation"
+})
+```
+
+**Parameters**:
+- `question`: The question text (clear and specific)
+- `options`: Array of multiple-choice options (2-6 options recommended)
+- `explanation`: Optional context for why this question is being asked
+
+**Best Practices**:
+- Use 2-6 options per question
+- Make options mutually exclusive when possible
+- Use clear labels (A, B, C, etc.)
+- Keep questions focused on one topic
+- Provide context in the explanation
+
+**Important**:
+- Ask all questions in one Plan mode session
+- Wait for each response before asking the next question
+- Use 2-6 options per question
+- Label options with A, B, C, D, E, F
+
+**Fallback (if AskQuestion tool not available)**:
+If the `AskQuestion` tool is not available, use this text format:
+
+```markdown
+## Questions
+
+1. What is the primary user action for this feature?
+   A. Create new items
+   B. View existing items
+   C. Edit existing items
+   D. Delete items
+   E. All of the above
+
+2. Should this feature support real-time updates?
+   A. Yes, real-time updates required
+   B. No, periodic refresh is sufficient
+```
+
+**Wait for user responses before proceeding to the next question.**
+
+---
+
+### Step 3: Wait for All Responses
+
+**DO NOT** continue until the user has answered all questions via the Questions UI (or text responses if using fallback).
+
+**If user doesn't respond**:
+1. Wait a reasonable amount of time
+2. Gently remind about pending questions
+3. Offer to continue with assumptions (clearly marked)
+4. Only proceed if user explicitly agrees to assumptions
+
+---
+
+### Step 4: Process Responses
+
+After receiving all responses:
+
+1. **Extract the selected options** (A, B, C, etc.) from each question
+2. **Map them to corresponding answers** (e.g., "A" → "Create new items")
+3. **Document the answers** appropriately
+4. **Use the answers** to inform next steps
+
+---
+
+### Step 5: Automatically Switch Back to Agent Mode
+
+**MANDATORY - AUTO-SWITCH**: After all questions are answered, **IMMEDIATELY CALL** the `SwitchMode` tool to switch back to Agent mode. Do not describe switching. Do not say "Switching back to Agent mode". **ACTUALLY CALL THE TOOL**. Do not ask the user if they want to switch - just call the tool:
+
+**YOU MUST ACTUALLY CALL THIS TOOL - DO NOT JUST DESCRIBE IT**:
+
+```
+SwitchMode(target_mode_id: "agent", explanation: "Discovery questions complete, returning to Agent mode")
+```
+
+**CRITICAL**: You must use the tool calling mechanism to invoke `SwitchMode`. Do not write text saying you're switching. Actually make the tool call.
+
+**Fallback (if SwitchMode tool not available)**:
+If the `SwitchMode` tool is not available or the tool call fails, provide clear instructions:
+
+```markdown
+## Returning to Agent Mode
+
+**Action Required**: Please switch back to Agent mode to continue.
+
+All questions have been answered. I will now proceed with the next steps.
+```
+
+---
+
+## Complete Workflow Example
+
+```markdown
+## Gathering Requirements via Interactive Questions
+
+**Step 1**: [SwitchMode tool called - actually invoked, not described]
+
+**Step 2**: [AskQuestion tool called for Question 1 - actually invoked]
+**Question 1**: What is the primary user action?
+- A. Create new items
+- B. View existing items
+- C. Edit existing items
+- D. Delete items
+
+[User selects: B]
+
+[AskQuestion tool called for Question 2 - actually invoked]
+**Question 2**: Should this feature support real-time updates?
+- A. Yes, real-time updates required
+- B. No, periodic refresh is sufficient
+
+[User selects: A]
+
+**Step 3**: All questions answered. [SwitchMode tool called to return to Agent mode - actually invoked]
+
+**Step 4**: Processing responses...
+- Primary action: View existing items
+- Real-time updates: Required
+
+**Step 5**: Continuing with next steps based on answers...
+```
+
+---
+
+## When to Use Interactive Questions
+
+### Use For:
+
+1. **Discovery Phase**: Gathering requirements and clarifying unknowns
+2. **Planning Phase**: Understanding scope, priorities, and constraints
+3. **Critical Decisions**: When user input is required before proceeding
+4. **Multiple Related Questions**: When you need to ask several questions in sequence
+5. **Complex Choices**: When options need to be clearly presented
+
+### Don't Use For:
+
+1. **Simple Yes/No Questions**: Use regular chat for these
+2. **Single Simple Questions**: Regular chat is faster
+3. **Information Already Available**: Don't ask if you can find the answer
+4. **Read-Only Operations**: No questions needed for reading/searching
+
+---
+
+## Question Format Guidelines
+
+### Good Question Format
+
+```
+AskQuestion({
+  question: "Where should the new button be placed?",
+  options: [
+    "A. Before 'Library' (per Figma order)",
+    "B. After 'Library'",
+    "C. In a separate toolbar",
+    "D. As a dropdown option"
+  ],
+  explanation: "Button placement affects user workflow and visual hierarchy"
+})
+```
+
+### Bad Question Format
+
+```
+// ❌ Too vague
+AskQuestion({
+  question: "What do you want?",
+  options: ["A. Yes", "B. No"]
+})
+
+// ❌ Too many options (hard to choose)
+AskQuestion({
+  question: "Choose an option",
+  options: ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"]
+})
+
+// ❌ No context
+AskQuestion({
+  question: "Option A or B?",
+  options: ["A", "B"]
+})
+```
+
+---
+
+## Error Handling
+
+### If SwitchMode Tool Fails
+
+If the `SwitchMode` tool is not available or fails:
+
+1. **Inform the user** that manual mode switch is required
+2. **Provide clear instructions** on how to switch
+3. **Wait for confirmation** before proceeding
+4. **Continue with the workflow** once in Plan mode
+
+### If AskQuestion Tool Not Available
+
+If the `AskQuestion` tool is not available:
+
+1. **Fall back to regular chat questions**
+2. **Present questions in a clear format**
+3. **Wait for text responses**
+4. **Process responses as usual**
+
+### If User Doesn't Respond
+
+If the user doesn't respond to questions:
+
+1. Wait a reasonable amount of time
+2. Gently remind about pending questions
+3. Offer to continue with assumptions (clearly marked)
+4. Only proceed if user explicitly agrees to assumptions
+
+---
+
+## Benefits of Interactive Questions
+
+1. **Better UX**: Visual multiple-choice options are easier to answer
+2. **Faster Responses**: Users can click instead of typing
+3. **Clearer Options**: Structured choices reduce ambiguity
+4. **Batch Processing**: Ask multiple questions in one session
+5. **Consistent Format**: Standardized question presentation
+6. **Reduced Errors**: Multiple-choice reduces typos and misunderstandings
+
+---
+
+## Related Tools
+
+- [Plan Mode Tool](.cursor/rules/tools/plan-mode-tool.mdc) - For switching to Plan mode
+- Discovery patterns: `.cursor/rules/patterns/discovery-patterns.mdc`
+- Discovery command: `.cursor/commands/discovery-plan.md`