PRD: NanoPM macOS Viewer

June 12, 2026 · View on GitHub

Generated by /pm-prd on 2026-06-10 Project: nanopm Status: DRAFT

Problem Statement

A non-terminal-native solo founder or PM who has run NanoPM has no way to see what it produced. The artifacts live in a hidden .nanopm/ folder reachable only by opening Claude Code inside the repo and navigating a dot-directory. So the planning value NanoPM generates is invisible unless you live in the terminal — and re-reading your own STRATEGY.md or PRD means re-launching the agent just to print a file. This is the exact wall the Q3 strategy names: the form factor (terminal-only, artifacts buried in a folder), not the value, is what blocks adoption beyond power users. There is currently zero retention measured on anyone — baseline 2026-06-10: 27 stars, 1 fork, 0 external issues (STRATEGY.md).

No FEEDBACK.md or DATA.md exists yet, so this Problem Statement carries no user quotes or quantified drop-off — it rests on the strategic bet, not on observed behavior. That is itself a risk this PRD inherits (see Falsification).

User Stories

As a non-terminal-native PM, I want to open a desktop app and pick my project, so that I can read what NanoPM generated without opening Claude Code or navigating a hidden folder.
As a solo founder mid-cycle, I want my artifacts grouped by the three phases (Discover / Plan / Ship), so that I see at a glance which stages I've done and which are still empty.
As a returning user, I want each artifact rendered as clean, readable Markdown, so that I review my strategy/PRD/roadmap the way I'd read a document — not as raw text in a code editor.

Success Criteria

Criteria	How Measured	Target
A non-terminal-native tester can locate and open a specific named artifact unaided	Observed task in a live test session with 5–10 recruited testers	≥ 7 of 10 succeed in < 60s with no help
Testers voluntarily return to read an artifact a second time	Re-enabled retention instrumentation + follow-up (per STRATEGY.md proof-test step 1)	≥ 40% reopen the viewer within 14 days
Reading happens without opening Claude Code	Self-report in the follow-up	Majority read at least one artifact only in the app, never in the terminal, during the test window
What will be different in commits after this ships?	Review git log 7 days post-ship	A new macOS app project appears (its own directory/repo): a project picker, a phase-grouped read-only file browser over `.nanopm/`, a Markdown renderer, and a subprocess/shell layer that reads files via terminal commands. The existing Bash skill pack's runtime is untouched, and there are no write paths to `.nanopm/`.

Anti-goals (what does NOT count as success for v1):

"It looks polished." Polish that drives a return-visit by novelty rather than by removed friction is a confound, not a win (STRATEGY.md risk #2).
Power-user delight. The target segment is non-terminal-native; retaining people who already tolerate the CLI proves nothing new.
Any in-app generation of new artifacts. v1 reads; it does not produce.

Falsification

Required field — gated.

⚠ rewritten by adversarial gate to satisfy 4-element rubric

Fewer than 40% of the 5–10 recruited non-terminal-native product people who open the NanoPM macOS Viewer will reopen it to read an artifact a second time within 14 days of their first session. If that threshold is missed, graphical read access to the artifacts did not change behavior — the "artifacts-buried-in-a-folder" half of the form-factor thesis is wrong, and a read-only viewer is not the unlock.

Note on what a PASS actually proves: this viewer removes only the reading friction, not the running-the-agent friction (skills are still launched in the terminal). A positive read therefore validates only half the form-factor bet. The control arm in STRATEGY.md (terminal-comfortable cohort) remains the disambiguator.

Scope

In scope (v1)

Project selection — on launch, pick a local folder/repo, mirroring how Claude Code asks you to choose a project. App detects whether .nanopm/ exists and shows an empty/onboarding state if not.
Phase-organized browsing — artifacts grouped into the three phases: Discover (FEEDBACK, DATA, SCAN, AUDIT, DISCOVERY, interview/competitor outputs) → Plan (OBJECTIVES, STRATEGY, ROADMAP, PRDs) → Ship (breakdown handoffs, RETRO, standup/weekly outputs).
Clean Markdown rendering of the latest version of each artifact.
Terminal-driven file access — the app reads .nanopm/ by executing background shell commands (e.g. ls, cat, git), not the Claude Code API.
macOS native.
Discover overview & one action (scope expansion, founder call 2026-06-10) — a recap page for the Discover phase listing the canonical discovery documents with status (generated / running / missing), links to existing artifacts, and a Run button for /pm-competitors-intel (headless claude -p in a background process). Future artifacts show in the sidebar with a running status while the user keeps browsing; a macOS notification fires when the document is ready.
Read-only, strictly: no path that writes to or deletes from .nanopm/.

Out of scope (v1)

File editing — read-only only. Revisit once the prototype reads positive.
Connector management UI (the 15 connectors) — revisit when scoping the full app, not the prototype.
Simultaneous multi-project view — one project open at a time, chosen like in Claude Code. Revisit after v1.
Windows / Linux / web — macOS only. Revisit if macOS validates.
Launching NanoPM runs from the app — ~~deferred per the scope decision~~ partially pulled into scope on founder call (2026-06-10): a Discover overview page exposes a Run action for /pm-competitors-intel, executed headlessly via the claude CLI in a background process (still terminal commands, no API). In-flight artifacts appear in the sidebar with a running status and a macOS notification fires on completion. Full orchestration (arbitrary skills, pipelines, interactive Q&A) remains out — revisit only on a positive prototype read.
Becoming a tracker — handoff stays in Linear/GitHub/etc. (permanent guardrail, STRATEGY.md).

Requirements

Functional requirements

On launch, present a project picker. The user selects a local folder/repo. If the app remembers previously opened projects, show them as a recents list (see The One UX Decision).
After selection, the app detects .nanopm/. If absent, show a clear empty state explaining this folder has no NanoPM artifacts yet. If present, enumerate its artifacts.
The app reads .nanopm/ contents exclusively via background shell/subprocess commands — never the Claude Code API.
Each discovered file is mapped to one of the phases via a fixed mapping table; files that don't match any rule are internal state (configs, logs, snapshots) and are hidden from navigation. (Revised 2026-06-12 — v1 shipped a visible "Other" bucket, retired because it only ever collected noise.)
Selecting an artifact renders its Markdown formatted (headings, tables, lists, code blocks), not as raw text.
The view reflects the latest on-disk state: re-read on window focus or an explicit refresh, because files change when the user runs skills in the terminal between app sessions.
The app exposes no write, rename, or delete operation on .nanopm/ contents. (Run actions create files through the skill, never through the app's own file layer.)
The Discover overview lists every canonical Discover document with its status; documents being generated by an in-flight run appear in the sidebar with a running indicator, without blocking navigation.
Launching any Discover skill (user-feedback, data, scan, audit, discovery, competitors-intel) spawns a claude -p background process in the project folder; each turn's exit triggers an artifact refresh and, on completion, a macOS user notification (success or failure).
When the model needs user input mid-run, it emits a structured nanopm-question block (the headless stand-in for AskUserQuestion); the app notifies the user, renders the questions natively (single/multi-choice options + free text), shows the model's messages so far, and resumes the same session (claude --resume <session_id>) with the composed answers — looping until the document is written.
Runs stream live (--output-format stream-json): each NDJSON event (session init, tool use, tool result, assistant text, turn summary, result) is parsed into a per-run log. An Activity Monitor window lists all runs across the session and shows a live, auto-following console for the selected one, so multiple parallel conversations can be monitored independently.
When competitor intel exists (competitors.json + intel/), the Discover section shows an expandable Competitors entry: selecting it renders the latest report with a History menu (reports newest → oldest); expanding it lists each competitor, opening a page with its monitored-page links, last-checked time, and per-page snapshots as tabs. Competitor-owned files are grouped there instead of cluttering the phase lists.
Phases are labeled Discover / Planning / Build, and each has an Overview page listing its runnable skills with status + Run buttons (Discover: feedback/data/scan/audit/discovery/competitors; Planning: objectives/strategy/roadmap; Build: prd/breakdown). In Build, PRDs are grouped in an expandable PRDs folder: selecting it shows a recap of every PRD with its parsed status (from each file's Status: header); expanding lists the individual PRDs, each opening its full detail.

Non-functional requirements

Local-first: no network calls are required for core browsing.
Graceful failure: missing folder, missing .nanopm/, or a non-repo selection must not crash — each has a defined empty/error state.
Responsive: artifact list and a single-file render complete in under ~1s for a typical .nanopm/ folder.

The One UX Decision

How does the app let you "choose a project," and what counts as one of your projects?

Option A — Claude-Code-style recents list. The app persists the folders you've opened and shows them as a recents/projects list on launch, plus a "browse for folder" escape hatch. Matches the mental model the user explicitly anchored on ("de la même façon qu'on demande à choisir un projet dans Claude Code") and makes re-entry one click — which is exactly the behavior the success metric (voluntary return within 14 days) depends on.
Option B — Finder folder-picker every time. Zero persisted state; the app simply opens a native folder picker on each launch and reads whatever you point it at. Simpler to build, but adds friction to every single return visit and doesn't feel like "my projects."

Tradeoff: A optimizes for the return visit the experiment is trying to measure, at the cost of persisting a small recents list. B is simpler but taxes the exact behavior we're testing. Recommendation: Option A — the return-visit is the success metric, so the form factor must make returning frictionless.

Open questions

Question	Owner	Blocks	By when
~~Tech stack~~	Guillaume	—	RESOLVED 2026-06-10: native Swift/SwiftUI via Swift Package Manager + MarkdownUI, assembled into a .app bundle. Implementation lives in `~/Projects/nanopm-viewer`.
~~Project discovery for the recents list~~	Guillaume	—	RESOLVED 2026-06-10: manually opened folders only (Option A recents persisted in UserDefaults, max 8). No auto-scan in v1.
~~Artifact→phase mapping~~	Guillaume	—	RESOLVED 2026-06-10: implemented as proposed (filename-prefix rules + `prds/` → Plan), unmatched files land in a visible "Other" bucket. Mapping is code (`PhaseMapper`), trivially adjustable. REVISED 2026-06-12: the Other bucket was removed — unmatched files are hidden.

Action: All v1-blocking questions are resolved; implementation has started.

Dependencies

.nanopm/ on-disk layout — the viewer couples to artifact filenames and folder structure. If NanoPM renames or relocates artifacts, the viewer's phase mapping breaks. Treat the layout as a contract the viewer reads against.
Retention instrumentation (memory-read) — must be re-enabled (STRATEGY.md proof-test step 1) for the "voluntary return within 14 days" success criterion to be measurable at all. Without it, this PRD ships blind.

Ties to

Strategy: the form-factor bet — "a visibility/orchestration layer above the agent unlocks adoption beyond power users." This PRD is the read-only slice of that throwaway prototype (STRATEGY.md, "How We Win" #2).
Objective: none defined yet — OBJECTIVES.md is missing. Flag: this PRD has no KR to tie to until /pm-objectives runs.
Roadmap: none defined yet — ROADMAP.md is missing. This covers the strategy's recommended next step (2): "build the minimal throwaway macOS prototype." Run /pm-roadmap to sequence it against the retention-instrumentation and cohort-test steps.

Sources: STRATEGY.md (2026-06-10), prior pm-scan & pm-strategy context, ETHOS.md, user answers (3 clarifying questions: phases = Discover/Plan/Ship, scope = read-only, out-of-scope = editing + connectors + multi-project + non-macOS). No FEEDBACK.md or DATA.md available.