npm - @macpaw/cctk - Versions diffs - 1.0.0-beta.1 - Mend

@macpaw/cctk 1.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (415) hide show

package/templates/claude/skills/mermaidjs-v11/references/integration.md ADDED Viewed

@@ -0,0 +1,310 @@
+# Mermaid.js Integration Patterns
+JavaScript API integration, HTML embedding, and platform-specific usage.
+## HTML/Browser Integration
+**Basic CDN Setup:**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js"></script>
+</head>
+<body>
+  <pre class="mermaid">
+    flowchart TD
+      A[Client] --> B[Load Balancer]
+      B --> C[Server 1]
+      B --> D[Server 2]
+  </pre>
+  <script>
+    mermaid.initialize({ startOnLoad: true });
+  </script>
+</body>
+</html>
+```
+**ES Module (Modern):**
+```html
+<script type="module">
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.esm.min.mjs';
+  mermaid.initialize({ startOnLoad: true });
+</script>
+```
+## NPM/Node.js Integration
+**Installation:**
+```bash
+npm install mermaid
+# or
+yarn add mermaid
+```
+**Import and Initialize:**
+```javascript
+import mermaid from 'mermaid';
+mermaid.initialize({
+  startOnLoad: true,
+  theme: 'dark',
+  securityLevel: 'strict'
+});
+```
+**Manual Rendering:**
+```javascript
+import mermaid from 'mermaid';
+const graphDefinition = `
+  graph TD
+    A[Start] --> B[Process]
+    B --> C[End]
+`;
+const { svg } = await mermaid.render('graphId', graphDefinition);
+document.getElementById('container').innerHTML = svg;
+```
+## React Integration
+**Component Wrapper:**
+```jsx
+import { useEffect, useRef } from 'react';
+import mermaid from 'mermaid';
+function MermaidDiagram({ chart }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    mermaid.initialize({ startOnLoad: false });
+    if (ref.current) {
+      mermaid.render('diagram', chart).then(({ svg }) => {
+        ref.current.innerHTML = svg;
+      });
+    }
+  }, [chart]);
+  return <div ref={ref} />;
+}
+// Usage
+<MermaidDiagram chart="graph TD\nA-->B" />
+```
+**Next.js (App Router):**
+```jsx
+'use client';
+import dynamic from 'next/dynamic';
+const Mermaid = dynamic(() => import('./MermaidDiagram'), {
+  ssr: false
+});
+export default function Page() {
+  return <Mermaid chart="flowchart TD\nA-->B" />;
+}
+```
+## Vue Integration
+**Component:**
+```vue
+<template>
+  <div ref="container"></div>
+</template>
+<script setup>
+import { ref, onMounted, watch } from 'vue';
+import mermaid from 'mermaid';
+const props = defineProps(['chart']);
+const container = ref(null);
+onMounted(() => {
+  mermaid.initialize({ startOnLoad: false });
+  renderDiagram();
+});
+watch(() => props.chart, renderDiagram);
+async function renderDiagram() {
+  const { svg } = await mermaid.render('diagram', props.chart);
+  container.value.innerHTML = svg;
+}
+</script>
+```
+## Markdown Integration
+**GitHub/GitLab:**
+````markdown
+```mermaid
+graph TD
+  A[Start] --> B[End]
+```
+````
+**MDX (Next.js/Gatsby):**
+```mdx
+import Mermaid from './Mermaid';
+# Architecture
+<Mermaid chart={`
+  flowchart LR
+    Client --> API
+    API --> Database
+`} />
+```
+## API Reference
+**mermaid.initialize(config)**
+Configure global settings.
+```javascript
+mermaid.initialize({
+  startOnLoad: true,
+  theme: 'dark',
+  logLevel: 3,
+  securityLevel: 'strict',
+  fontFamily: 'Arial'
+});
+```
+**mermaid.render(id, graphDefinition, config)**
+Programmatically render diagram.
+```javascript
+const { svg, bindFunctions } = await mermaid.render(
+  'uniqueId',
+  'graph TD\nA-->B',
+  { theme: 'forest' }
+);
+```
+**mermaid.parse(text)**
+Validate syntax without rendering.
+```javascript
+try {
+  await mermaid.parse('graph TD\nA-->B');
+  console.log('Valid');
+} catch(e) {
+  console.error('Invalid:', e);
+}
+```
+**mermaid.run(config)**
+Render all diagrams in page.
+```javascript
+await mermaid.run({
+  querySelector: '.mermaid',
+  suppressErrors: false
+});
+```
+## Event Handling
+**Click Events:**
+```javascript
+const graphDefinition = `
+  flowchart TD
+    A[Click me] --> B
+    click A callback "Tooltip text"
+`;
+window.callback = function() {
+  alert('Node clicked!');
+};
+await mermaid.render('graph', graphDefinition);
+```
+**Interactive URLs:**
+```
+flowchart TD
+  A[GitHub] --> B[Docs]
+  click A "https://github.com"
+  click B "https://mermaid.js.org" "Open docs"
+```
+## Advanced Patterns
+**Dynamic Theme Switching:**
+```javascript
+function updateTheme(isDark) {
+  mermaid.initialize({
+    theme: isDark ? 'dark' : 'default',
+    startOnLoad: false
+  });
+  // Re-render all diagrams
+  document.querySelectorAll('.mermaid').forEach(async (el) => {
+    const code = el.textContent;
+    const { svg } = await mermaid.render('id', code);
+    el.innerHTML = svg;
+  });
+}
+```
+**Lazy Loading:**
+```javascript
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(async (entry) => {
+    if (entry.isIntersecting) {
+      const code = entry.target.textContent;
+      const { svg } = await mermaid.render('id', code);
+      entry.target.innerHTML = svg;
+      observer.unobserve(entry.target);
+    }
+  });
+});
+document.querySelectorAll('.mermaid').forEach(el => observer.observe(el));
+```
+**Server-Side Rendering (SSR):**
+```javascript
+import { chromium } from 'playwright';
+async function renderServerSide(code) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.setContent(`
+    <script src="mermaid.min.js"></script>
+    <div class="mermaid">${code}</div>
+    <script>mermaid.initialize({ startOnLoad: true });</script>
+  `);
+  const svg = await page.locator('.mermaid svg').innerHTML();
+  await browser.close();
+  return svg;
+}
+```
+## Platform-Specific
+**Jupyter/Python:**
+Use mermaid.ink API:
+```python
+from IPython.display import Image
+diagram = "graph TD\nA-->B"
+url = f"https://mermaid.ink/svg/{diagram}"
+Image(url=url)
+```
+**VS Code:**
+Install "Markdown Preview Mermaid Support" extension.
+**Obsidian:**
+Native support in code blocks:
+````markdown
+```mermaid
+graph TD
+  A --> B
+```
+````
+**PowerPoint/Word:**
+Use mermaid.live editor → Export → Insert image.

package/templates/claude/skills/planning/SKILL.md ADDED Viewed

@@ -0,0 +1,115 @@
+---
+name: planning
+description: Use when you need to plan technical solutions that are scalable, secure, and maintainable.
+license: MIT
+---
+# Planning
+Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
+## When to Use
+Use this skill when:
+- Planning new feature implementations
+- Architecting system designs
+- Evaluating technical approaches
+- Creating implementation roadmaps
+- Breaking down complex requirements
+- Assessing technical trade-offs
+## Core Responsibilities & Rules
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+### 1. Research & Analysis
+Load: `references/research-phase.md`
+**Skip if:** Provided with researcher reports
+### 2. Codebase Understanding
+Load: `references/codebase-understanding.md`
+**Skip if:** Provided with scout reports
+### 3. Solution Design
+Load: `references/solution-design.md`
+### 4. Plan Creation & Organization
+Load: `references/plan-organization.md`
+### 5. Task Breakdown & Output Standards
+Load: `references/output-standards.md`
+## Workflow Process
+1. **Initial Analysis** → Read codebase docs, understand context
+2. **Research Phase** → Spawn researchers, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+## Output Requirements
+- DO NOT implement code - only create plans
+- Respond with plan file path and summary
+- Ensure self-contained plans with necessary context
+- Include code snippets/pseudocode when clarifying
+- Provide multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
+**Plan Directory Structure**
+```
+plans/
+└── {date}-plan-name/
+    ├── research/
+    │   ├── researcher-XX-report.md
+    │   └── ...
+    ├── reports/
+    │   ├── XX-report.md
+    │   └── ...
+    ├── scout/
+    │   ├── scout-XX-report.md
+    │   └── ...
+    ├── plan.md
+    ├── phase-XX-phase-name-here.md
+    └── ...
+```
+## Active Plan State
+Prevents version proliferation by tracking current working plan via session state.
+### Active vs Suggested Plans
+Check the `## Plan Context` section injected by hooks:
+- **"Plan: {path}"** = Active plan, explicitly set via `set-active-plan.cjs` - use for reports
+- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: none"** = No active plan
+### Rules
+1. **If "Plan:" shows a path**: Ask "Continue with existing plan? [Y/n]"
+2. **If "Suggested:" shows a path**: Inform user, ask if they want to activate or create new
+3. **If "Plan: none"**: Create new plan using naming from `## Naming` section
+4. **Update on create**: Run `node .claude/scripts/set-active-plan.cjs {plan-dir}`
+### Report Output Location
+All agents writing reports MUST:
+1. Check `## Naming` section injected by hooks for the computed naming pattern
+2. Active plans use plan-specific reports path
+3. Suggested plans use default reports path (not plan folder)
+**Important:** Suggested plans do NOT get plan-specific reports - this prevents pollution of old plan folders.
+## Quality Standards
+- Be thorough and specific
+- Consider long-term maintainability
+- Research thoroughly when uncertain
+- Address security and performance concerns
+- Make plans detailed enough for junior developers
+- Validate against existing codebase patterns
+**Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.

package/templates/claude/skills/planning/references/codebase-understanding.md ADDED Viewed

@@ -0,0 +1,62 @@
+# Codebase Understanding Phase
+**When to skip:** If provided with scout reports, skip this phase.
+## Core Activities
+### Parallel Scout Agents
+- Use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+- Each scout locates files needed for specific task aspects
+- Wait for all scout agents to report back before analysis
+- Efficient for finding relevant code across large codebases
+### Essential Documentation Review
+ALWAYS read these files first:
+1. **`./docs/development-rules.md`** (IMPORTANT)
+   - File Name Conventions
+   - File Size Management
+   - Development rules and best practices
+   - Code quality standards
+   - Security guidelines
+2. **`./docs/codebase-summary.md`**
+   - Project structure and current status
+   - High-level architecture overview
+   - Component relationships
+3. **`./docs/code-standards.md`**
+   - Coding conventions and standards
+   - Language-specific patterns
+   - Naming conventions
+4. **`./docs/design-guidelines.md`** (if exists)
+   - Design system guidelines
+   - Branding and UI/UX conventions
+   - Component library usage
+### Environment Analysis
+- Review development environment setup
+- Analyze dotenv files and configuration
+- Identify required dependencies
+- Understand build and deployment processes
+### Pattern Recognition
+- Study existing patterns in codebase
+- Identify conventions and architectural decisions
+- Note consistency in implementation approaches
+- Understand error handling patterns
+### Integration Planning
+- Identify how new features integrate with existing architecture
+- Map dependencies between components
+- Understand data flow and state management
+- Consider backward compatibility
+## Best Practices
+- Start with documentation before diving into code
+- Use scouts for targeted file discovery
+- Document patterns found for consistency
+- Note any inconsistencies or technical debt
+- Consider impact on existing features

package/templates/claude/skills/planning/references/output-standards.md ADDED Viewed

@@ -0,0 +1,127 @@
+# Output Standards & Quality
+## Plan File Format
+### YAML Frontmatter (Required for plan.md)
+All `plan.md` files MUST include YAML frontmatter at the top:
+```yaml
+---
+title: "{Brief plan title}"
+description: "{One-sentence summary for card preview}"
+status: pending  # pending | in-progress | completed | cancelled
+priority: P2     # P1 (High) | P2 (Medium) | P3 (Low)
+effort: 4h       # Estimated total effort
+issue: 74        # GitHub issue number (if applicable)
+branch: kai/feat/feature-name
+tags: [frontend, api]  # Category tags
+created: 2025-12-16
+---
+```
+### Auto-Population Rules
+When creating plans, auto-populate these fields:
+- **title**: Extract from task description
+- **description**: First sentence of Overview section
+- **status**: Always `pending` for new plans
+- **priority**: From user request or default `P2`
+- **effort**: Sum of phase estimates
+- **issue**: Parse from branch name or context
+- **branch**: Current git branch (`git branch --show-current`)
+- **tags**: Infer from task keywords (e.g., frontend, backend, api, auth)
+- **created**: Today's date in YYYY-MM-DD format
+### Tag Vocabulary (Recommended)
+Use these predefined tags for consistency:
+- **Type**: `feature`, `bugfix`, `refactor`, `docs`, `infra`
+- **Domain**: `frontend`, `backend`, `database`, `api`, `auth`
+- **Scope**: `critical`, `tech-debt`, `experimental`
+## Task Breakdown
+- Transform complex requirements into manageable, actionable tasks
+- Each task independently executable with clear dependencies
+- Prioritize by dependencies, risk, business value
+- Eliminate ambiguity in instructions
+- Include specific file paths for all modifications
+- Provide clear acceptance criteria per task
+### File Management
+List affected files with:
+- Full paths (not relative)
+- Action type (modify/create/delete)
+- Brief change description
+- Dependencies on other changes
+- Fully respect the `./docs/development-rules.md` file.
+## Workflow Process
+1. **Initial Analysis** → Read docs, understand context
+2. **Research Phase** → Spawn researchers in parallel, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan in Markdown
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+## Output Requirements
+### What Planners Do
+- Create plans ONLY (no implementation)
+- Provide plan file path and summary
+- Self-contained plans with necessary context
+- Code snippets/pseudocode when clarifying
+- Multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
+### Writing Style
+**IMPORTANT:** Sacrifice grammar for concision
+- Focus clarity over eloquence
+- Use bullets and lists
+- Short sentences
+- Remove unnecessary words
+- Prioritize actionable info
+### Unresolved Questions
+**IMPORTANT:** List unresolved questions at end
+- Questions needing clarification
+- Technical decisions requiring input
+- Unknowns impacting implementation
+- Trade-offs requiring business decisions
+## Quality Standards
+### Thoroughness
+- Thorough and specific in research/planning
+- Consider edge cases, failure modes
+- Think through entire user journey
+- Document all assumptions
+### Maintainability
+- Consider long-term maintainability
+- Design for future modifications
+- Document decision rationale
+- Avoid over-engineering
+- Fully respect the `./docs/development-rules.md` file.
+### Research Depth
+- When uncertain, research more
+- Multiple options with clear trade-offs
+- Validate against best practices
+- Consider industry standards
+### Security & Performance
+- Address all security concerns
+- Identify performance implications
+- Plan for scalability
+- Consider resource constraints
+### Implementability
+- Detailed enough for junior developers
+- Validate against existing patterns
+- Ensure codebase standards consistency
+- Provide clear examples
+**Remember:** Plan quality determines implementation success. Be comprehensive, consider all solution aspects.