claude-code-workflow 6.3.37 → 6.3.39

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.

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

@@ -1,6 +1,6 @@
 ---
-description: Plan issue(s) into bound solutions (writes solutions JSONL via ccw issue bind)
-argument-hint: "<issue-id>[,<issue-id>,...] [--all-pending] [--batch-size 3]"
+description: Plan issue(s) into bound solutions using subagent pattern (explore + plan closed-loop)
+argument-hint: "<issue-id>[,<issue-id>,...] [--all-pending] [--batch-size 4]"
 ---
 
 # Issue Plan (Codex Version)
@@ -9,7 +9,7 @@ argument-hint: "<issue-id>[,<issue-id>,...] [--all-pending] [--batch-size 3]"
 
 Create executable solution(s) for issue(s) and bind the selected solution to each issue using `ccw issue bind`.
 
-This workflow is **planning + registration** (no implementation): it explores the codebase just enough to produce a high-quality task breakdown that can be executed later (e.g., by `issue-execute.md`).
+This workflow uses **subagent pattern** for parallel batch processing: spawn planning agents per batch, wait for results, handle multi-solution selection.
 
 ## Core Guidelines
 
@@ -17,29 +17,25 @@ This workflow is **planning + registration** (no implementation): it explores th
 
 | 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')` |
+| List issues (brief) | `ccw issue list --status pending --brief` | Read issues.jsonl |
+| Read issue details | `ccw issue status <id> --json` | Read issues.jsonl |
 | Update status | `ccw issue update <id> --status ...` | Direct file edit |
 | Bind solution | `ccw issue bind <id> <sol-id>` | Direct file edit |
 
-**Output Options**:
-- `--brief`: JSON with minimal fields (id, title, status, priority, tags)
-- `--json`: Full JSON (for detailed processing)
-
 **ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly.
 
 ## Inputs
 
 - **Explicit issues**: comma-separated IDs, e.g. `ISS-123,ISS-124`
 - **All pending**: `--all-pending` → plan all issues in `registered` status
-- **Batch size**: `--batch-size N` (default `3`) → max issues per batch
+- **Batch size**: `--batch-size N` (default `4`) → max issues per subagent batch
 
 ## Output Requirements
 
 For each issue:
-- Register at least one solution and bind one solution to the issue (updates `.workflow/issues/issues.jsonl` and appends to `.workflow/issues/solutions/{issue-id}.jsonl`).
-- Ensure tasks conform to `.claude/workflows/cli-templates/schemas/solution-schema.json`.
-- Each task includes quantified `acceptance.criteria` and concrete `acceptance.verification`.
+- Register at least one solution and bind one solution to the issue
+- Ensure tasks conform to `~/.claude/workflows/cli-templates/schemas/solution-schema.json`
+- Each task includes quantified `acceptance.criteria` and concrete `acceptance.verification`
 
 Return a final summary JSON:
 ```json
@@ -52,73 +48,166 @@ Return a final summary JSON:
 
 ## Workflow
 
-### Step 1: Resolve issue list
+### Step 1: Resolve Issue List
 
-- If `--all-pending`:
-  - Run `ccw issue list --status registered --json` and plan all returned issues.
-- Else:
-  - Parse IDs from user input (split by `,`), and ensure each issue exists:
-    - `ccw issue init <issue-id> --title "Issue <issue-id>"` (safe if already exists)
+**If `--all-pending`:**
+```bash
+ccw issue list --status registered --json
+```
 
-### Step 2: Load issue details
+**Else (explicit IDs):**
+```bash
+# For each ID, ensure exists
+ccw issue init <issue-id> --title "Issue <issue-id>" 2>/dev/null || true
+ccw issue status <issue-id> --json
+```
 
-For each issue ID:
-- `ccw issue status <issue-id> --json`
-- Extract the issue title/context/labels and any discovery hints (affected files, snippets, etc. if present).
+### Step 2: Group Issues by Similarity
 
-### Step 3: Minimal exploration (evidence-based)
+Group issues for batch processing (max 4 per batch):
 
-- If issue context names specific files or symbols: open them first.
-- Otherwise:
-  - Use `rg` to locate relevant code paths by keywords from the title/context.
-  - Read 3+ similar patterns before proposing refactors or API changes.
+```bash
+# Extract issue metadata for grouping
+ccw issue list --status registered --brief --json
+```
 
-### Step 4: Draft solutions and tasks (schema-driven)
+Group by:
+- Shared tags
+- Similar keywords in title
+- Related components
 
-Default to **one** solution per issue unless there are genuinely different approaches.
+### Step 3: Spawn Planning Subagents (Parallel)
 
-Task rules (from schema):
-- `id`: `T1`, `T2`, ...
-- `action`: one of `Create|Update|Implement|Refactor|Add|Delete|Configure|Test|Fix`
-- `implementation`: step-by-step, executable instructions
-- `test.commands`: include at least one command per task when feasible
-- `acceptance.criteria`: testable statements
-- `acceptance.verification`: concrete steps/commands mapping to criteria
-- Prefer small, independently testable tasks; encode dependencies in `depends_on`.
+For each batch, spawn a planning subagent:
 
-### Step 5: Register & bind solutions via CLI
+```javascript
+// Subagent message structure
+spawn_agent({
+  message: `
+## TASK ASSIGNMENT
 
-**Create solution** (via CLI endpoint):
-```bash
-ccw issue solution <issue-id> --data '{"description":"...", "approach":"...", "tasks":[...]}'
-# Output: {"id":"SOL-{issue-id}-1", ...}
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+4. Read schema: ~/.claude/workflows/cli-templates/schemas/solution-schema.json
+
+---
+
+Goal: Plan solutions for ${batch.length} issues with executable task breakdown
+
+Scope:
+- CAN DO: Explore codebase, design solutions, create tasks
+- CANNOT DO: Execute solutions, modify production code
+- Directory: ${process.cwd()}
+
+Context:
+- Issues: ${batch.map(i => `${i.id}: ${i.title}`).join('\n')}
+- Fetch full details: ccw issue status <id> --json
+
+Deliverables:
+- For each issue: Write solution to .workflow/issues/solutions/{issue-id}.jsonl
+- Single solution → auto-bind via ccw issue bind
+- Multiple solutions → return in pending_selection
+
+Quality bar:
+- Tasks have quantified acceptance.criteria
+- Each task includes test.commands
+- Solution follows schema exactly
+`
+})
 ```
 
-**CLI Features:**
-| Feature | Description |
-|---------|-------------|
-| Auto-increment ID | `SOL-{issue-id}-{seq}` (e.g., `SOL-GH-123-1`) |
-| Multi-solution | Appends to existing JSONL, supports multiple per issue |
-| Trailing newline | Proper JSONL format, no corruption |
+**Batch execution (parallel):**
+```javascript
+// Launch all batches in parallel
+const agentIds = batches.map(batch => spawn_agent({ message: buildPrompt(batch) }))
+
+// Wait for all agents to complete
+const results = wait({ ids: agentIds, timeout_ms: 900000 })  // 15 min
+
+// Collect results
+const allBound = []
+const allPendingSelection = []
+const allConflicts = []
+
+for (const id of agentIds) {
+  if (results.status[id].completed) {
+    const result = JSON.parse(results.status[id].completed)
+    allBound.push(...(result.bound || []))
+    allPendingSelection.push(...(result.pending_selection || []))
+    allConflicts.push(...(result.conflicts || []))
+  }
+}
+
+// Close all agents
+agentIds.forEach(id => close_agent({ id }))
+```
 
-**Binding:**
-- **Single solution**: Auto-bind: `ccw issue bind <issue-id> <solution-id>`
-- **Multiple solutions**: Present alternatives in `pending_selection`, wait for user choice
+### Step 4: Handle Multi-Solution Selection
 
-### Step 6: Detect cross-issue file conflicts (best-effort)
+If `pending_selection` is non-empty, present options:
 
-Across the issues planned in this run:
-- Build a set of touched files from each solution's `modification_points.file` (and/or task `scope` when explicit files are missing).
-- If the same file appears in multiple issues, add it to `conflicts` with all involved issue IDs.
-- Recommend a safe execution order (sequential) when conflicts exist.
+```
+Issue ISS-001 has multiple solutions:
+1. SOL-ISS-001-1: Refactor with adapter pattern (3 tasks)
+2. SOL-ISS-001-2: Direct implementation (2 tasks)
 
-### Step 7: Update issue status
+Select solution (1-2):
+```
 
-After binding, update issue status to `planned`:
+Bind selected solution:
+```bash
+ccw issue bind ISS-001 SOL-ISS-001-1
+```
+
+### Step 5: Handle Conflicts
+
+If conflicts detected:
+- Low/Medium severity: Auto-resolve with recommended order
+- High severity: Present to user for decision
+
+### Step 6: Update Issue Status
+
+After binding, update status:
 ```bash
 ccw issue update <issue-id> --status planned
 ```
 
+### Step 7: Output Summary
+
+```markdown
+## Planning Complete
+
+**Planned**: 5 issues
+**Bound Solutions**: 4
+**Pending Selection**: 1
+
+### Bound Solutions
+| Issue | Solution | Tasks |
+|-------|----------|-------|
+| ISS-001 | SOL-ISS-001-1 | 3 |
+| ISS-002 | SOL-ISS-002-1 | 2 |
+
+### Pending Selection
+- ISS-003: 2 solutions available (user selection required)
+
+### Conflicts Detected
+- src/auth.ts touched by ISS-001, ISS-002 (resolved: sequential)
+
+**Next Step**: `/issue:queue`
+```
+
+## Subagent Role Reference
+
+Planning subagent uses role file at: `~/.codex/agents/issue-plan-agent.md`
+
+Role capabilities:
+- Codebase exploration (rg, file reading)
+- Solution design with task breakdown
+- Schema validation
+- Solution registration via CLI
+
 ## Quality Checklist
 
 Before completing, verify:
@@ -130,19 +219,28 @@ Before completing, verify:
 - [ ] Task acceptance criteria are quantified (not vague)
 - [ ] Conflicts detected and reported (if multiple issues touch same files)
 - [ ] Issue status updated to `planned` after binding
+- [ ] All subagents closed after completion
 
 ## Error Handling
 
 | Error | Resolution |
 |-------|------------|
 | Issue not found | Auto-create via `ccw issue init` |
+| Subagent timeout | Retry with increased timeout or smaller batch |
 | No solutions generated | Display error, suggest manual planning |
 | User cancels selection | Skip issue, continue with others |
 | File conflicts | Detect and suggest resolution order |
 
-## Done Criteria
+## Start Execution
+
+Begin by resolving issue list:
 
-- A bound solution exists for each issue unless explicitly deferred for user selection.
-- All tasks validate against the solution schema fields (especially acceptance criteria + verification).
-- The final summary JSON matches the required shape.
+```bash
+# Default to all pending
+ccw issue list --status registered --brief --json
+
+# Or with explicit IDs
+ccw issue status ISS-001 --json
+```
 
+Then group issues and spawn planning subagents.