thanh-kit 2.5.0 → 2.5.2

package/templates/skills/plan/references/validate-workflow.md

@@ -0,0 +1,65 @@
+# Validate Workflow
+
+Interview the user with critical questions to validate assumptions, confirm decisions, and surface potential issues in an implementation plan before coding begins.
+
+## Plan Resolution
+
+1. If `$ARGUMENTS` provided → Use that path
+2. Else check `## Plan Context` section → Use active plan path
+3. If no plan found → Ask user to specify path or run `/ck:plan --hard` first
+
+## Configuration
+
+Check `## Plan Context` section for validation settings:
+- `mode` - Controls auto/prompt/off behavior
+- `questions` - Range like `3-8` (min-max)
+
+## Workflow
+
+### Step 1: Read Plan Files
+- `plan.md` - Overview and phases list
+- `phase-*.md` - All phase files
+- Look for decision points, assumptions, risks, tradeoffs
+
+### Step 2: Extract Question Topics
+Load: `references/validate-question-framework.md`
+
+### Step 3: Generate Questions
+For each detected topic, formulate a concrete question with 2-4 options.
+Mark recommended option with "(Recommended)" suffix.
+
+### Step 4: Interview User
+Use `AskUserQuestion` tool.
+- Use question count from `## Plan Context` validation settings
+- Group related questions (max 4 per tool call)
+- Focus on: assumptions, risks, tradeoffs, architecture
+
+### Step 5: Document Answers
+Add or append `## Validation Log` section in `plan.md`.
+Load: `references/validate-question-framework.md` for recording format.
+
+### Step 6: Propagate Changes to Phases
+Auto-propagate validation decisions to affected phase files.
+Add marker: `<!-- Updated: Validation Session N - {change} -->`
+
+## Output
+- Number of questions asked
+- Key decisions confirmed
+- Phase propagation results
+- Recommendation: proceed or revise
+
+## Next Steps (MANDATORY)
+Remind user with absolute path:
+> **Best Practice:** Run `/clear` before implementing to start with fresh context.
+> Then run:
+> ```
+> /ck:cook --auto {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md
+> ```
+> **Why `--auto`?** Plan was already validated — safe to skip review gates.
+> **Why absolute path?** After `/clear`, the new session loses context.
+> Fresh context helps Claude focus solely on implementation without planning context pollution.
+
+## Important Notes
+- Only ask about genuine decision points
+- If plan is simple, fewer than min questions is okay
+- Prioritize questions that could change implementation significantly

package/templates/skills/plan/references/workflow-modes.md

@@ -0,0 +1,145 @@
+# Workflow Modes
+
+## Auto-Detection (Default: `--auto`)
+
+When no flag specified, analyze task and pick mode:
+
+| Signal | Mode | Rationale |
+|--------|------|-----------|
+| Simple task, clear scope, no unknowns | fast | Skip research overhead |
+| Complex task, unfamiliar domain, new tech | hard | Research needed |
+| 3+ independent features/layers/modules | parallel | Enable concurrent agents |
+| Ambiguous approach, multiple valid paths | two | Compare alternatives |
+
+Use `AskUserQuestion` if detection is uncertain.
+
+## Fast Mode (`--fast`)
+
+No research. Analyze → Plan → Hydrate Tasks.
+
+1. Read codebase docs (`codebase-summary.md`, `code-standards.md`, `system-architecture.md`)
+2. Use `planner` subagent to create plan
+3. Hydrate tasks (unless `--no-tasks`)
+4. **Context reminder:** `/ck:cook --auto {absolute-plan-path}/plan.md`
+
+**Why `--auto` cook flag?** Fast planning pairs with fast execution — skip review gates.
+
+## Hard Mode (`--hard`)
+
+Research → Scout → Plan → Red Team → Validate → Hydrate Tasks.
+
+1. Spawn max 2 `researcher` agents in parallel (different aspects, max 5 calls each)
+2. Read codebase docs; if stale/missing: run `/ck:scout` to search codebase
+3. Gather research + scout report filepaths → pass to `planner` subagent
+4. Post-plan red team review (see Red Team Review section below)
+5. Post-plan validation (see Validation section below)
+6. Hydrate tasks (unless `--no-tasks`)
+7. **Context reminder:** `/ck:cook {absolute-plan-path}/plan.md`
+
+**Why no cook flag?** Thorough planning needs interactive review gates.
+
+## Parallel Mode (`--parallel`)
+
+Research → Scout → Plan with file ownership → Red Team → Validate → Hydrate Tasks with dependency graph.
+
+1. Same as Hard mode steps 1-3
+2. Planner creates phases with:
+   - **Exclusive file ownership** per phase (no overlap)
+   - **Dependency matrix** (which phases run concurrently vs sequentially)
+   - **Conflict prevention** strategy
+3. plan.md includes: dependency graph, execution strategy, file ownership matrix
+4. Hydrate tasks: `addBlockedBy` for sequential deps, no blockers for parallel groups
+5. Post-plan red team review
+6. Post-plan validation
+7. **Context reminder:** `/ck:cook --parallel {absolute-plan-path}/plan.md`
+
+### Parallel Phase Requirements
+- Each phase self-contained, no runtime deps on other phases
+- Clear file boundaries — each file modified in ONE phase only
+- Group by: architectural layer, feature domain, or technology stack
+- Example: Phases 1-3 parallel (DB/API/UI), Phase 4 sequential (integration tests)
+
+## Two-Approach Mode (`--two`)
+
+Research → Scout → Plan 2 approaches → Compare → Hydrate Tasks.
+
+1. Same as Hard mode steps 1-3
+2. Planner creates 2 implementation approaches with:
+   - Clear trade-offs (pros/cons each)
+   - Recommended approach with rationale
+3. User selects approach
+4. Post-plan red team review on selected approach
+5. Post-plan validation
+6. Hydrate tasks for selected approach (unless `--no-tasks`)
+7. **Context reminder:** `/ck:cook {absolute-plan-path}/plan.md`
+
+## Task Hydration Per Mode
+
+| Mode | Task Granularity | Dependency Pattern |
+|------|------------------|--------------------|
+| fast | Phase-level only | Sequential chain |
+| hard | Phase + critical steps | Sequential + step deps |
+| parallel | Phase + steps + ownership | Parallel groups + sequential deps |
+| two | After user selects approach | Sequential chain |
+
+All modes: See `task-management.md` for TaskCreate patterns and metadata.
+
+## Post-Plan Red Team Review
+
+Adversarial review that spawns hostile reviewers to find flaws before validation.
+
+**Available in:** hard, parallel, two modes. **Skipped in:** fast mode.
+
+**Invocation:** Use the `Skill` tool to invoke `plan:red-team` with the plan directory path as argument:
+```
+Skill(skill: "ck:plan:red-team", args: "{plan-directory-path}")
+```
+
+**Sequence:** Red team runs BEFORE validation because:
+1. Red team may change the plan (added risks, removed sections, new constraints)
+2. Validation should confirm the FINAL plan, not a pre-review draft
+3. Validating first then red-teaming would invalidate validation answers
+
+## Post-Plan Validation
+
+Check `## Plan Context` → `Validation: mode=X, questions=MIN-MAX`:
+
+| Mode | Behavior |
+|------|----------|
+| `prompt` | Ask: "Validate this plan with interview?" → Yes (Recommended) / No |
+| `auto` | Use the `Skill` tool: `Skill(skill: "ck:plan:validate", args: "{plan-directory-path}")` |
+| `off` | Skip validation |
+
+**Invocation (when prompt mode, user says yes):** Use the `Skill` tool to invoke `plan:validate`:
+```
+Skill(skill: "ck:plan:validate", args: "{plan-directory-path}")
+```
+
+**Available in:** hard, parallel, two modes. **Skipped in:** fast mode.
+
+## Context Reminder (MANDATORY)
+
+After plan creation, MUST output with **actual absolute path**:
+
+| Mode | Cook Command |
+|------|-----------------------------|
+| fast | `/ck:cook --auto {path}/plan.md` |
+| hard | `/ck:cook {path}/plan.md` |
+| parallel | `/ck:cook --parallel {path}/plan.md` |
+| two | `/ck:cook {path}/plan.md` |
+
+> **Best Practice:** Run `/clear` before implementing to start fresh context.
+> Then run the cook command above.
+
+**Why absolute path?** After `/clear`, new session loses context.
+This reminder is **NON-NEGOTIABLE** — always output after presenting the plan.
+
+## Pre-Creation Check
+
+Check `## Plan Context` in injected context:
+- **"Plan: {path}"** → Ask "Continue with existing plan? [Y/n]"
+- **"Suggested: {path}"** → Branch hint only, ask if activate or create new
+- **"Plan: none"** → Create new using `Plan dir:` from `## Naming`
+
+After creating: `node .claude/scripts/set-active-plan.cjs {plan-dir}`
+Pass plan directory path to every subagent during the process.

package/templates/skills/plans-kanban/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: ck:plans-kanban
+description: View plans dashboard with progress tracking and timeline visualization. Use for kanban boards, plan status overview, phase progress, milestone tracking, project visibility.
+argument-hint: "[plans-dir]"
+---
+
+# plans-kanban
+
+Plans dashboard server with progress tracking and timeline visualization.
+
+## ⚠️ Installation Required
+
+**This skill requires npm dependencies.** Run one of the following:
+
+```bash
+# Option 1: Install via ClaudeKit CLI (recommended)
+ck init  # Runs install.sh which handles all skills
+
+# Option 2: Manual installation
+cd .claude/skills/plans-kanban
+npm install
+```
+
+**Dependencies:** `gray-matter`
+
+Without installation, you'll get **Error 500** when viewing plan details.
+
+## Purpose
+
+Visual dashboard for viewing plan directories with:
+- Progress tracking per plan
+- Timeline/Gantt visualization
+- Phase status indicators
+- Activity heatmap
+
+## Quick Start
+
+```bash
+# View plans dashboard
+node .claude/skills/plans-kanban/scripts/server.cjs \
+  --dir ./plans \
+  --open
+
+# Remote access (all interfaces)
+node .claude/skills/plans-kanban/scripts/server.cjs \
+  --dir ./plans \
+  --host 0.0.0.0 \
+  --open
+
+# Background mode
+node .claude/skills/plans-kanban/scripts/server.cjs \
+  --dir ./plans \
+  --background
+
+# Stop all running servers
+node .claude/skills/plans-kanban/scripts/server.cjs --stop
+```
+
+## Slash Command
+
+Use `/ck:kanban` for quick access:
+
+```bash
+/kanban plans/           # View plans dashboard
+/kanban --stop           # Stop kanban server
+```
+
+## Features
+
+### Dashboard View
+- Plan cards with progress bars
+- Phase status breakdown (completed, in-progress, pending)
+- Last modified timestamps
+- Issue and branch links
+- Priority indicators
+
+### Timeline Visualization
+- Gantt-style timeline of plans
+- Duration tracking
+- Activity heatmap
+
+### Design
+- Glassmorphism UI with dark mode
+- Responsive grid layout
+- Warm accent colors
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--dir <path>` | Plans directory | - |
+| `--port <number>` | Server port | 3500 |
+| `--host <addr>` | Host to bind (`0.0.0.0` for remote) | localhost |
+| `--open` | Auto-open browser | false |
+| `--background` | Run in background | false |
+| `--stop` | Stop all servers | - |
+
+## Architecture
+
+```
+scripts/
+├── server.cjs               # Main entry point
+└── lib/
+    ├── port-finder.cjs      # Port allocation (3500-3550)
+    ├── process-mgr.cjs      # PID management
+    ├── http-server.cjs      # HTTP routing
+    ├── plan-parser.cjs      # Plan.md parsing
+    ├── plan-scanner.cjs     # Directory scanning
+    ├── plan-metadata-extractor.cjs  # Rich metadata
+    └── dashboard-renderer.cjs       # HTML generation
+
+assets/
+├── dashboard-template.html  # Dashboard HTML template
+├── dashboard.css           # Styles
+└── dashboard.js            # Client interactivity
+```
+
+## HTTP Routes
+
+| Route | Description |
+|-------|-------------|
+| `/` or `/ck:kanban` | Dashboard view |
+| `/ck:kanban?dir=<path>` | Dashboard for specific directory |
+| `/api/plans` | JSON API for plans data |
+| `/api/plans?dir=<path>` | JSON API for specific directory |
+| `/assets/*` | Static assets |
+| `/file/*` | Local file serving |
+
+## Remote Access
+
+When using `--host 0.0.0.0`, the server auto-detects your local network IP:
+
+```json
+{
+  "success": true,
+  "url": "http://localhost:3500/kanban?dir=...",
+  "networkUrl": "http://192.168.2.75:3500/kanban?dir=...",
+  "port": 3500
+}
+```
+
+Use `networkUrl` to access from other devices on the same network.
+
+## Plan Structure
+
+The dashboard scans for directories containing `plan.md` files:
+
+```
+plans/
+├── 251215-feature-a/
+│   ├── plan.md              # Required - parsed for phases
+│   ├── phase-01-setup.md
+│   └── phase-02-impl.md
+├── 251214-feature-b/
+│   └── plan.md
+└── templates/               # Excluded by default
+```
+
+## Troubleshooting
+
+**Port in use**: Server auto-increments from 3500-3550
+
+**No plans found**: Ensure directories contain `plan.md` files
+
+**Remote access denied**: Use `--host 0.0.0.0` to bind all interfaces
+
+**PID files**: Located at `/tmp/plans-kanban-*.pid`

package/templates/skills/plans-kanban/assets/dashboard-template.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Plans Dashboard</title>
+  <link rel="icon" type="image/png" href="/assets/favicon.png">
+  <!-- Apply stored theme BEFORE CSS loads to prevent FOUC -->
+  <script>
+    (function(){
+      var h=document.documentElement;
+      var t=localStorage.getItem('theme');
+      if(t)h.dataset.theme=t;
+      else if(window.matchMedia('(prefers-color-scheme:dark)').matches)h.dataset.theme='dark';
+    })();
+  </script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Libre+Baskerville:wght@400;700&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/assets/novel-theme.css">
+  <link rel="stylesheet" href="/assets/dashboard.css">
+</head>
+<body class="dashboard-view {{has-plans}}">
+  <a href="#main-content" class="skip-link">Skip to main content</a>
+
+  <header class="dashboard-header">
+    <div class="header-left">
+      <h1>Plans</h1>
+      <div class="header-stats">
+        <span class="header-stat"><strong>{{stat-total}}</strong> total</span>
+        <span class="header-stat-divider"></span>
+        <span class="header-stat"><strong>{{stat-completed}}</strong> done</span>
+        <span class="header-stat-divider"></span>
+        <span class="header-stat"><strong>{{stat-in-progress}}</strong> active</span>
+      </div>
+    </div>
+
+    <div class="header-controls">
+      <div class="search-box">
+        <svg class="search-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <circle cx="11" cy="11" r="8"/><path d="m21 21-4.35-4.35"/>
+        </svg>
+        <input type="search" id="plan-search" placeholder="Search plans..." aria-label="Search plans">
+      </div>
+
+      <select id="sort-select" aria-label="Sort plans by">
+        <option value="date-desc">Newest First</option>
+        <option value="date-asc">Oldest First</option>
+        <option value="name-asc">Name A-Z</option>
+        <option value="name-desc">Name Z-A</option>
+        <option value="progress-desc">Most Progress</option>
+        <option value="progress-asc">Least Progress</option>
+      </select>
+
+      <div class="filter-pills" role="group" aria-label="Filter by status">
+        <button class="filter-pill active" data-filter="all" aria-pressed="true">All</button>
+        <button class="filter-pill" data-filter="completed" aria-pressed="false">Done</button>
+        <button class="filter-pill" data-filter="in-progress" aria-pressed="false">Active</button>
+        <button class="filter-pill" data-filter="pending" aria-pressed="false">Pending</button>
+      </div>
+
+      <div role="status" aria-live="polite" class="result-count">
+        <strong>{{plan-count}}</strong> plans
+      </div>
+
+      <div class="view-toggle" role="group" aria-label="View mode">
+        <button class="view-toggle-btn active" data-view="kanban" aria-pressed="true" title="Kanban view">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <rect x="3" y="3" width="5" height="18" rx="1"/><rect x="10" y="3" width="5" height="12" rx="1"/><rect x="17" y="3" width="5" height="8" rx="1"/>
+          </svg>
+        </button>
+        <button class="view-toggle-btn" data-view="grid" aria-pressed="false" title="Grid view">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/>
+          </svg>
+        </button>
+      </div>
+
+      <button id="theme-toggle" class="icon-btn" aria-label="Toggle theme">
+        <svg class="sun-icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <circle cx="12" cy="12" r="5"/><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
+        </svg>
+        <svg class="moon-icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+        </svg>
+      </button>
+    </div>
+  </header>
+
+  <main id="main-content" role="main" aria-label="Plans Dashboard">
+    {{timeline-section}}
+
+    <!-- Kanban Board View -->
+    <div class="kanban-board" aria-label="Kanban board">
+      {{kanban-columns}}
+    </div>
+
+    <div class="loading-skeleton" aria-hidden="true">
+      <div class="skeleton-card"></div>
+      <div class="skeleton-card"></div>
+      <div class="skeleton-card"></div>
+      <div class="skeleton-card"></div>
+      <div class="skeleton-card"></div>
+      <div class="skeleton-card"></div>
+    </div>
+
+    <section class="plans-grid" aria-label="Plans list">
+      {{plans-grid}}
+    </section>
+
+    {{empty-state}}
+  </main>
+
+  <div id="sr-announce" role="status" aria-live="polite" aria-atomic="true" class="visually-hidden"></div>
+
+  <script>window.__plans = {{plans-json}};</script>
+  <script src="/assets/dashboard.js"></script>
+</body>
+</html>