@lovehlmmm/primekit 1.0.0

package/skills/plans-kanban/scripts/open-dashboard.cjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+const { spawn, spawnSync } = require('child_process');
+const http = require('http');
+const os = require('os');
+
+const DEFAULT_PORT = 8766;
+const PROBE_TIMEOUT_MS = 1000;
+const START_TIMEOUT_MS = 10000;
+
+function parseArgs(argv) {
+  const args = { stop: false, open: true };
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--stop') {
+      args.stop = true;
+    } else if (arg === '--no-open') {
+      args.open = false;
+    } else if (arg === '--open') {
+      args.open = true;
+    } else if (arg === '--dir' || arg === '--plans' || arg === '--port' || arg === '--host') {
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : '';
+      warn(`ignoring deprecated ${arg}${value ? ` ${value}` : ''}; AgentKit dashboard owns plan scope`);
+    } else if (arg === '--background' || arg === '--foreground') {
+      warn(`ignoring deprecated ${arg}; dashboard process is managed by ak config`);
+    } else if (!arg.startsWith('--')) {
+      warn(`ignoring deprecated positional path ${arg}; opening /plans`);
+    } else {
+      warn(`unknown flag ${arg}; opening /plans`);
+    }
+  }
+  return args;
+}
+
+function warn(message) {
+  console.error(`[plans-kanban] ${message}`);
+}
+
+function akBin() {
+  return process.env.AGENTKIT_CLI || 'ak';
+}
+
+function runAK(args) {
+  return spawnSync(akBin(), args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+}
+
+function akAvailable() {
+  return !runAK(['--version']).error;
+}
+
+function parseJSONEnvelope(stdout) {
+  const lines = String(stdout || '').trim().split(/\r?\n/).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      return JSON.parse(lines[i]);
+    } catch {
+      // Try the next line; human output can precede JSON in dev builds.
+    }
+  }
+  return null;
+}
+
+function statusURL() {
+  const result = runAK(['config', 'status', '--json']);
+  if (result.error) {
+    return null;
+  }
+  const envelope = parseJSONEnvelope(result.stdout);
+  const data = envelope && envelope.data ? envelope.data : envelope;
+  if (!data || !data.running || !data.url) {
+    return null;
+  }
+  return String(data.url).replace(/\/$/, '');
+}
+
+function startDashboard() {
+  const child = spawn(akBin(), [
+    'config',
+    'start',
+    '--port',
+    String(DEFAULT_PORT),
+    '--no-open',
+    '--no-interactive'
+  ], {
+    detached: true,
+    stdio: 'ignore'
+  });
+  child.unref();
+}
+
+function requestJSON(baseURL, path) {
+  return new Promise((resolve) => {
+    const req = http.get(`${baseURL}${path}`, { timeout: PROBE_TIMEOUT_MS }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        body += chunk;
+      });
+      res.on('end', () => {
+        let json = null;
+        try {
+          json = body ? JSON.parse(body) : null;
+        } catch {
+          json = null;
+        }
+        resolve({ statusCode: res.statusCode || 0, json });
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ statusCode: 0, json: null });
+    });
+    req.on('error', () => resolve({ statusCode: 0, json: null }));
+  });
+}
+
+async function supportsPlans(baseURL) {
+  const health = await requestJSON(baseURL, '/api/health');
+  const features = health.json && Array.isArray(health.json.features) ? health.json.features : [];
+  if (features.includes('plans-dashboard')) {
+    return true;
+  }
+
+  const plans = await requestJSON(baseURL, '/api/plans');
+  return plans.statusCode >= 200 && plans.statusCode < 300;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForDashboard() {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const fromStatus = statusURL();
+    const candidates = fromStatus
+      ? [fromStatus]
+      : [`http://127.0.0.1:${DEFAULT_PORT}`, `http://localhost:${DEFAULT_PORT}`];
+
+    for (const baseURL of candidates) {
+      if (await supportsPlans(baseURL)) {
+        return baseURL;
+      }
+    }
+    await sleep(250);
+  }
+  return null;
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let command;
+  let args;
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    command = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+  child.unref();
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.stop) {
+    const result = runAK(['config', 'stop']);
+    if (result.error) {
+      console.error(`[plans-kanban] ak not found; install AgentKit CLI or set AGENTKIT_CLI`);
+      process.exit(1);
+    }
+    process.stdout.write(result.stdout || '');
+    process.stderr.write(result.stderr || '');
+    process.exit(result.status || 0);
+  }
+
+  let baseURL = await waitForDashboard();
+  if (!baseURL) {
+    if (!akAvailable()) {
+      console.error('[plans-kanban] ak not found; install AgentKit CLI or set AGENTKIT_CLI');
+      process.exit(1);
+    }
+    startDashboard();
+    baseURL = await waitForDashboard();
+  }
+
+  if (!baseURL) {
+    console.error('[plans-kanban] dashboard did not expose /api/plans. Upgrade AgentKit CLI or run `ak config start --no-open` manually.');
+    process.exit(1);
+  }
+
+  const url = `${baseURL}/plans`;
+  if (args.open) {
+    try {
+      openBrowser(url);
+    } catch (err) {
+      warn(`browser open failed: ${err.message}`);
+    }
+  }
+
+  console.log(JSON.stringify({
+    success: true,
+    url,
+    opened: args.open,
+    platform: os.platform()
+  }));
+}
+
+main().catch((err) => {
+  console.error(`[plans-kanban] ${err && err.message ? err.message : err}`);
+  process.exit(1);
+});

package/skills/predict/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: pk:predict
+description: "5 expert personas debate proposed changes before implementation. Catches architectural, security, performance, and UX issues early. Use before major features or risky changes."
+user-invocable: true
+when_to_use: "Invoke before high-risk changes that need persona debate."
+category: utilities
+keywords: [prediction, debate, review, risk]
+argument-hint: "<feature description or change proposal> [--files <glob>] [--chain reason|probe]"
+metadata:
+  author: primekit
+  attribution: "Multi-persona prediction pattern adapted from autoresearch by Udit Goenka (MIT)"
+  license: MIT
+  version: "1.1.0"
+---
+
+# pk:predict — Multi-Persona Pre-Analysis
+
+Five expert personas independently analyze a proposed change, then debate conflicts to produce a consensus verdict before a single line of code is written.
+
+## When to Use
+
+- Before implementing a major or high-risk feature
+- Before a significant refactor or architecture change
+- Evaluating competing technical approaches
+- Stress-testing assumptions in a proposed design
+
+## When NOT to Use
+
+- Trivial or low-risk changes (use `pk:debug` for bugs, `pk:plan` for already-decided tasks)
+- Already-approved work with no open design questions
+- Pure dependency upgrades with no API changes
+
+---
+
+## The 5 Personas
+
+| Persona | Focus | Core Questions |
+|---------|-------|----------------|
+| **Architect** | System design, scalability, coupling | Does this fit the architecture? Will it scale? What new coupling does it introduce? |
+| **Security** | Attack surface, data protection, auth | What can be abused? Where is data exposed? Are auth boundaries respected? |
+| **Performance** | Latency, memory, queries, bundle size | What is the latency impact? N+1 queries? Memory leaks? Bundle bloat? |
+| **UX** | User experience, accessibility, error states | Is this intuitive? What does the error state look like? Accessible on mobile? |
+| **Devil's Advocate** | Hidden assumptions, simpler alternatives | Why not do nothing? What is the simplest alternative? Which load-bearing assumption — one the proposal fails without — could be wrong, and what does it cost to reverse course once it is? |
+
+---
+
+## Debate Protocol
+
+1. **Read** the proposed change/feature description from the argument
+2. **Read relevant code** if file paths are provided (grep for affected areas)
+3. **Each persona analyzes independently** — do not let personas influence each other during this phase
+4. **Identify agreements** — points where all (or 4+) personas align
+5. **Identify conflicts** — points where personas meaningfully disagree
+6. **Weigh tradeoffs** — for each conflict, evaluate which concern has higher impact, comparing the options on their worst plausible case, not only their expected one
+7. **Produce verdict** — GO / CAUTION / STOP with actionable recommendations
+
+---
+
+## Output Format
+
+```
+## Prediction Report: [proposal title]
+
+## Verdict: GO | CAUTION | STOP
+
+### Agreements (all personas align)
+- [Point 1 — what they all agree on]
+- [Point 2]
+
+### Conflicts & Resolutions
+
+| Topic | Architect | Security | Performance | UX | Devil's Advocate | Resolution |
+|-------|-----------|----------|-------------|-----|-----------------|------------|
+| [Issue] | [View] | [View] | [View] | [View] | [View] | [Recommendation] |
+
+### Risk Summary
+
+| Risk | Severity | Early signal | Mitigation |
+|------|----------|--------------|------------|
+| [Risk description] | Critical/High/Medium/Low | [Observable sign this risk is materializing — omit when the risk is already certain] | [Concrete action] |
+
+### Recommendations
+1. [Action item — rationale]
+2. [Action item — rationale]
+3. [Action item — rationale]
+```
+
+---
+
+## Verdict Levels
+
+| Verdict | Meaning |
+|---------|---------|
+| **GO** | All personas aligned, no critical risks, proceed with confidence |
+| **CAUTION** | Concerns exist but are manageable — mitigations identified, proceed carefully |
+| **STOP** | Critical unresolved issue found — needs redesign or more information before proceeding |
+
+### STOP Triggers (any one is sufficient)
+- Security persona identifies auth bypass or data exposure with no viable mitigation
+- Architect identifies fundamental design incompatibility requiring significant rework
+- Performance persona identifies unacceptable latency or query explosion with no workaround
+- Devil's Advocate exposes a false assumption that invalidates the entire approach
+
+---
+
+## Chain Modes
+
+After producing the verdict, predict can chain into a follow-on workflow that always runs as part of a predict session (not as a standalone skill).
+
+| Flag | Purpose | When to use |
+|------|---------|-------------|
+| `--chain reason` | Subjective refinement loop — generate → critique → synthesize → blind judge → repeat until convergence | Verdict is CAUTION with subjective tradeoffs (architecture polish, design coherence) |
+| `--chain probe` | Requirement interrogation — saturation-driven harvest of missing constraints + assumptions | Verdict is CAUTION or STOP because of "missing constraint" or "unstated assumption" findings |
+
+Use the chain-mode summaries below as the supported protocol for this kit.
+
+These chain modes absorb upstream `/autoresearch:reason` and `/autoresearch:probe` ([uditgoenka/autoresearch](https://github.com/uditgoenka/autoresearch), MIT). They're folded into pk:predict — not shipped as standalone skills — because they always chain off a predict invocation. See `/pk:autoresearch` for the family map.
+
+---
+
+## Integration with Other Skills
+
+| Workflow Step | Skill | How |
+|---------------|-------|-----|
+| Deepen risk scenarios | `pk:scenario` | Feed Risk Summary rows as feature description |
+| Create implementation plan | `pk:plan` | Attach Recommendations as constraints to planner |
+| High-risk feature implementation | `pk:cook` | Reference CAUTION/STOP items as acceptance gates |
+
+---
+
+## Example Invocations
+
+```
+/pk:predict "Add WebSocket support for real-time notifications"
+/pk:predict "Migrate authentication from JWT to session cookies"
+/pk:predict "Add multi-tenancy to the database layer"
+/pk:predict "Replace REST API with GraphQL" --files src/api/**/*.ts
+
+# Chain modes
+/pk:predict "Pick auth library: Passport vs Better Auth" --chain reason
+/pk:predict "Move from REST to GraphQL" --chain probe
+```
+
+---
+
+## Lineage
+
+Faithful absorption (in scope) of upstream `/autoresearch:predict` ([uditgoenka/autoresearch](https://github.com/uditgoenka/autoresearch), MIT). The local version supports the 5-persona debate plus `--chain reason` (subjective refinement) and `--chain probe` (requirement interrogation), folding upstream's `/autoresearch:reason` and `/autoresearch:probe` sub-commands into chain modes rather than separate skills.
+
+See `/pk:autoresearch` for the full family map.

package/skills/preview/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: pk:preview
+description: "View files or generate visual explanations, slides, and diagrams. Use for code walkthroughs, architecture visualization, HTML/Markdown presentations."
+user-invocable: true
+when_to_use: "Invoke for visual explanations, file previews, or diagrams."
+category: utilities
+keywords: [preview, visual, slides, diagrams, HTML]
+argument-hint: "[path] OR [--html] --explain|--slides|--diagram|--ascii [topic] OR --html --diff|--plan-review|--recap [--no-antv|--no-diagram-design|--no-editorial-visuals]"
+metadata:
+  author: primekit
+  version: "1.2.0"
+  attribution: "Visual self-review pattern for diagram output adapted from fireworks-tech-graph by yizhiyanhua-ai (MIT)"
+  license: MIT
+---
+
+# Preview
+
+Universal viewer + visual generator. View existing content OR generate new visual explanations.
+
+## Default (No Arguments)
+
+If invoked without arguments, use `ask_user capability` to present available preview operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `(view)` | View a file or directory |
+| `--explain` | Generate visual explanation |
+| `--slides` | Generate presentation slides |
+| `--diagram` | Generate architecture diagram |
+| `--ascii` | Terminal-friendly diagram |
+| `--stop` | Stop preview server |
+| `--html --explain` | Self-contained HTML explanation (opens in browser) |
+| `--html --diagram` | Self-contained HTML diagram with zoom controls |
+| `--html --slides` | Magazine-quality HTML slide deck |
+| `--html --diff` | Visual diff review (HTML) |
+| `--html --plan-review` | Plan vs codebase comparison (HTML) |
+| `--html --recap` | Project context snapshot (HTML) |
+
+Present as options via `ask_user capability` with header "Preview Operation", question "What would you like to do?".
+
+## Usage
+
+### View Mode
+- `/pk:preview <file.md>` - View markdown file in novel-reader UI
+- `/pk:preview <directory/>` - Browse directory contents
+- `/pk:preview --stop` - Stop running server
+
+### Generation Mode (Markdown)
+- `/pk:preview --explain <topic>` - Generate visual explanation (ASCII + Mermaid + prose)
+- `/pk:preview --slides <topic>` - Generate presentation slides (one concept per slide)
+- `/pk:preview --diagram <topic>` - Generate focused diagram (ASCII + Mermaid)
+- `/pk:preview --ascii <topic>` - Generate ASCII-only diagram (terminal-friendly)
+
+### Generation Mode (HTML)
+- `/pk:preview --html --explain <topic>` - Self-contained HTML explanation
+- `/pk:preview --html --slides <topic>` - Magazine-quality HTML slide deck
+- `/pk:preview --html --diagram <topic>` - HTML diagram with zoom controls
+- `/pk:preview --html --diff [ref]` - Visual diff review
+- `/pk:preview --html --plan-review [plan-file]` - Plan vs codebase comparison
+- `/pk:preview --html --recap [timeframe]` - Project context snapshot
+
+## Argument Resolution
+
+When processing arguments, follow this priority order:
+
+1. **`--stop`** → Stop server (exit)
+2. **`--html` flag present** → Set HTML output mode flag (continues to next step)
+3. **Generation flags** (`--explain`, `--slides`, `--diagram`, `--ascii`) → Generation mode. Load `references/generation-modes.md`
+4. **HTML-only flags** (`--diff`, `--plan-review`, `--recap`) → Auto-set HTML mode, then generation mode. Load `references/generation-modes.md`
+5. **Visual workflow without explicit mode** → Load `references/visual-explanation-routing.md` to choose mode
+6. **Resolve path from argument:**
+   - If argument is an explicit path → use directly
+   - If argument is a contextual reference → resolve from recent conversation context
+7. **Resolved path exists on filesystem** → View mode. Load `references/view-mode.md`
+8. **Path doesn't exist or can't resolve** → Ask user to clarify
+
+**Topic-to-slug conversion:**
+- Lowercase the topic
+- Replace spaces/special chars with hyphens
+- Remove non-alphanumeric except hyphens
+- Collapse multiple hyphens → single hyphen
+- Trim leading/trailing hyphens
+- **Max 80 chars** - truncate at word boundary if longer
+
+**Multiple flags:** If multiple generation flags provided, use first one; remaining treated as topic.
+
+**Placeholder `{topic}`:** Replaced with original user input in title case (not the slug).
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Invalid topic (empty) | Ask user to provide a topic |
+| Flag without topic | Ask user: "Please provide a topic: `/pk:preview --explain <topic>`" |
+| Topic becomes empty after sanitization | Ask for topic with alphanumeric characters |
+| File write failure | Report error, suggest checking disk space and permissions |
+| Server startup failure | Check if port in use, try `/pk:preview --stop` first |
+| No generation flag + unresolvable reference | Ask user to clarify which file they meant |
+| Existing file at output path | Overwrite with new content (no prompt) |
+| Server already running | Reuse existing server instance, just open new URL |
+| Parent `plans/` dir missing | Create directories recursively before write |
+| `--diff` without git context | Explain: "No git repo detected. Run inside a git repository." |
+| `--plan-review` without plan file or active plan | Explain: "Provide a plan file path or run from a session with an active plan." |
+| `--recap` without git history | Explain: "No git history found. Run inside a git repository with commits." |
+| `--html --ascii` combination | Not supported — `--ascii` is terminal-only by design. Suggest `--html --diagram` instead |
+| `--diff` with PR number but `gh` unavailable | Explain: "GitHub CLI (gh) is required for PR diffs. Install from https://cli.github.com/" |
+
+## HTML Output Mode (`--html`)
+
+Adding `--html` to any generation flag switches output from Markdown to a self-contained HTML file.
+
+**Output:** Single `.html` file with all CSS/JS inline. Opens directly in browser — no server needed.
+**Location:** `{plan_dir}/visuals/{slug}.html` (same plan-aware logic as markdown mode)
+**Browser open:** `open` (macOS) / `xdg-open` (Linux) / `start` (Windows)
+**MANDATORY — Theme Toggle:** Every HTML page MUST include a light/dark theme toggle button. See `html-css-patterns.md` → "Theme Toggle Button" for the exact CSS, HTML, and JS to include. Pages without the toggle are considered incomplete.
+
+### Reference Loading (HTML mode)
+
+Before generating, agent MUST read these references:
+
+| Mode | Always read | Mode-specific |
+|------|-------------|---------------|
+| All HTML modes | `html-design-guidelines.md` | — |
+| `--explain` | `html-css-patterns.md`, `html-libraries.md` | Template: `architecture.html` |
+| `--diagram` | `html-css-patterns.md`, `html-libraries.md` | Template: `mermaid-flowchart.html` or `architecture.html` |
+| `--slides` | `html-slide-patterns.md`, `html-css-patterns.md`, `html-libraries.md` | Template: `slide-deck.html` |
+| `--diff` | `html-css-patterns.md`, `html-libraries.md` | Templates: `data-table.html`, `architecture.html` |
+| `--plan-review` | `html-css-patterns.md`, `html-libraries.md` | Templates: `architecture.html`, `data-table.html` |
+| `--recap` | `html-css-patterns.md`, `html-libraries.md` | Templates: `architecture.html`, `data-table.html` |
+
+Multi-section pages (`--explain`, `--diff`, `--plan-review`, `--recap`): also read `html-responsive-nav.md`.
+
+Use `/pk:mermaidjs-v11` skill for Mermaid syntax validation.
+
+### Editorial visual layer (on by default, additive)
+
+Two libraries extend Mermaid/Chart.js when the intent maps cleanly to an editorial vernacular. Both are on by default with a 3-tier opt-out — resolve via `primekit config prefs resolve --json | jq '.prefs.visual'` (nested keys use hook-facing camelCase, so `diagram_design` returns as `diagramDesign`); both fall back cleanly when disabled or when render fails.
+
+| Intent | Default engine | Editorial alternate | Reference |
+|--------|---------------|---------------------|-----------|
+| Architecture / concept | Mermaid C4 | **diagram-design Architecture** | `html-diagram-design.md` |
+| Quadrant 2×2 | (none) | **diagram-design Quadrant** | `html-diagram-design.md` |
+| Timeline | Mermaid gantt | **diagram-design Timeline** OR **AntV timeline** | both refs |
+| KPI panel (≥3 tiles) | Chart.js | **AntV Infographic** (`CandyCardLite`, `CircularProgress`) | `html-antv-infographic.md` |
+| Ranked list / compare | HTML table | **AntV `CompareBinaryHorizontal`** | `html-antv-infographic.md` |
+| DP security / integration / medallion | (none) | **diagram-design** (upstream types) | `html-diagram-design.md` |
+
+Resolution ladder per invocation: `--no-editorial-visuals` > `--no-antv` / `--no-diagram-design` > project `.primekit/config.yaml` > user `~/.primekit/config.yaml` > default `enabled: true`. No env-var tier. Read the corresponding reference file only when the intent matches — do not preload both.
+
+**Fallback contract (advisory in v1):** if AntV load or render fails, log `[antv] fell back to <engine>` and drop to Mermaid/Chart.js. If a diagram-design SVG fails geometry validation twice, drop to Mermaid. Vendored validator wrapper: `references/vendor/diagram-design-scripts/run-validators.sh` (exits 0 when `python3` is absent).
+
+### HTML-Only Modes
+
+#### `--diff [ref]` (implies --html)
+Visual diff review. Scope detection: branch name, commit hash, HEAD, PR number, commit range, default=main.
+Data: git diff --stat, --name-status, changed files, new API surface, CHANGELOG.
+Output: executive summary, KPI dashboard, module architecture (Mermaid), feature comparisons (side-by-side), flow diagrams, file map, test coverage, code review cards (Good/Bad/Ugly/Questions), decision log, re-entry context.
+
+#### `--plan-review [plan-file]` (implies --html)
+Plan vs codebase comparison. Input: plan file path or detect from active plan context.
+Data: read plan, read all referenced files, map blast radius, cross-reference assumptions.
+Output: plan summary, impact dashboard, current vs planned architecture (paired Mermaid), change breakdown (side-by-side), dependency analysis, risk assessment, review cards, understanding gaps.
+Visual language: blue=current, green=planned, amber=concern, red=gap.
+
+#### `--recap [timeframe]` (implies --html)
+Project context snapshot. Time window: shorthand (2w, 30d, 3m) or default 2w.
+Data: project identity, git log, git status, decision context, architecture scan.
+Output: project identity, architecture snapshot (Mermaid), recent activity, decision log, state KPI cards, mental model essentials, cognitive debt hotspots, next steps.
+
+### Style Strategy
+- Default: static anti-slop rules from `html-design-guidelines.md` (6 curated presets)
+- For `--slides`: consider invoking `/pk:ui-ux-pro-max` for richer style selection
+- Agent must vary aesthetics between consecutive HTML outputs (different font pair, palette)