STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► NOTE                                       ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:note — Quick Note Capture

You are running the note skill. Your job is zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.

This skill runs inline — no Task, no AskUserQuestion, no Bash.

References

references/ui-brand.md — Status symbols, banners, formatting for note display output

Storage Format

Notes are stored as individual markdown files in a notes directory:

Project scope: .planning/notes/{YYYY-MM-DD}-{slug}.md — used when .planning/ directory exists in cwd
Global scope: ~/.claude/notes/{YYYY-MM-DD}-{slug}.md — used as fallback when no .planning/, or when --global flag is present

Each note file has this format:

---
date: "YYYY-MM-DD HH:mm"
promoted: false
---

{note text verbatim}

--global flag: Strip --global from anywhere in $ARGUMENTS before parsing. When present, force global scope regardless of whether .planning/ exists.

Important: Do NOT create .planning/ if it doesn't exist. If there's no .planning/ directory, fall back to global scope silently.

Subcommand Parsing

Parse $ARGUMENTS after stripping --global:

Condition	Subcommand
Arguments are exactly `list` (case-insensitive)	list
Arguments are exactly `promote <N>` where N is a number	promote
Arguments are empty (no text at all)	list
Anything else	append (the text IS the note)

Critical: list is only a subcommand when it's the ENTIRE argument. /pbr:note list of groceries saves a note with text "list of groceries". Same for promote — only a subcommand when followed by exactly one number.

Subcommand: append

Create a timestamped note file in the target directory.

Steps

Determine scope (project or global) per Storage Format above
Ensure the notes directory exists (.planning/notes/ or ~/.claude/notes/)
Generate slug via CLI:
```
pbr-tools slug-generate "{note text}"
```
Parse the JSON output to get the slug field.
Generate filename: {YYYY-MM-DD}-{slug}.md
- If a file with that name already exists, append -2, -3, etc.
Write the file with frontmatter and note text (see Storage Format)
Confirm with exactly one line: Noted ({scope}): {note text}
- Where {scope} is "project" or "global"

Constraints

Never modify the note text — capture verbatim, including typos
Never ask questions — just write and confirm
Timestamp format: Use local time, YYYY-MM-DD HH:mm (24-hour, no seconds)

Subcommand: list

Show notes from both project and global scopes.

Steps

Glob .planning/notes/*.md (if directory exists) — these are "project" notes
Glob ~/.claude/notes/*.md (if directory exists) — these are "global" notes
For each file, read frontmatter to get date and promoted status
Exclude files where promoted: true from active counts (but still show them, dimmed)
Sort by date, number all active entries sequentially starting at 1
If total active entries > 20, show only the last 10 with a note about how many were omitted

Display Format

Notes:

Project (.planning/notes/):
  1. [2026-02-08 14:32] refactor the hook system to support async validators
  2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
  3. [2026-02-08 15:10] consider adding a --dry-run flag to build

Global (~/.claude/notes/):
  4. [2026-02-08 10:00] cross-project idea about shared config

{count} active note(s). Use `/pbr:note promote <N>` to convert to a todo.

If a scope has no directory or no entries, show: (no notes)

Subcommand: promote

Convert a note into a todo file.

Steps

Run the list logic to build the numbered index (both scopes)
Find entry N from the numbered list
If N is invalid or refers to an already-promoted note, tell the user and stop
Requires .planning/ directory — if it doesn't exist, warn: "Todos require a Plan-Build-Run project. Run /pbr:new-project to initialize one, or use /pbr:add-todo in an existing project."
Ensure .planning/todos/pending/ directory exists
Generate todo ID: {NNN}-{slug} where NNN is the next sequential number (scan both .planning/todos/pending/ and .planning/todos/done/ for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is generated via CLI:
```
pbr-tools slug-generate "{note text}"
```
Parse the JSON output to get the slug field.
Extract the note text from the source file (body after frontmatter)
Create .planning/todos/pending/{id}.md:

---
title: "{note text}"
status: pending
priority: P2
source: "promoted from /pbr:note"
created: {YYYY-MM-DD}
theme: general
---

## Goal

{note text}

## Context

Promoted from quick note captured on {original date}.

## Acceptance Criteria

- [ ] {primary criterion derived from note text}

Mark the source note file as promoted: update its frontmatter to promoted: true
Confirm: Promoted note {N} to todo {id}: {note text}

Edge Cases

"list" as note text: /pbr:note list of things → saves note "list of things" (subcommand only when list is the entire arg)
No .planning/: Falls back to global ~/.claude/notes/ — works in any directory
Promote without project: Warns that todos require .planning/, suggests /pbr:new-project
Large files: list shows last 10 when >20 active entries
Duplicate slugs: Append -2, -3 etc. to filename if slug already used on same date
--global position: Stripped from anywhere — --global my idea and my idea --global both save "my idea" globally
Promote already-promoted: Tell user "Note {N} is already promoted" and stop
Empty note text after stripping flags: Treat as list subcommand

Error Handling

Reference: skills/shared/error-reporting.md for branded error output patterns.

Write failure

If the Write tool fails (permissions, disk full, etc.), display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Failed to write note to {target_file}.

**To fix:** Check file permissions or disk space.

Promote target not found

If the specified note index is invalid, display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Note {N} not found. Valid range: 1-{max}.

**To fix:** Run `/pbr:note list` to see available notes.

Reference: skills/shared/commit-planning-docs.md -- if planning.commit_docs is true, commit the note file.

Anti-Patterns

DO NOT ask questions on append — just write and confirm
DO NOT modify note text — capture verbatim
DO NOT use Task, AskUserQuestion, or Bash
DO NOT create .planning/ if it doesn't exist — fall back to global
DO NOT number promoted notes in the active count (but still display them)
DO NOT over-format the confirmation — one line is enough
DO NOT use a flat NOTES.md file — always use individual files in notes directory