From d2a339ba93962fbd93bf283e1d63b7dd43ec61a5 Mon Sep 17 00:00:00 2001 From: antnewman Date: Sat, 9 May 2026 10:39:30 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20README=20Loom-prep=20=E2=80=94=20reorde?= =?UTF-8?q?r,=20fix=20tool=20counts,=20add=20Evidence=20Engine?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five changes ahead of recording the README's headline Loom video: 1. **Tool count consistency.** The lede paragraph said "122 structured tools" while every other reference said 124. Fixed in README, CLAUDE.md ("currently **122**" bookkeeping line, monorepo intro, structure diagram), llms.txt ("122 structured MCP tools"), server.json description, and the README's MCP modules table total row. 2. **What it does, in 90 seconds** — new section between the live demo line and the personas table, with a placeholder for the Loom embed and three bullets describing what the video shows. 3. **Start here, rewritten as a two-step onboarding pair.** The old recommendation led with scan_for_red_flags, which requires a project loaded first. New version leads with generate_premortem_questions (works against zero data, returns sharp output instantly), with three sample questions reproduced inline so the value is visible before the reader commits to anything. scan_for_red_flags follows as the next call once data is loaded. 4. **Built on PDA Platform** — new section after the modules table, featuring Evidence Engine (Laura White's MPA Challenge 5 hackathon product, evidence-engine.netlify.app) as the first product built on the engine. Provides a concrete adoption proof point and an open invitation for others. 5. **Section heading correction.** "17 MCP Modules" was already stale — we have 18. Heading updated. No code or test changes. Branch 5 of 5 in the Loom-readiness fix series. --- CLAUDE.md | 6 +++--- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++----- llms.txt | 2 +- server.json | 2 +- 4 files changed, 47 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4dc7fc7..06267ed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,14 +1,14 @@ # Claude Code Instructions — PDA Platform ## Project Overview -The PDA Platform is a Python monorepo providing AI-powered project delivery assurance for UK government. It exposes 122 MCP tools across 18 modules via a unified server, deployable locally or via Render. +The PDA Platform is a Python monorepo providing AI-powered project delivery assurance for UK government. It exposes 124 MCP tools across 18 modules via a unified server, deployable locally or via Render. ## Repo Structure ``` packages/ pda-platform/ Meta-package (pip install pda-platform) pm-data-tools/ Core library: parsers, validators, AssuranceStore (SQLite) - pm-mcp-servers/ 18 MCP modules, 122 tools + pm-mcp-servers/ 18 MCP modules, 124 tools agent-task-planning/ AI reliability: confidence extraction, outlier mining docs/ Practitioner guides and technical references .github/workflows/ publish.yml — PyPI publish on version tag @@ -68,7 +68,7 @@ Use semantic versioning: ## MCP Tool Count — Keep in Sync -The tool count (currently **122**) appears in multiple places. When adding new tools, update ALL of these: +The tool count (currently **124**) appears in multiple places. When adding new tools, update ALL of these: | File | What to update | |---|---| diff --git a/README.md b/README.md index 7754689..af1706c 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ --- -PDA Platform gives Claude and other MCP-compatible AI assistants **122 structured tools** to perform rigorous, evidence-based project delivery assurance aligned to IPA Gate Reviews (Gates 0–5), HM Treasury Green Book appraisal, and GMPP reporting standards. It is the only open-source MCP platform specifically designed for Senior Responsible Owners, Project Managers, Independent Assurance Reviewers, and Portfolio Managers working in UK government major project delivery. +PDA Platform gives Claude and other MCP-compatible AI assistants **124 structured tools** to perform rigorous, evidence-based project delivery assurance aligned to IPA Gate Reviews (Gates 0–5), HM Treasury Green Book appraisal, and GMPP reporting standards. It is the only open-source MCP platform specifically designed for Senior Responsible Owners, Project Managers, Independent Assurance Reviewers, and Portfolio Managers working in UK government major project delivery. Think of it as a **semantic layer for project data**: it ingests schedules from Primavera, MSP, Jira, and 5 other formats; normalises them into a consistent delivery model; pre-loads IPA benchmark statistics from five years of Annual Reports; and exposes everything through a structured API that AI can reason about directly — without parsing raw XML or making things up. @@ -22,6 +22,19 @@ Connect Claude to the platform and ask it to conduct a full gate readiness asses --- +## What it does, in 90 seconds + + +*A 90-second walkthrough of the platform on a real assumption register lives here. (Loom link to be added.)* + +In the video you'll see the platform: + +- **Generate the questions a senior gate reviewer would ask** — from your project data, with no setup +- **Score and validate every assumption in your business case** against live external signals from ONS and the World Bank +- **Produce a board-ready exception report** grounded in evidence rather than narrative + +--- + ## Who is this for? | Role | What the platform does for you | @@ -67,9 +80,23 @@ See the full **[Connection Guide](docs/connection-guide.md)** for Claude.ai, Cla --- -## Start here: scan for red flags +## Start here: two ways in, no setup needed for the first -The fastest way to get value from the platform is a single tool call: +**Try this first** — works against zero project data, returns immediately: + +``` +generate_premortem_questions +``` + +Returns the questions an experienced IPA reviewer would actually ask at a gate review: + +> *"What is the programme team not telling senior stakeholders — and why?"* +> *"Which assumption, if wrong, would most severely undermine the current delivery confidence rating?"* +> *"Is the risk register a genuine picture of what could go wrong — or a curated list of manageable risks?"* + +Tailor the output to a specific gate stage (`gate_stage: 3`) or risk profile to focus the questions further. + +**Once you've loaded a project**, the next call is: ``` scan_for_red_flags — project_id: "PROJ-001" @@ -120,7 +147,17 @@ Once connected, Claude can answer questions like: --- -## 17 MCP Modules +## Built on PDA Platform + +Products built on the PDA Platform engine: + +- **[Evidence Engine](https://evidence-engine.netlify.app)** — a forecast-driven early-warning system for project assumption drift. Built by Laura White as the MPA Challenge 5 hackathon entry. Wraps PDA Platform with a forecasting layer, cascade propagation across the assumption dependency graph, and a confidence decomposition that turns assurance evidence into a live early-warning signal. Calls `generate_narrative` over MCP SSE; falls back gracefully if the engine is unreachable. + +If you've built something on PDA Platform, open an issue or PR — we'll add it here. + +--- + +## 18 MCP Modules | Module | Tools | What it does | |--------|------:|-------------| @@ -142,7 +179,7 @@ Once connected, Claude can answer questions like: | pm-lessons | 5 | AI extraction of lessons from gate reviews/PIRs, cross-project keyword search, systemic pattern analysis | | pm-reporting | 6 | IPA-format gate review summaries, SRO dashboards, board exception reports, portfolio summaries, PIR templates, UDS export | | pm-assumptions | 8 | Assumption drift detection, confidence scoring, live external signal integration (ONS, World Bank), AI executive reports, cascade analysis, UDS dashboard | -| **Total** | **122** | One unified endpoint · One connection | +| **Total** | **124** | One unified endpoint · One connection | --- diff --git a/llms.txt b/llms.txt index b860142..0a6adce 100644 --- a/llms.txt +++ b/llms.txt @@ -4,7 +4,7 @@ ## What it is -PDA Platform (Project Data Analytics) is a semantic layer for project delivery data. It ingests schedules from Primavera, MSP, Jira, and 5 other formats; normalises them into a consistent delivery model; pre-loads IPA benchmark statistics from five years of Annual Reports; and exposes everything through 122 structured MCP tools that AI can reason about directly. +PDA Platform (Project Data Analytics) is a semantic layer for project delivery data. It ingests schedules from Primavera, MSP, Jira, and 5 other formats; normalises them into a consistent delivery model; pre-loads IPA benchmark statistics from five years of Annual Reports; and exposes everything through 124 structured MCP tools that AI can reason about directly. The platform is aligned to UK government delivery standards: IPA Gate Reviews (Gates 0-5), HM Treasury Green Book, GMPP reporting, and Cabinet Office project controls. diff --git a/server.json b/server.json index 5327fa7..1bdd188 100644 --- a/server.json +++ b/server.json @@ -2,7 +2,7 @@ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json", "name": "io.github.antnewman/pda-platform", "title": "PDA Platform", - "description": "122 MCP tools for UK government IPA Gate Review assurance: risk, benefits, Monte Carlo simulation, assumption drift detection, narrative divergence, EV, gate readiness, and portfolio analysis.", + "description": "124 MCP tools for UK government IPA Gate Review assurance: risk, benefits, Monte Carlo simulation, assumption drift detection, narrative divergence, EV, gate readiness, and portfolio analysis.", "version": "1.0.0", "status": "active", "websiteUrl": "https://github.com/antnewman/pda-platform",