mirror of
https://github.com/khodges42/nightShift.git
synced 2026-06-14 18:18:36 +00:00
141 lines
3.9 KiB
Markdown
141 lines
3.9 KiB
Markdown
# Tutorial 03: DeadDrop With Fixed Tests And Telemetry
|
|
|
|
This tutorial uses the `tutorial-deaddrop` template: a small Flask snippet sharing utility designed for deterministic NightShift orchestration tests.
|
|
|
|
It is intentionally simpler than the imageboard tutorial. There are no uploads, thumbnails, sessions, or moderation queues. The work is ordinary web-app behavior: snippet creation, viewing, listing, filtering, expiration handling, and simple HTML forms.
|
|
|
|
## What The Template Creates
|
|
|
|
Run this from a disposable parent directory:
|
|
|
|
```bash
|
|
nightshift init --template tutorial-deaddrop --root nightshift-deaddrop
|
|
cd nightshift-deaddrop
|
|
```
|
|
|
|
For an isolated local integration run, use the integration sandbox command from the NightShift repository root:
|
|
|
|
```bash
|
|
python -m nightshift.cli integ-run --template tutorial-deaddrop
|
|
```
|
|
|
|
To create, set up, validate, and run one task in a single command:
|
|
|
|
```bash
|
|
python -m nightshift.cli integ-test --template tutorial-deaddrop --task TASK-001
|
|
```
|
|
|
|
To create the sandbox and set up the Python project immediately:
|
|
|
|
```bash
|
|
python -m nightshift.cli integ-run --template tutorial-deaddrop --setup
|
|
```
|
|
|
|
Then set up the generated Python project:
|
|
|
|
```bash
|
|
python -m nightshift.cli integ-setup --project integ_runs/<timestamp>/project
|
|
```
|
|
|
|
`integ-setup` cannot activate the venv for your current shell. In PowerShell, activate it manually if you want plain `python` and `nightshift` to use the integration venv:
|
|
|
|
```powershell
|
|
integ_runs\<timestamp>\.venv\Scripts\Activate.ps1
|
|
```
|
|
|
|
The template creates:
|
|
|
|
```text
|
|
nightshift.yaml
|
|
.nightshift/
|
|
agents/
|
|
planner.md
|
|
test-writer.md
|
|
implementer.md
|
|
debugger.md
|
|
reviewer.md
|
|
tasks.md
|
|
src/
|
|
deaddrop_app/
|
|
templates/
|
|
tests/
|
|
pyproject.toml
|
|
README.md
|
|
```
|
|
|
|
The template includes a tiny Flask `create_app(database_path=None)` scaffold and fixed tests for each tutorial task. The default tutorial pipeline asks the implementation agent to make only the current task's deterministic tests pass before review.
|
|
|
|
## Prerequisites
|
|
|
|
Install NightShift from this repository:
|
|
|
|
```bash
|
|
python -m pip install -e .
|
|
```
|
|
|
|
Install target dependencies:
|
|
|
|
```bash
|
|
python -m pip install -e . pytest flask
|
|
```
|
|
|
|
Install and start Ollama, then pull the default DeadDrop model:
|
|
|
|
```bash
|
|
ollama pull qwen3-coder:30b
|
|
ollama list
|
|
```
|
|
|
|
NightShift uses Ollama's local HTTP API, normally at `http://localhost:11434`.
|
|
|
|
## Model
|
|
|
|
The default DeadDrop pipeline uses one strong local coder model:
|
|
|
|
- `qwen3-coder:30b`
|
|
|
|
NightShift records which agent/model handled each stage in `telemetry-summary.md`. Multi-candidate fallback belongs in a separate experiment template, not the default DeadDrop reliability harness.
|
|
|
|
## TDD Pipeline
|
|
|
|
The task pipeline runs in this shape:
|
|
|
|
```text
|
|
plan -> semantic_context -> context -> implement -> pytest -> review
|
|
```
|
|
|
|
The default template uses fixed task tests instead of model-generated tests. This keeps the tutorial focused on implementation and NightShift orchestration instead of letting a test-writing model invent an incompatible architecture.
|
|
|
|
## Task Plan
|
|
|
|
The template writes the full task list to `.nightshift/tasks.md`. A copy is included here as [tasks.md](tasks.md).
|
|
|
|
1. Snippet creation and viewing
|
|
2. Snippet metadata fields
|
|
3. Snippet listing and filtering
|
|
4. Expiration handling
|
|
5. HTML forms and templates
|
|
|
|
Run one task first:
|
|
|
|
```bash
|
|
python -m nightshift.cli validate
|
|
python -m nightshift.cli run --task TASK-001
|
|
python -m nightshift.cli what-happened
|
|
```
|
|
|
|
Then inspect:
|
|
|
|
```text
|
|
.nightshift/runs/<run-id>/devlog.md
|
|
.nightshift/runs/<run-id>/telemetry-summary.md
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/semantic-context.md
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/telemetry-summary.md
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/artifact-index.md
|
|
.nightshift/runs/<run-id>/tasks/TASK-001/test-output.txt
|
|
```
|
|
|
|
## Pipeline Reference
|
|
|
|
A copy of the template pipeline is included here as [nightshift.yaml](nightshift.yaml). The canonical runnable template lives under `nightshift/project_templates/tutorial-deaddrop/`.
|