feat(docs): enhance issue planning and queue documentation with new guidelines and commands

.codex/prompts/issue-plan.md

@@ -11,6 +11,23 @@ Create executable solution(s) for issue(s) and bind the selected solution to eac
 
 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`).
 
+## Core Guidelines
+
+**⚠️ Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow:
+
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` |
+| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
+| 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`
@@ -91,10 +108,38 @@ ccw issue solution <issue-id> --data '{"description":"...", "approach":"...", "t
 ### Step 6: Detect cross-issue file conflicts (best-effort)
 
 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).
+- 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.
 
+### Step 7: Update issue status
+
+After binding, update issue status to `planned`:
+```bash
+ccw issue update <issue-id> --status planned
+```
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] All input issues have solutions in `solutions/{issue-id}.jsonl`
+- [ ] Single solution issues are auto-bound (`bound_solution_id` set)
+- [ ] Multi-solution issues returned in `pending_selection` for user choice
+- [ ] Each solution has executable tasks with `modification_points`
+- [ ] Task acceptance criteria are quantified (not vague)
+- [ ] Conflicts detected and reported (if multiple issues touch same files)
+- [ ] Issue status updated to `planned` after binding
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Issue not found | Auto-create via `ccw issue init` |
+| 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
 
 - A bound solution exists for each issue unless explicitly deferred for user selection.

.codex/prompts/issue-queue.md

@@ -1,6 +1,6 @@
 ---
 description: Form execution queue from bound solutions (orders solutions, detects conflicts, assigns groups)
-argument-hint: "[--issue <id>]"
+argument-hint: "[--issue <id>] [--append <id>]"
 ---
 
 # Issue Queue (Codex Version)
@@ -11,10 +11,32 @@ Create an ordered execution queue from all bound solutions. Analyze inter-soluti
 
 This workflow is **ordering only** (no execution): it reads bound solutions, detects conflicts, and produces a queue file that `issue-execute.md` can consume.
 
+**Design Principle**: Queue items are **solutions**, not individual tasks. Each executor receives a complete solution with all its tasks.
+
+## Core Guidelines
+
+**⚠️ Data Access Principle**: Issues and queue files can grow very large. To avoid context overflow:
+
+| Operation | Correct | Incorrect |
+|-----------|---------|-----------|
+| List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` |
+| List queue (brief) | `ccw issue queue --brief` | `Read('queues/*.json')` |
+| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
+| Get next item | `ccw issue next --json` | `Read('queues/*.json')` |
+| Update status | `ccw issue update <id> --status ...` | Direct file edit |
+| Sync from queue | `ccw issue update --from-queue` | Direct file edit |
+
+**Output Options**:
+- `--brief`: JSON with minimal fields (id, status, counts)
+- `--json`: Full JSON (for detailed processing)
+
+**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `queues/*.json` directly.
+
 ## Inputs
 
 - **All planned**: Default behavior → queue all issues with `planned` status and bound solutions
 - **Specific issue**: `--issue <id>` → queue only that issue's solution
+- **Append mode**: `--append <id>` → append issue to active queue (don't create new)
 
 ## Output Requirements
 
@@ -176,18 +198,27 @@ Group assignment:
 
 ### Step 7: Update Issue Statuses
 
-For each queued issue, update status to `queued`:
+**MUST use CLI command** (NOT direct file operations):
 
 ```bash
+# Option 1: Batch update from queue (recommended)
+ccw issue update --from-queue              # Use active queue
+ccw issue update --from-queue QUE-xxx      # Use specific queue
+
+# Option 2: Individual issue update
 ccw issue update <issue-id> --status queued
 ```
 
+**⚠️ IMPORTANT**: Do NOT directly modify `issues.jsonl`. Always use CLI command to ensure proper validation and history tracking.
+
 ## Queue Item ID Format
 
 - Solution items: `S-1`, `S-2`, `S-3`, ...
 - Sequential numbering starting from 1
 
-## Done Criteria
+## Quality Checklist
+
+Before completing, verify:
 
 - [ ] Exactly 2 files generated: queue JSON + index update
 - [ ] Queue has valid DAG (no circular dependencies)
@@ -212,6 +243,16 @@ ccw issue update <issue-id> --status queued
 | Circular dependency detected | Abort, report cycle details |
 | Missing solution file | Skip issue, log warning |
 | Index file missing | Create new index |
+| Index not updated | Auto-fix: Set active_queue_id to new queue |
+
+## Done Criteria
+
+- [ ] All planned issues with `bound_solution_id` are included
+- [ ] Queue JSON written to `queues/{queue-id}.json`
+- [ ] Index updated in `queues/index.json` with `active_queue_id`
+- [ ] No circular dependencies in solution DAG
+- [ ] Parallel groups have no file overlaps
+- [ ] Issue statuses updated to `queued`
 
 ## Start Execution
 
@@ -222,3 +263,4 @@ ccw issue list --status planned --json
 ```
 
 Then follow the workflow to generate the queue.
+