JupyterManager/docs/AGENT_PROMPT.md

# Agent Prompt for Jupyter Lifecycle Alignment

Use this prompt when instructing a coding agent (Claude, Codex, etc.) to add or fix Jupyter lifecycle management in a client project.

---

## The Prompt

```
This project needs Jupyter lifecycle management aligned with the JupyterManager
cross-project specification.

Reference implementation: https://github.com/saymrwulf/JupyterManager
Spec: docs/LIFECYCLE_SPEC.md in that repo.

Key requirements:
1. scripts/app.sh with: bootstrap, start, stop, restart, status, logs
2. Isolated Jupyter dirs (JUPYTER_CONFIG_DIR, DATA_DIR, RUNTIME_DIR, IPYTHONDIR)
   all under the project root — set as env vars before any jupyter command
3. Kernel installed with --sys-prefix (not --user)
4. Auto port allocation (scan 8888-8899 for free port)
5. PID file at .logs/jupyter.pid
6. Background mode with nohup, foreground mode with exec
7. Graceful stop (SIGTERM → wait → SIGKILL fallback)
8. Orphan detection in status command
9. Stale runtime JSON cleanup on start/status
10. All isolation dirs in .gitignore

The cross-project manager (jupyter-hub) expects:
- PID files at .logs/jupyter.pid or .run/jupyter.pid
- Runtime JSON at .jupyter_runtime/jpserver-*.json
- scripts/app.sh stop to be callable from any working directory

Do NOT:
- Use --user for kernel installation
- Hardcode port 8888
- Skip the startup wait loop
- Leave out foreground mode
- Forget .gitignore entries for isolation dirs

A reference app.sh implementation exists at:
  https://github.com/saymrwulf/autoresearch-quantum/blob/master/scripts/app.sh
```
Initial commit: jupyter-hub cross-project Jupyter manager CLI tool that discovers and manages JupyterLab instances across multiple projects. Prevents port conflicts, finds orphan processes, provides unified status and stop-all functionality. Includes: - bin/jupyter-hub: the CLI (status, ports, stop-all, orphans, which, config) - config/defaults.sh: default scan dirs and port range - docs/LIFECYCLE_SPEC.md: client project requirements - docs/AGENT_PROMPT.md: prompt for coding agents to align projects - install.sh: symlink installer to ~/bin - tests/test_jupyter_hub.sh: 15 functional tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-04-16 07:07:43 +00:00			`# Agent Prompt for Jupyter Lifecycle Alignment`

			`Use this prompt when instructing a coding agent (Claude, Codex, etc.) to add or fix Jupyter lifecycle management in a client project.`

			`---`

			`## The Prompt`

			```
			`This project needs Jupyter lifecycle management aligned with the JupyterManager`
			`cross-project specification.`

			`Reference implementation: https://github.com/saymrwulf/JupyterManager`
			`Spec: docs/LIFECYCLE_SPEC.md in that repo.`

			`Key requirements:`
			`1. scripts/app.sh with: bootstrap, start, stop, restart, status, logs`
			`2. Isolated Jupyter dirs (JUPYTER_CONFIG_DIR, DATA_DIR, RUNTIME_DIR, IPYTHONDIR)`
			`all under the project root — set as env vars before any jupyter command`
			`3. Kernel installed with --sys-prefix (not --user)`
			`4. Auto port allocation (scan 8888-8899 for free port)`
			`5. PID file at .logs/jupyter.pid`
			`6. Background mode with nohup, foreground mode with exec`
			`7. Graceful stop (SIGTERM → wait → SIGKILL fallback)`
			`8. Orphan detection in status command`
			`9. Stale runtime JSON cleanup on start/status`
			`10. All isolation dirs in .gitignore`

			`The cross-project manager (jupyter-hub) expects:`
			`- PID files at .logs/jupyter.pid or .run/jupyter.pid`
			`- Runtime JSON at .jupyter_runtime/jpserver-*.json`
			`- scripts/app.sh stop to be callable from any working directory`

			`Do NOT:`
			`- Use --user for kernel installation`
			`- Hardcode port 8888`
			`- Skip the startup wait loop`
			`- Leave out foreground mode`
			`- Forget .gitignore entries for isolation dirs`

			`A reference app.sh implementation exists at:`
			`https://github.com/saymrwulf/autoresearch-quantum/blob/master/scripts/app.sh`
			```