@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/planning/references/plan-organization.md

@@ -0,0 +1,150 @@
+# Plan Creation & Organization
+
+## Directory Structure
+
+### Plan Location
+Use `Plan dir:` from `## Naming` section injected by hooks. This is the full computed path.
+
+**Example:** `plans/251101-1505-authentication/` or `ai_docs/feature/MRR-1453/`
+
+### File Organization
+
+```
+{plan-dir}/                                    # From `Plan dir:` in ## Naming
+├── research/
+│   ├── researcher-XX-report.md
+│   └── ...
+├── reports/
+│   ├── scout-report.md
+│   ├── researcher-report.md
+│   └── ...
+├── plan.md                                    # Overview access point
+├── phase-01-setup-environment.md              # Setup environment
+├── phase-02-implement-database.md             # Database models
+├── phase-03-implement-api-endpoints.md        # API endpoints
+├── phase-04-implement-ui-components.md        # UI components
+├── phase-05-implement-authentication.md       # Auth & authorization
+├── phase-06-implement-profile.md              # Profile page
+└── phase-07-write-tests.md                    # Tests
+```
+
+### Active Plan State Tracking
+
+Check the `## Plan Context` section injected by hooks:
+- **"Plan: {path}"** = Active plan - use for reports
+- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: none"** = No active plan
+
+**Pre-Creation Check:**
+1. If "Plan:" shows a path → ask "Continue with existing plan? [Y/n]"
+2. If "Suggested:" shows a path → inform user (hint only, do NOT auto-use)
+3. If "Plan: none" → create new plan using naming from `## Naming` section
+
+**After Creating Plan:**
+```bash
+# Update session state so subagents get the new plan context:
+node .claude/scripts/set-active-plan.cjs {plan-dir}
+```
+
+**Report Output Rules:**
+1. Use `Report:` and `Plan dir:` from `## Naming` section
+2. Active plans use plan-specific reports path
+3. Suggested plans use default reports path to prevent old plan pollution
+
+## File Structure
+
+### Overview Plan (plan.md)
+
+**IMPORTANT:** All plan.md files MUST include YAML frontmatter. See `output-standards.md` for schema.
+
+**Example plan.md structure:**
+```markdown
+---
+title: "Feature Implementation Plan"
+description: "Add user authentication with OAuth2 support"
+status: pending
+priority: P1
+effort: 8h
+issue: 123
+branch: kai/feat/oauth-auth
+tags: [auth, backend, security]
+created: 2025-12-16
+---
+
+# Feature Implementation Plan
+
+## Overview
+
+Brief description of what this plan accomplishes.
+
+## Phases
+
+| # | Phase | Status | Effort | Link |
+|---|-------|--------|--------|------|
+| 1 | Setup | Pending | 2h | [phase-01](./phase-01-setup.md) |
+| 2 | Implementation | Pending | 4h | [phase-02](./phase-02-impl.md) |
+| 3 | Testing | Pending | 2h | [phase-03](./phase-03-test.md) |
+
+## Dependencies
+
+- List key dependencies here
+```
+
+**Guidelines:**
+- Keep generic and under 80 lines
+- List each phase with status/progress
+- Link to detailed phase files
+- Key dependencies
+
+### Phase Files (phase-XX-name.md)
+Fully respect the `./docs/development-rules.md` file.
+Each phase file should contain:
+
+**Context Links**
+- Links to related reports, files, documentation
+
+**Overview**
+- Priority
+- Current status
+- Brief description
+
+**Key Insights**
+- Important findings from research
+- Critical considerations
+
+**Requirements**
+- Functional requirements
+- Non-functional requirements
+
+**Architecture**
+- System design
+- Component interactions
+- Data flow
+
+**Related Code Files**
+- List of files to modify
+- List of files to create
+- List of files to delete
+
+**Implementation Steps**
+- Detailed, numbered steps
+- Specific instructions
+
+**Todo List**
+- Checkbox list for tracking
+
+**Success Criteria**
+- Definition of done
+- Validation methods
+
+**Risk Assessment**
+- Potential issues
+- Mitigation strategies
+
+**Security Considerations**
+- Auth/authorization
+- Data protection
+
+**Next Steps**
+- Dependencies
+- Follow-up tasks

package/templates/claude/skills/planning/references/research-phase.md

@@ -0,0 +1,49 @@
+# Research & Analysis Phase
+
+**When to skip:** If provided with researcher reports, skip this phase.
+
+## Core Activities
+
+### Parallel Researcher Agents
+- Spawn multiple `researcher` agents in parallel to investigate different approaches
+- Wait for all researcher agents to report back before proceeding
+- Each researcher investigates a specific aspect or approach
+
+### Sequential Thinking
+- Use `sequential-thinking` skill for dynamic and reflective problem-solving
+- Structured thinking process for complex analysis
+- Enables multi-step reasoning with revision capability
+
+### Documentation Research
+- Use `docs-seeker` skill to read and understand documentation
+- Research plugins, packages, and frameworks
+- Find latest technical documentation using llms.txt standard
+
+### GitHub Analysis
+- Use `gh` command to read and analyze:
+  - GitHub Actions logs
+  - Pull requests
+  - Issues and discussions
+- Extract relevant technical context from GitHub resources
+
+### Remote Repository Analysis
+When given GitHub repository URL, generate fresh codebase summary:
+```bash
+# usage: 
+repomix --remote <github-repo-url>
+# example: 
+repomix --remote https://github.com/mrgoonie/human-mcp
+```
+
+### Debugger Delegation
+- Delegate to `debugger` agent for root cause analysis
+- Use when investigating complex issues or bugs
+- Debugger agent specializes in diagnostic tasks
+
+## Best Practices
+
+- Research breadth before depth
+- Document findings for synthesis phase
+- Identify multiple approaches for comparison
+- Consider edge cases during research
+- Note security implications early

package/templates/claude/skills/planning/references/solution-design.md

@@ -0,0 +1,63 @@
+# Solution Design
+
+## Core Principles
+
+Follow these fundamental principles:
+- **YAGNI** (You Aren't Gonna Need It) - Don't add functionality until necessary
+- **KISS** (Keep It Simple, Stupid) - Prefer simple solutions over complex ones
+- **DRY** (Don't Repeat Yourself) - Avoid code duplication
+
+## Design Activities
+
+### Technical Trade-off Analysis
+- Evaluate multiple approaches for each requirement
+- Compare pros and cons of different solutions
+- Consider short-term vs long-term implications
+- Balance complexity with maintainability
+- Assess development effort vs benefit
+- Recommend optimal solution based on current best practices
+
+### Security Assessment
+- Identify potential vulnerabilities during design phase
+- Consider authentication and authorization requirements
+- Assess data protection needs
+- Evaluate input validation requirements
+- Plan for secure configuration management
+- Address OWASP Top 10 concerns
+- Consider API security (rate limiting, CORS, etc.)
+
+### Performance & Scalability
+- Identify potential bottlenecks early
+- Consider database query optimization needs
+- Plan for caching strategies
+- Assess resource usage (memory, CPU, network)
+- Design for horizontal/vertical scaling
+- Plan for load distribution
+- Consider asynchronous processing where appropriate
+
+### Edge Cases & Failure Modes
+- Think through error scenarios
+- Plan for network failures
+- Consider partial failure handling
+- Design retry and fallback mechanisms
+- Plan for data consistency
+- Consider race conditions
+- Design for graceful degradation
+
+### Architecture Design
+- Create scalable system architectures
+- Design for maintainability
+- Plan component interactions
+- Design data flow
+- Consider microservices vs monolith trade-offs
+- Plan API contracts
+- Design state management
+
+## Best Practices
+
+- Document design decisions and rationale
+- Consider both technical and business requirements
+- Think through the entire user journey
+- Plan for monitoring and observability
+- Design with testing in mind
+- Consider deployment and rollback strategies

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

@@ -0,0 +1,157 @@
+# plans-kanban
+
+Plans dashboard server with progress tracking and timeline visualization.
+
+## ⚠️ Installation Required
+
+**This skill requires npm dependencies.** Run one of the following:
+
+```bash
+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 `/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 `/kanban` | Dashboard view |
+| `/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/claude/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>