pm-brain

name

pm-brain

description

Initialize a PM Brain — a markdown-native second brain for a product operator (PM, product lead, founder, or anyone accountable for one product or initiative) doing judgment-heavy work with scattered inputs. Detects greenfield vs. migration mode, runs a focused interview, copies the deterministic scaffold into the working directory, populates placeholders from interview answers, runs a self-test, and commits. Use when invoked via `/pm-brain` or when the user asks to set up a PM Brain.

PM Brain — Skill

This skill scaffolds and initializes a PM Brain in the current working directory. The scaffold is deterministic (static files copied as-is from scaffold/). The reasoning is adaptive (loaded from prompts/ per phase).

Architectural split

Layer	Where it lives	Why
Static structure — schemas, CLAUDE.md, INDEX.md, folder tree, file templates	scaffold/	Deterministic. Same every time. No generation needed.
Adaptive reasoning — mode detection, migration, interview, post-scaffold self-test	prompts/	Probabilistic. Depends on what's in the directory and what the PM says.
Orchestration — when to do what	This file	Glue.

Behavior evolves independently from structure. Schemas can change without touching reasoning. Reasoning can improve without rewriting schemas.

When to invoke

• Operator runs /pm-brain (or pastes a setup request like "set up a PM Brain here").
• Operator asks to add a PM Brain to an existing directory of PM artifacts.

Do not invoke this skill for routine PM Brain operations after init (ingestion, prep, review). Those are handled by the seeded CLAUDE.md operating manual in the target repo.

Workflow

1. Detect mode

Load prompts/mode-detection.md. Inspect the current working directory. Decide: greenfield (empty), migration (PM artifacts present), or active-repo (working repo — pause and ask).

Announce the detected mode to the operator in one line. For active-repo mode, do not proceed without confirmation.

2. If migration mode

Load prompts/migration.md. Copy (do not move) pre-existing PM artifacts into a source/ folder. Bulk-ingest with epistemic caution. Record cross-document conflicts for the post-scaffold contradictions block.

3. Run the interview

Load prompts/interview.md. Ask the 5 batches (greenfield) or only the gaps not covered by source artifacts (migration). Confirm back what you heard before scaffolding.

4. Copy the scaffold

Copy every file and folder from scaffold/ into the current working directory — including the hidden .claude/ directory (hooks + per-brain settings) and dotfiles (.gitignore, .gitkeep). Preserve structure.

Use the form of copy that picks up dotfiles by default:

• Bash: cp -R scaffold/. <dest>/ (the trailing /. is what makes dotfiles come along)
• PowerShell: Copy-Item -Recurse -Force scaffold\* <dest>\ followed by Copy-Item -Recurse -Force scaffold\.* <dest>\ (the second pass picks up .claude/ and .gitignore; Copy-Item -Recurse scaffold\* alone will silently drop them)

After copying, verify the install by listing the destination — .claude/, .gitignore, and every top-level area folder (hypotheses/, decisions/, source/, ingestion/, knowledge/, stakeholders/, rules/, maintenance/, docs/) must all be present. If .claude/ is missing the hook won't fire on agent writes and schema violations will go uncaught — re-do the copy.

Critical rules:

• Copy in place. The current working directory is the project root. Do not create a nested subfolder.
• Preserve .gitkeep files in empty folders.
• Preserve .claude/hooks/validate_brain_file.py and .claude/settings.json exactly as shipped — they're what makes schema enforcement happen in-loop as the agent edits brain files.
• Do not modify scaffold files at the source. If you need to change a template permanently, edit scaffold/ and re-version the skill.

5. Populate placeholders from interview answers

Walk the copied files and substitute interview answers. Use the full Batch → file mapping in prompts/interview.md § What the answers feed — that table is the canonical destination map. Every Batch answer has a documented home; do not silently drop any.

Highlights:

• knowledge/strategy.md — north-star metric, priorities (Batch A). Non-goals start empty if PM didn't volunteer them; flag in next moves.
• knowledge/product/features/<slug>.md — one file per active feature (Batch C Q1), populated from the feature schema.
• knowledge/product/roadmap.md — Now / Next sections from Batch C.
• stakeholders/<slug>.md — one file per stakeholder (Batch B Q1); influence + friction tagged from Batch B Q2.
• knowledge/org/team.md, knowledge/org/rituals.md, knowledge/org/tools.md — from Batch B Q3 + Batch D Q1.
• knowledge/market/landscape.md and/or trends.md — from Batch D Q3.
• rules/discovery.md, rules/data.md — from Batch D Q1-2.
• CLAUDE.md § Operating preferences — autonomy mode + maintenance cadence (Batch E Q1-2).
• CLAUDE.md § Off-limits — Batch E Q3.

For schema-templated files: copy the schema structure as-is, fill in what the interview provided, leave the rest with the placeholder comments intact.

Provenance: every populated field should be traceable back to either a Batch question or a source artifact. When a value came from a source artifact, link to it inline.

6. Post-scaffold self-test

Load prompts/post-scaffold.md. Run:

1. Routing self-test (can you route each of the 4 ingestion modes?).
2. Link verification (walk every internal markdown link, fix broken ones).
3. Surface 3-5 immediate next moves.
4. Surface 1-3 contradictions found during scaffolding (or say explicitly "none found").
5. Print the self-test receipt.

7. Commit

• Run git rev-parse --is-inside-work-tree in the current working directory.
• If already a repo: stage all scaffolded files. Single commit titled feat: initialize PM brain.
• If not a repo: git init in the current working directory, then stage and commit.
• Never push remotely. PM controls publication.
• If any git step fails, surface the error and stop. No destructive recovery.

8. Hand off

Lead with the habit loop, not the scaffold. See prompts/post-scaffold.md § 7 for the exact ordering:

1. The three habit actions (ingest today / prep next 1:1 / /review Friday) — specific slug + day.
2. 1-3 contradictions surfaced (or "none found").
3. 2-3 scaffold gaps worth filling.
4. One paragraph on what was built.

Do not lead with a folder map or "your scaffold is ready." Lead with what produces value in the next 24 hours.

Then stop and wait for the operator's first real task.

Anti-patterns

• Regenerating scaffold content. The whole point of scaffold/ is that it's deterministic. If you find yourself rewriting CLAUDE.md or a schema from scratch during init, stop — copy from scaffold/ instead.
• Creating a nested pm-brain/ subfolder. The current working directory is the project root.
• Skipping the self-test. Broken links are memory corruption, not cosmetic.
• Inventing contradictions. If migration mode found no genuine conflicts, say so. Don't fabricate.
• Pushing remotely. PM controls when and where this gets published.

Files in this skill

pm-brain-skill/
├── SKILL.md              # This file. Orchestration.
├── scaffold/             # Deterministic static structure. Copy as-is.
│   ├── .claude/          # Per-brain Claude Code config (hooks + settings)
│   │   ├── hooks/
│   │   │   └── validate_brain_file.py   # PostToolUse schema validator
│   │   ├── commands/     # Slash commands shipped with the brain
│   │   └── settings.json # Wires the hook to Write|Edit
│   ├── .gitignore
│   ├── CLAUDE.md
│   ├── INDEX.md
│   ├── README.md
│   ├── knowledge/        # strategy, product, users, market, org
│   ├── stakeholders/
│   ├── hypotheses/
│   ├── decisions/
│   ├── rules/
│   ├── source/           # Verbatim audit anchors
│   ├── ingestion/        # Synthesized records
│   ├── maintenance/
│   └── docs/
└── prompts/              # Adaptive reasoning. Loaded per phase.
    ├── mode-detection.md
    ├── migration.md
    ├── interview.md
    └── post-scaffold.md