claude-code-workflow 6.3.54 → 7.0.0

package/.codex/skills/issue-discover/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: issue-discover
+description: Unified issue discovery and creation. Create issues from GitHub/text, discover issues via multi-perspective analysis, or prompt-driven iterative exploration. Triggers on "issue:new", "issue:discover", "issue:discover-by-prompt", "create issue", "discover issues", "find issues".
+allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context, mcp__exa__search
+---
+
+# Issue Discover
+
+Unified issue discovery and creation skill covering three entry points: manual issue creation, perspective-based discovery, and prompt-driven exploration.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Issue Discover Orchestrator (SKILL.md)                          │
+│  → Action selection → Route to phase → Execute → Summary         │
+└───────────────┬─────────────────────────────────────────────────┘
+                │
+                ├─ ASK_USER: Select action
+                │
+    ┌───────────┼───────────┬───────────┐
+    ↓           ↓           ↓           │
+┌─────────┐ ┌─────────┐ ┌─────────┐   │
+│ Phase 1 │ │ Phase 2 │ │ Phase 3 │   │
+│  Create │ │Discover │ │Discover │   │
+│   New   │ │  Multi  │ │by Prompt│   │
+└─────────┘ └─────────┘ └─────────┘   │
+     ↓           ↓           ↓          │
+  Issue      Discoveries  Discoveries   │
+(registered)  (export)    (export)      │
+     │           │           │          │
+     │           ├───────────┤          │
+     │           ↓                      │
+     │     ┌───────────┐               │
+     │     │  Phase 4  │               │
+     │     │Quick Plan │               │
+     │     │& Execute  │               │
+     │     └─────┬─────┘               │
+     │           ↓                      │
+     │     .task/*.json                 │
+     │           ↓                      │
+     │     Direct Execution             │
+     │           │                      │
+     └───────────┴──────────────────────┘
+                  ↓ (fallback/remaining)
+          issue-resolve (plan/queue)
+                  ↓
+            /issue:execute
+```
+
+## Key Design Principles
+
+1. **Action-Driven Routing**: ASK_USER selects action, then load single phase
+2. **Progressive Phase Loading**: Only read the selected phase document
+3. **CLI-First Data Access**: All issue CRUD via `ccw issue` CLI commands
+4. **Auto Mode Support**: `-y` flag skips action selection with auto-detection
+5. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent
+6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS
+
+## Auto Mode
+
+When `--yes` or `-y`: Skip action selection, auto-detect action from input type.
+
+## Usage
+
+```
+issue-discover <input>
+issue-discover [FLAGS] "<input>"
+
+# Flags
+-y, --yes              Skip all confirmations (auto mode)
+--action <type>        Pre-select action: new|discover|discover-by-prompt
+
+# Phase-specific flags
+--priority <1-5>       Issue priority (new mode)
+--perspectives <list>  Comma-separated perspectives (discover mode)
+--external             Enable Exa research (discover mode)
+--scope <pattern>      File scope (discover/discover-by-prompt mode)
+--depth <level>        standard|deep (discover-by-prompt mode)
+--max-iterations <n>   Max exploration iterations (discover-by-prompt mode)
+
+# Examples
+issue-discover https://github.com/org/repo/issues/42                              # Create from GitHub
+issue-discover "Login fails with special chars"                                    # Create from text
+issue-discover --action discover src/auth/**                                       # Multi-perspective discovery
+issue-discover --action discover src/api/** --perspectives=security,bug            # Focused discovery
+issue-discover --action discover-by-prompt "Check API contracts"                   # Prompt-driven discovery
+issue-discover -y "auth broken"                                                    # Auto mode create
+```
+
+## Execution Flow
+
+```
+Input Parsing:
+   └─ Parse flags (--action, -y, --perspectives, etc.) and positional args
+
+Action Selection:
+   ├─ --action flag provided → Route directly
+   ├─ Auto-detect from input:
+   │   ├─ GitHub URL or #number → Create New (Phase 1)
+   │   ├─ Path pattern (src/**, *.ts) → Discover (Phase 2)
+   │   ├─ Short text (< 80 chars) → Create New (Phase 1)
+   │   └─ Long descriptive text (≥ 80 chars) → Discover by Prompt (Phase 3)
+   └─ Otherwise → ASK_USER to select action
+
+Phase Execution (load one phase):
+   ├─ Phase 1: Create New          → phases/01-issue-new.md
+   ├─ Phase 2: Discover            → phases/02-discover.md
+   └─ Phase 3: Discover by Prompt  → phases/03-discover-by-prompt.md
+
+Post-Phase:
+   └─ Summary + Next steps recommendation
+```
+
+### Phase Reference Documents
+
+| Phase | Document | Load When | Purpose |
+|-------|----------|-----------|---------|
+| Phase 1 | [phases/01-issue-new.md](phases/01-issue-new.md) | Action = Create New | Create issue from GitHub URL or text description |
+| Phase 2 | [phases/02-discover.md](phases/02-discover.md) | Action = Discover | Multi-perspective issue discovery (bug, security, test, etc.) |
+| Phase 3 | [phases/03-discover-by-prompt.md](phases/03-discover-by-prompt.md) | Action = Discover by Prompt | Prompt-driven iterative exploration with Gemini planning |
+| Phase 4 | [phases/04-quick-execute.md](phases/04-quick-execute.md) | Post-Phase = Quick Plan & Execute | Convert high-confidence findings to tasks and execute directly |
+
+## Core Rules
+
+1. **Action Selection First**: Always determine action before loading any phase
+2. **Single Phase Load**: Only read the selected phase document, never load all phases
+3. **CLI Data Access**: Use `ccw issue` CLI for all issue operations, NEVER read files directly
+4. **Content Preservation**: Each phase contains complete execution logic from original commands
+5. **Auto-Detect Input**: Smart input parsing reduces need for explicit --action flag
+6. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After completing each phase, immediately proceed to next
+7. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
+8. **Explicit Lifecycle**: Always close_agent after wait completes to free resources
+
+## Input Processing
+
+### Auto-Detection Logic
+
+```javascript
+function detectAction(input, flags) {
+  // 1. Explicit --action flag
+  if (flags.action) return flags.action;
+
+  const trimmed = input.trim();
+
+  // 2. GitHub URL → new
+  if (trimmed.match(/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/) || trimmed.match(/^#\d+$/)) {
+    return 'new';
+  }
+
+  // 3. Path pattern (contains **, /, or --perspectives) → discover
+  if (trimmed.match(/\*\*/) || trimmed.match(/^src\//) || flags.perspectives) {
+    return 'discover';
+  }
+
+  // 4. Short text (< 80 chars, no special patterns) → new
+  if (trimmed.length > 0 && trimmed.length < 80 && !trimmed.includes('--')) {
+    return 'new';
+  }
+
+  // 5. Long descriptive text → discover-by-prompt
+  if (trimmed.length >= 80) {
+    return 'discover-by-prompt';
+  }
+
+  // Cannot auto-detect → ask user
+  return null;
+}
+```
+
+### Action Selection (ASK_USER)
+
+```javascript
+// When action cannot be auto-detected
+const answer = ASK_USER([{
+  id: "action",
+  type: "select",
+  prompt: "What would you like to do?",
+  options: [
+    {
+      label: "Create New Issue (Recommended)",
+      description: "Create issue from GitHub URL, text description, or structured input"
+    },
+    {
+      label: "Discover Issues",
+      description: "Multi-perspective discovery: bug, security, test, quality, performance, etc."
+    },
+    {
+      label: "Discover by Prompt",
+      description: "Describe what to find — Gemini plans the exploration strategy iteratively"
+    }
+  ]
+}]);  // BLOCKS (wait for user response)
+
+// Route based on selection
+const actionMap = {
+  "Create New Issue": "new",
+  "Discover Issues": "discover",
+  "Discover by Prompt": "discover-by-prompt"
+};
+```
+
+## Data Flow
+
+```
+User Input (URL / text / path pattern / descriptive prompt)
+    ↓
+[Parse Flags + Auto-Detect Action]
+    ↓
+[Action Selection] ← ASK_USER (if needed)
+    ↓
+[Read Selected Phase Document]
+    ↓
+[Execute Phase Logic]
+    ↓
+[Summary + Next Steps]
+    ├─ After Create → Suggest issue-resolve (plan solution)
+    └─ After Discover → Suggest export to issues, then issue-resolve
+```
+
+## Subagent API Reference
+
+### spawn_agent
+
+Create a new subagent with task assignment.
+
+```javascript
+const agentId = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
+2. Execute: ccw spec load --category exploration
+
+## TASK CONTEXT
+${taskContext}
+
+## DELIVERABLES
+${deliverables}
+`
+})
+```
+
+### wait
+
+Get results from subagent (only way to retrieve results).
+
+```javascript
+const result = wait({
+  ids: [agentId],
+  timeout_ms: 600000  // 10 minutes
+})
+
+if (result.timed_out) {
+  // Handle timeout - can continue waiting or send_input to prompt completion
+}
+
+// Check completion status
+if (result.status[agentId].completed) {
+  const output = result.status[agentId].completed;
+}
+```
+
+### send_input
+
+Continue interaction with active subagent (for clarification or follow-up).
+
+```javascript
+send_input({
+  id: agentId,
+  message: `
+## CLARIFICATION ANSWERS
+${answers}
+
+## NEXT STEP
+Continue with plan generation.
+`
+})
+```
+
+### close_agent
+
+Clean up subagent resources (irreversible).
+
+```javascript
+close_agent({ id: agentId })
+```
+
+## Core Guidelines
+
+**Data Access Principle**: Issues files can grow very large. To avoid context overflow:
+
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` |
+| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
+| Create issue | `echo '...' \| ccw issue create` | Direct file write |
+| Update status | `ccw issue update <id> --status ...` | Direct file edit |
+
+**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` directly.
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| No action detected | Show ASK_USER with all 3 options |
+| Invalid action type | Show available actions, re-prompt |
+| Phase execution fails | Report error, suggest manual intervention |
+| No files matched (discover) | Check target pattern, verify path exists |
+| Gemini planning failed (discover-by-prompt) | Retry with qwen fallback |
+| Agent lifecycle errors | Ensure close_agent in error paths to prevent resource leaks |
+
+## Post-Phase Next Steps
+
+After successful phase execution, recommend next action:
+
+```javascript
+// After Create New (issue created)
+ASK_USER([{
+  id: "next_after_create",
+  type: "select",
+  prompt: "Issue created. What next?",
+  options: [
+    { label: "Plan Solution", description: "Generate solution via issue-resolve" },
+    { label: "Create Another", description: "Create more issues" },
+    { label: "View Issues", description: "Review all issues" },
+    { label: "Done", description: "Exit workflow" }
+  ]
+}]);  // BLOCKS (wait for user response)
+
+// After Discover / Discover by Prompt (discoveries generated)
+ASK_USER([{
+  id: "next_after_discover",
+  type: "select",
+  prompt: `Discovery complete: ${findings.length} findings, ${executableFindings.length} executable. What next?`,
+  options: [
+    { label: "Quick Plan & Execute (Recommended)", description: `Fix ${executableFindings.length} high-confidence findings directly` },
+    { label: "Export to Issues", description: "Convert discoveries to issues" },
+    { label: "Plan Solutions", description: "Plan solutions for exported issues via issue-resolve" },
+    { label: "Done", description: "Exit workflow" }
+  ]
+}]);  // BLOCKS (wait for user response)
+// If "Quick Plan & Execute" → Read phases/04-quick-execute.md, execute
+```
+
+## Related Skills & Commands
+
+- `issue-resolve` - Plan solutions, convert artifacts, form queues, from brainstorm
+- `issue-manage` - Interactive issue CRUD operations
+- `/issue:execute` - Execute queue with DAG-based parallel orchestration
+- `ccw issue list` - List all issues
+- `ccw issue status <id>` - View issue details

package/.codex/skills/issue-discover/phases/01-issue-new.md

@@ -0,0 +1,334 @@
+# Phase 1: Create New Issue
+
+> 来源: `commands/issue/new.md`
+
+## Overview
+
+Create structured issue from GitHub URL or text description with clarity-based flow control.
+
+**Core workflow**: Input Analysis → Clarity Detection → Data Extraction → Optional Clarification → GitHub Publishing → Create Issue
+
+**Input sources**:
+- **GitHub URL** - `https://github.com/owner/repo/issues/123` or `#123`
+- **Structured text** - Text with expected/actual/affects keywords
+- **Vague text** - Short description that needs clarification
+
+**Output**:
+- **Issue** (GH-xxx or ISS-YYYYMMDD-HHMMSS) - Registered issue ready for planning
+
+## Prerequisites
+
+- `gh` CLI available (for GitHub URLs)
+- `ccw issue` CLI available
+
+## Auto Mode
+
+When `--yes` or `-y`: Skip clarification questions, create issue with inferred details.
+
+## Arguments
+
+| Argument | Required | Type | Default | Description |
+|----------|----------|------|---------|-------------|
+| input | Yes | String | - | GitHub URL, `#number`, or text description |
+| --priority | No | Integer | auto | Priority 1-5 (auto-inferred if omitted) |
+| -y, --yes | No | Flag | false | Skip all confirmations |
+
+## Issue Structure
+
+```typescript
+interface Issue {
+  id: string;                    // GH-123 or ISS-YYYYMMDD-HHMMSS
+  title: string;
+  status: 'registered' | 'planned' | 'queued' | 'in_progress' | 'completed' | 'failed';
+  priority: number;              // 1 (critical) to 5 (low)
+  context: string;               // Problem description (single source of truth)
+  source: 'github' | 'text' | 'discovery';
+  source_url?: string;
+  labels?: string[];
+
+  // GitHub binding (for non-GitHub sources that publish to GitHub)
+  github_url?: string;
+  github_number?: number;
+
+  // Optional structured fields
+  expected_behavior?: string;
+  actual_behavior?: string;
+  affected_components?: string[];
+
+  // Feedback history
+  feedback?: {
+    type: 'failure' | 'clarification' | 'rejection';
+    stage: string;
+    content: string;
+    created_at: string;
+  }[];
+
+  bound_solution_id: string | null;
+  created_at: string;
+  updated_at: string;
+}
+```
+
+## Execution Steps
+
+### Step 1.1: Input Analysis & Clarity Detection
+
+```javascript
+const input = userInput.trim();
+const flags = parseFlags(userInput);
+
+// Detect input type and clarity
+const isGitHubUrl = input.match(/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/);
+const isGitHubShort = input.match(/^#(\d+)$/);
+const hasStructure = input.match(/(expected|actual|affects|steps):/i);
+
+// Clarity score: 0-3
+let clarityScore = 0;
+if (isGitHubUrl || isGitHubShort) clarityScore = 3;  // GitHub = fully clear
+else if (hasStructure) clarityScore = 2;             // Structured text = clear
+else if (input.length > 50) clarityScore = 1;        // Long text = somewhat clear
+else clarityScore = 0;                               // Vague
+
+let issueData = {};
+```
+
+### Step 1.2: Data Extraction (GitHub or Text)
+
+```javascript
+if (isGitHubUrl || isGitHubShort) {
+  // GitHub - fetch via gh CLI
+  const result = Bash(`gh issue view ${extractIssueRef(input)} --json number,title,body,labels,url`);
+  const gh = JSON.parse(result);
+  issueData = {
+    id: `GH-${gh.number}`,
+    title: gh.title,
+    source: 'github',
+    source_url: gh.url,
+    labels: gh.labels.map(l => l.name),
+    context: gh.body?.substring(0, 500) || gh.title,
+    ...parseMarkdownBody(gh.body)
+  };
+} else {
+  // Text description
+  issueData = {
+    id: `ISS-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`,
+    source: 'text',
+    ...parseTextDescription(input)
+  };
+}
+```
+
+### Step 1.3: Lightweight Context Hint (Conditional)
+
+```javascript
+// ACE search ONLY for medium clarity (1-2) AND missing components
+// Skip for: GitHub (has context), vague (needs clarification first)
+if (clarityScore >= 1 && clarityScore <= 2 && !issueData.affected_components?.length) {
+  const keywords = extractKeywords(issueData.context);
+
+  if (keywords.length >= 2) {
+    try {
+      const aceResult = mcp__ace-tool__search_context({
+        project_root_path: process.cwd(),
+        query: keywords.slice(0, 3).join(' ')
+      });
+      issueData.affected_components = aceResult.files?.slice(0, 3) || [];
+    } catch {
+      // ACE failure is non-blocking
+    }
+  }
+}
+```
+
+### Step 1.4: Conditional Clarification (Only if Unclear)
+
+```javascript
+// ONLY ask questions if clarity is low
+if (clarityScore < 2 && (!issueData.context || issueData.context.length < 20)) {
+  const answer = ASK_USER([{
+    id: "clarify",
+    type: "input",
+    prompt: "Please describe the issue in more detail:",
+    description: "Describe what, where, and expected behavior"
+  }]);  // BLOCKS (wait for user response)
+
+  if (answer.customText) {
+    issueData.context = answer.customText;
+    issueData.title = answer.customText.split(/[.\n]/)[0].substring(0, 60);
+    issueData.feedback = [{
+      type: 'clarification',
+      stage: 'new',
+      content: answer.customText,
+      created_at: new Date().toISOString()
+    }];
+  }
+}
+```
+
+### Step 1.5: GitHub Publishing Decision (Non-GitHub Sources)
+
+```javascript
+// For non-GitHub sources, ask if user wants to publish to GitHub
+let publishToGitHub = false;
+
+if (issueData.source !== 'github') {
+  // Yes → Create issue on GitHub and link it
+  // No  → Store as local issue without GitHub sync
+  publishToGitHub = CONFIRM("Would you like to publish this issue to GitHub?");  // BLOCKS (wait for user response)
+}
+```
+
+### Step 1.6: Create Issue
+
+**Issue Creation** (via CLI endpoint):
+```bash
+# Option 1: Pipe input (recommended for complex JSON)
+echo '{"title":"...", "context":"...", "priority":3}' | ccw issue create
+
+# Option 2: Heredoc (for multi-line JSON)
+ccw issue create << 'EOF'
+{"title":"...", "context":"含\"引号\"的内容", "priority":3}
+EOF
+```
+
+**GitHub Publishing** (if user opted in):
+```javascript
+// Step 1: Create local issue FIRST
+const localIssue = createLocalIssue(issueData);  // ccw issue create
+
+// Step 2: Publish to GitHub if requested
+if (publishToGitHub) {
+  const ghResult = Bash(`gh issue create --title "${issueData.title}" --body "${issueData.context}"`);
+  const ghUrl = ghResult.match(/https:\/\/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/)?.[0];
+  const ghNumber = parseInt(ghUrl?.match(/\/issues\/(\d+)/)?.[1]);
+
+  if (ghNumber) {
+    Bash(`ccw issue update ${localIssue.id} --github-url "${ghUrl}" --github-number ${ghNumber}`);
+  }
+}
+```
+
+**Workflow:**
+```
+1. Create local issue (ISS-YYYYMMDD-NNN) → stored in {projectRoot}/.workflow/issues.jsonl
+2. If publishToGitHub:
+   a. gh issue create → returns GitHub URL
+   b. Update local issue with github_url + github_number binding
+3. Both local and GitHub issues exist, linked together
+```
+
+## Execution Flow
+
+```
+Phase 1: Input Analysis
+   └─ Detect clarity score (GitHub URL? Structured text? Keywords?)
+
+Phase 2: Data Extraction (branched by clarity)
+   ┌────────────┬─────────────────┬──────────────┐
+   │  Score 3   │   Score 1-2     │   Score 0    │
+   │  GitHub    │   Text + ACE    │   Vague      │
+   ├────────────┼─────────────────┼──────────────┤
+   │  gh CLI    │  Parse struct   │  ASK_USER    │
+   │  → parse   │  + quick hint   │ (1 question) │
+   │            │  (3 files max)  │  → feedback  │
+   └────────────┴─────────────────┴──────────────┘
+
+Phase 3: GitHub Publishing Decision (non-GitHub only)
+   ├─ Source = github: Skip (already from GitHub)
+   └─ Source ≠ github: CONFIRM
+      ├─ Yes → publishToGitHub = true
+      └─ No  → publishToGitHub = false
+
+Phase 4: Create Issue
+   ├─ Score ≥ 2: Direct creation
+   └─ Score < 2: Confirm first → Create
+   └─ If publishToGitHub: gh issue create → link URL
+
+Note: Deep exploration & lifecycle deferred to /issue:plan
+```
+
+## Helper Functions
+
+```javascript
+function extractKeywords(text) {
+  const stopWords = new Set(['the', 'a', 'an', 'is', 'are', 'was', 'were', 'not', 'with']);
+  return text
+    .toLowerCase()
+    .split(/\W+/)
+    .filter(w => w.length > 3 && !stopWords.has(w))
+    .slice(0, 5);
+}
+
+function parseTextDescription(text) {
+  const result = { title: '', context: '' };
+  const sentences = text.split(/\.(?=\s|$)/);
+
+  result.title = sentences[0]?.trim().substring(0, 60) || 'Untitled';
+  result.context = text.substring(0, 500);
+
+  const expected = text.match(/expected:?\s*([^.]+)/i);
+  const actual = text.match(/actual:?\s*([^.]+)/i);
+  const affects = text.match(/affects?:?\s*([^.]+)/i);
+
+  if (expected) result.expected_behavior = expected[1].trim();
+  if (actual) result.actual_behavior = actual[1].trim();
+  if (affects) {
+    result.affected_components = affects[1].split(/[,\s]+/).filter(c => c.includes('/') || c.includes('.'));
+  }
+
+  return result;
+}
+
+function parseMarkdownBody(body) {
+  if (!body) return {};
+  const result = {};
+
+  const problem = body.match(/##?\s*(problem|description)[:\s]*([\s\S]*?)(?=##|$)/i);
+  const expected = body.match(/##?\s*expected[:\s]*([\s\S]*?)(?=##|$)/i);
+  const actual = body.match(/##?\s*actual[:\s]*([\s\S]*?)(?=##|$)/i);
+
+  if (problem) result.context = problem[2].trim().substring(0, 500);
+  if (expected) result.expected_behavior = expected[2].trim();
+  if (actual) result.actual_behavior = actual[2].trim();
+
+  return result;
+}
+```
+
+## Error Handling
+
+| Error | Message | Resolution |
+|-------|---------|------------|
+| GitHub fetch failed | gh CLI error | Check gh auth, verify URL |
+| Clarity too low | Input unclear | Ask clarification question |
+| Issue creation failed | CLI error | Verify ccw issue endpoint |
+| GitHub publish failed | gh issue create error | Create local-only, skip GitHub |
+
+## Examples
+
+### Clear Input (No Questions)
+
+```bash
+issue-discover https://github.com/org/repo/issues/42
+# → Fetches, parses, creates immediately
+
+issue-discover "Login fails with special chars. Expected: success. Actual: 500"
+# → Parses structure, creates immediately
+```
+
+### Vague Input (1 Question)
+
+```bash
+issue-discover "auth broken"
+# → Asks: "Please describe the issue in more detail"
+# → User provides details → saved to feedback[]
+# → Creates issue
+```
+
+## Post-Phase Update
+
+After issue creation:
+- Issue created with `status: registered`
+- Report: issue ID, title, source, affected components
+- Show GitHub URL (if published)
+- Recommend next step: `/issue:plan <id>` or `issue-resolve <id>`