cokit-cli 1.2.4 → 1.2.7

package/templates/repo/.github/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Review code quality, receive feedback with technical rigor, verify completion claims. Use before PRs, after implementing features, when claiming task completion, for agent reviews.
+description: Review code quality, receive feedback with technical rigor, verify completion claims. Includes edge case scouting for multi-file features. Use before PRs, after implementing features, when claiming task completion, for agent reviews.
 ---
 
 # Code Review
@@ -9,13 +9,12 @@ Guide proper code review practices emphasizing technical rigor, evidence-based c
 
 ## Overview
 
-Code review requires three distinct practices:
-
-1. **Receiving feedback** - Technical evaluation over performative agreement
-2. **Requesting reviews** - Systematic review via code-reviewer agent
-3. **Verification gates** - Evidence before any completion claims
-
-Each practice has specific triggers and protocols detailed in reference files.
+| Practice | When | Protocol |
+|----------|------|----------|
+| **Edge Case Scouting** | Before any review on 3+ file features | `/ck-scout` for hidden paths and untested scenarios |
+| **Receiving Feedback** | Feedback from human or agent | READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT |
+| **Requesting Reviews** | After each task, before merge, after major features | Delegate to `code-reviewer` agent |
+| **Verification Gates** | Before any completion claim | Run command, read output, then claim |
 
 ## Core Principle
 
@@ -26,6 +25,15 @@ Always honoring **YAGNI**, **KISS**, and **DRY** principles.
 
 ## When to Use This Skill
 
+### Edge Case Scouting
+Trigger when:
+- Feature touches 3+ files
+- Implementing complex business logic
+- Before requesting formal code review
+- After implementation, before testing
+
+**Reference:** `references/requesting-code-review.md`
+
 ### Receiving Feedback
 Trigger when:
 - Receiving code review comments from any source
@@ -61,35 +69,74 @@ Trigger when:
 ```
 SITUATION?
 │
+├─ Multi-file feature (3+ files)?
+│  └─ Run edge case scouting first → /ck-scout then request review
+│
 ├─ Received feedback
 │  ├─ Unclear items? → STOP, ask for clarification first
 │  ├─ From human partner? → Understand, then implement
 │  └─ From external reviewer? → Verify technically before implementing
 │
 ├─ Completed work
-│  ├─ Major feature/task? → Request code-reviewer agent review
-│  └─ Before merge? → Request code-reviewer agent review
+│  ├─ Major feature/task? → Request `code-reviewer` agent review
+│  └─ Before merge? → Request `code-reviewer` agent review
 │
 └─ About to claim status
    ├─ Have fresh verification? → State claim WITH evidence
    └─ No fresh verification? → RUN verification command first
 ```
 
+## Edge Case Scouting
+
+### When to Scout
+Before formal review of any multi-file feature (3+ files changed).
+
+### Process
+1. Use `/ck-scout` to search for hidden code paths, edge inputs, error branches
+2. Document untested scenarios found
+3. Add tests or guards for critical edge cases
+4. Then proceed to formal `code-reviewer` review
+
+### What to Look For
+- Null/undefined paths not covered by tests
+- Error branches lacking handlers
+- Boundary conditions (empty arrays, max values, concurrent calls)
+- Async race conditions
+- Permission/auth edge cases
+
+## Task-Managed Review Pipeline (Multi-File Features)
+
+For features spanning 3+ files, use a structured pipeline:
+
+```
+scout → review → fix → verify
+```
+
+**Steps:**
+1. **Scout** - Use `/ck-scout` or `/ck-scout ext` to identify edge cases and gaps
+2. **Review** - Delegate to `code-reviewer` agent with full context
+3. **Fix** - Implement critical and important feedback
+4. **Verify** - Run tests, confirm fixes, then claim completion
+
+Track progress using a checklist in your plan or task notes:
+```
+- [ ] Edge case scouting complete
+- [ ] `code-reviewer` review complete
+- [ ] Critical issues fixed
+- [ ] Verification passed
+```
+
 ## Receiving Feedback Protocol
 
 ### Response Pattern
 READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
 
 ### Key Rules
-- ❌ No performative agreement: "You're absolutely right!", "Great point!", "Thanks for [anything]"
-- ❌ No implementation before verification
-- ✅ Restate requirement, ask questions, push back with technical reasoning, or just start working
-- ✅ If unclear: STOP and ask for clarification on ALL unclear items first
-- ✅ YAGNI check: grep for usage before implementing suggested "proper" features
-
-### Source Handling
-- **Human partner:** Trusted - implement after understanding, no performative agreement
-- **External reviewers:** Verify technically correct, check for breakage, push back if wrong
+- No performative agreement: "You're absolutely right!", "Great point!", "Thanks for [anything]"
+- No implementation before verification
+- Restate requirement, ask questions, push back with technical reasoning, or just start working
+- If unclear: STOP and ask for clarification on ALL unclear items first
+- YAGNI check: search for usage before implementing suggested "proper" features
 
 **Full protocol:** `references/code-review-reception.md`
 
@@ -101,9 +148,10 @@ READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
 - Before merge to main
 
 ### Process
-1. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
-2. Delegate to code-reviewer agent with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
-3. Act on feedback: Fix Critical immediately, Important before proceeding, note Minor for later
+1. Scout edge cases (3+ file features): use `/ck-scout` first
+2. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
+3. Delegate to `code-reviewer` agent with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
+4. Act on feedback: Fix Critical immediately, Important before proceeding, note Minor for later
 
 **Full protocol:** `references/requesting-code-review.md`
 
@@ -130,14 +178,16 @@ Using "should"/"probably"/"seems to", expressing satisfaction before verificatio
 
 ## Integration with Workflows
 
-- **Agent-Driven:** Review after EACH task, verify before moving to next
-- **Pull Requests:** Verify tests pass, request code-reviewer review before merge
+- **Agent-Driven:** Scout edge cases first (3+ files), review after EACH task, verify before moving to next
+- **Pull Requests:** Scout → verify tests pass → request `code-reviewer` review before merge
 - **General:** Apply verification gates before any status claims, push back on invalid feedback
+- **Pipeline:** For complex features use the full `scout → review → fix → verify` pipeline
 
 ## Bottom Line
 
-1. Technical rigor over social performance - No performative agreement
-2. Systematic review processes - Use code-reviewer agent
-3. Evidence before claims - Verification gates always
+1. **Scout first** - Edge cases found before review save rework cycles
+2. Technical rigor over social performance - No performative agreement
+3. Systematic review processes - Use `code-reviewer` agent via pipeline
+4. Evidence before claims - Verification gates always
 
-Verify. Question. Then implement. Evidence. Then claim.
+Scout. Verify. Question. Then implement. Evidence. Then claim.

package/templates/repo/.github/skills/cook/SKILL.md

@@ -15,12 +15,13 @@ End-to-end implementation with automatic workflow detection.
 /cook <natural language task OR plan path>
 ```
 
-**Optional flags:** `--fast`, `--parallel`, `--no-test`, `--auto`
+**Optional flags:** `--fast`, `--parallel`, `--no-test`, `--auto`, `--interactive`
 
 Example:
 ```
 /cook "Add user authentication to the app" --fast
 /cook path/to/plan.md --auto
+/cook "Fix login bug" --interactive
 ```
 
 ## Smart Intent Detection
@@ -32,6 +33,7 @@ Example:
 | Contains "trust me", "auto" | auto | Auto-approve all steps |
 | Lists 3+ features OR "parallel" | parallel | Multi-agent execution |
 | Contains "no test", "skip test" | no-test | Skip testing step |
+| `--interactive` flag (explicit) | interactive | Full workflow with user input |
 | Default | interactive | Full workflow with user input |
 
 See `references/intent-detection.md` for detection logic.
@@ -71,19 +73,51 @@ Human review required at these checkpoints (skipped with `--auto`):
 **Always enforced (all modes):**
 - **Testing:** 100% pass required (unless no-test mode)
 - **Code Review:** User approval OR auto-approve (score≥9.5, 0 critical)
-- **Finalize:** project-manager AND docs-manager must complete
+- **Finalize:** docs-manager MUST complete
 
 ## Required Agents
 
-| Phase | Agent |
-|-------|----------|
-| Research | `researcher` (parallel, optional in fast) |
-| Scout | `scout` |
-| Plan | `planner` |
-| UI Work | `ui-ux-designer` |
-| Testing | `tester`, `debugger` |
-| Review | `code-reviewer` |
-| Finalize | `project-manager`, `docs-manager`, `git-manager` |
+| Phase | Agent | Requirement |
+|-------|-------|-------------|
+| Research | `researcher` agent (parallel, optional in fast) | Spawn as needed |
+| Scout | `scout` agent | Spawn for codebase search |
+| Plan | `planner` agent | MUST spawn |
+| UI Work | `ui-ux-designer` agent | Spawn when frontend work exists |
+| Testing | `tester`, `debugger` agents | MUST spawn |
+| Review | `code-reviewer` agent | MUST spawn |
+| Finalize | `docs-manager`, `git-manager` agents | MUST spawn |
+
+## Implementation Progress Tracking
+
+During Step 3 (Implementation), track progress using a todo list/checklist in the active plan or phase file:
+
+```
+- [ ] Phase 1: Setup environment
+- [ ] Phase 2: Database models
+- [ ] Phase 3: API endpoints
+- [ ] Phase 4: UI components
+```
+
+Update each item as completed. This replaces task management tooling with simple markdown tracking visible in the plan.
+
+## CRITICAL ENFORCEMENT
+
+**Steps 4 (Testing), 5 (Code Review), and 6 (Finalize) MUST delegate to agents. DO NOT implement testing, review, or finalization yourself.**
+
+- Step 4: Always delegate to `tester` agent. If failures, delegate to `debugger` agent, then re-delegate to `tester`.
+- Step 5: Always delegate to `code-reviewer` agent. Never self-review.
+- Step 6: Always delegate to `docs-manager` agent for doc updates.
+
+## Finalize Step (MANDATORY)
+
+Step 6 is not optional. All four actions MUST complete:
+
+1. Update plan/phase status to completed in plan files
+2. Delegate to `docs-manager` agent → review and update `./docs` if implementation changed APIs, architecture, or behavior
+3. Mark all todo checklist items complete in the active plan
+4. Ask the user: "Would you like to commit these changes via `git-manager` agent?"
+
+**Never skip finalize**, even in fast or auto mode.
 
 ## References
 

package/templates/repo/.github/skills/debug/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: debug
-description: Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation.
-languages: all
+description: Debug systematically with root cause analysis before fixes. Covers bugs, test failures, log analysis, CI/CD failures, database diagnostics, system investigation, performance issues, call stack tracing, multi-layer validation.
 ---
 
-# Debugging
+# Debugging & System Investigation
 
-Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
+Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, verification protocols, and system-level diagnostics.
 
 ## Core Principle
 
@@ -16,29 +15,29 @@ Random fixes waste time and create new bugs. Find the root cause, fix at source,
 
 ## When to Use
 
-**Always use for:** Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
+**Code-level:** Test failures, bugs, unexpected behavior, build failures, integration problems, before claiming work complete
+
+**System-level:** CI/CD pipeline failures, log analysis, database diagnostics, performance bottlenecks, infrastructure issues
 
 **Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
 
-## The Four Techniques
+## Techniques
 
 ### 1. Systematic Debugging (`references/systematic-debugging.md`)
 
-Four-phase framework ensuring proper investigation:
+Four-phase framework:
 - Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
 - Phase 2: Pattern Analysis (find working examples, compare, identify differences)
 - Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
 - Phase 4: Implementation (create test, fix once, verify)
 
-**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.
+Complete each phase before proceeding. No fixes without Phase 1.
 
 **Load when:** Any bug/issue requiring investigation and fix
 
 ### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
 
-Trace bugs backward through call stack to find original trigger.
-
-**Technique:** When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
+Trace bugs backward through call stack to find original trigger. Fix at source, not at symptom.
 
 **Includes:** `scripts/find-polluter.sh` for bisecting test pollution
 
@@ -46,9 +45,7 @@ Trace bugs backward through call stack to find original trigger.
 
 ### 3. Defense-in-Depth (`references/defense-in-depth.md`)
 
-Validate at every layer data passes through. Make bugs impossible.
-
-**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation
+Validate at every layer data passes through. Four layers: Entry validation → Business logic → Environment guards → Debug instrumentation
 
 **Load when:** After finding root cause, need to add comprehensive validation
 
@@ -58,19 +55,117 @@ Run verification commands and confirm output before claiming success.
 
 **Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
 
-Run the command. Read the output. Then claim the result.
-
 **Load when:** About to claim work complete, fixed, or passing
 
+### 5. Investigation Methodology
+
+For system-level issues (CI/CD, infrastructure, data pipeline):
+
+1. **Scope** - Define what is broken and what is working
+2. **Gather** - Collect logs, metrics, error outputs before touching anything
+3. **Isolate** - Narrow to smallest reproducible case
+4. **Hypothesize** - Form one theory, test it, reject or confirm
+5. **Fix & Validate** - Fix at root, verify at every affected layer
+
+**Load when:** Issue is not code-local — spans services, environments, or pipelines
+
+### 6. Log & CI/CD Analysis
+
+Use `gh` CLI and structured queries to diagnose pipeline failures:
+
+```bash
+# View failed CI run logs
+gh run view <run-id> --log-failed
+
+# List recent runs for a workflow
+gh run list --workflow=<name> --limit 10
+
+# Watch a running workflow
+gh run watch <run-id>
+```
+
+For structured logs: filter by severity, timestamp range, and correlation ID before reading raw output.
+
+**Load when:** CI/CD failure, deployment issue, or log-driven investigation
+
+### 7. Performance Diagnostics
+
+Identify bottlenecks before optimizing:
+- Profile first — measure before guessing
+- Check slow queries with `EXPLAIN ANALYZE` (PostgreSQL) or equivalent
+- Identify N+1 query patterns in ORM usage
+- Check memory allocation patterns for leaks
+- Use `psql` for live database diagnostics
+
+**Load when:** Slowness reported, timeout errors, resource exhaustion
+
+### 8. Reporting Standards
+
+For multi-component investigations, write a structured diagnostic report:
+
+```
+## Diagnostic Report
+- **Issue:** [one-line description]
+- **Root Cause:** [where and why it fails]
+- **Evidence:** [logs, output, reproduction steps]
+- **Fix Applied:** [what was changed]
+- **Verification:** [command run + result]
+- **Remaining Risk:** [any open questions]
+```
+
+Save to `plans/reports/debugger-{date}-{slug}.md`.
+
+**Load when:** Investigation spans multiple components or will be shared with others
+
+### 9. Task Management
+
+For multi-component investigations, track progress with a checklist rather than holding state mentally:
+
+```
+- [ ] Reproduce the issue
+- [ ] Identify root cause
+- [ ] Fix applied
+- [ ] Tests passing
+- [ ] Verification complete
+```
+
+Add this checklist to the active plan or investigation report. Check items off as each step completes.
+
+**Load when:** Investigation touches 3+ components or files
+
+### 10. Frontend Verification
+
+For visual bugs or UI regressions, use browser developer tools (or the `agent-browser` skill) to inspect rendering, network, and console errors directly in the browser.
+
+Use `/ck-scout ext` to search for frontend-specific patterns before diving into devtools.
+
+**Load when:** Visual regression, layout bug, client-side network error, or UI behavior that differs from expected
+
 ## Quick Reference
 
 ```
-Bug → systematic-debugging.md (Phase 1-4)
+Code bug → systematic-debugging.md (Phase 1-4)
   Error deep in stack? → root-cause-tracing.md (trace backward)
   Found root cause? → defense-in-depth.md (add layers)
   About to claim success? → verification.md (verify first)
+
+System issue → Investigation Methodology (5 steps)
+  CI/CD failure? → Log & CI/CD Analysis (gh CLI)
+  Slow/timeout? → Performance Diagnostics
+  Multi-component? → Task Management checklist + Reporting Standards
+  Visual/UI bug? → Frontend Verification (agent-browser / browser devtools)
 ```
 
+## Tools Integration
+
+| Tool | Use Case |
+|------|----------|
+| `execute` | Run test commands, build scripts, verification steps |
+| `gh` CLI | CI/CD log analysis, PR checks, workflow runs |
+| `psql` | Live database diagnostics and slow query analysis |
+| `agent-browser` skill | Frontend visual verification and network inspection |
+| `/ck-scout` | Search codebase for related patterns before investigating |
+
 ## Red Flags
 
 Stop and follow process if thinking:

package/templates/repo/.github/skills/fix/SKILL.md

@@ -12,6 +12,7 @@ Unified skill for fixing issues of any complexity with intelligent routing.
 - `--auto` - Activate autonomous mode (**default**)
 - `--review` - Activate human-in-the-loop review mode
 - `--quick` - Activate quick mode
+- `--parallel` - Fix 2+ independent issues concurrently using parallel agents
 
 ## Workflow
 
@@ -31,10 +32,10 @@ See `references/mode-selection.md` for question format.
 
 - Activate `debug` skill.
 - Guess all possible root causes.
-- Search in parallel to verify each hypothesis.
+- Spawn multiple parallel search agents to verify each hypothesis.
 - Create report with all findings for the next step.
 
-### Step 3: Complexity Assessment & Fix Implementation
+### Step 3: Complexity Assessment & Task Orchestration
 
 Classify before routing. See `references/complexity-assessment.md`.
 
@@ -45,17 +46,27 @@ Classify before routing. See `references/complexity-assessment.md`.
 | **Complex** | System-wide, architecture impact | `references/workflow-deep.md` |
 | **Parallel** | 2+ independent issues | Parallel `fullstack-developer` agents |
 
-### Step 4: Fix Verification & Prevent Future Issues
+**Task orchestration notes:**
+- **Quick workflow:** Skip task creation — proceed directly to fix.
+- **Moderate+ workflows:** After classifying, create a todo checklist for all phases upfront with dependencies before starting any implementation. Track each phase with checkboxes and note blockers inline.
+
+See `references/task-orchestration.md` for checklist structure and dependency tracking patterns.
+
+### Step 4: Fix Implementation & Verification
 
 - Read and analyze all the implemented changes.
-- Search in parallel to find possible related code for verification.
+- Spawn multiple parallel search agents to verify no regressions in related code.
 - Make sure these fixes don't break other parts of the codebase.
 - Prevent future issues by adding comprehensive validation.
 
 ### Step 5: Finalize
 
-- Report summary to user with confidence level/score, all the changes and related files.
-- Ask to commit via `git-manager` agent and update docs if needed via `docs-manager` agent (in parallel).
+**MANDATORY — always execute all steps:**
+
+1. Report summary to user with confidence score (0–10), all changes, and related files.
+2. Update `./docs` via ``docs-manager`` agent (NON-OPTIONAL — always run even for small fixes).
+3. Mark all checklist tasks complete.
+4. Ask user to commit via ``git-manager`` agent.
 
 ---
 
@@ -65,8 +76,8 @@ See `references/skill-activation-matrix.md` for complete matrix.
 
 **Always activate:** `debug` (all workflows)
 **Conditional:** `problem-solving`, `sequential-thinking`, `brainstorming`, `context-engineering`
-**Agents:** `debugger`, `researcher`, `planner`, `code-reviewer`, `tester`
-**Parallel:** Multiple parallel searches for scouting, terminal commands for verification
+**Agents:** ``debugger``, ``researcher``, ``planner``, ``code-reviewer``, ``tester``
+**Parallel patterns:** Multiple parallel search agents for scouting; parallel terminal commands for verification; parallel ``fullstack-developer`` agents for independent issues (`--parallel` flag)
 
 ## Output Format
 
@@ -85,6 +96,7 @@ Unified step markers:
 Load as needed:
 - `references/mode-selection.md` - Mode selection question format
 - `references/complexity-assessment.md` - Classification criteria
+- `references/task-orchestration.md` - Todo checklist structure and dependency tracking
 - `references/workflow-quick.md` - Quick: debug → fix → review
 - `references/workflow-standard.md` - Standard: full pipeline
 - `references/workflow-deep.md` - Deep: research + brainstorm + plan

package/templates/repo/.github/skills/frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: Create polished frontend interfaces from designs/screenshots. Use for web components, replicating UI designs, quick prototypes, avoiding AI slop.
+description: Create polished frontend interfaces from designs/screenshots/videos. Use for web components, replicating UI designs, quick prototypes, 3D experiences, immersive interfaces, avoiding AI slop.
 ---
 
 Create distinctive, production-grade frontend interfaces. Implement real working code with exceptional aesthetic attention.
@@ -12,15 +12,18 @@ Choose workflow based on input type:
 | Input | Workflow | Reference |
 |-------|----------|-----------|
 | Screenshot | Replicate exactly | `./references/workflow-screenshot.md` |
+| Video | Replicate with animations | `./references/workflow-video.md` |
 | Quick task | Rapid implementation | `./references/workflow-quick.md` |
 | Describe only | Document for devs | `./references/workflow-describe.md` |
+| 3D/WebGL request | Three.js immersive | `./references/workflow-3d.md` |
+| Complex/award-quality | Full immersive | `./references/workflow-immersive.md` |
 | From scratch | Design Thinking below | - |
 
 **All workflows**: Activate `ui-styling` skill FIRST for design patterns and component library.
 
 ## Screenshot/Video Replication (Quick Reference)
 
-1. **Analyze** visually - extract colors, fonts, spacing, effects
+1. **Analyze** visually (use `ai-multimodal` skill if available) - extract colors, fonts, spacing, effects
 2. **Plan** with `ui-ux-designer` agent - create phased implementation
 3. **Implement** - match source precisely
 4. **Verify** - compare to original
@@ -45,7 +48,7 @@ Before coding, commit to a BOLD aesthetic direction:
 - **Motion**: CSS-first, anime.js for complex (`./references/animejs.md`). Orchestrated page loads > scattered micro-interactions.
 - **Spatial**: Unexpected layouts. Asymmetry. Overlap. Negative space OR controlled density.
 - **Backgrounds**: Atmosphere over solid colors. Gradients, noise, patterns, shadows, grain.
-- **Assets**: Process with ImageMagick, FFmpeg, RMBG CLI tools
+- **Assets**: Process with ImageMagick, FFmpeg, RMBG CLI tools (or `ai-multimodal`/`media-processing` skills if available)
 
 ## Asset & Analysis References
 

package/templates/repo/.github/skills/planning/SKILL.md

@@ -7,6 +7,22 @@ description: Plan implementations, design architectures, create technical roadma
 
 Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
 
+## Workflow Modes
+
+Default: `--auto` — analyze the task and auto-pick the most appropriate mode.
+
+| Flag | Research | Red Team | Validation | Cook Flag |
+|------|----------|----------|------------|-----------|
+| `--auto` | Auto | Auto | Auto | auto |
+| `--fast` | Skip | Skip | Skip | fast |
+| `--hard` | Full | Yes | Yes | hard |
+| `--parallel` | Parallel | Yes | Yes | parallel |
+| `--two` | Full | Yes | Yes | two |
+
+Add `--no-tasks` to any mode to skip todo checklist hydration after the plan is written.
+
+See `references/workflow-modes.md` for detailed mode behavior.
+
 ## When to Use
 
 Use this skill when:
@@ -41,12 +57,15 @@ Load: `references/output-standards.md`
 
 ## Workflow Process
 
-1. **Initial Analysis** → Read codebase docs, understand context
-2. **Research Phase** → Spawn researchers, investigate approaches
-3. **Synthesis** → Analyze reports, identify optimal solution
-4. **Design Phase** → Create architecture, implementation design
-5. **Plan Documentation** → Write comprehensive plan
-6. **Review & Refine** → Ensure completeness, clarity, actionability
+1. **Pre-Creation Check** → Check `## Plan Context` from hook injection; follow Active Plan State rules below.
+2. **Mode Detection** → Use explicit flag if provided; otherwise auto-detect based on task complexity.
+3. **Research Phase** → Spawn parallel researcher agents to investigate approaches (skip in `--fast` mode).
+4. **Codebase Analysis** → Read docs in `./docs`; activate `/ck-scout` if file relationships are unclear.
+5. **Plan Documentation** → Write comprehensive plan via `planner` agent using the directory structure below.
+6. **Red Team Review** → Spawn adversarial reviewers to challenge assumptions (`--hard`, `--parallel`, `--two` modes only). See `references/workflow-modes.md`.
+7. **Post-Plan Validation** → Use `/ck-plan-validate` to verify completeness and coherence (`--hard`, `--parallel`, `--two` modes only).
+8. **Hydrate Tasks** → Create a todo checklist from plan phases with dependency annotations (default on; skip with `--no-tasks` or fewer than 3 phases).
+9. **Context Reminder** → Output the cook command with the absolute plan path (MANDATORY): `Use plan at: {absolute-plan-dir-path}`
 
 ## Output Requirements
 
@@ -57,13 +76,15 @@ Load: `references/output-standards.md`
 - Provide multiple options with trade-offs when appropriate
 - Fully respect the `./docs/development-rules.md` file.
 
-## Task Integration (Optional)
+## Task Management
 
-When session has `TASK_LIST_ID` set (active plan):
-- Create tasks for each phase with clear subjects
-- Set dependencies: Phase N+1 `blockedBy` Phase N
-- Agents coordinate via shared task list automatically
-- Update tasks to mark progress (in_progress → completed)
+Plan files are persistent on disk. Todo checklists are session-scoped. Hydration bridges the gap by converting plan phases into trackable checklist items at plan-creation time.
+
+- **Default:** Auto-hydrate after plan is written (create checklist with one item per phase).
+- **Skip with:** `--no-tasks` flag or when plan has fewer than 3 phases (3-Task Rule).
+- **Checklist format:** Include phase name, dependencies, and owning agent hint per item.
+
+See `references/task-management.md` for checklist schema and dependency notation.
 
 ### Important
 DO NOT create plans or reports in USER directory.
@@ -95,8 +116,8 @@ Prevents version proliferation by tracking current working plan via session stat
 ### Active vs Suggested Plans
 
 Check the `## Plan Context` section injected by hooks:
-- **"Plan: {path}"** = Active plan, explicitly set via `set-active-plan.cjs` - use for reports
-- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: {path}"** = Active plan, explicitly set via `set-active-plan.cjs` — use this path for all reports
+- **"Suggested: {path}"** = Branch-matched hint only — do NOT auto-use
 - **"Plan: none"** = No active plan
 
 ### Rules
@@ -117,7 +138,7 @@ All agents writing reports MUST:
 DO NOT create plans or reports in USER directory.
 ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
 
-**Important:** Suggested plans do NOT get plan-specific reports - this prevents pollution of old plan folders.
+**Important:** Suggested plans do NOT get plan-specific reports — this prevents pollution of old plan folders.
 
 ## Quality Standards
 
@@ -129,3 +150,14 @@ ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
 - Validate against existing codebase patterns
 
 **Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.
+
+## References
+
+Load as needed:
+- `references/workflow-modes.md` - Mode behavior details and flag descriptions
+- `references/task-management.md` - Checklist schema, dependency notation, hydration rules
+- `references/research-phase.md` - Research phase execution
+- `references/codebase-understanding.md` - Codebase analysis steps
+- `references/solution-design.md` - Solution design process
+- `references/plan-organization.md` - Plan file structure and organization
+- `references/output-standards.md` - Task breakdown and output format standards

package/templates/repo/.github/skills/research/SKILL.md

@@ -24,7 +24,7 @@ You will employ a multi-source research strategy:
 
 1. **Search Strategy**:
    - **Gemini Toggle**: Check `$HOME/.copilot/.ck.json` (or `~/.copilot/.ck.json`) for `skills.research.useGemini` (default: `true`). If `false`, skip Gemini and use WebSearch.
-   - **Gemini Model**: Read from `$HOME/.copilot/.ck.json`: `gemini.model` (default: `gemini-3.0-flash`)
+   - **Gemini Model**: Read from `$HOME/.copilot/.ck.json`: `gemini.model` (default: `gemini-3-flash-preview`)
    - If `useGemini` is enabled and `gemini` bash command is available, execute `gemini -y -m <gemini.model> "...your search prompt..."` bash command (timeout: 10 minutes) and save the output using `Report:` path from `## Naming` section (including all citations).
    - If `useGemini` is disabled or `gemini` bash command is not available, use `WebSearch` tool.
    - Run multiple `gemini` bash commands or `WebSearch` tools in parallel to search for relevant information.