@nudata/nu-claude-pm 0.1.0

package/commands/nu-pm-scaffold.md

@@ -0,0 +1,604 @@
+---
+name: nu-pm-scaffold
+description: Bootstrap a new project with the standard PM structure — product/ directory, placeholder docs, how-to extension files, and project-management-principles.md. Run from the project root.
+---
+
+Bootstrap a new project with the standard project management structure.
+
+Parse `$ARGUMENTS` for an optional project description (used to fill in placeholders). If not provided, use generic placeholder text.
+
+## What this creates
+
+```
+product/
+├── vision.md                     # why + who (problem, customer, north star)
+├── roadmap.md                    # architecture + milestone plan (placeholder)
+├── milestones.md                 # progress tracker (placeholder)
+├── now.md                        # session pointer (placeholder)
+├── project-management-principles.md   # canonical PM reference (copied from scaffold)
+├── design/                       # PRDs live here (empty, ready to use)
+├── market-research/              # competitive analysis, user research (empty)
+├── research/                     # pre-decision options analyses and deep dives (empty)
+├── operations/                   # cluster runbooks, infra how-tos (empty)
+├── learnings/                    # post-hoc reports, incident retrospectives (empty)
+├── reports/                      # session reports live here (empty, ready to use)
+└── how-to/
+    ├── nu-pm-continue.md            # project-specific resume additions (template)
+    ├── nu-pm-halt.md              # project-specific shutdown steps (template)
+    ├── nu-pm-update.md            # project-specific update additions (template)
+    └── nu-pm-status.md             # project-specific prerequisite checks (template)
+```
+
+## Steps
+
+### 1. Check for existing structure
+
+If `product/` already exists, warn the user: "product/ already exists — scaffolding will add missing files but will not overwrite existing ones." Proceed file by file, skipping any that already exist.
+
+### 2. Create product/roadmap.md
+
+```markdown
+# Roadmap
+
+> Replace this placeholder with your project's architecture, vision, and milestone plan.
+> See project-management-principles.md for guidance on what belongs here.
+
+## Purpose
+
+This document captures the architecture decisions, component design, and phased delivery
+plan. It is a **planning artifact**, not a task tracker.
+
+---
+
+## Context: Where We Are Now
+
+<Describe the current state of the project — what exists, what works, what doesn't.>
+
+---
+
+## Vision
+
+See `product/vision.md`.
+
+---
+
+## Architecture
+
+<Diagram or description of the main components and how they fit together.>
+
+---
+
+## Delivery Phases
+
+### Milestone 1: <Name>
+*Goal: <one sentence>*
+
+Stories:
+1. <Story title>
+2. <Story title>
+
+Exit criteria: <How do you know M1 is done?>
+
+---
+
+## Key Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+
+---
+
+## Open Questions
+
+- <Question 1>
+- <Question 2>
+```
+
+### 3. Create product/vision.md
+
+```markdown
+# Vision
+
+> The why behind this project — problem, customer, and north star.
+> More stable than roadmap.md. Rarely changes once the product direction is set.
+> Market research and competitive context lives in `product/market-research/`.
+
+---
+
+## Problem
+
+<What pain are we solving? Who feels it and when?>
+
+---
+
+## Customer / Target user
+
+<Who is this for? Be specific about the role, context, and workflow.>
+
+---
+
+## Market context
+
+<Where does this sit in the landscape? What alternatives exist and why aren't they enough?>
+See `product/market-research/` for supporting research.
+
+---
+
+## North star
+
+<What does success look like in 2–3 years? What can a user do that they couldn't before?>
+
+---
+
+## Why now?
+
+<What makes this the right time to build this?>
+
+---
+
+## What we are not
+
+<Product-level anti-goals — not feature-scope cuts, but fundamental things this product will never try to be.>
+```
+
+### 5. Create product/milestones.md
+
+```markdown
+# Milestones
+
+Lightweight task tracker. Update status markers and checkboxes as work progresses.
+Architecture context lives in `roadmap.md`.
+
+## Status Key
+
+```
+⏳ pending      — not started
+🔄 in progress  — actively being worked
+✅ done         — exit criteria met
+🚫 blocked      — waiting on something external
+```
+
+Task checkboxes:
+- `[ ]` not done
+- `[x]` done
+- `[~]` in progress
+- `[-]` skipped / won't do
+
+---
+
+## M1 — <Milestone Name>
+**Status**: ⏳ pending
+**Goal**: <one sentence>
+
+### Tasks
+
+- [ ] <Task 1>
+- [ ] <Task 2>
+- [ ] <Task 3>
+
+**Exit criteria**: <How do you know this milestone is done?>
+
+---
+
+## Notes
+
+- Milestones are sequential by dependency, not by calendar priority
+- Each milestone must pass its exit criteria before the next begins
+```
+
+### 4. Create product/now.md
+
+```markdown
+# Where We Are Now
+
+> Read this first when resuming work. Update it whenever a milestone or major task changes.
+
+---
+
+## Current Focus
+
+**Milestone**: M1 — <Milestone Name>
+**Status**: ⏳ not started
+**Next action**: <First task from milestones.md>
+
+---
+
+## What Was Just Done
+
+- Project scaffolded — replace this with session notes after first work session
+
+---
+
+## What's Coming Next
+
+1. [ ] <Task 1>
+2. [ ] <Task 2>
+3. [ ] <Task 3>
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `product/milestones.md` | Task checklist for all milestones |
+| `product/roadmap.md` | Architecture and vision — stable reference |
+| `product/now.md` | This file — current focus and resume context |
+
+---
+
+## How to Resume After a Break
+
+1. Read this file
+2. Check `milestones.md` for the first unchecked task in the active milestone
+3. Run `/nu-pm-continue` for a full context brief
+
+---
+
+## Recent Commits
+
+```
+<git log --oneline -5 will appear here after first commits>
+```
+```
+
+### 6. Create product/how-to/nu-pm-continue.md
+
+```markdown
+# Project-specific nu-pm-continue additions
+
+> Fill in any project-specific context sources that /nu-pm-continue should gather.
+> Examples: a CURRENT_STATE.md file, a cluster status check, an infra state API call.
+> Delete this file if there are no project-specific additions needed.
+
+## Additional context to gather
+
+TODO: list any project-specific files or commands to read during resume.
+
+## Additional fields in resume brief
+
+TODO: list any fields to add to the resume brief output (e.g. infrastructure state).
+```
+
+### 7. Create product/how-to/nu-pm-halt.md
+
+```markdown
+# Project-specific halt steps
+
+> These steps run AFTER the generic nu-pm-halt steps (docs updated, committed, pushed).
+> Add any project-specific teardown here — infrastructure hibernation, service shutdown, etc.
+> Delete this file if there are no project-specific shutdown steps.
+
+## TODO: Add project-specific shutdown steps
+
+Examples of what goes here:
+- Scale down cloud infrastructure (Kubernetes nodes, VMs, etc.)
+- Stop background processes
+- Update an external status page
+- Send a session-end notification
+
+Replace this with your actual shutdown steps and remove this comment.
+```
+
+### 8. Create product/how-to/nu-pm-update.md
+
+```markdown
+# Project-specific nu-pm-update additions
+
+> These additions run during /nu-pm-update state-gathering, before writing the report.
+> Add any project-specific state to capture in mid-session snapshots.
+> Delete this file if there are no project-specific additions needed.
+
+## Additional state to gather
+
+TODO: list any project-specific state to include in update snapshots.
+
+## Additional fields in the report snapshot
+
+TODO: describe any extra fields to add to the "In progress" section.
+```
+
+### 9. Create product/how-to/nu-pm-status.md
+
+```markdown
+# Project-specific nu-pm-status additions
+
+> These additions run during /nu-pm-status prerequisite checking.
+> Add any project-specific infrastructure checks needed before starting the next task.
+> Delete this file if there are no project-specific prerequisite checks.
+
+## Additional context to gather
+
+TODO: list any project-specific state files or commands to check.
+
+## Infrastructure prerequisite check
+
+TODO: describe what "infrastructure ready" means for this project and how to check it.
+```
+
+### 10. Create product/project-management-principles.md
+
+Write the following content exactly as the file:
+
+---
+
+# Project Management Principles
+
+This document explains how we work on this project: what our documents are, what our skills do, and how they fit together. Read this before your first session.
+
+For the full command reference — what every `nu-pm-*` command does, when to run it, and how they fit together — run **`/nu-pm-user-guide`**.
+
+---
+
+## The Guiding Principle
+
+**Each question has exactly one document to answer it. Reference, don't duplicate.**
+
+The moment the same content lives in two places, they drift. When documents drift, sessions start with confusion instead of clarity. We keep the document count small and the responsibility of each document strict.
+
+---
+
+## The Document Stack
+
+```
+product/vision.md            ← why + who (problem, customer, north star)
+product/roadmap.md           ← what + how (architecture, milestones, key decisions)
+product/milestones.md        ← progress tracker (story checkboxes, milestone status)
+product/now.md               ← session pointer (what I'm doing right now)
+product/design/*.md          ← design authority (story detail for milestones that need it)
+product/market-research/     ← competitive analysis, user research (feeds vision.md)
+product/research/            ← pre-decision options analyses and deep dives
+product/operations/          ← cluster runbooks, infra how-tos
+product/learnings/           ← post-hoc reports, incident retrospectives
+product/reports/             ← session history (timestamped logs of what happened)
+product/how-to/              ← project-specific skill extensions (infrastructure, etc.)
+```
+
+### `product/vision.md` — The Product Vision
+
+The why. Read it to understand the problem, the customer, and the north star. It contains:
+- Problem statement and who feels it
+- Target customer / user profile
+- Market context (references `market-research/` for depth)
+- North star — what success looks like in 2–3 years
+- Why now
+- What this product is not (product-level anti-goals)
+
+**More stable than roadmap.md.** Update it when product direction changes, not when milestones shift.
+
+### `product/roadmap.md` — The Architecture Document
+
+The technical delivery plan. Read it to understand how we're building it. It contains:
+- Architecture stack and component design
+- All milestones in sequence, with their goals and exit criteria
+- Key decisions already made (and the rationale behind them)
+- Open questions with proposed resolutions
+
+**Do not edit roadmap.md unless architecture changes.** It is not a task tracker.
+
+### `product/milestones.md` — The Progress Tracker
+
+The live checklist. Read it to understand where we are across all milestones. It contains:
+- One section per milestone with status (`⏳ pending`, `🔄 in progress`, `✅ done`, `🚫 blocked`)
+- Story-level checkboxes: `[ ]` not done, `[x]` done, `[~]` in progress, `[-]` skipped
+- For milestones with a PRD: a `Design:` reference to the design doc
+- Exit criteria per milestone
+
+**The milestone section owns the completion state of stories. The PRD owns the content of stories.**
+
+**Milestone status markers:**
+```
+⏳ pending      — not started
+🔄 in progress  — actively being worked
+✅ done         — exit criteria met
+🚫 blocked      — waiting on something external
+```
+
+### `product/now.md` — The Session Pointer
+
+The first thing you read when resuming. It tells you exactly where you are and where to go next. It contains:
+- Current milestone + status
+- Design doc reference + current story (if the milestone has a PRD)
+- What was just done (last session's output, 3–5 bullets)
+- Current infra state (if project has infrastructure)
+- What's coming next (ordered task list, first unchecked item is the target)
+- Key files you'll need
+- Recent commits
+
+**The skills keep `now.md` current.** You should rarely need to edit it by hand.
+
+### `product/design/` — Design Documents (PRDs)
+
+Not every milestone needs a PRD. Simple milestones track tasks directly in `milestones.md`. Milestones that involve software design — new endpoints, schemas, conventions — get a PRD.
+
+A PRD is the **single source of truth for story content**: scope, files, decisions, and validation. The `milestones.md` entry for a story is a one-line checkbox + title; the PRD has the full detail.
+
+**PRD naming convention**: `product/design/M{N}-PRD.md`
+
+A PRD contains:
+1. Overview (goal, non-goals, exit criteria)
+2. Architecture (stack diagram, component table)
+3. Directory layout after the milestone completes
+4. Schema or API specs (locked decisions)
+5. Story breakdown (one section per story: scope, files, decisions, validation)
+6. What does NOT change (scope guard)
+7. Open questions (with proposals and decision points)
+8. Files touched (change table)
+9. Story dependency graph
+10. Decision Log (append-only table of significant direction changes — see Conventions)
+
+### `product/reports/` — Session History
+
+One file per day: `product/reports/YYYY-MM-DD.md`. Append-only. Written by `/nu-pm-update` (mid-session) and `/nu-pm-halt` (session end). Historical record only — not a planning document.
+
+### `product/how-to/` — Skill Extension Files
+
+Project-specific additions to the generic global skills. Each file extends one skill:
+
+| File | Extends |
+|------|---------|
+| `how-to/nu-pm-continue.md` | `/nu-pm-continue` — extra context sources, extra resume brief fields |
+| `how-to/nu-pm-halt.md` | `/nu-pm-halt` — infrastructure shutdown, teardown steps |
+| `how-to/nu-pm-update.md` | `/nu-pm-update` — extra state to capture in snapshots |
+| `how-to/nu-pm-status.md` | `/nu-pm-status` — infrastructure prerequisites, extra context |
+
+**How-to files contain only the project-specific additions.** The generic steps live in the global skills. If there's nothing project-specific to add, the file can be deleted.
+
+---
+
+## The Skills
+
+Skills are Claude Code slash commands. Global skills live in `~/.claude/commands/` and work in any project. Invoke them with `/skill-name [arguments]`.
+
+### Session Skills (global)
+
+#### `/nu-pm-continue [dir]`
+**When**: Start of every session.
+
+Reads `now.md`, `milestones.md`, `roadmap.md`, the latest session report, and `how-to/nu-pm-continue.md` (if present). Outputs a resume brief with active story context from the PRD if applicable.
+
+#### `/nu-pm-status [dir]`
+**When**: After finishing a task, to orient to the next one.
+
+Shorter than `/nu-pm-continue`. Finds the active task, checks prerequisites (including project-specific infra state from `how-to/nu-pm-status.md`), and gives the concrete first action.
+
+#### `/nu-pm-update [dir]`
+**When**: Mid-session checkpoint — after a significant task, before stepping away.
+
+Appends a timestamped snapshot to today's session report. Does **not** commit. Incorporates project-specific state from `how-to/nu-pm-update.md` if present.
+
+#### `/nu-pm-halt [dir]`
+**When**: End of every session.
+
+The full shutdown sequence: updates milestones + now.md, writes session report, commits and pushes, then executes `how-to/nu-pm-halt.md` for project-specific teardown (infrastructure hibernation, etc.).
+
+**Always end sessions with `/nu-pm-halt`**, not manual commits.
+
+#### `/nu-pm-scaffold [description]`
+**When**: Starting a new project.
+
+Creates the full `product/` structure with placeholder docs, `how-to/` templates, and this principles document. Run from the project root.
+
+---
+
+## How a Typical Session Flows
+
+```
+Start session
+  → /nu-pm-continue
+  → (project-specific) wake infrastructure if needed
+
+Do the work
+  → edit files, run commands, iterate
+  → /nu-pm-update  (optional mid-session checkpoint)
+
+End session
+  → /nu-pm-halt  (updates docs, commits, runs project-specific teardown)
+```
+
+---
+
+## How Milestones and PRDs Work Together
+
+For milestones with a PRD, the three documents divide responsibility cleanly:
+
+**`milestones.md`** tracks completion:
+```markdown
+## M1 — Walking Skeleton
+**Status**: 🔄 in progress
+**Design**: `product/design/M1-PRD.md`
+
+- [x] Story 1 — Profile extraction
+- [ ] Story 2 — Hand-author Helmfile
+```
+
+**`now.md`** points to the current story:
+```markdown
+**Design doc**: product/design/M1-PRD.md
+**Current story**: Story 2 — Hand-author Helmfile
+```
+
+**`product/design/M1-PRD.md`** has the full story detail — files, decisions, validation.
+
+Nothing is duplicated. Each document answers exactly one question.
+
+---
+
+## What Goes Where — Quick Reference
+
+| Question | Document |
+|----------|----------|
+| Why are we building this? Who is it for? | `vision.md` |
+| What are we building and how? | `roadmap.md` |
+| Which milestone am I in? | `milestones.md` |
+| Which stories are done? | `milestones.md` |
+| What am I doing right now? | `now.md` |
+| What exactly does Story N require? | `product/design/M{N}-PRD.md` |
+| What happened last Tuesday? | `product/reports/YYYY-MM-DD.md` |
+| How do I shut down after a session? | `/nu-pm-halt` (reads `how-to/nu-pm-halt.md`) |
+
+---
+
+## Conventions
+
+**Commits** — written by `/nu-pm-halt` in this format:
+```
+session: <one-line summary>
+
+- bullet 1
+- bullet 2
+```
+No WIP commits. Sessions end cleanly with `/nu-pm-halt`.
+
+**Story naming** — titles in PRDs match checkboxes in `milestones.md`. Rename in sync.
+
+**PRDs are design records, not task lists** — don't add checkboxes to PRDs. Progress lives in `milestones.md`. If a design decision changes, update the PRD in place with the new decision and rationale.
+
+**Open questions get resolved, not deleted** — the question + answer pair is more useful than either alone.
+
+**Decision Log at the bottom of every PRD** — when a significant design decision changes (an API shape, a storage strategy, a scope cut), append a row to the Decision Log table rather than silently rewriting the doc. This answers "why did we end up here?" without requiring the reader to dig through git history. The format:
+
+```markdown
+## Decision Log
+
+| Date | Decision | Rationale | Changed from |
+|------|----------|-----------|--------------|
+| YYYY-MM-DD | <what was decided> | <why> | <what it replaced, or "new decision"> |
+```
+
+Log significant direction changes, contested calls, and anything a future reader would wonder about. Do NOT log every small edit — those belong to git. The question + answer pairs in "Open questions" feed naturally into the Decision Log once resolved.
+
+**Not every milestone needs a PRD** — if the work is straightforward operational tasks (infrastructure changes, benchmarking), track it directly in `milestones.md`. Create a PRD only when there are real design decisions to document.
+
+**How-to files contain only additions** — never duplicate the generic skill steps. If a how-to file would be empty, delete it.
+
+---
+
+*This document is the canonical copy distributed by `/nu-pm-scaffold`. To update the principles for all future projects, update the scaffold skill at `~/.claude/commands/nu-pm-scaffold.md`.*
+
+---
+
+### 11. Create empty placeholder files for design/, market-research/, research/, operations/, learnings/, and reports/
+
+Create `.gitkeep` files in all six directories:
+- `product/design/.gitkeep`
+- `product/market-research/.gitkeep`
+- `product/research/.gitkeep`
+- `product/research/spikes/.gitkeep`
+- `product/operations/.gitkeep`
+- `product/learnings/.gitkeep`
+- `product/reports/.gitkeep`
+
+### 12. Report back
+
+List every file created (or skipped because it already existed). Then say:
+
+```
+Project scaffolded. Next steps:
+1. Edit product/vision.md — fill in problem, customer, north star
+2. Edit product/roadmap.md — fill in your architecture and milestone plan
+3. Edit product/milestones.md — replace placeholder tasks with real ones
+4. Edit product/now.md — set your first milestone and next action
+5. Edit product/how-to/nu-pm-halt.md — add your project's shutdown steps (or delete if none)
+6. Run /nu-pm-continue when you're ready to start working
+```