From 2bb71ed5de13bb8844491985ca46fe57eb827192 Mon Sep 17 00:00:00 2001 From: Thieu Nguyen Date: Tue, 7 Apr 2026 01:04:10 +0700 Subject: [PATCH 1/4] feat(guides): add how-ck-works interactive guide with 20 workflow scenarios - Add interactive workflow visualizer for ClaudeKit command pipelines - 12 Engineer Kit scenarios: brainstorm, plan, cook, fix, frontend-design, ship, code-review, test, deploy, predict, bootstrap, security - 8 Marketer Kit scenarios: write:*, design, seo:*, campaign:*, social:*, email:*, persona, video:* - Compact pill-tag scenario selector with kit grouping - Step-by-step pipeline view with play/pause animation - Drill-down detail panel with explain + code tabs - 22 architecture reference docs in docs/ck-architecture/ - Bilingual EN/VI support throughout --- docs/ck-architecture/ck-bootstrap.md | 69 + docs/ck-architecture/ck-brainstorm.md | 47 + docs/ck-architecture/ck-code-review.md | 63 + docs/ck-architecture/ck-cook.md | 63 + docs/ck-architecture/ck-deploy.md | 56 + docs/ck-architecture/ck-fix.md | 88 + docs/ck-architecture/ck-frontend-design.md | 64 + docs/ck-architecture/ck-plan.md | 68 + docs/ck-architecture/ck-predict.md | 64 + docs/ck-architecture/ck-security-scan.md | 56 + docs/ck-architecture/ck-ship.md | 67 + docs/ck-architecture/ck-test.md | 61 + docs/ck-architecture/ckm-campaign.md | 77 + docs/ck-architecture/ckm-design.md | 66 + docs/ck-architecture/ckm-email.md | 74 + docs/ck-architecture/ckm-persona.md | 64 + docs/ck-architecture/ckm-seo.md | 67 + docs/ck-architecture/ckm-social.md | 63 + docs/ck-architecture/ckm-video.md | 72 + docs/ck-architecture/ckm-write.md | 65 + .../ck-architecture/claudekit-architecture.md | 30 + docs/ck-architecture/shared-concepts.md | 55 + src/components/guides/TabNavigation.astro | 10 +- .../guides/how-ck-works/HowCkWorksGuide.astro | 272 +++ .../how-ck-works/workflow-pipeline-view.astro | 196 ++ .../workflow-scenario-selector.astro | 110 ++ .../workflow-step-detail-panel.astro | 84 + src/data/guides/how-ck-works/index.ts | 4 + .../workflow-visualizer-scenarios.ts | 1707 +++++++++++++++++ .../how-ck-works/workflow-visualizer-types.ts | 81 + src/i18n/en/guides.ts | 2 + src/i18n/vi/guides.ts | 2 + src/layouts/GuidesLayout.astro | 2 +- src/pages/guides/how-ck-works.astro | 15 + src/pages/vi/guides/how-ck-works.astro | 15 + 35 files changed, 3896 insertions(+), 3 deletions(-) create mode 100644 docs/ck-architecture/ck-bootstrap.md create mode 100644 docs/ck-architecture/ck-brainstorm.md create mode 100644 docs/ck-architecture/ck-code-review.md create mode 100644 docs/ck-architecture/ck-cook.md create mode 100644 docs/ck-architecture/ck-deploy.md create mode 100644 docs/ck-architecture/ck-fix.md create mode 100644 docs/ck-architecture/ck-frontend-design.md create mode 100644 docs/ck-architecture/ck-plan.md create mode 100644 docs/ck-architecture/ck-predict.md create mode 100644 docs/ck-architecture/ck-security-scan.md create mode 100644 docs/ck-architecture/ck-ship.md create mode 100644 docs/ck-architecture/ck-test.md create mode 100644 docs/ck-architecture/ckm-campaign.md create mode 100644 docs/ck-architecture/ckm-design.md create mode 100644 docs/ck-architecture/ckm-email.md create mode 100644 docs/ck-architecture/ckm-persona.md create mode 100644 docs/ck-architecture/ckm-seo.md create mode 100644 docs/ck-architecture/ckm-social.md create mode 100644 docs/ck-architecture/ckm-video.md create mode 100644 docs/ck-architecture/ckm-write.md create mode 100644 docs/ck-architecture/claudekit-architecture.md create mode 100644 docs/ck-architecture/shared-concepts.md create mode 100644 src/components/guides/how-ck-works/HowCkWorksGuide.astro create mode 100644 src/components/guides/how-ck-works/workflow-pipeline-view.astro create mode 100644 src/components/guides/how-ck-works/workflow-scenario-selector.astro create mode 100644 src/components/guides/how-ck-works/workflow-step-detail-panel.astro create mode 100644 src/data/guides/how-ck-works/index.ts create mode 100644 src/data/guides/how-ck-works/workflow-visualizer-scenarios.ts create mode 100644 src/data/guides/how-ck-works/workflow-visualizer-types.ts create mode 100644 src/pages/guides/how-ck-works.astro create mode 100644 src/pages/vi/guides/how-ck-works.astro diff --git a/docs/ck-architecture/ck-bootstrap.md b/docs/ck-architecture/ck-bootstrap.md new file mode 100644 index 0000000..c1ed4d9 --- /dev/null +++ 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 new file mode 100644 index 0000000..dd7314e --- /dev/null +++ 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 new file mode 100644 index 0000000..2841f44 --- /dev/null +++ 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 new file mode 100644 index 0000000..e37b878 --- /dev/null +++ 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 new file mode 100644 index 0000000..dcaab32 --- /dev/null +++ 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 new file mode 100644 index 0000000..e4fd733 --- /dev/null +++ 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 diff --git a/docs/ck-architecture/ck-frontend-design.md b/docs/ck-architecture/ck-frontend-design.md new file mode 100644 index 0000000..cd56803 --- /dev/null +++ b/docs/ck-architecture/ck-frontend-design.md @@ -0,0 +1,64 @@ +# /ck:frontend-design — Polished Frontend Interface Creation + +Source: `~/.claude/skills/frontend-design/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user provides design brief, screenshot, video, or description +Step 2: Workflow Selection — route to appropriate workflow based on input type + (screenshot | video | describe | 3D | quick | immersive | redesign | from-scratch) +Step 3: Activate ck:ui-ux-pro-max — design intelligence (mandatory for all workflows) +Step 4: Analyze — if screenshot/video: ck:ai-multimodal extracts colors, fonts, spacing, effects +Step 5: Design Thinking — bold aesthetic direction (tone, purpose, differentiation) + Configure Design Dials: DESIGN_VARIANCE(8), MOTION_INTENSITY(6), VISUAL_DENSITY(4) +Step 6: Plan — ui-ux-designer sub-agent creates phased implementation plan +Step 7: Implement — production-grade code with anti-slop checks +Step 8: Verify — compare to original/brief, run anti-slop checklist +Step 9: Document — update docs/design-guidelines.md if approved +``` + +## Skills Activated + +| Type | Skill | +|------|-------| +| Mandatory | ck:ui-ux-pro-max (design intelligence, activated FIRST) | +| Mandatory | ck:ai-multimodal (asset generation via Imagen/Nano Banana, visual analysis via Gemini) | +| Optional | ck:media-processing (image optimization, format conversion) | +| Optional | ck:threejs (for 3D/WebGL workflow) | + +## Sub-agents + +- **ui-ux-designer** — spawned for phased implementation planning +- Main agent handles implementation directly (no fullstack-developer sub-agent) + +## Workflow Selection (7 workflows) + +| Input | Workflow | Key difference | +|-------|----------|----------------| +| Screenshot | workflow-screenshot.md | Pixel-perfect replication | +| Video | workflow-video.md | Replication + animations | +| Describe only | workflow-describe.md | Document for devs, no code | +| 3D/WebGL | workflow-3d.md | Three.js immersive experience | +| Quick task | workflow-quick.md | Rapid implementation | +| Complex/award | workflow-immersive.md | Full immersive, max quality | +| Existing upgrade | redesign-audit-checklist.md | Audit + improve existing | + +## Design Dials + +Three configurable parameters driving design decisions: +- `DESIGN_VARIANCE` (default 8) — symmetry vs asymmetry +- `MOTION_INTENSITY` (default 6) — hover states vs spring physics +- `VISUAL_DENSITY` (default 4) — art gallery vs cockpit density + +## Hard Gate + +Anti-slop checklist MUST pass before delivery. Forbidden: Inter/Roboto fonts, AI purple gradients, 3-column equal cards, "John Doe" content, neon glows. + +## Key References + +- `anti-slop-rules.md` — forbidden AI patterns +- `premium-design-patterns.md` — quality benchmarks +- `magicui-components.md` — 80+ component library +- `bento-motion-engine.md` — SaaS dashboard patterns +- `performance-guardrails.md` — animation/blur perf limits diff --git a/docs/ck-architecture/ck-plan.md b/docs/ck-architecture/ck-plan.md new file mode 100644 index 0000000..43ced67 --- /dev/null +++ b/docs/ck-architecture/ck-plan.md @@ -0,0 +1,68 @@ +# /ck:plan — Implementation Planning + +Source: `~/.claude/skills/ck-plan/SKILL.md` + `references/` + +## Authoritative Flow + +``` +Pre-Creation Check → active/suggested/no plan context +Cross-Plan Scan → detect blockedBy/blocks relationships +Step 0: Scope Challenge (skip if --fast or trivial) +Mode Detection → fast | hard | parallel | two +Codebase Analysis → read docs, scout if stale (hard/parallel/two only) +Plan Creation → planner subagent writes plan.md + phase-XX.md +Red Team Review → 2-4 code-reviewer agents (hard/parallel/two only) +Validation → interview with critical questions (hard/parallel/two only) +Task Hydration → TaskCreate per phase + critical steps +Output Cook Command → absolute path, mode-specific flags (MANDATORY) +Journal → /ck:journal +``` + +## Mode Selection + +Auto-detection or manual flags: + +| Mode | Flag | Research | Red Team | Validate | Task Hydrate | +|------|------|----------|----------|----------|-------------| +| Fast | --fast | Skip | Skip | Skip | Phase-level | +| Hard | --hard | 2 researchers | 2-4 reviewers | Yes | Phase + steps | +| Parallel | --parallel | 2 researchers | 2-4 reviewers | Yes | + ownership matrix | +| Two | --two | 2 researchers | 2-4 reviewers | Yes | Selected approach | + +## Skills Activated + +| Type | Skill | +|------|-------| +| Mandatory | /ck:project-organization | +| Conditional | ck:scout (if docs stale), ck:sequential-thinking, ck:docs-seeker | +| End-of-flow | /ck:journal | + +## Sub-agents Spawned + +| Phase | Agent | Condition | +|-------|-------|-----------| +| Research | 2x researcher | hard/parallel/two only | +| Plan Creation | planner | Always | +| Red Team | 2-4x code-reviewer | hard/parallel/two only | + +Red Team scaling: +- 1-2 phases → 2 reviewers +- 3-5 phases → 3 reviewers +- 6+ phases → 4 reviewers + +## Task Hydration + +- ON by default, skip with --no-tasks or <3 phases +- TaskCreate per phase with dependencies (addBlockedBy) +- Critical steps get separate tasks with riskLevel metadata + +## Output + +MANDATORY: output cook command with absolute path +- Fast: `/ck:cook --auto {path}/plan.md` +- Hard: `/ck:cook {path}/plan.md` +- Parallel: `/ck:cook --parallel {path}/plan.md` + +## Hard Gate + +No code implementation — ck:plan only creates plans. diff --git a/docs/ck-architecture/ck-predict.md b/docs/ck-architecture/ck-predict.md new file mode 100644 index 0000000..3e5d56f --- /dev/null +++ b/docs/ck-architecture/ck-predict.md @@ -0,0 +1,64 @@ +# /ck:predict — Multi-Persona Pre-Analysis + +Source: `~/.claude/skills/ck-predict/SKILL.md` + +## Authoritative Flow + +``` +1. Input — read proposed change/feature description +2. Hooks Fire — context injection (session-init, dev-rules-reminder) +3. Read Codebase — grep affected areas if --files provided +4. Independent Analysis — 5 personas analyze in parallel +5. Agreement Check — identify points where 4+ personas align +6. Conflict Resolution — weigh tradeoffs for disagreements +7. Verdict — GO / CAUTION / STOP with recommendations +``` + +## The 5 Personas + +| Persona | Focus | +|---------|-------| +| Architect | System design, scalability, coupling | +| Security | Attack surface, data protection, auth | +| Performance | Latency, memory, queries, bundle size | +| UX | User experience, accessibility, error states | +| Devil's Advocate | Hidden assumptions, simpler alternatives | + +## Skills Activated + +| Type | Skill | +|------|-------| +| Downstream | ck:scenario (feed risk rows), ck:plan (attach recommendations), ck:cook (CAUTION/STOP as gates) | + +## Sub-agents + +No dedicated sub-agents spawned. Main agent simulates all 5 personas internally. +Analysis is sequential within a single context window. + +## Mode Selection + +None — single mode (5-persona debate). + +## Complexity Routing + +None — all proposals get full 5-persona treatment regardless of size. + +## Verdict Levels + +| Verdict | Meaning | +|---------|---------| +| GO | All aligned, no critical risks | +| CAUTION | Concerns manageable with mitigations | +| STOP | Critical unresolved issue, needs redesign | + +## STOP Triggers + +Any one sufficient: +- Security: auth bypass or data exposure with no mitigation +- Architect: fundamental design incompatibility +- Performance: unacceptable latency/query explosion +- Devil's Advocate: false assumption invalidates approach + +## Hard Gate + +Any STOP trigger blocks implementation until resolved. diff --git a/docs/ck-architecture/ck-security-scan.md b/docs/ck-architecture/ck-security-scan.md new file mode 100644 index 0000000..1ed2ff9 --- /dev/null +++ b/docs/ck-architecture/ck-security-scan.md @@ -0,0 +1,56 @@ +# /ck:security — Security Audit (STRIDE + OWASP) + +Source: `~/.claude/skills/ck-security/SKILL.md` + +## Authoritative Flow + +``` +1. Scope Resolution — expand glob or `full` keyword into file list, read all in-scope files +2. STRIDE Analysis — evaluate 6 threat categories systematically: + S=Spoofing, T=Tampering, R=Repudiation, I=Info Disclosure, D=DoS, E=Elevation +3. OWASP Top 10 Check — map findings to A01–A10 categories + → Uses references/stride-owasp-checklist.md for per-category checks +4. Dependency Audit — run stack-appropriate tool (npm audit / pip-audit / govulncheck / bundle audit) +5. Secret Detection — regex scan for API keys, passwords, tokens, private keys + → Redact values in output (first 4 + last 2 chars only) +6. Finding Categorization — assign severity (Critical → High → Medium → Low → Info) +7. Output — severity-ranked findings report with fix recommendations +8. [--fix] Iterative Fix — sort by severity, apply one fix at a time, guard with tests + → Uses ck:autoresearch pattern for regression prevention + → Commit each fix: `security(fix-N): ` + → Stop early if guard fails +``` + +## Modes + +| Mode | Invocation | Behavior | +|------|-----------|----------| +| Audit only | `/ck:security ` | Scan → categorize → report | +| Audit + Fix | `/ck:security --fix` | Scan → categorize → fix iteratively | +| Bounded fix | `/ck:security --fix --iterations N` | Cap fix iterations to N | + +## Severity Definitions + +| Severity | Description | Fix Priority | +|----------|-------------|-------------| +| Critical | Exploitable now, data breach/RCE risk | Immediate — block release | +| High | Exploitable with moderate effort | This sprint | +| Medium | Limited exploitability or impact | Next sprint | +| Low | Theoretical risk, defense-in-depth | Backlog | +| Info | Best practice suggestion | Optional | + +## Integration with Other Skills + +| Skill | Relationship | +|-------|-------------| +| ck:predict | Run security audit when predict's security persona flags concerns | +| ck:autoresearch | Feed Critical/High findings for automated remediation (--fix mode) | +| ck:scenario | Deeper auth flow testing with `--focus authorization` | +| ck:plan | Schedule Medium/Low findings as sprint tasks | + +## Hard Gates + +1. **Secret redaction** — NEVER output actual secret values in reports. +2. **No auto-modification without --fix** — audit-only mode is read-only. +3. **Guard must pass** — each fix iteration verified by tests before proceeding. +4. **Real credential found** — recommend immediate rotation. diff --git a/docs/ck-architecture/ck-ship.md b/docs/ck-architecture/ck-ship.md new file mode 100644 index 0000000..5dda4ea --- /dev/null +++ b/docs/ck-architecture/ck-ship.md @@ -0,0 +1,67 @@ +# /ck:ship — Unified Ship Pipeline + +Source: `~/.claude/skills/ship/SKILL.md` + `references/` + +## Authoritative Flow (from SKILL.md) + +``` +Step 1: Pre-flight → Branch check, mode detection, diff analysis +Step 2: Link Issues → Find/create GitHub issues for traceability +Step 3: Merge target → Fetch + merge origin/ +Step 4: Run tests → Auto-detect test runner, delegate to tester subagent +Step 5: Pre-landing review→ Two-pass checklist (critical + informational) via code-reviewer +Step 6: Version bump → Auto-detect version file, bump patch/minor (conditional) +Step 7: Changelog → Auto-generate from commits + diff (conditional) +Step 8: Journal → Write technical journal via ck:journal (background) +Step 9: Docs update → Update project docs via ck:docs (official only, background) +Step 10: Commit → Conventional commit with security scan +Step 11: Push → git push -u origin (never force push) +Step 12: Create PR → gh pr create with linked issues +``` + +## Mode Selection + +| Argument | Target Branch | Pipeline | +|----------|--------------|----------| +| `official` | main/master (auto-detect) | Full: tests + review + version + changelog + journal + docs | +| `beta` | dev/beta/develop (auto-detect) | Lighter: skips docs update (Step 9) | +| (none) | Infer from branch name | feature/* hotfix/* → official; dev/* beta/* → beta; unclear → AskUserQuestion | + +## Skills Activated + +- `ck:journal` — technical journal entry (Step 8, background) +- `ck:docs update` — project docs sync (Step 9, official only, background) + +## Sub-agents Spawned + +| Step | Sub-agent | Type | Notes | +|------|-----------|------|-------| +| Step 4 | tester | CK agent | Runs auto-detected test suite | +| Step 5 | code-reviewer | CK agent | Two-pass: critical (security/auth) + informational | +| Step 8 | journal-writer | CK agent | Background, non-blocking | +| Step 9 | docs-manager | CK agent | Background, official mode only | + +## Hard Gates (pipeline stops) + +1. **On target branch** — abort immediately +2. **Merge conflicts** (non-trivial) — stop, show conflicts +3. **Test failures** — stop, show failures +4. **Critical review issues** — AskUserQuestion per issue (fix/acknowledge/skip) +5. **Secrets in staged diff** — stop, warn user +6. **Major/minor version bump** — AskUserQuestion + +## Auto-continue (no user input needed) + +- Uncommitted changes → always included +- Patch version bump → auto-decide +- Changelog/commit message → auto-generate +- No version file / no changelog → skip silently +- Push rejected → suggest rebase, retry once + +## Token Efficiency + +- Steps 4+5: delegated to subagents (not inlined) +- Steps 8+9: run in background (non-blocking) +- Step 2: single gh command batch +- Beta mode auto-skips Step 9 +- Skip flags reduce pipeline length diff --git a/docs/ck-architecture/ck-test.md b/docs/ck-architecture/ck-test.md new file mode 100644 index 0000000..7180ed6 --- /dev/null +++ b/docs/ck-architecture/ck-test.md @@ -0,0 +1,61 @@ +# /ck:test — Testing & Quality Assurance + +Source: `~/.claude/skills/test/SKILL.md` + +## Authoritative Flow + +``` +1. Mode Select — AskUserQuestion: code tests vs UI tests (skip if arg provided) +2. Hooks Fire — context injection (session-init, dev-rules-reminder, subagent-init) +3. Typecheck — run typecheck/analyze to catch syntax errors first +4. Execute Tests — run appropriate test suite (Jest/Vitest/pytest/go test/etc.) +5. Analyze Results — focus on failures, identify root causes +6. Coverage Report — generate coverage metrics (Istanbul/c8/pytest-cov/go cover) +7. UI Tests (conditional) — ck:chrome-devtools for screenshots, a11y, responsive +8. Screenshot Analysis (conditional) — ck:ai-multimodal for visual regression +9. Debug (conditional) — ck:debug for complex test failure investigation +10. QA Report — structured summary with metrics & recommendations +11. Organize — /ck:project-organization for output placement +``` + +## Skills Activated + +| Type | Skill | +|------|-------| +| Mandatory | (none — test runners invoked via Bash) | +| Conditional | ck:chrome-devtools (UI tests), ck:ai-multimodal (screenshot analysis) | +| Conditional | ck:debug (failure investigation), ck:sequential-thinking (complex analysis) | +| Conditional | /ck:project-organization (report output) | + +## Sub-agents + +No dedicated sub-agents spawned by default. Main agent runs test commands directly. +For UI testing, ck:chrome-devtools skill may spawn browser automation sub-agents. + +## Mode Selection + +Two modes selected via AskUserQuestion (or argument): +- **Code tests** (default) — unit/integration/e2e via test runners +- **UI tests** (`ui` arg) — browser-based visual testing via ck:chrome-devtools + +## Hard Gates + +- **NEVER ignore failing tests** — fix root causes, not symptoms +- **No mocks/cheats/tricks** to pass builds +- **All critical paths** must have test coverage +- **Test isolation** — no interdependencies between tests +- **Deterministic & reproducible** — tests must be repeatable + +## Supported Runners + +JS/TS: Jest, Vitest, Mocha | Python: pytest | Go: go test | Rust: cargo test | Flutter: flutter test + +## Report Format + +Structured QA report: test results overview, coverage metrics, failed tests detail, +performance data, build status, recommendations. + +## Team Mode + +When operating as teammate: claim tasks via TaskList/TaskUpdate, respect file ownership +(test files only), wait for implementation tasks to complete before testing. diff --git a/docs/ck-architecture/ckm-campaign.md b/docs/ck-architecture/ckm-campaign.md new file mode 100644 index 0000000..07c7cad --- /dev/null +++ b/docs/ck-architecture/ckm-campaign.md @@ -0,0 +1,77 @@ +# /ckm:campaign:* — Campaign Planning & Execution + +Source: `reference/marketing-stable/.claude/skills/campaign/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:campaign: +Step 2: Route — parse subcommand (create|status|analyze|email), load references/.md +Step 3: Brand Context — inject-brand-context.cjs reads user's docs/brand-guidelines.md +Step 4: Execute action-specific workflow (varies by subcommand) +Step 5: Output — campaign assets to assets/campaigns/{date}-{slug}/ +``` + +## Subcommands (4 actions) + +| Subcommand | Purpose | Key Agents | Complexity | +|------------|---------|------------|------------| +| `create` | Create comprehensive campaign | campaign-manager, funnel-architect | Heavy | +| `status` | Track campaign progress | analytics-analyst | Light | +| `analyze` | Performance analysis + diagnostics | analytics-analyst, campaign-debugger | Medium | +| `email` | Email campaign management | campaign-manager | Medium | + +## Campaign Types Supported + +Product Launch, Seasonal/Promotional, Brand Awareness, Lead Generation, Re-engagement + +## Agents Used + +| Agent | Used By | +|-------|---------| +| campaign-manager | create, email | +| funnel-architect | create | +| analytics-analyst | status, analyze | +| campaign-debugger | analyze | + +## Skills Activated + +| Type | Skill | Used By | +|------|-------|---------| +| Always | brand-guidelines (inject-brand-context.cjs) | All subcommands | +| Conditional | analytics | status, analyze | +| Conditional | content-marketing | create, email | + +## Output Paths + +- Campaign briefs → `assets/campaigns/{date}-{slug}/briefs/` +- Campaign creatives → `assets/campaigns/{date}-{slug}/creatives/` +- Campaign reports → `assets/campaigns/{date}-{slug}/reports/` +- Analysis reports → `assets/diagnostics/campaign-audits/{date}-{name}.md` + +## Create Subcommand Detail (Heaviest Flow) + +``` +User → parse args → inject brand context + → campaign-manager agent (requirements gathering, brief creation) + → funnel-architect agent (funnel design, channel strategy) + → output briefs + creatives to assets/campaigns/ +``` + +## Analyze Subcommand Detail + +``` +User → read campaign files from assets/campaigns/ + → analytics-analyst agent (performance metrics) + → campaign-debugger agent (issue diagnosis) + → output audit report to assets/diagnostics/ +``` + +## References (Knowledge Base) + +| Topic | File | +|-------|------| +| Campaign Brief | `references/campaign-brief.md` | +| Launch Checklist | `references/launch-checklist.md` | +| Budget Allocation | `references/budget-allocation.md` | +| Optimization Framework | `references/optimization-framework.md` | diff --git a/docs/ck-architecture/ckm-design.md b/docs/ck-architecture/ckm-design.md new file mode 100644 index 0000000..ae83c06 --- /dev/null +++ b/docs/ck-architecture/ckm-design.md @@ -0,0 +1,66 @@ +# /ckm:design — Unified Design Skill + +Source: `reference/marketing-stable/.claude/skills/design/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:design +Step 2: Route — parse space-arg, match sub-skill from routing table +Step 3: Brand Context — inject-brand-context.cjs reads user's docs/brand-guidelines.md +Step 4: Execute sub-skill workflow (varies by design type) +Step 5: Output — deliver design assets (images, HTML, SVG, presentations) +``` + +## Sub-skills (9 design types) + +| Design Type | Route Target | Key Tools | Output | +|------------|--------------|-----------|--------| +| `brand` | External skill (ckm:brand) | brand skill | Brand identity, voice, assets | +| `design-system` | External skill (ckm:design-system) | design-system skill | Tokens, CSS vars, specs | +| `ui-styling` | External skill | ui-styling skill | shadcn/ui + Tailwind config | +| `logo` | Built-in | Gemini AI (generate.py), search.py | Logo images (55 styles, 30 palettes) | +| `cip` | Built-in | Gemini Flash/Pro (generate.py), render-html.py | CIP mockups (50+ deliverables) | +| `slides` | Built-in | Chart.js, HTML templates | HTML presentations | +| `banner` | Built-in | frontend-design, ai-artist, chrome-devtools | PNG banners (22 styles) | +| `social photos` | Built-in | ui-ux-pro-max, chrome-devtools, Playwright | Multi-platform social images | +| `icon` | Built-in | Gemini 3.1 Pro (generate.py) | SVG icons (15 styles) | + +## Skills Activated + +| Type | Skill | Used By | +|------|-------|---------| +| Core | brand | brand identity sub-skill | +| Core | design-system | tokens sub-skill | +| Core | ui-styling | UI styling sub-skill | +| Conditional | ai-artist | banner (visual generation) | +| Conditional | ai-multimodal | banner, social photos (image gen) | +| Conditional | frontend-design | banner, social photos (HTML/CSS) | +| Conditional | ui-ux-pro-max | social photos, logo (HTML preview) | +| Conditional | chrome-devtools | banner, social photos (screenshot export) | +| Conditional | project-management | social photos (TODO orchestration) | +| Conditional | assets-organizing | social photos (file organization) | + +## Agents Used + +| Agent | Used By | Purpose | +|-------|---------|---------| +| Main agent | All types | Route, execute, coordinate | +| Parallel sub-agents | social photos | Independent design per platform/idea | + +## Platforms Supported + +Facebook, Twitter/X, LinkedIn, YouTube, Instagram, Pinterest, TikTok, Threads, Google Ads + +## AI Models + +| Model | Used By | +|-------|---------| +| gemini-2.5-flash-image | Logo gen (default), CIP gen (default) | +| gemini-3-pro-image-preview | CIP gen (pro mode, 4K text) | +| gemini-3.1-pro-preview | Icon gen (SVG text output) | + +## Workflows + +- **Complete Brand Package**: Logo → CIP → Slides presentation +- **New Design System**: Brand → Tokens → Tailwind/shadcn implementation diff --git a/docs/ck-architecture/ckm-email.md b/docs/ck-architecture/ckm-email.md new file mode 100644 index 0000000..9e87c2e --- /dev/null +++ b/docs/ck-architecture/ckm-email.md @@ -0,0 +1,74 @@ +# /ckm:email:* — Email Content & Automation + +Source: `reference/marketing-stable/.claude/skills/email/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:email: +Step 2: Route — parse subcommand (flow|sequence), load references/.md +Step 3: Brand Context — inject-brand-context.cjs reads user's docs/brand-guidelines.md +Step 4: Gather Context — AskUserQuestion for audience, message, CTA +Step 5: Agent Execution — email-wizard + copywriter generate content +Step 6: Output — emails to assets/copy/emails/{date}-{type}-{slug}.md +``` + +## Subcommands (2 actions) + +| Subcommand | Purpose | Key Agents | Complexity | +|------------|---------|------------|------------| +| `flow` | Email automation sequence with branches | email-wizard, copywriter | Heavy | +| `sequence` | Drip sequence with full copy | email-wizard, copywriter | Medium | + +## Email Types Supported + +newsletter, cold, followup, launch, nurture, welcome, winback + +## Flow Types (flow subcommand) + +welcome, cart, onboarding, nurture, re-engagement, upsell, renewal, webinar, custom + +## Sequence Types (sequence subcommand) + +welcome, onboarding, nurture, abandon, winback, launch + +## Agents Used + +| Agent | Used By | +|-------|---------| +| email-wizard | flow, sequence | +| copywriter | flow, sequence | + +## Skills Activated + +| Type | Skill | Used By | +|------|-------|---------| +| Always | brand-guidelines (inject-brand-context.cjs) | All subcommands | +| Always | email-marketing | flow, sequence | +| Always | copywriting | flow, sequence | +| Conditional | assets-organizing | flow | + +## Output Paths + +- Single emails → `assets/copy/emails/{date}-{type}-{slug}.md` +- Flow sequences → `assets/emails/flows/{flow-type}-{date}.md` +- Drip sequences → `assets/copy/emails/{date}-{type}-sequence/` + +## Flow Subcommand Detail (Heaviest) + +``` +User → parse flow type → inject brand context + → load automation-flows.md + subject-line-formulas.md + → email-wizard agent (sequence structure, timing, branches) + → copywriter agent (subject lines, body copy, CTAs) + → output flow + ASCII diagram + implementation notes +``` + +## References (Knowledge Base) + +| Topic | File | +|-------|------| +| Automation Flows | `references/automation-flows.md` | +| Subject Line Formulas | `references/subject-line-formulas.md` | +| Email Templates | `references/email-templates.md` | +| Deliverability Checklist | `references/deliverability-checklist.md` | diff --git a/docs/ck-architecture/ckm-persona.md b/docs/ck-architecture/ckm-persona.md new file mode 100644 index 0000000..60a5407 --- /dev/null +++ b/docs/ck-architecture/ckm-persona.md @@ -0,0 +1,64 @@ +# /ckm:persona — Customer Persona Management + +Source: `reference/marketing-stable/.claude/skills/persona/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:persona +Step 2: Parse Action — route to create|analyze|update|list workflow +Step 3: Hooks Fire — session-init, dev-rules-reminder, subagent-init +Step 4: Gather Data — AskUserQuestion collects demographics, pain points, goals, buying behavior, channels +Step 5: Agent Work — lead-qualifier defines persona; researcher validates market fit +Step 6: Skills — content-marketing frameworks, assets-organizing for output paths +Step 7: Output — ICP Profile saved to assets/leads/icp-profiles/{persona}.md +``` + +## Actions (4 variants) + +| Action | Purpose | Key Agents/Skills | Complexity | +|--------|---------|-------------------|------------| +| `create` | New persona from scratch | lead-qualifier, researcher, content-marketing | Heavy | +| `analyze` | Audience data analysis | lead-qualifier, analytics-analyst | Medium | +| `update [name]` | Revise existing persona | lead-qualifier (load + validate) | Light | +| `list` | List all personas | Main agent only | Light | + +## Agents Used + +| Agent | Used By | +|-------|---------| +| lead-qualifier | create, analyze, update | +| researcher | create (market validation) | +| analytics-analyst | analyze (behavior data) | + +## Skills Activated + +| Skill | Purpose | +|-------|---------| +| content-marketing | Persona frameworks & templates | +| assets-organizing | Standardized output paths | + +## Data Gathering (Create Flow) + +AskUserQuestion collects 5 dimensions: +1. Demographics (age, role, industry) +2. Pain points and challenges +3. Goals and motivations +4. Buying behavior +5. Preferred channels + +## Output + +- ICP Profiles → `assets/leads/icp-profiles/{persona}.md` + +## Analyze Workflow Detail + +- lead-qualifier performs audience analysis +- analytics-analyst processes behavior data +- Identifies segments and patterns +- Generates insights report + +## Hard Gate + +- `create`: All 5 data dimensions must be gathered before persona generation +- `update`: Existing persona must be loaded and validated before changes diff --git a/docs/ck-architecture/ckm-seo.md b/docs/ck-architecture/ckm-seo.md new file mode 100644 index 0000000..a16025b --- /dev/null +++ b/docs/ck-architecture/ckm-seo.md @@ -0,0 +1,67 @@ +# /ckm:seo:* — SEO Audits, Keyword Research & Optimization + +Source: `reference/marketing-stable/.claude/skills/seo/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:seo: +Step 2: Hooks — session-init, dev-rules-reminder inject project + brand context +Step 3: Route — parse subcommand from args, load references/.md +Step 4: Execute subcommand workflow (audit, keywords, pseo, optimize, schema) +Step 5: Output — reports, schema files, or pSEO pages +``` + +## Subcommands (5 variants) + +| Subcommand | Purpose | Key Agents/Skills | Complexity | +|------------|---------|-------------------|------------| +| `audit` | Technical SEO audit + Core Web Vitals | seo-specialist, audit-core-web-vitals.cjs | Heavy | +| `keywords` | Keyword research via ReviewWeb.site API | attraction-specialist, analyze-keywords.cjs | Medium | +| `pseo` | Programmatic SEO template generation | seo-specialist, pseo-generator.cjs | Heavy | +| `optimize` | On-page SEO optimization | seo-specialist, meta-tag-templates ref | Medium | +| `schema` | JSON+LD structured data generation | seo-specialist, generate-schema.cjs, validate-schema.cjs | Light | + +## Agents Used + +| Agent | Used By | +|-------|---------| +| seo-specialist | audit, pseo, optimize, schema | +| attraction-specialist | keywords | + +## Skills Activated + +| Type | Skill | Purpose | +|------|-------|---------| +| Core | seo | SEO domain knowledge + scripts | +| Conditional | brand-guidelines | Brand context injection for content | +| Conditional | scout | Codebase scan for existing SEO setup | + +## External APIs + +| API | Used By | Purpose | +|-----|---------|---------| +| ReviewWeb.site | keywords | Keyword volume, difficulty, CPC data | +| Google Search Console | audit, keywords | Queries, clicks, impressions, CTR, position | +| PageSpeed Insights | audit | Core Web Vitals measurement | + +## Scripts + +| Script | Purpose | +|--------|---------| +| `gsc-auth.cjs` | OAuth2 auth for Google Search Console | +| `gsc-query.cjs` | Query GSC analytics, sitemaps, URL inspection | +| `analyze-keywords.cjs` | Keyword research via ReviewWeb.site API | +| `audit-core-web-vitals.cjs` | Core Web Vitals measurement | +| `generate-sitemap.cjs` | XML sitemap generation | +| `generate-schema.cjs` | JSON+LD schema generator | +| `validate-schema.cjs` | JSON-LD validation | +| `pseo-generator.cjs` | Programmatic SEO page generation | + +## Output Locations + +- Audit reports → `assets/reports/seo/{date}-{domain}-audit.md` +- Keyword reports → `assets/reports/seo/{date}-{topic}-keywords.md` +- CWV reports → `assets/reports/seo/{date}-{domain}-cwv.md` +- Schema files → `assets/seo/schemas/{page}-schema.json` +- pSEO pages → generated from templates via pseo-generator.cjs diff --git a/docs/ck-architecture/ckm-social.md b/docs/ck-architecture/ckm-social.md new file mode 100644 index 0000000..1822026 --- /dev/null +++ b/docs/ck-architecture/ckm-social.md @@ -0,0 +1,63 @@ +# /ckm:social:* — Social Media Content & Scheduling + +Source: `reference/marketing-stable/.claude/skills/social/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:social OR /ckm:social:schedule +Step 2: Route — parse platform + content type from arguments; load references/.md +Step 3: Platform Agent — social-media-manager agent applies platform best practices +Step 4: Content Creation — content-creator + copywriter agents draft copy +Step 5: Formatting — platform-specific formatting, hashtag research, character limits +Step 6: Output — deliver to assets/posts/{platform}/{date}-{slug}.md +``` + +## Subcommands + +| Subcommand | Purpose | Key Agents | Complexity | +|------------|---------|------------|------------| +| *(default)* | Create social post/thread/carousel/reel | social-media-manager, content-creator, copywriter | Medium | +| `schedule` | Schedule posts via API | social-media-manager, schedule-post.js script | Light | + +## Platforms Supported + +`twitter`/`x`, `linkedin`, `instagram`, `tiktok`, `youtube`, `facebook`, `threads` + +## Content Types + +`post`, `thread`, `carousel`, `story`, `reel` + +## Agents Used + +| Agent | Role | +|-------|------| +| social-media-manager | Platform best practices, posting guidelines | +| content-creator | Content ideation and structure | +| copywriter | Final copy writing and hook optimization | + +## References (Knowledge Base) + +| Topic | File | +|-------|------| +| Platform Specs | `references/platform-specs.md` | +| Hook Writing | `references/hook-writing.md` | +| Engagement Templates | `references/engagement-templates.md` | +| Thread Templates | `references/thread-templates.md` | +| Posting Best Practices | `references/posting-best-practices.md` | +| Rate Limits & Errors | `references/rate-limits-errors.md` | +| Unified API Services | `references/unified-api-services.md` | +| Platform Workflows | `references/x-twitter-workflow.md`, `linkedin-workflow.md`, etc. | + +## Scripts + +| Script | Purpose | +|--------|---------| +| `scripts/schedule-post.js` | Schedule posts via API | +| `scripts/validate-post-content.js` | Validate content against platform rules | + +## Routing + +1. Parse subcommand from arguments (first word) +2. Load corresponding `references/{subcommand}.md` +3. Execute with remaining arguments diff --git a/docs/ck-architecture/ckm-video.md b/docs/ck-architecture/ckm-video.md new file mode 100644 index 0000000..8649a9e --- /dev/null +++ b/docs/ck-architecture/ckm-video.md @@ -0,0 +1,72 @@ +# /ckm:video — Video Production Skill + +Source: `reference/marketing-stable/.claude/skills/video/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:video +Step 2: Route — parse subcommand (create | script-create | storyboard-create) +Step 3: Brand Context — inject-brand-context.cjs reads docs/brand-guidelines.md +Step 4: Execute subcommand workflow (varies by type) +Step 5: AI Generation — Veo 3.1 / Imagen 4 / Nano Banana for visuals +Step 6: Quality Review Gates — AI reviews at each production stage +Step 7: Assembly — FFmpeg post-production + platform export +Step 8: Output — video assets, scripts, storyboards to assets/videos/ +``` + +## Subcommands + +| Subcommand | Description | Key Flow | +|------------|-------------|----------| +| `create` | Full Veo 3.1 video pipeline | Script → Storyboard → Frames → Video → Assembly | +| `script-create` | Production-ready script | Research → Brief → Brand align → Write script | +| `storyboard-create` | START/END frame pairs | Parse script → Character portraits → Frames → Review | + +## Skills Activated + +| Type | Skill | Used By | +|------|-------|---------| +| Core | video | All subcommands (references, templates) | +| Core | creativity | Style templates, color psychology, audio trends | +| Core | ai-multimodal | Veo 3.1 / Imagen 4 / Nano Banana generation | +| Conditional | media-processing | FFmpeg assembly + platform exports | +| Conditional | assets-organizing | Output path conventions | +| Conditional | brand | Brand alignment for scripts | +| Conditional | content-marketing | Funnel mapping for scripts | +| Conditional | ai-artist | Character portraits in storyboards | + +## Agents Used + +| Agent | Used By | Purpose | +|-------|---------|---------| +| Main agent | All subcommands | Route, execute, coordinate | +| Researcher sub-agents | script-create | Parallel research for video brief | + +## AI Models + +| Model | Used By | +|-------|---------| +| Veo 3.1 | Video clip generation (create) | +| Imagen 4 / Nano Banana Flash | START/END frame generation | +| Gemini 3 Pro Image | Character portrait generation (storyboard) | +| Gemini TTS | Voiceover generation | +| Lyria | Background music generation | + +## Quality Review Gates + +5 review gates in full pipeline: script, storyboard, audio, frames (score >= 8), video clips + +## Platform Support + +YouTube (16:9), TikTok (9:16), Reels (9:16), YouTube Shorts (9:16), Instagram (1:1), LinkedIn (16:9) + +## Scripts + +| Script | Purpose | +|--------|---------| +| `generate-video.cjs` | AI video generation | +| `create-storyboard.cjs` | Storyboard generation | +| `analyze-video.cjs` | Video analysis | +| `extract-captions.cjs` | Caption extraction | +| `optimize-for-platform.cjs` | Platform optimization | diff --git a/docs/ck-architecture/ckm-write.md b/docs/ck-architecture/ckm-write.md new file mode 100644 index 0000000..99e95ad --- /dev/null +++ b/docs/ck-architecture/ckm-write.md @@ -0,0 +1,65 @@ +# /ckm:write:* — Creative Copy & Content Writing + +Source: `reference/marketing-stable/.claude/skills/write/SKILL.md` + +## Authoritative Flow + +``` +Step 1: Input — user invokes /ckm:write: +Step 2: Route — parse subcommand, load references/.md +Step 3: Brand Context — inject-brand-context.cjs reads user's docs/brand-guidelines.md +Step 4: Execute subcommand workflow (varies by variant) +Step 5: Output — deliver content (copy, blog, audit report, etc.) +``` + +## Subcommands (9 variants) + +| Subcommand | Purpose | Key Agents/Skills | Complexity | +|------------|---------|-------------------|------------| +| `fast` | Quick creative copy | copywriter agent, ai-multimodal | Light | +| `good` | Thorough creative copy | researcher agents (parallel), planner, copywriter, creativity skill, ckm:design | Heavy | +| `blog` | SEO blog article | seo-specialist, planner, copywriter, seo skill, content-marketing skill | Heavy | +| `blog-youtube` | Blog from YouTube video | youtube skill, researcher, copywriter, seo skill | Heavy | +| `formula` | Copy from formulas (AIDA, PAS, BAB, 4Ps, ACCA, FAB) | copywriter agent | Medium | +| `cro` | Conversion rate optimization | Main agent (no sub-agents), 15-point CRO framework | Medium | +| `enhance` | Fix/improve existing copy | copywriter agent, ai-multimodal, scout | Medium | +| `audit` | Score content quality (0-10) | Main agent, 4 dimensions (Copywriting 40%, SEO 30%, Platform 20%, Brand 10%) | Light | +| `publish` | Audit → auto-fix → publish-ready | Combines audit + auto-fix pipeline | Medium | + +## Agents Used + +| Agent | Used By | +|-------|---------| +| copywriter | fast, good, blog, blog-youtube, formula, enhance | +| seo-specialist | blog | +| planner | good, blog | +| researcher (parallel) | good, blog-youtube | + +## Skills Activated + +| Type | Skill | Used By | +|------|-------|---------| +| Conditional | ai-multimodal | fast, good, enhance (screenshot/video input) | +| Conditional | seo | blog, blog-youtube | +| Conditional | content-marketing | blog | +| Conditional | youtube | blog-youtube | +| Conditional | creativity | good | +| Conditional | ckm:design | good (post-writing illustrations) | + +## Brand Context Injection + +All variants receive dynamic brand context via `inject-brand-context.cjs`: +- Reads user's `docs/brand-guidelines.md` +- Injects brand voice, colors, tone into prompts +- Graceful fallback if no brand docs exist + +## Variant Complexity Tiers + +- **Light** (fast, audit): Single agent or main agent only, minimal research +- **Medium** (formula, cro, enhance, publish): Focused workflow, 1-2 agents +- **Heavy** (good, blog, blog-youtube): Multi-agent parallel research → plan → write → illustrate + +## Hard Gate + +- `publish`: Content must pass audit threshold before output +- `good`: Plan must be created before copywriter writes diff --git a/docs/ck-architecture/claudekit-architecture.md b/docs/ck-architecture/claudekit-architecture.md new file mode 100644 index 0000000..fe52314 --- /dev/null +++ b/docs/ck-architecture/claudekit-architecture.md @@ -0,0 +1,30 @@ +# ClaudeKit Architecture Notes + +Reference docs for VividKit "How ClaudeKit Works" guide accuracy. + +## Commands/Workflows + +- [ck-brainstorm.md](ck-brainstorm.md) — /ck:brainstorm solution brainstorming with brutal honesty +- [ck-plan.md](ck-plan.md) — /ck:plan implementation planning (Fast/Hard/Parallel/Two modes) +- [ck-cook.md](ck-cook.md) — /ck:cook full build pipeline (Interactive/Auto/Fast/Parallel/Code modes) +- [ck-fix.md](ck-fix.md) — /ck:fix bug fix pipeline (Standard/Quick/Deep/Parallel workflows) +- [ck-frontend-design.md](ck-frontend-design.md) — /ck:frontend-design polished frontend interfaces from designs/screenshots/videos +- [ck-ship.md](ck-ship.md) — /ck:ship automated ship pipeline (merge, test, review, commit, push, PR) +- [ck-code-review.md](ck-code-review.md) — /ck:code-review adversarial 3-stage review with red-team analysis +- [ck-test.md](ck-test.md) — /ck:test testing & QA pipeline (unit/integration/e2e/UI) +- [ck-deploy.md](ck-deploy.md) — /ck:deploy auto-detect platform deploy with cost optimization +- [ck-predict.md](ck-predict.md) — /ck:predict 5-persona impact analysis before implementation +- [ck-bootstrap.md](ck-bootstrap.md) — /ck:bootstrap end-to-end project scaffolding (full/auto/fast/parallel) +- [ck-security-scan.md](ck-security-scan.md) — /ck:security STRIDE + OWASP security audit with auto-fix +- [ckm-write.md](ckm-write.md) — /ckm:write:* creative copy & content writing (9 subcommands) +- [ckm-design.md](ckm-design.md) — /ckm:design unified design (logo, CIP, banners, social, icons, slides) +- [ckm-seo.md](ckm-seo.md) — /ckm:seo:* SEO audits, keyword research, pSEO, schema (5 subcommands) +- [ckm-campaign.md](ckm-campaign.md) — /ckm:campaign:* campaign management (create, status, analyze, email) +- [ckm-social.md](ckm-social.md) — /ckm:social:* social media content across 7 platforms +- [ckm-email.md](ckm-email.md) — /ckm:email:* email campaigns, automation flows, drip sequences +- [ckm-persona.md](ckm-persona.md) — /ckm:persona customer persona with market-validated ICP +- [ckm-video.md](ckm-video.md) — /ckm:video:* AI video production (Veo 3.1, FFmpeg, multi-platform) + +## Shared + +- [shared-concepts.md](shared-concepts.md) — Agent list, Skills vs Agents, Hooks lifecycle diff --git a/docs/ck-architecture/shared-concepts.md b/docs/ck-architecture/shared-concepts.md new file mode 100644 index 0000000..ec26b09 --- /dev/null +++ b/docs/ck-architecture/shared-concepts.md @@ -0,0 +1,55 @@ +# ClaudeKit Shared Concepts + +## CK Agent List + +Source: `github.com/claudekit/claudekit-engineer/claude/agents/` + +brainstormer, code-reviewer, code-simplifier, debugger, docs-manager, +fullstack-developer, git-manager, journal-writer, mcp-manager, +planner, project-manager, researcher, tester, ui-ux-designer + +## Skills vs Agents vs Built-in Subagent Types + +- **Skills** (ck:scout, ck:debug, ck:sequential-thinking, etc.) = prompt templates activated in main agent context +- **Agents** (debugger, tester, code-reviewer, etc.) = sub-agents spawned via Task tool in isolated context +- **Built-in subagent types** (Explore, Bash) = Claude Code native, not CK-specific + +## Hooks Lifecycle (from settings.json — complete) + +Hooks fire at different lifecycle events, NOT all at UserPromptSubmit: + +| Event | Hook | Purpose | +|-------|------|---------| +| SessionStart | session-init.cjs | Project detection, config load | +| SessionStart | session-state.cjs | Session state tracking | +| SessionStart | usage-quota-cache-refresh.cjs | Refresh usage/quota cache | +| UserPromptSubmit | dev-rules-reminder.cjs | Inject coding standards, plan context | +| UserPromptSubmit | usage-quota-cache-refresh.cjs | Refresh usage/quota cache | +| PreToolUse (Bash/Read/Edit/etc.) | privacy-block.cjs | Block access to .env, credentials | +| PreToolUse (Bash/Read/Edit/etc.) | scout-block.cjs | Scout mode enforcement | +| PreToolUse (Write) | descriptive-name.cjs | Enforce kebab-case file naming | +| SubagentStart (*) | subagent-init.cjs | Inject context for sub-agents | +| SubagentStart (*) | team-context-inject.cjs | Team coordination context | +| SubagentStart (*) | approval-workflow.cjs | Plan approval flow | +| SubagentStop (Plan) | cook-after-plan-reminder.cjs | Remind to cook after planning | +| SubagentStop (*) | session-state.cjs | Update session state | +| PostToolUse (Edit/Write) | post-edit-simplify-reminder.cjs | Code simplification reminder | +| PostToolUse (Edit/Write) | plan-format-kanban.cjs | Format plan files as kanban | +| PostToolUse (Bash/Edit/Write/etc.) | usage-quota-cache-refresh.cjs | Refresh usage/quota cache | +| Stop (*) | (stop hook) | Session cleanup | + +## Skills Used in /ck:fix (complete list from skill-activation-matrix.md) + +### Always (all workflows) +- ck:scout, ck:debug, ck:sequential-thinking + +### Auto-triggered +- ck:problem-solving (when 2+ hypotheses refuted) + +### Conditional +- ck:brainstorm (Deep only — multiple valid approaches) +- ck:context-engineering (fixing AI/LLM/agent code) +- ck:ai-multimodal (UI/visual bugs, screenshots) +- ck:project-management (Moderate+ — task sync, progress tracking) +- ck:code-review (Step 5 — via code-reviewer subagent) +- /ck:journal (Step 6 — journal entry) diff --git a/src/components/guides/TabNavigation.astro b/src/components/guides/TabNavigation.astro index f084cb6..dfaf2da 100644 --- a/src/components/guides/TabNavigation.astro +++ b/src/components/guides/TabNavigation.astro @@ -2,8 +2,8 @@ import { useTranslations } from '@/i18n/utils'; import { getLangFromUrl, useTranslatedPath, type Language } from '@/i18n'; -interface Props { - activeTab: 'what-is-claudekit' | 'cli' | 'ccs' | 'happy-ccs' | 'mobile-coding' | 'remote-control' | 'ide-config' | 'token-tips' | 'workflows' | 'flowchart' | 'commands' | 'uiux' | 'session-recovery' | 'permissions' | 'fix-logs' | 'hooks' | 'promotions' | 'migrate'; +export interface Props { + activeTab: 'what-is-claudekit' | 'cli' | 'ccs' | 'happy-ccs' | 'mobile-coding' | 'remote-control' | 'ide-config' | 'token-tips' | 'workflows' | 'flowchart' | 'commands' | 'uiux' | 'session-recovery' | 'permissions' | 'fix-logs' | 'hooks' | 'promotions' | 'migrate' | 'how-ck-works'; lang?: Language; } @@ -26,6 +26,12 @@ const navSections = [ icon: ``, href: '/guides/what-is-claudekit', }, + { + id: 'how-ck-works', + label: t('guides.how_ck_works.title'), + icon: ``, + href: '/guides/how-ck-works', + }, { id: 'cli', label: t('guides.cli.title'), diff --git a/src/components/guides/how-ck-works/HowCkWorksGuide.astro b/src/components/guides/how-ck-works/HowCkWorksGuide.astro new file mode 100644 index 0000000..e1a12b0 --- /dev/null +++ b/src/components/guides/how-ck-works/HowCkWorksGuide.astro @@ -0,0 +1,272 @@ +--- +// Main wrapper for the "How ClaudeKit Works" interactive workflow visualizer +// Manages Alpine.js shared state for scenario selection, step navigation, and detail panel +import { getLangFromUrl, type Language } from '@/i18n'; +import { workflowScenarios, stepTypeColors } from '@/data/guides/how-ck-works'; +import WorkflowScenarioSelector from './workflow-scenario-selector.astro'; +import WorkflowPipelineView from './workflow-pipeline-view.astro'; +import WorkflowStepDetailPanel from './workflow-step-detail-panel.astro'; + +interface Props { + lang?: Language; +} + +const { lang } = Astro.props; +const currentLang = lang || getLangFromUrl(Astro.url); +const isVi = currentLang === 'vi'; + +// Serialize data at build time — will be injected via + +
+ {/* Page header */} +
+

+ {isVi ? 'Cách ClaudeKit Hoạt Động' : 'How ClaudeKit Works'} +

+ +
+

+ {isVi + ? 'ClaudeKit không phải là một phần mềm độc lập hay IDE mới. Nó là một bộ khung (Framework) nâng cao được tích hợp thẳng vào cấu hình native (.claude) của Claude Code trên máy bạn, biến terminal chat thành một hệ thống tự động hóa tác vụ chuyên nghiệp.' + : 'ClaudeKit is not a standalone app or a new IDE. It is an advanced Framework integrated directly into your native Claude Code configuration (.claude) on your machine, transforming your terminal chat into a professional task automation system.'} +

+ +
+
+
+ +
+

{isVi ? '1. Hooks (Hệ thống ngầm)' : '1. Hooks (Background System)'}

+

{isVi ? 'Các script chạy lót nền tự động. Khởi tạo config, rules dự án mà bạn không cần copy-paste thủ công mỗi lần.' : 'Background scripts that run automatically. They initialize configs and project rules so you don\'t have to copy-paste them manually.'}

+
+ +
+
+ +
+

{isVi ? '2. Agents (Các chuyên gia)' : '2. Agents (Specialists)'}

+

{isVi ? 'Các mô hình được thiết lập riêng (Planner, Tester, Reviewer) với prompt và tool nội bộ, tập trung vào 1 chuyên môn.' : 'Specialized models (Planner, Tester, Reviewer) with internal prompts and tools, focusing on a single task domain.'}

+
+ +
+
+ +
+

{isVi ? '3. Workflows (Quy trình)' : '3. Workflows (Pipelines)'}

+

{isVi ? 'Tổ hợp các Hooks, Skills và Agents chạy nối tiếp nhau từ lệnh nhập của bạn để xử lý luồng việc phức tạp trọn gói.' : 'Pipelines of Hooks, Skills and Agents running sequentially from your command input to handle complex workflows end-to-end.'}

+
+
+ +
+ +

+ {isVi + ? 'Cùng xem chi tiết cách Hooks, Skills và Agents điều phối một lệnh thực tế. Chọn quy trình bên dưới và nhấn Play để khám phá cơ chế bên trong.' + : 'Let\'s see how Hooks, Skills and Agents coordinate a real command. Pick a workflow below and press Play to explore the internal mechanism.'} +

+
+
+
+ + {/* Scenario selector */} +
+

+ {isVi ? 'Chọn Workflow' : 'Choose a Workflow'} +

+ +
+ + {/* Pipeline visualization */} +
+

+ {isVi ? 'Pipeline' : 'Pipeline'} +

+ +
+ + {/* Step detail panel */} + + + {/* Keyboard hint */} +

+ {isVi + ? 'Phím tắt: Space = Play/Pause · ← → = Bước trước/sau' + : 'Keyboard: Space = Play/Pause · ← → = Prev/Next step'} +

+ + {/* Next steps CTA */} +
+

+ {isVi ? 'Bạn đã sẵn sàng để trải nghiệm?' : 'Ready to experience it yourself?'} +

+
+ + + {isVi ? 'Cài đặt ClaudeKit ngay' : 'Install ClaudeKit Now'} + + + + {isVi ? 'Khám phá tất cả Lệnh' : 'Explore All Commands'} + +
+
+
+ + + + diff --git a/src/components/guides/how-ck-works/workflow-pipeline-view.astro b/src/components/guides/how-ck-works/workflow-pipeline-view.astro new file mode 100644 index 0000000..db278c0 --- /dev/null +++ b/src/components/guides/how-ck-works/workflow-pipeline-view.astro @@ -0,0 +1,196 @@ +--- +// Animated pipeline view — horizontal nodes connected by arrows +// Renders steps for the currently selected scenario +// Alpine.js state managed by parent HowItWorksGuide +import { getLangFromUrl, type Language } from '@/i18n'; + +interface Props { + lang?: Language; +} + +const { lang } = Astro.props; +const currentLang = lang || getLangFromUrl(Astro.url); +const isVi = currentLang === 'vi'; + +// scenarios, typeColors, colorMap are inherited from parent HowItWorksGuide x-data +--- + +
+ {/* Controls row */} +
+
+ {/* Play/Pause button */} + + + {/* Next button */} + + + {/* Reset button */} + +
+ + {/* Step counter */} + + / + +
+ + {/* Pipeline nodes — vertical timeline */} +
+
+ +
+
+ + {/* Progress bar */} +
+
+
+
+ + + + diff --git a/src/components/guides/how-ck-works/workflow-scenario-selector.astro b/src/components/guides/how-ck-works/workflow-scenario-selector.astro new file mode 100644 index 0000000..3a78a94 --- /dev/null +++ b/src/components/guides/how-ck-works/workflow-scenario-selector.astro @@ -0,0 +1,110 @@ +--- +// Scenario picker — compact pill tags grouped by kit (Engineer/Marketer) +// Shows icon + command only; description appears on hover via tooltip +// Uses Alpine.js x-data from parent HowItWorksGuide component +import { getLangFromUrl, type Language } from '@/i18n'; +import { workflowScenarios, kitConfigs } from '@/data/guides/how-ck-works'; + +interface Props { + lang?: Language; +} + +const { lang } = Astro.props; +const currentLang = lang || getLangFromUrl(Astro.url); +const isVi = currentLang === 'vi'; + +// Static color map for all scenario accent colors (avoids Tailwind purge issues) +const accentMap: Record = { + red: { border: 'border-red-500/50', ring: 'ring-red-500/30', bg: 'bg-red-500/10', text: 'text-red-500' }, + purple: { border: 'border-purple-500/50', ring: 'ring-purple-500/30', bg: 'bg-purple-500/10', text: 'text-purple-500' }, + emerald: { border: 'border-emerald-500/50', ring: 'ring-emerald-500/30', bg: 'bg-emerald-500/10', text: 'text-emerald-500' }, + blue: { border: 'border-blue-500/50', ring: 'ring-blue-500/30', bg: 'bg-blue-500/10', text: 'text-blue-500' }, + amber: { border: 'border-amber-500/50', ring: 'ring-amber-500/30', bg: 'bg-amber-500/10', text: 'text-amber-500' }, + rose: { border: 'border-rose-500/50', ring: 'ring-rose-500/30', bg: 'bg-rose-500/10', text: 'text-rose-500' }, + violet: { border: 'border-violet-500/50', ring: 'ring-violet-500/30', bg: 'bg-violet-500/10', text: 'text-violet-500' }, + cyan: { border: 'border-cyan-500/50', ring: 'ring-cyan-500/30', bg: 'bg-cyan-500/10', text: 'text-cyan-500' }, + orange: { border: 'border-orange-500/50', ring: 'ring-orange-500/30', bg: 'bg-orange-500/10', text: 'text-orange-500' }, + lime: { border: 'border-lime-500/50', ring: 'ring-lime-500/30', bg: 'bg-lime-500/10', text: 'text-lime-500' }, + pink: { border: 'border-pink-500/50', ring: 'ring-pink-500/30', bg: 'bg-pink-500/10', text: 'text-pink-500' }, + teal: { border: 'border-teal-500/50', ring: 'ring-teal-500/30', bg: 'bg-teal-500/10', text: 'text-teal-500' }, + fuchsia: { border: 'border-fuchsia-500/50', ring: 'ring-fuchsia-500/30', bg: 'bg-fuchsia-500/10', text: 'text-fuchsia-500' }, + indigo: { border: 'border-indigo-500/50', ring: 'ring-indigo-500/30', bg: 'bg-indigo-500/10', text: 'text-indigo-500' }, + yellow: { border: 'border-yellow-500/50', ring: 'ring-yellow-500/30', bg: 'bg-yellow-500/10', text: 'text-yellow-500' }, + slate: { border: 'border-slate-500/50', ring: 'ring-slate-500/30', bg: 'bg-slate-500/10', text: 'text-slate-500' }, + sky: { border: 'border-sky-500/50', ring: 'ring-sky-500/30', bg: 'bg-sky-500/10', text: 'text-sky-500' }, + stone: { border: 'border-stone-500/50', ring: 'ring-stone-500/30', bg: 'bg-stone-500/10', text: 'text-stone-500' }, + zinc: { border: 'border-zinc-500/50', ring: 'ring-zinc-500/30', bg: 'bg-zinc-500/10', text: 'text-zinc-500' }, +}; + +// Group scenarios by kit +const scenariosByKit = kitConfigs.map(kit => ({ + ...kit, + scenarios: workflowScenarios.filter(s => s.kit === kit.id), +})).filter(g => g.scenarios.length > 0); +--- + +
+ {scenariosByKit.map((group) => ( +
+ {/* Kit group label */} +

+ {isVi ? group.labelVi : group.labelEn} +

+ + {/* Compact pill tags — icon + command only, description on hover */} +
+ {group.scenarios.map((scenario) => { + const accent = accentMap[scenario.accentColor] || accentMap.purple; + const desc = isVi ? scenario.descVi : scenario.descEn; + return ( + + ); + })} +
+
+ ))} + + {/* Selected scenario info card */} +
+ +
+
diff --git a/src/components/guides/how-ck-works/workflow-step-detail-panel.astro b/src/components/guides/how-ck-works/workflow-step-detail-panel.astro new file mode 100644 index 0000000..a15fb45 --- /dev/null +++ b/src/components/guides/how-ck-works/workflow-step-detail-panel.astro @@ -0,0 +1,84 @@ +--- +// Drill-down detail panel — Explain + Code tabs for the active step +// Appears below the pipeline when a step is selected +// Uses colorMap from parent pipeline-view for Tailwind-safe dynamic classes +import { getLangFromUrl, type Language } from '@/i18n'; + +interface Props { + lang?: Language; +} + +const { lang } = Astro.props; +const currentLang = lang || getLangFromUrl(Astro.url); +const isVi = currentLang === 'vi'; +--- + +
+ {/* Terminal Header */} +
+
+
+
+
+
+
+ +
+
+ + {/* Panel content */} +
+ + + {/* Terminal Code Snippet */} + +
+
diff --git a/src/data/guides/how-ck-works/index.ts b/src/data/guides/how-ck-works/index.ts new file mode 100644 index 0000000..30c5f3a --- /dev/null +++ b/src/data/guides/how-ck-works/index.ts @@ -0,0 +1,4 @@ +// Re-export all how-ck-works data for convenient imports +export { workflowScenarios } from './workflow-visualizer-scenarios'; +export { stepTypeColors, kitConfigs } from './workflow-visualizer-types'; +export type { WorkflowScenario, WorkflowStep, StepType, KitId } from './workflow-visualizer-types'; diff --git a/src/data/guides/how-ck-works/workflow-visualizer-scenarios.ts b/src/data/guides/how-ck-works/workflow-visualizer-scenarios.ts new file mode 100644 index 0000000..404d0ae --- /dev/null +++ b/src/data/guides/how-ck-works/workflow-visualizer-scenarios.ts @@ -0,0 +1,1707 @@ +// Workflow scenario definitions for the interactive "How ClaudeKit Works" visualizer +// Each scenario describes a ClaudeKit command pipeline with step-by-step breakdown + +import type { WorkflowScenario } from './workflow-visualizer-types'; + +export const workflowScenarios: WorkflowScenario[] = [ + // ─── /ck:brainstorm — Solution Brainstorming ────────────────── + { + id: 'brainstorm', + command: '/ck:brainstorm', + kit: 'engineer', + titleEn: 'Brainstorm Solutions', + titleVi: 'Brainstorm Giải Pháp', + descEn: 'Multi-phase exploration with debate, research, and optional plan handoff', + descVi: 'Khám phá đa phase với tranh luận, nghiên cứu, và tuỳ chọn chuyển sang planning', + icon: '', + accentColor: 'amber', + steps: [ + { + id: 'bs-input', + type: 'user-input', + name: '/ck:brainstorm', + descEn: 'You describe what you want to build or decide', + descVi: 'Bạn mô tả điều muốn xây dựng hoặc quyết định', + explainEn: 'You describe your challenge in natural language. For example: "/ck:brainstorm best auth approach for our SaaS app".\n\nIMPORTANT: The brainstorm skill itself does NOT write any code. It only explores ideas, debates trade-offs, and produces a summary report. Implementation happens later via /ck:plan → /ck:cook.', + explainVi: 'Bạn mô tả thách thức bằng ngôn ngữ tự nhiên. Ví dụ: "/ck:brainstorm cách auth tốt nhất cho SaaS app".\n\nQUAN TRỌNG: Skill brainstorm KHÔNG viết code. Nó chỉ khám phá ý tưởng, tranh luận trade-offs, và tạo báo cáo tổng kết. Implementation xảy ra sau qua /ck:plan → /ck:cook.', + codeSnippet: '> /ck:brainstorm best auth approach for our SaaS\n\n# HARD GATE: No code writing allowed!\n# Only: explore ideas → debate → report\n# Implementation happens later via /ck:plan', + icon: '', + color: 'purple', + }, + { + id: 'bs-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection for project understanding', + descVi: 'Inject context để hiểu project', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards, active plan context.\n• SubagentStart: subagent-init.cjs — injects context for each sub-agent spawned later by skills.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards, plan context.\n• SubagentStart: subagent-init.cjs — inject context cho mỗi sub-agent được spawn bởi skills.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules\n// SubagentStart: subagent-init.cjs → sub-agent context', + icon: '', + color: 'blue', + }, + { + id: 'bs-scout', + type: 'agent', + name: 'Scout (ck:scout)', + descEn: 'Spawn Explore sub-agents to scan codebase', + descVi: 'Spawn Explore sub-agent quét codebase', + explainEn: 'The main agent activates ck:scout skill, which spawns 2-6 parallel Explore sub-agents (or Bash sub-agents for external tools like Gemini CLI):\n\n• Explore #1 — scan src/ for existing architecture patterns.\n• Explore #2 — scan config/, package.json for tech stack.\n• Explore #3 — scan docs/ for project constraints.\n\nEach sub-agent runs in isolated 200K context and returns findings to main agent. Scale depends on project size.', + explainVi: 'Main agent kích hoạt skill ck:scout, spawn 2-6 Explore sub-agent song song (hoặc Bash sub-agent cho external tools như Gemini CLI):\n\n• Explore #1 — quét src/ tìm architecture patterns hiện có.\n• Explore #2 — quét config/, package.json cho tech stack.\n• Explore #3 — quét docs/ cho project constraints.\n\nMỗi sub-agent chạy trong isolated 200K context và trả findings về main agent. Scale tuỳ kích thước project.', + codeSnippet: '// ck:scout skill activated on Main Agent\n// Spawns parallel sub-agents via Agent tool:\n//\n// Explore #1 → scan src/ architecture patterns\n// Explore #2 → scan config/ tech stack\n// Explore #3 → scan docs/ constraints\n//\n// Each: isolated 200K context\n// Output: structured project context report', + icon: '', + color: 'green', + isSubAgent: true, + }, + // ── Phase 2: Discovery + Scope ── + { + id: 'bs-discovery', + type: 'agent', + name: 'Discovery + Scope Check', + descEn: 'Clarifying questions via AskUserQuestion, scope decomposition', + descVi: 'Câu hỏi làm rõ qua AskUserQuestion, kiểm tra scope', + explainEn: 'The main agent runs discovery directly (no sub-agents):\n\n• AskUserQuestion — probing questions about requirements, constraints, timeline, success criteria.\n• Challenge assumptions — questions the user\'s initial approach.\n• Scope assessment — if 3+ independent subsystems detected (e.g. "build platform with chat, billing, analytics"), decomposes into sub-projects. Each gets its own brainstorm cycle.\n\nThis phase loops until the agent fully understands the problem.', + explainVi: 'Main agent chạy discovery trực tiếp (không spawn sub-agent):\n\n• AskUserQuestion — câu hỏi thăm dò về requirements, constraints, timeline, success criteria.\n• Challenge assumptions — thách thức approach ban đầu của user.\n• Scope assessment — nếu phát hiện 3+ subsystems độc lập (vd: "build platform với chat, billing, analytics"), tách thành sub-projects. Mỗi cái có brainstorm cycle riêng.\n\nPhase này lặp cho đến khi agent hiểu đầy đủ vấn đề.', + codeSnippet: '// Main Agent asks via AskUserQuestion:\n//\n// Q1: "What auth providers needed?"\n// Q2: "Session-based vs JWT?"\n// Q3: "Self-hosted vs managed service?"\n//\n// Scope check:\n// 3+ independent concerns? → decompose\n// Single concern? → proceed to research\n//\n// No sub-agents spawned in this phase', + icon: '', + color: 'amber', + }, + // ── Phase 3: Research ── + { + id: 'bs-research', + type: 'agent', + name: 'Research (optional)', + descEn: 'WebSearch + ck:docs-seeker for external knowledge', + descVi: 'WebSearch + ck:docs-seeker cho kiến thức bên ngoài', + explainEn: 'The main agent gathers external information using collaboration tools:\n\n• WebSearch — find best practices, proven solutions, community opinions.\n• ck:docs-seeker skill — fetch latest library docs via llms.txt (context7.com). This skill recommends parallel agent distribution for doc fetching (Agent 1: getting started, Agent 2: core concepts, Agent 3: API reference).\n• psql — query existing database structure if relevant.\n\nNot all brainstorms need research — simple architectural decisions may skip this.', + explainVi: 'Main agent thu thập thông tin bên ngoài qua collaboration tools:\n\n• WebSearch — tìm best practices, giải pháp đã chứng minh, ý kiến cộng đồng.\n• Skill ck:docs-seeker — fetch docs mới nhất qua llms.txt (context7.com). Skill này recommend phân phối agent song song để fetch docs (Agent 1: getting started, Agent 2: core concepts, Agent 3: API reference).\n• psql — query database structure hiện có nếu liên quan.\n\nKhông phải brainstorm nào cũng cần research — quyết định kiến trúc đơn giản có thể bỏ qua.', + codeSnippet: '// Collaboration tools (run on Main Agent):\n//\n// 1. WebSearch → "best auth library 2025"\n//\n// 2. ck:docs-seeker skill activated\n// → spawns parallel agents to fetch docs:\n// Agent 1: getting started + installation\n// Agent 2: core concepts + components\n// Agent 3: API reference + config\n//\n// 3. psql → check existing user schema', + icon: '', + color: 'green', + isSubAgent: true, + }, + // ── Phase 4: Analysis + Debate ── + { + id: 'bs-analyze', + type: 'agent', + name: 'Analyze + Debate', + descEn: 'Evaluate 2-3 approaches, challenge user, reach consensus', + descVi: 'Đánh giá 2-3 hướng, thách thức user, đạt đồng thuận', + explainEn: 'The main agent runs analysis directly (no sub-agents):\n\n• Presents 2-3 viable approaches with detailed pros/cons.\n• Brutal honesty — if something is over-engineered or unrealistic, says so directly.\n• May activate ck:sequential-thinking skill for structured multi-step reasoning (runs in main agent context, no sub-agents).\n• Iterates via AskUserQuestion until consensus is reached.\n\nCore principles enforced: YAGNI, KISS, DRY.', + explainVi: 'Main agent chạy analysis trực tiếp (không spawn sub-agent):\n\n• Trình bày 2-3 approaches khả thi với pros/cons chi tiết.\n• Brutal honesty — nếu gì đó over-engineered hoặc thiếu thực tế, nói thẳng.\n• Có thể kích hoạt skill ck:sequential-thinking cho suy luận nhiều bước (chạy trong main agent context, không spawn sub-agent).\n• Lặp qua AskUserQuestion cho đến khi đạt đồng thuận.\n\nNguyên tắc bắt buộc: YAGNI, KISS, DRY.', + codeSnippet: '// Main Agent evaluates (no sub-agents):\n//\n// Option A: Better Auth (self-hosted)\n// ✓ Full control, TypeScript native\n// ✗ More maintenance, custom UI needed\n//\n// Option B: Auth0 (managed)\n// ✓ Zero maintenance, enterprise features\n// ✗ Vendor lock-in, cost at scale\n//\n// ck:sequential-thinking → structured reasoning\n// (runs in main agent, no sub-agents)', + icon: '', + color: 'amber', + }, + // ── Phase 5: Report + Handoff ── + { + id: 'bs-finalize', + type: 'output', + name: 'Report → /ck:plan or /ck:journal', + descEn: 'Summary report, then fork: plan (spawns sub-agents) or journal', + descVi: 'Báo cáo tổng kết, rồi rẽ nhánh: plan (spawn sub-agents) hoặc journal', + explainEn: 'The pipeline concludes with a comprehensive markdown summary report, then asks the user:\n\n→ "Want a detailed implementation plan?"\n\n• Yes → invokes /ck:plan skill, which spawns multiple sub-agents:\n — 2 researcher sub-agents (parallel research)\n — 1 planner sub-agent (writes plan.md + phase files)\n — 2-4 code-reviewer sub-agents (red-team review)\n — 1 project-manager sub-agent (sync-back)\n\n• No → invokes /ck:journal skill, which spawns 1 journal-writer sub-agent to write a concise technical journal entry. Session ends.', + explainVi: 'Pipeline kết thúc với báo cáo tổng kết markdown, rồi hỏi user:\n\n→ "Muốn tạo kế hoạch triển khai chi tiết?"\n\n• Có → invoke skill /ck:plan, spawn nhiều sub-agents:\n — 2 researcher sub-agent (research song song)\n — 1 planner sub-agent (viết plan.md + phase files)\n — 2-4 code-reviewer sub-agent (red-team review)\n — 1 project-manager sub-agent (sync-back)\n\n• Không → invoke skill /ck:journal, spawn 1 journal-writer sub-agent viết journal entry ngắn gọn. Kết thúc session.', + codeSnippet: '// Summary Report saved to plans/reports/\n// Chosen: Option A - Better Auth\n//\n// "Want an implementation plan?"\n//\n// → Yes: /ck:plan activated (spawns sub-agents):\n// researcher ×2 → planner ×1 → red-team ×2-4\n// → project-manager ×1\n//\n// → No: /ck:journal activated:\n// journal-writer sub-agent → entry saved', + icon: '', + color: 'purple', + }, + ], + }, + + // ─── /ck:plan — Implementation Planning ───────────────────── + { + id: 'plan', + command: '/ck:plan', + kit: 'engineer', + titleEn: 'Plan Implementation', + titleVi: 'Lập Kế Hoạch', + descEn: 'Create phased plans with red-team review', + descVi: 'Tạo kế hoạch phân phase với red-team review', + icon: '', + accentColor: 'blue', + steps: [ + { + id: 'plan-input', + type: 'user-input', + name: '/ck:plan', + descEn: 'You describe what to plan and select mode', + descVi: 'Bạn mô tả cần lập kế hoạch gì và chọn mode', + explainEn: 'You describe the feature or system to plan. ClaudeKit auto-detects complexity:\n\n• Fast (--fast) — skip research, quick plan → cook.\n• Hard (--hard) — research + plan + red-team + validate.\n• Parallel (--parallel) — hard + file ownership per phase.\n• Two (--two) — hard + 2 approaches, user selects.\n\nStarts with Scope Challenge: is this too big? Can we reduce?', + explainVi: 'Bạn mô tả tính năng hoặc hệ thống cần planning. ClaudeKit tự phát hiện complexity:\n\n• Fast (--fast) — bỏ qua research, plan nhanh → cook.\n• Hard (--hard) — research + plan + red-team + validate.\n• Parallel (--parallel) — hard + file ownership mỗi phase.\n• Two (--two) — hard + 2 approaches, user chọn.\n\nBắt đầu với Scope Challenge: có quá lớn không? Có thể giảm scope?', + codeSnippet: '> /ck:plan --hard user authentication system\n\n# Scope Challenge (Step 0):\n# Exists? → no existing auth\n# Minimum changes? → need full impl\n# Complexity? → Hard (multi-file, unfamiliar)\n#\n# Mode: Hard → research + red-team + validate', + icon: '', + color: 'purple', + }, + { + id: 'plan-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection + plan context detection', + descVi: 'Inject context + phát hiện plan context', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects active plan context.\n\nPlan context hook checks for existing plans and cross-plan dependencies.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject active plan context.\n\nPlan context hook kiểm tra plans hiện có và cross-plan dependencies.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → plan context\n//\n// Plan context: none → create new plan\n// Cross-plan scan: no conflicts found', + icon: '', + color: 'blue', + }, + { + id: 'plan-research', + type: 'agent', + name: 'Research (researcher)', + descEn: 'Spawn 2 researcher sub-agents in parallel', + descVi: 'Spawn 2 researcher sub-agent song song', + explainEn: 'In Hard/Parallel/Two modes, the main agent spawns 2 researcher sub-agents in parallel:\n\n• Researcher #1 — investigate approach A, best practices.\n• Researcher #2 — investigate approach B, alternatives.\n\nMax 5 API calls each. Skipped in Fast mode.', + explainVi: 'Ở mode Hard/Parallel/Two, main agent spawn 2 researcher sub-agent song song:\n\n• Researcher #1 — khảo sát approach A, best practices.\n• Researcher #2 — khảo sát approach B, alternatives.\n\nTối đa 5 API calls mỗi agent. Bỏ qua ở mode Fast.', + codeSnippet: '// Main Agent → spawns 2 researchers in parallel\n//\n// Researcher #1: Better Auth vs Lucia Auth\n// → Better Auth: more features, active community\n//\n// Researcher #2: Session vs JWT strategies\n// → Session: simpler, revocable, DB-backed', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'plan-create', + type: 'agent', + name: 'Plan Creation (planner)', + descEn: 'Planner sub-agent writes plan.md + phase files', + descVi: 'Planner sub-agent viết plan.md + phase files', + explainEn: 'The main agent spawns a planner sub-agent that creates:\n\n• plan.md — overview with phase list and progress tracking.\n• phase-01-*.md through phase-XX-*.md — detailed per-phase specs.\n\nEach phase file includes: requirements, architecture, implementation steps, success criteria, risk assessment.', + explainVi: 'Main agent spawn planner sub-agent để tạo:\n\n• plan.md — overview với danh sách phases và theo dõi tiến độ.\n• phase-01-*.md đến phase-XX-*.md — specs chi tiết từng phase.\n\nMỗi phase file gồm: requirements, architecture, implementation steps, success criteria, risk assessment.', + codeSnippet: '// Main Agent → spawns planner sub-agent\n//\n// Created:\n// plans/260406-auth/plan.md\n// plans/260406-auth/phase-01-setup.md\n// plans/260406-auth/phase-02-backend.md\n// plans/260406-auth/phase-03-frontend.md\n// plans/260406-auth/phase-04-testing.md', + icon: '', + color: 'amber', + isSubAgent: true, + }, + { + id: 'plan-redteam', + type: 'agent', + name: 'Red Team (code-reviewer)', + descEn: 'Adversarial review by 2-4 reviewer sub-agents', + descVi: 'Review đối kháng bởi 2-4 reviewer sub-agent', + explainEn: 'In Hard/Parallel/Two modes, spawns 2-4 code-reviewer sub-agents as adversarial personas:\n\n• Security Adversary — finds vulnerabilities.\n• Assumption Destroyer — challenges hidden assumptions.\n• Failure Mode Analyst — identifies what can go wrong (3-5 phases).\n• Scope & Complexity Critic — questions necessity (6+ phases).\n\nMain agent adjudicates findings, applies accepted changes.', + explainVi: 'Ở mode Hard/Parallel/Two, spawn 2-4 code-reviewer sub-agent với vai đối kháng:\n\n• Security Adversary — tìm lỗ hổng bảo mật.\n• Assumption Destroyer — thách thức các giả định ẩn.\n• Failure Mode Analyst — xác định rủi ro (3-5 phases).\n• Scope & Complexity Critic — đặt câu hỏi về sự cần thiết (6+ phases).\n\nMain agent phân xử findings, áp dụng thay đổi được chấp nhận.', + codeSnippet: '// Main Agent → spawns red-team reviewers\n//\n// Security Adversary:\n// "Session tokens must be httpOnly + secure"\n// Status: ACCEPTED → plan updated\n//\n// Assumption Destroyer:\n// "Why assume single-tenant?"\n// Status: NOTED → added to risk section', + icon: '', + color: 'amber', + isSubAgent: true, + }, + { + id: 'plan-output', + type: 'output', + name: 'Output → /ck:cook', + descEn: 'Task hydration + cook command with absolute path', + descVi: 'Task hydration + cook command với absolute path', + explainEn: 'The pipeline concludes with:\n\n• Validation interview — critical questions to verify plan (Hard/Parallel/Two).\n• Task hydration — TaskCreate per phase with dependency chains.\n• Cook command — outputs the exact command to start implementation.\n• Journal — /ck:journal records the planning session.\n\nCook command format depends on mode (e.g. /ck:cook --auto for fast).', + explainVi: 'Pipeline kết thúc với:\n\n• Validation interview — câu hỏi quan trọng để verify plan (Hard/Parallel/Two).\n• Task hydration — TaskCreate mỗi phase với dependency chains.\n• Cook command — xuất lệnh chính xác để bắt đầu implementation.\n• Journal — /ck:journal ghi lại planning session.\n\nCook command format tùy mode (ví dụ /ck:cook --auto cho fast).', + codeSnippet: '// Task hydration:\n// T1: Setup environment (no blockers)\n// T2: Backend API (blocked by T1)\n// T3: Frontend UI (blocked by T2)\n// T4: Testing (blocked by T3)\n//\n// Ready to cook:\n// /ck:cook /abs/path/plans/260406-auth/plan.md', + icon: '', + color: 'purple', + }, + ], + }, + + // ─── /ck:cook — Build Feature ──────────────────────────────── + { + id: 'cook', + command: '/ck:cook', + kit: 'engineer', + titleEn: 'Build a Feature', + titleVi: 'Xây Dựng Tính Năng', + descEn: '6-step implementation with review gates', + descVi: 'Pipeline 6 bước triển khai với review gates', + icon: '', + accentColor: 'purple', + steps: [ + { + id: 'cook-input', + type: 'user-input', + name: '/ck:cook', + descEn: 'You pass a plan file or describe the feature', + descVi: 'Bạn truyền file plan hoặc mô tả tính năng', + explainEn: 'You invoke cook with a plan file or feature description. ClaudeKit detects the mode:\n\n• Interactive (default) — stops at each review gate for approval.\n• Auto (--auto) — auto-approve if score ≥ 9.5, 0 critical.\n• Fast (--fast) — skip research, compressed pipeline.\n• Parallel (--parallel) — multi-agent execution for 3+ features.\n• Code (plan path) — skip research/planning, start implementing.', + explainVi: 'Bạn gọi cook với file plan hoặc mô tả feature. ClaudeKit phát hiện mode:\n\n• Interactive (mặc định) — dừng ở mỗi review gate để duyệt.\n• Auto (--auto) — tự approve nếu score ≥ 9.5, 0 critical.\n• Fast (--fast) — bỏ research, pipeline rút gọn.\n• Parallel (--parallel) — multi-agent cho 3+ features.\n• Code (plan path) — bỏ research/planning, bắt đầu implement.', + codeSnippet: '> /ck:cook @plans/260406-auth/plan.md\n\n# Mode detected: Interactive (plan path provided)\n# Steps: Research(skip) → Plan(skip) → Implement\n# → Test → Review → Finalize', + icon: '', + color: 'purple', + }, + { + id: 'cook-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection + plan context loading', + descVi: 'Inject context + load plan context', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards, active plan.\n• PreToolUse: privacy-block.cjs — protects sensitive files.\n• SubagentStart: subagent-init.cjs — context for each sub-agent.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards, active plan.\n• PreToolUse: privacy-block.cjs — bảo vệ files nhạy cảm.\n• SubagentStart: subagent-init.cjs — context cho mỗi sub-agent.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → plan context\n// PreToolUse: privacy-block.cjs → protect secrets\n// SubagentStart: subagent-init.cjs → sub-agent context', + icon: '', + color: 'blue', + }, + { + id: 'cook-implement', + type: 'agent', + name: 'Implement (Main Agent)', + descEn: 'Execute plan phases sequentially', + descVi: 'Thực thi các phases của plan tuần tự', + explainEn: 'The main agent reads the plan and implements each phase:\n\n• Reads phase-XX-*.md files for detailed specs.\n• Writes code following project coding standards.\n• May spawn ui-ux-designer sub-agent for frontend work.\n• Review Gate pauses for your approval (Interactive mode).', + explainVi: 'Main agent đọc plan và implement từng phase:\n\n• Đọc phase-XX-*.md files cho specs chi tiết.\n• Viết code theo coding standards của project.\n• Có thể spawn ui-ux-designer sub-agent cho frontend.\n• Review Gate dừng để bạn duyệt (Interactive mode).', + codeSnippet: '// Reading: phase-01-setup.md\n// Implementing: database schema, config files\n//\n// Reading: phase-02-backend.md\n// Implementing: API routes, middleware\n//\n// [Review Gate 3] → User approves → continue', + icon: '', + color: 'green', + }, + { + id: 'cook-test', + type: 'agent', + name: 'Testing (tester)', + descEn: 'Spawn tester sub-agent, 100% pass required', + descVi: 'Spawn tester sub-agent, yêu cầu 100% pass', + explainEn: 'The main agent spawns a tester sub-agent:\n\n• Writes comprehensive tests for implemented code.\n• Runs full test suite — 100% pass required.\n• If tests fail, spawns debugger sub-agent to investigate.\n• Loops until all tests pass (max 3 cycles).', + explainVi: 'Main agent spawn tester sub-agent:\n\n• Viết tests toàn diện cho code đã implement.\n• Chạy full test suite — yêu cầu 100% pass.\n• Nếu tests fail, spawn debugger sub-agent để điều tra.\n• Lặp cho đến khi tất cả tests pass (tối đa 3 vòng).', + codeSnippet: '// Main Agent → spawns tester sub-agent\n//\n// Test results: 18/18 passed ✓\n//\n// If failed:\n// Main Agent → spawns debugger sub-agent\n// debugger → root cause found → fix → re-test', + icon: '', + color: 'amber', + isSubAgent: true, + }, + { + id: 'cook-review', + type: 'agent', + name: 'Code Review (code-reviewer)', + descEn: 'Sub-agent reviews quality, max 3 fix cycles', + descVi: 'Sub-agent review chất lượng, tối đa 3 vòng fix', + explainEn: 'The main agent spawns a code-reviewer sub-agent:\n\n• Reviews correctness, security, regressions, code quality.\n• Auto-approve if score ≥ 9.5 with 0 critical (Auto mode).\n• Fix/re-review cycle up to 3 times, then escalate.\n• In Interactive mode, pauses for your approval.', + explainVi: 'Main agent spawn code-reviewer sub-agent:\n\n• Review correctness, security, regressions, code quality.\n• Tự approve nếu score ≥ 9.5 với 0 critical (Auto mode).\n• Fix/re-review tối đa 3 vòng, sau đó escalate.\n• Ở Interactive mode, dừng để bạn duyệt.', + codeSnippet: '// Main Agent → spawns code-reviewer sub-agent\n//\n// Review: 9.6/10 — APPROVED\n// Correctness: ✓\n// Security: ✓\n// Quality: ✓ (1 minor suggestion)', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'cook-finalize', + type: 'agent', + name: 'Finalize (pm + docs + git)', + descEn: 'Mandatory: spawn 3 sub-agents to complete', + descVi: 'Bắt buộc: spawn 3 sub-agent để hoàn thành', + isSubAgent: true, + explainEn: 'Step 6 is MANDATORY — incomplete without all 3 sub-agents:\n\n• project-manager — syncs task status, updates plan progress.\n• docs-manager — updates project documentation.\n• git-manager — creates conventional commits, asks to push.\n\nAlso runs /ck:journal to record the session.', + explainVi: 'Step 6 là BẮT BUỘC — chưa hoàn thành nếu thiếu 1 trong 3 sub-agent:\n\n• project-manager — sync task status, cập nhật plan progress.\n• docs-manager — cập nhật tài liệu project.\n• git-manager — tạo conventional commits, hỏi push.\n\nĐồng thời chạy /ck:journal để ghi lại session.', + codeSnippet: '// MANDATORY: all 3 sub-agents required\n//\n// project-manager → plan status: Phase 1-4 complete\n// docs-manager → docs/system-architecture.md updated\n// git-manager → feat(auth): add user authentication\n//\n// /ck:journal → session recorded ✓', + icon: '', + color: 'purple', + }, + ], + }, + + // ─── /ck:fix — Fix a Bug ───────────────────────────────────── + { + id: 'fix', + command: '/ck:fix', + kit: 'engineer', + titleEn: 'Fix a Bug', + titleVi: 'Sửa Lỗi', + descEn: 'Standard 6-phase bug diagnosis and repair pipeline', + descVi: 'Quy trình chuẩn 6 phase chẩn đoán và sửa lỗi', + icon: '', + accentColor: 'red', + steps: [ + // ── Infrastructure (user input + hooks) ── + { + id: 'fix-input', + type: 'user-input', + name: '/ck:fix', + descEn: 'You describe the bug and select a mode', + descVi: 'Bạn mô tả lỗi và chọn chế độ xử lý', + explainEn: 'You describe the bug in natural language after the /ck:fix command. For example: "/ck:fix login button returns 500 error".\n\nClaudeKit then asks you to pick a mode:\n\n• Autonomous — auto-approve fixes if confidence ≥ 9.5.\n• Human-in-the-loop — pause for your approval at each step.\n• Quick — fast cycle for trivial issues (lint, type errors).\n\nYou can also pass flags directly: --auto, --review, --quick, or --parallel.', + explainVi: 'Bạn mô tả lỗi bằng ngôn ngữ tự nhiên sau lệnh /ck:fix. Ví dụ: "/ck:fix nút đăng nhập trả lỗi 500".\n\nClaudeKit sau đó hỏi bạn chọn chế độ:\n\n• Autonomous — tự động approve nếu confidence ≥ 9.5.\n• Human-in-the-loop — dừng để duyệt từng bước.\n• Quick — xử lý nhanh cho lỗi nhỏ (lint, type errors).\n\nBạn cũng có thể truyền flag trực tiếp: --auto, --review, --quick, hoặc --parallel.', + codeSnippet: '> /ck:fix login button returns 500 error on submit\n\n# Mode selection (asked via interactive prompt):\n# Autonomous → auto-approve if confidence >= 9.5\n# Review → pause for approval at each step\n# Quick → fast scout→diagnose→fix cycle\n#\n# Or pass flags directly:\n# --auto --review --quick --parallel', + icon: '', + color: 'purple', + }, + { + id: 'fix-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Session hooks initialize environment and inject context', + descVi: 'Hooks khởi tạo environment và inject context', + explainEn: 'Hooks fire at different lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards, active plan context.\n• PreToolUse: privacy-block.cjs — blocks access to sensitive files (.env, credentials).\n• SubagentStart: subagent-init.cjs — injects context for each spawned sub-agent.\n\nThese hooks run transparently — you don\'t configure anything.', + explainVi: 'Hooks fire ở các lifecycle events khác nhau:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards, plan context.\n• PreToolUse: privacy-block.cjs — chặn truy cập files nhạy cảm (.env, credentials).\n• SubagentStart: subagent-init.cjs — inject context cho mỗi sub-agent được spawn.\n\nCác hooks chạy tự động — bạn không cần cấu hình gì.', + codeSnippet: '// SessionStart hooks (once per session):\n// session-init.cjs → project detection, config load\n//\n// UserPromptSubmit hooks (on each prompt):\n// dev-rules-reminder.cjs → inject rules, plan context\n//\n// PreToolUse hooks (on each tool call):\n// privacy-block.cjs → block .env, credentials\n//\n// SubagentStart hooks (on each sub-agent spawn):\n// subagent-init.cjs → inject sub-agent context', + icon: '', + color: 'blue', + }, + // ── Phase 1: Scout ── + { + id: 'fix-scout', + type: 'agent', + name: 'Scout (ck:scout)', + descEn: 'Spawn Explore sub-agents to gather evidence', + descVi: 'Spawn Explore sub-agent thu thập bằng chứng', + explainEn: 'The main agent activates the ck:scout skill, which spawns 2-3 parallel Explore sub-agents:\n\n• Explore #1 — Grep for error patterns in logs and stack traces.\n• Explore #2 — Read affected source files and map dependencies.\n• Explore #3 — Check recent git changes for related commits.\n\nEach runs in isolated context and returns structured findings back to the main agent.', + explainVi: 'Main agent kích hoạt skill ck:scout, spawn 2-3 Explore sub-agent song song:\n\n• Explore #1 — Grep tìm error patterns trong logs và stack traces.\n• Explore #2 — Đọc source files bị ảnh hưởng và map dependencies.\n• Explore #3 — Kiểm tra git changes gần đây tìm commits liên quan.\n\nMỗi sub-agent chạy trong isolated context và trả kết quả về main agent.', + codeSnippet: '// Main Agent activates ck:scout skill\n// Spawns parallel Explore sub-agents:\n//\n// Explore #1 → Grep for error patterns in logs\n// Explore #2 → Read affected source files + deps\n// Explore #3 → git log --since="2 days" for recent changes\n//\n// Output: evidence report with file map + traces', + icon: '', + color: 'green', + isSubAgent: true, + }, + // ── Phase 2: Diagnose (includes implicit complexity assessment) ── + { + id: 'fix-diagnose', + type: 'agent', + name: 'Diagnose (ck:debug)', + descEn: 'Spawn debugger sub-agent for root cause analysis', + descVi: 'Spawn debugger sub-agent phân tích nguyên nhân gốc', + explainEn: 'The main agent activates a chain of skills and spawns a debugger sub-agent:\n\n• ck:debug — systematic root cause investigation.\n• ck:sequential-thinking — structured hypothesis formation (no guessing).\n• debugger sub-agent — deep analysis in isolated context.\n• Explore agents — parallel hypothesis verification against codebase.\n\nIf 2+ hypotheses fail, ck:problem-solving auto-activates.\n\nAfter diagnosis, the agent implicitly assesses complexity (Simple → quick workflow, Moderate → standard, Complex → deep with research/brainstorm) and routes to the appropriate workflow.', + explainVi: 'Main agent kích hoạt chuỗi skills và spawn debugger sub-agent:\n\n• ck:debug — điều tra nguyên nhân gốc có hệ thống.\n• ck:sequential-thinking — hình thành giả thuyết có cấu trúc (không đoán mò).\n• debugger sub-agent — phân tích sâu trong isolated context.\n• Explore agents — kiểm chứng giả thuyết song song với codebase.\n\nNếu 2+ giả thuyết sai, ck:problem-solving tự kích hoạt.\n\nSau khi chẩn đoán, agent tự đánh giá độ phức tạp (Simple → quick, Moderate → standard, Complex → deep có research/brainstorm) và chọn workflow phù hợp.', + codeSnippet: '// Skill chain activated on Main Agent:\n// 1. ck:debug → systematic root cause investigation\n// 2. ck:sequential → structured hypothesis reasoning\n//\n// Spawns debugger sub-agent for deep analysis\n// Hypothesis A: null check missing → CONFIRMED ✓\n// Hypothesis B: race condition → REJECTED ✗\n//\n// Diagnosis: Missing null check in auth.ts:45\n// Severity: HIGH | Scope: 2 files\n// Complexity: Moderate → Standard workflow', + icon: '', + color: 'amber', + isSubAgent: true, + }, + // ── Phase 3: Implement Fix ── + { + id: 'fix-apply', + type: 'agent', + name: 'Main Agent (Fix)', + descEn: 'Apply targeted fix based on root cause', + descVi: 'Áp dụng bản sửa chính xác dựa trên nguyên nhân gốc', + explainEn: 'The main agent writes the actual code change — a targeted fix addressing the root cause identified in diagnosis.\n\n• Follows project coding standards (injected by hooks).\n• Makes minimal changes, follows existing patterns.\n• Targets the ROOT CAUSE, not symptoms.\n• May use ck:sequential-thinking for complex logic.', + explainVi: 'Main agent viết code thay đổi thực tế — một bản sửa chính xác nhắm vào nguyên nhân gốc.\n\n• Tuân theo coding standards của project (inject bởi hooks).\n• Thay đổi tối thiểu, tuân theo patterns hiện có.\n• Nhắm vào NGUYÊN NHÂN GỐC, không phải triệu chứng.\n• Có thể dùng ck:sequential-thinking cho logic phức tạp.', + codeSnippet: '// Fix applied to auth.ts:45\n// Before:\n// const user = req.user;\n// await user.validate();\n//\n// After:\n// const user = req.user;\n// if (!user) {\n// return res.status(401).json({ error: "Session expired" });\n// }\n// await user.validate();', + icon: '', + color: 'green', + }, + // ── Phase 4: Verify + Prevent ── + { + id: 'fix-verify', + type: 'agent', + name: 'Verify + Prevent (tester)', + descEn: 'Verify fix, add regression test, prevent recurrence', + descVi: 'Xác minh fix, thêm regression test, ngăn tái phát', + explainEn: 'The main agent spawns a tester sub-agent and runs four verification phases:\n\n• Verify — re-run EXACT pre-fix commands, compare before/after output.\n• Regression test — tester adds test that MUST fail without fix, pass with it.\n• Prevention gate — defense-in-depth: input validation, type guards, assertions.\n• Parallel checks — Bash agents run typecheck + lint + build + full test suite.\n\nIf verification fails 3 times, the agent stops and questions the architecture with you.', + explainVi: 'Main agent spawn tester sub-agent và chạy bốn phase verification:\n\n• Verify — chạy lại ĐÚNG các lệnh pre-fix, so sánh before/after.\n• Regression test — tester thêm test PHẢI fail khi không có fix, pass khi có.\n• Prevention gate — defense-in-depth: input validation, type guards, assertions.\n• Parallel checks — Bash agents chạy typecheck + lint + build + full test suite.\n\nNếu verification fail 3 lần, agent dừng lại và thảo luận kiến trúc với bạn.', + codeSnippet: '// Main Agent → spawns tester sub-agent\n//\n// 1. Verify: re-run exact pre-fix commands\n// Before: 500 error → After: 200 OK ✓\n//\n// 2. Regression test (must fail without fix):\n// auth-session.test.ts → 4/4 passed ✓\n//\n// 3. Prevention gate:\n// ✓ Input validation added at boundary\n// ✓ Type guard for nullable user\n//\n// 4. Parallel Bash agents:\n// tsc --noEmit ✓ | eslint ✓ | build ✓ | test ✓', + icon: '', + color: 'amber', + isSubAgent: true, + }, + // ── Phase 5: Code Review ── + { + id: 'fix-review', + type: 'agent', + name: 'Code Review (code-reviewer)', + descEn: 'Sub-agent reviews code quality and correctness', + descVi: 'Sub-agent review chất lượng và tính chính xác của code', + explainEn: 'The main agent spawns a code-reviewer sub-agent for final quality check:\n\n• Correctness — does the fix address the root cause?\n• Security — no new vulnerabilities introduced?\n• Regressions — does anything else break?\n• Code quality — follows project standards?\n\nReview cycle by mode:\n• Autonomous — auto-approve if score ≥ 9.5 with 0 critical. Auto-fix critical issues up to 3 cycles, then escalate to you.\n• Review — always pause for your approval with full findings.\n• Quick — lower threshold (score ≥ 8.5), only 1 auto-fix cycle.', + explainVi: 'Main agent spawn code-reviewer sub-agent để kiểm tra chất lượng lần cuối:\n\n• Correctness — bản sửa có đúng nguyên nhân gốc?\n• Security — không tạo lỗ hổng mới?\n• Regressions — có gì khác bị ảnh hưởng?\n• Code quality — tuân theo standards của project?\n\nReview cycle theo mode:\n• Autonomous — tự approve nếu score ≥ 9.5, 0 critical. Tự fix critical tối đa 3 vòng, sau đó escalate cho bạn.\n• Review — luôn dừng để bạn duyệt với đầy đủ findings.\n• Quick — ngưỡng thấp hơn (score ≥ 8.5), chỉ 1 vòng auto-fix.', + codeSnippet: '// Main Agent → spawns code-reviewer sub-agent\n//\n// Review output:\n// Correctness: ✓ Root cause addressed\n// Security: ✓ No new vulnerabilities\n// Regressions: ✓ No side effects\n// Quality: ✓ Follows project standards\n// Score: 9.8/10 — APPROVED', + icon: '', + color: 'green', + isSubAgent: true, + }, + // ── Phase 6: Finalize ── + { + id: 'fix-finalize', + type: 'agent', + name: 'Finalize (pm + docs + git)', + descEn: 'Report, update docs, journal entry, offer commit', + descVi: 'Báo cáo, cập nhật docs, ghi journal, đề nghị commit', + isSubAgent: true, + explainEn: 'The pipeline concludes with ck:project-management skill for task sync-back, then spawns sub-agents:\n\n• project-manager — syncs task status and updates plan progress (if major fix).\n• docs-manager — updates project documentation if the fix warrants it.\n• git-manager — creates conventional commit and asks to push.\n\nAlso generates:\n• Report — confidence-scored summary: root cause, changes, prevention measures.\n• Journal — records what happened via /ck:journal for future reference.', + explainVi: 'Pipeline kết thúc với skill ck:project-management để sync task status, rồi spawn sub-agents:\n\n• project-manager — sync task status và cập nhật plan progress (nếu fix lớn).\n• docs-manager — cập nhật tài liệu project nếu cần.\n• git-manager — tạo conventional commit và hỏi push.\n\nĐồng thời tạo:\n• Report — báo cáo tổng kết có điểm confidence: nguyên nhân gốc, thay đổi, biện pháp phòng ngừa.\n• Journal — ghi lại sự kiện qua /ck:journal để tham khảo sau.', + codeSnippet: '// ck:project-management → sync task status, update plan\n//\n// Main Agent → spawns project-manager sub-agent\n// project-manager → plan progress updated\n//\n// Main Agent → spawns docs-manager sub-agent\n// docs-manager → updated docs/system-architecture.md\n//\n// Main Agent → spawns git-manager sub-agent\n// git-manager → feat(auth): fix null check in session\n//\n// Report: 9.8/10 confidence | Journal ✓', + icon: '', + color: 'purple', + }, + ], + }, + + // ─── /ck:frontend-design — Polished Frontend Interfaces ────── + { + id: 'frontend-design', + command: '/ck:frontend-design', + kit: 'engineer', + titleEn: 'Frontend Design', + titleVi: 'Thiết Kế Frontend', + descEn: 'Create polished interfaces from screenshots, videos, or design briefs with anti-slop aesthetics', + descVi: 'Tạo giao diện chỉn chu từ screenshot, video, hoặc brief thiết kế với anti-slop aesthetics', + icon: '', + accentColor: 'rose', + steps: [ + { + id: 'fd-input', + type: 'user-input', + name: '/ck:frontend-design', + descEn: 'You provide a design brief, screenshot, video, or description', + descVi: 'Bạn cung cấp brief thiết kế, screenshot, video, hoặc mô tả', + explainEn: 'You describe what interface to build. Input types determine the workflow:\n\n• Screenshot → pixel-perfect replication\n• Video → replication with animations\n• 3D/WebGL request → Three.js immersive experience\n• Quick task → rapid implementation\n• Complex/award-quality → full immersive pipeline\n• Existing project → redesign audit\n• From scratch → Design Thinking flow', + explainVi: 'Bạn mô tả giao diện cần xây dựng. Loại input quyết định workflow:\n\n• Screenshot → sao chép pixel-perfect\n• Video → sao chép kèm animation\n• 3D/WebGL → trải nghiệm Three.js immersive\n• Quick task → triển khai nhanh\n• Complex/award-quality → pipeline immersive đầy đủ\n• Project hiện có → audit redesign\n• Từ đầu → Design Thinking flow', + codeSnippet: '> /ck:frontend-design replicate this landing page\n> [attaches screenshot.png]\n\n# Workflow auto-selected: screenshot replication\n# Design Dials: VARIANCE=8, MOTION=6, DENSITY=4', + icon: '', + color: 'purple', + }, + { + id: 'fd-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection for project understanding', + descVi: 'Inject context để hiểu project', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards, design guidelines, plan context.\n• SubagentStart: subagent-init.cjs — injects context for ui-ux-designer sub-agent.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards, design guidelines, plan context.\n• SubagentStart: subagent-init.cjs — inject context cho sub-agent ui-ux-designer.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules + design guidelines\n// SubagentStart: subagent-init.cjs → sub-agent context', + icon: '', + color: 'blue', + }, + { + id: 'fd-uiux', + type: 'agent', + name: 'Activate ck:ui-ux-pro-max', + descEn: 'Load design intelligence — styles, palettes, font pairings, UX guidelines', + descVi: 'Load design intelligence — styles, palettes, font pairings, UX guidelines', + explainEn: 'MANDATORY first skill activation for ALL workflows. Loads:\n\n• 50+ design styles catalog\n• 161 color palettes with accessibility scores\n• 57 font pairings (display + body)\n• 161 product type templates\n• 99 UX guidelines\n• 25 chart type recommendations\n\nThis runs on the main agent — no sub-agent spawned. Provides the design foundation for all subsequent steps.', + explainVi: 'Skill BẮT BUỘC kích hoạt đầu tiên cho TẤT CẢ workflows. Load:\n\n• 50+ catalog phong cách thiết kế\n• 161 color palettes với accessibility scores\n• 57 font pairings (display + body)\n• 161 product type templates\n• 99 UX guidelines\n• 25 chart type recommendations\n\nChạy trên main agent — không spawn sub-agent. Cung cấp nền tảng thiết kế cho các bước sau.', + codeSnippet: '// Skill activated: ck:ui-ux-pro-max\n// Loaded into main agent context:\n// styles: 50+ catalogs\n// palettes: 161 options\n// fonts: 57 pairings\n// ux: 99 guidelines', + icon: '', + color: 'green', + }, + { + id: 'fd-analyze', + type: 'agent', + name: 'Analyze Input (ck:ai-multimodal)', + descEn: 'Extract colors, fonts, spacing, effects from screenshot/video via Gemini', + descVi: 'Trích xuất colors, fonts, spacing, effects từ screenshot/video qua Gemini', + explainEn: 'For screenshot/video workflows, the main agent activates ck:ai-multimodal skill:\n\n• Gemini Vision API analyzes the input image/video\n• Extracts: exact colors (hex), font families, spacing values, border radii, shadow properties, animation timing\n• Generates a structured design spec\n\nFor from-scratch workflows, this step is replaced by Design Thinking: choosing bold aesthetic direction (tone, purpose, differentiation) and configuring Design Dials.', + explainVi: 'Cho screenshot/video workflows, main agent kích hoạt skill ck:ai-multimodal:\n\n• Gemini Vision API phân tích input image/video\n• Trích xuất: exact colors (hex), font families, spacing values, border radii, shadow properties, animation timing\n• Tạo structured design spec\n\nCho from-scratch workflows, bước này thay bằng Design Thinking: chọn hướng thẩm mỹ mạnh mẽ (tone, purpose, differentiation) và cấu hình Design Dials.', + codeSnippet: '// ck:ai-multimodal activated on Main Agent\n// Gemini Vision → analyze screenshot\n//\n// Extracted:\n// colors: ["#1a1a2e", "#e94560", "#0f3460"]\n// font: "Cabinet Grotesk" (display), "Outfit" (body)\n// spacing: 8px base grid\n// shadows: tinted inner shadows\n// motion: spring physics on hover', + icon: '', + color: 'green', + }, + { + id: 'fd-plan', + type: 'agent', + name: 'Design Plan (ui-ux-designer)', + descEn: 'Sub-agent creates phased implementation plan', + descVi: 'Sub-agent tạo plan triển khai theo phases', + explainEn: 'The main agent spawns a ui-ux-designer sub-agent via Agent tool:\n\n• Receives the extracted design spec and aesthetic direction\n• Creates phased implementation plan (layout → typography → colors → effects → motion)\n• Identifies component boundaries and reuse opportunities\n• Flags potential accessibility issues\n\nThe sub-agent runs in isolated 200K context and returns the plan to main agent.', + explainVi: 'Main agent spawn ui-ux-designer sub-agent qua Agent tool:\n\n• Nhận design spec đã trích xuất và hướng thẩm mỹ\n• Tạo plan triển khai theo phases (layout → typography → colors → effects → motion)\n• Xác định component boundaries và reuse opportunities\n• Đánh dấu potential accessibility issues\n\nSub-agent chạy trong isolated 200K context và trả plan về main agent.', + codeSnippet: '// Main Agent → spawns ui-ux-designer sub-agent\n//\n// ui-ux-designer receives:\n// - design spec from Gemini analysis\n// - aesthetic direction + Design Dials\n// - project tech stack (React/Astro/etc.)\n//\n// Returns phased plan:\n// Phase 1: Layout structure (CSS Grid/Flexbox)\n// Phase 2: Typography + colors\n// Phase 3: Effects + motion\n// Phase 4: Responsive + a11y', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'fd-implement', + type: 'agent', + name: 'Implement + Anti-Slop Check', + descEn: 'Build production-grade code, verify against anti-slop rules', + descVi: 'Xây dựng code production-grade, verify theo anti-slop rules', + explainEn: 'The main agent implements the design following the phased plan:\n\n• Production-grade HTML/CSS/JS (or React/Vue/Astro components)\n• Anti-slop checklist enforced at every step:\n - No Inter/Roboto/Arial fonts\n - No AI purple gradient aesthetic\n - No 3-column equal card layouts\n - No "John Doe" placeholder content\n - No neon/outer glows\n• Asset generation via ck:ai-multimodal (Imagen 4, Nano Banana)\n• Image optimization via ck:media-processing\n• Performance guardrails: animation budget, blur limits', + explainVi: 'Main agent triển khai design theo phased plan:\n\n• Code production-grade HTML/CSS/JS (hoặc React/Vue/Astro components)\n• Anti-slop checklist bắt buộc mỗi bước:\n - Không dùng Inter/Roboto/Arial fonts\n - Không dùng AI purple gradient aesthetic\n - Không dùng 3-column equal card layouts\n - Không dùng "John Doe" placeholder content\n - Không dùng neon/outer glows\n• Tạo assets qua ck:ai-multimodal (Imagen 4, Nano Banana)\n• Tối ưu hình ảnh qua ck:media-processing\n• Performance guardrails: animation budget, blur limits', + codeSnippet: '// Main Agent implements directly:\n//\n// Phase 1: Layout with CSS Grid (asymmetric)\n// Phase 2: Typography — Cabinet Grotesk + Outfit\n// Phase 3: Colors — neutral base + single accent\n// Phase 4: Motion — spring physics, scroll reveals\n//\n// Anti-slop checklist:\n// ✓ No Inter/Roboto/Arial\n// ✓ No purple gradient\n// ✓ No equal 3-col cards\n// ✓ Realistic content\n// ✓ Performance budget OK', + icon: '', + color: 'green', + }, + { + id: 'fd-output', + type: 'output', + name: 'Verified Design + Docs', + descEn: 'Production-ready interface with design guidelines updated', + descVi: 'Giao diện production-ready với design guidelines đã cập nhật', + explainEn: 'Final deliverables:\n\n• Production-grade working code — visually striking, accessible, performant\n• Anti-slop verification passed\n• Design guidelines updated in docs/design-guidelines.md (if approved)\n• Assets generated and optimized\n\nThe interface should be UNFORGETTABLE — bold aesthetic with intentional design choices, not generic AI output.', + explainVi: 'Sản phẩm cuối cùng:\n\n• Code production-grade hoạt động — ấn tượng thị giác, accessible, performant\n• Anti-slop verification đã pass\n• Design guidelines cập nhật trong docs/design-guidelines.md (nếu được duyệt)\n• Assets đã tạo và tối ưu\n\nGiao diện phải ĐÁNG NHỚ — aesthetic mạnh mẽ với thiết kế có chủ đích, không phải output AI generic.', + codeSnippet: '// Output:\n// ✓ Working production code\n// ✓ Anti-slop checklist passed\n// ✓ Design guidelines documented\n// ✓ Assets generated + optimized\n//\n// Design Dials applied:\n// VARIANCE=8 → asymmetric layout\n// MOTION=6 → scroll reveals + spring hover\n// DENSITY=4 → generous whitespace', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:write:* — Creative Copy & Content Writing ──────────── + { + id: 'write', + command: '/ckm:write:*', + kit: 'marketer', + titleEn: 'Write Copy & Content', + titleVi: 'Viết Copy & Nội Dung', + descEn: '9 subcommands for blog, SEO copy, CRO, formulas, audit, and publish-ready content', + descVi: '9 subcommand cho blog, SEO copy, CRO, formulas, audit, và nội dung publish-ready', + icon: '', + accentColor: 'violet', + steps: [ + { + id: 'wr-input', + type: 'user-input', + name: '/ckm:write:*', + descEn: 'You choose a writing mode: fast, good, blog, formula, cro, audit, etc.', + descVi: 'Bạn chọn chế độ viết: fast, good, blog, formula, cro, audit, v.v.', + explainEn: 'You invoke /ckm:write: where is one of 9 subcommands:\n\n• /ckm:write:fast — quick creative copy (light, 1 agent)\n• /ckm:write:good — thorough copy with research + planning + illustrations (heavy, multi-agent)\n• /ckm:write:blog — SEO-optimized blog article (heavy, keyword research → outline → write)\n• /ckm:write:blog:youtube — blog from YouTube video (heavy, video extraction → research → write)\n• /ckm:write:formula — copy using proven frameworks: AIDA, PAS, BAB, 4Ps, ACCA, FAB\n• /ckm:write:cro — conversion rate optimization (15-point CRO framework)\n• /ckm:write:enhance — fix/improve existing copy\n• /ckm:write:audit — score content quality (0-10 across 4 dimensions)\n• /ckm:write:publish — audit → auto-fix → publish-ready output', + explainVi: 'Bạn gọi /ckm:write: trong đó là 1 trong 9 subcommand:\n\n• /ckm:write:fast — viết copy nhanh (nhẹ, 1 agent)\n• /ckm:write:good — copy kỹ lưỡng với research + planning + minh hoạ (nặng, multi-agent)\n• /ckm:write:blog — bài blog tối ưu SEO (nặng, keyword research → outline → viết)\n• /ckm:write:blog:youtube — blog từ video YouTube (nặng, trích xuất video → research → viết)\n• /ckm:write:formula — copy theo framework đã chứng minh: AIDA, PAS, BAB, 4Ps, ACCA, FAB\n• /ckm:write:cro — tối ưu conversion rate (15-point CRO framework)\n• /ckm:write:enhance — sửa/cải thiện copy hiện có\n• /ckm:write:audit — chấm điểm chất lượng nội dung (0-10 theo 4 chiều)\n• /ckm:write:publish — audit → auto-fix → sẵn sàng publish', + codeSnippet: '> /ckm:write:good write a launch announcement for our new AI feature\n> /ckm:write:blog "best practices for SaaS onboarding"\n> /ckm:write:formula AIDA for our pricing page\n> /ckm:write:audit docs/blog/latest-post.md\n> /ckm:write:cro "landing page has low conversion"', + icon: '', + color: 'purple', + }, + { + id: 'wr-hooks', + type: 'hook', + name: 'Hooks + Brand Context', + descEn: 'Inject project config and brand guidelines dynamically', + descVi: 'Inject project config và brand guidelines tự động', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads .ck.json config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards.\n• Brand injection: inject-brand-context.cjs — reads user\'s docs/brand-guidelines.md to extract brand voice, colors, tone, and target audience.\n\nBrand context is injected into ALL subcommand workflows. If no brand docs exist, the skill uses a graceful fallback with generic best practices.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load .ck.json config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards.\n• Brand injection: inject-brand-context.cjs — đọc docs/brand-guidelines.md của user để trích xuất brand voice, colors, tone, và target audience.\n\nBrand context được inject vào TẤT CẢ subcommand workflows. Nếu không có brand docs, skill sử dụng fallback nhẹ nhàng với generic best practices.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules\n//\n// Brand injection: inject-brand-context.cjs\n// reads: docs/brand-guidelines.md\n// extracts: voice, colors, tone, audience\n// fallback: generic best practices if no docs', + icon: '', + color: 'blue', + }, + { + id: 'wr-route', + type: 'agent', + name: 'Route Subcommand', + descEn: 'Parse variant, load specific workflow reference', + descVi: 'Parse variant, load workflow reference tương ứng', + explainEn: 'The main agent parses the subcommand from arguments and loads the corresponding workflow:\n\n• fast → references/fast.md (Light tier)\n• good → references/good.md (Heavy tier)\n• blog → references/blog.md (Heavy tier)\n• blog-youtube → references/blog-youtube.md (Heavy tier)\n• formula → references/formula.md (Medium tier)\n• cro → references/cro.md (Medium tier)\n• enhance → references/enhance.md (Medium tier)\n• audit → references/audit.md (Light tier)\n• publish → references/publish.md (Medium tier)\n\nComplexity tiers determine how many agents are spawned:\n• Light: 1 agent or main agent only\n• Medium: 1-2 agents, focused workflow\n• Heavy: multi-agent parallel research → plan → write → illustrate', + explainVi: 'Main agent parse subcommand từ arguments và load workflow tương ứng:\n\n• fast → references/fast.md (Light tier)\n• good → references/good.md (Heavy tier)\n• blog → references/blog.md (Heavy tier)\n• blog-youtube → references/blog-youtube.md (Heavy tier)\n• formula → references/formula.md (Medium tier)\n• cro → references/cro.md (Medium tier)\n• enhance → references/enhance.md (Medium tier)\n• audit → references/audit.md (Light tier)\n• publish → references/publish.md (Medium tier)\n\nComplexity tiers quyết định số agents được spawn:\n• Light: 1 agent hoặc chỉ main agent\n• Medium: 1-2 agents, workflow tập trung\n• Heavy: multi-agent parallel research → plan → write → illustrate', + codeSnippet: '// Main Agent routes subcommand:\n//\n// /ckm:write:good "launch announcement..."\n// → variant: "good"\n// → load: references/good.md\n// → tier: Heavy (multi-agent)\n//\n// Tier mapping:\n// Light: :fast, :audit\n// Medium: :formula, :cro, :enhance, :publish\n// Heavy: :good, :blog, :blog:youtube', + icon: '', + color: 'amber', + }, + { + id: 'wr-research', + type: 'agent', + name: 'Research + SEO (Heavy variants)', + descEn: 'Parallel researcher agents + seo-specialist for blog/good workflows', + descVi: 'Parallel researcher agents + seo-specialist cho blog/good workflows', + explainEn: 'For Heavy tier variants (good, blog, blog-youtube), the main agent spawns research sub-agents:\n\n• good: Multiple researcher agents in parallel search for relevant information, trends, competitive landscape.\n• blog: seo-specialist agent performs keyword research (primary, secondary, long-tail). Activates seo and content-marketing skills.\n• blog-youtube: youtube skill extracts video content (metadata, transcript). Then researcher agents gather additional perspectives.\n\nFor Light/Medium tiers, this step is skipped — the copywriter works directly from the brief.\n\nAll research findings are synthesized by the main agent before passing to the planning step.', + explainVi: 'Cho Heavy tier variants (good, blog, blog-youtube), main agent spawn research sub-agents:\n\n• good: Nhiều researcher agents song song tìm thông tin liên quan, trends, competitive landscape.\n• blog: seo-specialist agent thực hiện keyword research (primary, secondary, long-tail). Kích hoạt seo và content-marketing skills.\n• blog-youtube: youtube skill trích xuất nội dung video (metadata, transcript). Rồi researcher agents thu thập thêm perspectives.\n\nCho Light/Medium tiers, bước này được bỏ qua — copywriter làm việc trực tiếp từ brief.\n\nTất cả research findings được main agent tổng hợp trước khi chuyển sang bước planning.', + codeSnippet: '// Heavy tier: "good" variant\n// Main Agent → spawns parallel researcher sub-agents\n// researcher #1 → trends + market data\n// researcher #2 → competitor analysis\n// researcher #3 → audience insights\n//\n// Heavy tier: "blog" variant\n// seo-specialist → keyword research\n// skills: seo, content-marketing\n//\n// Heavy tier: "blog-youtube" variant\n// youtube skill → extract transcript\n// researcher → additional perspectives', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'wr-plan', + type: 'agent', + name: 'Plan + Write (copywriter)', + descEn: 'Planner outlines structure, copywriter agent produces content', + descVi: 'Planner tạo outline cấu trúc, copywriter agent viết nội dung', + explainEn: 'For Heavy/Medium tiers:\n\n1. planner agent creates content outline (structure, sections, key messages)\n2. copywriter agent writes the actual content following the plan\n\nFor Light tier (fast):\n• copywriter agent writes directly from the brief — no planner step.\n\nSpecial variant behaviors:\n• formula: copywriter applies chosen framework (AIDA, PAS, BAB, etc.) directly\n• cro: main agent runs 15-point CRO framework analysis (no copywriter)\n• audit: main agent scores across 4 dimensions — Copywriting 40%, SEO 30%, Platform 20%, Brand 10%\n• enhance: copywriter reads existing copy + issues, writes improved version\n• publish: runs audit first, then auto-fixes issues\n\nFor "good" variant, after content is finalized, /ckm:design is invoked to create 2-3 supporting illustrations.', + explainVi: 'Cho Heavy/Medium tiers:\n\n1. planner agent tạo content outline (cấu trúc, sections, key messages)\n2. copywriter agent viết nội dung thực tế theo plan\n\nCho Light tier (fast):\n• copywriter agent viết trực tiếp từ brief — không có bước planner.\n\nHành vi đặc biệt theo variant:\n• formula: copywriter áp dụng framework đã chọn (AIDA, PAS, BAB, v.v.) trực tiếp\n• cro: main agent chạy phân tích 15-point CRO framework (không dùng copywriter)\n• audit: main agent chấm điểm 4 chiều — Copywriting 40%, SEO 30%, Platform 20%, Brand 10%\n• enhance: copywriter đọc copy hiện tại + issues, viết phiên bản cải thiện\n• publish: chạy audit trước, rồi auto-fix issues\n\nCho "good" variant, sau khi content xong, /ckm:design được gọi để tạo 2-3 minh hoạ hỗ trợ.', + codeSnippet: '// Heavy "good" variant:\n//\n// Main Agent → spawns planner sub-agent\n// planner → content outline + key messages\n//\n// Main Agent → spawns copywriter sub-agent\n// copywriter → writes content per plan\n// activated: creativity skill\n//\n// Post-write:\n// /ckm:design → 2-3 illustrations\n//\n// Light "fast" variant:\n// copywriter → writes directly from brief\n//\n// "audit" variant (no copywriter):\n// Main Agent → score 4 dimensions (0-10)', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'wr-output', + type: 'output', + name: 'Content Delivered', + descEn: 'Final copy, blog article, audit report, or publish-ready content', + descVi: 'Copy hoàn chỉnh, bài blog, audit report, hoặc nội dung publish-ready', + explainEn: 'Output varies by subcommand:\n\n• fast/good: Polished creative copy with brand voice applied\n• blog/blog-youtube: SEO-optimized article with meta tags, keywords, internal links\n• formula: Copy structured around chosen framework (AIDA, PAS, etc.)\n• cro: Actionable optimization recommendations with priority scores\n• enhance: Improved version of existing copy with tracked changes\n• audit: Quality scorecard (0-10) across Copywriting, SEO, Platform Compliance, Brand Alignment\n• publish: Auto-fixed content that passed audit threshold, ready to publish\n\n"good" variant additionally includes 2-3 designed illustrations from /ckm:design.', + explainVi: 'Output thay đổi theo subcommand:\n\n• fast/good: Copy creative đã polish với brand voice\n• blog/blog-youtube: Bài viết tối ưu SEO với meta tags, keywords, internal links\n• formula: Copy cấu trúc theo framework đã chọn (AIDA, PAS, v.v.)\n• cro: Recommendations tối ưu conversion với priority scores\n• enhance: Phiên bản cải thiện của copy hiện có với tracked changes\n• audit: Scorecard chất lượng (0-10) theo Copywriting, SEO, Platform Compliance, Brand Alignment\n• publish: Nội dung đã auto-fix qua audit threshold, sẵn sàng publish\n\n"good" variant còn có thêm 2-3 minh hoạ thiết kế từ /ckm:design.', + codeSnippet: '// Output examples:\n//\n// "good": polished copy + 2-3 illustrations\n// "blog": SEO article + meta + keywords\n// "formula": AIDA-structured landing page copy\n// "audit": scorecard 8.5/10\n// Copywriting: 9/10\n// SEO: 8/10\n// Platform: 8/10\n// Brand: 9/10\n// "publish": auto-fixed → ready to ship', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:ship — Ship to Production ─────────────────────────── + { + id: 'ship', + command: '/ck:ship', + kit: 'engineer', + titleEn: 'Ship to Production', + titleVi: 'Ship lên Production', + descEn: 'Automated pipeline: merge, test, review, commit, push, and create PR in one command', + descVi: 'Pipeline tự động: merge, test, review, commit, push, và tạo PR trong một lệnh', + icon: '', + accentColor: 'cyan', + steps: [ + { + id: 'sh-input', + type: 'user-input', + name: '/ck:ship', + descEn: 'You invoke the ship command with optional mode and flags', + descVi: 'Bạn gọi lệnh ship với mode và flags tuỳ chọn', + explainEn: 'You run /ck:ship from a feature branch. Optional arguments control the pipeline:\n\n- "official" → ship to main/master with full pipeline (docs + journal)\n- "beta" → ship to dev/beta with lighter pipeline\n- No argument → auto-detect from branch name (feature/* → official, dev/* → beta)\n\nFlags like --skip-tests, --skip-review, --skip-journal, --skip-docs, --dry-run let you customize which steps run.', + explainVi: 'Bạn chạy /ck:ship từ feature branch. Arguments tuỳ chọn điều khiển pipeline:\n\n- "official" → ship lên main/master với full pipeline (docs + journal)\n- "beta" → ship lên dev/beta với pipeline nhẹ hơn\n- Không argument → auto-detect từ tên branch (feature/* → official, dev/* → beta)\n\nFlags như --skip-tests, --skip-review, --skip-journal, --skip-docs, --dry-run cho phép tuỳ chỉnh steps nào chạy.', + codeSnippet: '> /ck:ship official\n> /ck:ship beta --skip-tests\n> /ck:ship --dry-run\n\n# Mode auto-detection:\n# feature/* hotfix/* → official (target main)\n# dev/* beta/* → beta (target dev)', + icon: '', + color: 'purple', + }, + { + id: 'sh-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection for project understanding', + descVi: 'Inject context để hiểu project', + explainEn: 'Hooks fire at lifecycle events:\n\n- SessionStart: session-init.cjs — detects project, loads config.\n- UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards, active plan context.\n- SubagentStart: subagent-init.cjs — injects context for each sub-agent spawned later (tester, code-reviewer, etc.).', + explainVi: 'Hooks fire ở các lifecycle events:\n\n- SessionStart: session-init.cjs — phát hiện project, load config.\n- UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards, plan context.\n- SubagentStart: subagent-init.cjs — inject context cho mỗi sub-agent được spawn sau (tester, code-reviewer, v.v.).', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules\n// SubagentStart: subagent-init.cjs → sub-agent context', + icon: '', + color: 'blue', + }, + { + id: 'sh-preflight', + type: 'agent', + name: 'Pre-flight & Issues', + descEn: 'Branch check, mode detection, diff analysis, link GitHub issues', + descVi: 'Kiểm tra branch, detect mode, phân tích diff, link GitHub issues', + explainEn: 'The main agent runs pre-flight checks:\n\n1. Verify not on target branch (abort if so).\n2. Detect ship mode (official/beta) from arguments or branch name.\n3. Run git status + git diff to understand scope of changes.\n4. Search for related GitHub issues or create new ones for traceability.\n5. If --dry-run flag: show what would happen and stop.\n\nHARD GATE: If on target branch already, pipeline aborts immediately.', + explainVi: 'Main agent chạy pre-flight checks:\n\n1. Xác nhận không ở target branch (abort nếu đang ở).\n2. Detect ship mode (official/beta) từ arguments hoặc tên branch.\n3. Chạy git status + git diff để hiểu scope changes.\n4. Tìm GitHub issues liên quan hoặc tạo mới để traceability.\n5. Nếu --dry-run flag: hiển thị kế hoạch và dừng.\n\nHARD GATE: Nếu đang ở target branch, pipeline abort ngay.', + codeSnippet: 'git fetch origin main\ngit merge origin/main --no-edit\ngh issue list --search "keywords" --state open', + icon: '', + color: 'green', + }, + { + id: 'sh-merge', + type: 'agent', + name: 'Merge Target Branch', + descEn: 'Fetch and merge target branch so tests run on merged state', + descVi: 'Fetch và merge target branch để tests chạy trên merged state', + explainEn: 'Fetches the latest target branch (main or dev) and merges it into the current feature branch:\n\ngit fetch origin && git merge origin/ --no-edit\n\nThis ensures tests run against the combined state of your changes + latest target.\n\nHARD GATE: If merge conflicts cannot be auto-resolved, the pipeline stops and shows the conflicts for manual resolution.', + explainVi: 'Fetch target branch mới nhất (main hoặc dev) và merge vào feature branch hiện tại:\n\ngit fetch origin && git merge origin/ --no-edit\n\nĐảm bảo tests chạy trên combined state của changes + target mới nhất.\n\nHARD GATE: Nếu merge conflicts không thể auto-resolve, pipeline dừng và hiển thị conflicts để manual resolution.', + codeSnippet: 'git fetch origin main\ngit merge origin/main --no-edit\n# If conflicts → STOP, show conflicts\n# If up to date → continue silently', + icon: '', + color: 'green', + }, + { + id: 'sh-test', + type: 'agent', + name: 'Run Tests (tester)', + descEn: 'Auto-detect test runner and execute via tester sub-agent', + descVi: 'Auto-detect test runner và chạy qua tester sub-agent', + explainEn: 'Delegated to the tester sub-agent:\n\n1. Auto-detect test command from project files (package.json scripts, Makefile, pytest.ini, etc.).\n2. Run the full test suite.\n3. Report pass/fail counts.\n\nHARD GATE: If ANY test fails, the pipeline stops. No exceptions unless --skip-tests flag was used.', + explainVi: 'Delegate cho tester sub-agent:\n\n1. Auto-detect test command từ project files (package.json, Makefile, pytest.ini, v.v.).\n2. Chạy full test suite.\n3. Báo cáo pass/fail counts.\n\nHARD GATE: Nếu BẤT KỲ test nào fail, pipeline dừng. Không ngoại lệ trừ khi dùng --skip-tests.', + codeSnippet: '# Auto-detect: npm test / pytest / go test / cargo test\n# Delegate to tester sub-agent\n# HARD GATE: any failure → STOP', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'sh-review', + type: 'agent', + name: 'Pre-landing Review (code-reviewer)', + descEn: 'Two-pass code review: critical security issues + informational findings', + descVi: 'Code review hai pass: critical security issues + informational findings', + explainEn: 'Delegated to the code-reviewer sub-agent with full diff against target:\n\nPass 1 (CRITICAL): Security vulnerabilities, injection, race conditions, auth bypass.\nPass 2 (INFORMATIONAL): Dead code, magic numbers, test gaps, style issues.\n\nHARD GATE (critical only): For each critical issue, AskUserQuestion with options:\nA) Fix now (recommended)\nB) Acknowledge and ship\nC) False positive — skip', + explainVi: 'Delegate cho code-reviewer sub-agent với full diff so với target:\n\nPass 1 (CRITICAL): Security vulnerabilities, injection, race conditions, auth bypass.\nPass 2 (INFORMATIONAL): Dead code, magic numbers, test gaps, style issues.\n\nHARD GATE (chỉ critical): Với mỗi critical issue, AskUserQuestion với options:\nA) Fix ngay (khuyến nghị)\nB) Acknowledge và ship\nC) False positive — skip', + codeSnippet: '# Pass 1: CRITICAL → security, injection, auth bypass\n# Pass 2: INFORMATIONAL → dead code, style, test gaps\n# Critical → AskUserQuestion per issue', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'sh-background', + type: 'agent', + name: 'Journal & Docs (background)', + descEn: 'Write technical journal and update docs in background (non-blocking)', + descVi: 'Viết technical journal và cập nhật docs trong background (non-blocking)', + explainEn: 'Two background tasks run in parallel without blocking the pipeline:\n\nJournal (ck:journal): The journal-writer sub-agent writes a technical journal entry. Saved to ./docs/journals/.\n\nDocs Update (official mode only): The docs-manager sub-agent invokes ck:docs update to sync documentation.\n\nBeta mode auto-skips docs update. Both can be skipped via --skip-journal and --skip-docs flags.', + explainVi: 'Hai background tasks chạy song song không block pipeline:\n\nJournal (ck:journal): journal-writer sub-agent viết technical journal entry. Lưu vào ./docs/journals/.\n\nDocs Update (chỉ official mode): docs-manager sub-agent gọi ck:docs update để sync documentation.\n\nBeta mode tự động skip docs update. Cả hai có thể skip qua --skip-journal và --skip-docs flags.', + codeSnippet: '# Background (non-blocking):\n# journal-writer → ck:journal → ./docs/journals/\n# docs-manager → ck:docs update (official only)', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'sh-output', + type: 'output', + name: 'Commit, Push & PR', + descEn: 'Conventional commit, push to origin, create PR with linked issues', + descVi: 'Conventional commit, push lên origin, tạo PR với linked issues', + explainEn: 'The final output steps:\n\n1. Stage all changes with security scan for secrets. HARD GATE if secrets found.\n2. Compose conventional commit message (feat/fix/refactor/chore).\n3. Push to origin (never force push).\n4. Create PR via gh pr create with structured body and linked issues.\n\nThe PR URL is the final output — the single deliverable from /ck:ship.', + explainVi: 'Các output steps cuối cùng:\n\n1. Stage all changes với security scan cho secrets. HARD GATE nếu tìm thấy secrets.\n2. Compose conventional commit message (feat/fix/refactor/chore).\n3. Push lên origin (không bao giờ force push).\n4. Tạo PR qua gh pr create với structured body và linked issues.\n\nPR URL là final output — deliverable duy nhất từ /ck:ship.', + codeSnippet: 'git add -A\ngit commit -m "feat(auth): add OAuth2 login flow"\ngit push -u origin feature/foo\ngh pr create --base main --title "feat: ..." --body "..."', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:code-review — Adversarial Code Review ────────────── + { + id: 'code-review', + command: '/ck:code-review', + kit: 'engineer', + titleEn: 'Code Review', + titleVi: 'Review Code', + descEn: 'Adversarial 3-stage review with red-team analysis on every review', + descVi: 'Review đối kháng 3 giai đoạn với red-team analysis trên mọi review', + icon: '', + accentColor: 'orange', + steps: [ + { + id: 'cr-input', + type: 'user-input', + name: '/ck:code-review', + descEn: 'You invoke code review with a target: PR#, commit, --pending, or codebase', + descVi: 'Bạn gọi code review với target: PR#, commit, --pending, hoặc codebase', + explainEn: 'You invoke code review with an argument that determines the input mode:\n\n• /ck:code-review #123 — review a PR diff\n• /ck:code-review abc1234 — review a specific commit\n• /ck:code-review --pending — review staged + unstaged changes\n• /ck:code-review codebase — full codebase scan\n• /ck:code-review codebase parallel — multi-reviewer audit', + explainVi: 'Bạn gọi code review với argument xác định input mode:\n\n• /ck:code-review #123 — review PR diff\n• /ck:code-review abc1234 — review commit cụ thể\n• /ck:code-review --pending — review staged + unstaged changes\n• /ck:code-review codebase — quét toàn bộ codebase\n• /ck:code-review codebase parallel — audit nhiều reviewer song song', + codeSnippet: '> /ck:code-review #42\n> /ck:code-review --pending\n> /ck:code-review codebase parallel', + icon: '', + color: 'purple', + }, + { + id: 'cr-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection: project config, coding standards, plan context', + descVi: 'Inject context: project config, coding standards, plan context', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads .ck.json config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards, active plan context.\n• SubagentStart: subagent-init.cjs — injects context for each reviewer sub-agent.', + explainVi: 'Hooks fire ở lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load .ck.json config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards, plan context.\n• SubagentStart: subagent-init.cjs — inject context cho mỗi reviewer sub-agent.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules\n// SubagentStart: subagent-init.cjs → sub-agent context', + icon: '', + color: 'blue', + }, + { + id: 'cr-diff', + type: 'agent', + name: 'Diff Acquisition', + descEn: 'Fetch diff based on input mode (PR, commit, pending, codebase)', + descVi: 'Lấy diff dựa trên input mode (PR, commit, pending, codebase)', + explainEn: 'The main agent resolves the input mode and fetches the appropriate diff:\n\n• PR mode → gh pr diff #123\n• Commit mode → git show abc1234\n• Pending mode → git diff + git diff --staged\n• Codebase mode → full file scan\n\nNo sub-agents spawned — main agent handles diff acquisition directly.', + explainVi: 'Main agent xác định input mode và lấy diff phù hợp:\n\n• PR mode → gh pr diff #123\n• Commit mode → git show abc1234\n• Pending mode → git diff + git diff --staged\n• Codebase mode → full file scan\n\nKhông spawn sub-agent — main agent xử lý trực tiếp.', + codeSnippet: '// PR# → gh pr diff 123\n// Commit → git show abc1234\n// Pending → git diff && git diff --staged\n// Codebase → scan all source files', + icon: '', + color: 'green', + }, + { + id: 'cr-spec', + type: 'agent', + name: 'Stage 1: Spec Compliance', + descEn: 'Verify code matches what was requested — HARD GATE', + descVi: 'Kiểm tra code khớp yêu cầu — HARD GATE', + explainEn: 'Stage 1 checks spec compliance (main agent):\n\n• Does the code match what was requested in the plan/spec?\n• Any missing requirements?\n• Any unjustified extras (YAGNI violation)?\n\nHARD GATE: Stage 1 MUST pass before proceeding to Stage 2.', + explainVi: 'Stage 1 kiểm tra spec compliance (main agent):\n\n• Code có khớp yêu cầu trong plan/spec không?\n• Có requirements nào bị thiếu?\n• Có extras không cần thiết (vi phạm YAGNI)?\n\nHARD GATE: Stage 1 PHẢI pass trước khi sang Stage 2.', + codeSnippet: '// Stage 1 — Spec Compliance (HARD GATE)\n// ✓ All requirements implemented?\n// ✓ No missing features?\n// ✓ No YAGNI violations?\n// PASS → Stage 2 | FAIL → fix → re-run', + icon: '', + color: 'green', + }, + { + id: 'cr-quality', + type: 'agent', + name: 'Stage 2: Code Quality + Scout', + descEn: 'Scout edge cases, then spawn code-reviewer for standards/security/performance', + descVi: 'Scout edge cases, rồi spawn code-reviewer cho standards/security/performance', + explainEn: 'First, ck:scout activates with edge-case focus — spawns 2-6 parallel Explore sub-agents to scan data flows, error paths, boundary conditions.\n\nThen code-reviewer sub-agent spawns for full quality review:\n• Coding standards, naming, structure\n• Security: injection, auth bypass, data exposure\n• Performance: N+1 queries, missing caching\n• Edge cases from scout findings\n\nFor 3+ files: parallel scoped reviewers (backend + frontend).', + explainVi: 'Đầu tiên, ck:scout kích hoạt tập trung edge cases — spawn 2-6 Explore sub-agent song song quét data flows, error paths, boundary conditions.\n\nSau đó code-reviewer sub-agent spawn cho quality review đầy đủ:\n• Coding standards, naming, structure\n• Security: injection, auth bypass, data exposure\n• Performance: N+1 queries, missing caching\n• Edge cases từ scout\n\nVới 3+ files: parallel scoped reviewers (backend + frontend).', + codeSnippet: '// ck:scout → 2-6 Explore sub-agents (edge cases)\n// code-reviewer sub-agent → full review\n// Standards, Security, Performance\n// 3+ files → parallel scoped reviewers', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'cr-adversarial', + type: 'agent', + name: 'Stage 3: Adversarial (Red Team)', + descEn: 'Red-team reviewer actively tries to break the code', + descVi: 'Red-team reviewer chủ động thử phá code', + explainEn: 'Adversarial reviewer sub-agent — a red team that actively tries to break the code:\n\n• Scope gate: skip if ≤2 files, ≤30 lines, no security-sensitive files\n• Attacks: security holes, false assumptions, resource exhaustion, race conditions, supply chain risks\n• Each finding gets a verdict: Accept (must fix), Reject (false positive), Defer (GitHub issue)\n• Critical findings BLOCK merge\n• Re-review cycle limit: 3 — escalate to user after', + explainVi: 'Adversarial reviewer sub-agent — red team chủ động thử phá code:\n\n• Scope gate: skip nếu ≤2 files, ≤30 lines, không có security files\n• Attacks: security holes, false assumptions, resource exhaustion, race conditions, supply chain risks\n• Mỗi finding: Accept (phải fix), Reject (false positive), Defer (GitHub issue)\n• Critical findings CHẶN merge\n• Giới hạn re-review: 3 cycles → escalate cho user', + codeSnippet: '// Stage 3 — Adversarial (sub-agent)\n// Scope gate: skip if trivial\n// Red-team attacks:\n// Auth bypass, resource exhaustion,\n// race conditions, supply chain\n// Verdicts: Accept | Reject | Defer\n// Critical → BLOCK merge', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'cr-output', + type: 'output', + name: 'Review Report', + descEn: 'Findings with severity, verdicts, and merge recommendation', + descVi: 'Findings với severity, verdicts, và khuyến nghị merge', + explainEn: 'Structured review report:\n\n• Findings grouped by severity (Critical, Important, Minor)\n• Each finding: description, file/line, verdict (Accept/Reject/Defer)\n• Critical findings block merge\n• Deferred findings create GitHub issues\n• Merge recommendation: APPROVE, REQUEST CHANGES, or BLOCK\n\nVerification gates run before report: build + tests must pass with fresh evidence.', + explainVi: 'Review report có cấu trúc:\n\n• Findings nhóm theo severity (Critical, Important, Minor)\n• Mỗi finding: mô tả, file/line, verdict (Accept/Reject/Defer)\n• Critical findings chặn merge\n• Deferred findings tạo GitHub issues\n• Khuyến nghị: APPROVE, REQUEST CHANGES, hoặc BLOCK\n\nVerification gates chạy trước report: build + tests phải pass với bằng chứng mới.', + codeSnippet: '// Review Report:\n// ## Critical (must fix)\n// - SQL injection in user.ts:42 → Accept\n// ## Important\n// - Missing error boundary → Accept\n// ## Minor\n// - Naming inconsistency → Defer (#87)\n// Recommendation: REQUEST CHANGES', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:test — Testing & Quality Assurance ────────────────── + { + id: 'test', + command: '/ck:test', + kit: 'engineer', + titleEn: 'Test & QA', + titleVi: 'Kiểm Thử & QA', + descEn: 'Run tests, analyze failures, generate coverage reports, and optional UI visual regression', + descVi: 'Chạy tests, phân tích lỗi, tạo coverage reports, và tuỳ chọn UI visual regression', + icon: '', + accentColor: 'lime', + steps: [ + { + id: 'ts-input', + type: 'user-input', + name: '/ck:test', + descEn: 'You specify test scope or select mode (code vs UI)', + descVi: 'Bạn chỉ định test scope hoặc chọn mode (code vs UI)', + explainEn: 'Invoke with context to run code tests directly, or with "ui [url]" for browser-based visual testing.\n\nTwo modes:\n• (default) — Run unit/integration/e2e tests\n• ui — Run UI tests on a website\n\nExample: "/ck:test auth module" or "/ck:test ui https://myapp.com".', + explainVi: 'Gọi kèm context để chạy code tests, hoặc "ui [url]" cho visual testing trên browser.\n\nHai mode:\n• (default) — Chạy unit/integration/e2e tests\n• ui — Chạy UI tests trên website\n\nVí dụ: "/ck:test auth module" hoặc "/ck:test ui https://myapp.com".', + codeSnippet: '> /ck:test auth module\n> /ck:test ui https://myapp.com', + icon: '', + color: 'purple', + }, + { + id: 'ts-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection — project config, test framework detection', + descVi: 'Inject context — project config, phát hiện test framework', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project type, loads config, identifies test framework.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards and plan context.\n• SubagentStart: subagent-init.cjs — provides context to sub-agents (chrome-devtools for UI tests).', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện loại project, load config, xác định test framework.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards và plan context.\n• SubagentStart: subagent-init.cjs — cung cấp context cho sub-agents (chrome-devtools cho UI tests).', + codeSnippet: '// SessionStart: session-init.cjs → project + framework\n// UserPromptSubmit: dev-rules-reminder.cjs → rules\n// SubagentStart: subagent-init.cjs → sub-agent context', + icon: '', + color: 'blue', + }, + { + id: 'ts-typecheck', + type: 'agent', + name: 'Typecheck & Execute Tests', + descEn: 'Run typecheck first, then execute test suites via detected runner', + descVi: 'Chạy typecheck trước, rồi chạy test suites qua runner đã detect', + explainEn: 'Two-phase execution on main agent:\n\n1. Typecheck/static analysis (catch compile errors first):\n • TypeScript: tsc --noEmit\n • Python: mypy\n • Go: go vet\n\n2. Execute tests via detected framework:\n • Jest/Vitest/Mocha — npm test\n • pytest — python -m pytest\n • Go — go test ./...\n • Rust — cargo test\n\nHARD GATE: Never ignore failing tests. Fix actual broken code, never mock/cheat to pass.', + explainVi: 'Thực thi 2 phase trên main agent:\n\n1. Typecheck/static analysis (bắt lỗi compile trước):\n • TypeScript: tsc --noEmit\n • Python: mypy\n • Go: go vet\n\n2. Chạy tests qua framework đã detect:\n • Jest/Vitest/Mocha — npm test\n • pytest — python -m pytest\n • Go — go test ./...\n • Rust — cargo test\n\nHARD GATE: Không bao giờ bỏ qua failing tests. Sửa code thực, không mock/cheat để pass.', + codeSnippet: '// Phase 1: Typecheck\n// tsc --noEmit | mypy | go vet\n//\n// Phase 2: Test execution\n// npm test | pytest | go test | cargo test\n//\n// NEVER mock/cheat to pass!', + icon: '', + color: 'green', + }, + { + id: 'ts-analyze', + type: 'agent', + name: 'Analyze Failures + Coverage', + descEn: 'Root cause analysis, fix broken code, generate coverage metrics', + descVi: 'Phân tích nguyên nhân gốc, sửa code lỗi, tạo coverage metrics', + explainEn: 'The main agent analyzes failures and generates coverage:\n\n• Read error messages and stack traces → identify root cause vs. symptom\n• Complex failures → activate ck:sequential-thinking\n• Deep bugs → activate ck:debug\n• Generate coverage reports (Istanbul/c8/pytest-cov/go tool cover)\n• Target: 80%+ coverage on critical paths', + explainVi: 'Main agent phân tích failures và tạo coverage:\n\n• Đọc error messages và stack traces → xác định root cause vs. symptom\n• Failures phức tạp → kích hoạt ck:sequential-thinking\n• Bugs sâu → kích hoạt ck:debug\n• Tạo coverage reports (Istanbul/c8/pytest-cov/go tool cover)\n• Mục tiêu: 80%+ coverage trên critical paths', + codeSnippet: '// Analyze failures:\n// 1. Stack trace → root cause\n// 2. Complex? → ck:sequential-thinking\n// 3. Deep bug? → ck:debug\n//\n// Coverage: npm run test:coverage\n// Target: 80%+ critical paths', + icon: '', + color: 'green', + }, + { + id: 'ts-ui', + type: 'agent', + name: 'UI Tests (conditional)', + descEn: 'Browser automation via ck:chrome-devtools for visual regression', + descVi: 'Browser automation qua ck:chrome-devtools cho visual regression', + explainEn: 'Activated when mode is "ui". The ck:chrome-devtools skill spawns browser automation:\n\n• Screenshots at multiple viewports (mobile, tablet, desktop)\n• Accessibility audit (ARIA, contrast, keyboard nav)\n• Form automation and flow verification\n• Console error collection\n• Screenshots analyzed by ck:ai-multimodal for visual regression', + explainVi: 'Kích hoạt khi mode là "ui". Skill ck:chrome-devtools spawn browser automation:\n\n• Screenshots ở nhiều viewports (mobile, tablet, desktop)\n• Accessibility audit (ARIA, contrast, keyboard nav)\n• Form automation và flow verification\n• Thu thập console errors\n• Screenshots được phân tích bởi ck:ai-multimodal cho visual regression', + codeSnippet: '// ck:chrome-devtools:\n// 1. Screenshot at 375px, 768px, 1440px\n// 2. ARIA audit → a11y issues\n// 3. Form fill & submit\n// 4. Console.error collection\n// 5. ck:ai-multimodal → visual regression', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'ts-report', + type: 'output', + name: 'QA Report', + descEn: 'Structured summary — results, coverage, failures, recommendations', + descVi: 'Báo cáo tổng kết — kết quả, coverage, failures, recommendations', + explainEn: 'Structured QA report:\n\n• Test Results — pass/fail counts per suite\n• Coverage Metrics — line, branch, function percentages\n• Failed Tests Detail — each failure with root cause and fix\n• Performance — execution time, slow tests flagged\n• Build Status — compile + all tests pass\n• Recommendations — missing coverage, suggested improvements', + explainVi: 'QA report có cấu trúc:\n\n• Test Results — số pass/fail mỗi suite\n• Coverage Metrics — phần trăm line, branch, function\n• Failed Tests Detail — mỗi failure với root cause và fix\n• Performance — thời gian chạy, slow tests\n• Build Status — compile + tất cả tests pass\n• Recommendations — coverage thiếu, cải tiến gợi ý', + codeSnippet: '// QA Report:\n// ✅ 142 passed | ❌ 3 failed | ⏭ 2 skipped\n// Coverage: Lines 87% | Branches 72%\n// Failed: auth.test.ts:45 — null check (FIXED)\n// Recommend: edge case tests for session expiry', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:design — Unified Design Assets ───────────────────── + { + id: 'design', + command: '/ckm:design', + kit: 'marketer', + titleEn: 'Design Assets', + titleVi: 'Thiết Kế Tài Sản', + descEn: 'Unified design: logo, CIP, banners, social photos, icons, slides, brand identity', + descVi: 'Thiết kế thống nhất: logo, CIP, banner, ảnh social, icon, slides, brand identity', + icon: '', + accentColor: 'pink', + steps: [ + { + id: 'ds-input', + type: 'user-input', + name: '/ckm:design', + descEn: 'You specify design type and context via space args', + descVi: 'Bạn chỉ định loại thiết kế và context qua space args', + explainEn: 'You invoke the unified design skill with a design type as space argument:\n\n• "/ckm:design logo modern tech startup"\n• "/ckm:design banner Facebook cover for SaaS launch"\n• "/ckm:design social photos Instagram carousel"\n• "/ckm:design cip business card letterhead"\n\n9 design types: brand, design-system, ui-styling, logo, cip, slides, banner, social photos, icon.', + explainVi: 'Bạn gọi skill thiết kế thống nhất với space argument:\n\n• "/ckm:design logo tech startup hiện đại"\n• "/ckm:design banner Facebook cover cho SaaS launch"\n• "/ckm:design social photos Instagram carousel"\n• "/ckm:design cip business card letterhead"\n\n9 loại: brand, design-system, ui-styling, logo, cip, slides, banner, social photos, icon.', + codeSnippet: '> /ckm:design logo modern minimalist tech startup\n\n# Space-arg routing (NOT colon subcommands)\n# 9 types: brand | design-system | ui-styling\n# logo | cip | slides | banner\n# social photos | icon', + icon: '', + color: 'purple', + }, + { + id: 'ds-hooks', + type: 'hook', + name: 'Hooks + Brand Injection', + descEn: 'Context injection and brand guidelines loaded', + descVi: 'Inject context và load brand guidelines', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards.\n• inject-brand-context.cjs — reads docs/brand-guidelines.md, injects brand voice, colors, typography.\n\nBrand injection is critical for design consistency. Graceful fallback if no brand docs exist.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards.\n• inject-brand-context.cjs — đọc docs/brand-guidelines.md, inject brand voice, colors, typography.\n\nBrand injection rất quan trọng cho tính nhất quán. Fallback nhẹ nhàng nếu không có brand docs.', + codeSnippet: '// inject-brand-context.cjs:\n// reads: docs/brand-guidelines.md\n// injects: { colors, fonts, voice, tone }\n// fallback: graceful if no brand docs', + icon: '', + color: 'blue', + }, + { + id: 'ds-route', + type: 'agent', + name: 'Route + Research', + descEn: 'Parse design type, load references, research styles/colors/industries', + descVi: 'Parse loại thiết kế, load references, research styles/colors/industries', + explainEn: 'The main agent routes to the correct sub-workflow and runs research:\n\n• External sub-skills (brand, design-system, ui-styling) → delegates entirely.\n• Built-in sub-skills (logo, cip, banner, social, icon, slides) → loads references/*.md + runs Python scripts.\n\nResearch examples:\n• Logo: search.py queries 55 styles, 30 palettes, 25 industry guides via BM25.\n• CIP: search.py queries 50+ deliverables, 20 mockup scenes.\n• Banner: AskUserQuestion gathers specs, ui-ux-pro-max browses Pinterest.', + explainVi: 'Main agent route đến sub-workflow đúng và chạy research:\n\n• External sub-skills (brand, design-system, ui-styling) → delegate hoàn toàn.\n• Built-in (logo, cip, banner, social, icon, slides) → load references/*.md + chạy Python scripts.\n\nResearch:\n• Logo: search.py truy vấn 55 styles, 30 palettes, 25 industry guides.\n• CIP: search.py truy vấn 50+ deliverables, 20 mockup scenes.\n• Banner: AskUserQuestion thu thập specs, ui-ux-pro-max browse Pinterest.', + codeSnippet: '# Logo research:\npython3 scripts/logo/search.py "tech startup" --design-brief\n\n# CIP research:\npython3 scripts/cip/search.py "business card" --domain deliverable\n\n# Banner: AskUserQuestion → Pinterest', + icon: '', + color: 'green', + }, + { + id: 'ds-generate', + type: 'agent', + name: 'AI Generation + Design', + descEn: 'Gemini AI generates images/SVG, or HTML/CSS design created', + descVi: 'Gemini AI tạo hình ảnh/SVG, hoặc thiết kế HTML/CSS', + explainEn: 'Core creation varies by type:\n\n• Logo: Gemini Flash → logo images (55 styles)\n• CIP: Gemini Flash/Pro → mockup images, supports full set\n• Icon: Gemini 3.1 Pro → SVG output, batch + multi-size\n• Banner: frontend-design + ai-artist/ai-multimodal → HTML/CSS + visuals\n• Social Photos: ckm:brand → ckm:design-system → HTML per platform size\n• Slides: Chart.js + design tokens → HTML presentation', + explainVi: 'Tạo chính khác nhau theo type:\n\n• Logo: Gemini Flash → logo images (55 styles)\n• CIP: Gemini Flash/Pro → mockup images, hỗ trợ full set\n• Icon: Gemini 3.1 Pro → SVG output, batch + multi-size\n• Banner: frontend-design + ai-artist/ai-multimodal → HTML/CSS + visuals\n• Social Photos: ckm:brand → ckm:design-system → HTML per platform size\n• Slides: Chart.js + design tokens → HTML presentation', + codeSnippet: '# Logo:\npython3 scripts/logo/generate.py --brand "TechFlow" --style minimalist\n# CIP:\npython3 scripts/cip/generate.py --brand "TopGroup" --logo logo.png --set\n# Icon:\npython3 scripts/icon/generate.py --prompt "settings" --style outlined\n# Banner: frontend-design → HTML → ai-artist visuals\n# Social: ckm:brand → design-system → HTML per size', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'ds-output', + type: 'output', + name: 'Design Assets + Report', + descEn: 'Final assets exported, organized, and summary report saved', + descVi: 'Assets cuối cùng được export, tổ chức, và báo cáo tổng kết', + explainEn: 'Final delivery:\n\n• Generated assets (PNG, SVG, HTML) in project directory\n• HTML designs → chrome-devtools screenshots at exact platform dimensions (2x retina)\n• assets-organizing skill sorts output by platform/type\n• Summary report in plans/reports/\n• CIP: full HTML presentation gallery\n• All assets follow injected brand guidelines\n\nVerify + iterate on user feedback before finalizing.', + explainVi: 'Giao hàng cuối:\n\n• Assets (PNG, SVG, HTML) trong project directory\n• HTML designs → chrome-devtools screenshots ở kích thước chính xác (2x retina)\n• assets-organizing skill sắp xếp output theo platform/type\n• Báo cáo trong plans/reports/\n• CIP: HTML presentation gallery đầy đủ\n• Tất cả assets theo brand guidelines đã inject\n\nVerify + iterate theo feedback user trước khi hoàn tất.', + codeSnippet: '// Output:\n// logos/ → brand-logo-v1.png\n// cip/ → business-card.png, letterhead.png\n// banners/ → fb-cover.png, twitter-header.png\n// social/ → ig-post-1080x1080.png\n// icons/ → settings.svg\n// slides/ → pitch-deck.html', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:seo:* — SEO Audit & Optimization ────────────────── + { + id: 'seo', + command: '/ckm:seo:*', + kit: 'marketer', + titleEn: 'SEO Audit & Optimization', + titleVi: 'Kiểm Tra & Tối Ưu SEO', + descEn: 'Technical SEO audits, keyword research via ReviewWeb.site API, Google Search Console, pSEO', + descVi: 'Kiểm tra SEO kỹ thuật, nghiên cứu từ khóa qua ReviewWeb.site API, Google Search Console, pSEO', + icon: '', + accentColor: 'teal', + steps: [ + { + id: 'se-input', + type: 'user-input', + name: '/ckm:seo:', + descEn: 'You specify SEO task: audit, keywords, pseo, optimize, or schema', + descVi: 'Bạn chỉ định tác vụ SEO: audit, keywords, pseo, optimize, hoặc schema', + explainEn: 'You invoke /ckm:seo with a subcommand:\n\n• /ckm:seo:audit example.com — full technical SEO audit\n• /ckm:seo:keywords "saas pricing" — keyword research with real data\n• /ckm:seo:pseo product-pages — programmatic SEO templates\n• /ckm:seo:schema homepage — JSON+LD structured data', + explainVi: 'Bạn gọi /ckm:seo với subcommand:\n\n• /ckm:seo:audit example.com — kiểm tra SEO kỹ thuật toàn diện\n• /ckm:seo:keywords "saas pricing" — nghiên cứu từ khóa với dữ liệu thực\n• /ckm:seo:pseo product-pages — template SEO tự động hóa\n• /ckm:seo:schema homepage — JSON+LD structured data', + codeSnippet: '> /ckm:seo:audit example.com\n> /ckm:seo:keywords "saas pricing"\n> /ckm:seo:pseo product-pages\n> /ckm:seo:schema homepage', + icon: '', + color: 'purple', + }, + { + id: 'se-hooks', + type: 'hook', + name: 'Hooks + Brand Context', + descEn: 'Session init + brand context so SEO aligns with brand voice', + descVi: 'Khởi tạo session + brand context để SEO phù hợp brand voice', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• inject-brand-context.cjs — reads docs/brand-guidelines.md so SEO recommendations align with brand voice.\n• SubagentStart: subagent-init.cjs — context for seo-specialist and attraction-specialist agents.', + explainVi: 'Hooks fire ở các lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• inject-brand-context.cjs — đọc docs/brand-guidelines.md để SEO phù hợp brand voice.\n• SubagentStart: subagent-init.cjs — context cho seo-specialist và attraction-specialist agents.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// Brand: inject-brand-context.cjs → brand voice\n// SubagentStart: subagent-init.cjs → agent context', + icon: '', + color: 'blue', + }, + { + id: 'se-data', + type: 'agent', + name: 'GSC + Keyword Data', + descEn: 'Fetch real data from Google Search Console and ReviewWeb.site API', + descVi: 'Lấy dữ liệu thực từ Google Search Console và ReviewWeb.site API', + explainEn: 'Real data collection from external APIs:\n\n• Google Search Console: gsc-query.cjs fetches top queries, low-CTR pages, indexing status. OAuth2 auth via gsc-auth.cjs.\n• ReviewWeb.site API: analyze-keywords.cjs gets search volume, keyword difficulty, CPC, competition.\n• Keyword clustering by semantic similarity.\n• Content gap analysis vs competitors.\n\nAll real API data — not LLM-generated estimates. Skipped if no credentials configured.', + explainVi: 'Thu thập dữ liệu thực từ APIs bên ngoài:\n\n• Google Search Console: gsc-query.cjs lấy top queries, low-CTR pages, indexing status. OAuth2 qua gsc-auth.cjs.\n• ReviewWeb.site API: analyze-keywords.cjs lấy search volume, keyword difficulty, CPC, competition.\n• Keyword clustering theo semantic similarity.\n• Content gap analysis vs đối thủ.\n\nDữ liệu API thực — không phải LLM estimates. Bỏ qua nếu chưa config credentials.', + codeSnippet: '// GSC:\nnode scripts/gsc-query.cjs --top-queries -s URL\nnode scripts/gsc-query.cjs --low-ctr -s URL\n\n// Keywords:\nnode scripts/analyze-keywords.cjs "saas pricing"\n// → volume, difficulty, CPC, competition', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'se-execute', + type: 'agent', + name: 'SEO Specialist Execution', + descEn: 'Spawn seo-specialist for audit, optimize, pseo, or schema tasks', + descVi: 'Spawn seo-specialist cho audit, optimize, pseo, hoặc schema tasks', + explainEn: 'The seo-specialist sub-agent handles execution:\n\n• audit: Core Web Vitals (LCP, FID, CLS), technical checklist (robots.txt, sitemap, canonicals, mobile, structured data)\n• optimize: on-page SEO checklist 2025, meta titles/descriptions, headings, internal linking\n• pseo: pseo-generator.cjs creates templated pages at scale from data sources\n• schema: generate-schema.cjs + validate-schema.cjs for JSON+LD structured data', + explainVi: 'Sub-agent seo-specialist xử lý execution:\n\n• audit: Core Web Vitals (LCP, FID, CLS), technical checklist (robots.txt, sitemap, canonicals, mobile, structured data)\n• optimize: on-page SEO checklist 2025, meta titles/descriptions, headings, internal linking\n• pseo: pseo-generator.cjs tạo templated pages quy mô lớn từ data sources\n• schema: generate-schema.cjs + validate-schema.cjs cho JSON+LD', + codeSnippet: '// seo-specialist sub-agent:\n// AUDIT: audit-core-web-vitals.cjs → LCP, FID, CLS\n// OPTIMIZE: on-page-seo-checklist-2025.md\n// PSEO: pseo-generator.cjs → pages at scale\n// SCHEMA: generate-schema.cjs → JSON+LD', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'se-output', + type: 'output', + name: 'SEO Reports & Assets', + descEn: 'Audit reports, keyword data, schema files, pSEO pages', + descVi: 'Báo cáo audit, dữ liệu từ khóa, schema files, trang pSEO', + explainEn: 'Outputs by subcommand:\n\n• audit → comprehensive technical SEO report with CWV scores, prioritized fixes\n• keywords → keyword clusters with volume/difficulty, content gap analysis\n• schema → validated JSON+LD files ready for production\n• pseo → generated pages from templates\n\nAll reports use real API data (ReviewWeb.site, GSC, PageSpeed).', + explainVi: 'Outputs theo subcommand:\n\n• audit → báo cáo SEO kỹ thuật toàn diện với CWV scores, fixes ưu tiên\n• keywords → keyword clusters với volume/difficulty, content gap analysis\n• schema → JSON+LD files đã validate cho production\n• pseo → pages tạo từ templates\n\nTất cả reports dùng dữ liệu API thực (ReviewWeb.site, GSC, PageSpeed).', + codeSnippet: '// Output:\n// audit → seo/{date}-{domain}-audit.md\n// keywords → seo/{date}-{topic}-keywords.md\n// schema → seo/schemas/{page}-schema.json\n// pseo → generated pages\n// All real API data, no LLM estimates', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:campaign:* — Campaign Management ────────────────── + { + id: 'campaign', + command: '/ckm:campaign:*', + kit: 'marketer', + titleEn: 'Campaign Management', + titleVi: 'Quản Lý Chiến Dịch', + descEn: 'End-to-end campaign planning, execution, tracking, and optimization', + descVi: 'Lập kế hoạch, thực thi, theo dõi và tối ưu chiến dịch end-to-end', + icon: '', + accentColor: 'fuchsia', + steps: [ + { + id: 'cp-input', + type: 'user-input', + name: '/ckm:campaign:', + descEn: 'You invoke a campaign action: create, status, analyze, or email', + descVi: 'Bạn gọi hành động chiến dịch: create, status, analyze, hoặc email', + explainEn: 'Campaign commands:\n\n• /ckm:campaign:create "Summer Sale 2025" — full campaign creation\n• /ckm:campaign:status "Summer Sale 2025" — progress check\n• /ckm:campaign:analyze "Q1 Launch" — performance analysis\n• /ckm:campaign:email "Welcome Series" — email campaign\n\nTypes: Product Launch, Seasonal, Brand Awareness, Lead Gen, Re-engagement.', + explainVi: 'Các lệnh campaign:\n\n• /ckm:campaign:create "Summer Sale 2025" — tạo chiến dịch đầy đủ\n• /ckm:campaign:status "Summer Sale 2025" — kiểm tra tiến độ\n• /ckm:campaign:analyze "Q1 Launch" — phân tích hiệu suất\n• /ckm:campaign:email "Welcome Series" — email campaign\n\nLoại: Product Launch, Seasonal, Brand Awareness, Lead Gen, Re-engagement.', + codeSnippet: '> /ckm:campaign:create "Summer Sale 2025"\n> /ckm:campaign:status "Summer Sale 2025"\n> /ckm:campaign:analyze "Q1 Launch"\n> /ckm:campaign:email "Welcome Series"', + icon: '', + color: 'purple', + }, + { + id: 'cp-hooks', + type: 'hook', + name: 'Hooks + Brand Context', + descEn: 'Session hooks + brand guidelines injection for campaign consistency', + descVi: 'Session hooks + inject brand guidelines cho tính nhất quán chiến dịch', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — project config.\n• inject-brand-context.cjs — reads docs/brand-guidelines.md for brand voice, colors, tone in all campaign outputs.\n• SubagentStart: subagent-init.cjs — context for campaign-manager, funnel-architect, analytics-analyst, campaign-debugger.', + explainVi: 'Hooks fire ở lifecycle events:\n\n• SessionStart: session-init.cjs — project config.\n• inject-brand-context.cjs — đọc docs/brand-guidelines.md cho brand voice, colors, tone trong mọi campaign outputs.\n• SubagentStart: subagent-init.cjs — context cho campaign-manager, funnel-architect, analytics-analyst, campaign-debugger.', + codeSnippet: '// inject-brand-context.cjs → brand voice, colors, tone\n// SubagentStart → context for 4 campaign agents', + icon: '', + color: 'blue', + }, + { + id: 'cp-create', + type: 'agent', + name: 'Campaign Manager + Funnel', + descEn: 'Campaign brief, timeline, budget + conversion funnel design', + descVi: 'Campaign brief, timeline, ngân sách + thiết kế funnel chuyển đổi', + explainEn: 'For create subcommand, two agents work sequentially:\n\n1. campaign-manager agent:\n • Gathers requirements (audience, goals, KPIs, budget, timeline)\n • Creates campaign brief + channel strategy + budget allocation\n • Runs launch checklist\n\n2. funnel-architect agent:\n • Maps customer journey: Awareness → Interest → Desire → Action\n • Designs touchpoints per stage (ads, landing pages, emails, retargeting)\n • Creates conversion metrics framework', + explainVi: 'Cho create subcommand, hai agents làm việc tuần tự:\n\n1. campaign-manager agent:\n • Thu thập requirements (audience, goals, KPIs, budget, timeline)\n • Tạo campaign brief + channel strategy + budget allocation\n • Chạy launch checklist\n\n2. funnel-architect agent:\n • Map customer journey: Awareness → Interest → Desire → Action\n • Thiết kế touchpoints mỗi stage (ads, landing pages, emails, retargeting)\n • Tạo conversion metrics framework', + codeSnippet: '// campaign-manager → brief + budget + timeline\n// funnel-architect → journey map + touchpoints\n//\n// Output → assets/campaigns/{date}-{slug}/\n// briefs/ + creatives/', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'cp-analyze', + type: 'agent', + name: 'Analytics + Debugger', + descEn: 'Performance tracking (status) and diagnostics (analyze)', + descVi: 'Theo dõi hiệu suất (status) và chẩn đoán (analyze)', + explainEn: 'For status/analyze subcommands:\n\n• analytics-analyst agent: reads campaign files → progress dashboard, KPI tracking, budget burn rate. For analyze: deep performance analysis, ROI calculation.\n\n• campaign-debugger agent (analyze only): works parallel with analyst. Identifies underperforming channels, audience targeting issues, budget allocation inefficiency. Produces priority-ranked fix recommendations.\n\nAnalyst provides data, debugger provides diagnosis.', + explainVi: 'Cho status/analyze subcommands:\n\n• analytics-analyst agent: đọc campaign files → dashboard tiến độ, KPI tracking, budget burn rate. Cho analyze: phân tích hiệu suất sâu, tính ROI.\n\n• campaign-debugger agent (chỉ analyze): làm việc song song với analyst. Xác định channels kém, targeting issues, budget allocation kém hiệu quả. Tạo recommendations có priority ranking.\n\nAnalyst cung cấp data, debugger cung cấp chẩn đoán.', + codeSnippet: '// analytics-analyst → data + ROI\n// campaign-debugger → diagnosis (parallel)\n//\n// Output:\n// status → terminal dashboard\n// analyze → diagnostics/campaign-audits/', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'cp-output', + type: 'output', + name: 'Campaign Assets', + descEn: 'Briefs, funnels, reports, email sequences organized by campaign', + descVi: 'Briefs, funnels, reports, email sequences tổ chức theo chiến dịch', + explainEn: 'Outputs organized by campaign:\n\n• create → briefs/ (brief, budget, timeline) + creatives/ (funnel, journey map)\n• status → terminal progress dashboard\n• analyze → diagnostics/campaign-audits/ (performance + diagnosis)\n• email → emails/ (sequences, templates)\n\nAll outputs inherit brand context automatically.', + explainVi: 'Outputs tổ chức theo campaign:\n\n• create → briefs/ (brief, budget, timeline) + creatives/ (funnel, journey map)\n• status → terminal dashboard tiến độ\n• analyze → diagnostics/campaign-audits/ (performance + chẩn đoán)\n• email → emails/ (sequences, templates)\n\nTất cả outputs tự động thừa hưởng brand context.', + codeSnippet: '// assets/campaigns/{date}-{slug}/\n// briefs/ (create)\n// creatives/ (create)\n// emails/ (email)\n// assets/diagnostics/campaign-audits/ (analyze)', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:deploy — Auto-Detect Deploy Pipeline ──────────────── + { + id: 'deploy', + command: '/ck:deploy', + kit: 'engineer', + titleEn: 'Deploy Project', + titleVi: 'Deploy Dự Án', + descEn: 'Auto-detect platform and deploy with cost-optimized recommendations', + descVi: 'Tự động phát hiện platform và deploy với đề xuất tối ưu chi phí', + icon: '', + accentColor: 'indigo', + steps: [ + { + id: 'dp-input', + type: 'user-input', + name: '/ck:deploy', + descEn: 'You say "deploy", "go live", or name a platform', + descVi: 'Bạn nói "deploy", "go live", hoặc chỉ định platform', + explainEn: 'You invoke deploy with an optional platform argument:\n\n• "/ck:deploy" — auto-detect everything\n• "/ck:deploy vercel" — target Vercel\n• "/ck:deploy railway production" — deploy to Railway prod\n\nSupports 15 platforms: Vercel, Netlify, Cloudflare, Railway, Fly.io, Render, Heroku, TOSE.sh, Coolify, Dokploy, Github Pages, GCP, AWS, Digital Ocean, Vultr.', + explainVi: 'Bạn gọi deploy với platform tuỳ chọn:\n\n• "/ck:deploy" — tự động phát hiện\n• "/ck:deploy vercel" — chỉ định Vercel\n• "/ck:deploy railway production" — deploy lên Railway prod\n\nHỗ trợ 15 platforms: Vercel, Netlify, Cloudflare, Railway, Fly.io, Render, Heroku, TOSE.sh, Coolify, Dokploy, Github Pages, GCP, AWS, Digital Ocean, Vultr.', + codeSnippet: '> /ck:deploy\n> /ck:deploy vercel\n> /ck:deploy railway production', + icon: '', + color: 'purple', + }, + { + id: 'dp-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection for project and deployment config', + descVi: 'Inject context cho project và config deployment', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project type, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards.', + explainVi: 'Hooks fire ở lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project type, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules', + icon: '', + color: 'blue', + }, + { + id: 'dp-detect', + type: 'agent', + name: 'Detect + Recommend Platform', + descEn: '4-step detection cascade, cost-optimized recommendation', + descVi: 'Detection cascade 4 bước, đề xuất tối ưu chi phí', + explainEn: 'Detection cascade (stops at first match):\n\n1. docs/deployment.md — parse existing config\n2. Config files — vercel.json, netlify.toml, fly.toml, wrangler.toml, etc.\n3. Project type → cost-optimized recommendations:\n Static → Github Pages (free) → Cloudflare\n SPA/SSR → Vercel → Netlify\n API → Railway ($5 free) → Render\n Docker → Fly.io → Railway\n4. AskUserQuestion with top 4 options', + explainVi: 'Detection cascade (dừng ở match đầu tiên):\n\n1. docs/deployment.md — parse config hiện có\n2. Config files — vercel.json, netlify.toml, fly.toml, wrangler.toml, v.v.\n3. Project type → đề xuất tối ưu chi phí:\n Static → Github Pages (free) → Cloudflare\n SPA/SSR → Vercel → Netlify\n API → Railway ($5 free) → Render\n Docker → Fly.io → Railway\n4. AskUserQuestion với top 4 lựa chọn', + codeSnippet: '// Detection cascade:\n// 1. docs/deployment.md → existing config\n// 2. vercel.json, fly.toml, etc.\n// 3. Project type → cost-optimized pick\n// 4. AskUserQuestion → user picks', + icon: '', + color: 'green', + }, + { + id: 'dp-execute', + type: 'agent', + name: 'CLI Setup + Deploy', + descEn: 'Install CLI, authenticate, run deploy, verify URL is live', + descVi: 'Cài CLI, xác thực, chạy deploy, verify URL hoạt động', + explainEn: '3-step deploy sequence:\n\n1. Check CLI → install if missing (npm i -g vercel, brew install flyctl)\n2. Check auth → login if needed\n3. Run deploy from platform-specific reference\n\nAfter deploy: verify URL returns HTTP 200. If fail → troubleshoot → escalate to /ck:devops.\n\nSecurity: checks .env + .gitignore before deploying. Progressive: loads only needed platform reference.', + explainVi: 'Deploy sequence 3 bước:\n\n1. Kiểm CLI → cài nếu thiếu\n2. Kiểm auth → login nếu cần\n3. Chạy deploy từ platform reference\n\nSau deploy: verify URL trả HTTP 200. Nếu fail → troubleshoot → chuyển /ck:devops.\n\nBảo mật: kiểm .env + .gitignore trước deploy. Progressive: chỉ load platform reference cần thiết.', + codeSnippet: '// 1. which vercel || npm i -g vercel\n// 2. vercel whoami || vercel login\n// 3. vercel --prod\n// 4. curl $URL → 200? → success\n// Security: scan .env before deploy', + icon: '', + color: 'green', + }, + { + id: 'dp-output', + type: 'output', + name: 'docs/deployment.md', + descEn: 'Create/update deployment docs with URL, commands, rollback', + descVi: 'Tạo/cập nhật deployment docs với URL, commands, rollback', + explainEn: 'Creates or updates docs/deployment.md with:\n\n• Platform name + version\n• Production URL\n• Deploy command used\n• Environment variables required\n• Custom domain setup\n• Rollback instructions\n\nNext /ck:deploy auto-detects from this file (highest priority).', + explainVi: 'Tạo hoặc cập nhật docs/deployment.md:\n\n• Tên platform + version\n• Production URL\n• Deploy command đã dùng\n• Environment variables cần thiết\n• Custom domain setup\n• Rollback instructions\n\nLần /ck:deploy sau auto-detect từ file này (ưu tiên cao nhất).', + codeSnippet: '# docs/deployment.md\n## Platform: Vercel\n## URL: https://my-app.vercel.app\n## Deploy: vercel --prod\n## Rollback: vercel rollback', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:predict — Multi-Persona Impact Analysis ───────────── + { + id: 'predict', + command: '/ck:predict', + kit: 'engineer', + titleEn: 'Predict Impact', + titleVi: 'Dự Đoán Tác Động', + descEn: '5 expert personas debate proposed changes before implementation', + descVi: '5 chuyên gia tranh luận thay đổi đề xuất trước khi triển khai', + icon: '', + accentColor: 'yellow', + steps: [ + { + id: 'pd-input', + type: 'user-input', + name: '/ck:predict', + descEn: 'You describe the proposed change or feature', + descVi: 'Bạn mô tả thay đổi hoặc tính năng đề xuất', + explainEn: 'Describe your proposed change. Optionally --files to point at affected code.\n\n• "/ck:predict Add WebSocket for real-time notifications"\n• "/ck:predict Migrate auth from JWT to sessions --files src/api/**/*.ts"\n\nThis skill does NOT implement anything — analysis and verdict only.', + explainVi: 'Mô tả thay đổi đề xuất. Tuỳ chọn --files chỉ code liên quan.\n\n• "/ck:predict Thêm WebSocket cho real-time"\n• "/ck:predict Migrate auth từ JWT sang sessions --files src/api/**/*.ts"\n\nSkill này KHÔNG implement — chỉ phân tích và đưa verdict.', + codeSnippet: '> /ck:predict "Replace REST with GraphQL" --files src/api/**/*.ts\n\n# Analysis only — no code written\n# Output: GO / CAUTION / STOP', + icon: '', + color: 'purple', + }, + { + id: 'pd-hooks', + type: 'hook', + name: 'Hooks Fire', + descEn: 'Context injection for project understanding', + descVi: 'Inject context để hiểu project', + explainEn: 'Hooks fire at lifecycle events:\n\n• SessionStart: session-init.cjs — detects project, loads config.\n• UserPromptSubmit: dev-rules-reminder.cjs — injects coding standards.\n\nGives all 5 personas full project awareness.', + explainVi: 'Hooks fire ở lifecycle events:\n\n• SessionStart: session-init.cjs — phát hiện project, load config.\n• UserPromptSubmit: dev-rules-reminder.cjs — inject coding standards.\n\nCho 5 personas nhận biết đầy đủ project.', + codeSnippet: '// SessionStart: session-init.cjs → project config\n// UserPromptSubmit: dev-rules-reminder.cjs → rules', + icon: '', + color: 'blue', + }, + { + id: 'pd-personas', + type: 'agent', + name: '5 Personas Analyze', + descEn: 'Architect, Security, Performance, UX, Devil\'s Advocate each analyze independently', + descVi: 'Architect, Security, Performance, UX, Devil\'s Advocate phân tích độc lập', + explainEn: 'Each persona analyzes through their lens (all in main context, no sub-agents):\n\n• Architect — system design fit, scalability, new coupling\n• Security — attack surface, data exposure, auth violations\n• Performance — latency, N+1 queries, memory leaks, bundle bloat\n• UX — intuitiveness, error states, mobile accessibility\n• Devil\'s Advocate — hidden assumptions, simpler alternatives, "why not do nothing?"', + explainVi: 'Mỗi persona phân tích qua lăng kính riêng (tất cả trong main context, không sub-agent):\n\n• Architect — phù hợp thiết kế, scalability, coupling mới\n• Security — attack surface, data exposure, vi phạm auth\n• Performance — latency, N+1 queries, memory leaks, bundle bloat\n• UX — trực quan, error states, mobile accessibility\n• Devil\'s Advocate — giả định ẩn, alternative đơn giản hơn', + codeSnippet: '// 5 Personas (all in main context):\n// 🏗️ Architect → design fit?\n// 🔒 Security → attack surface?\n// ⚡ Performance → latency impact?\n// 👤 UX → intuitive?\n// 😈 Devil\'s Adv → why not do nothing?', + icon: '', + color: 'green', + }, + { + id: 'pd-debate', + type: 'agent', + name: 'Agreements + Conflicts', + descEn: 'Find consensus, debate disagreements, produce resolutions', + descVi: 'Tìm đồng thuận, tranh luận bất đồng, đưa ra giải pháp', + explainEn: 'Compare all 5 analyses:\n\n• Agreements — points where 4-5 personas align (low-risk aspects)\n• Conflicts — meaningful disagreements with tradeoff table: Topic × 5 Personas × Resolution\n\nConflicts are the most valuable part — surfacing hidden tensions before code is written.', + explainVi: 'So sánh cả 5 phân tích:\n\n• Agreements — điểm 4-5 personas đồng thuận (khía cạnh ít rủi ro)\n• Conflicts — bất đồng có ý nghĩa với bảng tradeoff: Topic × 5 Personas × Resolution\n\nConflicts là phần giá trị nhất — bộc lộ tensions ẩn trước khi viết code.', + codeSnippet: '// Conflict table:\n// | Topic | Arch | Sec | Perf | UX | DA | Resolution |\n// | Cache | ✅ | ⚠️ | ✅ | - | ❌ | Use w/ TTL |', + icon: '', + color: 'amber', + }, + { + id: 'pd-verdict', + type: 'output', + name: 'Verdict Report', + descEn: 'GO / CAUTION / STOP with risk summary and recommendations', + descVi: 'GO / CAUTION / STOP với tóm tắt rủi ro và recommendations', + explainEn: 'Structured prediction report:\n\n• Verdict: GO (proceed), CAUTION (proceed with mitigations), STOP (needs redesign)\n• Agreements + Conflicts & Resolutions\n• Risk Summary with severity (Critical/High/Medium/Low)\n• Numbered recommendations\n\nSTOP triggers: auth bypass, design incompatibility, unacceptable latency, or false core assumption.', + explainVi: 'Prediction report có cấu trúc:\n\n• Verdict: GO (tiến hành), CAUTION (cẩn thận với mitigations), STOP (cần redesign)\n• Agreements + Conflicts & Resolutions\n• Risk Summary với severity\n• Recommendations đánh số\n\nSTOP trigger: auth bypass, design incompatibility, latency không chấp nhận, giả định sai.', + codeSnippet: '## Verdict: CAUTION\n### Risk Summary\n| Risk | Severity | Mitigation |\n| Memory leaks | High | Connection pooling |\n### Recommendations\n1. Connection pooling — Performance\n2. WS-specific auth — Security', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:bootstrap — New Project Scaffolding ───────────────── + { + id: 'bootstrap', + command: '/ck:bootstrap', + kit: 'engineer', + titleEn: 'Bootstrap Project', + titleVi: 'Khởi Tạo Dự Án', + descEn: 'End-to-end project scaffolding: research, design, plan, implement', + descVi: 'Scaffolding dự án từ đầu đến cuối: nghiên cứu, thiết kế, lập kế hoạch, triển khai', + icon: '', + accentColor: 'slate', + steps: [ + { + id: 'bt-input', + type: 'user-input', + name: '/ck:bootstrap', + descEn: 'Describe project + optional mode (full/auto/fast/parallel)', + descVi: 'Mô tả dự án + mode tuỳ chọn (full/auto/fast/parallel)', + explainEn: 'Describe your project with an optional mode:\n\n• --full: Interactive, gates at every phase\n• --auto (default): Automatic, only design gate\n• --fast: Skip research, no gates\n• --parallel: Multi-agent execution', + explainVi: 'Mô tả dự án với mode tuỳ chọn:\n\n• --full: Tương tác, gate ở mọi phase\n• --auto (mặc định): Tự động, chỉ design gate\n• --fast: Bỏ qua research, không gate\n• --parallel: Thực thi đa agent', + codeSnippet: '> /ck:bootstrap "E-commerce with Stripe" --parallel', + icon: '', + color: 'purple', + }, + { + id: 'bt-hooks', + type: 'hook', + name: 'Hooks + Git Init', + descEn: 'Context injection, git-manager initializes repo if needed', + descVi: 'Inject context, git-manager khởi tạo repo nếu cần', + explainEn: 'Hooks fire, then git-manager sub-agent creates repo if not initialized. In --full mode asks user first; other modes auto-init.', + explainVi: 'Hooks fire, rồi git-manager sub-agent tạo repo nếu chưa init. --full hỏi user trước; các mode khác tự động.', + codeSnippet: '// git rev-parse --git-dir → not found?\n// → git-manager sub-agent inits repo', + icon: '', + color: 'blue', + }, + { + id: 'bt-research', + type: 'agent', + name: 'Research + Design', + descEn: 'Parallel researchers explore idea, then tech stack + wireframes', + descVi: 'Researcher song song khám phá ý tưởng, rồi tech stack + wireframes', + explainEn: 'Multiple parallel researcher sub-agents explore idea validation, best solutions, tech landscape (≤150 lines each, skipped in --fast).\n\nThen parallel tracks:\n1. Tech Stack: planner + researcher → ./docs\n2. Design: ui-ux-designer + researcher → wireframes, design-guidelines.md, logo via ai-multimodal\n\nDesign Gate: user must approve (except --fast).', + explainVi: 'Nhiều researcher sub-agent song song khám phá validation ý tưởng, giải pháp, tech landscape (≤150 dòng mỗi, bỏ qua --fast).\n\nSau đó 2 track song song:\n1. Tech Stack: planner + researcher → ./docs\n2. Design: ui-ux-designer + researcher → wireframes, design-guidelines.md, logo qua ai-multimodal\n\nDesign Gate: user phải approve (trừ --fast).', + codeSnippet: '// Researchers ×3 (parallel)\n// → idea validation, solutions, tech landscape\n//\n// Tech Stack: planner + researcher → docs/\n// Design: ui-ux-designer → wireframes + logo\n// [Design Gate] → user approves', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'bt-plan-cook', + type: 'agent', + name: 'Plan (ck:plan) → Build (ck:cook)', + descEn: 'Activate ck:plan then ck:cook for full implementation', + descVi: 'Kích hoạt ck:plan rồi ck:cook cho implementation đầy đủ', + explainEn: 'Sequential skill activation:\n\n1. ck:plan — creates plan.md + phase-XX files (mode-mapped: full→hard, auto→auto, fast→fast, parallel→parallel)\n2. ck:cook — full build pipeline: implement phases → tester → debugger (if failures) → code-reviewer → fix until score ≥9.5\n\nBoth are full skills with their own sub-agent orchestration.', + explainVi: 'Kích hoạt skill tuần tự:\n\n1. ck:plan — tạo plan.md + phase-XX files (map mode: full→hard, auto→auto, fast→fast, parallel→parallel)\n2. ck:cook — full build pipeline: implement → tester → debugger → code-reviewer → fix đến score ≥9.5\n\nCả hai là skills đầy đủ với orchestration sub-agent riêng.', + codeSnippet: '// /ck:plan --auto → plans/260406/plan.md\n// /ck:cook --auto plans/260406/plan.md\n// → implement → test → debug → review\n// → score ≥9.5? → finalize', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'bt-finalize', + type: 'output', + name: 'Docs + Onboard + Commit', + descEn: 'Generate docs, onboard user, summary report, git commit', + descVi: 'Tạo docs, onboard user, báo cáo tổng kết, git commit', + explainEn: 'Finalization sub-agents:\n\n• docs-manager → README, codebase-summary, architecture\n• project-manager → roadmap, plan status\n• Onboarding: AskUserQuestion loop ("Enter API key → .env")\n• git-manager → commit (--fast auto-commits)\n• /ck:journal → session entry', + explainVi: 'Sub-agents finalization:\n\n• docs-manager → README, codebase-summary, architecture\n• project-manager → roadmap, plan status\n• Onboarding: AskUserQuestion loop ("Nhập API key → .env")\n• git-manager → commit (--fast tự động commit)\n• /ck:journal → session entry', + codeSnippet: '// docs-manager → README, architecture\n// project-manager → roadmap\n// AskUserQuestion → onboard user\n// git-manager → commit\n// /ck:journal → session entry', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ck:security — Security Audit (STRIDE + OWASP) ───────── + { + id: 'security-scan', + command: '/ck:security', + kit: 'engineer', + titleEn: 'Security Audit', + titleVi: 'Kiểm Tra Bảo Mật', + descEn: 'STRIDE + OWASP security scan with severity-ranked findings and optional auto-fix', + descVi: 'Quét bảo mật STRIDE + OWASP với findings xếp hạng severity và tuỳ chọn auto-fix', + icon: '', + accentColor: 'red', + steps: [ + { + id: 'ss-input', + type: 'user-input', + name: '/ck:security', + descEn: 'Specify scope glob or "full" with optional --fix flag', + descVi: 'Chỉ định scope glob hoặc "full" với tuỳ chọn --fix', + explainEn: 'Examples:\n\n• /ck:security src/api/**/*.ts — audit API layer\n• /ck:security full — full codebase\n• /ck:security src/ --fix --iterations 15 — audit + auto-fix\n\nWithout --fix: read-only report only.', + explainVi: 'Ví dụ:\n\n• /ck:security src/api/**/*.ts — audit API layer\n• /ck:security full — toàn bộ codebase\n• /ck:security src/ --fix --iterations 15 — audit + auto-fix\n\nKhông --fix: chỉ report read-only.', + codeSnippet: '> /ck:security src/api/**/*.ts\n> /ck:security full\n> /ck:security src/ --fix --iterations 15', + icon: '', + color: 'purple', + }, + { + id: 'ss-scope', + type: 'hook', + name: 'Scope + Project Detection', + descEn: 'Expand glob, detect stack for dependency audit tool', + descVi: 'Mở rộng glob, detect stack cho dependency audit tool', + explainEn: 'Expands glob to file list. Detects project type: package.json → npm audit, pyproject.toml → pip-audit, go.mod → govulncheck, Cargo.toml → cargo audit.', + explainVi: 'Mở rộng glob thành file list. Detect project type: package.json → npm audit, pyproject.toml → pip-audit, go.mod → govulncheck, Cargo.toml → cargo audit.', + codeSnippet: '// Detect: package.json → npm audit\n// pyproject.toml → pip-audit\n// go.mod → govulncheck', + icon: '', + color: 'blue', + }, + { + id: 'ss-stride-owasp', + type: 'agent', + name: 'STRIDE + OWASP Analysis', + descEn: 'Evaluate 6 STRIDE threats, map to OWASP Top 10', + descVi: 'Đánh giá 6 STRIDE threats, ánh xạ sang OWASP Top 10', + explainEn: 'STRIDE 6 categories: Spoofing (auth), Tampering (input validation), Repudiation (logging), Info Disclosure (data leakage), DoS (rate limits), Elevation (RBAC).\n\nFindings cross-referenced with OWASP Top 10 (A01-A10) for comprehensive coverage.', + explainVi: 'STRIDE 6 categories: Spoofing (auth), Tampering (input validation), Repudiation (logging), Info Disclosure (rò rỉ), DoS (rate limits), Elevation (RBAC).\n\nFindings cross-reference với OWASP Top 10 (A01-A10) cho coverage toàn diện.', + codeSnippet: '// STRIDE: S-T-R-I-D-E\n// OWASP: A01 Broken Access Control\n// A03 Injection\n// A07 Auth Failures\n// Cross-reference for full coverage', + icon: '', + color: 'green', + }, + { + id: 'ss-deps', + type: 'agent', + name: 'Dependency + Secret Audit', + descEn: 'npm audit / pip-audit + regex secret scanning (redacted)', + descVi: 'npm audit / pip-audit + quét secrets bằng regex (redacted)', + explainEn: 'Parallel checks:\n\n1. Dependency audit via detected tool\n2. Secret detection: regex for AWS AKIA*, GitHub ghp_*, Stripe sk_*, etc.\n\nSecrets NEVER shown in full — redacted to first 4 + last 2 chars.', + explainVi: 'Kiểm tra song song:\n\n1. Dependency audit qua tool đã detect\n2. Secret detection: regex cho AWS AKIA*, GitHub ghp_*, Stripe sk_*, v.v.\n\nSecrets KHÔNG BAO GIỜ hiện đầy đủ — redact còn 4 đầu + 2 cuối.', + codeSnippet: '// npm audit --json\n// Regex: AKIA[0-9A-Z]{16} → AWS key\n// ghp_[A-Za-z0-9_]{36} → GitHub\n// Output: redacted (AKIA****XY)', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'ss-output', + type: 'output', + name: 'Security Report', + descEn: 'Severity-ranked findings; --fix mode commits fixes iteratively', + descVi: 'Findings xếp hạng severity; --fix mode commit fixes lần lượt', + explainEn: 'Structured report: summary + findings table (severity, STRIDE/OWASP category, file:line, fix recommendation).\n\nWith --fix: applies fixes iteratively (Critical first), runs tests after each, commits as security(fix-N). Stops if tests fail.', + explainVi: 'Report có cấu trúc: summary + bảng findings (severity, STRIDE/OWASP, file:line, đề xuất fix).\n\nVới --fix: apply fixes lần lượt (Critical trước), chạy tests sau mỗi fix, commit security(fix-N). Dừng nếu tests fail.', + codeSnippet: '## Security Audit Report\n| # | Severity | Category | File:Line | Fix |\n| 1 | Critical | Injection | api/users.ts:45 | Parameterized queries |\n| 2 | High | Auth | login.ts:12 | Rate limiting |', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:social:* — Social Media Content ──────────────────── + { + id: 'social', + command: '/ckm:social:*', + kit: 'marketer', + titleEn: 'Social Media Content', + titleVi: 'Nội Dung Social Media', + descEn: 'Create and schedule social posts across X, LinkedIn, Instagram, TikTok, YouTube, Facebook, Threads', + descVi: 'Tạo và lên lịch bài đăng trên X, LinkedIn, Instagram, TikTok, YouTube, Facebook, Threads', + icon: '', + accentColor: 'sky', + steps: [ + { + id: 'sc-input', + type: 'user-input', + name: '/ckm:social', + descEn: 'Specify platform, content type, and topic', + descVi: 'Chỉ định platform, loại content, và chủ đề', + explainEn: 'Invoke with platform and type:\n\n• "/ckm:social linkedin post about feature launch"\n• "/ckm:social x thread on AI trends"\n• "/ckm:social:schedule tomorrow 9am"\n\nPlatforms: X, LinkedIn, Instagram, TikTok, YouTube, Facebook, Threads.\nTypes: post, thread, carousel, story, reel.', + explainVi: 'Gọi với platform và type:\n\n• "/ckm:social linkedin post về feature launch"\n• "/ckm:social x thread về AI trends"\n• "/ckm:social:schedule ngày mai 9am"\n\nPlatforms: X, LinkedIn, Instagram, TikTok, YouTube, Facebook, Threads.\nLoại: post, thread, carousel, story, reel.', + codeSnippet: '> /ckm:social linkedin post about feature launch\n> /ckm:social x thread on AI trends\n> /ckm:social:schedule tomorrow 9am', + icon: '', + color: 'purple', + }, + { + id: 'sc-hooks', + type: 'hook', + name: 'Hooks + Platform Routing', + descEn: 'Brand injection, parse platform, load platform-specific refs', + descVi: 'Inject brand, parse platform, load refs theo platform', + explainEn: 'inject-brand-context.cjs loads brand voice. Routes to platform reference (linkedin-workflow.md, etc.) with character limits and best practices.', + explainVi: 'inject-brand-context.cjs load brand voice. Route đến platform reference (linkedin-workflow.md, v.v.) với character limits và best practices.', + codeSnippet: '// inject-brand-context.cjs → brand voice\n// Route: "linkedin" → linkedin-workflow.md\n// Load: platform-specs.md → limits', + icon: '', + color: 'blue', + }, + { + id: 'sc-create', + type: 'agent', + name: 'Social Manager + Copywriter', + descEn: 'Platform strategy, then content-creator + copywriter draft copy', + descVi: 'Chiến lược platform, rồi content-creator + copywriter soạn copy', + explainEn: 'social-media-manager sub-agent provides platform strategy (format, hashtags, engagement hooks, algorithm tips).\n\nThen content-creator structures the post (hook, body, CTA) and copywriter writes final copy with brand voice and hook-writing techniques.', + explainVi: 'Sub-agent social-media-manager cung cấp chiến lược platform (format, hashtags, engagement hooks, algorithm tips).\n\nSau đó content-creator cấu trúc bài (hook, body, CTA) và copywriter viết copy cuối với brand voice và kỹ thuật hook-writing.', + codeSnippet: '// social-media-manager → platform strategy\n// content-creator → structure (hook, body, CTA)\n// copywriter → final copy with brand voice', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'sc-output', + type: 'output', + name: 'Post Delivered', + descEn: 'Final content saved to assets/posts/{platform}/ with hashtags + media specs', + descVi: 'Content cuối lưu assets/posts/{platform}/ với hashtags + media specs', + explainEn: 'Validated per platform rules (character limits, hashtag count, media ratios). Saved as markdown with posting time suggestion.\n\nFor /ckm:social:schedule, schedule-post.js queues via API.', + explainVi: 'Validate theo rules platform (character limits, hashtag count, media ratios). Lưu markdown với đề xuất thời gian đăng.\n\nVới /ckm:social:schedule, schedule-post.js xếp lịch qua API.', + codeSnippet: '// assets/posts/linkedin/2025-01-15-feature.md\n// Copy + hashtags + media specs + posting time', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:email:* — Email Campaigns & Automation ───────────── + { + id: 'email', + command: '/ckm:email:*', + kit: 'marketer', + titleEn: 'Email Campaigns & Automation', + titleVi: 'Email Marketing & Tự Động Hoá', + descEn: 'Email content, automation flows, drip sequences with subject line optimization', + descVi: 'Nội dung email, automation flows, drip sequences với tối ưu subject line', + icon: '', + accentColor: 'stone', + steps: [ + { + id: 'em-input', + type: 'user-input', + name: '/ckm:email:', + descEn: 'Invoke email subcommand: flow, sequence, or direct', + descVi: 'Gọi subcommand email: flow, sequence, hoặc trực tiếp', + explainEn: 'Subcommands:\n\n• /ckm:email:flow welcome — automation flow\n• /ckm:email:sequence launch "Black Friday" — drip sequence\n• /ckm:email newsletter — direct email generation', + explainVi: 'Subcommands:\n\n• /ckm:email:flow welcome — automation flow\n• /ckm:email:sequence launch "Black Friday" — drip sequence\n• /ckm:email newsletter — tạo email trực tiếp', + codeSnippet: '> /ckm:email:flow welcome\n> /ckm:email:sequence launch "Black Friday"\n> /ckm:email newsletter', + icon: '', + color: 'purple', + }, + { + id: 'em-hooks', + type: 'hook', + name: 'Hooks + Brand Context', + descEn: 'Brand voice injection for email tone and CTA style', + descVi: 'Inject brand voice cho tone email và CTA style', + explainEn: 'inject-brand-context.cjs reads docs/brand-guidelines.md for voice, tone, CTA style. Routes to subcommand reference (flow.md, sequence.md, subject-line-formulas.md).', + explainVi: 'inject-brand-context.cjs đọc docs/brand-guidelines.md cho voice, tone, CTA style. Route đến subcommand reference (flow.md, sequence.md, subject-line-formulas.md).', + codeSnippet: '// inject-brand-context.cjs → voice, tone, CTA\n// Route: "flow" → automation-flows.md\n// "sequence" → sequence.md + email-templates.md', + icon: '', + color: 'blue', + }, + { + id: 'em-wizard', + type: 'agent', + name: 'Email Wizard + Copywriter', + descEn: 'Sequence architecture, then subject lines + body copy via formulas', + descVi: 'Kiến trúc sequence, rồi subject lines + body copy theo formulas', + explainEn: 'email-wizard sub-agent creates sequence architecture (timing, branches, exit conditions, ASCII flow diagram).\n\ncopywriter sub-agent writes per email: 3-5 subject line variants (curiosity gap, benefit, urgency), preview text, body copy (PAS/AIDA/BAB), CTA, P.S. line.\n\nA/B testing variants included.', + explainVi: 'Sub-agent email-wizard tạo kiến trúc sequence (timing, branches, exit conditions, ASCII flow diagram).\n\nSub-agent copywriter viết mỗi email: 3-5 subject line variants (curiosity gap, benefit, urgency), preview text, body copy (PAS/AIDA/BAB), CTA, P.S.\n\nA/B testing variants đi kèm.', + codeSnippet: '// email-wizard → sequence architecture\n// Email 1 (Day 0) → Welcome\n// [Opened?] Yes→2A, No→2B\n//\n// copywriter → per email:\n// Subject A: "Welcome! Quick start guide"\n// Subject B: "[Name], 3 steps to start"\n// Body: PAS framework + CTA', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'em-output', + type: 'output', + name: 'Email Assets', + descEn: 'Complete emails saved to assets/copy/emails/ or assets/emails/flows/', + descVi: 'Email hoàn chỉnh lưu assets/copy/emails/ hoặc assets/emails/flows/', + explainEn: 'Output by type:\n\n• flow → assets/emails/flows/ with ASCII diagram + timing + platform notes\n• sequence → assets/copy/emails/{date}-{type}-sequence/ with numbered email files\n• single → assets/copy/emails/{date}-{slug}.md\n\nAll include A/B subject variants and platform implementation notes.', + explainVi: 'Output theo loại:\n\n• flow → assets/emails/flows/ với ASCII diagram + timing + platform notes\n• sequence → assets/copy/emails/{date}-{type}-sequence/ với email files đánh số\n• single → assets/copy/emails/{date}-{slug}.md\n\nTất cả có A/B subject variants và platform notes.', + codeSnippet: '// assets/copy/emails/20260406-launch-sequence/\n// 00-sequence-plan.md\n// 01-announcement.md\n// 02-social-proof.md\n// 03-urgency.md', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:persona — Customer Persona ───────────────────────── + { + id: 'persona', + command: '/ckm:persona', + kit: 'marketer', + titleEn: 'Customer Persona', + titleVi: 'Chân Dung Khách Hàng', + descEn: 'Create and manage customer personas with market-validated ICP profiles', + descVi: 'Tạo và quản lý chân dung khách hàng với ICP profiles đã validate', + icon: '', + accentColor: 'purple', + steps: [ + { + id: 'ps-input', + type: 'user-input', + name: '/ckm:persona', + descEn: 'You invoke with action: create, analyze, update, or list', + descVi: 'Bạn gọi với action: create, analyze, update, hoặc list', + explainEn: '4 actions:\n\n• create — new persona from scratch (most comprehensive)\n• analyze — analyze existing audience data\n• update [name] — revise existing persona\n• list — show all saved personas', + explainVi: '4 actions:\n\n• create — persona mới từ đầu (toàn diện nhất)\n• analyze — phân tích audience data hiện có\n• update [name] — chỉnh sửa persona đã có\n• list — hiển thị tất cả personas', + codeSnippet: '> /ckm:persona create\n> /ckm:persona analyze\n> /ckm:persona update "Tech Startup Founder"', + icon: '', + color: 'purple', + }, + { + id: 'ps-gather', + type: 'agent', + name: 'Data Gathering (5 dimensions)', + descEn: 'AskUserQuestion collects demographics, pain points, goals, buying behavior, channels', + descVi: 'AskUserQuestion thu thập demographics, pain points, goals, buying behavior, channels', + explainEn: 'Collects 5 dimensions via AskUserQuestion:\n\n1. Demographics (age, role, industry)\n2. Pain points (challenges, frustrations)\n3. Goals (motivations, outcomes)\n4. Buying behavior (budget, triggers)\n5. Preferred channels (social, email, search)\n\nHARD GATE: all 5 required before generation.', + explainVi: 'Thu thập 5 chiều qua AskUserQuestion:\n\n1. Demographics (tuổi, vai trò, ngành)\n2. Pain points (thách thức, khó khăn)\n3. Goals (động lực, kết quả)\n4. Buying behavior (ngân sách, triggers)\n5. Preferred channels (social, email, search)\n\nHARD GATE: phải đủ 5 chiều.', + codeSnippet: '// Q1: Demographics\n// Q2: Pain points\n// Q3: Goals\n// Q4: Buying behavior\n// Q5: Preferred channels\n// HARD GATE: all 5 required', + icon: '', + color: 'amber', + }, + { + id: 'ps-agents', + type: 'agent', + name: 'Lead Qualifier + Researcher', + descEn: 'Structure ICP profile, then validate against market data', + descVi: 'Cấu trúc hoá ICP profile, rồi validate với dữ liệu thị trường', + explainEn: 'lead-qualifier sub-agent structures raw input into ICP framework (demographics, psychographics, buying journey).\n\nresearcher sub-agent validates via WebSearch: market data, industry benchmarks, real signals. Flags unvalidated assumptions.\n\nEnsures persona reflects reality, not just assumptions.', + explainVi: 'Sub-agent lead-qualifier cấu trúc input thô thành ICP framework (demographics, psychographics, buying journey).\n\nSub-agent researcher validate qua WebSearch: dữ liệu thị trường, benchmarks, tín hiệu thực. Flag giả định chưa validate.\n\nĐảm bảo persona phản ánh thực tế.', + codeSnippet: '// lead-qualifier → ICP framework\n// researcher → WebSearch market validation\n// ✅ market-confirmed assumptions\n// ⚠️ unvalidated → flagged', + icon: '', + color: 'green', + isSubAgent: true, + }, + { + id: 'ps-output', + type: 'output', + name: 'ICP Profile', + descEn: 'Market-validated persona saved to assets/leads/icp-profiles/', + descVi: 'Persona đã validate lưu assets/leads/icp-profiles/', + explainEn: 'Comprehensive ICP Profile markdown:\n\n• Name, avatar, demographics\n• Psychographics (goals, values)\n• Pain points with severity\n• Buying behavior + triggers\n• Preferred channels\n• Market validation notes from researcher\n\nSaved to assets/leads/icp-profiles/{persona-name}.md', + explainVi: 'ICP Profile markdown toàn diện:\n\n• Tên, avatar, demographics\n• Psychographics (goals, values)\n• Pain points với severity\n• Buying behavior + triggers\n• Preferred channels\n• Ghi chú validation từ researcher\n\nLưu assets/leads/icp-profiles/{persona-name}.md', + codeSnippet: '// assets/leads/icp-profiles/tech-startup-founder.md\n// Demographics: 28-42, CTO/Founder, SaaS\n// Pain points: scaling eng, technical debt\n// Channels: Twitter, HN, Dev blogs\n// Validation: ✅ market-confirmed', + icon: '', + color: 'amber', + }, + ], + }, + + // ─── /ckm:video:* — Video Production Pipeline ──────────────── + { + id: 'video', + command: '/ckm:video:*', + kit: 'marketer', + titleEn: 'Video Production', + titleVi: 'Sản Xuất Video', + descEn: 'AI-powered video pipeline: scripts, storyboards, Veo 3.1 generation, platform export', + descVi: 'Pipeline video AI: script, storyboard, tạo video Veo 3.1, xuất theo nền tảng', + icon: '', + accentColor: 'zinc', + steps: [ + { + id: 'vd-input', + type: 'user-input', + name: '/ckm:video:', + descEn: 'Invoke: create, script-create, or storyboard-create', + descVi: 'Gọi: create, script-create, hoặc storyboard-create', + explainEn: '3 subcommands:\n\n• /ckm:video create — full pipeline to exported video\n• /ckm:video script-create — production-ready script with AI prompts\n• /ckm:video storyboard-create
- {/* Node with hover tooltip */} -
+ {/* Node */} - {/* Hover tooltip popup — mini card with extra context */} - -
{/* close .relative.group wrapper */} - {/* Vertical Arrow connector (not on last item) */}
- {/* Terminal Header */} + {/* Terminal Header with prev/next navigation */}
-
- + + {/* Center: command + step counter */} +
+ +
+ + {/* Prev / Next buttons */} +
+ +
@@ -51,18 +75,18 @@ const isVi = currentLang === 'vi'; >
-
- {/* Step name + type */} -
+
+ {/* Step name + type badge */} +

- {/* Detailed explanation */} -

+ {/* Formatted explanation — paragraphs + indented bullets */} +
@@ -82,3 +106,36 @@ const isVi = currentLang === 'vi';
+ + From 4dacc48d009f0c962652413029eb7f55728ee64f Mon Sep 17 00:00:00 2001 From: Thieu Nguyen Date: Tue, 7 Apr 2026 10:58:27 +0700 Subject: [PATCH 4/4] feat(guides): add kit tab toggle and filtering to how-ck-works scenario selector MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Engineer Kit / Marketing Kit tab toggle with counts - Implement activeKit state and switchKit() method in Alpine component - Add filteredScenarios computed property for filtering scenarios by kit - Rename "Marketer Kit" → "Marketing Kit" across data and UI - Auto-select first scenario of new kit on tab switch - Update scenario info card kit label with color-coded styling --- .../guides/how-ck-works/HowCkWorksGuide.astro | 20 ++- .../workflow-scenario-selector.astro | 117 +++++++++++------- .../how-ck-works/workflow-visualizer-types.ts | 2 +- 3 files changed, 92 insertions(+), 47 deletions(-) diff --git a/src/components/guides/how-ck-works/HowCkWorksGuide.astro b/src/components/guides/how-ck-works/HowCkWorksGuide.astro index 2e9c68b..78d60d7 100644 --- a/src/components/guides/how-ck-works/HowCkWorksGuide.astro +++ b/src/components/guides/how-ck-works/HowCkWorksGuide.astro @@ -55,6 +55,7 @@ const typeColorsJson = JSON.stringify(stepTypeColors);
- {isVi ? 'Chọn Workflow' : 'Choose a Workflow'} - diff --git a/src/components/guides/how-ck-works/workflow-scenario-selector.astro b/src/components/guides/how-ck-works/workflow-scenario-selector.astro index 3a78a94..f89bc96 100644 --- a/src/components/guides/how-ck-works/workflow-scenario-selector.astro +++ b/src/components/guides/how-ck-works/workflow-scenario-selector.astro @@ -1,7 +1,7 @@ --- -// Scenario picker — compact pill tags grouped by kit (Engineer/Marketer) -// Shows icon + command only; description appears on hover via tooltip -// Uses Alpine.js x-data from parent HowItWorksGuide component +// Scenario picker with Engineer Kit / Marketing Kit tab toggle +// Compact pill tags for scenarios, filtered by active kit tab +// Uses Alpine.js x-data from parent HowCkWorksGuide component import { getLangFromUrl, type Language } from '@/i18n'; import { workflowScenarios, kitConfigs } from '@/data/guides/how-ck-works'; @@ -36,49 +36,78 @@ const accentMap: Record ({ - ...kit, - scenarios: workflowScenarios.filter(s => s.kit === kit.id), -})).filter(g => g.scenarios.length > 0); +// Pre-compute scenario counts per kit +const engineerCount = workflowScenarios.filter(s => s.kit === 'engineer').length; +const marketerCount = workflowScenarios.filter(s => s.kit === 'marketer').length; ---
- {scenariosByKit.map((group) => ( -
- {/* Kit group label */} -

- {isVi ? group.labelVi : group.labelEn} -

+ {/* Kit Tab Toggle — matching workflows page design */} +
+ + +
- {/* Compact pill tags — icon + command only, description on hover */} -
- {group.scenarios.map((scenario) => { - const accent = accentMap[scenario.accentColor] || accentMap.purple; - const desc = isVi ? scenario.descVi : scenario.descEn; - return ( - - ); - })} -
-
- ))} + {/* Command name only */} + {scenario.command} + + ); + })} +
{/* Selected scenario info card */}
({
- +

diff --git a/src/data/guides/how-ck-works/workflow-visualizer-types.ts b/src/data/guides/how-ck-works/workflow-visualizer-types.ts index bc6dac4..cfe95b1 100644 --- a/src/data/guides/how-ck-works/workflow-visualizer-types.ts +++ b/src/data/guides/how-ck-works/workflow-visualizer-types.ts @@ -33,7 +33,7 @@ export interface KitConfig { export const kitConfigs: KitConfig[] = [ { id: 'engineer', labelEn: 'Engineer Kit', labelVi: 'Engineer Kit' }, - { id: 'marketer', labelEn: 'Marketer Kit', labelVi: 'Marketer Kit' }, + { id: 'marketer', labelEn: 'Marketing Kit', labelVi: 'Marketing Kit' }, ]; export interface WorkflowScenario {