@sienklogic/plan-build-run 2.54.0 → 2.55.0

package/plugins/codex-pbr/skills/note/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: note
+description: "Zero-friction idea capture. Append, list, or promote notes to todos."
+---
+
+**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.
+
+---
+
+## 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:
+
+```markdown
+---
+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
+
+1. Determine scope (project or global) per Storage Format above
+2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see Storage Format)
+6. 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
+
+1. Glob `.planning/notes/*.md` (if directory exists) — these are "project" notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — these are "global" notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
+6. 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
+
+1. Run the **list** logic to build the numbered index (both scopes)
+2. Find entry N from the numbered list
+3. If N is invalid or refers to an already-promoted note, tell the user and stop
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a Plan-Build-Run project. Run `$pbr-begin` to initialize one, or use `$pbr-todo add` in an existing project."
+5. Ensure `.planning/todos/pending/` directory exists
+6. 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 the first ~4 meaningful words of the note text, lowercase, hyphen-separated
+7. Extract the note text from the source file (body after frontmatter)
+8. Create `.planning/todos/pending/{id}.md`:
+
+```yaml
+---
+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}
+```
+
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
+10. Confirm: `Promoted note {N} to todo {id}: {note text}`
+
+---
+
+## Edge Cases
+
+1. **"list" as note text**: `$pbr-note list of things` → saves note "list of things" (subcommand only when `list` is the entire arg)
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `$pbr-begin`
+4. **Large files**: `list` shows last 10 when >20 active entries
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
+6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
+7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
+8. **Empty note text after stripping flags**: Treat as `list` subcommand
+
+---
+
+## Error Handling
+
+### 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.
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** ask questions on append — just write and confirm
+2. **DO NOT** modify note text — capture verbatim
+3. **DO NOT** use Task, AskUserQuestion, or Bash
+4. **DO NOT** create `.planning/` if it doesn't exist — fall back to global
+5. **DO NOT** number promoted notes in the active count (but still display them)
+6. **DO NOT** over-format the confirmation — one line is enough
+7. **DO NOT** use a flat NOTES.md file — always use individual files in notes directory

package/plugins/codex-pbr/skills/pause/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: pause
+description: "Save your current session state for later resumption."
+---
+
+**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 ► PAUSING SESSION                            ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# $pbr-pause — Save Session State
+
+You are running the **pause** skill. Your job is to capture the current session state so the user can resume exactly where they left off in a future conversation. This creates a `.continue-here.md` handoff file with everything the next session needs.
+
+This skill runs **inline** (no Task delegation).
+
+---
+
+## Core Principle
+
+**Capture everything the next session needs to hit the ground running.** The resume skill will read this file cold, with zero prior context. Write it as if you're handing off to a colleague who has never seen this project.
+
+---
+
+## Flow
+
+### Step 1: Read Current State
+
+**Flag: `--checkpoint`**
+
+If `$ARGUMENTS` contains `--checkpoint`:
+- Perform a lightweight state dump without full session analysis
+- Write a minimal .continue-here.md with just: Position, git status, and suggested next action
+- Skip the detailed "Completed This Session" analysis (saves time)
+- Useful for quick manual checkpoints at any point
+
+Read the following files to understand where things stand:
+
+1. **`.planning/STATE.md`** — Current position
+   - Extract: current phase, current plan, progress, blockers
+   - If STATE.md doesn't exist, display:
+     ```
+     ╔══════════════════════════════════════════════════════════════╗
+     ║  ERROR                                                       ║
+     ╚══════════════════════════════════════════════════════════════╝
+
+     No Plan-Build-Run project state found. Nothing to pause.
+
+     **To fix:** Run `$pbr-begin` to initialize a project first.
+     ```
+
+2. **`.planning/config.json`** — Project settings
+   - Extract: project name, feature toggles
+
+3. **`.planning/ROADMAP.md`** — Phase overview
+   - Extract: current phase name, total phases
+
+### Step 2: Determine Current Phase Directory
+
+From STATE.md, get the current phase number and find its directory:
+1. List directories in `.planning/phases/`
+2. Match the current phase number to a directory
+3. If no match: use the most recently modified phase directory
+
+### Step 3: Gather Session State
+
+Collect the following information:
+
+#### Current Position
+- Phase number and name
+- Plan number (if mid-phase) or "between plans"
+- Status: in-progress, between-plans, between-phases, planning, reviewing
+
+#### Work Completed This Session
+Scan the current phase directory for SUMMARY.md files:
+- Read each SUMMARY.md frontmatter
+- Note which ones were created/modified recently (check timestamps or git log)
+- For recently completed plans: extract the plan name and brief status
+
+Also check git log for recent commits:
+```bash
+git log --oneline -20 --since="8 hours ago"
+```
+This gives a reasonable window for "this session's work."
+
+#### Remaining Work
+Scan for plan files without corresponding SUMMARY.md files:
+- These are plans that haven't been executed yet
+- List them with brief descriptions from their frontmatter
+
+#### Key Decisions Made
+Check for:
+- Recent CONTEXT.md files (from `$pbr-discuss`)
+- Key decisions in recent SUMMARY.md files
+- Any deviations noted in summaries
+
+#### Blockers or Concerns
+From STATE.md blockers section and any:
+- Failed verifications
+- Checkpoint stops
+- Active debug sessions
+- Unresolved issues noted in summaries
+
+#### What to Do Next
+Determine the logical next action (same routing logic as `$pbr-status`):
+- If mid-plan execution: "Continue building phase N"
+- If between plans in a phase: "Execute next plan (plan M)"
+- If phase complete, not reviewed: "Review phase N"
+- If phase reviewed, has gaps: "Fix gaps in phase N"
+- If phase complete: "Plan phase N+1"
+
+### Step 4: Write .continue-here.md
+
+**CRITICAL: Write pause state NOW before displaying confirmation. Do NOT skip this step.**
+
+Write the handoff file to the current phase directory:
+
+**Path:** `.planning/phases/{NN}-{phase-name}/.continue-here.md`
+
+**Content:**
+
+Read `skills/pause/templates/continue-here.md.tmpl` for the handoff file format. Fill in all `{variable}` placeholders with actual session data gathered in Steps 1-3.
+
+### Step 5: Update STATE.md
+
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body. Both must be updated atomically.**
+
+First, update the STATE.md YAML frontmatter:
+- Set `last_command: "$pbr-pause"`
+- Set `last_activity: {ISO datetime}`
+
+Then update the Session Continuity section of STATE.md:
+
+```markdown
+### Session Continuity
+
+**Last paused:** {ISO datetime}
+**Position:** Phase {N}, Plan {M}
+**Continue file:** .planning/phases/{NN}-{phase-name}/.continue-here.md
+**Next action:** {suggested command}
+```
+
+If the Session Continuity section doesn't exist, create it at the end of STATE.md.
+
+### Step 6: Commit as WIP
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config.json:
+
+```bash
+git add .planning/phases/{NN}-{phase-name}/.continue-here.md
+git add .planning/STATE.md
+git commit -m "wip(planning): save session state — phase {N} plan {M}"
+```
+
+**Commit rules:**
+- Always use `wip(planning):` prefix for pause commits
+- Include phase and plan numbers
+- Stage only the continue-here and STATE.md files
+- Do NOT stage any code changes (those should already be committed by the executor)
+
+### Step 7: Confirm to User
+
+Display branded confirmation:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SESSION SAVED ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
+
+Position: Phase {N} — {phase name}, Plan {M}
+Completed: {count} plans this session
+Remaining: {count} plans in this phase
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Resume in your next session**
+
+`$pbr-resume`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+```
+
+---
+
+## What Gets Captured
+
+| Information | Source | Why It Matters |
+|-------------|--------|---------------|
+| Phase + plan position | STATE.md | Know where to start |
+| Completed work | SUMMARY.md files, git log | Know what's already done |
+| Remaining work | Plan files without summaries | Know what's left |
+| Decisions | CONTEXT.md, SUMMARY.md | Preserve user preferences |
+| Blockers | STATE.md, verification files | Don't repeat failed approaches |
+| Next steps | Routing logic | Immediate action on resume |
+
+---
+
+## Edge Cases
+
+### No work was done this session
+- Still write the continue-here file
+- "Completed This Session" section says: "No plans completed (discussion/planning only)"
+- Capture any decisions or context from the conversation
+
+### Multiple phases were worked on
+- Write .continue-here.md in the MOST RECENT phase directory
+- Reference the other phases in the "Completed This Session" section
+- Next steps should focus on the current position
+
+### Mid-task pause (executor was interrupted)
+- Note which task was in progress
+- Warn: "Task {name} was in progress when paused. It may need to be re-executed."
+- Check git log to see if any partial commits exist
+
+### .continue-here.md already exists
+- **Always REPLACE** the existing file entirely — never append
+- Appending causes stale data from previous sessions to persist, which confuses resume
+- The old .continue-here.md content is superseded by the current state
+- No need to ask the user — the current session state is always more accurate
+
+### STATE.md doesn't exist
+- Warn: "No STATE.md found. Creating a minimal pause file."
+- Write .continue-here.md based on git log and file system scan only
+- Don't try to update STATE.md
+
+### No git history (fresh project)
+- Skip the git log step
+- Estimate session work from file modification times
+- Still write the continue-here file
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** include full file contents in .continue-here.md — keep it concise
+2. **DO NOT** stage code files in the WIP commit — only planning docs
+3. **DO NOT** skip the commit when `planning.commit_docs` is enabled — the WIP commit preserves the pause state in version control and ensures `.continue-here.md` is not lost if working tree changes occur
+4. **DO NOT** write multiple .continue-here.md files — one per pause
+5. **DO NOT** include sensitive information (API keys, passwords) in the handoff
+6. **DO NOT** modify any code files — this skill only writes planning docs
+7. **DO NOT** skip the "Next Steps" section — it's the most important part for resumption