Night Shift

SKILL.md

---
name: night-shift
version: 1.0.5
description: "Queue coding plans during the day, approve them, execute later in isolated worktrees, and inspect reports. Background agentic execution requires an explicitly configured non-interactive runner."
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["python3", "git"] },
        "optional":
          {
            "bins": ["agent", "cursor", "claude"],
            "env":
              [
                "OPENCLAW_WORKSPACE",
                "NIGHT_SHIFT_DATA_DIR",
                "NIGHT_SHIFT_MODEL",
                "CURSOR_CLI",
                "CURSOR_API_KEY",
                "TELEGRAM_BOT_TOKEN",
                "TELEGRAM_CHAT_ID",
                "NIGHT_SHIFT_CHAT_ID",
              ],
          },
        "capabilities":
          [
            "filesystem-read-write",
            "git-worktrees",
            "subprocess-execution",
            "optional-cursor-cli",
            "optional-claude-cli",
            "optional-telegram-notifications",
            "optional-model-provider-calls",
          ],
      },
  }
---

# Night Shift

Night Shift is an autonomous queued-execution skill for engineering work.

Instead of asking the agent to do one large coding task immediately, you build a queue of plans, review or approve them, then run them in a controlled batch window. Each plan is split into phases, executed in isolation, verified, checkpointed, and summarized in a report.

**Mental model:**
- Daytime: create and refine plans
- Before execution: approve what is safe to run
- Execution window: Night Shift runs plans phase by phase
- Morning: inspect results, merge, retry, or continue

This is useful when you want:
- deferred execution instead of immediate chat-time work
- safer batching for multi-step changes
- isolated worktrees per plan
- retry and checkpoint behavior
- a written report after execution

---

## When to Use

Use Night Shift when the user asks for things like:
- “good night”
- “queue this for later”
- “plan add …”
- “run these approved plans overnight”
- “night shift status”
- “show my morning report”
- “retry plan #3”
- “merge that finished plan”

Prefer Night Shift over immediate execution when:
- the work is multi-phase
- the task needs isolation from the main repo state
- the user wants review/approval before execution
- the work may take a long time
- you want a queue of tasks rather than one interactive run

Do **not** use Night Shift for:
- tiny one-off edits better handled immediately
- high-risk production actions without review
- tasks that require constant human decisions mid-run
- public/external actions that should be explicitly approved in the moment

---

## Core Concepts

### 1. Plan
A plan is the unit of queued work. It includes:
- title
- optional description
- optional repo URL
- priority
- token/time budget hints
- generated phases
- status and execution metadata

### 2. Phase
Each plan is split into phases. A phase has:
- a title
- a prompt/instruction
- an execution method
- verification settings
- retry state
- status

### 3. Execution Method
Each phase chooses one of several execution methods:
- `shell`
- `cursor`
- `claude-code`
- `subagent`

This lets the framework mix deterministic shell work with agentic coding work.

### 4. Worktree Isolation
Each plan runs in its own git worktree under `data/night-shift/worktrees/`.

That means Night Shift can:
- avoid trampling the main branch
- keep plan-specific diffs separate
- retry or inspect work in isolation
- support safer merge/rollback flows

### 5. Verification
Phases can be checked after execution using one of several verification modes, including:
- `files_exist`
- `check_git_diff`
- `run_tests`
- `lint_check`
- `smoke_test`
- `import_check`
- `integration_check`
- `snapshot_diff`
- `none`

### 6. Reporting
After execution, Night Shift writes a report so the next interaction starts from evidence instead of guesswork.

---

## Typical Workflow

### During the day
1. Add one or more plans
2. Review phases
3. Edit prompts or priorities if needed
4. Approve the plans that are safe to run

### At execution time
5. Start Night Shift
6. It acquires a lock, checks budgets, creates worktrees, and executes phases
7. It verifies each phase, checkpoints progress, records failures, and logs results

### After execution
8. Read the report
9. Inspect worktrees or diffs
10. Merge successful work, retry failed work, or queue follow-up plans

---

## User-Facing Commands

These are the command patterns the skill is designed around.

| Command | Purpose |
|---|---|
| `plan add <desc>` | Create a new plan with generated phases |
| `plan steal <url> <desc>` | Queue work derived from an external repo/project |
| `plan list [status]` | Show plans in the queue |
| `plan show #<id>` | Show full details for one plan |
| `plan approve #<id>` | Approve one plan |
| `plan approve all` | Approve all queued plans |
| `plan remove #<id>` | Remove a plan |
| `plan priority #<id> <level>` | Change priority |
| `plan edit #<id> phase <n> prompt <text>` | Refine a phase prompt |
| `good night` | Start execution of approved plans |
| `night shift status` | Show current state |
| `night shift stop` | Request stop / halt execution |
| `night shift dry-run` | Preview what would execute |
| `morning` | Show the latest execution report |
| `night shift merge #<id>` | Merge completed plan results |
| `night shift inspect #<id>` | Inspect outputs/worktree |
| `night shift retry #<id>` | Retry a failed or partial plan |

If your host agent uses a different natural-language wrapper, preserve the same intent and lifecycle.

---

## Architecture

Night Shift is split into a few major parts.

### Queue and Models
- `models.py` — core plan/phase data models and enums
- `queue.py` — CRUD, queue index, plan storage, approvals, updates
- `phase_generator.py` — creates initial phases from plan input

### Execution Engine
- `executor.py` — main run loop, orchestration, locking, budget checks, reporting
- `phase_runner.py` — executes individual phases using the chosen method
- `subagent_runner.py` — helper for subagent-based execution

### Safety and Recovery
- `verifier.py` — phase verification logic
- `checkpoint.py` — save/resume progress
- `failure_memory.py` — track known failures and avoid blind repetition
- `lock.py` — prevent overlapping runs
- `budget.py` — per-phase/per-plan/night budget tracking
- `memory_guard.py` — watchdog for memory/process hygiene

### Repo / Git Operations
- `git_manager.py` — worktree setup, commit/reset helpers

### Visibility and Operations
- `reporter.py` — morning-style summaries
- `monitor.py` — notifications and health checks
- `watchdog.py` — execution monitoring
- `status.py` — status helpers
- `cron_trigger.sh` / `ns-control.sh` — optional shell wrappers

### Optional Extensions
The `bmad_*.py` files are advanced helpers for richer planning/PRD flows. They are **not required** for the core Night Shift lifecycle.

---

## Execution Flow

A typical run looks like this:

1. **Preflight**
   - confirm no conflicting lock
   - load queue
   - check for approved plans
   - initialize budget / logs / monitors

2. **Plan selection**
   - choose approved plans in queue order / priority order

3. **Per-plan setup**
   - create or prepare isolated worktree
   - load checkpoint if resuming

4. **Per-phase execution**
   - build phase prompt
   - dispatch via the selected execution method
   - capture output, status, timing, and any token/cost metadata available

5. **Verification**
   - run configured verification step
   - mark success/failure
   - record failure memory if relevant

6. **Persistence**
   - update plan JSON
   - update queue index
   - save checkpoint/logs

7. **Completion**
   - finalize plan status
   - generate report
   - release lock

---

## Safety Model

Night Shift is designed to be agentic, but not reckless.

### Safety features
- **approval gate** before execution
- **worktree isolation** per plan
- **execution lock** to prevent overlapping runs
- **phase-by-phase progression** instead of one giant opaque run
- **verification hooks** after phases
- **checkpointing** for resumes/recovery
- **failure memory** to reduce repeated mistakes
- **budget caps** across phase/plan/night scopes
- **watchdog/monitoring** support

### What this protects against
- clobbering the main branch
- executing multiple Night Shift loops at once
- losing progress on interruption
- repeating the same failing step forever
- oversized unattended execution sessions

### What it does **not** guarantee
- perfect code quality
- correct architectural judgment for every task
- safe production deployment by default
- zero hallucination from external coding models

You still need sensible approval and review.

### Trust, permissions, and security scanners

Night Shift may be flagged by automated scanners because it intentionally includes operational automation primitives:

- shell wrappers (`cron_trigger.sh`, `ns-control.sh`, `claude-wrapper.sh`)
- Python subprocess execution for approved phases
- git worktree, commit, reset, and diff helpers
- optional Cursor CLI / Claude Code / subagent dispatch
- optional Telegram notification support

These are expected for an unattended coding workflow, but they deserve review before use. Night Shift does **not** bundle private keys, hidden credentials, miners, persistence malware, or background network beacons. It only uses credentials and CLIs already available in the host environment.

Before running it in a new workspace:

1. Review queued plans and phase prompts before approval.
2. Run `night shift dry-run` first when available.
3. Start with a disposable test repo or branch.
4. Keep production deploys as explicit manual steps unless you intentionally add deploy phases.
5. Inspect diffs/reports before merging completed work.

For non-interactive ClawHub installs, some registries may require `--force` after scanner warnings. Treat that as a prompt to review the code, not as a failure signal.

---

## Storage Layout

Night Shift stores runtime state under:

```text
data/night-shift/
├── queue.json
├── plans/
├── worktrees/
├── execution/
├── reports/
├── failure-memory.json
├── budget.json
└── execution.log
```

### Important files
- `queue.json` — lightweight queue index
- `plans/*.json` — full plan records
- `worktrees/<plan_id>/` — isolated git worktree per plan
- `failure-memory.json` — prior failed step fingerprints
- `budget.json` — current budget tracking
- `execution.log` — main execution log

---

## Environment Variables

Night Shift now supports portable configuration instead of relying on hardcoded local paths.

### Core
- `OPENCLAW_WORKSPACE` — override workspace root
- `NIGHT_SHIFT_MODEL` — preferred model hint for model-driven helpers
- `CURSOR_CLI` — explicit path to Cursor CLI / `agent` binary

### Notifications
- `NIGHT_SHIFT_CHAT_ID` — target chat for Night Shift notifications
- `TELEGRAM_CHAT_ID` — fallback notification target
- `TELEGRAM_BOT_TOKEN` — Telegram Bot token for notifications

### Execution environment
Night Shift also inherits normal environment from the host runtime, including anything needed by:
- git
- Python
- shell commands
- coding harnesses / subagents

If a specific execution method requires additional auth or binaries, document that at the host level.

---

## Prerequisites

### Required
- Python 3
- git
- workspace write access
- ability to create and modify files in `data/night-shift/`
- a host environment that can run shell commands and Python scripts

### Optional but useful
- Cursor CLI / agent binary for `cursor` execution
- Claude Code for `claude-code` execution
- subagent support for delegated runs
- Telegram bot setup for notifications

### Strongly recommended
- run inside a git-backed workspace
- use approval before unattended execution
- keep tests/lint scripts working in the target repo

---

## Examples

### Example 1 — queue a feature for later
User intent:
> Add OAuth login to the app, but do it overnight.

Night Shift flow:
1. `plan add add OAuth login to the app`
2. inspect generated phases
3. `plan approve #<id>`
4. later: `good night`

### Example 2 — multiple plans in one batch
User intent:
> Queue three fixes now, run them all tonight.

Flow:
1. add three plans
2. set priorities as needed
3. approve the safe ones
4. run Night Shift
5. read the morning report

### Example 3 — dry run before execution
User intent:
> Show me what would run tonight.

Flow:
- `night shift dry-run`

### Example 4 — retry a failed plan
User intent:
> Retry the failed parser plan.

Flow:
- inspect plan/report
- refine the phase prompt if needed
- `night shift retry #<id>`

### Example 5 — inspect before merge
User intent:
> Show me what Night Shift changed before we merge.

Flow:
- `night shift inspect #<id>`
- review diff/worktree/tests
- `night shift merge #<id>` when satisfied

---

## How to Operate the Skill Well

### Good plan inputs
Night Shift works best when the plan title/description is concrete.

Better:
- “Add retry logic to payment webhooks and verify with integration tests”
- “Refactor dashboard query caching and run frontend smoke tests”

Worse:
- “make it better”
- “fix the app somehow”

### Good approval policy
Approve unattended runs when:
- the repo is in a sane state
- the task is scoped
- verification exists
- you can tolerate isolated failures

Avoid approval when:
- the task is ambiguous
- the run might touch production systems directly
- the work needs live stakeholder decisions

### Good execution method selection
Use:
- `shell` for deterministic scripted work
- `cursor` / `claude-code` for coding-heavy phases
- `subagent` for delegated structured work

---

## Limitations

Be honest about these.

- It is not a general scheduler for arbitrary business processes.
- It is optimized for engineering work in a writable workspace.
- Quality depends heavily on phase quality and verification quality.
- If the underlying coding harness is weak or unavailable, outcomes degrade.
- Worktree-based isolation assumes the repo supports normal git operations.
- Some wrapper scripts and helpers are host-environment dependent.
- Long unattended runs still need human review before high-trust deployment.

---

## Troubleshooting

### “No approved plans found”
Approve at least one plan before starting execution.

### “Night Shift already running”
A lock file or active run exists. Inspect status before forcing a restart.

### “Worktree creation failed”
Check:
- git repo health
- branch/worktree permissions
- existing conflicting worktrees

### “Phase keeps failing”
- inspect the plan’s phase prompt
- review verification settings
- check failure memory / logs
- reduce scope and retry

### “Notifications are not sent”
Check notification env vars:
- `TELEGRAM_BOT_TOKEN`
- `NIGHT_SHIFT_CHAT_ID` or `TELEGRAM_CHAT_ID`

### “Cursor / Claude execution not found”
Set the expected binary path explicitly or install the required tool:
- `CURSOR_CLI`
- whichever CLI your host maps to `claude-code`

### “Execution stopped midway”
Inspect checkpoints, report output, logs, and plan status. Resume/retry instead of starting from scratch blindly.

---

## Publishing Notes

Night Shift is publishable as a **power-user engineering skill**.

Its strongest differentiators are:
- queued plan lifecycle
- isolated worktrees
- phase verification
- checkpointing and retry behavior
- morning-report workflow

Its biggest adoption caveats are:
- requires a repo-aware writable environment
- works best with supporting CLIs/tools already installed
- more operational than a simple one-file prompt skill

That is fine. Don’t oversell it as “plug-and-play for everyone.” Sell it as a serious autonomous coding workflow for advanced users.

---

## Files

Core engine files in `scripts/` include:
- `models.py`
- `queue.py`
- `phase_generator.py`
- `executor.py`
- `phase_runner.py`
- `verifier.py`
- `checkpoint.py`
- `failure_memory.py`
- `budget.py`
- `git_manager.py`
- `lock.py`
- `reporter.py`
- `monitor.py`
- `watchdog.py`
- `subagent_runner.py`
- `memory_guard.py`

Optional/advanced helpers:
- `bmad_batch.py`
- `bmad_context.py`
- `bmad_guardrails.py`
- `bmad_phases.py`
- `bmad_prd_evolve.py`
- `bmad_queue.py`
- `bmad_rollback.py`

Shell helpers:
- `cron_trigger.sh`
- `ns-control.sh`
- `claude-wrapper.sh`

---

## See Also

- `REFERENCE.md` — operational reference, setup notes, environment variables, and troubleshooting
- `scripts/test_queue.py` — queue behavior checks
- `scripts/test_integration.py` — end-to-end integration checks