@nudata/nu-claude-pm 0.1.0

package/bin/nu-claude-pm.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const COMMANDS_SRC = path.join(__dirname, "..", "commands");
+
+const args = process.argv.slice(2);
+const command = args[0];
+const isLocal = args.includes("--local");
+const isGlobal = args.includes("--global") || !isLocal;
+
+function getTargetDir() {
+  if (isLocal) {
+    return path.join(process.cwd(), ".claude", "commands");
+  }
+  return path.join(os.homedir(), ".claude", "commands");
+}
+
+function listCommands() {
+  return fs.readdirSync(COMMANDS_SRC).filter((f) => f.endsWith(".md"));
+}
+
+function install() {
+  const targetDir = getTargetDir();
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const files = listCommands();
+  for (const file of files) {
+    const src = path.join(COMMANDS_SRC, file);
+    const dest = path.join(targetDir, file);
+    fs.copyFileSync(src, dest);
+    console.log(`  installed: ${file}`);
+  }
+
+  const scope = isLocal ? "project (.claude/commands/)" : "global (~/.claude/commands/)";
+  console.log(`\n✓ ${files.length} commands installed ${scope}`);
+  console.log("  Reload Claude Code to pick up new commands.");
+}
+
+function uninstall() {
+  const targetDir = getTargetDir();
+  const files = listCommands();
+  let removed = 0;
+
+  for (const file of files) {
+    const dest = path.join(targetDir, file);
+    if (fs.existsSync(dest)) {
+      fs.unlinkSync(dest);
+      console.log(`  removed: ${file}`);
+      removed++;
+    }
+  }
+
+  if (removed === 0) {
+    console.log("No nu-pm commands found to remove.");
+  } else {
+    console.log(`\n✓ ${removed} commands removed.`);
+  }
+}
+
+function printHelp() {
+  console.log(`
+nu-claude-pm — install Claude Code PM commands
+
+Usage:
+  nu-claude-pm install [--global|--local]
+  nu-claude-pm uninstall [--global|--local]
+  nu-claude-pm list
+
+Options:
+  --global   Install to ~/.claude/commands/  (default)
+  --local    Install to .claude/commands/ in the current project
+
+Commands:
+  install    Copy nu-pm-* commands into your Claude Code commands directory
+  uninstall  Remove nu-pm-* commands from your Claude Code commands directory
+  list       List available commands
+`);
+}
+
+switch (command) {
+  case "install":
+    install();
+    break;
+  case "uninstall":
+    uninstall();
+    break;
+  case "list":
+    listCommands().forEach((f) => console.log(`  /` + f.replace(".md", "")));
+    break;
+  default:
+    printHelp();
+    break;
+}

package/commands/nu-pm-continue.md

@@ -0,0 +1,64 @@
+---
+name: nu-pm-continue
+description: Resume work on a project by reading now.md, milestones.md, and roadmap.md. Default directory is product/. Pass a different path as argument if needed.
+---
+
+You are helping the user resume work on a software project after a break or context reset. Work through the following steps in order.
+
+## 1. Locate the product docs
+
+The target directory is: `$ARGUMENTS` (use `product/` if empty or not provided).
+
+Look for these files in the target directory:
+- `now.md` — current focus, next action, what was recently completed
+- `milestones.md` — task checklist across all milestones
+- `roadmap.md` — architecture and design decisions (skim only, don't summarise at length)
+
+If none of these files exist in the given directory, search the repo for files with these names and ask the user to confirm which project they want to resume.
+
+## 2. Gather supporting context
+
+- If `<dir>/how-to/nu-pm-continue.md` exists, read it now and follow any project-specific context-gathering steps listed there (e.g. reading a cluster state file, checking additional infra docs) before proceeding.
+- Run `git log --oneline -8` to see recent commits
+- Run `git status` to surface any uncommitted or untracked changes
+
+## 3. Find the active task
+
+In `milestones.md`:
+- Find the first milestone marked `🔄 in progress`
+- Within that milestone, find the first task marked `[~]` (in progress) or `[ ]` (not yet done)
+- That is the task to resume
+
+## 4. Load design context if present
+
+If `now.md` contains a `Design doc:` field referencing a PRD, and a `Current story:` field:
+- Read the referenced PRD
+- Locate the current story's section
+- Extract its scope, files touched, decisions, and validation criteria — this is the working context for the session
+
+## 5. Present the resume brief
+
+Output a short, scannable summary — aim for something the user can read in 30 seconds:
+
+```
+## Resume Brief
+
+**Milestone**: <milestone name and status>
+**Active story**: <story title (from PRD if present, otherwise task from milestones.md)>
+**Story scope**: <1–2 sentence summary of what the story does and its exit criteria>
+
+**Recently completed**:
+- <2–3 bullet points from now.md "What Was Just Done">
+
+**Infrastructure state**: <up / hibernated / unknown — from how-to/nu-pm-continue.md context if available>
+**Uncommitted changes**: <none / list files if any>
+**Recent commits**: <last 3–4 one-liners from git log>
+```
+
+## 6. Propose the next action
+
+State clearly what to do next — the exact command to run, the file to edit, or the decision to make. Ask the user if they want to proceed with that, or if something has changed since the docs were last updated.
+
+## 7. Offer to update now.md
+
+If the user confirms the current state is accurate, offer to update `now.md` with today's date and any corrections. If the state has changed (e.g. a task was completed offline), update `milestones.md` checkboxes and `now.md` before proceeding.

package/commands/nu-pm-elevator-pitch.md

@@ -0,0 +1,55 @@
+---
+name: nu-pm-elevator-pitch
+description: Generate a short elevator pitch for the project. Produces 3 variants at different lengths, then iterates with the user until it's sharp.
+---
+
+You are helping the user craft a tight elevator pitch for their project. This is a collaborative, iterative process — generate options, get feedback, refine.
+
+The target directory is: `$ARGUMENTS` (use `product/` if empty or not provided).
+
+## 1. Gather source material
+
+Read all of these in parallel:
+- `<dir>/vision.md` — problem, customer, north star (primary source)
+- `<dir>/one-pager.md` — if it exists, use it as a condensed starting point
+- `<dir>/now.md` — current milestone state (for credibility signals: "we've already proven X")
+
+If neither `vision.md` nor `one-pager.md` exist, read `roadmap.md` as a fallback.
+
+## 2. Generate 3 pitch variants
+
+Produce three pitches targeting different contexts. Label them clearly.
+
+**Tweet (≤ 280 chars)**
+One sentence that captures the problem and the product. No jargon. Must make a skeptic want to know more.
+
+**30-second verbal (≤ 75 words)**
+The version you'd say out loud to someone you just met. Covers: who has the problem, what the pain costs them, what you've built, and one proof point. Conversational tone, no bullet points.
+
+**60-second investor / stakeholder (≤ 150 words)**
+Adds: market context, what makes this defensible or timely, and current traction (what's been proven, not just planned). Still a single paragraph — no headers, no lists.
+
+## 3. Present and prompt
+
+Show all three variants. Then ask:
+
+**"Which of these is closest to what you need? I can adjust the tone, sharpen the hook, add a specific number, make it more technical or less, or write a version targeting a specific audience (investor, customer, recruiter, partner)."**
+
+## 4. Iterate
+
+Work through changes one at a time. After each round, show the updated variant only (not all three again) unless the user asks for a full reset.
+
+Common refinement passes:
+- **Sharpen the hook** — lead with the pain or the surprise, not the product name
+- **Add a number** — a concrete metric beats any adjective ("93% cache hit rate" > "fast prefix caching")
+- **Audience swap** — rewrite for a specific reader (a CTO, a VC, a potential customer)
+- **Cut jargon** — flag any term that requires insider knowledge; offer a plain-language swap
+- **Strengthen the "why us / why now"** — add one sentence about what makes this timely or defensible
+
+Keep iterating until the user is satisfied or asks to save.
+
+## 5. Save when ready
+
+When the user confirms a variant is ready, write it to `<dir>/elevator-pitch.md` with all three final variants (or just the one they chose — ask if unclear). Tell them the file was written.
+
+Do not write the file until the user explicitly says to save or approves it.

package/commands/nu-pm-halt.md

@@ -0,0 +1,108 @@
+---
+name: nu-pm-halt
+description: Wrap up the current work session cleanly. Updates docs, writes a session report, commits and pushes. Reads product/how-to/nu-pm-halt.md for project-specific shutdown steps (infrastructure hibernation, etc.).
+---
+
+Wrap up the current work session cleanly.
+
+The target directory is: `$ARGUMENTS` (use `product/` if empty or not provided).
+
+Work through these steps in order:
+
+## 1. Gather current state
+
+Read all of:
+- `<dir>/now.md` — what was just done, what's next
+- `<dir>/milestones.md` — task checklist
+- `git log --oneline -10` — recent commits
+- `git status` — uncommitted changes
+
+## 2. Assess checkpoint readiness
+
+A good checkpoint is one where:
+- No task is mid-execution (no benchmark half-run, no deploy half-applied)
+- All completed work is reflected in docs and committed, OR you are about to do that now
+- The next person (or future session) can resume cleanly from now.md
+
+If NOT at a good checkpoint, warn the user: explain what's in-flight, and ask if they want to wait, skip, or force-halt anyway.
+
+## 3. Update milestones.md
+
+Go through the active milestone task list. For each task completed this session, change `[ ]` to `[x]`. For any task in progress but not done, use `[~]`. Be conservative — only check off tasks that are verifiably complete.
+
+If the milestone has a `Design:` reference, note the current story for now.md but do not modify the PRD.
+
+## 4. Update now.md
+
+- Rewrite "What Was Just Done" with 3–5 bullets from this session
+- Update "Next action" to the first unchecked task in milestones.md
+- If the milestone has a PRD: update "Current story" to the next incomplete story
+- Update any infra state section if infrastructure changed
+- Update the "Recent Commits" block
+
+## 5. Write session report
+
+Create or append to `<dir>/reports/YYYY-MM-DD.md` (today's date).
+
+If the file already exists, append a new section:
+```
+## Session End — HH:MM UTC
+
+**Duration**: <start to now if known, otherwise omit>
+**Git commits this session**: <list new commits>
+
+### Completed
+- <bullet list of what was accomplished>
+
+### Key numbers (if any benchmarks or significant runs happened)
+| Metric | Value |
+|--------|-------|
+
+### Bugs / Surprises
+- <anything unexpected>
+
+### Left in progress
+- <anything started but not finished>
+
+### Next session starts at
+<first unchecked task from milestones.md>
+```
+
+If the file does not exist, create it with a header first:
+```markdown
+# Session Report — YYYY-MM-DD
+```
+Then append the Session End section.
+
+## 6. Commit and push
+
+Stage all modified files:
+- `<dir>/now.md`
+- `<dir>/milestones.md`
+- `<dir>/reports/YYYY-MM-DD.md`
+- Any other modified tracked files surfaced by git status
+- New untracked files that are clearly intentional (reports, design docs, config files)
+
+Write a commit message summarising what was accomplished:
+```
+session: <one-line summary of what was done>
+
+- <bullet 1>
+- <bullet 2>
+```
+
+Push to origin main.
+
+## 7. Project-specific shutdown
+
+Check if `<dir>/how-to/nu-pm-halt.md` exists. If it does, read it and execute all steps described there. These are project-specific teardown steps such as infrastructure hibernation, scaling down services, or other environment cleanup.
+
+If the file does not exist, skip this step silently.
+
+## 8. Report back
+
+Confirm:
+- ✅ Docs updated (milestones.md, now.md)
+- ✅ Session report written to `<dir>/reports/YYYY-MM-DD.md`
+- ✅ Committed and pushed (show `git log --oneline -3`)
+- Any project-specific shutdown steps completed (from how-to file, if present)

package/commands/nu-pm-one-pager.md

@@ -0,0 +1,81 @@
+---
+name: nu-pm-one-pager
+description: Create or update a one-pager.md for the project. Synthesises vision, roadmap, and milestone state into a crisp single-page summary, then iterates with the user.
+---
+
+You are helping the user create or refine a one-pager for their project. This is an interactive, iterative process — generate a draft, present it, then work through changes together.
+
+The target directory is: `$ARGUMENTS` (use `product/` if empty or not provided).
+
+## 1. Gather source material
+
+Read all of these in parallel:
+- `<dir>/vision.md` — problem, customer, north star (primary source)
+- `<dir>/roadmap.md` — architecture, delivery phases, key decisions (skim)
+- `<dir>/milestones.md` — what's done vs in-progress vs pending (current state)
+- `<dir>/now.md` — most recent completed work (for "where we are" section)
+
+If `<dir>/one-pager.md` already exists, read it too — you'll be updating it, not replacing it from scratch.
+
+## 2. Check for an existing one-pager
+
+- If `<dir>/one-pager.md` exists: load it, note what's stale or missing, and propose targeted updates rather than a full rewrite.
+- If it doesn't exist: generate a fresh draft using the structure below.
+
+## 3. Draft structure
+
+Write a one-pager that fits on a single printed page (~400–600 words). Use this structure:
+
+```
+# <Project Name> — One-Pager
+
+## The Problem
+<2–3 sentences. What pain exists, for whom, and why it matters now.>
+
+## What We're Building
+<2–3 sentences. The product in plain language — what it does, who uses it, how it's different.>
+
+## How It Works
+<3–5 bullets. Key technical or product mechanisms — enough to be credible, not a deep dive.>
+
+## Where We Are
+<Current milestone + 1–2 sentences on what's proven so far.>
+
+## What's Next
+<Next 1–2 milestones in plain language — what they unlock.>
+
+## Why Now
+<1–2 sentences. The timing argument — market window, infrastructure readiness, or strategic moment.>
+
+## Key Numbers
+<3–5 concrete metrics — benchmark results, cost figures, customer counts, or performance numbers pulled from source docs.>
+```
+
+Adapt section names if the project's vocabulary suggests better ones. Keep every section tight — cut anything that doesn't help a reader decide whether to care.
+
+## 4. Present the draft
+
+Show the full draft. Then immediately below it, list:
+
+```
+### Suggested improvements
+- <specific thing that could be sharper, more concrete, or better evidenced>
+- <section that is weak or missing a number>
+- <anything that sounds vague or that a skeptical reader would question>
+```
+
+Limit suggestions to 3–5 — don't overwhelm. Focus on the highest-leverage improvements.
+
+## 5. Iterate
+
+Ask the user: **"What would you like to change? I can also expand any section, add a section, sharpen the language, or update numbers."**
+
+Make changes as requested. After each round, show only the updated section(s) unless the user asks to see the full doc again.
+
+Keep iterating until the user says they're happy with it or asks to save.
+
+## 6. Save when ready
+
+When the user confirms the draft is ready, write it to `<dir>/one-pager.md`. Tell them the file was written and that it can be regenerated any time by running `/nu-pm-one-pager`.
+
+Do not write the file until the user explicitly says to save or approves it.

package/commands/nu-pm-research.md

@@ -0,0 +1,151 @@
+---
+name: nu-pm-research
+description: Create a structured research document for market research, competitive analysis, or technology deep-dives. Guides the investigation interactively and writes findings to product/research/ or product/market-research/.
+---
+
+You are helping the user conduct and document a structured research investigation. This produces a permanent artifact in the project — not a one-time answer, but a document that informs a decision.
+
+The target directory is: `$ARGUMENTS` (use `product/` if empty or not provided).
+
+---
+
+## Step 1 — Check for existing research
+
+List any files in `<dir>/research/` and `<dir>/market-research/` so the user knows what's already been done. If either directory doesn't exist, note it but continue.
+
+Ask: **"What are you researching?"** Wait for the answer before proceeding.
+
+---
+
+## Step 2 — Classify the research type
+
+Based on the user's answer, determine the type (or ask if unclear):
+
+| Type | Description | Output directory |
+|------|-------------|-----------------|
+| `market` | Market size, customer segments, buying behavior, pricing | `<dir>/market-research/` |
+| `competitive` | Specific competitors, their positioning, features, pricing, weaknesses | `<dir>/market-research/` |
+| `technology` | Evaluating a technology, framework, protocol, or approach for use in the project | `<dir>/research/` |
+| `user` | User interviews, surveys, behavioral patterns, workflow analysis | `<dir>/market-research/` |
+| `domain` | Understanding a domain, industry, or regulatory context relevant to the product | `<dir>/research/` |
+
+Confirm with the user: **"I'll file this as [type] research in [directory] — does that sound right?"**
+
+---
+
+## Step 3 — Frame the research
+
+Ask these questions one at a time. Don't ask all at once.
+
+1. **"What specific question does this research need to answer?"**
+   Help them sharpen it if it's too broad. "How big is the market?" is weak. "Is there a segment of platform engineering teams managing >10 GPU workloads who are currently unserved by managed options?" is strong.
+
+2. **"What decision does this inform — and by when?"**
+   This prevents research from becoming an end in itself. Acceptable answers: "whether to price by seat or by GPU-hour (before M5)", "whether to build our own routing layer or use LiteLLM (this week)".
+
+3. **"What do we already know or believe?"**
+   Capture existing assumptions so the research can confirm or challenge them, not just collect neutral facts.
+
+4. **"What would change if the answer is X vs Y?"**
+   Forces the research to be decision-relevant. If both answers lead to the same action, the research isn't needed.
+
+---
+
+## Step 4 — Draft the research document
+
+Generate a filename: `YYYY-MM-DD-<slug>.md` where slug is a 3-5 word kebab-case title derived from the question. Use today's date.
+
+Write the document to the appropriate directory with this structure:
+
+```markdown
+# <Research Title>
+
+**Type**: <market / competitive / technology / user / domain>
+**Status**: 🔄 in progress
+**Question**: <the sharpened question from Step 3>
+**Decision it informs**: <what changes based on the answer, and by when>
+**Started**: YYYY-MM-DD
+
+---
+
+## What We Already Know
+
+<Assumptions and prior knowledge going into this research. These are the things this research will confirm, challenge, or add nuance to.>
+
+---
+
+## Approach
+
+<How this will be investigated — sources, methods, scope limits. Be honest about what won't be covered.>
+
+---
+
+## Findings
+
+> Fill this in as research progresses. Structure by sub-question or theme, not by source.
+
+---
+
+## Recommendation
+
+> Complete this last. State the answer to the research question directly, then explain.
+
+**Answer**: <direct answer to the research question>
+
+**Rationale**: <2–3 sentences — what the findings show and why they support this answer>
+
+**Confidence**: <high / medium / low — and why>
+
+**What this changes**: <specific impact on vision, roadmap, or a milestone decision>
+
+---
+
+## Sources
+
+| Source | Type | Key takeaway |
+|--------|------|-------------|
+| | | |
+
+---
+
+## Open Questions
+
+<Things this research raised but didn't answer. These may become their own research docs or spike investigations.>
+```
+
+Show the user the created document path and tell them the structure is ready to fill in.
+
+---
+
+## Step 5 — Begin the investigation collaboratively
+
+Ask: **"Do you want to work through this together now, or do you have findings to add?"**
+
+**If working together now**: help the user think through the research systematically. For competitive research, work through competitors one by one. For technology research, evaluate against the project's specific requirements. For market research, help estimate from first principles rather than citing vague statistics. Push back on weak evidence. Fill in Findings and Recommendation collaboratively.
+
+**If they have findings to add**: take what they give you and help structure it into the document. Ask clarifying questions to get to the Recommendation section — don't let the document end with findings but no answer.
+
+---
+
+## Step 6 — Complete the document
+
+When findings are sufficient to answer the research question:
+
+1. Fill in the **Recommendation** section — answer the question directly
+2. Change **Status** from `🔄 in progress` to `✅ concluded`
+3. Fill in **What this changes** — this is the most important field: what specifically in the project should change as a result?
+
+If the research reveals something significant that affects `vision.md` or `roadmap.md`, flag it:
+> "This finding suggests [X] should change in your roadmap/vision. Want to run `/nu-pm-roadmap` or `/nu-pm-vision` to review?"
+
+---
+
+## Step 7 — If research can't be concluded today
+
+If the user needs to stop before the research is complete, leave **Status** as `🔄 in progress` and add a note under Findings:
+
+```markdown
+> **Paused YYYY-MM-DD**: <what was found so far, what remains to investigate>
+```
+
+Tell the user: "This research doc is in `<path>`. Resume it any time by running `/nu-pm-research` — it will show you open research at the start."