mindforge-cc 11.5.0 → 11.6.0
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.
- package/.agent/mindforge/skill-tdd.md +53 -0
- package/.agent/mindforge/skills-index.md +118 -0
- package/.agent/mindforge/systematic-debug.md +60 -0
- package/.agent/skills/1password-skill/SKILL.md +156 -0
- package/.agent/skills/1password-skill/references/cli-examples.md +31 -0
- package/.agent/skills/1password-skill/references/get-started.md +21 -0
- package/.agent/skills/article-illustrator/SKILL.md +199 -0
- package/.agent/skills/article-illustrator/references/prompt-construction.md +426 -0
- package/.agent/skills/article-illustrator/references/style-presets.md +80 -0
- package/.agent/skills/article-illustrator/references/styles.md +224 -0
- package/.agent/skills/article-illustrator/references/usage.md +50 -0
- package/.agent/skills/article-illustrator/references/workflow.md +332 -0
- package/.agent/skills/arxiv/SKILL.md +275 -0
- package/.agent/skills/blogwatcher/SKILL.md +130 -0
- package/.agent/skills/code-wiki/SKILL.md +438 -0
- package/.agent/skills/code-wiki/templates/README.md +31 -0
- package/.agent/skills/code-wiki/templates/architecture.md +30 -0
- package/.agent/skills/code-wiki/templates/getting-started.md +47 -0
- package/.agent/skills/code-wiki/templates/module.md +38 -0
- package/.agent/skills/codebase-inspection/SKILL.md +109 -0
- package/.agent/skills/comic-creator/SKILL.md +240 -0
- package/.agent/skills/comic-creator/references/analysis-framework.md +176 -0
- package/.agent/skills/comic-creator/references/auto-selection.md +71 -0
- package/.agent/skills/comic-creator/references/base-prompt.md +98 -0
- package/.agent/skills/comic-creator/references/character-template.md +180 -0
- package/.agent/skills/comic-creator/references/ohmsha-guide.md +85 -0
- package/.agent/skills/comic-creator/references/partial-workflows.md +106 -0
- package/.agent/skills/comic-creator/references/storyboard-template.md +143 -0
- package/.agent/skills/comic-creator/references/workflow.md +401 -0
- package/.agent/skills/concept-diagrams/SKILL.md +355 -0
- package/.agent/skills/concept-diagrams/references/dashboard-patterns.md +43 -0
- package/.agent/skills/concept-diagrams/references/infrastructure-patterns.md +144 -0
- package/.agent/skills/concept-diagrams/references/physical-shape-cookbook.md +42 -0
- package/.agent/skills/creative-ideation/SKILL.md +144 -0
- package/.agent/skills/creative-ideation/references/full-prompt-library.md +110 -0
- package/.agent/skills/devops-cli/SKILL.md +149 -0
- package/.agent/skills/devops-cli/references/app-discovery.md +112 -0
- package/.agent/skills/devops-cli/references/authentication.md +59 -0
- package/.agent/skills/devops-cli/references/cli-reference.md +104 -0
- package/.agent/skills/devops-cli/references/running-apps.md +171 -0
- package/.agent/skills/devops-watchers/SKILL.md +103 -0
- package/.agent/skills/docker-management/SKILL.md +273 -0
- package/.agent/skills/domain-intel/SKILL.md +96 -0
- package/.agent/skills/duckduckgo-search/SKILL.md +230 -0
- package/.agent/skills/github-auth/SKILL.md +240 -0
- package/.agent/skills/github-code-review/SKILL.md +474 -0
- package/.agent/skills/github-code-review/references/review-output-template.md +74 -0
- package/.agent/skills/github-issues/SKILL.md +363 -0
- package/.agent/skills/github-issues/templates/bug-report.md +35 -0
- package/.agent/skills/github-issues/templates/feature-request.md +31 -0
- package/.agent/skills/github-pr-workflow/SKILL.md +360 -0
- package/.agent/skills/github-pr-workflow/references/ci-troubleshooting.md +183 -0
- package/.agent/skills/github-pr-workflow/references/conventional-commits.md +71 -0
- package/.agent/skills/github-pr-workflow/templates/pr-body-bugfix.md +35 -0
- package/.agent/skills/github-pr-workflow/templates/pr-body-feature.md +33 -0
- package/.agent/skills/github-repo-management/SKILL.md +509 -0
- package/.agent/skills/github-repo-management/references/github-api-cheatsheet.md +161 -0
- package/.agent/skills/godmode/SKILL.md +396 -0
- package/.agent/skills/godmode/references/jailbreak-templates.md +128 -0
- package/.agent/skills/godmode/references/refusal-detection.md +142 -0
- package/.agent/skills/hyperframes/SKILL.md +182 -0
- package/.agent/skills/hyperframes/references/cli.md +185 -0
- package/.agent/skills/hyperframes/references/composition.md +129 -0
- package/.agent/skills/hyperframes/references/features.md +289 -0
- package/.agent/skills/hyperframes/references/gsap.md +136 -0
- package/.agent/skills/hyperframes/references/troubleshooting.md +137 -0
- package/.agent/skills/hyperframes/references/website-to-video.md +145 -0
- package/.agent/skills/jupyter-live-kernel/SKILL.md +160 -0
- package/.agent/skills/kanban-orchestrator/SKILL.md +209 -0
- package/.agent/skills/kanban-worker/SKILL.md +188 -0
- package/.agent/skills/llm-wiki/SKILL.md +499 -0
- package/.agent/skills/meme-generation/SKILL.md +122 -0
- package/.agent/skills/node-inspect-debugger/SKILL.md +312 -0
- package/.agent/skills/obsidian/SKILL.md +60 -0
- package/.agent/skills/osint-investigation/SKILL.md +269 -0
- package/.agent/skills/osint-investigation/templates/source-template.md +59 -0
- package/.agent/skills/oss-forensics/SKILL.md +422 -0
- package/.agent/skills/oss-forensics/references/evidence-types.md +89 -0
- package/.agent/skills/oss-forensics/references/github-archive-guide.md +184 -0
- package/.agent/skills/oss-forensics/references/investigation-templates.md +131 -0
- package/.agent/skills/oss-forensics/references/recovery-techniques.md +164 -0
- package/.agent/skills/oss-forensics/templates/forensic-report.md +151 -0
- package/.agent/skills/oss-forensics/templates/malicious-package-report.md +43 -0
- package/.agent/skills/parallel-cli/SKILL.md +384 -0
- package/.agent/skills/pinggy-tunnel/SKILL.md +302 -0
- package/.agent/skills/pixel-art/SKILL.md +209 -0
- package/.agent/skills/pixel-art/references/palettes.md +49 -0
- package/.agent/skills/plan/SKILL.md +331 -0
- package/.agent/skills/polymarket/SKILL.md +75 -0
- package/.agent/skills/polymarket/references/api-endpoints.md +220 -0
- package/.agent/skills/python-debugpy/SKILL.md +368 -0
- package/.agent/skills/requesting-code-review/SKILL.md +273 -0
- package/.agent/skills/research-paper-writing/SKILL.md +2367 -0
- package/.agent/skills/research-paper-writing/references/autoreason-methodology.md +394 -0
- package/.agent/skills/research-paper-writing/references/checklists.md +434 -0
- package/.agent/skills/research-paper-writing/references/citation-workflow.md +563 -0
- package/.agent/skills/research-paper-writing/references/experiment-patterns.md +728 -0
- package/.agent/skills/research-paper-writing/references/human-evaluation.md +476 -0
- package/.agent/skills/research-paper-writing/references/paper-types.md +481 -0
- package/.agent/skills/research-paper-writing/references/reviewer-guidelines.md +433 -0
- package/.agent/skills/research-paper-writing/references/sources.md +191 -0
- package/.agent/skills/research-paper-writing/references/writing-guide.md +474 -0
- package/.agent/skills/research-paper-writing/templates/README.md +251 -0
- package/.agent/skills/rest-graphql-debug/SKILL.md +507 -0
- package/.agent/skills/s6-container-supervision/SKILL.md +171 -0
- package/.agent/skills/scrapling/SKILL.md +328 -0
- package/.agent/skills/sherlock/SKILL.md +186 -0
- package/.agent/skills/simplify-code/SKILL.md +168 -0
- package/.agent/skills/skill-authoring/SKILL.md +158 -0
- package/.agent/skills/spike/SKILL.md +190 -0
- package/.agent/skills/subagent-driven-development/SKILL.md +345 -0
- package/.agent/skills/subagent-driven-development/references/context-budget-discipline.md +53 -0
- package/.agent/skills/subagent-driven-development/references/gates-taxonomy.md +93 -0
- package/.agent/skills/systematic-debugging/SKILL.md +360 -0
- package/.agent/skills/test-driven-development/SKILL.md +336 -0
- package/.agent/skills/video-orchestrator/SKILL.md +194 -0
- package/.agent/skills/video-orchestrator/references/examples.md +227 -0
- package/.agent/skills/video-orchestrator/references/intake.md +166 -0
- package/.agent/skills/video-orchestrator/references/kanban-setup.md +278 -0
- package/.agent/skills/video-orchestrator/references/monitoring.md +180 -0
- package/.agent/skills/video-orchestrator/references/role-archetypes.md +298 -0
- package/.agent/skills/video-orchestrator/references/tool-matrix.md +317 -0
- package/.agent/skills/web-pentest/SKILL.md +332 -0
- package/.agent/skills/web-pentest/references/bypass-techniques.md +133 -0
- package/.agent/skills/web-pentest/references/exploitation-techniques.md +204 -0
- package/.agent/skills/web-pentest/references/scope-enforcement.md +110 -0
- package/.agent/skills/web-pentest/references/vuln-taxonomy.md +81 -0
- package/.agent/skills/web-pentest/templates/authorization.md +69 -0
- package/.agent/skills/web-pentest/templates/pentest-report.md +178 -0
- package/.claude/commands/mindforge/skill-tdd.md +53 -0
- package/.claude/commands/mindforge/skills-index.md +118 -0
- package/.claude/commands/mindforge/systematic-debug.md +60 -0
- package/.mindforge/config.json +2 -2
- package/.mindforge/memory/sync-manifest.json +1 -1
- package/.mindforge/skills/arxiv/SKILL.md +294 -0
- package/.mindforge/skills/blogwatcher/SKILL.md +147 -0
- package/.mindforge/skills/code-wiki/SKILL.md +457 -0
- package/.mindforge/skills/codebase-inspection/SKILL.md +126 -0
- package/.mindforge/skills/concept-diagrams/SKILL.md +373 -0
- package/.mindforge/skills/creative-ideation/SKILL.md +162 -0
- package/.mindforge/skills/domain-intel/SKILL.md +116 -0
- package/.mindforge/skills/duckduckgo-search/SKILL.md +249 -0
- package/.mindforge/skills/github-code-review/SKILL.md +493 -0
- package/.mindforge/skills/github-issues/SKILL.md +382 -0
- package/.mindforge/skills/github-pr-workflow/SKILL.md +379 -0
- package/.mindforge/skills/jupyter-live-kernel/SKILL.md +179 -0
- package/.mindforge/skills/kanban-orchestrator/SKILL.md +227 -0
- package/.mindforge/skills/kanban-worker/SKILL.md +206 -0
- package/.mindforge/skills/meme-generation/SKILL.md +141 -0
- package/.mindforge/skills/obsidian/SKILL.md +80 -0
- package/.mindforge/skills/osint-investigation/SKILL.md +288 -0
- package/.mindforge/skills/oss-forensics/SKILL.md +421 -0
- package/.mindforge/skills/pixel-art/SKILL.md +228 -0
- package/.mindforge/skills/plan/SKILL.md +350 -0
- package/.mindforge/skills/requesting-code-review/SKILL.md +292 -0
- package/.mindforge/skills/research-paper-writing/SKILL.md +2384 -0
- package/.mindforge/skills/scrapling/SKILL.md +345 -0
- package/.mindforge/skills/sherlock/SKILL.md +203 -0
- package/.mindforge/skills/simplify-code/SKILL.md +187 -0
- package/.mindforge/skills/spike/SKILL.md +209 -0
- package/.mindforge/skills/subagent-driven-development/SKILL.md +364 -0
- package/.mindforge/skills/systematic-debugging/SKILL.md +379 -0
- package/.mindforge/skills/test-driven-development/SKILL.md +355 -0
- package/.mindforge/skills/web-pentest/SKILL.md +327 -0
- package/CHANGELOG.md +88 -0
- package/MINDFORGE.md +3 -3
- package/README.md +38 -3
- package/RELEASENOTES.md +100 -0
- package/bin/dashboard/api-router.js +10 -1
- package/bin/governance/approve.js +5 -1
- package/bin/memory/federated-sync.js +11 -2
- package/bin/memory/knowledge-capture.js +10 -1
- package/bin/memory/pillar-health-tracker.js +9 -1
- package/bin/review/ads-engine.js +2 -2
- package/bin/security/trust-boundaries.js +5 -0
- package/docs/getting-started.md +42 -5
- package/package.json +1 -1
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Website to Video
|
|
2
|
+
|
|
3
|
+
Capture a website, produce a professional video from it. Use when the user provides a URL and wants a video — social ad, product tour, 30-second promo, etc.
|
|
4
|
+
|
|
5
|
+
The workflow has 7 steps. Each produces an artifact that gates the next. **Do not skip steps** — each artifact prevents a downstream failure mode.
|
|
6
|
+
|
|
7
|
+
## Step 1: Capture & Understand
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx hyperframes capture https://example.com -o example-video
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Produces `example-video/capture/` with:
|
|
14
|
+
- `capture/screenshots/` — above-the-fold + section screenshots (up to `--max-screenshots`)
|
|
15
|
+
- `capture/assets/` — logos, hero images, background video (if any)
|
|
16
|
+
- `capture/extracted/tokens.json` — colors, fonts, and spacing tokens
|
|
17
|
+
- `capture/extracted/visible-text.txt` — extracted headings, paragraphs, CTAs
|
|
18
|
+
- `capture/extracted/fonts.json` — font families and stacks detected in computed styles
|
|
19
|
+
- `capture/asset-descriptions.md` — auto-generated asset catalog
|
|
20
|
+
|
|
21
|
+
All subsequent steps read from the `capture/` subfolder — `capture/extracted/tokens.json`, `capture/assets/hero.png`, etc. Never strip the `capture/` prefix when referencing these files.
|
|
22
|
+
|
|
23
|
+
**Gate:** Print a site summary — name, top 3 colors, primary + display fonts, hero asset path, one-sentence vibe. Keep it in your context — don't re-capture.
|
|
24
|
+
|
|
25
|
+
## Step 2: Write DESIGN.md
|
|
26
|
+
|
|
27
|
+
Small brand reference at the project root. 6 sections, ~90 lines. This is the cheat sheet — not the creative plan.
|
|
28
|
+
|
|
29
|
+
```markdown
|
|
30
|
+
# DESIGN
|
|
31
|
+
|
|
32
|
+
## Brand
|
|
33
|
+
- Name: Example Co.
|
|
34
|
+
- One-line mission: "…"
|
|
35
|
+
|
|
36
|
+
## Colors
|
|
37
|
+
- Background: #0B0F14
|
|
38
|
+
- Primary: #00E0A4 (accent, CTA)
|
|
39
|
+
- Secondary: #7A8B9B (body text)
|
|
40
|
+
- Text: #FFFFFF
|
|
41
|
+
|
|
42
|
+
## Typography
|
|
43
|
+
- Display: "Inter Tight", 700, tight letter-spacing
|
|
44
|
+
- Body: "Inter", 400
|
|
45
|
+
|
|
46
|
+
## Motion
|
|
47
|
+
- Mood: precise, technical, confident
|
|
48
|
+
- Eases: `power3.out` for entrances, `expo.in` for exits
|
|
49
|
+
|
|
50
|
+
## Assets
|
|
51
|
+
- Logo: `capture/assets/logo.svg`
|
|
52
|
+
- Hero image: `capture/assets/hero.png`
|
|
53
|
+
|
|
54
|
+
## What NOT to Do
|
|
55
|
+
- No purple, no pastels, no serif body
|
|
56
|
+
- No playful/bubbly eases (`elastic`, `bounce`)
|
|
57
|
+
- No drop shadows on text
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**Gate:** `DESIGN.md` exists in the project directory.
|
|
61
|
+
|
|
62
|
+
## Step 3: Write SCRIPT.md
|
|
63
|
+
|
|
64
|
+
Narration script. Story backbone. **Scene durations come from the narration, not from guessing.**
|
|
65
|
+
|
|
66
|
+
```markdown
|
|
67
|
+
# SCRIPT
|
|
68
|
+
|
|
69
|
+
## Scene 1 — Hook (0:00–0:04)
|
|
70
|
+
"What if your dashboards wrote themselves?"
|
|
71
|
+
|
|
72
|
+
## Scene 2 — Problem (0:04–0:11)
|
|
73
|
+
"Teams spend hours stitching together queries, charts, and callouts — every Monday."
|
|
74
|
+
|
|
75
|
+
## Scene 3 — Solution (0:11–0:22)
|
|
76
|
+
"Example Co. watches your data streams and proposes the dashboard you'd have built — in seconds."
|
|
77
|
+
|
|
78
|
+
## Scene 4 — CTA (0:22–0:28)
|
|
79
|
+
"Try it free at example.com."
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Run `npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav` to generate TTS audio. Note the exact duration — that's the video's duration.
|
|
83
|
+
|
|
84
|
+
**Gate:** `SCRIPT.md` + `narration.wav` exist and durations match the plan (±0.3s).
|
|
85
|
+
|
|
86
|
+
## Step 4: Storyboard
|
|
87
|
+
|
|
88
|
+
Text-only scene plan: for each scene, describe the hero frame — what's on screen at the scene's most-visible moment.
|
|
89
|
+
|
|
90
|
+
```markdown
|
|
91
|
+
# STORYBOARD
|
|
92
|
+
|
|
93
|
+
## Scene 1 (0:00–0:04) — Hook
|
|
94
|
+
Hero frame: giant "WHAT IF YOUR DASHBOARDS WROTE THEMSELVES?" in display font, centered, on near-black. Logo top-left at 40% opacity.
|
|
95
|
+
Entrance: each word staggers in, 0.08s apart.
|
|
96
|
+
Transition out: flash-through-white into Scene 2.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
One paragraph per scene. Do NOT skip this step — it's where you catch narrative gaps before writing HTML.
|
|
100
|
+
|
|
101
|
+
**Gate:** `STORYBOARD.md` exists. Each scene has: hero frame, entrance, transition.
|
|
102
|
+
|
|
103
|
+
## Step 5: Composition
|
|
104
|
+
|
|
105
|
+
Write `index.html` scene-by-scene:
|
|
106
|
+
- Each scene is a `<div class="scene scene-N">` positioned absolutely, full-bleed.
|
|
107
|
+
- Static HTML+CSS for the hero frame first (no GSAP).
|
|
108
|
+
- Layer the narration `<audio>` at `data-start="0"` on a high track index.
|
|
109
|
+
- Add a transitions component (`flash-through-white`, `liquid-wipe`, etc.) between each scene.
|
|
110
|
+
- THEN add GSAP entrances (`gsap.from()`), no exits — transitions own the exit.
|
|
111
|
+
- Register `window.__timelines["root"] = tl`.
|
|
112
|
+
|
|
113
|
+
Install transitions as needed:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
npx hyperframes add flash-through-white
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Step 6: Render
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npx hyperframes lint --strict # must pass
|
|
123
|
+
npx hyperframes validate # WCAG contrast audit
|
|
124
|
+
npx hyperframes render --quality draft --output draft.mp4
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Watch the draft. Note issues in a `REVIEW.md` bullet list (scene, timestamp, issue). Fix, re-render.
|
|
128
|
+
|
|
129
|
+
When happy:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
npx hyperframes render --quality high --output final.mp4
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Step 7: Deliver
|
|
136
|
+
|
|
137
|
+
- Report file path + duration + file size to the user.
|
|
138
|
+
- If the user wants a vertical cut, re-render with a 9:16 composition (`data-width="1080" data-height="1920"`) — typically requires a separate `index-vertical.html` with tighter typography and re-stacked scene layout.
|
|
139
|
+
|
|
140
|
+
## Common Failure Modes
|
|
141
|
+
|
|
142
|
+
- **Skipped DESIGN.md** → colors drift scene-to-scene; output feels like "AI slides."
|
|
143
|
+
- **Skipped STORYBOARD.md** → scenes overlap or hero frames collide with transitions.
|
|
144
|
+
- **Exit animations** before transitions → empty frames when the transition fires.
|
|
145
|
+
- **Narration longer than `data-duration`** → audio clips mid-sentence. Update the composition's `data-duration` to match the TTS output length + 0.5s buffer.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: jupyter-live-kernel
|
|
3
|
+
description: "Iterative Python via live Jupyter kernel (hamelnb)."
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Jupyter Live Kernel (hamelnb)
|
|
8
|
+
|
|
9
|
+
Gives you a **stateful Python REPL** via a live Jupyter kernel. Variables persist
|
|
10
|
+
across executions. Use this instead of `execute_code` when you need to build up
|
|
11
|
+
state incrementally, explore APIs, inspect DataFrames, or iterate on complex code.
|
|
12
|
+
|
|
13
|
+
## When to Use This vs Other Tools
|
|
14
|
+
|
|
15
|
+
| Tool | Use When |
|
|
16
|
+
|------|----------|
|
|
17
|
+
| **This skill** | Iterative exploration, state across steps, data science, ML, "let me try this and check" |
|
|
18
|
+
| `execute_code` | One-shot scripts needing hermes tool access (web_search, file ops). Stateless. |
|
|
19
|
+
| `terminal` | Shell commands, builds, installs, git, process management |
|
|
20
|
+
|
|
21
|
+
**Rule of thumb:** If you'd want a Jupyter notebook for the task, use this skill.
|
|
22
|
+
|
|
23
|
+
## Prerequisites
|
|
24
|
+
|
|
25
|
+
1. **uv** must be installed (check: `which uv`)
|
|
26
|
+
2. **JupyterLab** must be installed: `uv tool install jupyterlab`
|
|
27
|
+
3. A Jupyter server must be running (see Setup below)
|
|
28
|
+
|
|
29
|
+
## Setup
|
|
30
|
+
|
|
31
|
+
The hamelnb script location:
|
|
32
|
+
```
|
|
33
|
+
SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
If not cloned yet:
|
|
37
|
+
```
|
|
38
|
+
git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Starting JupyterLab
|
|
42
|
+
|
|
43
|
+
Check if a server is already running:
|
|
44
|
+
```
|
|
45
|
+
uv run "$SCRIPT" servers
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
If no servers found, start one:
|
|
49
|
+
```
|
|
50
|
+
jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
|
|
51
|
+
--IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
|
|
52
|
+
sleep 3
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Note: Token/password disabled for local agent access. The server runs headless.
|
|
56
|
+
|
|
57
|
+
### Creating a Notebook for REPL Use
|
|
58
|
+
|
|
59
|
+
If you just need a REPL (no existing notebook), create a minimal notebook file:
|
|
60
|
+
```
|
|
61
|
+
mkdir -p ~/notebooks
|
|
62
|
+
```
|
|
63
|
+
Write a minimal .ipynb JSON file with one empty code cell, then start a kernel
|
|
64
|
+
session via the Jupyter REST API:
|
|
65
|
+
```
|
|
66
|
+
curl -s -X POST http://127.0.0.1:8888/api/sessions \
|
|
67
|
+
-H "Content-Type: application/json" \
|
|
68
|
+
-d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python3"}}'
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Core Workflow
|
|
72
|
+
|
|
73
|
+
All commands return structured JSON. Always use `--compact` to save tokens.
|
|
74
|
+
|
|
75
|
+
### 1. Discover servers and notebooks
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
uv run "$SCRIPT" servers --compact
|
|
79
|
+
uv run "$SCRIPT" notebooks --compact
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### 2. Execute code (primary operation)
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
State persists across execute calls. Variables, imports, objects all survive.
|
|
89
|
+
|
|
90
|
+
Multi-line code works with $'...' quoting:
|
|
91
|
+
```
|
|
92
|
+
uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### 3. Inspect live variables
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
|
|
99
|
+
uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### 4. Edit notebook cells
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
# View current cells
|
|
106
|
+
uv run "$SCRIPT" contents --path <notebook.ipynb> --compact
|
|
107
|
+
|
|
108
|
+
# Insert a new cell
|
|
109
|
+
uv run "$SCRIPT" edit --path <notebook.ipynb> insert \
|
|
110
|
+
--at-index <N> --cell-type code --source '<code>' --compact
|
|
111
|
+
|
|
112
|
+
# Replace cell source (use cell-id from contents output)
|
|
113
|
+
uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \
|
|
114
|
+
--cell-id <id> --source '<new code>' --compact
|
|
115
|
+
|
|
116
|
+
# Delete a cell
|
|
117
|
+
uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### 5. Verification (restart + run all)
|
|
121
|
+
|
|
122
|
+
Only use when the user asks for a clean verification or you need to confirm
|
|
123
|
+
the notebook runs top-to-bottom:
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Practical Tips from Experience
|
|
130
|
+
|
|
131
|
+
1. **First execution after server start may timeout** — the kernel needs a moment
|
|
132
|
+
to initialize. If you get a timeout, just retry.
|
|
133
|
+
|
|
134
|
+
2. **The kernel Python is JupyterLab's Python** — packages must be installed in
|
|
135
|
+
that environment. If you need additional packages, install them into the
|
|
136
|
+
JupyterLab tool environment first.
|
|
137
|
+
|
|
138
|
+
3. **--compact flag saves significant tokens** — always use it. JSON output can
|
|
139
|
+
be very verbose without it.
|
|
140
|
+
|
|
141
|
+
4. **For pure REPL use**, create a scratch.ipynb and don't bother with cell editing.
|
|
142
|
+
Just use `execute` repeatedly.
|
|
143
|
+
|
|
144
|
+
5. **Argument order matters** — subcommand flags like `--path` go BEFORE the
|
|
145
|
+
sub-subcommand. E.g.: `variables --path nb.ipynb list` not `variables list --path nb.ipynb`.
|
|
146
|
+
|
|
147
|
+
6. **If a session doesn't exist yet**, you need to start one via the REST API
|
|
148
|
+
(see Setup section). The tool can't execute without a live kernel session.
|
|
149
|
+
|
|
150
|
+
7. **Errors are returned as JSON** with traceback — read the `ename` and `evalue`
|
|
151
|
+
fields to understand what went wrong.
|
|
152
|
+
|
|
153
|
+
8. **Occasional websocket timeouts** — some operations may timeout on first try,
|
|
154
|
+
especially after a kernel restart. Retry once before escalating.
|
|
155
|
+
|
|
156
|
+
## Timeout Defaults
|
|
157
|
+
|
|
158
|
+
The script has a 30-second default timeout per execution. For long-running
|
|
159
|
+
operations, pass `--timeout 120`. Use generous timeouts (60+) for initial
|
|
160
|
+
setup or heavy computation.
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kanban-orchestrator
|
|
3
|
+
description: Decomposition playbook + anti-temptation rules for an orchestrator profile routing work through Kanban. The "don't do the work yourself" rule and the basic lifecycle are auto-injected into every kanban worker's system prompt; this skill is the deeper playbook when you're specifically playing the orchestrator role.
|
|
4
|
+
version: 3.0.0
|
|
5
|
+
environments: [kanban]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Kanban Orchestrator — Decomposition Playbook
|
|
9
|
+
|
|
10
|
+
> The **core worker lifecycle** (including the `kanban_create` fan-out pattern and the "decompose, don't execute" rule) is auto-injected into every kanban process via the `KANBAN_GUIDANCE` system-prompt block. This skill is the deeper playbook when you're an orchestrator profile whose whole job is routing.
|
|
11
|
+
|
|
12
|
+
## Profiles are user-configured — not a fixed roster
|
|
13
|
+
|
|
14
|
+
the agent setups vary widely. Some users run a single profile that does everything; some run a small fleet (`docker-worker`, `cron-worker`); some run a curated specialist team they've named themselves. There is **no default specialist roster** — the orchestrator skill does not know what profiles exist on this machine.
|
|
15
|
+
|
|
16
|
+
Before fanning out, you must ground the decomposition in the profiles that actually exist. The dispatcher silently fails to spawn unknown assignee names — it doesn't autocorrect, doesn't suggest, doesn't fall back. So a card assigned to `researcher` on a setup that only has `docker-worker` just sits in `ready` forever.
|
|
17
|
+
|
|
18
|
+
**Step 0: discover available profiles before planning.**
|
|
19
|
+
|
|
20
|
+
Use one of these:
|
|
21
|
+
|
|
22
|
+
- `hermes profile list` — prints the table of profiles configured on this machine. Run it through your terminal tool if you have one; otherwise ask the user.
|
|
23
|
+
- `kanban_list(assignee="<some-name>")` — sanity-check a single name. Returns an empty list (rather than an error) for an unknown assignee, so this only confirms a name you're already considering.
|
|
24
|
+
- **Just ask the user.** "What profiles do you have set up?" is a fine first turn when the goal needs more than one specialist.
|
|
25
|
+
|
|
26
|
+
Cache the result in your working memory for the rest of the conversation. Re-asking every turn wastes a tool call.
|
|
27
|
+
|
|
28
|
+
## When to use the board (vs. just doing the work)
|
|
29
|
+
|
|
30
|
+
Create Kanban tasks when any of these are true:
|
|
31
|
+
|
|
32
|
+
1. **Multiple specialists are needed.** Research + analysis + writing is three profiles.
|
|
33
|
+
2. **The work should survive a crash or restart.** Long-running, recurring, or important.
|
|
34
|
+
3. **The user might want to interject.** Human-in-the-loop at any step.
|
|
35
|
+
4. **Multiple subtasks can run in parallel.** Fan-out for speed.
|
|
36
|
+
5. **Review / iteration is expected.** A reviewer profile loops on drafter output.
|
|
37
|
+
6. **The audit trail matters.** Board rows persist in SQLite forever.
|
|
38
|
+
|
|
39
|
+
If *none* of those apply — it's a small one-shot reasoning task — use `delegate_task` instead or answer the user directly.
|
|
40
|
+
|
|
41
|
+
## The anti-temptation rules
|
|
42
|
+
|
|
43
|
+
Your job description says "route, don't execute." The rules that enforce that:
|
|
44
|
+
|
|
45
|
+
- **Do not execute the work yourself.** Your restricted toolset usually doesn't even include terminal/file/code/web for implementation. If you find yourself "just fixing this quickly" — stop and create a task for the right specialist.
|
|
46
|
+
- **For any concrete task, create a Kanban task and assign it.** Every single time.
|
|
47
|
+
- **Split multi-lane requests before creating cards.** A user prompt can contain several independent workstreams. Extract those lanes first, then create one card per lane instead of bundling unrelated work into a single implementer card.
|
|
48
|
+
- **Run independent lanes in parallel.** If two cards do not need each other's output, leave them unlinked so the dispatcher can fan them out. Link only true data dependencies.
|
|
49
|
+
- **Never create dependent work as independent ready cards.** If a card must wait for another card, pass `parents=[...]` in the original `kanban_create` call. Do not create it first and link it later, and do not rely on prose like "wait for T1" inside the body.
|
|
50
|
+
- **If no specialist fits the available profiles, ask the user which profile to create or which existing profile to use.** Do not invent profile names; the dispatcher will silently drop unknown assignees.
|
|
51
|
+
- **Decompose, route, and summarize — that's the whole job.**
|
|
52
|
+
|
|
53
|
+
## Decomposition playbook
|
|
54
|
+
|
|
55
|
+
### Step 1 — Understand the goal
|
|
56
|
+
|
|
57
|
+
Ask clarifying questions if the goal is ambiguous. Cheap to ask; expensive to spawn the wrong fleet.
|
|
58
|
+
|
|
59
|
+
### Step 2 — Sketch the task graph
|
|
60
|
+
|
|
61
|
+
Before creating anything, draft the graph out loud (in your response to the user). Treat every concrete workstream as a candidate card:
|
|
62
|
+
|
|
63
|
+
1. Extract the lanes from the request.
|
|
64
|
+
2. Map each lane to one of the profiles you discovered in Step 0. If a lane doesn't fit any existing profile, ask the user which to use or create.
|
|
65
|
+
3. Decide whether each lane is independent or gated by another lane.
|
|
66
|
+
4. Create independent lanes as parallel cards with no parent links.
|
|
67
|
+
5. Create synthesis/review/integration cards with parent links to the lanes they depend on. A child created with unfinished parents starts in `todo`; the dispatcher promotes it to `ready` only after every parent is done.
|
|
68
|
+
|
|
69
|
+
Examples of prompts that should fan out (using placeholder profile names — substitute whatever exists on the user's setup):
|
|
70
|
+
|
|
71
|
+
- "Build an app" → one card to a design-oriented profile for product/UI direction, one or two cards to engineering profiles for implementation, plus a later integration/review card if the user has a reviewer profile.
|
|
72
|
+
- "Fix blockers and check model variants" → one implementation card for the blocker fixes plus one discovery/research card for config/source verification. A final reviewer card can depend on both.
|
|
73
|
+
- "Research docs and implement" → a docs-research card can run in parallel with a codebase-discovery card; implementation waits only if it truly needs those findings.
|
|
74
|
+
- "Analyze this screenshot and find the related code" → one card to a vision-capable profile for the visual analysis while another searches the codebase.
|
|
75
|
+
|
|
76
|
+
Words like "also," "finally," or "and" do not automatically imply a dependency. They often mean "make sure this is covered before reporting back." Only link tasks when one card cannot start until another card's output exists.
|
|
77
|
+
|
|
78
|
+
Show the graph to the user before creating cards. Let them correct it — including which actual profile name should own each lane.
|
|
79
|
+
|
|
80
|
+
### Step 3 — Create tasks and link
|
|
81
|
+
|
|
82
|
+
Use the profile names from Step 0. The example below uses placeholders `<profile-A>`, `<profile-B>`, `<profile-C>` — replace them with what the user actually has.
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
t1 = kanban_create(
|
|
86
|
+
title="research: Postgres cost vs current",
|
|
87
|
+
assignee="<profile-A>", # whichever profile handles research on this setup
|
|
88
|
+
body="Compare estimated infrastructure costs, migration costs, and ongoing ops costs over a 3-year window. Sources: AWS/GCP pricing, team time estimates, current Postgres bills from peers.",
|
|
89
|
+
tenant=os.environ.get("HERMES_TENANT"),
|
|
90
|
+
)["task_id"]
|
|
91
|
+
|
|
92
|
+
t2 = kanban_create(
|
|
93
|
+
title="research: Postgres performance vs current",
|
|
94
|
+
assignee="<profile-A>", # same profile, run in parallel
|
|
95
|
+
body="Compare query latency, throughput, and scaling characteristics at our expected data volume (~500GB, 10k QPS peak). Sources: benchmark papers, public case studies, pgbench results if easy.",
|
|
96
|
+
)["task_id"]
|
|
97
|
+
|
|
98
|
+
t3 = kanban_create(
|
|
99
|
+
title="synthesize migration recommendation",
|
|
100
|
+
assignee="<profile-B>", # whichever profile does synthesis/analysis
|
|
101
|
+
body="Read the findings from T1 (cost) and T2 (performance). Produce a 1-page recommendation with explicit trade-offs and a go/no-go call.",
|
|
102
|
+
parents=[t1, t2],
|
|
103
|
+
)["task_id"]
|
|
104
|
+
|
|
105
|
+
t4 = kanban_create(
|
|
106
|
+
title="draft decision memo",
|
|
107
|
+
assignee="<profile-C>", # whichever profile drafts user-facing prose
|
|
108
|
+
body="Turn the analyst's recommendation into a 2-page memo for the CTO. Match the tone of previous decision memos in the team's knowledge base.",
|
|
109
|
+
parents=[t3],
|
|
110
|
+
)["task_id"]
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`parents=[...]` gates promotion — children stay in `todo` until every parent reaches `done`, then auto-promote to `ready`. No manual coordination needed; the dispatcher and dependency engine handle it.
|
|
114
|
+
|
|
115
|
+
If the task graph has dependencies, create the parent cards first, capture their returned ids, and include those ids in the child card's `parents` list during the child `kanban_create` call. Avoid creating all cards in parallel and linking them afterward; that creates a window where the dispatcher can claim a child before its inputs exist.
|
|
116
|
+
|
|
117
|
+
### Step 4 — Complete your own task
|
|
118
|
+
|
|
119
|
+
If you were spawned as a task yourself (e.g. a planner profile was assigned `T0: "investigate Postgres migration"`), mark it done with a summary of what you created:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
kanban_complete(
|
|
123
|
+
summary="decomposed into T1-T4: 2 research lanes in parallel, 1 synthesis on their outputs, 1 prose draft on the recommendation",
|
|
124
|
+
metadata={
|
|
125
|
+
"task_graph": {
|
|
126
|
+
"T1": {"assignee": "<profile-A>", "parents": []},
|
|
127
|
+
"T2": {"assignee": "<profile-A>", "parents": []},
|
|
128
|
+
"T3": {"assignee": "<profile-B>", "parents": ["T1", "T2"]},
|
|
129
|
+
"T4": {"assignee": "<profile-C>", "parents": ["T3"]},
|
|
130
|
+
},
|
|
131
|
+
},
|
|
132
|
+
)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Step 5 — Report back to the user
|
|
136
|
+
|
|
137
|
+
Tell them what you created in plain prose, naming the actual profiles you used:
|
|
138
|
+
|
|
139
|
+
> I've queued 4 tasks:
|
|
140
|
+
> - **T1** (`<profile-A>`): cost comparison
|
|
141
|
+
> - **T2** (`<profile-A>`): performance comparison, in parallel with T1
|
|
142
|
+
> - **T3** (`<profile-B>`): synthesizes T1 + T2 into a recommendation
|
|
143
|
+
> - **T4** (`<profile-C>`): turns T3 into a CTO memo
|
|
144
|
+
>
|
|
145
|
+
> The dispatcher will pick up T1 and T2 now. T3 starts when both finish. You'll get a gateway ping when T4 completes. Use the dashboard or `hermes kanban tail <id>` to follow along.
|
|
146
|
+
|
|
147
|
+
## Common patterns
|
|
148
|
+
|
|
149
|
+
**Fan-out + fan-in (research → synthesize):** N research-style cards with no parents, one synthesis card with all of them as parents.
|
|
150
|
+
|
|
151
|
+
**Parallel implementation + validation:** one implementer card makes the change while one explorer/researcher card verifies config, docs, or source mapping. A reviewer card can depend on both. Do not make the implementer own unrelated verification just because the user mentioned both in one sentence.
|
|
152
|
+
|
|
153
|
+
**Pipeline with gates:** `planner → implementer → reviewer`. Each stage's `parents=[previous_task]`. Reviewer blocks or completes; if reviewer blocks, the operator unblocks with feedback and respawns.
|
|
154
|
+
|
|
155
|
+
**Same-profile queue:** N tasks, all assigned to the same profile, no dependencies between them. Dispatcher serializes — that profile processes them in priority order, accumulating experience in its own memory.
|
|
156
|
+
|
|
157
|
+
**Human-in-the-loop:** Any task can `kanban_block()` to wait for input. Dispatcher respawns after `/unblock`. The comment thread carries the full context.
|
|
158
|
+
|
|
159
|
+
## Pitfalls
|
|
160
|
+
|
|
161
|
+
**Inventing profile names that don't exist.** The dispatcher silently fails to spawn unknown assignees — the card just sits in `ready` forever. Always assign to a profile from your Step 0 discovery; ask the user if you're unsure.
|
|
162
|
+
|
|
163
|
+
**Bundling independent lanes into one card.** If the user asks for two independent outcomes, create two cards. Example: "fix blockers and check model variants" is not one fixer task; create a fixer/engineer card for the fixes and an explorer/researcher card for the variant check, then optionally gate review on both.
|
|
164
|
+
|
|
165
|
+
**Over-linking because of wording.** "Finally check X" may still be parallel with implementation if X is static config, docs, or source discovery. Link it after implementation only when the check depends on the implementation result.
|
|
166
|
+
|
|
167
|
+
**Forgetting dependency links.** If the task graph says `research -> implement -> review`, do not create all tasks as independent ready cards. Use parent links so implement/review cannot run before their inputs exist.
|
|
168
|
+
|
|
169
|
+
**Reassignment vs. new task.** If a reviewer blocks with "needs changes," create a NEW task linked from the reviewer's task — don't re-run the same task with a stern look. The new task is assigned to the original implementer profile.
|
|
170
|
+
|
|
171
|
+
**Argument order for links.** `kanban_link(parent_id=..., child_id=...)` — parent first. Mixing them up demotes the wrong task to `todo`.
|
|
172
|
+
|
|
173
|
+
**Don't pre-create the whole graph if the shape depends on intermediate findings.** If T3's structure depends on what T1 and T2 find, let T3 exist as a "synthesize findings" task whose own first step is to read parent handoffs and plan the rest. Orchestrators can spawn orchestrators.
|
|
174
|
+
|
|
175
|
+
**Tenant inheritance.** If `HERMES_TENANT` is set in your env, pass `tenant=os.environ.get("HERMES_TENANT")` on every `kanban_create` call so child tasks stay in the same namespace.
|
|
176
|
+
|
|
177
|
+
## Goal-mode cards (persistent workers)
|
|
178
|
+
|
|
179
|
+
By default a dispatched worker gets **one shot** at its card: it does its work, calls `kanban_complete`/`kanban_block`, and exits. For open-ended cards where one turn rarely finishes the job, pass `goal_mode=True` to wrap that worker in a Ralph-style goal loop — the same engine behind the `/goal` slash command:
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
kanban_create(
|
|
183
|
+
title="Translate the full docs site to French",
|
|
184
|
+
body="Acceptance: every page translated, no English left, links intact.",
|
|
185
|
+
assignee="<translator-profile>",
|
|
186
|
+
goal_mode=True, # judge re-checks the card after each turn
|
|
187
|
+
goal_max_turns=15, # optional budget (default 20)
|
|
188
|
+
)["task_id"]
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
How it behaves:
|
|
192
|
+
- After each worker turn, an auxiliary judge evaluates the worker's response against the card's **title + body** (treated as the acceptance criteria).
|
|
193
|
+
- Not done + budget remains → the worker keeps going **in the same session** (full context retained — not a fresh respawn).
|
|
194
|
+
- Worker calls `kanban_complete`/`kanban_block` itself → loop stops, normal lifecycle.
|
|
195
|
+
- Budget exhausted without completion → the card is **blocked** for human review (sticky), never a silent exit.
|
|
196
|
+
|
|
197
|
+
When to use it: long, multi-step, or "keep going until X is true" cards. When NOT to: cheap one-shot cards (translation of a single string, a quick lookup) — the judge overhead isn't worth it, and the dispatcher's existing retry/circuit-breaker already handles transient worker failures.
|
|
198
|
+
|
|
199
|
+
Write the body as **explicit acceptance criteria** — the judge is only as good as the goal text. "Translate the README" is weaker than "Translate every section of the README to French; no English sentences remain."
|
|
200
|
+
|
|
201
|
+
## Recovering stuck workers
|
|
202
|
+
|
|
203
|
+
When a worker profile keeps crashing, hallucinating, or getting blocked by its own mistakes (usually: wrong model, missing skill, broken credential), the kanban dashboard flags the task with a ⚠ badge and opens a **Recovery** section in the drawer. Three primary actions:
|
|
204
|
+
|
|
205
|
+
1. **Reclaim** (or `hermes kanban reclaim <task_id>`) — abort the running worker immediately and reset the task to `ready`. The existing claim TTL is ~15 min; this is the fast path out.
|
|
206
|
+
2. **Reassign** (or `hermes kanban reassign <task_id> <new-profile> --reclaim`) — switch the task to a different profile (one that exists on this setup) and let the dispatcher pick it up with a fresh worker.
|
|
207
|
+
3. **Change profile model** — the dashboard prints a copy-paste hint for `hermes -p <profile> model` since profile config lives on disk; edit it in a terminal, then Reclaim to retry with the new model.
|
|
208
|
+
|
|
209
|
+
Hallucination warnings appear on tasks where a worker's `kanban_complete(created_cards=[...])` claim included card ids that don't exist or weren't created by the worker's profile (the gate blocks the completion), or where the free-form summary references `t_<hex>` ids that don't resolve (advisory prose scan, non-blocking). Both produce audit events that persist even after recovery actions — the trail stays for debugging.
|