kenn-forge-ephemeral-dev

# Kenn Forge Ephemeral Dev ## Core Rule Use `make dev-ephemeral` when the user wants a local kenn-forge dev stack without fixed ports or without mutating the normal config/database. Do not hand-roll separate `make dev` and `make frontend-dev` commands unless the user explicitly asks for manual process control. ## Workflow 1. Start the stack: ```sh make dev-ephemeral ``` Provider sync is disabled by default. Opt in only when fresh provider data is required: ```sh make dev-ephemeral ARGS="-sync" ``` 2. The default work directory is `tmp/dev-ephemeral`. Re-running the command while that stack is live prints the existing status instead of starting a duplicate stack. 3. For a separate concurrent run directory or explicit ports, pass `ARGS`: ```sh make dev-ephemeral ARGS="-work-dir tmp/my-run" make dev-ephemeral ARGS="-backend-port 19091 -frontend-port 15174 -mcp-port 19092" ``` 4. Use a fresh empty DB only when requested: ```sh make dev-ephemeral ARGS="-fresh-db" ``` ## Behavior Contract - The launcher starts both backend and frontend. - The backend disables provider sync by default; `-sync` explicitly enables it. - It writes a generated config at `<work-dir>/config.toml`. - MCP using the source default shares the ephemeral backend port. Enabled MCP uses a dedicated free port when `-mcp-port` is supplied or the source explicitly enables it or sets its own port. Status JSON reports `mcp_port` and `mcp_url` when MCP is enabled. - It copies the configured source SQLite DB by default into `<work-dir>/data/forge.db`. - It passes `KENN_FORGE_CONFIG=<work-dir>/config.toml` to both processes. - It passes `KENN_FORGE_API_URL=<backend-url>` to the frontend. - It writes typed status JSON at `<work-dir>/dev-ephemeral.json`. - `make dev-ephemeral-stop` without arguments stops the default `tmp/dev-ephemeral` stack. - The launcher is intentionally unsupported on Windows for now. ## Status JSON Read `<work-dir>/dev-ephemeral.json` when another tool or response needs process discovery: ```json { "pid": 1001, "backend_pid": 1002, "frontend_pid": 1003, "backend_port": 19091, "frontend_port": 15174, "mcp_port": 19092, "config_path": "tmp/my-run/config.toml", "data_dir": "tmp/my-run/data", "backend_url": "http://127.0.0.1:19091", "frontend_url": "http://127.0.0.1:15174", "mcp_url": "http://127.0.0.1:19092/mcp" } ``` Treat this as the source of truth for selected ports and PIDs instead of scraping terminal output. ## Verification For changes to the workflow or this skill, run: ```sh go test ./tools/devephemeral -shuffle=on make lint-check make help ``` Before claiming the stack is running, verify the status file exists and contains both child PIDs and both URLs.