Initial commit

2025-11-30 08:46:00 +08:00
commit 2109c2330b
22 changed files with 9156 additions and 0 deletions
--- a/commands/create.md
+++ b/commands/create.md
@@ -0,0 +1,579 @@
+---
+description: Create Jira issues (story, epic, feature, task, bug, feature-request) with proper formatting
+argument-hint: <type> [project-key] <summary> [--component <name>] [--version <version>] [--parent <key>]
+---
+
+## Name
+jira:create
+
+## Synopsis
+```
+/jira:create <type> [project-key] <summary> [options]
+```
+
+## Description
+The `jira:create` command creates Jira issues following best practices and team-specific conventions. It supports creating stories, epics, features, tasks, bugs, and feature requests with intelligent defaults, interactive prompts, and validation.
+
+This command is particularly useful for:
+- Creating well-formed user stories with acceptance criteria
+- Organizing epics and features with proper hierarchy
+- Submitting bugs with complete reproduction steps
+- Capturing customer-driven feature requests with business justification
+- Maintaining consistency across team Jira practices
+
+## Key Features
+
+- **Multi-Type Support** - Create stories, epics, features, tasks, bugs, or feature requests from a single command
+- **Smart Defaults** - Automatically applies project-specific conventions (e.g., CNTRLPLANE, OCPBUGS, RFE)
+- **Interactive Guidance** - Prompts for missing information with helpful templates
+- **Context Detection** - Analyzes summary text to suggest components (ARO, ROSA, HyperShift)
+- **Security Validation** - Scans for credentials and secrets before submission
+- **Template Support** - Provides user story templates, bug report templates, feature request workflows, acceptance criteria formats
+
+## Implementation
+
+The `jira:create` command runs in multiple phases:
+
+### 🎯 Phase 1: Load Implementation Guidance
+
+Invoke the appropriate skill based on issue type using the Skill tool:
+
+- **Type: `story`** → Invoke `jira:create-story` skill
+  - Loads user story template guidance
+  - Provides acceptance criteria formats
+  - Offers story quality validation
+
+- **Type: `epic`** → Invoke `jira:create-epic` skill
+  - Loads epic structure guidance
+  - Provides epic name field handling
+  - Offers parent feature linking workflow
+
+- **Type: `feature`** → Invoke `jira:create-feature` skill
+  - Loads strategic planning guidance
+  - Provides market problem framework
+  - Offers success criteria templates
+
+- **Type: `task`** → Invoke `jira:create-task` skill
+  - Loads technical task guidance
+  - Provides task vs story differentiation
+  - Offers acceptance criteria for technical work
+
+- **Type: `bug`** → Invoke `jira:create-bug` skill
+  - Loads bug report template
+  - Provides structured reproduction steps
+  - Offers severity and reproducibility guidance
+
+- **Type: `feature-request`** → Invoke `jira:create-feature-request` skill
+  - Loads customer-driven feature request guidance
+  - Provides 4-question workflow (title, description, business requirements, components)
+  - Offers component mapping from teams/operators
+  - Targets RFE project
+
+### 🏢 Phase 2: Apply Project-Specific Conventions
+
+Invoke project-specific and team-specific skills using the Skill tool as needed:
+
+**Project-specific skills:**
+- **CNTRLPLANE:** Invoke `cntrlplane` skill for CNTRLPLANE stories/epics/features/tasks
+- **OCPBUGS:** Invoke `ocpbugs` skill for OCPBUGS bugs
+- **Other projects:** Use only type-specific skills for best practices
+
+**Team-specific skills:**
+- Detected based on keywords in summary/description or component
+- Apply team-specific conventions (component selection, custom fields, workflows)
+- Layer on top of project-specific conventions
+- Example: HyperShift team → invoke `hypershift` skill
+
+**General projects** use only the type-specific skills (create-story, create-bug, etc.) for best practices.
+
+### 📝 Phase 3: Parse Arguments & Detect Context
+
+Parse command arguments:
+- **Required:** `type`, `summary`
+- **Optional:** `project_key` (may have project-specific defaults)
+- **Optional flags:** `--component`, `--version`, `--parent`
+
+Analyze summary text for context clues:
+- Extract keywords that may indicate team, component, or platform
+- Pass context to project-specific and team-specific skills for interpretation
+- Skills handle keyword detection and component/field suggestions
+
+### ⚙️ Phase 4: Apply Smart Defaults
+
+**Universal requirements (MUST be applied to ALL tickets):**
+- **Security level:** Red Hat Employee (required)
+- **Labels:** ai-generated-jira (required)
+
+**Project defaults:**
+- May include default project for certain issue types
+- Version defaults (if applicable)
+- Additional labels (for tracking or automation)
+
+**Team defaults:**
+- Component selection (based on keywords or prompts)
+- Custom field values
+- Workflow-specific requirements
+
+**General projects:**
+- Use type-specific skills for issue structure
+- Prompt for required fields as needed
+
+### 💬 Phase 5: Interactive Prompts (Hybrid Approach)
+
+Prompt for missing required information based on issue type:
+
+**For Stories:**
+- Offer user story template: "As a... I want... So that..."
+- Collect acceptance criteria (suggest formats)
+- Confirm auto-detected component
+
+**For Epics:**
+- Collect epic objective and scope
+- Collect epic acceptance criteria
+- Collect timeline/target release
+- Set epic name field (same as summary)
+- Optional parent feature link (via `--parent` or prompt)
+
+**For Features:**
+- Collect market problem description
+- Collect strategic value and business impact
+- Collect success criteria (adoption, usage, outcomes, business)
+- Identify component epics (3-8 major work streams)
+- Collect timeline and milestones
+
+**For Tasks:**
+- Collect task description (what needs to be done)
+- Collect motivation/context (why it's needed)
+- Optionally collect acceptance criteria
+- Optionally collect technical details (files, approach)
+
+**For Bugs:**
+- Use bug template (interactive fill-in):
+  - Description of problem
+  - Version-Release number
+  - How reproducible (Always | Sometimes | Rarely)
+  - Steps to Reproduce (numbered list)
+  - Actual results (include error messages)
+  - Expected results (correct behavior)
+  - Additional info (logs, screenshots)
+
+**For Feature Requests:**
+- Use 4-question workflow:
+  1. Proposed title of feature request
+  2. Nature and description (current limitations, desired behavior, use case)
+  3. Business requirements (customer impact, regulatory drivers, justification)
+  4. Affected packages and components (teams, operators, component mapping)
+
+### ✅ Phase 5.5: Summary Validation
+
+Before security validation, validate the summary format to catch common mistakes:
+
+**Check for anti-patterns:**
+1. Summary starts with "As a" (user story format belongs in description)
+2. Summary contains "I want" or "so that" (belongs in description)
+3. Summary exceeds 100 characters (likely too long, may be full user story)
+
+**Action if anti-pattern detected:**
+1. Detect that user put full user story in summary field
+2. Extract the key action/feature from the summary
+3. Generate a concise alternative (5-10 words)
+4. Prompt user for confirmation:
+   ```
+   The summary looks like a full user story. Summaries should be concise titles.
+
+   Current: "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying"
+
+   Suggested: "Enable ImageTagMirrorSet configuration in HostedCluster CRs"
+
+   Use the suggested summary? (yes/no/edit)
+   ```
+
+5. If user says yes, use suggested summary
+6. If user says edit, prompt for their preferred summary
+7. If user says no, use their original summary (but warn it may be truncated in Jira)
+
+**Note:** This validation should happen BEFORE creating the issue, to avoid having to update the summary afterward.
+
+### 🔒 Phase 6: Security Validation
+
+Scan all content (summary, description, comments) for sensitive data:
+
+**Prohibited content:**
+- Credentials (usernames/passwords, API tokens)
+- Cloud keys (AWS access keys, GCP service accounts, Azure credentials)
+- Kubeconfigs (cluster credentials, service account tokens)
+- SSH keys (private keys, authorized_keys)
+- Certificates (PEM files, private keys)
+- URLs with embedded credentials (e.g., `https://user:pass@example.com`)
+
+**Action if detected:**
+- STOP issue creation immediately
+- Inform user what type of data was detected (without exposing it)
+- Ask user to redact sensitive information
+- Provide guidance on safe alternatives (placeholder values)
+
+### ✅ Phase 7: Create Issue via MCP
+
+Use the `mcp__atlassian__jira_create_issue` MCP tool with collected parameters.
+
+**Build additional_fields:**
+
+**Required fields (MUST be included):**
+- `security`: `{"name": "Red Hat Employee"}`
+- `labels`: `["ai-generated-jira"]` (may be combined with additional labels)
+
+**Project-specific and team-specific fields:**
+- Custom field mappings
+- Version fields
+- Additional labels
+- Parent links
+- Component names
+- Any other project/team-specific requirements
+
+The MCP tool parameters come from the combined guidance of type-specific, project-specific, and team-specific skills, with universal requirements always applied.
+
+**Note:** Project-specific skills (e.g., CNTRLPLANE) may implement fallback strategies for handling creation failures (such as epic linking). Refer to the project-specific skill documentation for these strategies.
+
+### 📤 Phase 8: Return Result
+
+Display to user:
+- **Issue Key** (e.g., PROJECT-1234)
+- **Issue URL** (direct link to created issue)
+- **Summary of applied defaults** (any fields auto-populated by skills)
+
+**Example output:**
+```
+Created: PROJECT-1234
+Title: <issue summary>
+URL: <issue URL>
+
+Applied defaults:
+- <Field>: <Value>
+- <Field>: <Value>
+(varies by project/team)
+```
+
+## Usage Examples
+
+1. **Create a story with minimal info**:
+   ```
+   /jira:create story MYPROJECT "Add user dashboard"
+   ```
+   → Prompts for user story format, acceptance criteria, and any required fields
+
+2. **Create a story with options**:
+   ```
+   /jira:create story MYPROJECT "Add search functionality" --component "Frontend" --version "2.5.0"
+   ```
+   → Uses provided component and version, prompts only for description and AC
+
+3. **Create an epic with parent feature**:
+   ```
+   /jira:create epic MYPROJECT "Mobile application redesign" --parent MYPROJECT-100
+   ```
+   → Links epic to parent feature, prompts for epic details
+
+4. **Create a bug**:
+   ```
+   /jira:create bug MYPROJECT "Login button doesn't work on mobile"
+   ```
+   → Prompts for bug template fields (description, steps, actual/expected results)
+
+5. **Create a bug with component**:
+   ```
+   /jira:create bug MYPROJECT "API returns 500 error" --component "Backend"
+   ```
+   → Uses specified component, prompts for bug details
+
+6. **Create a task under a story**:
+   ```
+   /jira:create task MYPROJECT "Update API documentation" --parent MYPROJECT-456
+   ```
+   → Links task to parent story, prompts for task description
+
+7. **Create a feature**:
+   ```
+   /jira:create feature MYPROJECT "Advanced search capabilities"
+   ```
+   → Prompts for market problem, strategic value, success criteria, epic breakdown
+
+8. **Create a feature request**:
+   ```
+   /jira:create feature-request RFE "Support custom SSL certificates for ROSA HCP"
+   ```
+   → Prompts for nature/description, business requirements, affected components (4-question workflow)
+
+9. **Create with project-specific conventions** (examples vary by project):
+   ```
+   /jira:create story SPECIALPROJECT "New capability"
+   ```
+   → Applies SPECIALPROJECT-specific skills and conventions automatically
+
+## Arguments
+
+- **$1 – type** *(required)*
+  Issue type to create.
+  **Options:** `story` | `epic` | `feature` | `task` | `bug` | `feature-request`
+
+- **$2 – project-key** *(optional for bugs and feature-requests)*
+  JIRA project key (e.g., `CNTRLPLANE`, `OCPBUGS`, `RFE`, `MYPROJECT`).
+  **Default for bugs:** `OCPBUGS`
+  **Default for feature-requests:** `RFE`
+  **Required for:** stories, epics, features, tasks
+
+- **$3 – summary** *(required)*
+  Issue title/summary text.
+  Use quotes for multi-word summaries: `"Enable automatic scaling"`
+
+- **--component** *(optional)*
+  Component name (e.g., `"HyperShift / ROSA"`, `"Networking"`, `"API"`).
+  Auto-detected from summary context if not provided (for CNTRLPLANE/OCPBUGS).
+
+- **--version** *(optional)*
+  Target version (e.g., `"4.21"`, `"4.22"`, `"2.5.0"`).
+  **Default varies by project:**
+  - CNTRLPLANE/OCPBUGS: `openshift-4.21`
+  - Other projects: Prompt or use project default
+
+- **--parent** *(optional)*
+  Parent issue key for linking (e.g., `CNTRLPLANE-123`).
+  **Valid for:**
+  - Epics: Link to parent Feature
+  - Tasks: Link to parent Story or Epic
+  - Stories: Link to parent Epic (less common)
+
+## Return Value
+
+- **Issue Key**: The created Jira issue identifier (e.g., `CNTRLPLANE-1234`)
+- **Issue URL**: Direct link to the created issue
+- **Summary**: Confirmation of applied defaults and field values
+
+## Configuration
+
+### Project-Specific Skills
+
+The command automatically detects and applies project-specific conventions:
+
+- **CNTRLPLANE:** Uses `cntrlplane` skill for CNTRLPLANE stories/epics/features/tasks
+- **OCPBUGS:** Uses `ocpbugs` skill for OCPBUGS bugs
+- **Other projects:** Uses general best practices from type-specific skills
+
+To add conventions for your project, create a skill at:
+```
+plugins/jira/skills/your-project-name/SKILL.md
+```
+
+Then update the command implementation to invoke your skill when the project is detected.
+
+### Environment Variables
+
+The command respects MCP Jira server configuration:
+- **JIRA_PROJECTS_FILTER:** Filter which projects are accessible
+- **JIRA_SERVER_URL:** Jira instance URL
+- **JIRA_AUTH:** Authentication credentials
+
+## Error Handling
+
+### Invalid Issue Type
+
+**Scenario:** User specifies invalid type.
+
+**Action:**
+```
+Invalid issue type "stroy". Valid types: story, epic, feature, task, bug
+
+Did you mean "story"?
+```
+
+### Missing Project Key
+
+**Scenario:** Project key required but not provided.
+
+**Action:**
+```
+Project key is required for stories/tasks/epics/features.
+
+Usage: /jira:create story PROJECT-KEY "summary"
+
+Example: /jira:create story CNTRLPLANE "Enable autoscaling"
+```
+
+### Component Required But Not Provided
+
+**Scenario:** Project requires component, cannot auto-detect, user didn't specify.
+
+**Action:**
+```
+Component is required for CNTRLPLANE issues. Which component?
+1. HyperShift / ARO - for ARO HCP (Azure) issues
+2. HyperShift / ROSA - for ROSA HCP (AWS) issues
+3. HyperShift - for platform-agnostic issues
+
+Select a component (1-3):
+```
+
+### Parent Issue Not Found
+
+**Scenario:** User specifies `--parent` but issue doesn't exist.
+
+**Action:**
+```
+Parent issue CNTRLPLANE-999 not found.
+
+Options:
+1. Proceed without parent link
+2. Specify different parent
+3. Cancel creation
+
+What would you like to do?
+```
+
+### Security Validation Failure
+
+**Scenario:** Credentials or secrets detected.
+
+**Action:**
+```
+I detected what appears to be an API token in the description.
+
+Please review and redact before proceeding. Use placeholder values like:
+- YOUR_API_KEY
+- <redacted>
+- ********
+
+Would you like to edit the description?
+```
+
+### MCP Tool Error
+
+**Scenario:** MCP tool returns an error.
+
+**Action:**
+1. Parse error message
+2. Translate to user-friendly explanation
+3. Suggest corrective action
+4. Offer to retry
+
+**Common errors:**
+- **"Field 'component' is required"** → Prompt for component
+- **"Version not found"** → Fetch available versions, suggest closest match
+- **"Permission denied"** → User may lack permissions, suggest contacting admin
+- **"Issue type not available"** → Project may not support this issue type
+
+### Epic Link Creation Failure
+
+**Scenario:** Story/task creation fails when including epic link field.
+
+**Action:**
+Refer to project-specific skills for epic linking fallback strategies:
+- **CNTRLPLANE:** See CNTRLPLANE skill "Epic Linking Implementation Strategy" section
+- **Other projects:** Consult project-specific skill documentation
+
+**General pattern:**
+1. Detect error related to linking (error contains "epic", "parent", "link", or "customfield")
+2. Check project-specific skill for recommended fallback approach
+3. Typically: Create without link, then link via update
+4. Inform user of outcome
+5. **Last stand fallback:** If all strategies fail (including update-after-create), retry with absolute minimal fields:
+   - Remove ALL custom fields (epic link, target version, etc.)
+   - Keep only: project_key, summary, issue_type, description, assignee, components
+   - Log to console what was stripped out
+   - If this succeeds, inform user which fields need manual configuration in Jira
+
+### Field Format Error
+
+**Scenario:** Field provided in wrong format (e.g., Target Version as string instead of array).
+
+**Common field format errors:**
+
+1. **Target Version format**
+   - ❌ Wrong: `"customfield_12319940": "openshift-4.21"`
+   - ✅ Correct: `"customfield_12319940": [{"id": "12448830"}]`
+   - **Action:** Fetch version ID using `mcp__atlassian__jira_get_project_versions`, convert to correct format
+
+2. **Epic Link format**
+   - ❌ Wrong: `"parent": {"key": "EPIC-123"}` (for stories)
+   - ✅ Correct: `"customfield_12311140": "EPIC-123"` (string, not object)
+   - **Action:** Convert to correct format and retry
+
+3. **Component format**
+   - ❌ Wrong: `"components": "ComponentName"`
+   - ✅ Correct: `"components": ["ComponentName"]` (array) or just `"ComponentName"` (MCP accepts both)
+   - **Action:** Ensure consistent format
+
+**Detection:**
+- Parse error message for field names
+- Check skill documentation for correct format
+- Automatically convert and retry when possible
+
+## Best Practices
+
+1. **Use descriptive summaries:** Include relevant keywords for context and auto-detection
+2. **Provide flags when known:** Use `--component` and `--version` to skip prompts
+3. **Link related work:** Use `--parent` to maintain hierarchy
+4. **Review before submit:** Check the formatted content before confirming creation
+5. **Follow templates:** Use the provided templates for consistency
+6. **Sanitize content:** Remove credentials before including logs or screenshots
+
+## Anti-Patterns to Avoid
+
+❌ **Wrong issue type**
+```
+/jira:create story MYPROJECT "Refactor database layer"
+```
+✅ This is technical work, use `task` instead
+
+❌ **Vague summaries**
+```
+/jira:create bug "Something is broken"
+```
+✅ Be specific: "API server returns 500 error when creating namespaces"
+
+❌ **Missing context**
+```
+/jira:create epic MYPROJECT "Improve things"
+```
+✅ Be descriptive: "Mobile application redesign"
+
+❌ **Including credentials**
+```
+Steps to reproduce:
+1. Export API_KEY=sk_live_abc123xyz
+```
+✅ Use placeholders: "Export API_KEY=YOUR_API_KEY"
+
+## See Also
+
+- `jira:solve` - Analyze and solve Jira issues
+- `jira:grooming` - Generate grooming meeting agendas
+- `jira:status-rollup` - Create status rollup reports
+- `jira:generate-test-plan` - Generate test plans for PRs
+
+## Skills Reference
+
+The following skills are automatically invoked by this command:
+
+**Type-specific skills:**
+- **create-story** - User story creation guidance
+- **create-epic** - Epic creation and structure
+- **create-feature** - Feature planning and strategy
+- **create-task** - Technical task creation
+- **create-bug** - Bug report templates
+- **create-feature-request** - Customer-driven feature request workflow for RFE project
+
+**Project-specific skills:**
+- **cntrlplane** - CNTRLPLANE project conventions (stories, epics, features, tasks)
+- **ocpbugs** - OCPBUGS project conventions (bugs only)
+
+**Team-specific skills:**
+- **hypershift** - HyperShift team conventions (component selection for ARO/ROSA/HyperShift)
+
+To view skill details:
+```bash
+ls plugins/jira/skills/
+cat plugins/jira/skills/create-story/SKILL.md
+cat plugins/jira/skills/create-feature-request/SKILL.md
+cat plugins/jira/skills/cntrlplane/SKILL.md
+cat plugins/jira/skills/ocpbugs/SKILL.md
+cat plugins/jira/skills/hypershift/SKILL.md
+```