Meta-system update from dogfooding

Improvements to the agent system, frameworks, and documentation — all derived from dogfooding PM Brain in a real PM role over 5 weeks.

Highlights

Bootstrap optimization — The always-on bootstrap set is now 5 files (~14,600 tokens), down from 6 files (~17,800 tokens). version.json moved to sleeping memory. AGENTS.md trimmed to persona + pointers. thinking.mdc refactored into 7 focused always-on coaching lenses.

New coaching lenses — Outcome vs output, assumptions vs facts, pre-mortem instinct, uncomfortable thought, hypothesis stress-test, timing instinct, and org reality acknowledgment. These fire in every conversation regardless of mode.

Orchestration improvements — Company context routing guard (prevents stale docs from polluting decisions). Intent disambiguation (asks before loading when signals are ambiguous). Mid-conversation transition enforcement (reloads context at mode changes, not just at start). Claude Code bootstrap reference added.

VS Code + GitHub Copilot support — New .github/copilot-instructions.md provides automatic bootstrap loading in VS Code Copilot chat.

New frameworks

• 10-Things Workshop (2.3.8) — Framework + template for team alignment workshops, with PDF exports
• Documentation Standards (2.4.10) — Framework for decision records, architecture docs, and documentation quality evaluation

Other changes

• docs/platform-setup.md — New consolidated platform setup guide (replaces old 01-Company-Context/SETUP.md and SETUP-QUICK-REFERENCE.md)
• docs/architecture.md, docs/setup.md, docs/guidelines.md updated
• Agent behavior eval guide and scenarios updated
• MEMORY.md wake tables refreshed
• CLAUDE.md enhanced for Claude Code workflow
• .gitignore templates updated for relocated setup files

Breaking changes

• Bootstrap set is now 5 files (version.json no longer bootstrap — woken on demand via MEMORY.md)
• thinking.mdc stripped to coaching lenses only — other content moved to canonical homes
• Setup files moved from 01-Company-Context/ to docs/platform-setup.md
• .github/copilot-instructions.md added as VS Code + Copilot bootstrap layer

Full Changelog: 3.4.0...3.5.0

Faster Onboarding, Script-Free Judgment Test, Safer Context

This release makes PM Brain easier to adopt for new teammates, removes a scripting dependency from the Product Judgment Test, and gives the agent a single place to reason about stale company context.

🚀 Onboarding Cluster

• New 01-Company-Context/1.3-Onboarding/ folder with a Top 10 guide, metrics glossary, and acronyms quick-reference so a new PM can get oriented in under an hour.
• 01-Company-Context/README.md and TODO.md now point directly to this onboarding cluster instead of a vague “Top 10” idea.

📊 Product Judgment Test Without Scripts

• Added brier-calculation.md and a product-judgment-test-calculator.csv sheet so you can compute Overall Brier with a calculator or spreadsheet, no Python required.
• Updated README/dashboard to reference the calculator and removed the old compute_brier.py helper script.

🩺 Context Health Table

• New 01-Company-Context/CONTEXT-HEALTH.md tracks which company/initiative docs are “living inputs” and how quickly they rot.
• MEMORY.md and ORCHESTRATION.md now let the agent use this table to offer optional “is this still roughly true?” nudges when those docs feed into real decisions (roadmaps, OKRs, PRDs, politics).

If you’re upgrading from 3.3.0, this is a quality-of-life release: no behavior reset, just smoother onboarding, a friendlier Product Judgment Test, and safer reuse of older company context.

Sharper Positioning, Cleaner Language, Better Routing

This release tightens PM Brain’s front door and internal consistency: clearer problem framing in the opening README, cleaner naming, and better orchestration reminders so the agent stays grounded in repo guidelines while routing work.
The core value: PM Brain gets easier to understand at first glance and more reliable in day-to-day use. Less ambiguity, less terminology drift, and clearer signals for both humans and agents.

🎯 Simpler Opening, Clearer PM Pain

• Refined README opening to better reflect real PM pain (scattered context, strategy/execution gap, thinking quality).
• Shortened positioning so users understand what PM Brain is for in the first screen, not halfway down the page.
• Kept the “thinking partner” framing, but with tighter language and faster onboarding clarity.

🧭 Better Agent Guidance Hygiene

• Added lightweight guideline wiring so docs/guidelines.md is easier for the agent to pull in when maintenance or repo-usage questions appear.
• Updated orchestration reminder behavior to reduce drift and keep responses aligned with repo conventions.
• Improved consistency between setup, orchestration, and memory references.

🏛️ Terminology & Structure Consistency

• Standardized terminology to full forms across docs (organization / communication).
• Renamed and normalized references around 1.2-Organization-Survival and related links.
• Reduced naming mismatches across context/framework/rules docs.

🧑‍🏫 Identity Alignment: PM Brain Coach

• Aligned agent naming to PM Brain Coach across core docs and templates.
• Reduced persona/reference fragmentation between AGENTS, setup, and rules.
• If you’re upgrading from 3.0.0: this is a clarity and consistency release rather than a behavior reset — same core model, cleaner language and better guidance wiring.

Platform-Agnostic Brain & Politics Layer

This release catches the repo up to where it’s been heading since 1.1.0: one orchestration core that works across Cursor, Claude Code, and other agents, clear voice and evaluation, and organization politics as a first-class layer alongside strategy and stakeholder management.

The core value: PM Brain is no longer tied to a single AI host. Context, rules, and skills are mapped through one manifest (MEMORY.md); agents get the same persona and workflows whether you’re in Cursor or Claude Code. And when the conversation turns to power, alliances, or stakeholder games, the agent now has a dedicated politics layer and skill to work with.

---

🌐 Platform-Agnostic Core (v3.0)

• Single path-mapping layer: AGENTS.md and ORCHESTRATION.md no longer reference .cursor/ directly; MEMORY.md is the single place for platform-specific paths (rules, skills, evals). Same brain, different hosts.
• Context Health: Heuristic-based checkpointing, re-anchoring at state transitions, and error recovery so long sessions don’t drift.
• CLAUDE.md for Claude Code users; checkpoints/ folder for session state persistence.
• Setup: Multi-platform guide (Cursor, Claude Code, Claude.ai, ChatGPT, GitHub Copilot, universal).

📁 Structure & Docs (v3.1)

• Human-facing docs moved into docs/ (setup, architecture, guidelines, credits, agent-manifest). Root stays for agent entry points and version.
• README as single entry point for humans, agents, and forkers.
• Design Principles and Naming conventions in docs/architecture.md.
• Agent checks the filesystem before asking you whether context exists; MEMORY wake trigger for repo structure and architecture.

🎭 Voice & Communication (v2.2)

• voice.mdc (always-applied): direct, experience-backed, prose-first style. No corporate speak; lead with “I’ve generally seen…” and honest uncertainty.
• DevX === UX as a recurring angle for internal tools and platforms.

🧩 Skills & Orchestration (v2.0–2.1)

• Orchestration lives in ORCHESTRATION.md: explicit state machine (product_sense, execution_mode, meta_reflection, conversation) and when to load what.
• Sleeping memory (MEMORY.md): company context, initiatives, research, rules, and skills wake when the conversation touches them.
• Specialized skills: discovery-research, strategy-planning, stakeholder-management; eval test generator and optional post-conversation eval logging.

🏛️ Politics & Organization Survival (v3.2)

• politics-coach skill: Navigate org politics, simulate stakeholder feedback, run politics checks on plans and communication.
• Stakeholder avatars framework and Organization-Survival company-context layer: power map, political landscape, stakeholder games, coalitions and timing, red flags and history.
• ORCHESTRATION and MEMORY route politics-related queries through avatars and Organization-Survival docs; initiative stakeholders are wired into this layer.
• Normalized language for organization and communication across core docs.

---

If you’re upgrading from 1.1.0: Treat MEMORY.md as the source of truth for where things live on your platform. Re-read ORCHESTRATION.md for state transitions and context health. No breaking change to how you use the frameworks—only where the agent finds rules, skills, and evals.

Product Sense & Intelligent Agent System

🧠 Product Sense is Now Built-In

This release transforms PM Brain from a framework library into an intelligent PM assistant that actively guides users through product thinking and develops product sense through structured coaching.

The core value: Product sense isn't just documented—it's orchestrated. The agent enforces deep thinking before structure, asks Socratic questions, and guides users to better product judgment through every interaction.

---

🎯 Agent Orchestration (The Brain)

• Three explicit modes that guide the thinking process:
  • product_sense_mode: Braindump & Socratic questioning (no templates until thinking is deep)
  • execution_mode: Framework application (after sufficient braindump)
  • meta_mode: Reflection & logging (capture learnings and decisions)
• Eval checkpoints at key transition points ensure the "braindump before structure" golden rule is followed
• Version checking enables agents to detect repository changes and adapt
• Context management optimizes file loading for efficient guidance

📊 Two-Level Evaluation System

Ensures both artifact quality and agent behavior improve over time:

• Level 1: Artifact quality checks (Quick Quality Checks + full evaluation per framework)
• Level 2: Agent behavior evaluation (guidance-based checklists, scenario matching)
• Eval instrumentation for pattern detection over time
• Results logging format for tracking agent performance

🎯 Framework Enhancements

• "For Agents" sections added to 14 frameworks with guidance on:
  • When to suggest each framework
  • Common mistakes to avoid
  • When not to use them
  • Cross-references to related frameworks

v1.0.0 - The External Brain Release

First major release! PM-Brain now functions as a complete external brain for product managers, bridging strategic thinking with day-to-day execution.

Product Sense Feature
The addition to v1.0 - deep thinking capabilities that connect dots across your entire product workflow:

• Analyzes patterns and relationships across tasks, decisions, and context
• Surfaces insights that bridge strategic vision with tactical execution
• Acts as a true external brain, maintaining coherent understanding across all your PM work
• Links everything together intelligently - from daily standup notes to quarterly planning

Integrated Deep Thinking

• Seamless context awareness across all PM artifacts
• Smart connections between related items, decisions, and learnings
• Contextual recommendations based on your entire product knowledge base