mirror of https://github.com/khodges42/nightShift.git synced 2026-06-14 18:18:36 +00:00

K. Hodges 957dc7d25b Ollama backend support, experiment metadata and prompt snapshots, stronger command execution controls, refreshed docs/examples, a read-only Flask dashboard, and a runnable quickstart Lisp project.

2026-05-17 01:39:44 -07:00

6.2 KiB

Raw Blame History

NightShift Quickstart

This guide runs the current MVP with safe example files.

1. Install for Development

pip install -e .

Or run the module directly:

python -m nightshift.cli --help

2. Create Starter Files

From a project directory:

nightshift init

This creates:

nightshift.yaml
tasks.md
agents/

Existing starter files are not overwritten unless you pass --force.

3. Validate

nightshift validate

Validation checks config structure, task parsing, prompt files, scoped paths, and command safety.

4. Run One Task

Run the next incomplete task:

nightshift run

Run a specific task:

nightshift run --task TASK-001

5. Review Artifacts

After a run, inspect:

.nightshift/runs/<run-id>/

Useful files:

run-summary.md
config.snapshot.yaml
tasks/TASK-001/task.md
tasks/TASK-001/context.md
tasks/TASK-001/plan.md
tasks/TASK-001/test-output.txt
tasks/TASK-001/stage-results.md
tasks/TASK-001/context-out.md
tasks/TASK-001/final-notes.md

Example Templates

Example run files are available in templates/. They are safe starter examples and use command-backed fake agents.

The repository also includes a complete sample target project:

examples/quickstart-lisp/

Copy that directory elsewhere if you want to test NightShift against a multi-task project.

Quickstart Test Project

A good first real target project is a tiny Lisp interpreter in Python. It is small enough to review, but it naturally breaks into multiple tasks that test NightShift's planning, implementation, command execution, artifacts, reports, and dependency handling.

If you do not want a language interpreter, use a small config parser or markdown todo CLI instead. The Lisp interpreter is the recommended default because it has clear incremental milestones and simple tests.

1. Create a Target Project

mkdir tiny-lisp
cd tiny-lisp
mkdir agents tests
touch lisp.py tests/test_lisp.py

2. Add `nightshift.yaml`

project:
  name: tiny-lisp
  root: .
  task_file: tasks.md
  artifact_dir: .nightshift

safety:
  require_clean_worktree: false
  scoped_paths:
    - .
  allowed_commands:
    - python -m unittest discover -v
  forbidden_commands:
    - rm -rf
    - git push
    - curl | bash

agents:
  planner:
    backend: command
    command: echo
    system_prompt: agents/planner.md

  implementer:
    backend: command
    command: echo
    system_prompt: agents/implementer.md

  reviewer:
    backend: command
    command: python -c "print('status: pass'); print('reason: quickstart reviewer accepted artifacts')"
    system_prompt: agents/reviewer.md

pipeline:
  max_task_retries: 1
  continue_on_task_failure: false
  stages:
    - id: plan
      type: agent
      agent: planner
      output: plan.md

    - id: implement
      type: agent
      agent: implementer
      output: implementation-log.md

    - id: test
      type: command
      commands:
        - python -m unittest discover -v
      output: test-output.txt

    - id: review
      type: agent_review
      agent: reviewer
      on_fail: implement
      output: review.md

    - id: summarize
      type: summarize
      output: final-notes.md

This uses fake command agents so the pipeline is safe and deterministic. Replace command: echo later with your real local agent wrapper.

3. Add `tasks.md`

# Tasks

- [ ] TASK-001: Parse Lisp expressions

Description:
Implement tokenization and parsing for a tiny Lisp subset.

Acceptance Criteria:
- Parses numbers
- Parses symbols
- Parses nested lists
- Raises useful errors for unbalanced parentheses
- Includes unit tests

- [ ] TASK-002: Evaluate arithmetic forms

Dependencies:
- TASK-001

Description:
Evaluate parsed arithmetic expressions.

Acceptance Criteria:
- Supports `+`, `-`, `*`, and `/`
- Evaluates nested arithmetic
- Includes unit tests

- [ ] TASK-003: Add variables and definitions

Dependencies:
- TASK-002

Description:
Add an environment and support variable lookup and definitions.

Acceptance Criteria:
- Supports symbol lookup
- Supports `(define name value)`
- Keeps environment behavior tested

- [ ] TASK-004: Add conditionals

Dependencies:
- TASK-003

Description:
Implement simple truthiness and `if` expressions.

Acceptance Criteria:
- Supports `(if condition then else)`
- Handles false-like values consistently
- Includes tests for both branches

4. Add Prompt Files

agents/planner.md:

You are the planning agent. Create a small, conservative plan for the task.
Do not write code. Include files to edit, tests to add, and risks.

agents/implementer.md:

You are the implementation agent. Implement the smallest correct change.
Preserve existing behavior and include tests.

agents/reviewer.md:

You are the review agent. Decide whether the task should pass, retry, or fail.

Output:
status: pass | fail | retry | escalate
reason: <short explanation>
next_stage: <optional stage id>
context_update: <compact useful note>

5. Add an Initial Passing Test File

# tests/test_lisp.py
import unittest


class SmokeTests(unittest.TestCase):
    def test_smoke(self):
        self.assertTrue(True)


if __name__ == "__main__":
    unittest.main()

6. Validate and Run

nightshift validate
nightshift status
nightshift run --task TASK-001

Run all currently runnable tasks:

nightshift run --all

Because the example uses fake agents, it will not actually implement the Lisp interpreter by itself. It is meant to verify the pipeline, dependency handling, reports, and artifacts before you connect a real command-backed agent.

7. Review Artifacts