<p align="center">
  <img src="plugins/pnCore/assets/pn-logo.svg" width="176" alt="pnCore" />
</p>

# pnCore — v0.19.9

pnCore is an MCP engine with harness adapters for Cursor, Claude Code, Codex, and Pi. It runs software delivery as a sequence of named, gated steps instead of one long chat.

<p align="center">
  <img src="docs/readme/01_control_rail.svg" width="850" alt="workflow_step is a named rail: discovery, plan, build, review. A skeptic gate latches plan to build. Same engine on Cursor, Claude Code, Codex, and Pi.">
</p>

It runs named workflows through a deterministic `workflow_step` engine — discovery, plan, build, review on `full_dev`; design, audits, assets, and deliver as other types — backed by skills, agents, rules, and `pn-core://` resources, not a folder of prompts.

**Catalog:** 171 skills, 9 public agents + 6 internal orchestration agents, 31 visible slash palette files (30 under **`pn`** submenu + **`/pn`** stub) + 18 palette-hidden surgical commands (49 command files total), 29 MCP tools, 16 workflow types, plus `pn-core://` resources and prompts.

---

## Why this exists

<p align="center">
  <img src="docs/readme/02_who_owns_the_loop.svg" width="850" alt="Left: a single chat plans, codes, and checks its own work with no checkpoint in between. Right: the engine runs one gated step at a time, with skeptic, human, or workflow_verify deciding pass or fail. Same models either way — the MCP keeps the state between calls.">
</p>

A single chat can plan a feature, write the code, and tell you it's done — but there's no checkpoint in between. If it goes sideways on step three, you're rereading the whole transcript to find out where. Asking it to redo one part usually means starting the conversation over, and whatever context got it that far is gone.

pnCore moves that step list out of the chat. `workflow_step(type, index, state)` runs one step at a time — discovery, plan, build, review — and hands back the next instruction. A skeptic pass, a human gate, or `workflow_verify` decides whether a step actually passed, not the model's own say-so. If you get disconnected, `workflow_state_save` and `workflow_state_load` pick the run back up where it left off.

---

## What it is

**Deterministic.** `workflow_step(type, index, state)` decides the next instruction. Steps aren't skipped by assumption — skipping one is a gate decision, logged in state.

**Gated.** Skeptic, human, and `workflow_verify` gates are built into the engine. Intent is `full auto`, `design focused`, or `involved`. Involved gates discovery, prior-art, plan, specialist list, and review — you confirm to advance. Design focused is the `design` workflow, not a third gate flavor of `full_dev`.

**Multi-harness.** One canonical tree in `packages/pn-core-mcp/content/`; one engine; four adapters. `harness_detect` finds the active surface and `harness_scaffold` / `plugin-install --harness` write only the folders that surface reads — `.cursor/` (Cursor), `.claude/` + `.mcp.json` (Claude Code), `.agents/skills` + `AGENTS.md` block (Codex), `.agents/skills` + `.pi/prompts` (Pi). Pi registers the same tools natively. Matrix: `pn-core://reference/harness-matrix.md`, [ADR-0016](docs/adr/0016-harness-adapters.md).

**Resumable.** Every run has a `run_id`. Handoff lines and usage land in JSONL. After a disconnect, load state and continue the same step list.

<p align="center">
  <img src="docs/readme/03_four_harnesses.svg" width="850" alt="Canonical content under packages/pn-core-mcp/content/ feeds one engine. harness_scaffold writes only the folders for Cursor, Claude Code, Codex, or Pi. Pi can run the same tools natively.">
</p>

---

## Install

**Prerequisite:** Node.js 22+.

Call `health` first — it should return version, `calendarDateUtc`, and capabilities. If it doesn't, nothing downstream (skills, agents, `workflow_step`) will load either.

<a id="mcp-any-mcp-client"></a>

### Cursor — MCP (one-click)

[![Install MCP](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pn-core&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi0tcGFja2FnZT1naXQraHR0cHM6Ly9naXRodWIuY29tL3Blcm5pZW1hbm4vcG5Db3JlLmdpdCNtYWluIiwiLS0iLCJwbi1jb3JlIl0sImVudiI6eyJHSVRfVEVSTUlOQUxfUFJPTVBUIjoiMCIsIkdJVF9BU0tQQVNTIjoiZWNobyJ9fQ==)

Or add manually to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pn-core": {
      "command": "npx",
      "args": ["-y", "--package=git+https://github.com/perniemann/pnCore.git#main", "--", "pn-core"],
      "env": { "GIT_TERMINAL_PROMPT": "0", "GIT_ASKPASS": "echo" }
    }
  }
}
```

`GIT_TERMINAL_PROMPT=0` and `GIT_ASKPASS=echo` fail fast when git cannot authenticate (missing credentials, rate limit, or a bad URL). Without them, a credential prompt on piped stdin leaves Cursor in a forever loading state.

### Project files per harness — `plugin-install --harness`

From your **target project** directory:

```bash
npx github:perniemann/pnCore plugin-install                        # auto-detect (PNCORE_HARNESS > env > folders; falls back to cursor)
npx github:perniemann/pnCore plugin-install --harness claude_code  # or cursor | codex | pi | codex,pi | all
npx github:perniemann/pnCore plugin-install --harness codex --with-mcp-config --inline-rules
```

Only the selected harness's folders are created:

| Harness | What lands | Engine config (`--with-mcp-config`) |
|---------|------------|-------------------------------------|
| `cursor` | `.cursor/{commands,rules,skills,agents,hooks,scripts}`, `config/`, `.cursor-plugin/plugin.json` | `.cursor/mcp.json` |
| `claude_code` | `.claude/{skills,agents,commands}` + `.claude/rules/*.md` (`.mdc` converted; `globs` → `paths:`) | `.mcp.json` (repo root) |
| `codex` | `.agents/skills/<id>` (`$pn-<name>`), pnCore block in `AGENTS.md` | `.codex/config.toml` `[mcp_servers.pn-core]` |
| `pi` | `.agents/skills/<id>`, `.pi/prompts/pn-*.md`, pnCore block in `AGENTS.md` | `.pi/settings.json` `packages` |

Onboarding inside a session (`/pn-setup`, `/pn-new`, `project_kickoff`) uses the same table through `harness_detect` → `harness_scaffold`. Full matrix and rule-conversion notes: [harness-matrix.md](packages/pn-core-mcp/content/reference/harness-matrix.md).

> **MCP or plugin files?** MCP is the engine. The per-harness files add the surface (slash palette / prompts, file-glob rules, agents, stop hook on Cursor). The intended setup is both. Details: [Plugin vs MCP](packages/pn-core-mcp/README.md#plugin-vs-mcp).

### Claude Code

Add the same MCP JSON to `.mcp.json` at the repo root (or `claude mcp add --scope user`), then `plugin-install --harness claude_code` for `.claude/` skills, agents, rules, and `/pn-*` commands. See [Anthropic's MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).

### Codex

Add `[mcp_servers.pn-core]` to `.codex/config.toml` or `~/.codex/config.toml` (`plugin-install --harness codex --with-mcp-config` writes it), then restart Codex. Skills are `$pn-<name>` from `.agents/skills`; slash commands are MCP prompts (`get_command("pn-build")`); the `AGENTS.md` pnCore block carries the bootstrap.

### pi.dev (Pi coding agent)

```bash
pi install git:github.com/perniemann/pnCore@main
```

Pi surfaces a single **`/pn`** entry. Direct invoke: `/pn pn-build`. Native tools ship with `pi install git:…/pnCore` or `pi install .` from this repo root after `npm run build:mcp`; `plugin-install --harness pi` adds project-level `.pi/prompts` and `.agents/skills`. See [ADR-0008](docs/adr/0008-command-palette-pn-submenu.md) and [ADR-0009](docs/adr/0009-pi-native-tools.md).

Windows, Cloud Agents, this-checkout `node` paths, and first-npx timeouts: [packages/pn-core-mcp/README.md](packages/pn-core-mcp/README.md#installation). Clone-and-develop: [CONTRIBUTING.md](CONTRIBUTING.md).

---

## Quick start

1. Install MCP and/or plugin (above).
2. Call `health` — version, UTC date, capabilities.
3. **New repo or greenfield:** `/pn-new` or `workflow_step("project_kickoff", 0, {})` — discovery, refs, PRD, and design docs under `docs/refs/`.
4. **Build or extend:** `/pn-build` or `workflow_step("full_dev", 0, {})` — skips kickoff when the project already has context.
5. Optional after the run: `/pn-deliver` for a handoff pack, or `/pn-frontend-audit`.

Copy-paste first message:

```
pn-new ▲

Build [your-project-name] — [one-line description].
References: [path or "in .ref/"] (pitch, requirements, design assets).
Analyze both: prior art and design.
Intent: Involved — full gates at discovery, prior-art, plan, specialist list, and review.
Delivery tier: full. Design ambition: distinctive.
```

pn-new questionnaire: Step 0 of 2 — Yes, Both. Step 1 of 2 — (3) Involved.

More prompts: [docs/how-to-use-guide.md](docs/how-to-use-guide.md).

---

## Workflows

<p align="center">
  <img src="docs/readme/04_full_dev_lanes.svg" width="850" alt="You start /pn-build. The MCP runs discovery and plan. On involved intent you pass the skeptic gate. Specialists build. The MCP reviews. A step only counts once its gate passes; /pn-deliver waits as the next named step.">
</p>

Call `list_workflow_types` for live step counts.

| Use it for | Workflow | Cursor | MCP entry |
|-------------|----------|--------|-----------|
| New project: refs, discovery, PRD, design | `project_kickoff` | `/pn-new` → Involved | `workflow_step("project_kickoff", 0, {})` |
| Build a feature or product end-to-end | `full_dev` | `/pn-build` | `workflow_step("full_dev", 0, {})` |
| Design-first UI | `design` | `/pn-design` | `workflow_step("design", 0, {})` |
| Scored frontend diagnosis + fix roadmap | `frontend_audit` | `/pn-frontend-audit` | `workflow_step("frontend_audit", 0, {})` |
| API, security, data, errors, performance | `backend_audit` | `/pn-backend-audit` | `workflow_step("backend_audit", 0, {})` |
| SVG, raster, or placeholders | `svg_create` / `image_create` | `/pn-assets` | `workflow_step("svg_create" \| "image_create", 0, {})` |
| Evidence-led strategy brief | `business_strategy` | `/pn-strategy` | `workflow_step("business_strategy", 0, {})` |
| Competing implementations (2–3 worktrees) | `implementation_tournament` | `/pn-best-of-n` (`bestOfN.enabled: true`) | `workflow_step("implementation_tournament", 0, {})` |
| Multi-slice hierarchical build | `feature_program` | `/pn-program` (preview; `featureProgram: true`) | `workflow_step("feature_program", 0, {})` |

Also on the engine: `visual_tweak`, `prompt_optimize`, `game_feature`, `engine_feature` (Unreal / Godot), `fsi_analyst_draft`, `media_director`. Full table and aliases: `list_workflow_types`.

### Example: `full_dev`

| # | Who | Action |
|---|-----|--------|
| 1 | You | `/pn-build` or `workflow_step("full_dev", 0, {})`. Pass `intent: "involved"` when you want full gates. |
| 2 | MCP | Discovery, then prior-art for your stack. |
| 3 | MCP | Plan under `docs/plans/`. |
| 4 | You | **Involved:** skeptic latches plan to build (`workflow_confirm`); not a peer step. |
| 5 | MCP | Specialists build; UI assets when in scope. |
| 6 | MCP | Review + optimize against the plan. |

Tool steps are 0-based. Resume after disconnect: `workflow_state_save` then `workflow_state_load`. Schema: `pn-core://reference/workflow-state-schema.md`.

After the run, `/pn-deliver` is the next named workflow if you need a handoff pack (or `/pn-frontend-audit` for a scored quality gate).

**Design-first:** `design focused` intent (or `/pn-design`) runs `workflow_step("design", 0)` — not `full_dev`. Load `.pncore-design.md` via `/pn-setup`.

**Game / 3D:** `workflow_step("game_feature", 0)` for feature loops. For full builds, use `full_dev` and name the stack in discovery.

---

## What changes

| Without pnCore | With pnCore |
|-----------------|-------------|
| One long transcript | Named steps, each with a `run_id` |
| "Done" means the model stopped talking | Skeptic, `workflow_verify`, or a delivery pack decide |
| A retry starts a new chat | `workflow_state_load` picks up where it stopped |
| Skills live in a folder you have to remember to load | The engine loads gates and skills automatically |
| Works in Cursor chat, nowhere else | Same engine on Cursor, Claude Code, Codex, Pi; files land in each harness's own folders |

**Three tier concepts** (do not conflate them): **delivery tier** (MVP/Full), **context tier** (1–4 reading depth), **model tier** (`fast` / `standard` / `premium` / `premium_thinking` / `long_horizon`). Loop orchestration: `suggest_model_tier` with `role: orchestrator` → `long_horizon`. See `pn-core://reference/delivery-tier-criteria.md` and [MCP tools](packages/pn-core-mcp/README.md#tools).

Load before a build session: `pn-core://reference/best-practices.md`, `pn-core://reference/loop-orchestration-guide.md`, `pn-core://reference/aesthetics-baseline.md`, and `health` for the current UTC date.

---

## Honest edges

| Situation | What happens | What to do |
|-----------|--------------|------------|
| A one-line typo fix | The workflow overhead isn't worth it | Ask directly, skip `workflow_step` |
| Plugin without MCP | Slash templates only — no `workflow_step` engine | Install MCP for Cursor, or both |
| First npx on a git+https package URL | Cursor MCP can time out on a cold clone | Pre-warm once, then reload. Matrix: [MCP README](packages/pn-core-mcp/README.md#troubleshooting-mcp-wont-connect-in-cursor) |
| `feature_program` / `bestOfN` | Preview flags; off by default | Set `featureProgram: true` or `bestOfN.enabled: true` |
| Vue, Svelte, Angular, Unity | Limited support | Prefer React, Astro, Next, vanilla web, Node, Three.js / Babylon, n8n, web3 |

**Best fit:** teams building with Cursor, Claude Code, Codex, or Pi on React, Astro, Next.js, vanilla web, Node backends, Three.js / Babylon / gamedev, n8n, and web3. Inventory: [docs/plugin-reference.md](docs/plugin-reference.md).

---

## Documentation

| Guide | What's in it |
|-------|-------------|
| [docs/how-to-use-guide.md](docs/how-to-use-guide.md) | Copy-paste prompts, example flows, MCP-only bootstrap |
| [docs/mcp-usage-guide.md](docs/mcp-usage-guide.md) | MCP tools, resources, workflow patterns, state/handoff |
| [docs/plugin-reference.md](docs/plugin-reference.md) | Rules, skills, agents, commands, hooks |
| [packages/pn-core-mcp/README.md](packages/pn-core-mcp/README.md) | MCP config, tools, env vars, error codes, resources |
| [docs/companion-mcp-catalog.md](docs/companion-mcp-catalog.md) | Companion MCPs (Octocode, Stripe, n8n, …) |
| [docs/pitch-to-app-example.md](docs/pitch-to-app-example.md) | End-to-end pitch-to-app walkthrough |
| [packages/pn-core-mcp/content/docs/starting-new-project.md](packages/pn-core-mcp/content/docs/starting-new-project.md) | Kickoff and `docs/refs/` setup |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Workspace map, scripts, PR workflow, ADR policy |
| [plugins/pnCore/CHANGELOG.md](plugins/pnCore/CHANGELOG.md) | Release history |

---

## Scripts

Contributor scripts, local MCP config, and how to develop pnCore live in [CONTRIBUTING.md](CONTRIBUTING.md#scripts). Repo layout: [docs/folder-structure.md](docs/folder-structure.md).

---

## License

MIT — see [LICENSE](LICENSE).