cokit-cli 1.2.7 → 1.3.0

package/templates/repo/.github/prompts/ck-test.prompt.md

@@ -7,7 +7,6 @@ tools: ['execute/runInTerminal', 'execute/getTerminalOutput', 'execute/runTests'
 Use the `tester` agent to run tests locally and analyze the summary report.
 
 **IMPORTANT**: **Do not** start implementing.
-**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
 
 ---
 
@@ -18,4 +17,3 @@ Use the `tester` agent to run tests locally and analyze the summary report.
 | `/ck-fix` | Analyze and fix issues |
 | `/ck-review` | Scan and analyze codebase |
 | `/ck-git` | Commit changes |
-| `/ck-spec-checklist` | Validate against spec requirements |

package/templates/repo/.github/prompts/ck-watzup.prompt.md

@@ -18,4 +18,3 @@ Analyze the overall impact and quality of the changes.
 | `/ck-brainstorm` | Explore ideas |
 | `/ck-plan` | Create plan |
 | `/ck-cook` | Implement feature |
-| `/ck-spec-specify` | Write detailed feature spec |

package/templates/repo/.github/skills/agent-browser/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: agent-browser
 description: AI-optimized browser automation CLI with context-efficient snapshots. Use for long autonomous sessions, self-verifying workflows, video recording, and cloud browser testing (Browserbase).
+license: Apache-2.0
+argument-hint: "[url or task]"
 ---
 
 # agent-browser Skill
@@ -43,15 +45,16 @@ agent-browser click @e1
 agent-browser snapshot -i
 ```
 
-## When to Use
+## When to Use (vs chrome-devtools)
 
-Best for:
-- Long autonomous AI sessions (context-efficient snapshots)
-- Self-verifying workflows and build loops
-- Video recording for debugging
-- Cloud browsers (Browserbase) for CI/CD
-- Multi-tab handling
-- Form automation and testing
+| Use agent-browser | Use chrome-devtools |
+|-------------------|---------------------|
+| Long autonomous AI sessions | Quick one-off screenshots |
+| Context-constrained workflows | Custom Puppeteer scripts needed |
+| Video recording for debugging | WebSocket full frame debugging |
+| Cloud browsers (Browserbase) | Existing workflow integration |
+| Multi-tab handling | Need Sharp auto-compression |
+| Self-verifying build loops | Session with auth injection |
 
 **Token efficiency:** ~280 chars/snapshot vs 8K+ for Playwright MCP.
 

package/templates/repo/.github/skills/agent-browser/references/agent-browser-vs-chrome-devtools.md

@@ -0,0 +1,112 @@
+# agent-browser vs chrome-devtools
+
+Detailed comparison guide for choosing between browser automation skills.
+
+## Feature Comparison
+
+| Feature | agent-browser | chrome-devtools |
+|---------|---------------|-----------------|
+| **Engine** | Playwright (via Rust CLI) | Puppeteer |
+| **Refs system** | `@e1` inline | `[ref=e1]` YAML |
+| **Session persistence** | Named sessions (`--session`) | `.browser-session.json` |
+| **Screenshot** | Basic | Auto-compress >5MB (Sharp) |
+| **Network intercept** | `route` command | `network.js` script |
+| **Console capture** | Basic | With filtering |
+| **WebSocket debug** | Limited | Full frames support |
+| **Video recording** | Built-in `record` | Not available |
+| **PDF export** | Built-in `pdf` | Via Puppeteer API |
+| **Auth persistence** | `state save/load` | `inject-auth.js` |
+| **Multi-tab** | Full support | Limited |
+| **Cloud browsers** | Browserbase native | Manual setup |
+| **Performance** | Rust CLI (fast) | Node.js |
+| **Custom scripts** | None (CLI only) | 20+ utilities |
+
+## Token Efficiency Benchmarks
+
+| Metric | agent-browser | chrome-devtools | Playwright MCP |
+|--------|---------------|-----------------|----------------|
+| Homepage snapshot | ~280 chars | ~300-500 chars | ~8,247 chars |
+| Context reduction | 93% vs MCP | 90% vs MCP | Baseline |
+| Tool definitions | ~2K tokens | 0 (CLI scripts) | ~17K tokens |
+
+**Conclusion:** Both agent-browser and chrome-devtools are similarly efficient. Both dramatically outperform Playwright MCP.
+
+## Use Case Decision Tree
+
+```
+Need browser automation?
+|
++-- Long autonomous AI session?
+|   +-- YES --> agent-browser (better context efficiency)
+|   +-- NO --> Continue
+|
++-- Need video recording?
+|   +-- YES --> agent-browser (built-in)
+|   +-- NO --> Continue
+|
++-- Cloud browser (CI/CD)?
+|   +-- YES --> agent-browser (Browserbase native)
+|   +-- NO --> Continue
+|
++-- Custom Puppeteer scripts?
+|   +-- YES --> chrome-devtools (20+ utilities)
+|   +-- NO --> Continue
+|
++-- WebSocket debugging?
+|   +-- YES --> chrome-devtools (full frames)
+|   +-- NO --> Continue
+|
++-- Screenshot auto-compression?
+|   +-- YES --> chrome-devtools (Sharp)
+|   +-- NO --> agent-browser OR chrome-devtools
+```
+
+## Parallel Usage Patterns
+
+Both skills can coexist - use the right tool for each task:
+
+```bash
+# Quick screenshot with compression -> chrome-devtools
+node "$SKILL_DIR/screenshot.js" --url https://example.com --output ss.png
+
+# Long autonomous session -> agent-browser
+agent-browser --session test1 open https://example.com
+agent-browser snapshot -i
+# ... many interactions ...
+agent-browser close
+```
+
+## Migration Guide
+
+### From chrome-devtools to agent-browser
+
+| chrome-devtools | agent-browser |
+|-----------------|---------------|
+| `node navigate.js --url X` | `agent-browser open X` |
+| `node aria-snapshot.js --url X` | `agent-browser open X && agent-browser snapshot -i` |
+| `node select-ref.js --ref e5 --action click` | `agent-browser click @e5` |
+| `node fill.js --selector "#email" --value "X"` | `agent-browser fill @e1 "X"` |
+| `node screenshot.js --output X.png` | `agent-browser screenshot -o X.png` |
+| `node console.js --types error` | No direct equivalent |
+| `node network.js` | No direct equivalent |
+
+### Key Differences
+
+1. **Refs format:** `[ref=e5]` vs `@e5`
+2. **Session:** File-based vs named sessions
+3. **Commands:** Node scripts vs CLI commands
+4. **Output:** JSON always vs JSON with `--json` flag
+
+## When to Switch
+
+**Switch to agent-browser when:**
+- Starting new long-running automation
+- Need video recording capability
+- Moving to cloud browsers (Browserbase)
+- Want simpler CLI syntax
+
+**Keep chrome-devtools when:**
+- Existing workflows depend on custom scripts
+- Need WebSocket full-frame debugging
+- Need automatic screenshot compression
+- Need fine-grained console log filtering

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

@@ -0,0 +1,102 @@
+---
+name: bootstrap
+description: "Bootstrap new projects with research, tech stack, design, planning, and implementation. Modes: full (interactive), auto (default), fast (skip research), parallel (multi-agent)."
+license: MIT
+argument-hint: "[requirements] [--full|--auto|--fast|--parallel]"
+---
+
+# Bootstrap - New Project Scaffolding
+
+End-to-end project bootstrapping from idea to running code.
+
+**Principles:** YAGNI, KISS, DRY | Token efficiency | Concise reports
+
+## Usage
+
+```
+/ck-bootstrap <user-requirements>
+```
+
+**Flags** (optional, default `--auto`):
+
+| Flag | Mode | Thinking | User Gates | Planning Skill | Cook Skill |
+|------|------|----------|------------|----------------|------------|
+| `--full` | Full interactive | Ultrathink | Every phase | `--hard` | (interactive) |
+| `--auto` | Automatic | Ultrathink | Design only | `--auto` | `--auto` |
+| `--fast` | Quick | Think hard | None | `--fast` | `--auto` |
+| `--parallel` | Multi-agent | Ultrathink | Design only | `--parallel` | `--parallel` |
+
+**Example:**
+```
+/ck-bootstrap "Build a SaaS dashboard with auth" --fast
+/ck-bootstrap "E-commerce platform with Stripe" --parallel
+```
+
+## Workflow Overview
+
+```
+[Git Init] → [Research?] → [Tech Stack?] → [Design?] → [Planning] → [Implementation] → [Test] → [Review] → [Docs] → [Onboard] → [Final]
+```
+
+Each mode loads a specific workflow reference + shared phases.
+
+## Mode Detection
+
+If no flag provided, default to `--auto`.
+
+Load the appropriate workflow reference:
+- `--full`: Load `references/workflow-full.md`
+- `--auto`: Load `references/workflow-auto.md`
+- `--fast`: Load `references/workflow-fast.md`
+- `--parallel`: Load `references/workflow-parallel.md`
+
+All modes share: Load `references/shared-phases.md` for implementation through final report.
+
+## Step 0: Git Init (ALL modes)
+
+Check if Git initialized. If not:
+- `--full`: Ask user if they want to init → `git-manager` subagent (`main` branch)
+- Others: Auto-init via `git-manager` subagent (`main` branch)
+
+## Skill Triggers (MANDATORY)
+
+After early phases (research, tech stack, design), trigger downstream skills:
+
+### Planning Phase
+Activate **plan** skill with mode-appropriate flag:
+- `--full` → `/ck-plan --hard <requirements>` (thorough research + validation)
+- `--auto` → `/ck-plan --auto <requirements>` (auto-detect complexity)
+- `--fast` → `/ck-plan --fast <requirements>` (skip research)
+- `--parallel` → `/ck-plan --parallel <requirements>` (file ownership + dependency graph)
+
+Planning skill outputs a plan path. Pass this to cook.
+
+### Implementation Phase
+Activate **cook** skill with the plan path and mode-appropriate flag:
+- `--full` → `/ck-cook <plan-path>` (interactive review gates)
+- `--auto` → `/ck-cook --auto <plan-path>` (skip review gates)
+- `--fast` → `/ck-cook --auto <plan-path>` (skip review gates)
+- `--parallel` → `/ck-cook --parallel <plan-path>` (multi-agent execution)
+
+## Role
+
+Elite software engineering expert specializing in system architecture and technical decisions. Brutally honest about feasibility and trade-offs.
+
+## Critical Rules
+
+- Activate relevant skills from catalog during the process
+- Keep all research reports ≤150 lines
+- All docs written to `./docs` directory
+- Plans written to `./plans` directory using naming from `## Naming` section
+- DO NOT implement code directly — delegate through planning + cook skills
+- Sacrifice grammar for concision in reports
+- List unresolved questions at end of reports
+- Run `/ck-journal` to write a concise technical journal entry upon completion
+
+## References
+
+- `references/workflow-full.md` - Full interactive workflow
+- `references/workflow-auto.md` - Auto workflow (default)
+- `references/workflow-fast.md` - Fast workflow
+- `references/workflow-parallel.md` - Parallel workflow
+- `references/shared-phases.md` - Common phases (implementation → final report)

package/templates/repo/.github/skills/bootstrap/references/shared-phases.md

@@ -0,0 +1,59 @@
+# Shared Phases (All Modes)
+
+These phases apply after planning is complete and cook skill is activated.
+Cook skill handles most of these — this reference documents bootstrap-specific guidance.
+
+## Implementation
+
+Handled by **cook** skill. Bootstrap-specific notes:
+- Use main agent to implement step by step per plan in `./plans`
+- Use `ui-ux-designer` subagent for frontend per `./docs/design-guidelines.md`
+- Asset pipeline: `ai-multimodal` (if available) (generate/analyze) → `imagemagick` (crop/resize) → background removal if needed
+- Run type checking and compile after each phase
+
+## Testing
+
+Handled by **cook** skill. Bootstrap-specific notes:
+- Write real tests — NO fake data, mocks, cheats, tricks, temporary solutions
+- `tester` subagent runs tests → report to main agent
+- If failures: `debugger` subagent → fix → repeat until all pass
+- DO NOT ignore failed tests to pass build/CI
+
+## Code Review
+
+Handled by **cook** skill. Bootstrap-specific notes:
+- `code-reviewer` subagent reviews code
+- If critical issues: fix → retest → repeat
+- Report summary to user when all tests pass and code reviewed
+
+## Documentation
+
+After code review passes. Use `docs-manager` subagent to create/update:
+- `./docs/README.md` (≤300 lines)
+- `./docs/codebase-summary.md`
+- `./docs/project-overview-pdr.md` (Product Development Requirements)
+- `./docs/code-standards.md`
+- `./docs/system-architecture.md`
+
+Use `project-manager` subagent to create:
+- `./docs/project-roadmap.md`
+- Update plan/phase status to complete
+
+## Onboarding
+
+Guide user to get started with the project:
+- Ask 1 question at a time, wait for answer before next
+- Example: instruct user to obtain API key → ask for key → add to env vars
+- If user requests config changes, repeat until approved
+
+## Final Report
+
+1. Summary of all changes, brief explanations
+2. Guide user to get started + suggest next steps
+3. Ask user if they want to commit/push:
+   - If yes: `git-manager` subagent to commit (and push if requested)
+   - `--fast` mode: auto-commit (no push) without asking
+
+**Report rules:**
+- Sacrifice grammar for concision
+- List unresolved questions at end, if any

package/templates/repo/.github/skills/bootstrap/references/workflow-auto.md

@@ -0,0 +1,52 @@
+# Auto Workflow (`--auto`) — Default
+
+**Thinking level:** Ultrathink
+**User gates:** Design approval only. All other phases proceed automatically.
+
+## Step 1: Research
+
+Spawn multiple `researcher` subagents in parallel:
+- Explore request, idea validation, challenges, best solutions
+- Keep every report ≤150 lines
+
+No user gate — proceed automatically.
+
+## Step 2: Tech Stack
+
+1. Use `planner` + multiple `researcher` subagents in parallel for best-fit stack
+2. Write tech stack to `./docs` directory
+
+No user gate — auto-select best option.
+
+## Step 3: Wireframe & Design
+
+1. Use `ui-ux-designer` + `researcher` subagents in parallel:
+   - Research style, trends, fonts (predict Google Fonts name, NOT just Inter/Poppins), colors, spacing, positions
+   - Describe assets for `ai-multimodal` (if available) skill generation
+2. `ui-ux-designer` creates:
+   - Design guidelines at `./docs/design-guidelines.md`
+   - Wireframes in HTML at `./docs/wireframe/`
+3. If no logo provided: generate with `ai-multimodal` (if available) skill
+4. Screenshot wireframes with `chrome-devtools` (if available) → save to `./docs/wireframes/`
+
+**Gate:** Ask user to approve design. Repeat if rejected.
+
+**Image tools:** `ai-multimodal` (if available) for generation/analysis, `imagemagick` for crop/resize, background removal tool as needed.
+
+## Step 4: Planning
+
+Activate **plan** skill: `/ck-plan --auto <requirements>`
+- Planning skill auto-detects complexity and picks appropriate mode
+- Creates plan directory using `## Naming` pattern
+- Overview at `plan.md` (<80 lines) + `phase-XX-*.md` files
+
+No user gate — proceed to implementation.
+
+## Step 5: Implementation → Final Report
+
+Load `references/shared-phases.md` for remaining phases.
+
+Activate **cook** skill: `/ck-cook --auto <plan-path>`
+- Skips all review gates
+- Auto-approves if score≥9.5 and 0 critical issues
+- Continues through all phases without stopping

package/templates/repo/.github/skills/bootstrap/references/workflow-fast.md

@@ -0,0 +1,50 @@
+# Fast Workflow (`--fast`)
+
+**Thinking level:** Think hard
+**User gates:** None. Fully autonomous from start to finish.
+
+## Step 1: Combined Research & Planning
+
+All research happens in parallel, then feeds into planning:
+
+**Parallel research batch** (spawn these simultaneously):
+- 2 `researcher` subagents (max 5 sources each): explore request, validate idea, find solutions
+- 2 `researcher` subagents (max 5 sources each): find best-fit tech stack
+- 2 `researcher` subagents (max 5 sources each): research design style, trends, fonts, colors, spacing, positions
+  - Predict Google Fonts name (NOT just Inter/Poppins)
+  - Describe assets for `ai-multimodal` (if available) generation
+
+Keep all reports ≤150 lines.
+
+## Step 2: Design
+
+1. `ui-ux-designer` subagent analyzes research, creates:
+   - Design guidelines at `./docs/design-guidelines.md`
+   - Wireframes in HTML at `./docs/wireframe/`
+2. If no logo provided: generate with `ai-multimodal` (if available) skill
+3. Screenshot wireframes with `chrome-devtools` (if available) → save to `./docs/wireframes/`
+
+**Image tools:** `ai-multimodal` (if available) for generation/analysis, `imagemagick` for crop/resize, background removal tool as needed.
+
+No user gate — proceed directly.
+
+## Step 3: Planning
+
+Activate **plan** skill: `/ck-plan --fast <requirements>`
+- Skip research (already done above)
+- Read codebase docs → create plan directly
+- Plan directory using `## Naming` pattern
+- Overview at `plan.md` (<80 lines) + `phase-XX-*.md` files
+
+No user gate — proceed to implementation.
+
+## Step 4: Implementation → Final Report
+
+Load `references/shared-phases.md` for remaining phases.
+
+Activate **cook** skill: `/ck-cook --auto <plan-path>`
+- Skips all review gates (fast planning pairs with fast execution)
+- Auto-approves if score≥9.5 and 0 critical issues
+- Continues through all phases without stopping
+
+**Note:** Fast mode uses `git-manager` to auto-commit (no push) at the end.

package/templates/repo/.github/skills/bootstrap/references/workflow-full.md

@@ -0,0 +1,60 @@
+# Full Interactive Workflow (`--full`)
+
+**Thinking level:** Ultrathink
+**User gates:** Every major phase requires user approval before proceeding.
+
+## Step 1: Clarify Requirements
+
+Use asking the user to probe user's request, constraints, true objectives.
+- Ask 1 question at a time, wait for answer before next
+- Question everything — don't assume
+- Challenge assumptions — best solution often differs from initial vision
+- Continue until 100% certain about requirements
+
+## Step 2: Research
+
+Spawn multiple `researcher` subagents in parallel:
+- Explore request validity, challenges, best solutions
+- Keep every report ≤150 lines
+
+**Gate:** Present findings to user. Proceed only with approval.
+
+## Step 3: Tech Stack
+
+1. Ask user for preferred tech stack. If provided, skip to step 4.
+2. Use `planner` + multiple `researcher` subagents in parallel to find best-fit stack
+3. Present 2-3 options with pros/cons by asking the user
+4. Write approved tech stack to `./docs` directory
+
+**Gate:** User approves tech stack before continuing.
+
+## Step 4: Wireframe & Design
+
+1. Ask user if they want wireframes/design. If no → skip to Step 5.
+2. Use `ui-ux-designer` + `researcher` subagents in parallel:
+   - Research style, trends, fonts (predict Google Fonts name, NOT just Inter/Poppins), colors, spacing, positions
+   - Describe assets for `ai-multimodal` (if available) skill generation
+3. `ui-ux-designer` creates:
+   - Design guidelines at `./docs/design-guidelines.md`
+   - Wireframes in HTML at `./docs/wireframe/`
+4. If no logo provided: generate with `ai-multimodal` (if available) skill
+5. Screenshot wireframes with `chrome-devtools` (if available) → save to `./docs/wireframes/`
+
+**Gate:** User approves design. Repeat if rejected.
+
+**Image tools:** `ai-multimodal` (if available) for generation/analysis, `imagemagick` for crop/resize, background removal tool as needed.
+
+## Step 5: Planning
+
+Activate **plan** skill: `/ck-plan --hard <requirements>`
+- Planner creates directory using `## Naming` pattern
+- Overview at `plan.md` (<80 lines) + `phase-XX-*.md` files
+- Present pros/cons of plan
+
+**Gate:** User approves plan. DO NOT start implementing without approval.
+
+## Step 6: Implementation → Final Report
+
+Load `references/shared-phases.md` for remaining phases.
+
+Activate **cook** skill: `/ck-cook <plan-path>` (interactive mode — review gates at each step)

package/templates/repo/.github/skills/bootstrap/references/workflow-parallel.md

@@ -0,0 +1,59 @@
+# Parallel Workflow (`--parallel`)
+
+**Thinking level:** Ultrathink parallel
+**User gates:** Design approval only. Implementation uses multi-agent parallel execution.
+
+## Step 1: Research
+
+Spawn max 2 `researcher` agents in parallel:
+- Explore requirements, validation, challenges, solutions
+- Keep reports ≤150 lines
+
+No user gate — proceed automatically.
+
+## Step 2: Tech Stack
+
+Use `planner` + multiple `researcher` agents in parallel for best-fit stack.
+Write to `./docs` directory (≤150 lines).
+
+No user gate — proceed automatically.
+
+## Step 3: Wireframe & Design
+
+1. Use `ui-ux-designer` + `researcher` agents in parallel:
+   - Research style, trends, fonts, colors, spacing, positions
+   - Predict Google Fonts name (NOT just Inter/Poppins)
+   - Describe assets for `ai-multimodal` (if available) generation
+2. `ui-ux-designer` creates:
+   - Design guidelines at `./docs/design-guidelines.md`
+   - Wireframes in HTML at `./docs/wireframe/`
+3. If no logo: generate with `ai-multimodal` (if available) skill
+4. Screenshot with `chrome-devtools` (if available) → save to `./docs/wireframes/`
+
+**Gate:** Ask user to approve design. Repeat if rejected.
+
+**Image tools:** `ai-multimodal` (if available) for generation/analysis, `imagemagick` for crop/resize, background removal tool as needed.
+
+## Step 4: Parallel Planning
+
+Activate **plan** skill: `/ck-plan --parallel <requirements>`
+- Creates phases with **exclusive file ownership** per phase (no overlap)
+- **Dependency matrix**: which phases run concurrently vs sequentially
+- `plan.md` includes dependency graph, execution strategy, file ownership matrix
+- Task hydration with `addBlockedBy` for sequential deps, no blockers for parallel groups
+
+No user gate — proceed to implementation.
+
+## Step 5: Parallel Implementation → Final Report
+
+Load `references/shared-phases.md` for remaining phases.
+
+Activate **cook** skill: `/ck-cook --parallel <plan-path>`
+- Read `plan.md` for dependency graph and execution strategy
+- Launch multiple `fullstack-developer` agents in PARALLEL for concurrent phases
+  - Pass: phase file path, environment info
+- Use `ui-ux-designer` for frontend (generate/analyze assets with `ai-multimodal` (if available), edit with `imagemagick`)
+- Respect file ownership boundaries
+- Run type checking after implementation
+
+Cook handles testing, review, docs, onboarding, final report per `shared-phases.md`.

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

@@ -1,6 +1,8 @@
 ---
 name: brainstorm
-description: Brainstorm solutions with trade-off analysis and brutal honesty. Use for ideation, architecture decisions, technical debates, feature exploration, feasibility assessment, design discussions.
+description: "Brainstorm solutions with trade-off analysis and brutal honesty. Use for ideation, architecture decisions, technical debates, feature exploration, feasibility assessment, design discussions."
+license: MIT
+argument-hint: "[topic or problem]"
 ---
 
 # Brainstorming Skill
@@ -22,38 +24,84 @@ You operate by the holy trinity of software engineering: **YAGNI** (You Aren't G
 - Performance optimization and bottleneck identification
 
 ## Your Approach
-1. **Question Everything**: Ask probing questions directly in your response to fully understand the user's request, constraints, and true objectives. Then stop and wait for user to answer. Don't assume - clarify until you're 100% certain.
-2. **Brutal Honesty**: Provide frank, unfiltered feedback about ideas directly in your response. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
+1. **Question Everything**: ask probing questions to fully understand the user's request, constraints, and true objectives. Don't assume - clarify until you're 100% certain.
+2. **Brutal Honesty**: provide frank, unfiltered feedback about ideas. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
 3. **Explore Alternatives**: Always consider multiple approaches. Present 2-3 viable solutions with clear pros/cons, explaining why one might be superior.
-4. **Challenge Assumptions**: Question the user's initial approach directly in your response. Often the best solution is different from what was originally envisioned. Wait for user input.
-5. **Consider All Stakeholders**: Ask the user about impact on end users, developers, operations team, and business objectives. Wait for response.
+4. **Challenge Assumptions**: question the user's initial approach. Often the best solution is different from what was originally envisioned.
+5. **Consider All Stakeholders**: evaluate impact on end users, developers, operations team, and business objectives.
 
 ## Collaboration Tools
 - Consult the `planner` agent to research industry best practices and find proven solutions
 - Engage the `docs-manager` agent to understand existing project implementation and constraints
 - Use `WebSearch` tool to find efficient approaches and learn from others' experiences
 - Use `docs-seeker` skill to read latest documentation of external plugins/packages
-- Use screenshot tools to capture and analyze visual materials and mockups
+- Leverage `ai-multimodal` (if available) skill to analyze visual materials and mockups
 - Query `psql` command to understand current database structure and existing data
 - Employ `sequential-thinking` skill for complex problem-solving that requires structured analysis
 
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.
+This applies to EVERY brainstorming session regardless of perceived simplicity.
+The design can be brief for simple projects, but you MUST present it and get approval.
+</HARD-GATE>
+
+## Anti-Rationalization
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to need a design" | Simple projects = most wasted work from unexamined assumptions. |
+| "I already know the solution" | Then writing it down takes 30 seconds. Do it. |
+| "The user wants action, not talk" | Bad action wastes more time than good planning. |
+| "Let me explore the code first" | Brainstorming tells you HOW to explore. Follow the process. |
+| "I'll just prototype quickly" | Prototypes become production code. Design first. |
+
+## Process Flow (Authoritative)
+
+```mermaid
+flowchart TD
+    A[Scout Project Context] --> B[Ask Clarifying Questions]
+    B --> C{Scope too large?}
+    C -->|Yes| D[Decompose into Sub-Projects]
+    D --> B
+    C -->|No| E[Propose 2-3 Approaches]
+    E --> F[Present Design Sections]
+    F --> G{User Approves?}
+    G -->|No| F
+    G -->|Yes| H[Write Design Doc / Report]
+    H --> I{Create Plan?}
+    I -->|Yes| J[Invoke /ck-plan]
+    I -->|No| K[End Session]
+    J --> L[Journal]
+    K --> L
+```
+
+**This diagram is the authoritative workflow.** If prose conflicts with this flow, follow the diagram. The terminal state is either `/ck-plan` or end.
+
 ## Your Process
 1. **Scout Phase**: Use `scout` skill to discover relevant files and code patterns, read relevant docs in `<project-dir>/docs` directory, to understand the current state of the project
-2. **Discovery Phase**: Ask clarifying questions about requirements, constraints, timeline, and success criteria directly in your response. Wait for user answers.
-3. **Research Phase**: Gather information from other agents and external sources
-4. **Analysis Phase**: Evaluate multiple approaches using your expertise and principles
-5. **Debate Phase**: Present options directly, challenge user preferences, and work toward the optimal solution. Wait for user input.
-6. **Consensus Phase**: Ensure alignment on the chosen approach and document decisions
-7. **Documentation Phase**: Create a comprehensive markdown summary report with the final agreed solution
-8. **Finalize Phase**: Ask the user if they want to create a detailed implementation plan. Wait for response.
-   - If `Yes`: Run `/plan` command with the brainstorm summary context as the argument to ensure plan continuity.
+2. **Discovery Phase**: ask clarifying questions about requirements, constraints, timeline, and success criteria
+3. **Scope Assessment**: Before deep-diving, assess if request covers multiple independent subsystems:
+   - If request describes 3+ independent concerns (e.g., "build platform with chat, billing, analytics") → flag immediately
+   - Help user decompose into sub-projects: identify pieces, relationships, build order
+   - Each sub-project gets its own brainstorm → plan → implement cycle
+   - Don't spend questions refining details of a project that needs decomposition first
+4. **Research Phase**: Gather information from other agents and external sources
+5. **Analysis Phase**: Evaluate multiple approaches using your expertise and principles
+6. **Debate Phase**: Present options, challenge user preferences, and work toward the optimal solution
+7. **Consensus Phase**: Ensure alignment on the chosen approach and document decisions
+8. **Documentation Phase**: Create a comprehensive markdown summary report with the final agreed solution
+9. **Finalize Phase**: ask if user wants to create a detailed implementation plan.
+   - If `Yes`: Run `/ck-plan` command with the brainstorm summary context as the argument to ensure plan continuity.
      **CRITICAL:** The invoked plan command will create `plan.md` with YAML frontmatter including `status: pending`.
    - If `No`: End the session.
+10. **Journal Phase**: Run `/ck-journal` to write a concise technical journal entry upon completion.
 
 ## Report Output
 Use the naming pattern from the `## Naming` section in the injected context. The pattern includes the full path and computed date.
 
 ## Output Requirements
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the reports.
+
 When brainstorming concludes with agreement, create a detailed markdown summary report including:
 - Problem statement and requirements
 - Evaluated approaches with pros/cons
@@ -71,4 +119,4 @@ When brainstorming concludes with agreement, create a detailed markdown summary
 
 **Remember:** Your role is to be the user's most trusted technical advisor - someone who will tell them hard truths to ensure they build something great, maintainable, and successful.
 
-**IMPORTANT:** **DO NOT** implement anything, just brainstorm, answer questions and advise.
+**IMPORTANT:** **DO NOT** implement anything, just brainstorm, answer questions and advise.