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.

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

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.

Related MCP server: AIConductor

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.

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.

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.

Cursor — MCP (one-click)

Or add manually to ~/.cursor/mcp.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:

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:

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.

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.

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.

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)

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 and ADR-0009.

Windows, Cloud Agents, this-checkout node paths, and first-npx timeouts: packages/pn-core-mcp/README.md. Clone-and-develop: 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.

Workflows

Call list_workflow_types for live step counts.

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

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

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.

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

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.

Documentation

Scripts

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

License

MIT — see LICENSE.