Initial commit

2025-11-29 18:24:24 +08:00
commit f4fe5ac0c3
74 changed files with 33758 additions and 0 deletions
--- a/commands/planning:create.md
+++ b/commands/planning:create.md
@@ -0,0 +1,391 @@
+---
+description: Create Linear issue and run full planning workflow in one step
+allowed-tools: [Bash, LinearMCP, AtlassianMCP, SlackMCP, PlaywrightMCP, Context7MCP]
+argument-hint: "<title>" <project> <jira-ticket-id>
+---
+
+# Creating & Planning: $1 for Project: $2
+
+You are **creating a new Linear issue** and running the **Planning Phase** in one step.
+
+## 🚨 CRITICAL: Safety Rules
+
+**READ FIRST**: ``$CCPM_COMMANDS_DIR/SAFETY_RULES.md``
+
+**NEVER** submit, post, or update anything to Jira, Confluence, BitBucket, or Slack without explicit user confirmation, even in bypass permission mode.
+
+- ✅ **READ-ONLY** operations are permitted (fetch, search, view)
+- ⛔ **WRITE operations** require user confirmation
+- ✅ **Linear** operations are permitted (our internal tracking)
+
+When in doubt, ASK before posting anything externally.
+
+## Project Configuration
+
+**IMPORTANT**: This command uses CCPM agents for efficient project detection and configuration loading.
+
+### Auto-Activate Skills
+
+```markdown
+Skill(project-detection): Auto-activates for project context
+Skill(project-operations): Provides workflow guidance
+```
+
+### Load Project Configuration with Agents
+
+Use project agents to detect and load configuration:
+
+```javascript
+// Step 1: Detect or get project from argument
+const projectArg = "$2"  // Optional project argument
+
+let projectContext
+
+if (projectArg && projectArg !== "") {
+  // User specified project, load it
+  projectContext = Task(project-context-manager): `
+  Get context for project: ${projectArg}
+  Format: standard
+  Include all sections: true
+  `
+} else {
+  // Auto-detect from current directory
+  projectContext = Task(project-context-manager): `
+  Get active project context
+  Format: standard
+  Include all sections: true
+  `
+}
+
+if (projectContext.error) {
+  console.error(`❌ ${projectContext.error.message}`)
+  projectContext.error.suggestions?.forEach(s => console.log(`  - ${s}`))
+  exit(1)
+}
+
+// Now we have all project configuration in structured format:
+const PROJECT_ID = projectContext.detected.project_id
+const PROJECT_NAME = projectContext.config.project_name
+const SUBPROJECT = projectContext.detected.subproject  // NEW: for monorepos
+
+const LINEAR_TEAM = projectContext.config.linear.team
+const LINEAR_PROJECT = projectContext.config.linear.project
+const LINEAR_DEFAULT_LABELS = projectContext.config.linear.default_labels
+
+const EXTERNAL_PM_ENABLED = projectContext.config.external_pm.enabled
+const EXTERNAL_PM_TYPE = projectContext.config.external_pm.type
+const JIRA_CONFIG = projectContext.config.external_pm.jira
+const CONFLUENCE_CONFIG = projectContext.config.external_pm.confluence
+
+const TECH_STACK = SUBPROJECT
+  ? projectContext.config.subproject?.tech_stack
+  : projectContext.config.tech_stack
+
+// Display context
+console.log(projectContext.display.title)  // e.g., "My Monorepo › frontend"
+```
+
+**Benefits of Agent-Based Approach**:
+- ~80% token reduction vs inline logic
+- Automatic subdirectory detection for monorepos
+- Consistent error handling
+- Structured, validated output
+- Tech stack awareness (overall or per-subproject)
+
+## Workflow
+
+### Step 1: Create Linear Issue
+
+**IMPORTANT**: Use shared Linear helpers for resilient state and label handling:
+
+```markdown
+READ: commands/_shared-linear-helpers.md
+```
+
+Use **Linear MCP** to create a new issue using loaded configuration:
+
+**Title**: $1
+**Team**: ${LINEAR_TEAM} (from config)
+**Project**: ${LINEAR_PROJECT} (from config)
+**Status**: Backlog
+**Labels**: ${LINEAR_DEFAULT_LABELS} + subproject label (if in monorepo)
+
+```javascript
+// Build labels array
+const labels = [...LINEAR_DEFAULT_LABELS]
+
+// Add subproject label for monorepo context
+if (SUBPROJECT) {
+  labels.push(SUBPROJECT)
+  console.log(`📁 Subproject context: ${SUBPROJECT}`)
+}
+
+// Ensure all labels exist before creating issue
+try {
+  const validLabels = await ensureLabelsExist(LINEAR_TEAM, labels, {
+    descriptions: {
+      'planning': 'Task is in planning phase',
+      'research': 'Research and discovery required',
+      'implementation': 'Task is being implemented',
+      'verification': 'Task is being verified'
+    }
+  })
+
+  // Get valid state ID for "Backlog"
+  const backlogStateId = await getValidStateId(LINEAR_TEAM, "Backlog")
+
+  // Create issue with validated state and labels
+  const issue = linear_create_issue({
+    title: "$1",
+    team: LINEAR_TEAM,
+    project: LINEAR_PROJECT,
+    stateId: backlogStateId,
+    labelIds: validLabels
+  })
+
+} catch (error) {
+  if (error.message.includes('Could not find state') || error.message.includes('Invalid state')) {
+    console.error(`❌ Linear State Error: ${error.message}`)
+    console.log(`💡 Tip: Run '/ccpm:utils:status' to see available states for your team`)
+    throw error
+  }
+  throw error
+}
+```
+
+**Initial Description**:
+
+```markdown
+## Task
+
+$1
+
+**Jira Reference**: $3 (if provided)
+
+---
+
+_Planning in progress..._
+```
+
+Save the created Linear issue ID.
+
+Display:
+
+```
+✅ Linear Issue Created!
+
+📋 Issue: [WORK-123]
+🔗 URL: https://linear.app/workspace/issue/[WORK-123]
+📝 Title: $1
+🏢 Project: $2
+
+⏳ Starting planning workflow...
+```
+
+### Step 2: Execute Shared Planning Workflow
+
+**READ**: `commands/_shared-planning-workflow.md`
+
+Execute the shared planning workflow to complete planning for the newly created issue.
+
+**Set required context variables:**
+- `LINEAR_ISSUE_ID` = [created issue ID from Step 1]
+- `JIRA_TICKET_ID` = $3 (optional Jira ticket ID)
+- `PROJECT_CONFIG` = [loaded in project configuration section]
+- `EXTERNAL_PM_ENABLED` = [from config]
+- `EXTERNAL_PM_TYPE` = [from config]
+- `JIRA_ENABLED`, `CONFLUENCE_ENABLED`, `SLACK_ENABLED` = [from config]
+
+**Execute these steps from the shared workflow:**
+
+1. **Step 0.5**: Detect and analyze images in the Linear issue
+   - Uses `commands/_shared-image-analysis.md` logic
+   - Finds UI mockups, diagrams, screenshots
+   - Analyzes and formats for Linear description
+
+2. **Step 0.6**: Detect and extract Figma designs
+   - Uses `commands/_shared-figma-detection.md` logic
+   - Identifies live Figma links
+   - Extracts design tokens and specifications
+   - Caches results in Linear comments
+
+3. **Step 1**: Gather external PM context (Jira, Confluence, Slack)
+   - Only if external PM is enabled
+   - Fetches Jira ticket details and linked issues
+   - Searches Confluence for related documentation
+   - Finds Slack thread discussions
+   - Checks BitBucket for related PRs
+
+4. **Step 2**: Analyze codebase
+   - Identifies relevant files to modify
+   - Maps patterns and conventions
+   - Determines dependencies
+
+5. **Step 2.5**: Invoke engineer agents for technical analysis
+   - Selects appropriate agents based on task type
+   - Backend tasks → `backend-architect`
+   - Frontend tasks → `frontend-developer`
+   - Mobile tasks → `mobile-developer`
+   - Full-stack → both backend and frontend in parallel
+   - Security-critical → add `security-auditor`
+
+6. **Step 3**: Update Linear description with comprehensive research
+   - Creates implementation checklist
+   - Inserts visual context (images + Figma designs)
+   - Adds research findings
+   - Includes agent analysis
+   - Links all external resources
+
+7. **Step 4**: Confirm completion
+   - Display status summary
+   - Show research added
+   - Provide Linear issue URL
+
+This ensures the new issue receives the same comprehensive planning as existing issues:
+- Image analysis
+- Figma design extraction
+- External PM research
+- Codebase analysis
+- Implementation checklist generation
+
+### Step 3: Show Status & Interactive Next Actions
+
+**READ**: ``$CCPM_COMMANDS_DIR/_shared-linear-helpers.md``
+
+Use **Linear MCP** to get current status.
+
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Create & Planning Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Linear Issue: [WORK-123]
+🔗 URL: https://linear.app/workspace/issue/[WORK-123]
+📝 Jira Reference: $3 (if provided)
+
+📊 Current Status: Planning
+🎯 Progress: 0 of [N] subtasks complete (0%)
+🏷️  Labels: planning, research-complete
+⏱️  Time in status: Just created
+📈 Complexity: [Low/Medium/High]
+
+📊 Research Summary:
+- Gathered context from [X] Jira tickets (if applicable)
+- Found [Y] relevant Confluence docs (if applicable)
+- Analyzed [Z] related Slack discussions (if applicable)
+- Identified [N] files to modify
+- Researched best practices from Context7
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 Suggested Next Actions
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use **AskUserQuestion** tool:
+
+```javascript
+{
+  questions: [{
+    question: "Planning complete! What would you like to do next?",
+    header: "Next Step",
+    multiSelect: false,
+    options: [
+      {
+        label: "Start Implementation",
+        description: "Begin working with agent coordination (/ccpm:implementation:start)"
+      },
+      {
+        label: "Get AI Insights",
+        description: "Get AI analysis of complexity, risks, and timeline (/ccpm:utils:insights)"
+      },
+      {
+        label: "Review Planning",
+        description: "Review the planning details in Linear (/ccpm:utils:status)"
+      },
+      {
+        label: "Auto-Assign Agents",
+        description: "Let AI assign subtasks to optimal agents (/ccpm:utils:auto-assign)"
+      }
+    ]
+  }]
+}
+```
+
+**Execute the chosen action**:
+
+- If "Start Implementation" → Run `/ccpm:implementation:start [WORK-123]`
+- If "Get AI Insights" → Run `/ccpm:utils:insights [WORK-123]`
+- If "Review Planning" → Run `/ccpm:utils:status [WORK-123]`
+- If "Auto-Assign Agents" → Run `/ccpm:utils:auto-assign [WORK-123]`
+- If "Other" → Show quick commands and exit gracefully
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📝 Quick Commands
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status:        /ccpm:utils:status [WORK-123]
+Start:         /ccpm:implementation:start [WORK-123]
+Insights:      /ccpm:utils:insights [WORK-123]
+Context:       /ccpm:utils:context [WORK-123]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 💡 Hint: Try the New Natural Command
+
+For a simpler workflow, consider using:
+
+```bash
+/ccpm:plan "task title" [project] [jira-ticket]
+```
+
+**Benefits:**
+- Same functionality, simpler syntax
+- Part of the 6-command natural workflow
+- Auto-detects project if configured
+- See: [Quick Start Guide](./README.md#quick-start)
+
+This command still works perfectly! The hint is just a suggestion.
+
+---
+
+## Notes
+
+### This Command Combines
+
+1. **Issue Creation** - No manual Linear UI needed
+2. **Full Planning** - All research in one go
+3. **Interactive Mode** - Suggests next actions
+4. **Continuous Flow** - Can chain to next command
+
+### Usage Patterns
+
+**With Jira:**
+
+```bash
+/ccpm:planning:create "Add JWT authentication" my-app PROJ-456
+```
+
+**Without Jira (Linear-only):**
+
+```bash
+/ccpm:planning:create "Add dark mode toggle" personal-project
+```
+
+**With Active Project:**
+
+```bash
+/ccpm:project:set my-app
+/ccpm:planning:create "Add JWT authentication"  # Uses active project
+```
+
+### Benefits
+
+- ✅ One command instead of two
+- ✅ No context switching to Linear UI
+- ✅ Immediate planning after creation
+- ✅ Interactive next steps
+- ✅ Fast workflow start