Night Shift

Queue coding plans during the day, execute them later in a controlled overnight batch, and wake up to a report. Use when the user wants autonomous queued exe...

Security Scan

The skill's behavior largely matches a queued overnight code-execution tool, but there are important mismatches and several powerful capabilities (shell execution, git worktrees, cloning repos, subagent/model tasks, optional notifications) that are not declared in the registry metadata — review carefully before installing or running in a real workspace.

Purpose & Capability

The skill's name/description (queued overnight coding) aligns with its code: queue management, phase execution, worktree/gits operations, verification, and reporting. However the registry metadata claims no required env vars/binaries while the packaged docs and code clearly expect Python, git, and optional tool CLIs (Cursor/Claude CLI), plus env vars like OPENCLAW_WORKSPACE and NIGHT_SHIFT_MODEL. That mismatch between declared requirements and actual expectations is an incoherence that could lead to accidental privilege/IO on the host.

Instruction Scope

SKILL.md and REFERENCE.md instruct the agent to create git worktrees under data/night-shift/, run subprocesses (tests, linters, arbitrary shell phases), clone/steal repos, and enqueue subagent/model tasks. Those actions are consistent with the stated purpose but are broad — execution methods allow arbitrary shell commands and subagent/model-driven changes. The instructions also rely on environment variables and writable filesystem locations that were not declared in registry metadata.

Install Mechanism

There is no external install spec (no downloads or third-party installers) — the package is delivered as code and docs. That lowers install-time supply-chain risk compared with remote downloads. Still, the skill contains many executable scripts that will be run at runtime if you invoke the executor.

Credentials

Registry metadata lists no required env vars or credentials, but the code and REFERENCE.md use/expect OPENCLAW_WORKSPACE, NIGHT_SHIFT_MODEL, CURSOR_CLI and optional TELEGRAM_BOT_TOKEN / NIGHT_SHIFT_CHAT_ID. Those environment variables are appropriate for the features (workspace selection, model hinting, notifications) but their absence from the declared requirements is a documentation/permission mismatch — users may be surprised the skill can access the filesystem, run model-backed subagent tasks, and send notifications when tokens are present.

Persistence & Privilege

The skill runs as a user-level tool and does not request always:true or system-wide privileges; it writes state under a workspace (default data/night-shift/) and includes optional shell cron wrappers. That's expected for this function. Still, it will create/modify files and run subprocesses in the chosen workspace, and its phases can perform arbitrary repo changes if approved — do not run in a production repository without reviews and dry-runs.

What to consider before installing

This package implements a powerful autonomous execution framework that will: create git worktrees, run shell commands, clone/inspect repos, run tests/linters, call model/subagent tasks, and optionally send Telegram notifications. Those capabilities are coherent with the 'Night Shift' purpose, but the registry listing omits environment and runtime expectations (e.g., OPENCLAW_WORKSPACE, NIGHT_SHIFT_MODEL, CURSOR_CLI, TELEGRAM_*), which is a red flag — metadata should advertise these. Before installing: 1) Inspect the executor, night-runner, and any subagent enqueue functions to see how/when data is sent to external services. 2) Test in an isolated disposable workspace (set OPENCLAW_WORKSPACE to a throwaway path). 3) Run dry-run mode and review generated plans/worktrees before approving actual runs. 4) If you enable notifications, treat tokens as sensitive and verify message recipients. 5) Avoid running against production repos or systems until you’ve reviewed guardrails and performed small test runs. Ask the publisher to correct the metadata (declare required env vars and runtime prerequisites) and provide source/homepage/provenance if you need higher assurance.

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:

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