mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
feat: Add multi-perspective issue discovery and structured issue creation
- Implemented issue discovery prompt to analyze code from various perspectives (bug, UX, test, quality, security, performance, maintainability, best-practices). - Created structured issue generation prompt from GitHub URLs or text descriptions, including clarity detection and optional clarification questions. - Introduced CCW Loop-B hybrid orchestrator pattern for iterative development, featuring a coordinator and specialized workers with batch wait support. - Defined state management, session structure, and output schemas for the CCW Loop-B workflow. - Added error handling and best practices documentation for the new features.
This commit is contained in:
catlog22
@@ -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)
|
||||
|
||||
### Step 2: Load issue details
|
||||
|
||||
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 3: Minimal exploration (evidence-based)
|
||||
|
||||
- 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.
|
||||
|
||||
### Step 4: Draft solutions and tasks (schema-driven)
|
||||
|
||||
Default to **one** solution per issue unless there are genuinely different approaches.
|
||||
|
||||
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`.
|
||||
|
||||
### Step 5: Register & bind solutions via CLI
|
||||
|
||||
**Create solution** (via CLI endpoint):
|
||||
**If `--all-pending`:**
|
||||
```bash
|
||||
ccw issue solution <issue-id> --data '{"description":"...", "approach":"...", "tasks":[...]}'
|
||||
# Output: {"id":"SOL-{issue-id}-1", ...}
|
||||
ccw issue list --status registered --json
|
||||
```
|
||||
|
||||
**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 |
|
||||
**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
|
||||
```
|
||||
|
||||
**Binding:**
|
||||
- **Single solution**: Auto-bind: `ccw issue bind <issue-id> <solution-id>`
|
||||
- **Multiple solutions**: Present alternatives in `pending_selection`, wait for user choice
|
||||
### Step 2: Group Issues by Similarity
|
||||
|
||||
### Step 6: Detect cross-issue file conflicts (best-effort)
|
||||
Group issues for batch processing (max 4 per batch):
|
||||
|
||||
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.
|
||||
```bash
|
||||
# Extract issue metadata for grouping
|
||||
ccw issue list --status registered --brief --json
|
||||
```
|
||||
|
||||
### Step 7: Update issue status
|
||||
Group by:
|
||||
- Shared tags
|
||||
- Similar keywords in title
|
||||
- Related components
|
||||
|
||||
After binding, update issue status to `planned`:
|
||||
### Step 3: Spawn Planning Subagents (Parallel)
|
||||
|
||||
For each batch, spawn a planning subagent:
|
||||
|
||||
```javascript
|
||||
// Subagent message structure
|
||||
spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### 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
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**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 }))
|
||||
```
|
||||
|
||||
### Step 4: Handle Multi-Solution Selection
|
||||
|
||||
If `pending_selection` is non-empty, present options:
|
||||
|
||||
```
|
||||
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)
|
||||
|
||||
Select solution (1-2):
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
- 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.
|
||||
Begin by resolving issue list:
|
||||
|
||||
```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.
|
||||
|
||||
Reference in New Issue
Block a user