thanh-kit 2.5.0 → 2.5.2

package/templates/skills/cook/references/subagent-patterns.md

@@ -0,0 +1,75 @@
+# Subagent Patterns
+
+Standard patterns for spawning and using subagents in cook workflows.
+
+## Task Tool Pattern
+```
+Task(subagent_type="[type]", prompt="[task description]", description="[brief]")
+```
+
+## Research Phase
+```
+Task(subagent_type="researcher", prompt="Research [topic]. Report ≤150 lines.", description="Research [topic]")
+```
+- Use multiple researchers in parallel for different topics
+- Keep reports ≤150 lines with citations
+
+## Scout Phase
+```
+Task(subagent_type="scout", prompt="Find files related to [feature] in codebase", description="Scout [feature]")
+```
+- Use `/ck:scout ext` (preferred) or `/ck:scout` (fallback)
+
+## Planning Phase
+```
+Task(subagent_type="planner", prompt="Create implementation plan based on reports: [reports]. Save to [path]", description="Plan [feature]")
+```
+- Input: researcher and scout reports
+- Output: `plan.md` + `phase-XX-*.md` files
+
+## UI Implementation
+```
+Task(subagent_type="ui-ux-designer", prompt="Implement [feature] UI per ./docs/design-guidelines.md", description="UI [feature]")
+```
+- For frontend work
+- Follow design guidelines
+
+## Testing
+```
+Task(subagent_type="tester", prompt="Run test suite for plan phase [phase-name]", description="Test [phase]")
+```
+- Must achieve 100% pass rate
+
+## Debugging
+```
+Task(subagent_type="debugger", prompt="Analyze failures: [details]", description="Debug [issue]")
+```
+- Use when tests fail
+- Provides root cause analysis
+
+## Code Review
+```
+Task(subagent_type="code-reviewer", prompt="Review changes for [phase]. Check security, performance, YAGNI/KISS/DRY. Return score (X/10), critical, warnings, suggestions.", description="Review [phase]")
+```
+
+## Project Management
+```
+Task(subagent_type="project-manager", prompt="Run full sync-back in [plan-path]: reconcile completed tasks with all phase files, backfill stale completed checkboxes across all phases, update plan.md status/progress, and report unresolved mappings.", description="Update plan")
+```
+
+## Documentation
+```
+Task(subagent_type="docs-manager", prompt="Update docs for [phase]. Changed files: [list]", description="Update docs")
+```
+
+## Git Operations
+```
+Task(subagent_type="git-manager", prompt="Stage and commit changes with conventional commit message", description="Commit changes")
+```
+
+## Parallel Execution
+```
+Task(subagent_type="fullstack-developer", prompt="Implement [phase-file] with file ownership: [files]", description="Implement phase [N]")
+```
+- Launch multiple for parallel phases
+- Include file ownership boundaries

package/templates/skills/cook/references/workflow-steps.md

@@ -0,0 +1,172 @@
+# Unified Workflow Steps
+
+All modes share core steps with mode-specific variations.
+
+## Step 0: Intent Detection & Setup
+
+1. Parse input with `intent-detection.md` rules
+2. Log detected mode: `✓ Step 0: Mode [X] - [reason]`
+3. If mode=code: detect plan path, set active plan
+4. Use `TaskCreate` to create workflow step tasks (with dependencies if complex)
+
+**Output:** `✓ Step 0: Mode [interactive|auto|fast|parallel|no-test|code] - [detection reason]`
+
+## Step 1: Research (skip if fast/code mode)
+
+**Interactive/Auto:**
+- Spawn multiple `researcher` agents in parallel
+- Use `/ck:scout ext` or `scout` agent for codebase search
+- Keep reports ≤150 lines
+
+**Parallel:**
+- Optional: max 2 researchers if complex
+
+**Output:** `✓ Step 1: Research complete - [N] reports gathered`
+
+### [Review Gate 1] Post-Research (skip if auto mode)
+- Present research summary to user
+- Use `AskUserQuestion` to ask: "Proceed to planning?" / "Request more research" / "Abort"
+- **Auto mode:** Skip this gate
+
+## Step 2: Planning
+
+**Interactive/Auto/No-test:**
+- Use `planner` agent with research context
+- Create `plan.md` + `phase-XX-*.md` files
+
+**Fast:**
+- Use `/ck:plan --fast` with scout results only
+- Minimal planning, focus on action
+
+**Parallel:**
+- Use `/ck:plan --parallel` for dependency graph + file ownership matrix
+
+**Code:**
+- Skip - plan already exists
+- Parse existing plan for phases
+
+**Output:** `✓ Step 2: Plan created - [N] phases`
+
+### [Review Gate 2] Post-Plan (skip if auto mode)
+- Present plan overview with phases
+- Use `AskUserQuestion` to ask: "Validate the plan or approve plan to start implementation?" - "Validate" / "Approve" / "Abort" / "Other" ("Request revisions")
+  - "Validate": run `/ck:plan validate` slash command
+  - "Approve": continue to implementation
+  - "Abort": stop the workflow
+  - "Other": revise the plan based on user's feedback
+- **Auto mode:** Skip this gate
+
+## Step 3: Implementation
+
+**IMPORTANT:**
+1. `TaskList` first — check for existing tasks (hydrated by planning skill in same session)
+2. If tasks exist → pick them up, skip re-creation
+3. If no tasks → read plan phases, `TaskCreate` for each unchecked `[ ]` item with priority order and metadata (`phase`, `planDir`, `phaseFile`)
+4. Tasks can be blocked by other tasks via `addBlockedBy`
+
+**All modes:**
+- Use `TaskUpdate` to mark tasks as `in_progress` immediately.
+- Execute phase tasks sequentially (Step 3.1, 3.2, etc.)
+- Use `ui-ux-designer` for frontend
+- Use `ck:ai-multimodal` for image assets
+- Run type checking after each file
+
+**Parallel mode:**
+- Utilize all tools of Claude Tasks: `TaskCreate`, `TaskUpdate`, `TaskGet` and `TaskList`
+- Launch multiple `fullstack-developer` agents
+- When agents pick up a task, use `TaskUpdate` to assign task to agent and mark tasks as `in_progress` immediately.
+- Respect file ownership boundaries
+- Wait for parallel group before next
+
+**Output:** `✓ Step 3: Implemented [N] files - [X/Y] tasks complete`
+
+### [Review Gate 3] Post-Implementation (skip if auto mode)
+- Present implementation summary (files changed, key changes)
+- Use `AskUserQuestion` to ask: "Proceed to testing?" / "Request implementation changes" / "Abort"
+- **Auto mode:** Skip this gate
+
+## Step 4: Testing (skip if no-test mode)
+
+**All modes (except no-test):**
+- Write tests: happy path, edge cases, errors
+- **MUST** spawn `tester` subagent: `Task(subagent_type="tester", prompt="Run test suite", description="Run tests")`
+- If failures: **MUST** spawn `debugger` subagent → fix → repeat
+- **Forbidden:** fake mocks, commented tests, changed assertions, skipping subagent delegation
+
+**Output:** `✓ Step 4: Tests [X/X passed] - tester subagent invoked`
+
+### [Review Gate 4] Post-Testing (skip if auto mode)
+- Present test results summary
+- Use `AskUserQuestion` to ask: "Proceed to code review?" / "Request test fixes" / "Abort"
+- **Auto mode:** Skip this gate
+
+## Step 5: Code Review
+
+**All modes - MANDATORY subagent:**
+- **MUST** spawn `code-reviewer` subagent: `Task(subagent_type="code-reviewer", prompt="Review changes. Return score, critical issues, warnings.", description="Code review")`
+- **DO NOT** review code yourself - delegate to subagent
+
+**Interactive/Parallel/Code/No-test:**
+- Interactive cycle (max 3): see `review-cycle.md`
+- Requires user approval
+
+**Auto:**
+- Auto-approve if score≥9.5 AND 0 critical
+- Auto-fix critical (max 3 cycles)
+- Escalate to user after 3 failed cycles
+
+**Fast:**
+- Simplified review, no fix loop
+- User approves or aborts
+
+**Output:** `✓ Step 5: Review [score]/10 - [Approved|Auto-approved] - code-reviewer subagent invoked`
+
+## Step 6: Finalize
+
+**All modes - MANDATORY subagents (NON-NEGOTIABLE):**
+1. **MUST** spawn these subagents in parallel:
+   - `Task(subagent_type="project-manager", prompt="Run full sync-back for [plan-path]: reconcile all completed Claude Tasks with all phase files, backfill stale completed checkboxes across every phase, then update plan.md frontmatter/table progress. Do NOT only mark current phase.", description="Update plan")`
+   - `Task(subagent_type="docs-manager", prompt="Update docs for changes.", description="Update docs")`
+2. Project-manager sync-back MUST include:
+   - Sweep all `phase-XX-*.md` files in the plan directory.
+   - Mark every completed item `[ ] → [x]` based on completed tasks (including earlier phases finished before current phase).
+   - Update `plan.md` status/progress (`pending`/`in-progress`/`completed`) from actual checkbox state.
+   - Return unresolved mappings if any completed task cannot be matched to a phase file.
+3. Use `TaskUpdate` to mark Claude Tasks complete after sync-back confirmation.
+4. Onboarding check (API keys, env vars)
+5. **MUST** spawn git subagent: `Task(subagent_type="git-manager", prompt="Stage and commit changes", description="Commit")`
+
+**CRITICAL:** Step 6 is INCOMPLETE without spawning all 3 subagents. DO NOT skip subagent delegation.
+
+**Auto mode:** Continue to next phase automatically, start from **Step 3**.
+**Others:** Ask user before next phase
+
+**Output:** `✓ Step 6: Finalized - 3 subagents invoked - Full-plan sync-back completed - Committed`
+
+## Mode-Specific Flow Summary
+
+Legend: `[R]` = Review Gate (human approval required)
+
+```
+interactive: 0 → 1 → [R] → 2 → [R] → 3 → [R] → 4 → [R] → 5(user) → 6
+auto:        0 → 1 → 2 → 3 → 4 → 5(auto) → 6 → next phase (NO stops)
+fast:        0 → skip → 2(fast) → [R] → 3 → [R] → 4 → [R] → 5(simple) → 6
+parallel:    0 → 1? → [R] → 2(parallel) → [R] → 3(multi-agent) → [R] → 4 → [R] → 5(user) → 6
+no-test:     0 → 1 → [R] → 2 → [R] → 3 → [R] → skip → 5(user) → 6
+code:        0 → skip → skip → 3 → [R] → 4 → [R] → 5(user) → 6
+```
+
+**Key difference:** `auto` mode is the ONLY mode that skips all review gates.
+
+## Critical Rules
+
+- Never skip steps without mode justification
+- **MANDATORY SUBAGENT DELEGATION:** Steps 4, 5, 6 MUST spawn subagents via Task tool. DO NOT implement directly.
+  - Step 4: `tester` (and `debugger` if failures)
+  - Step 5: `code-reviewer`
+  - Step 6: `project-manager`, `docs-manager`, `git-manager`
+- Use `TaskCreate` to create Claude Tasks for each unchecked item with priority order and dependencies.
+- Use `TaskUpdate` to mark Claude Tasks `in_progress` when picking up a task.
+- Use `TaskUpdate` to mark Claude Tasks `complete` immediately after finalizing the task.
+- All step outputs follow format: `✓ Step [N]: [status] - [metrics]`
+- **VALIDATION:** If Task tool calls = 0 at end of workflow, the workflow is INCOMPLETE.

package/templates/skills/copywriting/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ck:copywriting
+description: Conversion copywriting formulas, headline templates, email copy patterns, landing page structures, CTA optimization, and writing style extraction. Activate for writing high-converting copy, crafting headlines, email campaigns, landing pages, or applying custom writing styles from assets/writing-styles/ directory.
+license: MIT
+argument-hint: "[copy-type] [context]"
+---
+
+# Copywriting
+
+Formulas, templates, patterns, and writing styles for high-converting copy.
+
+## When to Use
+
+- Writing headlines/subject lines, landing page copy, email campaigns
+- Social posts, product descriptions, CTA optimization, A/B variations
+- Applying custom writing styles from user documents
+
+## Writing Styles
+
+Load: `references/writing-styles.md` | Full catalog: `assets/writing-styles/default.md` (50 styles)
+
+**Extract styles from multi-format files:**
+```bash
+python .claude/skills/copywriting/scripts/extract-writing-styles.py --list        # List files
+python .claude/skills/copywriting/scripts/extract-writing-styles.py --style <name> # Extract style
+```
+
+**Formats:** `.md` `.txt` `.pdf` `.docx` `.xlsx` `.pptx` `.jpg` `.png` `.mp4` (docs/media need `GEMINI_API_KEY`)
+
+## Copy Formulas
+
+Load: `references/copy-formulas.md`
+
+| Formula | Structure | Best For |
+|---------|-----------|----------|
+| AIDA | Attention → Interest → Desire → Action | Landing pages, ads |
+| PAS | Problem → Agitate → Solution | Email, sales pages |
+| BAB | Before → After → Bridge | Testimonials, case studies |
+| 4Ps | Promise → Picture → Proof → Push | Long-form sales |
+| 4Us | Urgent + Unique + Useful + Ultra-specific | Headlines |
+| FAB | Feature → Advantage → Benefit | Product descriptions |
+
+## Headlines
+
+Load: `references/headline-templates.md`
+
+Patterns: "How to [X] without [Y]" • "[Number] ways to [benefit]" • "The secret to [outcome]" • "Why [belief] is wrong"
+
+## Email Copy
+
+Load: `references/email-copy.md`
+
+Subject lines: Curiosity gap • Benefit-driven • Question • Urgency
+
+## Landing Pages & CTAs
+
+Load: `references/landing-page-copy.md` | `references/cta-patterns.md`
+
+Hero: Headline (promise) → Subheadline (how) → CTA (action) → Social proof
+CTAs: "Start [verb]ing" • "Get [benefit]" • "Yes, I want [benefit]"
+
+## Workflows
+
+| Workflow | Purpose | Use When |
+|----------|---------|----------|
+| `references/workflow-cro.md` | CRO optimization (25 principles) + plan creation workflow | Conversion optimization & CRO plan requests |
+| `references/workflow-enhance.md` | Copy enhancement | Improving existing copy |
+| `references/workflow-fast.md` | Quick copy generation | Simple, time-sensitive requests |
+| `references/workflow-good.md` | Quality copy with research | High-stakes content |
+
+## References
+
+| File | Purpose |
+|------|---------|
+| `references/writing-styles.md` | 30 writing styles quick reference |
+| `references/copy-formulas.md` | AIDA, PAS, BAB, 4Ps, FAB formulas |
+| `references/headline-templates.md` | Headline patterns & templates |
+| `references/email-copy.md` | Email copy patterns |
+| `references/landing-page-copy.md` | Landing page structure |
+| `references/cta-patterns.md` | CTA optimization |
+| `references/power-words.md` | Power words by emotion |
+| `references/social-media-copy.md` | Platform-specific copy |
+| `scripts/extract-writing-styles.py` | Extract styles from multi-format files |
+| `templates/copy-brief.md` | Creative brief template |
+
+## Agent Integration
+
+**Primary:** fullstack-developer | **Related:** brand-guidelines, content-marketing, email-marketing
+
+## Best Practices
+
+1. Lead with benefit, not feature | 2. One CTA per piece
+3. Specificity > vague claims | 4. Read aloud—if awkward, rewrite
+5. Test headlines first | 6. Match copy to awareness level

package/templates/skills/copywriting/references/copy-formulas.md

@@ -0,0 +1,150 @@
+# Copy Formulas
+
+Proven frameworks for persuasive writing.
+
+## AIDA (Attention → Interest → Desire → Action)
+
+The classic framework. Works for landing pages, ads, sales emails.
+
+```
+ATTENTION: Bold claim or pattern interrupt
+INTEREST: Explain why this matters to them
+DESIRE: Paint the picture of transformation
+ACTION: Clear CTA with urgency
+```
+
+**Example:**
+```
+[A] Stop losing 80% of your leads.
+[I] Most businesses capture emails but never convert them.
+    The problem isn't your product—it's your follow-up.
+[D] Imagine waking up to sales notifications while you sleep.
+    Our automation sends the right message at the right time.
+[A] Start your free trial → No credit card required.
+```
+
+## PAS (Problem → Agitate → Solution)
+
+Dan Kennedy's "most reliable formula." Works for email, sales pages.
+
+```
+PROBLEM: Name the specific pain
+AGITATE: Twist the knife (consequences, frustration)
+SOLUTION: Present your offer as the answer
+```
+
+**Example:**
+```
+[P] You're posting on LinkedIn daily but getting zero leads.
+[A] Hours of content creation. Crickets in your DMs.
+    Meanwhile, competitors with worse products are
+    booking calls. What do they know that you don't?
+[S] Our LinkedIn system generates 15+ qualified leads/week
+    using posts that take 10 minutes to write.
+```
+
+## BAB (Before → After → Bridge)
+
+Best for testimonials, case studies, transformation stories.
+
+```
+BEFORE: Describe the painful current state
+AFTER: Paint the desired future state
+BRIDGE: Your product/service is the bridge
+```
+
+**Example:**
+```
+[B] Sarah spent 4 hours/day on customer support emails.
+    Burnout was inevitable. Her team was drowning.
+[A] Now she handles 3x the volume in 1 hour.
+    Her team focuses on growth, not firefighting.
+[BR] The bridge? Our AI support assistant that learns
+     your voice and handles 80% of tickets automatically.
+```
+
+## 4Ps (Promise → Picture → Proof → Push)
+
+Long-form sales pages, webinar pitches.
+
+```
+PROMISE: Bold outcome claim
+PICTURE: Help them visualize having it
+PROOF: Evidence it works (testimonials, data)
+PUSH: Create urgency, clear CTA
+```
+
+## 4Us (Urgent + Unique + Useful + Ultra-specific)
+
+Headlines, subject lines, hooks.
+
+| U | Meaning | Example |
+|---|---------|---------|
+| Urgent | Time-sensitive | "24 hours left" |
+| Unique | Different from competition | "The only..." |
+| Useful | Clear benefit | "Save 10 hours/week" |
+| Ultra-specific | Precise details | "47% increase in 30 days" |
+
+**Example headline:**
+"[24 hours] The only cold email template that books [23 calls/month]"
+
+## FAB (Feature → Advantage → Benefit)
+
+Product descriptions, feature announcements.
+
+```
+FEATURE: What it is
+ADVANTAGE: What it does better
+BENEFIT: Why they care
+```
+
+**Example:**
+```
+[F] One-click export to PDF
+[A] No more screenshots or manual formatting
+[B] Share professional reports in seconds, not hours
+```
+
+## ACCA (Awareness → Comprehension → Conviction → Action)
+
+Educational content, complex products.
+
+```
+AWARENESS: Make them aware of the problem/opportunity
+COMPREHENSION: Help them understand the solution
+CONVICTION: Build belief with proof
+ACTION: Direct next step
+```
+
+## The 1-2-3-4 Formula
+
+Quick, punchy copy. Social posts, short emails.
+
+```
+1. What I've got for you
+2. What it will do for you
+3. Who am I? (credibility)
+4. What you need to do next
+```
+
+## Star-Chain-Hook
+
+Storytelling format for longer content.
+
+```
+STAR: Introduce the hero (reader or case study)
+CHAIN: Series of facts, benefits, reasons
+HOOK: Compelling CTA
+```
+
+## Formula Selection Guide
+
+| Situation | Best Formula |
+|-----------|--------------|
+| Cold audience | AIDA, ACCA |
+| Aware of problem | PAS |
+| Testimonial | BAB |
+| Product feature | FAB |
+| Headline | 4Us |
+| Sales page | 4Ps |
+| Quick hook | 1-2-3-4 |

package/templates/skills/copywriting/references/cta-patterns.md

@@ -0,0 +1,168 @@
+# CTA Patterns
+
+Button copy and calls-to-action that convert.
+
+## CTA Formulas
+
+### Action + Benefit
+```
+Start [benefit]ing
+Get [outcome]
+Unlock [benefit]
+Claim [offer]
+```
+
+**Examples:**
+- Start saving hours
+- Get instant access
+- Unlock your growth
+- Claim your free trial
+
+### First Person ("My")
+```
+Start my free trial
+Get my copy
+Build my [thing]
+Show me how
+Send me the guide
+```
+
+Outperforms generic "Get started" in many tests.
+
+### Yes + Benefit
+```
+Yes, I want [benefit]
+Yes, show me how
+Yes, sign me up
+Count me in
+I'm ready to [benefit]
+```
+
+### Imperative Verbs
+| Verb | Best For |
+|------|----------|
+| Get | Acquiring something |
+| Start | Beginning a journey |
+| Join | Community/membership |
+| Discover | Learning/content |
+| Build | Creation tools |
+| Try | Low commitment |
+| Book | Services/calls |
+| Download | Content offers |
+| Watch | Video content |
+
+## CTA by Funnel Stage
+
+### TOFU (Awareness)
+```
+Learn more
+Read the guide
+Watch the video
+Get the checklist
+See how it works
+```
+
+### MOFU (Consideration)
+```
+Start free trial
+Schedule a demo
+See pricing
+Compare plans
+Talk to sales
+```
+
+### BOFU (Decision)
+```
+Buy now
+Get started
+Subscribe
+Upgrade today
+Claim your spot
+```
+
+## Button Copy A/B Tests
+
+Tests often show these winners:
+
+| Lower Conversion | Higher Conversion |
+|------------------|-------------------|
+| Submit | Get My Free Guide |
+| Click here | Start My Free Trial |
+| Learn more | Show Me How |
+| Sign up | Yes, I Want This |
+| Download | Send Me the Checklist |
+
+## Adding Urgency
+
+```
+[CTA] - Limited spots
+[CTA] - Offer ends [date]
+[CTA] (only [N] left)
+[CTA] before [deadline]
+```
+
+## Adding Value
+
+```
+[CTA] — It's free
+[CTA] (no credit card)
+[CTA] — Cancel anytime
+[CTA] — 30-second setup
+[CTA] — Risk-free
+```
+
+## CTA Placement
+
+### Landing Page
+- Hero section (primary)
+- After benefits section
+- After testimonials
+- Final section (full-width)
+
+### Email
+- After value proposition
+- P.S. section
+- Keep above scroll if possible
+
+### Blog Post
+- After introduction
+- Mid-content (if natural)
+- End of post
+
+## Surrounding Copy
+
+### Above CTA
+```
+Ready to [benefit]?
+Join [number]+ [audience] who already [benefit]
+Stop [pain]. Start [benefit].
+```
+
+### Below CTA (Microcopy)
+```
+Free forever. No credit card required.
+30-day money-back guarantee
+Setup takes 2 minutes
+Cancel anytime. No questions asked.
+```
+
+## CTA Contrast
+
+For multiple CTAs on page:
+
+| Primary | Secondary |
+|---------|-----------|
+| Filled button | Ghost/outline button |
+| Start Free Trial | See Pricing |
+| Get Started | Watch Demo |
+| Buy Now | Learn More |
+
+## CTA Checklist
+
+- [ ] Action verb starts the CTA?
+- [ ] Benefit clear?
+- [ ] Matches page intent?
+- [ ] Contrasts visually?
+- [ ] One primary CTA per section?
+- [ ] Risk reducer nearby?
+- [ ] Mobile tap-friendly size?