claude-code-workflow 6.3.37 → 6.3.38

package/.codex/prompts/issue-discover.md

@@ -0,0 +1,261 @@
+---
+description: Discover potential issues from multiple perspectives (bug, UX, test, quality, security, performance, maintainability, best-practices)
+argument-hint: "<path-pattern> [--perspectives=bug,ux,...] [--external]"
+---
+
+# Issue Discovery (Codex Version)
+
+## Goal
+
+Multi-perspective issue discovery that explores code from different angles to identify potential bugs, UX improvements, test gaps, and other actionable items. Unlike code review (which assesses existing code quality), discovery focuses on **finding opportunities for improvement and potential problems**.
+
+**Discovery Scope**: Specified modules/files only
+**Output Directory**: `.workflow/issues/discoveries/{discovery-id}/`
+**Available Perspectives**: bug, ux, test, quality, security, performance, maintainability, best-practices
+
+## Inputs
+
+- **Target Pattern**: File glob pattern (e.g., `src/auth/**`)
+- **Perspectives**: Comma-separated list via `--perspectives` (or interactive selection)
+- **External Research**: `--external` flag enables Exa research for security and best-practices
+
+## Output Requirements
+
+**Generate Files:**
+1. `.workflow/issues/discoveries/{discovery-id}/discovery-state.json` - Session state
+2. `.workflow/issues/discoveries/{discovery-id}/perspectives/{perspective}.json` - Per-perspective findings
+3. `.workflow/issues/discoveries/{discovery-id}/discovery-issues.jsonl` - Generated issue candidates
+4. `.workflow/issues/discoveries/{discovery-id}/summary.md` - Summary report
+
+**Return Summary:**
+```json
+{
+  "discovery_id": "DSC-YYYYMMDD-HHmmss",
+  "target_pattern": "src/auth/**",
+  "perspectives_analyzed": ["bug", "security", "test"],
+  "total_findings": 15,
+  "issues_generated": 8,
+  "priority_distribution": { "critical": 1, "high": 3, "medium": 4 }
+}
+```
+
+## Workflow
+
+### Step 1: Initialize Discovery Session
+
+```bash
+# Generate discovery ID
+DISCOVERY_ID="DSC-$(date -u +%Y%m%d-%H%M%S)"
+OUTPUT_DIR=".workflow/issues/discoveries/${DISCOVERY_ID}"
+
+# Create directory structure
+mkdir -p "${OUTPUT_DIR}/perspectives"
+```
+
+Resolve target files:
+```bash
+# List files matching pattern
+find <target-pattern> -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx"
+```
+
+If no files found, abort with error message.
+
+### Step 2: Select Perspectives
+
+**If `--perspectives` provided:**
+- Parse comma-separated list
+- Validate against available perspectives
+
+**If not provided (interactive):**
+- Present perspective groups:
+  - Quick scan: bug, test, quality
+  - Security audit: security, bug, quality
+  - Full analysis: all perspectives
+- Use first group as default or wait for user input
+
+### Step 3: Analyze Each Perspective
+
+For each selected perspective, explore target files and identify issues.
+
+**Perspective-Specific Focus:**
+
+| Perspective | Focus Areas | Priority Guide |
+|-------------|-------------|----------------|
+| **bug** | Null checks, edge cases, resource leaks, race conditions, boundary conditions, exception handling | Critical=data corruption/crash, High=malfunction, Medium=edge case |
+| **ux** | Error messages, loading states, feedback, accessibility, interaction patterns | Critical=inaccessible, High=confusing, Medium=inconsistent |
+| **test** | Missing unit tests, edge case coverage, integration gaps, assertion quality | Critical=no security tests, High=no core logic tests |
+| **quality** | Complexity, duplication, naming, documentation, code smells | Critical=unmaintainable, High=significant issues |
+| **security** | Input validation, auth/authz, injection, XSS/CSRF, data exposure | Critical=auth bypass/injection, High=missing authz |
+| **performance** | N+1 queries, memory leaks, caching, algorithm efficiency | Critical=memory leaks, High=N+1 queries |
+| **maintainability** | Coupling, interface design, tech debt, extensibility | Critical=forced changes, High=unclear boundaries |
+| **best-practices** | Framework conventions, language patterns, anti-patterns | Critical=bug-causing anti-patterns, High=convention violations |
+
+**For each perspective:**
+
+1. Read target files and analyze for perspective-specific concerns
+2. Use `rg` to search for patterns indicating issues
+3. Record findings with:
+   - `id`: Finding ID (e.g., `F-001`)
+   - `title`: Brief description
+   - `priority`: critical/high/medium/low
+   - `category`: Specific category within perspective
+   - `description`: Detailed explanation
+   - `file`: File path
+   - `line`: Line number
+   - `snippet`: Code snippet
+   - `suggested_issue`: Proposed issue text
+   - `confidence`: 0.0-1.0
+
+4. Write to `{OUTPUT_DIR}/perspectives/{perspective}.json`:
+```json
+{
+  "perspective": "security",
+  "analyzed_at": "2025-01-22T...",
+  "files_analyzed": 15,
+  "findings": [
+    {
+      "id": "F-001",
+      "title": "Missing input validation",
+      "priority": "high",
+      "category": "input-validation",
+      "description": "User input is passed directly to database query",
+      "file": "src/auth/login.ts",
+      "line": 42,
+      "snippet": "db.query(`SELECT * FROM users WHERE name = '${input}'`)",
+      "suggested_issue": "Add input sanitization to prevent SQL injection",
+      "confidence": 0.95
+    }
+  ]
+}
+```
+
+### Step 4: External Research (if --external)
+
+For security and best-practices perspectives, use Exa to search for:
+- Industry best practices for the tech stack
+- Known vulnerability patterns
+- Framework-specific security guidelines
+
+Write results to `{OUTPUT_DIR}/external-research.json`.
+
+### Step 5: Aggregate and Prioritize
+
+1. Load all perspective JSON files
+2. Deduplicate findings by file+line
+3. Calculate priority scores:
+   - critical: 1.0
+   - high: 0.8
+   - medium: 0.5
+   - low: 0.2
+   - Adjust by confidence
+
+4. Sort by priority score descending
+
+### Step 6: Generate Issues
+
+Convert high-priority findings to issue format:
+
+```bash
+# Append to discovery-issues.jsonl
+echo '{"id":"ISS-DSC-001","title":"...","priority":"high",...}' >> ${OUTPUT_DIR}/discovery-issues.jsonl
+```
+
+Issue criteria:
+- `priority` is critical or high
+- OR `priority_score >= 0.7`
+- OR `confidence >= 0.9` with medium priority
+
+### Step 7: Update Discovery State
+
+Write final state to `{OUTPUT_DIR}/discovery-state.json`:
+```json
+{
+  "discovery_id": "DSC-...",
+  "target_pattern": "src/auth/**",
+  "phase": "complete",
+  "created_at": "...",
+  "updated_at": "...",
+  "perspectives": ["bug", "security", "test"],
+  "results": {
+    "total_findings": 15,
+    "issues_generated": 8,
+    "priority_distribution": {
+      "critical": 1,
+      "high": 3,
+      "medium": 4
+    }
+  }
+}
+```
+
+### Step 8: Generate Summary
+
+Write summary to `{OUTPUT_DIR}/summary.md`:
+```markdown
+# Discovery Summary: DSC-...
+
+**Target**: src/auth/**
+**Perspectives**: bug, security, test
+**Total Findings**: 15
+**Issues Generated**: 8
+
+## Priority Breakdown
+- Critical: 1
+- High: 3
+- Medium: 4
+
+## Top Findings
+
+1. **[Critical] SQL Injection in login.ts:42**
+   Category: security/input-validation
+   ...
+
+2. **[High] Missing null check in auth.ts:128**
+   Category: bug/null-check
+   ...
+
+## Next Steps
+- Run `/issue:plan` to plan solutions for generated issues
+- Use `ccw view` to review findings in dashboard
+```
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] All target files analyzed for selected perspectives
+- [ ] Findings include file:line references
+- [ ] Priority assigned to all findings
+- [ ] Issues generated from high-priority findings
+- [ ] Discovery state shows `phase: complete`
+- [ ] Summary includes actionable next steps
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No files match pattern | Abort with clear error message |
+| Perspective analysis fails | Log error, continue with other perspectives |
+| No findings | Report "No issues found" (not an error) |
+| External research fails | Continue without external context |
+
+## Schema References
+
+| Schema | Path | Purpose |
+|--------|------|---------|
+| Discovery State | `~/.claude/workflows/cli-templates/schemas/discovery-state-schema.json` | Session state |
+| Discovery Finding | `~/.claude/workflows/cli-templates/schemas/discovery-finding-schema.json` | Finding format |
+
+## Start Discovery
+
+Begin by resolving target files:
+
+```bash
+# Parse target pattern from arguments
+TARGET_PATTERN="${1:-src/**}"
+
+# Count matching files
+find ${TARGET_PATTERN} -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) | wc -l
+```
+
+Then proceed with perspective selection and analysis.

package/.codex/prompts/issue-execute.md

@@ -9,6 +9,16 @@ argument-hint: "--queue <queue-id> [--worktree [<existing-path>]]"
 
 **Serial Execution**: Execute solutions ONE BY ONE from the issue queue via `ccw issue next`. For each solution, complete all tasks sequentially (implement → test → verify), then commit once per solution with formatted summary. Continue autonomously until queue is empty.
 
+## Project Context (MANDATORY FIRST STEPS)
+
+Before starting execution, load project context:
+
+1. **Read project tech stack**: `.workflow/project-tech.json`
+2. **Read project guidelines**: `.workflow/project-guidelines.json`
+3. **Read solution schema**: `~/.claude/workflows/cli-templates/schemas/solution-schema.json`
+
+This ensures execution follows project conventions and patterns.
+
 ## Queue ID Requirement (MANDATORY)
 
 **`--queue <queue-id>` parameter is REQUIRED**

package/.codex/prompts/issue-new.md

@@ -0,0 +1,285 @@
+---
+description: Create structured issue from GitHub URL or text description
+argument-hint: "<github-url | text-description> [--priority 1-5]"
+---
+
+# Issue New (Codex Version)
+
+## Goal
+
+Create a new issue from a GitHub URL or text description. Detect input clarity and ask clarifying questions only when necessary. Register the issue for planning.
+
+**Core Principle**: Requirement Clarity Detection → Ask only when needed
+
+```
+Clear Input (GitHub URL, structured text)  → Direct creation
+Unclear Input (vague description)          → Minimal clarifying questions
+```
+
+## 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
+  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[];
+  
+  // Solution binding
+  bound_solution_id: string | null;
+  
+  // Timestamps
+  created_at: string;
+  updated_at: string;
+}
+```
+
+## Inputs
+
+- **GitHub URL**: `https://github.com/owner/repo/issues/123` or `#123`
+- **Text description**: Natural language description
+- **Priority flag**: `--priority 1-5` (optional, default: 3)
+
+## Output Requirements
+
+**Create Issue via CLI** (preferred method):
+```bash
+# Pipe input (recommended for complex JSON)
+echo '{"title":"...", "context":"...", "priority":3}' | ccw issue create
+
+# Returns created issue JSON
+{"id":"ISS-20251229-001","title":"...","status":"registered",...}
+```
+
+**Return Summary:**
+```json
+{
+  "created": true,
+  "id": "ISS-20251229-001",
+  "title": "Login fails with special chars",
+  "source": "text",
+  "github_published": false,
+  "next_step": "/issue:plan ISS-20251229-001"
+}
+```
+
+## Workflow
+
+### Step 1: Analyze Input Clarity
+
+Parse and detect input type:
+
+```javascript
+// Detection patterns
+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
+```
+
+### Step 2: Extract Issue Data
+
+**For GitHub URL/Short:**
+
+```bash
+# Fetch issue details via gh CLI
+gh issue view <issue-ref> --json number,title,body,labels,url
+
+# Parse response
+{
+  "id": "GH-123",
+  "title": "...",
+  "source": "github",
+  "source_url": "https://github.com/...",
+  "labels": ["bug", "priority:high"],
+  "context": "..."
+}
+```
+
+**For Text Description:**
+
+```javascript
+// Generate issue ID
+const id = `ISS-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+
+// Parse structured fields if present
+const expected = text.match(/expected:?\s*([^.]+)/i);
+const actual = text.match(/actual:?\s*([^.]+)/i);
+const affects = text.match(/affects?:?\s*([^.]+)/i);
+
+// Build issue data
+{
+  "id": id,
+  "title": text.split(/[.\n]/)[0].substring(0, 60),
+  "source": "text",
+  "context": text.substring(0, 500),
+  "expected_behavior": expected?.[1]?.trim(),
+  "actual_behavior": actual?.[1]?.trim()
+}
+```
+
+### Step 3: Context Hint (Conditional)
+
+For medium clarity (score 1-2) without affected components:
+
+```bash
+# Use rg to find potentially related files
+rg -l "<keyword>" --type ts | head -5
+```
+
+Add discovered files to `affected_components` (max 3 files).
+
+**Note**: Skip this for GitHub issues (already have context) and vague inputs (needs clarification first).
+
+### Step 4: Clarification (Only if Unclear)
+
+**Only for clarity score < 2:**
+
+Present a prompt asking for more details:
+
+```
+Input unclear. Please describe:
+- What is the issue about?
+- Where does it occur?
+- What is the expected behavior?
+```
+
+Wait for user response, then update issue data.
+
+### Step 5: GitHub Publishing Decision
+
+For non-GitHub sources, determine if user wants to publish to GitHub:
+
+```
+Would you like to publish this issue to GitHub?
+1. Yes, publish to GitHub (create issue and link it)
+2. No, keep local only (store without GitHub sync)
+```
+
+### Step 6: Create Issue
+
+**Create via CLI:**
+
+```bash
+# Build issue JSON
+ISSUE_JSON='{"title":"...","context":"...","priority":3,"source":"text"}'
+
+# Create issue (auto-generates ID)
+echo "${ISSUE_JSON}" | ccw issue create
+```
+
+**If publishing to GitHub:**
+
+```bash
+# Create on GitHub first
+GH_URL=$(gh issue create --title "..." --body "..." | grep -oE 'https://github.com/[^ ]+')
+GH_NUMBER=$(echo $GH_URL | grep -oE '/issues/([0-9]+)$' | grep -oE '[0-9]+')
+
+# Update local issue with binding
+ccw issue update ${ISSUE_ID} --github-url "${GH_URL}" --github-number ${GH_NUMBER}
+```
+
+### Step 7: Output Result
+
+```markdown
+## Issue Created
+
+**ID**: ISS-20251229-001
+**Title**: Login fails with special chars
+**Source**: text
+**Priority**: 2 (High)
+
+**Context**:
+500 error when password contains quotes
+
+**Affected Components**:
+- src/auth/login.ts
+- src/utils/validation.ts
+
+**GitHub**: Not published (local only)
+
+**Next Step**: `/issue:plan ISS-20251229-001`
+```
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] Issue ID generated correctly (GH-xxx or ISS-YYYYMMDD-HHMMSS)
+- [ ] Title extracted (max 60 chars)
+- [ ] Context captured (problem description)
+- [ ] Priority assigned (1-5)
+- [ ] Status set to `registered`
+- [ ] Created via `ccw issue create` CLI command
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| GitHub URL not accessible | Report error, suggest text input |
+| gh CLI not available | Fall back to text-based creation |
+| Empty input | Prompt for description |
+| Very vague input | Ask clarifying questions |
+| Issue already exists | Report duplicate, show existing |
+
+## Examples
+
+### Clear Input (No Questions)
+
+```bash
+# GitHub URL
+codex -p "@.codex/prompts/issue-new.md https://github.com/org/repo/issues/42"
+# → Fetches, parses, creates immediately
+
+# Structured text
+codex -p "@.codex/prompts/issue-new.md 'Login fails with special chars. Expected: success. Actual: 500'"
+# → Parses structure, creates immediately
+```
+
+### Vague Input (Clarification)
+
+```bash
+codex -p "@.codex/prompts/issue-new.md 'auth broken'"
+# → Asks: "Please describe the issue in more detail"
+# → User provides details
+# → Creates issue
+```
+
+## Start Execution
+
+Parse input and detect clarity:
+
+```bash
+# Get input from arguments
+INPUT="${1}"
+
+# Detect if GitHub URL
+if echo "${INPUT}" | grep -qE 'github\.com/.*/issues/[0-9]+'; then
+  echo "GitHub URL detected - fetching issue..."
+  gh issue view "${INPUT}" --json number,title,body,labels,url
+else
+  echo "Text input detected - analyzing clarity..."
+  # Continue with text parsing
+fi
+```
+
+Then follow the workflow based on detected input type.