vividkit · thieung · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026 · Apr 7, 2026
diff --git a/docs/ck-architecture/ck-bootstrap.md b/docs/ck-architecture/ck-bootstrap.md
@@ -0,0 +1,69 @@
+# /ck:bootstrap — New Project Scaffolding
+
+Source: `~/.claude/skills/bootstrap/SKILL.md` + `references/`
+
+## Authoritative Flow
+
+```
+Step 0: Git Init → ensure repo exists
+Step 1: Research → parallel researcher sub-agents explore idea/challenges
+Step 2: Tech Stack → planner + researchers pick best-fit stack → docs/
+Step 3: Design → ui-ux-designer + researcher → wireframes, design guidelines → [Design Gate]
+Step 4: Planning → activate ck:plan skill with mode flag
+Step 5: Implementation → activate ck:cook skill with plan path
+Step 6: Test + Review → handled by ck:cook (tester → debugger → code-reviewer)
+Step 7: Docs + Onboard → docs-manager, project-manager sub-agents → final report + git commit
+```
+
+## Mode Selection
+
+| Mode | Flag | Research | User Gates | Planning Skill | Cook Skill |
+|------|------|----------|------------|----------------|------------|
+| full | --full | Yes | Every phase | --hard | interactive |
+| auto | --auto (default) | Yes | Design only | --auto | --auto |
+| fast | --fast | Skip | None | --fast | --auto |
+| parallel | --parallel | Yes | Design only | --parallel | --parallel |
+
+Detection: explicit flag → default `--auto`.
+
+## Skills Activated
+
+| Phase | Skill |
+|-------|-------|
+| Step 4 | ck:plan (planning) |
+| Step 5-6 | ck:cook (implementation + test + review) |
+| Step 3 | ck:ai-multimodal (image generation), ck:chrome-devtools (screenshots) |
+| Step 7 | ck:journal (final entry) |
+
+## Sub-agents Spawned
+
+| Phase | Agent | Mandatory |
+|-------|-------|-----------|
+| Git Init | git-manager | Yes (all modes) |
+| Research | researcher (parallel) | Optional (skip in fast) |
+| Tech Stack | planner + researcher | Optional (skip in fast) |
+| Design | ui-ux-designer + researcher | Optional (skip in fast) |
+| Planning | via ck:plan skill | Yes |
+| Implementation | via ck:cook skill | Yes |
+| Docs | docs-manager | Yes |
+| Docs | project-manager | Yes |
+
+## Critical Rules
+
+- DO NOT implement code directly — delegate through ck:plan → ck:cook
+- All research reports ≤150 lines
+- Plans to `./plans`, docs to `./docs`
+- YAGNI / KISS / DRY enforced
+- Run /ck:journal on completion
+
+## Design Gate (auto/parallel modes)
+
+Only user approval gate in auto mode. Wireframes generated as HTML at `./docs/wireframe/`.
+If rejected, iterate until approved. Full mode gates every phase; fast mode skips all gates.
+
+## Shared Phases (Step 5-7)
+
+After planning, ck:cook handles: implementation → testing → code review.
+Then bootstrap resumes: docs-manager creates README, codebase-summary, code-standards,
+system-architecture. project-manager creates roadmap. Onboarding guides user (1 question
+at a time). Final report summarizes all changes + suggests next steps.
diff --git a/docs/ck-architecture/ck-brainstorm.md b/docs/ck-architecture/ck-brainstorm.md
@@ -0,0 +1,47 @@
+# /ck:brainstorm — Solution Brainstorming
+
+Source: `~/.claude/skills/brainstorm/SKILL.md`
+
+## Authoritative Flow
+
+```
+1. Scout — ck:scout to discover project context
+2. Clarify — AskUserQuestion for requirements
+3. Scope Assessment — 3+ subsystems? → decompose into sub-projects
+4. Research — gather info from agents + external sources
+5. Analysis — evaluate 2-3 viable approaches with pros/cons
+6. Debate — present options, challenge user preferences (brutal honesty)
+7. Consensus — align on chosen approach
+8. Documentation — create comprehensive markdown summary report
+9. Finalize — ask if user wants implementation plan
+   → Yes: run /ck:plan
+   → No: end session
+10. Journal — /ck:journal
+```
+
+## Skills Activated
+
+| Type | Skill |
+|------|-------|
+| Mandatory | ck:scout |
+| Conditional | /ck:plan (if user approves → plan), /ck:journal |
+| Optional | ck:sequential-thinking, ck:docs-seeker, ck:ai-multimodal |
+
+## Sub-agents
+
+No dedicated sub-agents spawned. Main agent handles all phases directly.
+Consults planner and docs-manager agents but doesn't spawn them via Task tool.
+
+## Mode Selection
+
+None — single mode (brutal honesty brainstorming).
+
+## Complexity Routing
+
+Scope-based only:
+- 3+ independent subsystems → decompose into sub-projects
+- Each sub-project gets independent brainstorm → plan → implement cycle
+
+## Hard Gate
+
+No implementation until design presented and approved.
diff --git a/docs/ck-architecture/ck-code-review.md b/docs/ck-architecture/ck-code-review.md
@@ -0,0 +1,63 @@
+# /ck:code-review — Adversarial Code Review
+
+Source: `~/.claude/skills/code-review/SKILL.md`
+
+## Authoritative Flow
+
+```
+1. Input Resolution — auto-detect mode from arguments (PR#, commit, --pending, codebase, default)
+   → If ambiguous/no args: AskUserQuestion to select review target
+2. Diff Acquisition — fetch diff via gh pr diff / git show / git diff per mode
+3. Stage 1: Spec Compliance — does code match what was requested? (references/spec-compliance-review.md)
+   → MUST pass before Stage 2
+4. Edge Case Scouting — invoke /ck:scout with edge-case focus
+5. Stage 2: Code Quality — spawn code-reviewer sub-agent (standards, security, performance)
+6. Stage 3: Adversarial Review — spawn adversarial reviewer sub-agent (references/adversarial-review.md)
+   → Scope gate: skip if ≤2 files, ≤30 lines, no security files
+   → Red-team: security holes, false assumptions, race conditions, resource exhaustion
+   → Verdicts per finding: Accept (must fix) / Reject (false positive) / Defer (GitHub issue)
+7. Verification Gates — run build/test commands, confirm 0 failures before any completion claim
+8. Output — review report with findings, severity, verdicts; critical findings block merge
+```
+
+## Skills Activated
+
+| Type | Skill |
+|------|-------|
+| Mandatory | ck:scout (edge case scouting) |
+| Conditional | ck:sequential-thinking (complex reasoning) |
+| Optional | ck:docs-seeker (library API verification) |
+
+## Sub-agents
+
+| Agent | When | Purpose |
+|-------|------|---------|
+| code-reviewer | Stage 2 | Code quality review (standards, security, performance) |
+| adversarial-reviewer | Stage 3 | Red-team analysis to actively break code |
+| Parallel code-reviewers | Multi-file (3+) | Scoped reviewers for independent file groups (e.g. backend + frontend) |
+
+## Input Modes
+
+| Input | Mode | What Gets Reviewed |
+|-------|------|--------------------|
+| `#123` or PR URL | PR | Full PR diff via `gh pr diff` |
+| `abc1234` (7+ hex) | Commit | Single commit diff via `git show` |
+| `--pending` | Pending | Staged + unstaged via `git diff` |
+| *(no args)* | Default | Recent changes in context |
+| `codebase` | Codebase | Full codebase scan |
+| `codebase parallel` | Codebase+ | Parallel multi-reviewer audit |
+
+## Hard Gates
+
+1. **Spec compliance MUST pass** before code quality review (Stage 1 → Stage 2).
+2. **Adversarial review runs on EVERY review** — no exceptions (scope gate exempts trivial changes).
+3. **NO completion claims without fresh verification evidence** — tests pass, build succeeds, original symptom resolved.
+4. **Critical findings block merge** — must fix before proceeding.
+5. **Re-review cycle limit: 3** — escalate to user after 3 failed cycles.
+
+## Task-Managed Pipeline (3+ files)
+
+```
+scout → review → adversarial → fix → verify
+```
+Each step is a Task with dependency chain. Parallel scoped reviewers for independent file groups. Fix task blocks on all reviewers completing.
diff --git a/docs/ck-architecture/ck-cook.md b/docs/ck-architecture/ck-cook.md
@@ -0,0 +1,63 @@
+# /ck:cook — Build Feature Pipeline
+
+Source: `~/.claude/skills/cook/SKILL.md` + `references/`
+
+## Authoritative Flow
+
+```
+Step 0: Intent Detection → mode routing
+Step 1: Research (skip if fast/code) → [Review Gate 1]
+Step 2: Planning → plan.md + phase-XX.md → [Review Gate 2]
+Step 3: Implementation → execute phase tasks → [Review Gate 3]
+Step 4: Testing (skip if no-test) → tester subagent, 100% pass → [Review Gate 4]
+Step 5: Code Review → code-reviewer subagent, fix/approve cycle → [Review Gate 5]
+Step 6: Finalize (MANDATORY) → project-manager + docs-manager + git-manager + journal
+```
+
+## Mode Selection
+
+| Mode | Flag/Trigger | Research | Test | Review Gates | Parallel |
+|------|-------------|----------|------|-------------|----------|
+| interactive | Default | Yes | Yes | Stops for approval | No |
+| auto | --auto | Yes | Yes | Skip (auto-approve ≥9.5) | Yes |
+| fast | --fast | Skip | Yes | Stops | No |
+| parallel | --parallel / 3+ features | Yes | Yes | Stops | Yes |
+| no-test | --no-test | Yes | Skip | Stops | No |
+| code | Path to plan.md | Skip | Yes | Per plan | Per plan |
+
+Detection priority: explicit flags → plan path → keywords → feature count → default interactive.
+
+## Skills Activated
+
+| Type | Skill |
+|------|-------|
+| Entry | ck:cook (self-activates before every feature/fix/plan) |
+| Step 1 | ck:scout (codebase search) |
+| Step 2 | ck:plan (generate plan files) |
+| Step 6 | /ck:journal |
+
+## Sub-agents Spawned
+
+| Phase | Agent | Mandatory |
+|-------|-------|-----------|
+| Research | researcher | Optional (not in fast/code) |
+| Planning | planner | Optional (not in code) |
+| UI Work | ui-ux-designer | Conditional (if frontend) |
+| Testing | tester | Yes (except no-test) |
+| Debug | debugger | Conditional (if tests fail) |
+| Code Review | code-reviewer | Yes |
+| Finalize | project-manager | Yes |
+| Finalize | docs-manager | Yes |
+| Finalize | git-manager | Yes |
+
+Step 6 incomplete without ALL 3 finalize subagents.
+
+## Review Cycle
+
+- Max 3 fix cycles before escalate to user
+- Auto-approve threshold: score ≥9.5 AND 0 critical issues
+- 100% test pass required before code review (except no-test)
+
+## Hard Gate
+
+No implementation without approved plan (unless user overrides with "just code it").
diff --git a/docs/ck-architecture/ck-deploy.md b/docs/ck-architecture/ck-deploy.md
@@ -0,0 +1,56 @@
+# /ck:deploy — Auto-Detect Deploy Pipeline
+
+Source: `~/.claude/skills/deploy/SKILL.md` + `references/`
+
+## Authoritative Flow (from SKILL.md)
+
+```
+Step 1:  Detect target     → Read docs/deployment.md, scan config files, analyze project type
+Step 2:  Platform recommend → Cost-optimized suggestion based on project type + free tiers
+Step 3:  User confirmation  → AskUserQuestion with top 4 platform options (if no auto-detect)
+Step 4:  CLI setup          → Check/install platform CLI, check/run auth login
+Step 5:  Deploy execution   → Run platform-specific deploy command
+Step 6:  Verify + docs      → Check deployment URL, create/update docs/deployment.md
+Step 7:  Troubleshooting    → Auto-fix common errors or escalate to /ck:devops
+```
+
+## Detection Signals (14 platforms)
+
+| File/Pattern | Platform |
+|---|---|
+| `vercel.json`, `.vercel/` | Vercel |
+| `netlify.toml`, `_redirects` | Netlify |
+| `wrangler.toml` | Cloudflare |
+| `fly.toml` | Fly.io |
+| `railway.json` | Railway |
+| `render.yaml` | Render |
+| `Procfile` + `app.json` | Heroku |
+| `tose.yaml` | TOSE.sh |
+| `docker-compose.yml` + coolify ref | Coolify |
+| `dokploy.yml` | Dokploy |
+| `.github/workflows/*pages*` | Github Pages |
+| `app.yaml` (GAE) | GCP |
+| `amplify.yml` / `buildspec.yml` | AWS |
+| `.do/app.yaml` | Digital Ocean |
+
+## Platform Priority (Cost-Optimized)
+
+**Free (static):** Github Pages → Cloudflare Pages → Vercel → Netlify
+**Free (backend):** Railway ($5 credit) → Render (750h) → Fly.io (3 VMs)
+**Pay-as-you-go:** TOSE.sh → Cloudflare Workers → Railway
+**Self-hosted:** Coolify → Dokploy
+**Enterprise:** AWS, GCP, Digital Ocean, Vultr, Heroku
+
+## Scope Boundaries
+
+- **Handles:** deployment, platform selection, deployment docs
+- **Does NOT handle:** infra provisioning, DB migrations, DNS, SSL, CI/CD pipelines
+- **Escalation:** unresolvable errors → `/ck:devops`
+
+## Reference Loading
+
+Progressive disclosure — loads ONLY the platform reference needed from `references/platforms/{name}.md`.
+
+## Post-Deploy Output
+
+Creates/updates `docs/deployment.md` with: platform, URL, deploy command, env vars, custom domain setup, rollback instructions.
diff --git a/docs/ck-architecture/ck-fix.md b/docs/ck-architecture/ck-fix.md
@@ -0,0 +1,88 @@
+# /ck:fix — Bug Fix Pipeline
+
+Source: `~/.claude/skills/fix/SKILL.md` + `references/`
+
+## Authoritative Flow (from SKILL.md mermaid diagram)
+
+```
+Step 0: Mode Selection → auto | review | quick (AskUserQuestion)
+Step 1: Scout (MANDATORY) → ck:scout skill OR 2-3 parallel Explore subagents
+Step 2: Diagnose (MANDATORY) → ck:debug + ck:sequential-thinking + debugger subagent
+  └─ Complexity Assessment happens HERE (implicit, not a separate step)
+Step 3: Route to workflow based on complexity
+Step 4: Fix Implementation
+Step 5: Verify + Prevent (MANDATORY)
+Step 6: Finalize
+```
+
+## Complexity Assessment
+
+Happens AFTER Scout + Diagnose (not before). Source: `references/complexity-assessment.md`
+
+| Level | Indicators | Workflow | Task Phases |
+|-------|------------|----------|-------------|
+| Simple | 1 file, clear error (type/lint) | workflow-quick.md | 5 steps, no Tasks |
+| Moderate | 2-5 files, multi-file fix | workflow-standard.md | 6 phases with Tasks |
+| Complex | 5+ files, architecture impact | workflow-deep.md | 9 phases with Tasks |
+| Parallel | 2+ independent issues or --parallel flag | Multiple fullstack-developer agents | Separate task trees |
+
+## Workflow Differences
+
+### Quick (Simple)
+1. Scout (minimal — file + direct deps only)
+2. Diagnose (abbreviated — ck:debug + ck:sequential)
+3. Fix + Verify (combined step, parallel Bash for typecheck+lint)
+4. Review (code-reviewer subagent) + Prevention (abbreviated)
+5. Complete (git-manager if autonomous)
+
+### Standard (Moderate) — 6 Task Phases
+1. Scout → ck:scout OR parallel Explore subagents
+2. Diagnose → ck:debug + ck:sequential + debugger subagent + Explore
+3. Implement fix
+4. Verify + Prevent → tester subagent + parallel Bash (typecheck/lint/build/test)
+5. Code Review → code-reviewer subagent
+6. Finalize → ck:project-management + docs-manager + git-manager + journal
+
+### Deep (Complex) — 9 Task Phases
+1-2-3. Scout + Diagnose + Research (PARALLEL) → researcher subagent
+4. Brainstorm → ck:brainstorm skill
+5. Plan → planner subagent
+6. Implement fix
+7. Verify + Prevent → tester + parallel Bash
+8. Code Review → code-reviewer subagent
+9. Finalize → ck:project-management + docs-manager + git-manager + journal
+
+## Sub-agents Spawned by Workflow
+
+### Standard (shown in VividKit guide)
+
+| Step | Sub-agents | Type |
+|------|------------|------|
+| Scout | 2-3 Explore | Built-in subagent type |
+| Diagnose | debugger + Explore | CK agent + built-in |
+| Verify | tester + parallel Bash | CK agent + built-in |
+| Review | code-reviewer | CK agent |
+| Finalize | docs-manager + git-manager + project-manager | CK agents |
+
+### Deep (additional agents)
+
+| Step | Sub-agents | Type |
+|------|------------|------|
+| Research | researcher | CK agent (parallel with Scout+Diagnose) |
+| Brainstorm | (main agent, ck:brainstorm skill) | — |
+| Plan | planner | CK agent |
+
+### Parallel (additional agents)
+
+| Step | Sub-agents | Type |
+|------|------------|------|
+| Per-issue | fullstack-developer (one per independent issue) | CK agent |
+
+## VividKit Guide Design Decisions
+
+1. Pipeline shows the **Standard workflow** as default (most representative)
+2. Complexity Routing is NOT a separate step — implicit after Diagnose
+3. Mode Selection is part of user input step (flags + interactive prompt)
+4. Steps that spawn sub-agents are visually indented with "spawned by main agent" label
+5. Deep/Parallel workflow details shown in Diagnose explain text (not separate UI branches)
+6. Conditional skills (ck:context-engineering, ck:ai-multimodal) not shown — too edge-case for overview