Capture Workflows

Capture for ideas that surface mid-execution but don't yet belong to a milestone. Each of these commands is pure markdown CRUD, so capture is fast and cheap.

np:add-todo

Capture a pending todo. Writes a Markdown file at .nubos-pilot/todos/pending/YYYY-MM-DD-<slug>.md and bumps the pending_todos counter in STATE.md via the single-writer lock.

/np:add-todo "Investigate slow plan-checker pass on milestone 5"

Structure:

---
title_short: Investigate slow plan-checker pass on milestone 5
created: 2026-04-20T10:30:00Z
status: pending
---

Investigate slow plan-checker pass on milestone 5

The description is validated (≤ 500 chars, no YAML separator pattern) before any filesystem write. Duplicate DATE-SLUG collisions prompt via askuser (re-run / view / skip / rename).

np:note

Capture a free-form note. Two scopes:

• Project (default): writes .nubos-pilot/notes/YYYY-MM-DD-<slug>.md and commits to git.
• Global (--global): writes ~/.nubos-pilot/notes/YYYY-MM-DD-<slug>.md and never commits — intended for sensitive/cross-project content.

/np:note "Design idea: use a queue instead of a stack for the wave dispatcher"
/np:note --global "API token pattern for the staging environment"

Notes never bind to a unit-type. They are pure "I want to remember this" capture.

np:thread

Cross-session thread CRUD. Threads live at .nubos-pilot/threads/<slug>.md and persist a conversation context that survives across host CLI sessions.

/np:thread auth-migration         # create or resume

Two modes chosen by file presence:

• create — writes the thread with status: OPEN; one atomic docs(…): create thread commit.
• resume — bumps status: OPEN → IN_PROGRESS, refreshes last_resumed. No commit, so heartbeats don't add log noise.

Lifecycle: OPEN → IN_PROGRESS → RESOLVED. There is no close command by design. The user flips status: RESOLVED by hand when they consider the thread closed.

np:handoff-* (agent-to-agent handoffs)

Persistent, phase-independent notes exchanged between subagents. Use the handoff channel for cross-phase signals that don't belong in commit messages or frontmatter: an executor flagging a deliberate compromise for the verifier, or a researcher flagging a cross-milestone trap for future planners.

Files live under milestones/M<NNN>/handoffs/ (milestone-scoped, default) or top-level handoffs/ (project-global, no --milestone). Detailed schema and semantics in the artifact schemas.

handoff-write

Write one handoff. Required: --from, --to, --topic. Optional: --milestone, --slice, --task, --body, --body-file.

node .nubos-pilot/bin/np-tools.cjs handoff-write \
  --from np-executor \
  --to np-verifier \
  --topic "Feature flag hardcoded" \
  --milestone M001 --slice M001-S002 --task M001-S001-T0003 \
  --body "Config layer is pending — flag X is inlined in UserController."

Broadcast: --to "*". Returns JSON {id, path, filename, created_at}.

handoff-read <id>

Load one handoff as JSON, including the Markdown body and all frontmatter.

node .nubos-pilot/bin/np-tools.cjs handoff-read c209db90

handoff-list

Query handoffs. Filters:

Flag	Effect
--for AGENT	only entries addressed to AGENT (or broadcast *)
--milestone M<NNN>	milestone-scope only
--global	project-global only
--status STATUS	filter by open / read / acted / archived

Returns a JSON array, sorted by created_at ascending.

node .nubos-pilot/bin/np-tools.cjs handoff-list --for np-verifier --milestone M001 --status open

handoff-status <id> <new-status>

Update a handoff's status. Valid transitions: open → read → acted → archived. Mutation rewrites only the status: line.

node .nubos-pilot/bin/np-tools.cjs handoff-status c209db90 acted