@stella-studio/ck 1.0.0

package/.claude/commands/preview.md

@@ -0,0 +1,280 @@
+---
+description: View files/directories OR generate visual explanations, slides, diagrams
+arguments:
+  - name: path
+    description: Path to file/directory to preview, OR topic for generation modes
+    required: false
+---
+
+Universal viewer + visual generator. View existing content OR generate new visual explanations.
+
+## Usage
+
+### View Mode (existing behavior)
+- `/preview <file.md>` - View markdown file in novel-reader UI
+- `/preview <directory/>` - Browse directory contents
+- `/preview --stop` - Stop running server
+
+### Generation Mode (new)
+- `/preview --explain <topic>` - Generate visual explanation (ASCII + Mermaid + prose)
+- `/preview --slides <topic>` - Generate presentation slides (one concept per slide)
+- `/preview --diagram <topic>` - Generate focused diagram (ASCII + Mermaid)
+- `/preview --ascii <topic>` - Generate ASCII-only diagram (terminal-friendly)
+
+## Examples
+
+```bash
+# View mode
+/preview plans/my-plan/plan.md     # View markdown file
+/preview plans/                    # Browse plans directory
+
+# Generation mode
+/preview --explain OAuth flow      # Generate OAuth explanation
+/preview --slides API architecture # Generate architecture slides
+/preview --diagram data flow       # Generate data flow diagram
+/preview --ascii auth process      # Generate ASCII-only diagram
+```
+
+## Argument Resolution
+
+When processing arguments, follow this priority order:
+
+1. **`--stop`** → Stop server (exit)
+2. **Generation flags** (`--explain`, `--slides`, `--diagram`, `--ascii`) → Generation mode
+3. **Path exists on filesystem** → View mode
+4. **Neither flag nor valid path** → Error: suggest `/preview --help`
+
+**Topic-to-slug conversion:**
+- Lowercase the topic
+- Replace spaces/special chars with hyphens
+- Remove non-alphanumeric except hyphens
+- Collapse multiple hyphens → single hyphen
+- Trim leading/trailing hyphens
+- **Max 80 chars** - truncate at word boundary if longer
+- If result is empty (topic was all special chars) → Error: ask for valid topic
+
+Example: `OAuth 2.0 Flow` → `oauth-2-0-flow.md`
+
+**Multiple flags:** If multiple generation flags provided, use first one; remaining treated as topic.
+Example: `/preview --explain --slides topic` → `--explain` mode, topic = "--slides topic"
+
+**Placeholder `{topic}`:** Replaced with original user input in title case (not the slug).
+
+## Execution
+
+**IMPORTANT:** Run server as Claude Code background task using `run_in_background: true` with the Bash tool. This makes the server visible in `/tasks` and manageable via `KillShell`.
+
+The skill is located at `.claude/skills/markdown-novel-viewer/`.
+
+### Stop Server
+
+If `--stop` flag is provided:
+
+```bash
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs --stop
+```
+
+### Start Server
+
+Otherwise, run the `markdown-novel-viewer` server as CC background task with `--foreground` flag (keeps process alive for CC task management):
+
+```bash
+# Determine if path is file or directory
+INPUT_PATH="{{path}}"
+if [[ -d "$INPUT_PATH" ]]; then
+  # Directory mode - browse
+  node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+    --dir "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+else
+  # File mode - view markdown
+  node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+    --file "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+fi
+```
+
+**Critical:** When calling the Bash tool:
+- Set `run_in_background: true` to run as CC background task
+- Set `timeout: 300000` (5 minutes) to prevent premature termination
+- Parse JSON output and report URL to user
+
+Example Bash tool call:
+```json
+{
+  "command": "node .claude/skills/markdown-novel-viewer/scripts/server.cjs --dir \"path\" --host 0.0.0.0 --open --foreground",
+  "run_in_background": true,
+  "timeout": 300000,
+  "description": "Start preview server in background"
+}
+```
+
+After starting, parse the JSON output (e.g., `{"success":true,"url":"http://localhost:3456/view?file=...","networkUrl":"http://192.168.1.x:3456/view?file=..."}`) and report:
+- Local URL for browser access
+- Network URL for remote device access (if available)
+- Inform user that server is now running as CC background task (visible in `/tasks`)
+
+**CRITICAL:** MUST display the FULL URL including path and query string (e.g., `http://localhost:3456/view?file=/path/to/file.md`). NEVER truncate to just `host:port` (e.g., `http://localhost:3456`). The full URL is required for direct file access.
+
+---
+
+## Generation Mode
+
+When `--explain`, `--slides`, `--diagram`, or `--ascii` flag is provided:
+
+### Step 1: Determine Output Location
+
+1. Check if there's an active plan context (from `## Plan Context` in hook injection)
+2. If active plan exists: save to `{plan_dir}/visuals/{topic-slug}.md`
+3. If no active plan: save to `plans/visuals/{topic-slug}.md`
+4. Create `visuals/` directory if it doesn't exist
+
+### Step 2: Generate Content
+
+**Mermaid Diagram Syntax:**
+When generating ` ```mermaid ` code blocks, use `/mermaidjs-v11` skill for v11 syntax rules.
+
+**Essential rules (always apply):**
+- Quote node text with special characters: `A["text with /slashes"]`
+- Escape brackets in labels: `A["array[0]"]`
+
+Use the appropriate template based on flag:
+
+#### --explain (Visual Explanation)
+```markdown
+# Visual Explanation: {topic}
+
+## Overview
+Brief description of what we're explaining.
+
+## Quick View (ASCII)
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│ Component A │───>│ Component B │───>│ Component C │
+└─────────────┘    └─────────────┘    └─────────────┘
+
+## Detailed Flow
+\```mermaid
+sequenceDiagram
+    participant A as Component A
+    participant B as Component B
+    A->>B: Request
+    B-->>A: Response
+\```
+
+## Key Concepts
+1. **Concept A** - Explanation
+2. **Concept B** - Explanation
+
+## Code Example (if applicable)
+\```typescript
+// Relevant code snippet with comments
+\```
+```
+
+#### --slides (Presentation Format)
+```markdown
+# {Topic} - Visual Presentation
+
+---
+
+## Slide 1: Introduction
+- One concept per slide
+- Bullet points only
+
+---
+
+## Slide 2: The Problem
+\```mermaid
+flowchart TD
+    A[Problem] --> B[Impact]
+\```
+
+---
+
+## Slide 3: The Solution
+- Key point 1
+- Key point 2
+
+---
+
+## Slide 4: Summary
+Key takeaways...
+```
+
+#### --diagram (Focused Diagram)
+```markdown
+# Diagram: {topic}
+
+## ASCII Version
+┌──────────────────────────────────────────┐
+│               Architecture               │
+├─────────────┬──────────────┬─────────────┤
+│   Layer 1   │   Layer 2    │   Layer 3   │
+└─────────────┴──────────────┴─────────────┘
+
+## Mermaid Version
+\```mermaid
+flowchart TB
+    subgraph Layer1[Layer 1]
+        A[Component A]
+    end
+    subgraph Layer2[Layer 2]
+        B[Component B]
+    end
+    A --> B
+\```
+```
+
+#### --ascii (Terminal-Friendly Only)
+```
+┌────────────────────────────────────────────────────────┐
+│                    {Topic} Overview                    │
+├────────────────────────────────────────────────────────┤
+│                                                        │
+│   ┌─────────┐       ┌─────────┐       ┌─────────┐      │
+│   │  Input  │──────>│ Process │──────>│ Output  │      │
+│   └─────────┘       └─────────┘       └─────────┘      │
+│                                                        │
+│   Legend:                                              │
+│   ──────>  Data flow                                   │
+│   ──────   Connection                                  │
+│                                                        │
+└────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Save and Preview
+
+1. Write generated content to determined path
+2. Start preview server with the generated file:
+```bash
+node .claude/skills/markdown-novel-viewer/scripts/server.cjs \
+  --file "<generated-file-path>" \
+  --host 0.0.0.0 \
+  --open \
+  --foreground
+```
+
+### Step 4: Report to User
+
+Report:
+- Generated file path
+- Preview URL (local + network)
+- Remind: file saved in plan's `visuals/` folder for future reference
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Invalid topic (empty) | Ask user to provide a topic |
+| Flag without topic (`/preview --explain`) | Ask user: "Please provide a topic: `/preview --explain <topic>`" |
+| Topic becomes empty after sanitization | Ask user to provide topic with alphanumeric characters |
+| File write failure | Report error, suggest checking permissions |
+| Server startup failure | Check if port in use, try `/preview --stop` first |
+| No generation flag + invalid path | Suggest `/preview --help` or correct syntax |
+| Existing file at output path | Overwrite with new content (no prompt) |
+| Server already running | Reuse existing server instance, just open new URL |
+| Parent `plans/` dir missing | Create directories recursively before write |

package/.claude/commands/review/codebase/parallel.md

@@ -0,0 +1,122 @@
+---
+description: ⚡⚡⚡ Ultrathink edge cases, then parallel verify with code-reviewers
+argument-hint: [scope-or-prompt]
+---
+
+**Ultrathink** to exhaustively list ALL potential edge cases, then dispatch parallel `code-reviewer` agents to verify: <scope>$ARGUMENTS</scope>
+
+**IMPORTANT:** Activate needed skills. Ensure token efficiency. Sacrifice grammar for concision.
+
+## Workflow
+
+### 1. Ultrathink Edge Cases
+
+Main agent deeply analyzes the scope to LIST all potential edge cases FIRST:
+- Read `codebase-summary.md` for context
+- Use `/scout:ext` to find relevant files
+- **Think exhaustively** about what could go wrong:
+  - Null/undefined scenarios
+  - Boundary conditions (off-by-one, empty, max values)
+  - Error handling gaps
+  - Race conditions, async edge cases
+  - Input validation holes
+  - Security vulnerabilities
+  - Resource leaks
+  - Untested code paths
+
+**Output format:**
+```markdown
+## Edge Cases Identified
+
+### Category: [scope-area]
+1. [edge case description] → files: [file1, file2]
+2. [edge case description] → files: [file3]
+
+### Category: [another-area]
+1. [edge case description] → files: [file4, file5]
+```
+
+### 2. Categorize & Assign
+
+Group edge cases by similar scope for parallel verification:
+- Each category → one `code-reviewer` agent
+- Max 6 categories (merge small ones)
+- Each reviewer gets specific edge cases to VERIFY, not discover
+
+### 3. Parallel Verification
+
+Launch N `code-reviewer` subagents simultaneously:
+- Pass: category name, list of edge cases, relevant files
+- Task: **VERIFY** if each edge case is properly handled in code
+- Report: which edge cases are handled vs unhandled
+
+**Reviewer instruction:**
+```
+Verify these specific edge cases in the given files:
+[list of edge cases]
+
+For each, report:
+- ✅ Handled: [how it's handled]
+- ❌ Unhandled: [what's missing]
+- ⚠️ Partial: [what needs improvement]
+```
+
+### 4. Aggregate Results
+
+Collect all verification reports:
+```markdown
+## Edge Case Verification Report
+
+### Summary
+- Total edge cases: X
+- Handled: Y ✅
+- Unhandled: Z ❌
+- Partial: W ⚠️
+
+### Unhandled Edge Cases (Need Fix)
+| # | Edge Case | File | Status |
+|---|-----------|------|--------|
+| 1 | ...       | ...  | ❌     |
+
+### Partial Handling (Need Review)
+| # | Edge Case | File | Issue |
+|---|-----------|------|-------|
+| 1 | ...       | ...  | ...   |
+```
+
+### 5. Auto-Fix Pipeline
+
+**IF** unhandled/partial edge cases found:
+- Ask: "Found N unhandled edge cases. Fix with /fix --parallel? [Y/n]"
+- **IF yes:** Trigger `/fix --parallel` with unhandled list
+
+### 6. Final Report
+
+- Summary of verification
+- Ask: "Commit? [Y/n]" → use `git-manager`
+
+## Example
+
+```
+User: /review:codebase:parallel auth module
+
+1. Ultrathink → Lists 12 edge cases for auth:
+   - Empty password submission
+   - Token expiry during request
+   - Concurrent login attempts
+   - Invalid refresh token
+   ...
+
+2. Categorize → 3 groups:
+   - Login flow (4 cases)
+   - Token handling (5 cases)
+   - Session management (3 cases)
+
+3. Parallel → 3 code-reviewers verify simultaneously
+
+4. Aggregate → 8 handled, 3 unhandled, 1 partial
+
+5. Fix → User approves → /fix --parallel
+
+6. Final → Commit changes
+```

package/.claude/commands/review/codebase.md

@@ -0,0 +1,49 @@
+---
+description: ⚡⚡⚡ Scan & analyze the codebase.
+argument-hint: [tasks-or-prompt]
+---
+
+Think harder to scan the codebase and analyze it follow the Orchestration Protocol, Core Responsibilities, Subagents Team and Development Rules: 
+<tasks>$ARGUMENTS</tasks>
+
+---
+
+## Role Responsibilities
+- You are an elite software engineering expert who specializes in system architecture design and technical decision-making. 
+- You operate by the holy trinity of software engineering: **YAGNI** (You Aren't Gonna Need It), **KISS** (Keep It Simple, Stupid), and **DRY** (Don't Repeat Yourself). Every solution you propose must honor these principles.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+---
+
+## Workflow:
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+### Research
+
+* Use 2 `researcher` subagents in parallel to search up to max 5 sources for the user's request, idea validation, best practices, challenges, and find the best possible solutions.
+* Keep every research markdown report concise (≤150 lines) while covering all requested topics and citations.
+* Use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+
+### Code Review
+
+* After finishing, use multiple `code-reviewer` subagents in parallel to review code. 
+* If there are any issues, duplicate code, or security vulnerabilities, ask main agent to improve the code and repeat the "Testing" process until all tests pass. 
+* When all tests pass, code is reviewed, the tasks are completed, report back to user with a summary of the changes and explain everything briefly, ask user to review the changes and approve them.
+* **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
+
+### Plan
+* Use `planner` subagent to analyze reports from `researcher` and `scout` subagents to create an improvement plan following the progressive disclosure structure:
+  - Create a directory using naming pattern from `## Naming` section.
+  - Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+  - For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
+
+### Final Report
+* Report back to user with a summary of the changes and explain everything briefly, guide user to get started and suggest the next steps.
+* Ask the user if they want to commit and push to git repository, if yes, use `git-manager` subagent to commit and push to git repository.
+
+**REMEMBER**:
+- You can always generate images with `ai-multimodal` skill on the fly for visual assets.
+- You always read and analyze the generated assets with `ai-multimodal` skill to verify they meet requirements.
+- For image editing (removing background, adjusting, cropping), use ImageMagick or similar tools as needed.

package/.claude/commands/test/ui.md

@@ -0,0 +1,92 @@
+---
+description: ⚡⚡ Run UI tests on a website & generate a detailed report.
+argument-hint: [url] [options]
+---
+
+Activate the chrome-devtools skill.
+
+## Purpose
+Run comprehensive UI tests on a website and generate a detailed report.
+
+## Arguments
+- $1: URL - The URL of the website to test
+- $2: OPTIONS - Optional test configuration (e.g., --headless, --mobile, --auth)
+
+## Testing Protected Routes (Authentication)
+
+For testing protected routes that require authentication, follow this workflow:
+
+### Step 1: User Manual Login
+Instruct the user to:
+1. Open the target site in their browser
+2. Log in manually with their credentials
+3. Open browser DevTools (F12) → Application tab → Cookies/Storage
+
+### Step 2: Extract Auth Credentials
+Ask the user to provide one of:
+- **Cookies**: Copy cookie values (name, value, domain)
+- **Access Token**: Copy JWT/Bearer token from localStorage or cookies
+- **Session Storage**: Copy relevant session keys
+
+### Step 3: Inject Authentication
+Use the `inject-auth.js` script to inject credentials before testing:
+
+```bash
+cd $SKILL_DIR  # .claude/skills/chrome-devtools/scripts
+
+# Option A: Inject cookies
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc123","domain":".example.com"}]'
+
+# Option B: Inject Bearer token
+node inject-auth.js --url https://example.com --token "Bearer eyJhbGciOi..." --header Authorization --token-key access_token
+
+# Option C: Inject localStorage
+node inject-auth.js --url https://example.com --local-storage '{"auth_token":"xyz","user_id":"123"}'
+
+# Combined (cookies + localStorage)
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc"}]' --local-storage '{"user":"data"}'
+```
+
+### Step 4: Run Tests
+After auth injection, the browser session persists. Run tests normally:
+
+```bash
+# Navigate and screenshot protected pages
+node navigate.js --url https://example.com/dashboard
+node screenshot.js --url https://example.com/profile --output profile.png
+
+# The auth session persists until --close true is used
+node screenshot.js --url https://example.com/settings --output settings.png --close true
+```
+
+### Auth Script Options
+- `--cookies '<json>'` - Inject cookies (JSON array)
+- `--token '<token>'` - Inject Bearer token
+- `--token-key '<key>'` - localStorage key for token (default: access_token)
+- `--header '<name>'` - Set HTTP header with token (e.g., Authorization)
+- `--local-storage '<json>'` - Inject localStorage items
+- `--session-storage '<json>'` - Inject sessionStorage items
+- `--reload true` - Reload page after injection
+- `--clear true` - Clear saved auth session
+
+## Workflow
+- Use `planning` skill to organize the test plan & report in the current project directory.
+- All the screenshots should be saved in the same report directory.
+- Browse $URL with the specified $OPTIONS, discover all pages, components, and endpoints.
+- Create a test plan based on the discovered structure
+- Use multiple `tester` subagents or tool calls in parallel to test all pages, forms, navigation, user flows, accessibility, functionalities, usability, responsive layouts, cross-browser compatibility, performance, security, seo, etc.
+- Use `ai-multimodal` to analyze all screenshots and visual elements.
+- Generate a comprehensive report in Markdown format, embedding all screenshots directly in the report.
+- Finally respond to the user with a concise summary of findings and recommendations.
+- Use `AskUserQuestion` tool to ask if user wants to preview the report with `/preview` slash command.
+
+## Output Requirements
+How to write reports:
+- Format: Use clear, structured Markdown with headers, lists, and code blocks where appropriate
+- Include the test results summary, key findings, and screenshot references
+- **IMPORTANT:** Ensure token efficiency while maintaining high quality.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+**IMPORTANT**: **Do not** start implementing the fixes.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/.claude/commands/test.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Run tests locally and analyze the summary report.
+---
+
+Use the `tester` subagent 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.

package/.claude/commands/use-mcp.md

@@ -0,0 +1,38 @@
+---
+description: Utilize tools of Model Context Protocol (MCP) servers
+argument-hint: [task]
+---
+Execute MCP operations via **Gemini CLI** to preserve context budget.
+
+## Execution Steps
+
+1. **Execute task via Gemini CLI** (using stdin pipe for MCP support):
+   ```bash
+   # IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+   # Read model from .claude/.ck.json: gemini.model (default: gemini-3-flash-preview)
+   echo "$ARGUMENTS. Return JSON only per GEMINI.md instructions." | gemini -y -m <gemini.model>
+   ```
+
+2. **Fallback to mcp-manager subagent** (if Gemini CLI unavailable):
+   - Use `mcp-manager` subagent to discover and execute tools
+   - If the subagent got issues with the scripts of `mcp-management` skill, use `mcp-builder` skill to fix them
+   - **DO NOT** create ANY new scripts
+   - The subagent can only use MCP tools if any to achieve this task
+   - If the subagent can't find any suitable tools, just report it back to the main agent to move on to the next step
+
+## Important Notes
+
+- **MUST use stdin piping** - the deprecated `-p` flag skips MCP initialization
+- Use `-y` flag to auto-approve tool execution
+- **GEMINI.md auto-loaded**: Gemini CLI automatically loads `GEMINI.md` from project root, enforcing JSON-only response format
+- **Parseable output**: Responses are structured JSON: `{"server":"name","tool":"name","success":true,"result":<data>,"error":null}`
+
+## Anti-Pattern (DO NOT USE)
+
+```bash
+# BROKEN - deprecated -p flag skips MCP server connections!
+gemini -y -m <gemini.model> -p "..."
+
+# ALSO BROKEN - --model flag with -p
+gemini -y -p "..." --model gemini-3-flash-preview
+```

package/.claude/commands/watzup.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Review recent changes and wrap up the work
+---
+Review my current branch and the most recent commits. 
+Provide a detailed summary of all changes, including what was modified, added, or removed. 
+Analyze the overall impact and quality of the changes.
+
+**IMPORTANT**: **Do not** start implementing.