mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-30 20:21:09 +08:00
feat: initialize monorepo with package.json for CCW workflow platform
This commit is contained in:
catlog22
392
ccw/docs-site/docs/commands/issue/issue-convert-to-plan.md
Normal file
392
ccw/docs-site/docs/commands/issue/issue-convert-to-plan.md
Normal file
@@ -0,0 +1,392 @@
|
||||
---
|
||||
title: issue:convert-to-plan
|
||||
sidebar_label: issue:convert-to-plan
|
||||
sidebar_position: 7
|
||||
description: Convert planning artifacts to issue solutions
|
||||
---
|
||||
|
||||
# issue:convert-to-plan
|
||||
|
||||
Converts various planning artifact formats (lite-plan, workflow session, markdown, JSON) into issue workflow solutions with intelligent detection and automatic binding.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:convert-to-plan` command bridges external planning workflows with the issue system. It auto-detects source formats, extracts task structures, normalizes to solution schema, and either creates new issues or supplements existing solutions.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Multi-format support**: lite-plan, workflow sessions, markdown, JSON
|
||||
- **Auto-detection**: Identifies source type automatically
|
||||
- **AI-assisted extraction**: Gemini CLI for markdown parsing
|
||||
- **Supplement mode**: Add tasks to existing solutions
|
||||
- **Auto-binding**: Solutions automatically bound to issues
|
||||
- **Issue auto-creation**: Creates issues from plans when needed
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Convert lite-plan to new issue (auto-creates issue)
|
||||
/issue:convert-to-plan ".workflow/.lite-plan/implement-auth-2026-01-25"
|
||||
|
||||
# Convert workflow session to existing issue
|
||||
/issue:convert-to-plan WFS-auth-impl --issue GH-123
|
||||
|
||||
# Convert markdown file to issue
|
||||
/issue:convert-to-plan "./docs/implementation-plan.md"
|
||||
|
||||
# Supplement existing solution with additional tasks
|
||||
/issue:convert-to-plan "./docs/additional-tasks.md" --issue ISS-001 --supplement
|
||||
|
||||
# Auto mode - skip confirmations
|
||||
/issue:convert-to-plan ".workflow/.lite-plan/my-plan" -y
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `SOURCE` | Yes | Planning artifact path or WFS-xxx ID |
|
||||
| `--issue <id>` | No | Bind to existing issue instead of creating new |
|
||||
| `--supplement` | No | Add tasks to existing solution (requires --issue) |
|
||||
| `-y, --yes` | No | Skip all confirmations |
|
||||
|
||||
## Examples
|
||||
|
||||
### Convert Lite-Plan
|
||||
|
||||
```bash
|
||||
/issue:convert-to-plan ".workflow/.lite-plan/implement-auth"
|
||||
# Output:
|
||||
# Detected source type: lite-plan
|
||||
# Extracted: 5 tasks
|
||||
# Created issue: ISS-20250129-001 (priority: 3)
|
||||
# ✓ Created solution: SOL-ISS-20250129-001-a7b3
|
||||
# ✓ Bound solution to issue
|
||||
# → Status: planned
|
||||
```
|
||||
|
||||
### Convert Workflow Session
|
||||
|
||||
```bash
|
||||
/issue:convert-to-plan WFS-auth-impl --issue GH-123
|
||||
# Output:
|
||||
# Detected source type: workflow-session
|
||||
# Loading session: .workflow/active/WFS-auth-impl/
|
||||
# Extracted: 8 tasks from session
|
||||
# ✓ Created solution: SOL-GH-123-c9d2
|
||||
# ✓ Bound solution to issue GH-123
|
||||
```
|
||||
|
||||
### Convert Markdown with AI
|
||||
|
||||
```bash
|
||||
/issue:convert-to-plan "./docs/api-redesign.md"
|
||||
# Output:
|
||||
# Detected source type: markdown-file
|
||||
# Using Gemini CLI for intelligent extraction...
|
||||
# Extracted: 6 tasks
|
||||
# Created issue: ISS-20250129-002 (priority: 2)
|
||||
# ✓ Created solution: SOL-ISS-20250129-002-e4f1
|
||||
```
|
||||
|
||||
### Supplement Existing Solution
|
||||
|
||||
```bash
|
||||
/issue:convert-to-plan "./docs/tasks-phase2.md" --issue ISS-001 --supplement
|
||||
# Output:
|
||||
# Loaded existing solution: SOL-ISS-001-a7b3 (3 tasks)
|
||||
# Extracted: 2 new tasks
|
||||
# Supplementing: 3 existing + 2 new = 5 total tasks
|
||||
# ✓ Updated solution: SOL-ISS-001-a7b3
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Source Artifact] --> B{Detect Type}
|
||||
B -->|Lite-Plan| C1[plan.json]
|
||||
B -->|Workflow Session| C2[workflow-session.json]
|
||||
B -->|Markdown| C3[.md File + Gemini AI]
|
||||
B -->|JSON| C4[plan.json]
|
||||
C1 --> D[Extract Tasks]
|
||||
C2 --> D
|
||||
C3 --> D
|
||||
C4 --> D
|
||||
D --> E{--issue
|
||||
Provided?}
|
||||
E -->|Yes| F{Issue
|
||||
Exists?}
|
||||
E -->|No| G[Create New
|
||||
Issue]
|
||||
F -->|Yes| H{--supplement?}
|
||||
F -->|No| I[Error: Issue
|
||||
Not Found]
|
||||
H -->|Yes| J[Load Existing
|
||||
Solution]
|
||||
H -->|No| K[Create New
|
||||
Solution]
|
||||
G --> K
|
||||
J --> L[Merge Tasks]
|
||||
K --> M[Normalize IDs]
|
||||
L --> M
|
||||
M --> N[Persist
|
||||
Solution]
|
||||
N --> O[Bind to Issue]
|
||||
O --> P[Status: Planned]
|
||||
P --> Q[issue:queue]
|
||||
```
|
||||
|
||||
## Supported Sources
|
||||
|
||||
### 1. Lite-Plan
|
||||
|
||||
**Location**: `.workflow/.lite-plan/{slug}/plan.json`
|
||||
|
||||
**Schema**:
|
||||
```typescript
|
||||
interface LitePlan {
|
||||
summary: string;
|
||||
approach: string;
|
||||
complexity: 'low' | 'medium' | 'high';
|
||||
estimated_time: string;
|
||||
tasks: LiteTask[];
|
||||
_metadata: {
|
||||
timestamp: string;
|
||||
exploration_angles: string[];
|
||||
};
|
||||
}
|
||||
|
||||
interface LiteTask {
|
||||
id: string;
|
||||
title: string;
|
||||
scope: string;
|
||||
action: string;
|
||||
description: string;
|
||||
modification_points: Array<{file, target, change}>;
|
||||
implementation: string[];
|
||||
acceptance: string[];
|
||||
depends_on: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Workflow Session
|
||||
|
||||
**Location**: `.workflow/active/{session}/` or `WFS-xxx` ID
|
||||
|
||||
**Files**:
|
||||
- `workflow-session.json` - Session metadata
|
||||
- `IMPL_PLAN.md` - Implementation plan (optional)
|
||||
- `.task/IMPL-*.json` - Task definitions
|
||||
|
||||
**Extraction**:
|
||||
```typescript
|
||||
// From workflow-session.json
|
||||
{
|
||||
title: session.name,
|
||||
description: session.description,
|
||||
session_id: session.id
|
||||
}
|
||||
|
||||
// From IMPL_PLAN.md
|
||||
approach: Extract overview section
|
||||
|
||||
// From .task/IMPL-*.json
|
||||
tasks: Map IMPL-001 → T1, IMPL-002 → T2...
|
||||
```
|
||||
|
||||
### 3. Markdown File
|
||||
|
||||
**Any `.md` file with implementation/task content**
|
||||
|
||||
**AI Extraction** (via Gemini CLI):
|
||||
```javascript
|
||||
// Prompt Gemini to extract structure
|
||||
{
|
||||
title: "Extracted from document",
|
||||
approach: "Technical strategy section",
|
||||
tasks: [
|
||||
{
|
||||
id: "T1",
|
||||
title: "Parsed from headers/lists",
|
||||
scope: "inferred from content",
|
||||
action: "detected from verbs",
|
||||
implementation: ["step 1", "step 2"],
|
||||
acceptance: ["criteria 1", "criteria 2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. JSON File
|
||||
|
||||
**Direct JSON matching plan-json-schema**
|
||||
|
||||
```typescript
|
||||
interface JSONPlan {
|
||||
summary?: string;
|
||||
title?: string;
|
||||
description?: string;
|
||||
approach?: string;
|
||||
complexity?: 'low' | 'medium' | 'high';
|
||||
tasks: JSONTask[];
|
||||
_metadata?: object;
|
||||
}
|
||||
```
|
||||
|
||||
## Task Normalization
|
||||
|
||||
### ID Normalization
|
||||
|
||||
```javascript
|
||||
// Various input formats → T1, T2, T3...
|
||||
"IMPL-001" → "T1"
|
||||
"IMPL-01" → "T1"
|
||||
"task-1" → "T1"
|
||||
"1" → "T1"
|
||||
"T-1" → "T1"
|
||||
```
|
||||
|
||||
### Depends-On Normalization
|
||||
|
||||
```javascript
|
||||
// Normalize all references to T-format
|
||||
depends_on: ["IMPL-001", "task-2"]
|
||||
// → ["T1", "T2"]
|
||||
```
|
||||
|
||||
### Action Validation
|
||||
|
||||
```javascript
|
||||
// Valid actions (case-insensitive, auto-capitalized)
|
||||
['Create', 'Update', 'Implement', 'Refactor',
|
||||
'Add', 'Delete', 'Configure', 'Test', 'Fix']
|
||||
|
||||
// Invalid actions → Default to 'Implement'
|
||||
'build' → 'Implement'
|
||||
'write' → 'Create'
|
||||
```
|
||||
|
||||
## Solution Schema
|
||||
|
||||
Target format for all extracted data:
|
||||
|
||||
```typescript
|
||||
interface Solution {
|
||||
id: string; // SOL-{issue-id}-{4-char-uid}
|
||||
description?: string; // High-level summary
|
||||
approach?: string; // Technical strategy
|
||||
tasks: Task[]; // Required: at least 1 task
|
||||
exploration_context?: object; // Optional: source context
|
||||
analysis?: {
|
||||
risk: 'low' | 'medium' | 'high';
|
||||
impact: 'low' | 'medium' | 'high';
|
||||
complexity: 'low' | 'medium' | 'high';
|
||||
};
|
||||
score?: number; // 0.0-1.0
|
||||
is_bound: boolean;
|
||||
created_at: string;
|
||||
bound_at?: string;
|
||||
_conversion_metadata?: {
|
||||
source_type: string;
|
||||
source_path: string;
|
||||
converted_at: string;
|
||||
};
|
||||
}
|
||||
|
||||
interface Task {
|
||||
id: string; // T1, T2, T3...
|
||||
title: string; // Required: action verb + target
|
||||
scope: string; // Required: module path or feature area
|
||||
action: Action; // Required: Create|Update|Implement...
|
||||
description?: string;
|
||||
modification_points?: Array<{file, target, change}>;
|
||||
implementation: string[]; // Required: step-by-step guide
|
||||
test?: {
|
||||
unit?: string[];
|
||||
integration?: string[];
|
||||
commands?: string[];
|
||||
coverage_target?: string;
|
||||
};
|
||||
acceptance: {
|
||||
criteria: string[];
|
||||
verification: string[];
|
||||
};
|
||||
commit?: {
|
||||
type: string;
|
||||
scope: string;
|
||||
message_template: string;
|
||||
breaking?: boolean;
|
||||
};
|
||||
depends_on?: string[];
|
||||
priority?: number; // 1-5 (default: 3)
|
||||
}
|
||||
|
||||
type Action = 'Create' | 'Update' | 'Implement' | 'Refactor' |
|
||||
'Add' | 'Delete' | 'Configure' | 'Test' | 'Fix';
|
||||
```
|
||||
|
||||
## Priority Auto-Detection
|
||||
|
||||
For new issues created from plans:
|
||||
|
||||
```javascript
|
||||
const complexityMap = {
|
||||
high: 2, // High complexity → priority 2 (high)
|
||||
medium: 3, // Medium complexity → priority 3 (medium)
|
||||
low: 4 // Low complexity → priority 4 (low)
|
||||
};
|
||||
|
||||
// If no complexity specified, default to 3
|
||||
const priority = complexityMap[plan.complexity?.toLowerCase()] || 3;
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error Code | Message | Resolution |
|
||||
|------------|---------|------------|
|
||||
| **E001** | Source not found: {path} | Check path exists and is accessible |
|
||||
| **E002** | Unable to detect source format | Verify file contains valid plan structure |
|
||||
| **E003** | Issue not found: {id} | Check issue ID or omit --issue to create new |
|
||||
| **E004** | Issue already has bound solution | Use --supplement to add tasks |
|
||||
| **E005** | Failed to extract tasks from markdown | Check markdown structure, try simpler format |
|
||||
| **E006** | No tasks extracted from source | Source must contain at least 1 task |
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
```bash
|
||||
# Create new issue
|
||||
ccw issue create << 'EOF'
|
||||
{"title":"...","context":"...","priority":3,"source":"converted"}
|
||||
EOF
|
||||
|
||||
# Check issue exists
|
||||
ccw issue status <id> --json
|
||||
|
||||
# Get existing solution
|
||||
ccw issue solution <solution-id> --json
|
||||
|
||||
# Bind solution to issue
|
||||
ccw issue bind <issue-id> <solution-id>
|
||||
|
||||
# Update issue status
|
||||
ccw issue update <issue-id> --status planned
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[issue:plan](./issue-plan.md)** - Generate solutions from issue exploration
|
||||
- **[issue:new](./issue-new.md)** - Create issues from GitHub or text
|
||||
- **[issue:queue](./issue-queue.md)** - Form execution queue from converted plans
|
||||
- **[issue:execute](./issue-execute.md)** - Execute converted solutions
|
||||
- **[workflow:lite-lite-lite](#)** - Generate lite-plan artifacts
|
||||
- **[workflow:execute](#)** - Generate workflow sessions
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Verify source format**: Ensure plan has valid structure before conversion
|
||||
2. **Check for existing solutions**: Use --supplement to add tasks, not replace
|
||||
3. **Review extracted tasks**: Verify AI extraction accuracy for markdown
|
||||
4. **Normalize manually**: Edit task IDs and dependencies if needed
|
||||
5. **Test in supplement mode**: Add tasks to existing solution before creating new issue
|
||||
6. **Keep source artifacts**: Don't delete original plan files after conversion
|
||||
269
ccw/docs-site/docs/commands/issue/issue-discover.md
Normal file
269
ccw/docs-site/docs/commands/issue/issue-discover.md
Normal file
@@ -0,0 +1,269 @@
|
||||
---
|
||||
title: issue:discover
|
||||
sidebar_label: issue:discover
|
||||
sidebar_position: 2
|
||||
description: Discover potential issues from multiple code analysis perspectives
|
||||
---
|
||||
|
||||
# issue:discover
|
||||
|
||||
Multi-perspective issue discovery orchestrator that explores code from different angles to identify potential bugs, UX improvements, test gaps, and other actionable items.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:discover` command analyzes code from 8 specialized perspectives (bug, UX, test, quality, security, performance, maintainability, best-practices) using parallel CLI agents. It aggregates findings and can export high-priority discoveries as issues.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **8 analysis perspectives**: Specialized analysis for different concern areas
|
||||
- **Parallel execution**: Multiple agents run simultaneously for speed
|
||||
- **External research**: Exa integration for security and best-practices benchmarking
|
||||
- **Dashboard integration**: View and filter findings via CCW dashboard
|
||||
- **Smart prioritization**: Automated severity scoring and deduplication
|
||||
- **Direct export**: Convert findings to issues with one click
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Interactive perspective selection
|
||||
/issue:discover src/auth/**
|
||||
|
||||
# Specific perspectives
|
||||
/issue:discover src/payment/** --perspectives=bug,security,test
|
||||
|
||||
# With external research
|
||||
/issue:discover src/api/** --external
|
||||
|
||||
# Auto mode - all perspectives
|
||||
/issue:discover src/** --yes
|
||||
|
||||
# Multiple modules
|
||||
/issue:discover src/auth/**,src/payment/**
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `path-pattern` | Yes | Glob pattern for files to analyze |
|
||||
| `--perspectives` | No | Comma-separated list (default: interactive) |
|
||||
| `--external` | No | Enable Exa external research |
|
||||
| `-y, --yes` | No | Auto-select all perspectives |
|
||||
|
||||
## Perspectives
|
||||
|
||||
### Available Analysis Types
|
||||
|
||||
| Perspective | Focus Areas | Categories |
|
||||
|-------------|-------------|------------|
|
||||
| **bug** | Edge cases, null checks, resource leaks | edge-case, null-check, race-condition, boundary |
|
||||
| **ux** | User experience issues | error-message, loading-state, accessibility, feedback |
|
||||
| **test** | Test coverage gaps | missing-test, edge-case-test, integration-gap |
|
||||
| **quality** | Code quality issues | complexity, duplication, naming, code-smell |
|
||||
| **security** | Security vulnerabilities | injection, auth, encryption, input-validation |
|
||||
| **performance** | Performance bottlenecks | n-plus-one, memory-usage, caching, algorithm |
|
||||
| **maintainability** | Code maintainability | coupling, cohesion, tech-debt, module-boundary |
|
||||
| **best-practices** | Industry best practices | convention, pattern, framework-usage |
|
||||
|
||||
## Examples
|
||||
|
||||
### Quick Scan (Recommended)
|
||||
|
||||
```bash
|
||||
/issue:discover src/auth/**
|
||||
# Interactive prompt:
|
||||
# Select primary discovery focus:
|
||||
# [1] Bug + Test + Quality (Recommended)
|
||||
# [2] Security + Performance
|
||||
# [3] Maintainability + Best-practices
|
||||
# [4] Full analysis
|
||||
```
|
||||
|
||||
### Security Audit with External Research
|
||||
|
||||
```bash
|
||||
/issue:discover src/payment/** --perspectives=security --external
|
||||
# Uses Exa to research OWASP payment security standards
|
||||
# Compares implementation against industry benchmarks
|
||||
```
|
||||
|
||||
### Full Analysis with Auto Mode
|
||||
|
||||
```bash
|
||||
/issue:discover src/api/** --yes
|
||||
# Runs all 8 perspectives in parallel
|
||||
# No confirmations, processes all findings
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Target Files] --> B[Select Perspectives]
|
||||
B --> C[Launch N Agents Parallel]
|
||||
C --> D1[Bug Agent]
|
||||
C --> D2[UX Agent]
|
||||
C --> D3[Test Agent]
|
||||
C --> D4[Security Agent + Exa]
|
||||
C --> D5[Performance Agent]
|
||||
C --> D6[Quality Agent]
|
||||
C --> D7[Maintainability Agent]
|
||||
C --> D8[Best-Practices Agent + Exa]
|
||||
D1 --> E[Aggregate Findings]
|
||||
D2 --> E
|
||||
D3 --> E
|
||||
D4 --> E
|
||||
D5 --> E
|
||||
D6 --> E
|
||||
D7 --> E
|
||||
D8 --> E
|
||||
E --> F{Priority Score}
|
||||
F -->|Critical/High| G[Export to Issues]
|
||||
F -->|Medium| H[Dashboard Review]
|
||||
F -->|Low| I[Archive]
|
||||
G --> J[issue:plan]
|
||||
H --> J
|
||||
```
|
||||
|
||||
## Discovery Output Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
.workflow/issues/discoveries/
|
||||
├── {discovery-id}/
|
||||
│ ├── discovery-state.json # Session state machine
|
||||
│ ├── perspectives/
|
||||
│ │ ├── bug.json # Bug findings
|
||||
│ │ ├── ux.json # UX findings
|
||||
│ │ ├── security.json # Security findings
|
||||
│ │ └── ...
|
||||
│ ├── external-research.json # Exa results (if enabled)
|
||||
│ ├── discovery-issues.jsonl # Exported candidate issues
|
||||
│ └── summary.md # Consolidated report
|
||||
```
|
||||
|
||||
### Finding Schema
|
||||
|
||||
```typescript
|
||||
interface DiscoveryFinding {
|
||||
id: string;
|
||||
perspective: string;
|
||||
title: string;
|
||||
priority: 'critical' | 'high' | 'medium' | 'low';
|
||||
category: string;
|
||||
description: string;
|
||||
file: string;
|
||||
line: number;
|
||||
snippet: string;
|
||||
suggested_issue: string;
|
||||
confidence: number;
|
||||
priority_score: number;
|
||||
}
|
||||
```
|
||||
|
||||
## Priority Categories
|
||||
|
||||
### Critical (Automatic Export)
|
||||
|
||||
- Data corruption risks
|
||||
- Security vulnerabilities (auth bypass, injection)
|
||||
- Memory leaks
|
||||
- Race conditions
|
||||
- Critical accessibility issues
|
||||
|
||||
### High (Recommended Export)
|
||||
|
||||
- Missing core functionality tests
|
||||
- Significant UX confusion
|
||||
- N+1 query problems
|
||||
- Clear security gaps
|
||||
- Major code smells
|
||||
|
||||
### Medium (Dashboard Review)
|
||||
|
||||
- Edge case gaps
|
||||
- Inconsistent patterns
|
||||
- Minor performance issues
|
||||
- Documentation gaps
|
||||
- Style violations
|
||||
|
||||
### Low (Informational)
|
||||
|
||||
- Cosmetic issues
|
||||
- Minor naming inconsistencies
|
||||
- Optimization opportunities
|
||||
- Nice-to-have improvements
|
||||
|
||||
## Dashboard Integration
|
||||
|
||||
### Viewing Discoveries
|
||||
|
||||
```bash
|
||||
# Open CCW dashboard
|
||||
ccw view
|
||||
|
||||
# Navigate to: Issues > Discovery
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- View all discovery sessions
|
||||
- Filter by perspective and priority
|
||||
- Preview finding details with code snippets
|
||||
- Bulk select findings for export
|
||||
- Compare findings across sessions
|
||||
|
||||
### Exporting to Issues
|
||||
|
||||
From the dashboard:
|
||||
1. Select findings to export
|
||||
2. Click "Export as Issues"
|
||||
3. Findings are converted to standard issue format
|
||||
4. Appended to `.workflow/issues/issues.jsonl`
|
||||
5. Status set to `registered`
|
||||
6. Continue with `/issue:plan` workflow
|
||||
|
||||
## Exa External Research
|
||||
|
||||
### Security Perspective
|
||||
|
||||
Researches:
|
||||
- OWASP Top 10 for your technology stack
|
||||
- Industry-standard security patterns
|
||||
- Common vulnerabilities in your framework
|
||||
- Best practices for your specific use case
|
||||
|
||||
### Best-Practices Perspective
|
||||
|
||||
Researches:
|
||||
- Framework-specific conventions
|
||||
- Language idioms and patterns
|
||||
- Deprecated API warnings
|
||||
- Community-recommended approaches
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[issue:new](./issue-new.md)** - Create issues from discoveries
|
||||
- **[issue:plan](./issue-plan.md)** - Plan solutions for discovered issues
|
||||
- **[issue:manage](#)** - Interactive issue management dashboard
|
||||
- **[review-code](#)** - Code review for quality assessment
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start focused**: Begin with specific modules, not entire codebase
|
||||
2. **Quick scan first**: Use bug+test+quality for fast results
|
||||
3. **Review before export**: Not all findings warrant issues
|
||||
4. **Enable Exa strategically**: For unfamiliar tech or security audits
|
||||
5. **Combine perspectives**: Run related perspectives together (e.g., security+bug)
|
||||
6. **Iterate**: Run discovery on changed modules after each sprint
|
||||
|
||||
## Comparison: Discovery vs Code Review
|
||||
|
||||
| Aspect | issue:discover | review-code |
|
||||
|--------|----------------|-------------|
|
||||
| **Purpose** | Find actionable issues | Assess code quality |
|
||||
| **Output** | Exportable issues | Quality report |
|
||||
| **Perspectives** | 8 specialized angles | 7 quality dimensions |
|
||||
| **External Research** | Yes (Exa) | No |
|
||||
| **Dashboard Integration** | Yes | No |
|
||||
| **Use When** | Proactive issue hunting | Post-commit review |
|
||||
364
ccw/docs-site/docs/commands/issue/issue-execute.md
Normal file
364
ccw/docs-site/docs/commands/issue/issue-execute.md
Normal file
@@ -0,0 +1,364 @@
|
||||
---
|
||||
title: issue:execute
|
||||
sidebar_label: issue:execute
|
||||
sidebar_position: 5
|
||||
description: Execute issue queue with DAG-based parallel orchestration
|
||||
---
|
||||
|
||||
# issue:execute
|
||||
|
||||
Minimal orchestrator that dispatches solution IDs to executors. Each executor receives a complete solution with all tasks and commits once per solution.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:execute` command executes queued solutions using DAG-based parallel orchestration. Each executor receives a complete solution with all tasks, executes tasks sequentially, and commits once per solution. Supports optional git worktree isolation for clean workspace management.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **DAG-based parallelism**: Automatic parallel execution of independent solutions
|
||||
- **Solution-level execution**: Each executor handles all tasks in a solution
|
||||
- **Single commit per solution**: Clean git history with formatted summaries
|
||||
- **Worktree isolation**: Optional isolated workspace for queue execution
|
||||
- **Multiple executors**: Codex, Gemini, or Agent support
|
||||
- **Resume capability**: Recover from interruptions with existing worktree
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Execute specific queue (REQUIRED)
|
||||
/issue:execute --queue QUE-xxx
|
||||
|
||||
# Execute in isolated worktree
|
||||
/issue:execute --queue QUE-xxx --worktree
|
||||
|
||||
# Resume in existing worktree
|
||||
/issue:execute --queue QUE-xxx --worktree /path/to/worktree
|
||||
|
||||
# Dry-run (show DAG without executing)
|
||||
/issue:execute --queue QUE-xxx
|
||||
# Select: Dry-run mode
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--queue <id>` | Yes | Queue ID to execute (required) |
|
||||
| `--worktree` | No | Create isolated worktree for execution |
|
||||
| `--worktree <path>` | No | Resume in existing worktree |
|
||||
|
||||
### Executor Selection
|
||||
|
||||
Interactive prompt selects:
|
||||
- **Codex** (Recommended): Autonomous coding with 2hr timeout
|
||||
- **Gemini**: Large context analysis and implementation
|
||||
- **Agent**: Claude Code sub-agent for complex tasks
|
||||
|
||||
## Examples
|
||||
|
||||
### Execute Queue (Interactive)
|
||||
|
||||
```bash
|
||||
/issue:execute --queue QUE-20251227-143000
|
||||
# Output:
|
||||
# ## Executing Queue: QUE-20251227-143000
|
||||
# ## Queue DAG (Solution-Level)
|
||||
# - Total Solutions: 5
|
||||
# - Ready: 2
|
||||
# - Completed: 0
|
||||
# - Parallel in batch 1: 2
|
||||
#
|
||||
# Select executor:
|
||||
# [1] Codex (Recommended)
|
||||
# [2] Gemini
|
||||
# [3] Agent
|
||||
# Select mode:
|
||||
# [1] Execute (Recommended)
|
||||
# [2] Dry-run
|
||||
# Use git worktree?
|
||||
# [1] Yes (Recommended)
|
||||
# [2] No
|
||||
```
|
||||
|
||||
### Queue ID Not Provided
|
||||
|
||||
```bash
|
||||
/issue:execute
|
||||
# Output:
|
||||
# Available Queues:
|
||||
# ID Status Progress Issues
|
||||
# -----------------------------------------------------------
|
||||
# → QUE-20251215-001 active 3/10 ISS-001, ISS-002
|
||||
# QUE-20251210-002 active 0/5 ISS-003
|
||||
# QUE-20251205-003 completed 8/8 ISS-004
|
||||
#
|
||||
# Which queue would you like to execute?
|
||||
# [1] QUE-20251215-001 - 3/10 completed, Issues: ISS-001, ISS-002
|
||||
# [2] QUE-20251210-002 - 0/5 completed, Issues: ISS-003
|
||||
```
|
||||
|
||||
### Execute with Worktree
|
||||
|
||||
```bash
|
||||
/issue:execute --queue QUE-xxx --worktree
|
||||
# Output:
|
||||
# Created queue worktree: /repo/.ccw/worktrees/queue-exec-QUE-xxx
|
||||
# Branch: queue-exec-QUE-xxx
|
||||
# ### Executing Solutions (DAG batch 1): S-1, S-2
|
||||
# [S-1] Executor launched (codex, 2hr timeout)
|
||||
# [S-2] Executor launched (codex, 2hr timeout)
|
||||
# ✓ S-1 completed: 3 tasks, 1 commit
|
||||
# ✓ S-2 completed: 2 tasks, 1 commit
|
||||
```
|
||||
|
||||
### Resume Existing Worktree
|
||||
|
||||
```bash
|
||||
# Find existing worktrees
|
||||
git worktree list
|
||||
# /repo/.ccw/worktrees/queue-exec-QUE-123
|
||||
|
||||
# Resume execution
|
||||
/issue:execute --queue QUE-123 --worktree /repo/.ccw/worktrees/queue-exec-QUE-123
|
||||
# Output:
|
||||
# Resuming in existing worktree: /repo/.ccw/worktrees/queue-exec-QUE-123
|
||||
# Branch: queue-exec-QUE-123
|
||||
# ### Executing Solutions (DAG batch 2): S-3
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Start] --> B{Queue ID
|
||||
Provided?}
|
||||
B -->|No| C[List Queues]
|
||||
B -->|Yes| D[Validate Queue]
|
||||
C --> E[User Selects]
|
||||
E --> D
|
||||
D --> F{Use
|
||||
Worktree?}
|
||||
F -->|Yes| G[Create/Resume
|
||||
Worktree]
|
||||
F -->|No| H[Main Workspace]
|
||||
G --> I[Get DAG]
|
||||
H --> I
|
||||
I --> J[Parallel Batches]
|
||||
J --> K[Dispatch Batch 1]
|
||||
K --> L1[Executor 1:
|
||||
S-1 Detail]
|
||||
K --> L2[Executor 2:
|
||||
S-2 Detail]
|
||||
K --> L3[Executor N:
|
||||
S-N Detail]
|
||||
L1 --> M1[Execute All Tasks]
|
||||
L2 --> M2[Execute All Tasks]
|
||||
L3 --> M3[Execute All Tasks]
|
||||
M1 --> N1[Commit Once]
|
||||
M2 --> N2[Commit Once]
|
||||
M3 --> N3[Commit Once]
|
||||
N1 --> O[Mark Done]
|
||||
N2 --> O
|
||||
N3 --> O
|
||||
O --> P{More Batches?}
|
||||
P -->|Yes| I
|
||||
P -->|No| Q{Worktree
|
||||
Used?}
|
||||
Q -->|Yes| R{All Complete?}
|
||||
Q -->|No| S[Done]
|
||||
R -->|Yes| T[Merge Strategy]
|
||||
R -->|No| I
|
||||
T --> U1[Create PR]
|
||||
T --> U2[Merge Main]
|
||||
T --> U3[Keep Branch]
|
||||
```
|
||||
|
||||
## Execution Model
|
||||
|
||||
### DAG-Based Batching
|
||||
|
||||
```
|
||||
Batch 1 (Parallel): S-1, S-2 → No file conflicts
|
||||
Batch 2 (Parallel): S-3, S-4 → No conflicts, waits for Batch 1
|
||||
Batch 3 (Sequential): S-5 → Depends on S-3
|
||||
```
|
||||
|
||||
### Solution Execution (Within Executor)
|
||||
|
||||
```
|
||||
ccw issue detail S-1 → Get full solution with all tasks
|
||||
↓
|
||||
For each task T1, T2, T3...:
|
||||
- Follow implementation steps
|
||||
- Run test commands
|
||||
- Verify acceptance criteria
|
||||
↓
|
||||
After ALL tasks pass:
|
||||
git commit -m "feat(scope): summary
|
||||
|
||||
Solution: S-1
|
||||
Tasks completed: T1, T2, T3
|
||||
|
||||
Changes:
|
||||
- file1: what changed
|
||||
- file2: what changed
|
||||
|
||||
Verified: all tests passed"
|
||||
↓
|
||||
ccw issue done S-1 --result '{summary, files, commit}'
|
||||
```
|
||||
|
||||
## Executor Dispatch
|
||||
|
||||
### Codex Executor
|
||||
|
||||
```bash
|
||||
ccw cli -p "## Execute Solution: S-1
|
||||
..." --tool codex --mode write --id exec-S-1
|
||||
# Timeout: 2 hours (7200000ms)
|
||||
# Background: true
|
||||
```
|
||||
|
||||
### Gemini Executor
|
||||
|
||||
```bash
|
||||
ccw cli -p "## Execute Solution: S-1
|
||||
..." --tool gemini --mode write --id exec-S-1
|
||||
# Timeout: 1 hour (3600000ms)
|
||||
# Background: true
|
||||
```
|
||||
|
||||
### Agent Executor
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: 'code-developer',
|
||||
run_in_background: false,
|
||||
description: 'Execute solution S-1',
|
||||
prompt: '...' // Full execution prompt
|
||||
})
|
||||
```
|
||||
|
||||
## Worktree Management
|
||||
|
||||
### Create New Worktree
|
||||
|
||||
```bash
|
||||
# One worktree for entire queue execution
|
||||
git worktree add .ccw/worktrees/queue-exec-QUE-xxx -b queue-exec-QUE-xxx
|
||||
# All solutions execute in this isolated workspace
|
||||
# Main workspace remains untouched
|
||||
```
|
||||
|
||||
### Resume Existing Worktree
|
||||
|
||||
```bash
|
||||
# Find interrupted executions
|
||||
git worktree list
|
||||
# Output:
|
||||
# /repo/.ccw/worktrees/queue-exec-QUE-123 abc1234 [queue-exec-QUE-123]
|
||||
|
||||
# Resume with worktree path
|
||||
/issue:execute --queue QUE-123 --worktree /repo/.ccw/worktrees/queue-exec-QUE-123
|
||||
```
|
||||
|
||||
### Worktree Completion
|
||||
|
||||
After all batches complete:
|
||||
|
||||
```bash
|
||||
# Prompt for merge strategy
|
||||
Queue complete. What to do with worktree branch "queue-exec-QUE-xxx"?
|
||||
[1] Create PR (Recommended)
|
||||
[2] Merge to main
|
||||
[3] Keep branch
|
||||
|
||||
# Create PR
|
||||
git push -u origin queue-exec-QUE-xxx
|
||||
gh pr create --title "Queue QUE-xxx" --body "Issue queue execution"
|
||||
git worktree remove .ccw/worktrees/queue-exec-QUE-xxx
|
||||
|
||||
# OR Merge to main
|
||||
git merge --no-ff queue-exec-QUE-xxx -m "Merge queue QUE-xxx"
|
||||
git branch -d queue-exec-QUE-xxx
|
||||
git worktree remove .ccw/worktrees/queue-exec-QUE-xxx
|
||||
```
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
### Queue Operations
|
||||
|
||||
```bash
|
||||
# List queues
|
||||
ccw issue queue list --brief --json
|
||||
|
||||
# Get DAG
|
||||
ccw issue queue dag --queue QUE-xxx
|
||||
# Returns: {parallel_batches: [["S-1","S-2"], ["S-3"]]}
|
||||
```
|
||||
|
||||
### Solution Operations
|
||||
|
||||
```bash
|
||||
# Get solution details (READ-ONLY)
|
||||
ccw issue detail S-1
|
||||
# Returns: Full solution with all tasks
|
||||
|
||||
# Mark solution complete
|
||||
ccw issue done S-1 --result '{"summary":"...","files_modified":[...],"commit":{...},"tasks_completed":3}'
|
||||
|
||||
# Mark solution failed
|
||||
ccw issue done S-1 --fail --reason '{"task_id":"T2","error_type":"test_failure","message":"..."}'
|
||||
```
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
```bash
|
||||
feat(auth): implement OAuth2 login flow
|
||||
|
||||
Solution: S-1
|
||||
Tasks completed: T1, T2, T3
|
||||
|
||||
Changes:
|
||||
- src/auth/oauth.ts: Implemented OAuth2 flow
|
||||
- src/auth/login.ts: Integrated OAuth with existing login
|
||||
- tests/auth/oauth.test.ts: Added comprehensive tests
|
||||
|
||||
Verified: all tests passed
|
||||
```
|
||||
|
||||
**Commit Types**:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `refactor`: Code refactoring
|
||||
- `docs`: Documentation
|
||||
- `test`: Test updates
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[issue:queue](./issue-queue.md)** - Form execution queue before executing
|
||||
- **[issue:plan](./issue-plan.md)** - Plan solutions before queuing
|
||||
- **ccw issue retry** - Reset failed solutions for retry
|
||||
- **ccw issue queue dag** - View dependency graph
|
||||
- **ccw issue detail <id>** - View solution details
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Codex executor**: Best for long-running autonomous work
|
||||
2. **Enable worktree**: Keeps main workspace clean during execution
|
||||
3. **Check DAG first**: Use dry-run to see execution plan
|
||||
4. **Monitor progress**: Executors run in background, check completion
|
||||
5. **Resume on failure**: Use existing worktree path to continue
|
||||
6. **Review commits**: Each solution produces one formatted commit
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| No queue specified | --queue argument missing | List queues and select one |
|
||||
| No ready solutions | Dependencies blocked | Check DAG for blocking issues |
|
||||
| Executor timeout | Solution too complex | Break into smaller solutions |
|
||||
| Worktree exists | Previous incomplete execution | Resume with --worktree <path> |
|
||||
| Partial task failure | Task reports failure | Check ccw issue done --fail output |
|
||||
| Git conflicts | Parallel executors touched same files | DAG should prevent this |
|
||||
460
ccw/docs-site/docs/commands/issue/issue-from-brainstorm.md
Normal file
460
ccw/docs-site/docs/commands/issue/issue-from-brainstorm.md
Normal file
@@ -0,0 +1,460 @@
|
||||
---
|
||||
title: issue:from-brainstorm
|
||||
sidebar_label: issue:from-brainstorm
|
||||
sidebar_position: 6
|
||||
description: Convert brainstorm session ideas into issues with solutions
|
||||
---
|
||||
|
||||
# issue:from-brainstorm
|
||||
|
||||
Bridge command that converts brainstorm-with-file session output into executable issue + solution for parallel-dev-cycle consumption.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:from-brainstorm` command converts brainstorm session ideas into structured issues with executable solutions. It loads synthesis results, selects ideas, enriches context with multi-CLI perspectives, and generates task-based solutions ready for execution.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Idea selection**: Interactive or automatic (highest-scored) selection
|
||||
- **Context enrichment**: Adds clarifications and multi-perspective insights
|
||||
- **Auto task generation**: Creates structured tasks from idea next_steps
|
||||
- **Priority calculation**: Derives priority from idea score (0-10 → 1-5)
|
||||
- **Direct binding**: Solution automatically bound to issue
|
||||
- **Session metadata**: Preserves brainstorm origin in issue
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Interactive mode - select idea from table
|
||||
/issue:from-brainstorm SESSION="BS-rate-limiting-2025-01-28"
|
||||
|
||||
# Auto mode - select highest-scored idea
|
||||
/issue:from-brainstorm SESSION="BS-caching-2025-01-28" --auto
|
||||
|
||||
# Pre-select idea by index
|
||||
/issue:from-brainstorm SESSION="BS-auth-system-2025-01-28" --idea=0
|
||||
|
||||
# Auto mode with skip confirmations
|
||||
/issue:from-brainstorm SESSION="BS-caching-2025-01-28" --auto -y
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `SESSION` | Yes | Session ID or path to `.workflow/.brainstorm/BS-xxx` |
|
||||
| `--idea <index>` | No | Pre-select idea by index (0-based) |
|
||||
| `--auto` | No | Auto-select highest-scored idea |
|
||||
| `-y, --yes` | No | Skip all confirmations |
|
||||
|
||||
## Examples
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
```bash
|
||||
/issue:from-brainstorm SESSION="BS-rate-limiting-2025-01-28"
|
||||
# Output:
|
||||
# | # | Title | Score | Feasibility |
|
||||
# |---|-------|-------|-------------|
|
||||
# | 0 | Token Bucket Algorithm | 8.5 | High |
|
||||
# | 1 | Sliding Window Counter | 7.2 | Medium |
|
||||
# | 2 | Fixed Window | 6.1 | High |
|
||||
#
|
||||
# Select idea: #0
|
||||
#
|
||||
# ✓ Created issue: ISS-20250128-001
|
||||
# ✓ Created solution: SOL-ISS-20250128-001-ab3d
|
||||
# ✓ Bound solution to issue
|
||||
# → Status: planned
|
||||
# → Next: /issue:queue
|
||||
```
|
||||
|
||||
### Auto Mode
|
||||
|
||||
```bash
|
||||
/issue:from-brainstorm SESSION="BS-caching-2025-01-28" --auto
|
||||
# Output:
|
||||
# Auto-selected: Redis Cache Layer (Score: 9.2/10)
|
||||
# ✓ Created issue: ISS-20250128-002
|
||||
# ✓ Solution with 4 tasks:
|
||||
# - T1: Research & Validate Approach
|
||||
# - T2: Design & Create Specification
|
||||
# - T3: Implement Redis Cache Layer
|
||||
# - T4: Write Integration Tests
|
||||
# → Status: planned
|
||||
```
|
||||
|
||||
### Pre-select Idea
|
||||
|
||||
```bash
|
||||
/issue:from-brainstorm SESSION="BS-auth-system-2025-01-28" --idea=1
|
||||
# Skips selection, uses idea at index 1
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Brainstorm Session] --> B[Load Synthesis]
|
||||
B --> C[Load Perspectives
|
||||
Optional]
|
||||
C --> D[Load Synthesis
|
||||
Artifacts
|
||||
Optional]
|
||||
D --> E{Idea Selection}
|
||||
E -->|Auto| F[Select Highest
|
||||
Score]
|
||||
E -->|Pre-selected| F
|
||||
E -->|Interactive| G[Display Table]
|
||||
G --> H[User Selects]
|
||||
H --> F
|
||||
F --> I[Enrich Context]
|
||||
I --> J[Add Clarifications]
|
||||
J --> K[Add Multi-CLI
|
||||
Insights]
|
||||
K --> L[Create Issue]
|
||||
L --> M[Generate Tasks]
|
||||
M --> N[Create Solution]
|
||||
N --> O[Bind Solution]
|
||||
O --> P[Status: Planned]
|
||||
P --> Q[issue:queue]
|
||||
```
|
||||
|
||||
## Session Files
|
||||
|
||||
### Input Files
|
||||
|
||||
```
|
||||
.workflow/.brainstorm/BS-{slug}-{date}/
|
||||
├── synthesis.json # REQUIRED - Top ideas with scores
|
||||
├── perspectives.json # OPTIONAL - Multi-CLI insights
|
||||
├── brainstorm.md # Reference only
|
||||
└── .brainstorming/ # OPTIONAL - Synthesis artifacts
|
||||
├── system-architect/
|
||||
│ └── analysis.md # Contains clarifications
|
||||
├── api-designer/
|
||||
│ └── analysis.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Synthesis Schema
|
||||
|
||||
```typescript
|
||||
interface Synthesis {
|
||||
session_id: string;
|
||||
topic: string;
|
||||
completed_at: string;
|
||||
top_ideas: Idea[];
|
||||
}
|
||||
|
||||
interface Idea {
|
||||
index: number;
|
||||
title: string;
|
||||
description: string;
|
||||
score: number; // 0-10
|
||||
novelty: number; // 0-10
|
||||
feasibility: 'Low' | 'Medium' | 'High';
|
||||
key_strengths: string[];
|
||||
main_challenges: string[];
|
||||
next_steps: string[];
|
||||
}
|
||||
```
|
||||
|
||||
## Context Enrichment
|
||||
|
||||
### Base Context (Always Included)
|
||||
|
||||
```markdown
|
||||
## Idea Description
|
||||
{idea.description}
|
||||
|
||||
## Why This Idea
|
||||
{idea.key_strengths}
|
||||
|
||||
## Challenges to Address
|
||||
{idea.main_challenges}
|
||||
|
||||
## Implementation Steps
|
||||
{idea.next_steps}
|
||||
```
|
||||
|
||||
### Enhanced Context (If Available)
|
||||
|
||||
#### From Synthesis Artifacts
|
||||
|
||||
```markdown
|
||||
## Requirements Clarification (system-architect)
|
||||
Q: How will this integrate with existing auth?
|
||||
A: Will use adapter pattern to wrap current system
|
||||
|
||||
## Architecture Feasibility (api-designer)
|
||||
Q: What API changes are needed?
|
||||
A: New /oauth/* endpoints, backward compatible
|
||||
```
|
||||
|
||||
#### From Multi-CLI Perspectives
|
||||
|
||||
```markdown
|
||||
## Creative Perspective
|
||||
Insight: Consider gamification to improve adoption
|
||||
|
||||
## Pragmatic Perspective
|
||||
Blocker: Current rate limiter lacks configuration
|
||||
|
||||
## Systematic Perspective
|
||||
Pattern: Token bucket provides better burst handling
|
||||
```
|
||||
|
||||
## Task Generation Strategy
|
||||
|
||||
### Task 1: Research & Validation
|
||||
|
||||
**Trigger**: `idea.main_challenges.length > 0`
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: "T1",
|
||||
title: "Research & Validate Approach",
|
||||
scope: "design",
|
||||
action: "Research",
|
||||
implementation: [
|
||||
"Investate identified blockers",
|
||||
"Review similar implementations in industry",
|
||||
"Validate approach with team/stakeholders"
|
||||
],
|
||||
acceptance: {
|
||||
criteria: [
|
||||
"Blockers documented with resolution strategies",
|
||||
"Feasibility assessed with risk mitigation",
|
||||
"Approach validated with key stakeholders"
|
||||
],
|
||||
verification: [
|
||||
"Research document created",
|
||||
"Stakeholder approval obtained",
|
||||
"Risk assessment completed"
|
||||
]
|
||||
},
|
||||
priority: 1
|
||||
}
|
||||
```
|
||||
|
||||
### Task 2: Design & Specification
|
||||
|
||||
**Trigger**: `idea.key_strengths.length > 0`
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: "T2",
|
||||
title: "Design & Create Specification",
|
||||
scope: "design",
|
||||
action: "Design",
|
||||
implementation: [
|
||||
"Create detailed design document",
|
||||
"Define success metrics and KPIs",
|
||||
"Plan implementation phases"
|
||||
],
|
||||
acceptance: {
|
||||
criteria: [
|
||||
"Design document complete with diagrams",
|
||||
"Success metrics defined and measurable",
|
||||
"Implementation plan with timeline"
|
||||
],
|
||||
verification: [
|
||||
"Design reviewed and approved",
|
||||
"Metrics tracked in dashboard",
|
||||
"Phase milestones defined"
|
||||
]
|
||||
},
|
||||
priority: 2
|
||||
}
|
||||
```
|
||||
|
||||
### Task 3+: Implementation Tasks
|
||||
|
||||
**Trigger**: `idea.next_steps[]`
|
||||
|
||||
Each next_step becomes a task:
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: "T3",
|
||||
title: "{next_steps[0]}", // max 60 chars
|
||||
scope: inferScope(step), // backend, frontend, infra...
|
||||
action: detectAction(step), // Implement, Create, Update...
|
||||
implementation: [
|
||||
"Execute: {next_steps[0]}",
|
||||
"Follow design specification",
|
||||
"Write unit and integration tests"
|
||||
],
|
||||
acceptance: {
|
||||
criteria: [
|
||||
"Step implemented per design",
|
||||
"Tests passing with coverage >80%",
|
||||
"Code reviewed and approved"
|
||||
],
|
||||
verification: [
|
||||
"Functional tests pass",
|
||||
"Code coverage meets threshold",
|
||||
"Review approved"
|
||||
]
|
||||
},
|
||||
priority: 3
|
||||
}
|
||||
```
|
||||
|
||||
### Fallback Task
|
||||
|
||||
**Trigger**: No tasks generated from above
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: "T1",
|
||||
title: idea.title,
|
||||
scope: "implementation",
|
||||
action: "Implement",
|
||||
implementation: [
|
||||
"Analyze requirements and context",
|
||||
"Design solution approach",
|
||||
"Implement core functionality",
|
||||
"Write comprehensive tests",
|
||||
"Document changes and usage"
|
||||
],
|
||||
acceptance: {
|
||||
criteria: [
|
||||
"Core functionality working",
|
||||
"Tests passing",
|
||||
"Documentation complete"
|
||||
],
|
||||
verification: [
|
||||
"Manual testing successful",
|
||||
"Automated tests pass",
|
||||
"Docs reviewed"
|
||||
]
|
||||
},
|
||||
priority: 3
|
||||
}
|
||||
```
|
||||
|
||||
## Priority Calculation
|
||||
|
||||
### Issue Priority
|
||||
|
||||
```javascript
|
||||
// idea.score: 0-10 → priority: 1-5
|
||||
priority = max(1, min(5, ceil((10 - score) / 2)))
|
||||
|
||||
Examples:
|
||||
score 9-10 → priority 1 (critical)
|
||||
score 7-8 → priority 2 (high)
|
||||
score 5-6 → priority 3 (medium)
|
||||
score 3-4 → priority 4 (low)
|
||||
score 0-2 → priority 5 (lowest)
|
||||
```
|
||||
|
||||
### Task Priority
|
||||
|
||||
- Research task: 1 (highest - validates approach)
|
||||
- Design task: 2 (high - foundation for implementation)
|
||||
- Implementation tasks: 3 by default
|
||||
- Testing/documentation: 4-5 (lower priority)
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Issue Created
|
||||
|
||||
```typescript
|
||||
interface Issue {
|
||||
id: string; // ISS-YYYYMMDD-NNN
|
||||
title: string; // From idea.title
|
||||
status: 'planned'; // Auto-set after binding
|
||||
priority: number; // Derived from score
|
||||
context: string; // Enriched description
|
||||
source: 'brainstorm';
|
||||
labels: string[]; // ['brainstorm', perspective, feasibility]
|
||||
expected_behavior: string; // From key_strengths
|
||||
actual_behavior: string; // From main_challenges
|
||||
affected_components: string[]; // Extracted from description
|
||||
bound_solution_id: string; // Auto-bound
|
||||
_brainstorm_metadata: {
|
||||
session_id: string;
|
||||
idea_score: number;
|
||||
novelty: number;
|
||||
feasibility: string;
|
||||
clarifications_count: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Solution Created
|
||||
|
||||
```typescript
|
||||
interface Solution {
|
||||
id: string; // SOL-{issue-id}-{4-char-uid}
|
||||
description: string; // idea.title
|
||||
approach: string; // idea.description
|
||||
tasks: Task[];
|
||||
analysis: {
|
||||
risk: 'low' | 'medium' | 'high';
|
||||
impact: 'low' | 'medium' | 'high';
|
||||
complexity: 'low' | 'medium' | 'high';
|
||||
};
|
||||
is_bound: true;
|
||||
created_at: string;
|
||||
bound_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Integration Flow
|
||||
|
||||
```
|
||||
brainstorm-with-file
|
||||
│
|
||||
├─ synthesis.json (top_ideas)
|
||||
├─ perspectives.json (multi-CLI insights)
|
||||
└─ .brainstorming/** (synthesis artifacts)
|
||||
│
|
||||
▼
|
||||
issue:from-brainstorm ◄─── This command
|
||||
│
|
||||
├─ ISS-YYYYMMDD-NNN (enriched issue)
|
||||
└─ SOL-{issue-id}-{uid} (structured solution)
|
||||
│
|
||||
▼
|
||||
issue:queue
|
||||
│
|
||||
▼
|
||||
issue:execute
|
||||
│
|
||||
▼
|
||||
Complete Solution
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[workflow:brainstorm-with-file](#)** - Generate brainstorm sessions
|
||||
- **[workflow:brainstorm:synthesis](#)** - Add clarifications to brainstorm
|
||||
- **[issue:new](./issue-new.md)** - Create issues from GitHub or text
|
||||
- **[issue:plan](./issue-plan.md)** - Plan solutions for issues
|
||||
- **[issue:queue](./issue-queue.md)** - Form execution queue
|
||||
- **[issue:execute](./issue-execute.md)** - Execute with parallel-dev-cycle
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
```bash
|
||||
# Create issue
|
||||
ccw issue create << 'EOF'
|
||||
{
|
||||
"title": "...",
|
||||
"context": "...",
|
||||
"priority": 3,
|
||||
"source": "brainstorm",
|
||||
"labels": ["brainstorm", "creative", "feasibility-high"]
|
||||
}
|
||||
EOF
|
||||
|
||||
# Bind solution
|
||||
ccw issue bind {issue-id} {solution-id}
|
||||
|
||||
# Update status
|
||||
ccw issue update {issue-id} --status planned
|
||||
```
|
||||
203
ccw/docs-site/docs/commands/issue/issue-new.md
Normal file
203
ccw/docs-site/docs/commands/issue/issue-new.md
Normal file
@@ -0,0 +1,203 @@
|
||||
---
|
||||
title: issue:new
|
||||
sidebar_label: issue:new
|
||||
sidebar_position: 1
|
||||
description: Create new issue with automatic categorization
|
||||
---
|
||||
|
||||
# issue:new
|
||||
|
||||
Create structured issues from GitHub URLs, text descriptions, or brainstorm sessions with automatic categorization and priority detection.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:new` command creates structured issues from multiple input sources with intelligent clarity detection. It asks clarifying questions only when needed and supports both local and GitHub-synced issues.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Multi-source input**: GitHub URLs, text descriptions, structured input
|
||||
- **Clarity detection**: Asks questions only for vague inputs
|
||||
- **GitHub integration**: Optional publishing to GitHub with bidirectional sync
|
||||
- **Smart categorization**: Automatic tag and priority detection
|
||||
- **ACE integration**: Lightweight codebase context for affected components
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Clear inputs - direct creation (no questions)
|
||||
/issue:new https://github.com/owner/repo/issues/123
|
||||
/issue:new "Login fails with special chars. Expected: success. Actual: 500"
|
||||
|
||||
# Vague input - will ask 1 clarifying question
|
||||
/issue:new "something wrong with auth"
|
||||
|
||||
# With priority override
|
||||
/issue:new "Database connection times out" --priority 2
|
||||
|
||||
# Auto mode - skip confirmations
|
||||
/issue:new "Fix navigation bug" -y
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `input` | Yes | GitHub URL, issue description, or structured text |
|
||||
| `-y, --yes` | No | Skip confirmation questions |
|
||||
| `--priority <1-5>` | No | Override priority (1=critical, 5=low) |
|
||||
|
||||
## Examples
|
||||
|
||||
### Create from GitHub URL
|
||||
|
||||
```bash
|
||||
/issue:new https://github.com/owner/repo/issues/42
|
||||
# Output: Fetches issue details via gh CLI, creates immediately
|
||||
```
|
||||
|
||||
### Create with Structured Text
|
||||
|
||||
```bash
|
||||
/issue:new "Login fails with special chars. Expected: success. Actual: 500 error"
|
||||
# Output: Parses structure, creates issue with extracted fields
|
||||
```
|
||||
|
||||
### Create with Clarification
|
||||
|
||||
```bash
|
||||
/issue:new "auth broken"
|
||||
# System asks: "Please describe the issue in more detail:"
|
||||
# User provides: "Users cannot log in when password contains quotes"
|
||||
# Issue created with enriched context
|
||||
```
|
||||
|
||||
### Create with GitHub Publishing
|
||||
|
||||
```bash
|
||||
/issue:new "Memory leak in WebSocket handler"
|
||||
# System asks: "Would you like to publish to GitHub?"
|
||||
# User selects: "Yes, publish to GitHub"
|
||||
# Output:
|
||||
# Local issue: ISS-20251229-001
|
||||
# GitHub issue: https://github.com/org/repo/issues/123
|
||||
# Both linked bidirectionally
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Input Source] --> B{Clarity Score}
|
||||
B -->|Score 3: GitHub| C[Fetch via gh CLI]
|
||||
B -->|Score 2: Structured| D[Parse Text]
|
||||
B -->|Score 0-1: Vague| E[Ask 1 Question]
|
||||
C --> F[Create Issue]
|
||||
D --> F
|
||||
E --> F
|
||||
F --> G{Publish to GitHub?}
|
||||
G -->|Yes| H[Create + Link GitHub]
|
||||
G -->|No| I[Local Only]
|
||||
H --> J[issue:plan]
|
||||
I --> J
|
||||
```
|
||||
|
||||
## Issue Fields
|
||||
|
||||
### Core Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Issue ID (`GH-123` or `ISS-YYYYMMDD-NNN`) |
|
||||
| `title` | string | Issue title (max 60 chars) |
|
||||
| `status` | enum | `registered` | `planned` | `queued` | `in_progress` | `completed` | `failed` |
|
||||
| `priority` | number | 1 (critical) to 5 (low) |
|
||||
| `context` | string | Problem description (single source of truth) |
|
||||
| `source` | enum | `github` | `text` | `discovery` | `brainstorm` | `converted` |
|
||||
|
||||
### Optional Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `source_url` | string | Original source URL |
|
||||
| `labels` | string[] | Category tags |
|
||||
| `expected_behavior` | string | Expected system behavior |
|
||||
| `actual_behavior` | string | Actual problematic behavior |
|
||||
| `affected_components` | string[] | Related files/modules (via ACE) |
|
||||
| `github_url` | string | Linked GitHub issue URL |
|
||||
| `github_number` | number | GitHub issue number |
|
||||
| `feedback` | object[] | Failure history and clarifications |
|
||||
|
||||
### Feedback Schema
|
||||
|
||||
```typescript
|
||||
interface Feedback {
|
||||
type: 'failure' | 'clarification' | 'rejection';
|
||||
stage: 'new' | 'plan' | 'execute';
|
||||
content: string;
|
||||
created_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Clarity Detection
|
||||
|
||||
### Scoring Rules
|
||||
|
||||
| Score | Criteria | Behavior |
|
||||
|-------|----------|----------|
|
||||
| **3** | GitHub URL | Fetch directly, no questions |
|
||||
| **2** | Structured text (has "expected:", "actual:", etc.) | Parse structure, may use ACE for components |
|
||||
| **1** | Long text (>50 chars) | Quick ACE hint if components missing |
|
||||
| **0** | Vague/short text | Ask 1 clarifying question |
|
||||
|
||||
### Structured Text Patterns
|
||||
|
||||
The command recognizes these keywords for automatic parsing:
|
||||
- `expected:` / `Expected:`
|
||||
- `actual:` / `Actual:`
|
||||
- `affects:` / `Affects:`
|
||||
- `steps:` / `Steps:`
|
||||
|
||||
## GitHub Publishing Workflow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Command
|
||||
participant CLI
|
||||
participant GitHub
|
||||
|
||||
User->>Command: /issue:new "description"
|
||||
Command->>CLI: ccw issue create (local)
|
||||
CLI-->>Command: ISS-YYYYMMDD-NNN
|
||||
Command->>User: Publish to GitHub?
|
||||
User->>Command: Yes
|
||||
Command->>GitHub: gh issue create
|
||||
GitHub-->>Command: https://github.com/.../123
|
||||
Command->>CLI: ccw issue update --github-url --github-number
|
||||
CLI-->>Command: Issue updated
|
||||
Command-->>User: Local + GitHub linked
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[issue:plan](./issue-plan.md)** - Generate solution for issue
|
||||
- **[issue:queue](./issue-queue.md)** - Form execution queue
|
||||
- **[issue:discover](./issue-discover.md)** - Discover issues from codebase
|
||||
- **[issue:from-brainstorm](./issue-from-brainstorm.md)** - Convert brainstorm to issue
|
||||
- **[issue:convert-to-plan](./issue-convert-to-plan.md)** - Convert plans to issues
|
||||
- **[issue:execute](./issue-execute.md)** - Execute issue queue
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
The command uses these CLI endpoints:
|
||||
|
||||
```bash
|
||||
# Create issue
|
||||
echo '{"title":"...","context":"...","priority":3}' | ccw issue create
|
||||
|
||||
# Update with GitHub binding
|
||||
ccw issue update <id> --github-url "<url>" --github-number <num>
|
||||
|
||||
# View issue
|
||||
ccw issue status <id> --json
|
||||
```
|
||||
288
ccw/docs-site/docs/commands/issue/issue-plan.md
Normal file
288
ccw/docs-site/docs/commands/issue/issue-plan.md
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
title: issue:plan
|
||||
sidebar_label: issue:plan
|
||||
sidebar_position: 3
|
||||
description: Plan issue solutions with exploration and task breakdown
|
||||
---
|
||||
|
||||
# issue:plan
|
||||
|
||||
Batch plan issue resolution using intelligent agent-driven exploration and planning with failure-aware retry logic.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:plan` command uses the issue-plan-agent to combine exploration and planning into a single closed-loop workflow. It generates executable solutions with task breakdowns, handles previous failure analysis, and supports batch processing of up to 3 issues per agent.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Explore + Plan**: Combined workflow for faster planning
|
||||
- **Failure-aware**: Analyzes previous failures to avoid repeats
|
||||
- **Batch processing**: Groups semantically similar issues
|
||||
- **Auto-binding**: Single solutions automatically bound
|
||||
- **Conflict detection**: Identifies cross-issue file conflicts
|
||||
- **GitHub integration**: Adds GitHub comment tasks when applicable
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Plan all pending issues (default)
|
||||
/issue:plan
|
||||
|
||||
# Plan specific issues
|
||||
/issue:plan GH-123,GH-124,GH-125
|
||||
|
||||
# Plan single issue
|
||||
/issue:plan ISS-20251229-001
|
||||
|
||||
# Explicit all-pending
|
||||
/issue:plan --all-pending
|
||||
|
||||
# Custom batch size
|
||||
/issue:plan --batch-size 5
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `issue-ids` | No | Comma-separated issue IDs (default: all pending) |
|
||||
| `--all-pending` | No | Explicit flag for all pending issues |
|
||||
| `--batch-size <n>` | No | Max issues per batch (default: 3) |
|
||||
| `-y, --yes` | No | Auto-bind without confirmation |
|
||||
|
||||
## Examples
|
||||
|
||||
### Plan All Pending Issues
|
||||
|
||||
```bash
|
||||
/issue:plan
|
||||
# Output:
|
||||
# Found 5 pending issues
|
||||
# Processing 5 issues in 2 batch(es)
|
||||
# [Batch 1/2] Planning GH-123, GH-124, GH-125...
|
||||
# ✓ GH-123: SOL-GH-123-a7x9 (3 tasks)
|
||||
# ✓ GH-124: SOL-GH-124-b3m2 (4 tasks)
|
||||
# ✓ GH-125: SOL-GH-125-c8k1 (2 tasks)
|
||||
```
|
||||
|
||||
### Plan with Failure Retry
|
||||
|
||||
```bash
|
||||
/issue:plan ISS-20251229-001
|
||||
# Agent analyzes previous failure from issue.feedback
|
||||
# Avoids same approach that failed before
|
||||
# Creates alternative solution with verification steps
|
||||
```
|
||||
|
||||
### Multiple Solutions Selection
|
||||
|
||||
```bash
|
||||
/issue:plan GH-999
|
||||
# Agent generates 2 alternative solutions
|
||||
# Interactive prompt:
|
||||
# Issue GH-999: which solution to bind?
|
||||
# [1] SOL-GH-999-a1b2 (4 tasks) - Refactor approach
|
||||
# [2] SOL-GH-999-c3d4 (6 tasks) - Rewrite approach
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Issues to Plan] --> B[Load Issue Metadata]
|
||||
B --> C[Intelligent Grouping]
|
||||
C --> D[Launch Agents Parallel]
|
||||
D --> E1[Agent Batch 1]
|
||||
D --> E2[Agent Batch 2]
|
||||
E1{Analyze
|
||||
Failures?}
|
||||
E2{Analyze
|
||||
Failures?}
|
||||
E1 -->|Yes| F1[Extract Failure Patterns]
|
||||
E1 -->|No| G1[Explore Codebase]
|
||||
E2 -->|Yes| F2[Extract Failure Patterns]
|
||||
E2 -->|No| G2[Explore Codebase]
|
||||
F1 --> G1
|
||||
F2 --> G2
|
||||
G1 --> H1[Generate Solution]
|
||||
G2 --> H2[Generate Solution]
|
||||
H1 --> I{Single
|
||||
Solution?}
|
||||
H2 --> I
|
||||
I -->|Yes| J[Auto-Bind]
|
||||
I -->|No| K[User Selection]
|
||||
K --> L[Bind Selected]
|
||||
J --> M[Status: Planned]
|
||||
L --> M
|
||||
```
|
||||
|
||||
## Planning Workflow
|
||||
|
||||
### Phase 1: Issue Loading
|
||||
|
||||
```bash
|
||||
# Brief metadata only (to avoid context overflow)
|
||||
ccw issue list --status pending,registered --json
|
||||
```
|
||||
|
||||
**Returns**: Array of `{id, title, tags}`
|
||||
|
||||
### Phase 2: Agent Exploration (Parallel)
|
||||
|
||||
Each agent performs:
|
||||
|
||||
1. **Fetch full issue details**
|
||||
```bash
|
||||
ccw issue status <id> --json
|
||||
```
|
||||
|
||||
2. **Analyze failure history** (if exists)
|
||||
- Extract `issue.feedback` where `type='failure'`, `stage='execute'`
|
||||
- Parse error_type, message, task_id, solution_id
|
||||
- Identify repeated patterns and root causes
|
||||
- Design alternative approach
|
||||
|
||||
3. **Load project context**
|
||||
- `.workflow/project-tech.json` (technology stack)
|
||||
- `.workflow/project-guidelines.json` (constraints)
|
||||
|
||||
4. **Explore codebase** (ACE semantic search)
|
||||
|
||||
5. **Generate solution** (following solution-schema.json)
|
||||
- Tasks with quantified acceptance criteria
|
||||
- Verification steps to prevent same failure
|
||||
- Reference to previous failures in approach
|
||||
|
||||
6. **Write and bind**
|
||||
- Write to `solutions/{issue-id}.jsonl`
|
||||
- Execute `ccw issue bind <issue-id> <solution-id>` if single solution
|
||||
|
||||
### Phase 3: Solution Selection
|
||||
|
||||
Multiple solutions → User selects via AskUserQuestion
|
||||
|
||||
### Phase 4: Summary
|
||||
|
||||
```bash
|
||||
## Done: 5 issues → 5 planned
|
||||
|
||||
Bound Solutions:
|
||||
- GH-123: SOL-GH-123-a7x9 (3 tasks)
|
||||
- GH-124: SOL-GH-124-b3m2 (4 tasks)
|
||||
- ISS-20251229-001: SOL-ISS-20251229-001-c8k1 (2 tasks)
|
||||
|
||||
Next: /issue:queue
|
||||
```
|
||||
|
||||
## Failure-Aware Planning
|
||||
|
||||
### Feedback Schema
|
||||
|
||||
```typescript
|
||||
interface FailureFeedback {
|
||||
type: 'failure';
|
||||
stage: 'execute';
|
||||
content: {
|
||||
task_id: string;
|
||||
solution_id: string;
|
||||
error_type: 'test_failure' | 'compilation' | 'timeout' | 'runtime_error';
|
||||
message: string;
|
||||
timestamp: string;
|
||||
};
|
||||
created_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Failure Analysis Rules
|
||||
|
||||
1. **Extract patterns**: Repeated errors indicate systemic issues
|
||||
2. **Identify root cause**: Test failure vs. compilation vs. timeout
|
||||
3. **Design alternative**: Change approach, not just implementation
|
||||
4. **Add prevention**: Explicit verification steps for same error
|
||||
5. **Document lessons**: Reference failures in solution.approach
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
### Issue Operations
|
||||
|
||||
```bash
|
||||
# List pending issues (brief)
|
||||
ccw issue list --status pending --brief
|
||||
|
||||
# Get full issue details (agent use)
|
||||
ccw issue status <id> --json
|
||||
|
||||
# Bind solution to issue
|
||||
ccw issue bind <issue-id> <solution-id>
|
||||
|
||||
# List with bound solutions
|
||||
ccw issue solutions --status planned --brief
|
||||
```
|
||||
|
||||
### Solution Schema
|
||||
|
||||
```typescript
|
||||
interface Solution {
|
||||
id: string; // SOL-{issue-id}-{4-char-uid}
|
||||
description: string;
|
||||
approach: string;
|
||||
tasks: Task[];
|
||||
exploration_context: {
|
||||
relevant_files: string[];
|
||||
dependencies: string[];
|
||||
patterns: string[];
|
||||
};
|
||||
failure_analysis?: {
|
||||
previous_failures: string[];
|
||||
alternative_approach: string;
|
||||
prevention_steps: string[];
|
||||
};
|
||||
is_bound: boolean;
|
||||
created_at: string;
|
||||
bound_at?: string;
|
||||
}
|
||||
|
||||
interface Task {
|
||||
id: string; // T1, T2, T3...
|
||||
title: string;
|
||||
scope: string;
|
||||
action: string;
|
||||
implementation: string[];
|
||||
acceptance: {
|
||||
criteria: string[];
|
||||
verification: string[];
|
||||
};
|
||||
test?: {
|
||||
unit?: string[];
|
||||
integration?: string[];
|
||||
commands?: string[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[issue:new](./issue-new.md)** - Create issues before planning
|
||||
- **[issue:queue](./issue-queue.md)** - Form execution queue from planned issues
|
||||
- **[issue:execute](./issue-execute.md)** - Execute planned solutions
|
||||
- **[issue:from-brainstorm](./issue-from-brainstorm.md)** - Convert brainstorm to planned issue
|
||||
- **[issue:convert-to-plan](./issue-convert-to-plan.md)** - Convert existing plans to issues
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Plan in batches**: Default 3 issues per batch for optimal performance
|
||||
2. **Review failures**: Check issue feedback before replanning
|
||||
3. **Verify conflicts**: Agent reports file conflicts across issues
|
||||
4. **GitHub issues**: Agent adds final task to comment on GitHub issue
|
||||
5. **Acceptance criteria**: Ensure tasks have quantified success metrics
|
||||
6. **Test coverage**: Each task should include verification steps
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| No pending issues | All issues already planned | Create new issues or use --all-pending flag |
|
||||
| Agent timeout | Large codebase exploration | Reduce batch size or limit scope |
|
||||
| No solutions generated | Insufficient context | Provide more detailed issue description |
|
||||
| Solution conflicts | Multiple issues touch same files | Agent reports conflicts, resolve manually |
|
||||
| Bind failure | Solution file write error | Check permissions, retry |
|
||||
372
ccw/docs-site/docs/commands/issue/issue-queue.md
Normal file
372
ccw/docs-site/docs/commands/issue/issue-queue.md
Normal file
@@ -0,0 +1,372 @@
|
||||
---
|
||||
title: issue:queue
|
||||
sidebar_label: issue:queue
|
||||
sidebar_position: 4
|
||||
description: Form execution queue from bound solutions with conflict resolution
|
||||
---
|
||||
|
||||
# issue:queue
|
||||
|
||||
Queue formation command using issue-queue-agent that analyzes bound solutions, resolves inter-solution conflicts, and creates an ordered execution queue.
|
||||
|
||||
## Description
|
||||
|
||||
The `issue:queue` command creates execution queues from planned issues with bound solutions. It performs solution-level conflict analysis, builds dependency DAGs, calculates semantic priority, and assigns execution groups (parallel/sequential).
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Solution-level granularity**: Queue items are complete solutions, not individual tasks
|
||||
- **Conflict resolution**: Automatic detection and user clarification for high-severity conflicts
|
||||
- **Multi-queue support**: Create parallel queues for distributed execution
|
||||
- **Semantic priority**: Intelligent ordering based on issue priority and task complexity
|
||||
- **DAG-based grouping**: Parallel (P*) and Sequential (S*) execution groups
|
||||
- **Queue history**: Track all queues with active queue management
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Form new queue from all bound solutions
|
||||
/issue:queue
|
||||
|
||||
# Form 3 parallel queues (solutions distributed)
|
||||
/issue:queue --queues 3
|
||||
|
||||
# Form queue for specific issue only
|
||||
/issue:queue --issue GH-123
|
||||
|
||||
# Append to active queue
|
||||
/issue:queue --append GH-124
|
||||
|
||||
# List all queues
|
||||
/issue:queue --list
|
||||
|
||||
# Switch active queue
|
||||
/issue:queue --switch QUE-xxx
|
||||
|
||||
# Archive completed queue
|
||||
/issue:queue --archive
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--queues <n>` | No | Number of parallel queues (default: 1) |
|
||||
| `--issue <id>` | No | Form queue for specific issue only |
|
||||
| `--append <id>` | No | Append issue to active queue |
|
||||
| `--force` | No | Skip active queue check, always create new |
|
||||
| `-y, --yes` | No | Auto-confirm, use recommended resolutions |
|
||||
|
||||
### CLI Subcommands
|
||||
|
||||
```bash
|
||||
ccw issue queue list # List all queues with status
|
||||
ccw issue queue add <issue-id> # Add issue to queue
|
||||
ccw issue queue add <issue-id> -f # Force add to new queue
|
||||
ccw issue queue merge <src> --queue <target> # Merge queues
|
||||
ccw issue queue switch <queue-id> # Switch active queue
|
||||
ccw issue queue archive # Archive current queue
|
||||
ccw issue queue delete <queue-id> # Delete queue from history
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Create Single Queue
|
||||
|
||||
```bash
|
||||
/issue:queue
|
||||
# Output:
|
||||
# Loading 5 bound solutions...
|
||||
# Generating queue: QUE-20251227-143000
|
||||
# Analyzing conflicts...
|
||||
# ✓ Queue created: 5 solutions, 3 execution groups
|
||||
# - P1: S-1, S-2 (parallel)
|
||||
# - S1: S-3 (sequential)
|
||||
# - P2: S-4, S-5 (parallel)
|
||||
# Next: /issue:execute --queue QUE-20251227-143000
|
||||
```
|
||||
|
||||
### Create Multiple Parallel Queues
|
||||
|
||||
```bash
|
||||
/issue:queue --queues 3
|
||||
# Distributes solutions to minimize cross-queue conflicts
|
||||
# Creates: QUE-20251227-143000-1, QUE-20251227-143000-2, QUE-20251227-143000-3
|
||||
# All linked via queue_group: QGR-20251227-143000
|
||||
```
|
||||
|
||||
### Append to Existing Queue
|
||||
|
||||
```bash
|
||||
/issue:queue --append GH-124
|
||||
# Checks active queue exists
|
||||
# Adds new solution to end of active queue
|
||||
# Recalculates execution groups
|
||||
```
|
||||
|
||||
## Issue Lifecycle Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Planned Issues + Bound Solutions] --> B[Load Solutions]
|
||||
B --> C{Multi-Queue?}
|
||||
C -->|Yes| D[Partition Solutions]
|
||||
C -->|No| E[Single Queue]
|
||||
D --> F[Launch N Agents Parallel]
|
||||
E --> G[Launch Agent]
|
||||
F --> H[Conflict Analysis]
|
||||
G --> H
|
||||
H --> I{High-Severity
|
||||
Conflicts?}
|
||||
I -->|Yes| J[User Clarification]
|
||||
I -->|No| K[Build DAG]
|
||||
J --> K
|
||||
K --> L[Calculate Priority]
|
||||
L --> M[Assign Groups]
|
||||
M --> N[Write Queue + Index]
|
||||
N --> O{Active Queue
|
||||
Exists?}
|
||||
O -->|No| P[Activate New Queue]
|
||||
O -->|Yes| Q[User Decision]
|
||||
Q --> R1[Merge]
|
||||
Q --> R2[Switch]
|
||||
Q --> R3[Cancel]
|
||||
R1 --> S[Queue Ready]
|
||||
R2 --> S
|
||||
P --> S
|
||||
```
|
||||
|
||||
## Execution Groups
|
||||
|
||||
### Parallel Groups (P*)
|
||||
|
||||
Solutions with NO file conflicts can execute simultaneously:
|
||||
|
||||
```
|
||||
P1: S-1, S-2, S-3 → 3 executors work in parallel
|
||||
```
|
||||
|
||||
### Sequential Groups (S*)
|
||||
|
||||
Solutions with shared dependencies must execute in order:
|
||||
|
||||
```
|
||||
S1: S-4 → S-5 → S-6 → Execute one after another
|
||||
```
|
||||
|
||||
### Mixed Execution
|
||||
|
||||
```
|
||||
P1: S-1, S-2 (parallel)
|
||||
↓
|
||||
S1: S-3 (sequential, waits for P1)
|
||||
↓
|
||||
P2: S-4, S-5 (parallel, waits for S1)
|
||||
```
|
||||
|
||||
## Conflict Types
|
||||
|
||||
### 1. File Conflicts
|
||||
|
||||
Solutions modify the same file:
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_id": "CFT-1",
|
||||
"type": "file",
|
||||
"severity": "high",
|
||||
"solutions": ["S-1", "S-2"],
|
||||
"files": ["src/auth/login.ts"],
|
||||
"resolution": "sequential"
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution**: S-1 before S-2 in sequential group
|
||||
|
||||
### 2. API Conflicts
|
||||
|
||||
Solutions change shared interfaces:
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_id": "CFT-2",
|
||||
"type": "api",
|
||||
"severity": "high",
|
||||
"solutions": ["S-3", "S-4"],
|
||||
"interfaces": ["AuthService.login()"],
|
||||
"resolution": "sequential"
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution**: User clarifies which approach to use
|
||||
|
||||
### 3. Data Conflicts
|
||||
|
||||
Solutions modify same database schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_id": "CFT-3",
|
||||
"type": "data",
|
||||
"severity": "medium",
|
||||
"solutions": ["S-5", "S-6"],
|
||||
"tables": ["users"],
|
||||
"resolution": "sequential"
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution**: S-5 before S-6
|
||||
|
||||
### 4. Dependency Conflicts
|
||||
|
||||
Solutions require incompatible versions:
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_id": "CFT-4",
|
||||
"type": "dependency",
|
||||
"severity": "high",
|
||||
"solutions": ["S-7", "S-8"],
|
||||
"packages": ["redis@4.x vs 5.x"],
|
||||
"resolution": "clarification"
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution**: User selects version or defers one solution
|
||||
|
||||
### 5. Architecture Conflicts
|
||||
|
||||
Solutions have opposing architectural approaches:
|
||||
|
||||
```json
|
||||
{
|
||||
"conflict_id": "CFT-5",
|
||||
"type": "architecture",
|
||||
"severity": "medium",
|
||||
"solutions": ["S-9", "S-10"],
|
||||
"approaches": ["monolithic", "microservice"],
|
||||
"resolution": "clarification"
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution**: User selects approach or separates concerns
|
||||
|
||||
## Queue Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
.workflow/issues/queues/
|
||||
├── index.json # Queue index (active + history)
|
||||
├── QUE-20251227-143000.json # Individual queue file
|
||||
├── QUE-20251227-143000-1.json # Multi-queue partition 1
|
||||
├── QUE-20251227-143000-2.json # Multi-queue partition 2
|
||||
└── QUE-20251227-143000-3.json # Multi-queue partition 3
|
||||
```
|
||||
|
||||
### Index Schema
|
||||
|
||||
```typescript
|
||||
interface QueueIndex {
|
||||
active_queue_id: string | null;
|
||||
active_queue_group: string | null;
|
||||
queues: QueueEntry[];
|
||||
}
|
||||
|
||||
interface QueueEntry {
|
||||
id: string;
|
||||
queue_group?: string; // Links multi-queue partitions
|
||||
queue_index?: number; // Position in group (1-based)
|
||||
total_queues?: number; // Total queues in group
|
||||
status: 'active' | 'archived' | 'deleted';
|
||||
issue_ids: string[];
|
||||
total_solutions: number;
|
||||
completed_solutions: number;
|
||||
created_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Queue File Schema
|
||||
|
||||
```typescript
|
||||
interface Queue {
|
||||
queue_id: string;
|
||||
queue_group?: string;
|
||||
solutions: QueueSolution[];
|
||||
execution_groups: ExecutionGroup[];
|
||||
conflicts: Conflict[];
|
||||
priority_order: string[];
|
||||
created_at: string;
|
||||
}
|
||||
|
||||
interface QueueSolution {
|
||||
item_id: string; // S-1, S-2, S-3...
|
||||
issue_id: string;
|
||||
solution_id: string;
|
||||
status: 'pending' | 'in_progress' | 'completed' | 'failed';
|
||||
task_count: number;
|
||||
files_touched: string[];
|
||||
priority_score: number;
|
||||
}
|
||||
|
||||
interface ExecutionGroup {
|
||||
id: string; // P1, S1, P2...
|
||||
type: 'parallel' | 'sequential';
|
||||
items: string[]; // S-1, S-2...
|
||||
}
|
||||
```
|
||||
|
||||
## Clarification Flow
|
||||
|
||||
When high-severity conflicts exist without clear resolution:
|
||||
|
||||
```bash
|
||||
# Interactive prompt
|
||||
[CFT-5] File conflict: src/auth/login.ts modified by both S-1 and S-2
|
||||
Options:
|
||||
[1] Sequential: Execute S-1 first, then S-2
|
||||
[2] Sequential: Execute S-2 first, then S-1
|
||||
[3] Merge: Combine changes into single solution
|
||||
[4] Defer: Remove one solution from queue
|
||||
|
||||
User selects: [1]
|
||||
|
||||
# Agent resumes with resolution
|
||||
# Updates queue with sequential ordering: S1: [S-1, S-2]
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- **[issue:plan](./issue-plan.md)** - Plan solutions before queuing
|
||||
- **[issue:execute](./issue-execute.md)** - Execute queued solutions
|
||||
- **[issue:new](./issue-new.md)** - Create issues to plan and queue
|
||||
- **ccw issue queue dag** - View dependency graph
|
||||
- **ccw issue next** - Get next item from queue
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Plan before queue**: Ensure all issues have bound solutions
|
||||
2. **Review conflicts**: Check conflict report before execution
|
||||
3. **Use parallel queues**: For large projects, distribute work
|
||||
4. **Archive completed**: Keep queue history for reference
|
||||
5. **Check unplanned**: Review planned but unqueued issues
|
||||
6. **Validate DAG**: Ensure no circular dependencies
|
||||
|
||||
## CLI Endpoints
|
||||
|
||||
```bash
|
||||
# List planned issues with bound solutions
|
||||
ccw issue solutions --status planned --brief
|
||||
|
||||
# Create/update queue
|
||||
ccw issue queue form
|
||||
|
||||
# Sync issue statuses from queue
|
||||
ccw issue update --from-queue [queue-id]
|
||||
|
||||
# View queue DAG
|
||||
ccw issue queue dag --queue <queue-id>
|
||||
|
||||
# Get next item
|
||||
ccw issue next --queue <queue-id>
|
||||
```
|
||||
Reference in New Issue
Block a user